66 lines
3.7 KiB
Markdown
66 lines
3.7 KiB
Markdown
# 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.
|