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. 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.

Focused checks:

go test ./internal/app -run 'Test(XTerm|DelegatedInput)' -count=1
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. Record the exact keys, focused application, speech and Braille for failures.