cthulhu/docs/testing/graphical-terminals.md

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.

Run from the repository root:

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.