cthulhu/docs/testing/phonetic-review.md

Flat review spelling and phonetic hints

Build a separate binary, preserving the running reader:

go build -o /tmp/cthulhu-phonetic-review ./cmd/cthulhu
python3 tests/native_test_session.py go test -race ./internal/input ./internal/config ./internal/preferences ./internal/app ./internal/review ./internal/presentation -count=1
CTHULHU_BINARY=/tmp/cthulhu-phonetic-review CTHULHU_PREFS_READING_ONLY=1 /usr/bin/python3 tests/native_preferences.py
CTHULHU_BINARY=/tmp/cthulhu-phonetic-review /usr/bin/python3 tests/native_x11.py
python3 tests/check_speech.py

The native fixtures use private Xvfb, D-Bus and AT-SPI sessions. Run them sequentially. They verify command consumption and releases, repeat routing, accessible checkbox state, Space/arrows/Tab/Shift+Tab, Apply and reload. Go tests verify line spelling including spaces and repeated letters, OCR cursor/Braille stability, the hint delay and cancellation, silent modes, defaults, persistence and application overrides. These checks do not establish audible speech or physical keyboard/Braille behavior.

After reviewing the diff and installing/restarting through the normal process:

1. In a text editor, use a line such as A book!. Check single/double Numpad 2, single/double/triple Numpad 5 and single/double/triple Numpad 8. Presses within each sequence must be no more than 500 ms apart. Confirm immediate ordinary speech on the first press, repeated letters, capitals, spaces and punctuation. Pause longer than 500 ms and confirm the next press starts ordinary reading.
2. Check the same actions in a terminal and a browser. If using laptop layout, use Cthulhu+Comma, Cthulhu+K and Cthulhu+I. Confirm other review movement and window start/end still work, with no leaked or stuck keys. If using OCR or Wine flat review, confirm the line sequence and retained Braille cursor there.
3. In Speech → Reading settings, confirm Phonetic character hints starts unchecked. Toggle with Space, Apply, and use plain Left/Right through text: a should be followed about 300 ms later by alpha. Try capitals and repeated letters. Move or type before the delay expires: the previous hint must not follow the new character. Hold an arrow and confirm navigation stays responsive. With capital beep, raised pitch and “cap” enabled, arrow to T: those cues should occur only with the character, followed by plain tango in the normal voice. Double Numpad 2 and triple Numpad 5/8 should retain capital cues in their explicitly requested phonetic output.
4. Confirm Ctrl+Left/Right, Shift+Left/Right, Home/End, typing, punctuation and spaces retain their usual behavior. Repeat in browser browse and editable text modes and a supported Wine editor when available. Turn speech off and on; hints suppressed while off must never replay. Confirm capital pitch/beep/ “cap” choices and ordinary speech queues still behave as configured.
5. Uncheck and Apply: arrows should speak characters alone again. Check saved state after restart and application-specific settings if used. Cancel a draft toggle and confirm it does not change the saved choice. With Braille enabled, confirm hints do not move the review or Braille cursor or replace its text.

Human review and these listening checks remain required before submission.