Some echo tests added.

docs/testing/key-echo.md

@@ -0,0 +1,78 @@
+# Key echo verification
+
+Debug records named `delivering accessible presentation` already include
+`utterance` and `custom_echo`. `custom_echo: true` identifies a delivery attempt
+using the custom echo path; `false` uses the ordinary voice path, including
+existing uppercase, system and hyperlink voice choices. These records describe
+what the reader sends to its speech backend, not what was audibly heard.
+Normal, non-debug logs omit utterances. Password-role delivery text is redacted.
+
+Run the repeatable speech check:
+
+```sh
+python3 tests/check_speech.py
+```
+
+It requires the echo regression tests to pass, alongside the existing queue,
+title and interruption checks. It uses private services and silent test speech.
+The focused equivalent is:
+
+```sh
+go test -race ./internal/presentation ./internal/app ./internal/input -run 'Echo|Capital|EditorParagraph' -count=1
+```
+
+The tests cover:
+
+- All eight combinations of character, word and sentence echo, with echo
+  enabled and disabled and printable key categories independently disabled.
+- All sixteen combinations of the four custom-voice selections, with the
+  custom-voice master setting on and off. The matrix checks the resulting
+  utterance, character/text backend call and `custom_echo` delivery record.
+- Word punctuation, repeated delimiters, Unicode, sentence precedence over
+  word echo, Enter completion and multi-character paste presentation.
+- Real SSIP client routing for key, character, word and sentence output,
+  using private recorded speech endpoints, both directly and through the
+  configured speaker. Existing checks cover uppercase choices, preferences
+  Apply, persistence, edit-fields-only, Wine character feedback, key-name
+  completion ordering and fresh-input interruption.
+
+Verify Enter against a real GTK TextView and native AT-SPI capture:
+
+```sh
+python3 tests/native_test_session.py env CTHULHU_NATIVE_TYPING_ECHO=1 go test ./internal/app -run '^TestNativeTypingEchoLineSplit$' -count=1 -v -timeout=30s
+```
+
+This private Xvfb/D-Bus check presses Enter in the middle and at the beginning
+of existing text, for word and sentence echo. Only text before Enter may be
+completed. A known empty position before the caret must stay empty; the rest
+of the line must not be substituted into the completion context. The test
+captures native events and checks presentation without starting a reader or
+using an audio device. GTK3 Python bindings, Xvfb and xdotool are required.
+
+Wine's insertion protocol currently supplies individual character labels,
+without the text context needed to complete words or sentences. The Wine
+tests cover the supported character/key routing; they do not establish Wine
+word or sentence echo. Native browser and application behavior also needs
+acceptance in the target application.
+
+After reviewing the diff and rebuilding, listen with the updated reader:
+
+1. Enable character echo with a distinctive custom character voice. Type
+   lowercase, capitals, digits, punctuation and spaces. Disable that custom
+   selection, then the custom-voice master setting, and check normal speech.
+2. Enable word echo and type `Hello world, ` slowly. Test with character echo
+   both on and off. Check the Words custom-voice selection independently.
+3. Enable sentence echo and type `First. Second. `, including the spaces.
+   Repeat with word and character echo enabled together; sentence completion
+   should use the Sentences voice selection.
+4. In a multiline editor, put the caret between `Hello` and ` following text`
+   and press Enter. Word/sentence completion should say `Hello`, never
+   `following text`. At the start of a line, Enter must not echo the following
+   text. Repeat on a blank line and with a line ending in punctuation.
+5. Check key echo disabled and edit-fields-only, pasted text, Backspace,
+   Left/Right navigation, rapid typing and interruption during long speech.
+   Right's echoed key name should finish before normal caret feedback.
+
+Automated routing and ordering do not prove audible voice identity, physical
+keyboard behavior, Braille output or normal-profile acceptance. Human review
+and these listening checks remain required before submission.

docs/testing/messaging.md

@@ -0,0 +1,108 @@
+# Messaging support
+
+Pidgin now uses the shared Go messaging history. This first port follows the
+legacy defaults: announce inserted messages from all conversations, keep one
+combined history for each running Pidgin accessibility provider, omit room-name
+prefixes, and suppress typing-status announcements. History contains messages
+received while this reader is running; it does not import an existing transcript.
+
+The legacy controls for separate conversation histories, room-name prefixes,
+typing announcements, and message verbosity are not yet ported.
+
+## Shortcuts
+
+Both desktop and laptop layouts use:
+
+- **Cthulhu+F1–F9**: review the newest through ninth-newest message.
+- **Cthulhu+Shift+F1–F9**: copy that message and confirm after the write succeeds.
+- **Cthulhu+H**: enter or exit learn mode. Cthulhu+F1 no longer opens it.
+
+Empty history slots are silent. Chat commands act only when Pidgin owns the
+reader's current focus. They are configurable in the existing key-binding page.
+An explicit shortcut assignment takes precedence over an uncustomized chat
+default, preserving existing configurations; the shortcut list reflects this.
+Within temporary OCR review, Cthulhu+F5 retains its refresh behavior.
+In learn mode, plain F1 still opens documentation, and F2/F3 retain their
+existing functions.
+
+Steam retains its existing notification support: **Cthulhu+N** for the latest
+notification and **Cthulhu+Ctrl+N** for the notification list. Neither the legacy
+Steam script nor this port provides F-key conversation review for Steam.
+
+## Implementation boundary
+
+- `internal/atspi/pidgin_native.go` recognizes the legacy transcript shape:
+  a noneditable, multiline text object directly inside a scroll pane, belonging
+  to a provider whose process name is `pidgin`. Its bounded ancestor scan copies
+  conversation/window identities and the room name. Typing status is identified
+  from the inserted range's smaller/lighter text attributes.
+- `internal/messaging` stores copied messages without native handles or output
+  dependencies. It bounds each provider's history to nine messages and the number
+  of retained providers to 32. Provider identities prevent cross-instance replay.
+- `internal/app/messaging.go` coordinates passive speech, one Braille flash,
+  review, and asynchronous clipboard copying on the reader event loop. A bounded
+  worker uses the shared clipboard writer; writes have a three-second deadline.
+  The event loop cancels pending copies when foreground ownership is cleared,
+  when another copy replaces them, on screen lock, and during shutdown.
+- `internal/input/messaging.go` defines numbered semantic commands independently
+  of their physical shortcuts. Existing binding configuration and learn mode
+  describe the same commands.
+
+Background chat never becomes focus or review ownership. Lock gates reject
+messages; lock transitions clear history. Destruction of a known transcript or
+window retires its messages. Ordinary edits, buddy-list activity, and unrelated
+providers keep their existing event-filtering behavior. History is never saved.
+
+Future application support should add its own verified native detector and
+explicit dispatch to this shared message contract. Keep transcript identification
+out of generic focus, speech, and history code. Steam conversation support needs
+inspection of an actual chat accessibility tree before choosing its detector;
+notification text alone does not establish conversation identity.
+
+## Automated checks
+
+From the repository root:
+
+```sh
+GOCACHE=/tmp/cthulhu-cache go test ./...
+GOCACHE=/tmp/cthulhu-cache go test -race ./internal/messaging ./internal/input ./internal/atspi ./internal/app
+python3 tests/native_test_session.py env GOCACHE=/tmp/cthulhu-cache CTHULHU_NATIVE_MESSAGING=1 go test ./internal/atspi -run '^TestNativePidginTranscriptCapture$' -count=1 -v
+python3 tests/native_test_session.py env GOCACHE=/tmp/cthulhu-cache CTHULHU_NATIVE_MESSAGING=1 go test ./internal/app -run '^TestNativeMessagingCopyPreservesClipboardText$' -count=1 -v
+python3 tests/native_test_session.py env GOCACHE=/tmp/cthulhu-cache CTHULHU_NATIVE_X11=1 go test ./internal/platform/xorg -run '^TestNativeLearnModeCapturesKeysAndRestoresCommands$' -count=1 -v
+```
+
+Native checks use private X11 and D-Bus sessions. The transcript fixture sets its
+own process name to exercise the Pidgin detector; it is not the actual Pidgin
+client. These checks verify copied metadata, recorded presentation, synthetic
+keys, and clipboard contents. They do not establish audible speech, physical
+keyboard behavior, or a connected Braille display.
+
+## Human review and live acceptance
+
+Review the diff before submission under the contribution policy. Build a reader
+for testing, then load it using the normal authorized reader-replacement procedure.
+The implementation work does not replace the running reader.
+
+1. Open two Pidgin conversations. Receive distinct messages in each and verify
+   they speak once, including when a different application has focus. Confirm
+   keyboard focus remains in that other application.
+2. Return to Pidgin. Check F1/F2 review the most recent messages across both
+   conversations. Receive more than nine messages and check the F9 boundary.
+   Send two identical messages and verify both occupy separate history slots.
+3. Use Shift+F1/F2 to copy, then paste into a native editor. Check Unicode and
+   multiline content. Confirm the copy response follows a successful write.
+4. Type in Pidgin's message entry and account/preferences fields. Check normal
+   echo and editing feedback. Buddy-list updates and remote typing status must
+   not enter chat history.
+5. Switch to another application and check chat commands do not replay Pidgin
+   history. Close a conversation window and check its messages are retired.
+   Lock/unlock and verify prior history is cleared and messages received while
+   locked are not replayed.
+6. Check Cthulhu+H enters/exits learn mode, F1/F2 work inside it, and the shortcut
+   list identifies the chat commands. Check a saved custom F-key assignment still
+   works and the displaced default is not listed as active.
+7. Check OCR F5 refresh, normal browser navigation, and Steam notifications with
+   their existing review/list commands. On Braille, check each message flashes
+   once and the normal focus display returns afterward.
+
+Actual Pidgin listening, physical shortcuts, and Braille acceptance remain pending.