Preserve terminal feedback while coalescing repaints

docs/testing/graphical-terminals.md

@@ -0,0 +1,58 @@
+# Graphical terminal regression checks
+
+Terminal scrollback removal stays silent. In-place delete/insert repaints of
+the same region coalesce to the latest insertion for up to 500 milliseconds;
+continuous output retains that first deadline. Different terminals and regions
+keep their own feedback, and appended output flushes an earlier held repaint
+in order. Short updates such as `OK` and counts still speak. Backspace and
+Delete feedback on the caret line remains available. Moving focus to another
+control cancels the held repaint.
+
+Typing in a focused terminal can establish flat-review focus if the reader
+missed its initial focus event. A different control's stale focused bit must
+not replace known review focus.
+
+Animated window-title frames share a normalized repeat key for three seconds
+after their last occurrence. History belongs to that window and survives a
+workspace round trip; another window's identical title can still announce.
+Explicit title reading remains available. See [title checks](../../tests/window_titles.md).
+
+Run from the repository root:
+
+```sh
+go test ./internal/app -run 'Terminal|Title|Caret' -count=1
+go build -o /tmp/cthulhu-terminal-review ./cmd/cthulhu
+CTHULHU_BINARY=/tmp/cthulhu-terminal-review python3 tests/native_terminal.py
+```
+
+The native fixture uses a private X11 display, accessibility bus, shell and
+speech protocol recorder. It checks scrolling, command output, Backspace,
+Ctrl+W, Delete, history and flat review without replacing the desktop reader.
+
+For live acceptance with a rebuilt reader:
+
+1. In a VTE terminal, run commands that scroll past the visible rows. Confirm
+   each command's output speaks without replaying removed prompts.
+2. Type text, use Backspace, Ctrl+W, Left and Delete, then recall command
+   history. Check speech and Braille against the edited line.
+3. Read current and previous lines with flat review. Repeat after starting
+   the reader while that terminal already has focus, without switching away.
+4. Use a TUI that continuously rewrites a status region. Confirm its latest
+   status speaks during the activity, including short counts or `OK`. Check
+   separate regions, appended output, and two terminal panes. Move focus to
+   another control and confirm an old repaint does not follow it.
+5. Check animated titles, meaningful title changes, workspace round trips,
+   and two windows with identical titles. Check explicit title reading and
+   disabled automatic title changes. Confirm XTerm still delegates input to
+   the terminal reader and desktop controls resume normally on return.
+
+Wayland Shift+digit heading navigation uses the default libxkbcommon keymap
+(`XKB_DEFAULT_LAYOUT`, variant and options). These must match the compositor;
+KeyboardMonitor does not expose its active keymap or group. Ambiguous shifted
+symbols in multiple layouts are not registered as additional grabs. Verify
+Shift+1 through Shift+6, Alt+Shift+digit heading lists, plain typing, learn mode,
+and releasing Shift before the digit on the actual compositor. Private D-Bus
+tests establish protocol dispatch, not physical key suppression.
+
+Automated checks do not establish installed-reader, audible speech, physical
+keyboard or physical Braille acceptance.