Add global command bypass with Cthulhu+Z

docs/testing/command-bypass.md

@@ -0,0 +1,65 @@
+# Command bypass
+
+Cthulhu+Z temporarily passes reader command keys to the current application on
+Xorg. It retains the bypass shortcut and keeps speech and Braille running.
+Switching applications, leaving the foreground client, or locking restores
+commands. Same-process window changes and browser content changes preserve
+bypass. Accessible application identity is the fallback when native process
+identity is unavailable. Unknown foreground samples do not restore commands.
+
+The shared focus gate owns bypass state; command dispatch changes it and the
+accessibility event loop observes foreground/application departure. The X11
+command owner applies requested routing and grabs after held keys release.
+Unbound modifier chords use existing replay, with Caps Lock's native action
+included while bypass is active. OCR review ends on entry. Secure input and
+XTerm handoff retain their existing precedence. Reader shutdown discards state.
+Wayland reports bypass unavailable; its current backend has no replay path.
+
+## Automated checks
+
+Run affected Go packages and build the native listener test executable:
+
+```sh
+go test ./internal/input ./internal/app ./internal/platform/xorg -count=1
+go test -c -o /tmp/cthulhu-bypass-xorg.test ./internal/platform/xorg
+CTHULHU_XRECORD_TEST=/tmp/cthulhu-bypass-xorg.test CTHULHU_NATIVE_LISTENER_ONLY=1 CTHULHU_NATIVE_X11_TESTS='^TestNativeCommandBypass$' python3 tests/native_x11.py
+```
+
+The native harness owns a private Xvfb display and D-Bus session. It checks both
+layouts with Insert, KP_Insert, and Caps Lock; complete press/release delivery
+to an xev client; browse, arrow and keypad pass-through; balanced toggle releases;
+Caps Lock's actual lock state; and restoration of browse and global commands.
+Go tests check stale-command suppression, continued speech/Braille output,
+application departure without accessibility events, unknown foreground samples,
+same-application windows, and recovery when bindings are changed during bypass.
+
+These checks do not establish installed-binary behavior, audible speech,
+physical keyboard input, or physical Braille output.
+
+## Live acceptance
+
+1. Quit the running reader with Cthulhu+Q. Press Ctrl+Escape to enter i3 personal
+   mode, then press Shift+G to rebuild and start the reader. Ctrl+Escape and
+   Shift+G are separate key presses.
+2. In a graphical terminal other than XTerm, press Cthulhu+Z. Expect
+   "Cthulhu command keys off." in speech and a Braille status flash. Type and
+   use arrows: application input and configured echo should continue. Press
+   Cthulhu+T: it should reach the terminal and must not read the time.
+3. Press Cthulhu+Z again. Expect "Cthulhu command keys on." Press Cthulhu+T:
+   expect the time, with focus remaining in the terminal.
+4. In a browser in browse mode, enable bypass. Use a page with a known letter
+   shortcut, then press that key. Expect the page's action rather than structural
+   navigation. Arrows should follow the browser's native behavior. Tab should
+   still move focus with ordinary speech and Braille presentation.
+5. Disable bypass and press H. Expect the next heading. Enable bypass again,
+   switch to a different application, then press Cthulhu+T. Expect the time
+   without first toggling bypass off. Return to the browser and verify that H
+   again navigates by heading when browse mode is active.
+6. With bypass enabled, switch between windows of the same application. Expect
+   bypass to remain active. If Caps Lock is a configured modifier, press and
+   release it alone during bypass: expect normal lock behavior. Turn it off
+   again before restoring reader commands.
+
+Report the exact speech, Braille text, focused control, and application key
+behavior for any mismatch. Inspect ~/devel/cthulhu-go.log after an unexpected
+result, preserving the fresh log before another restart.