Some echo tests added.

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.