cthulhu/docs/testing/xterm-handoff.md

XTerm handoff verification

While input is delegated to a terminal reader in XTerm, Cthulhu suppresses ordinary key echo, input-driven speech interruption and lock-state feedback. An i3 desktop announcement opens a narrow exception: the configured interruption keys can stop Cthulhu's active and queued speech during handoff, without key echo or cancelling the terminal reader's own Speech Dispatcher client. Ordinary terminal input still causes no Cthulhu cancellation when no such announcement has been admitted. It releases its command grabs. On return, Caps Lock tracking adopts the current XKB lock state before treating Caps Lock as the reader modifier again.

On i3, focusing an empty workspace resumes Cthulhu and its shortcuts even though no accessible application gains focus. This requires i3's verified window-manager identity, no EWMH active client, and keyboard focus on i3's support window. Returning to a workspace with focused XTerm suspends Cthulhu again. Moving or closing the last window also restores shortcuts when i3 enters that no-client state. This behavior is independent of workspace announcement preferences. Unknown focus on other desktops keeps the existing handoff policy.

Focused checks:

go test ./internal/app -run 'Test(XTerm|DelegatedInput)' -count=1
python3 tests/native_i3.py
python3 tests/native_x11.py

The native harness uses a private X display and checks grab suspension, restoration and lock state with synthetic input. Audible output from another reader and physical keyboard handling require live verification.

1. Quit Cthulhu with Cthulhu+Q. Press Ctrl+Escape, then Shift+G to rebuild and launch it. These are separate key presses.
2. Focus XTerm with your console reader active. Press its reader modifier and navigation keys. Expect the console reader to receive them, without Cthulhu modifier echo or Cthulhu interrupting its speech.
3. Change Caps Lock in XTerm, then switch to an ordinary desktop application. Expect Cthulhu to resume focused-control speech and Braille and accept its configured modifier commands with the current lock state.
4. Switch back and repeat with keypad commands where configured. Confirm focus stays on the intended application and no key remains grabbed after handoff. Restore the original lock state.
5. While an i3 workspace or mode announcement is speaking in XTerm, press Control, or Shift when using the “all keys” interruption setting. Expect Cthulhu's current announcement and queued continuation to stop promptly. Fenrir must continue receiving terminal keys, with no Cthulhu key echo.
6. With XTerm in workspace 7, switch to empty workspace 8. Expect the normal workspace announcement if enabled. Press Cthulhu+Space; expect Preferences to open and its controls to speak and appear on Braille. Close Preferences, return to workspace 7, and check that Fenrir receives its modifier and navigation keys again, without Cthulhu key echo. Repeat with a floating XTerm, and with i3 workspace announcements disabled. The shortcuts must resume on the empty workspace in each case. Also visit an ordinary editor or file manager and confirm normal Cthulhu focus speech and Braille.
7. Record the exact keys, focused application, speech and Braille for failures.