correx/docs/qa/QA-tui-v2.md

QA Plan: TUI Bubble Tea v2 + native cursor — d247b19 85af2c6

Status: DRAFT Run date / operator: BACKLOG item: none — operator-requested TUI work, already archived in RETRO.md (2026-06-22). This plan does not gate a BACKLOG→RETRO move; it gates the behavioral claims that go test can't prove (Shift+Enter, the real cursor, no render regressions), which need a real kitty-protocol terminal.

---

Preconditions

• terminal: kitty (or any kitty-keyboard-protocol terminal: ghostty / foot / wezterm / recent iTerm2) — Shift+Enter disambiguation depends on it.
• tui build/branch: feat/backlog-burndown at 85af2c6 — cd apps/tui-go && GOTOOLCHAIN=auto go build -o /tmp/correx-tui .
• server up: a correx server reachable at --host/--port (default localhost:8080) with at least one resumable session, so in-session views render. Rebuild the server only while it's stopped (lazy classloading).
• config synced: ~/.config/correx matches examples/* (stale copies cause silent bugs).
• (optional) CORREX_TUI_LOG=/tmp/tui.log to capture the KEY type=… alt=… debug lines as corroborating evidence for the key checks.

Acceptance gate (one sentence)

The TUI is correct on v2 iff Shift+Enter inserts a newline in the composer without sending, a real blinking cursor tracks the caret in insert mode (and vanishes in normal mode / behind modals), and nothing in the render layer regressed from the v1 build.

Checks

Evidence is the live TUI render (an allowed source) plus, where noted, the CORREX_TUI_LOG key lines.

#	Action	Expected observable evidence	Result
1	Enter a session, press i, type a word	A blinking vertical-bar cursor sits at the caret; typing extends it. Log shows KEY … type=keyRunes.
2	With text in the composer, press Shift+Enter	A newline is inserted; the input grows to a second row; nothing is submitted. Log line shows the Enter key with shift (no submit).
3	Press Enter (bare)	The message submits (composer clears / turn appears). Confirms bare Enter still sends.
4	Press Ctrl+J, then Alt+Enter (fallback paths)	Each inserts a newline without sending (parity with Shift+Enter).
5	From insert mode press esc to normal mode	The blinking cursor disappears entirely (no stray bar left on screen).
6	In insert mode, open the palette (/ or p)	The modal's own filter caret blinks; no second cursor shows behind/around the modal. Close it → composer cursor returns.
7	Leave the composer in insert mode and idle ~5s, then drag-select text with the mouse	Selection holds (screen isn't being redrawn out from under it) — confirms insert mode no longer forces the frame loop.
8	Observe the terminal tab/title while in a session vs. idle	Title reads correx — <session name> in-session; correx — <model> (or correx) when idle.
9	Visual regression sweep: open ? help, stats, an e event inspector, a ^x diff, the t artifacts viewer; resize the terminal narrow↔wide	Colors/borders/opaque panels look as before; modals scroll (PgUp/PgDn, g/G); diff viewer pages; no garbled ANSI, no off-by-one panel widths, alt-screen restores the shell cleanly on q.
10	Walk the approval band (trigger a gate), ↑/↓ the queue, approve/reject/steer	Band behaves exactly as on v1 (single-key low tiers, arm→confirm T3+); steering caret still draws.

Out of scope (explicitly NOT covered this pass)

• Mouse-wheel scroll (deliberately not added — would fight native text selection).
• Native cursor for the palette/files/steering/config carets (still frame-drawn ▏; only the main composer moved to View.Cursor).
• Behavior on non-kitty terminals beyond the documented Ctrl+J/Alt+Enter fallback.

Disposition

• PASS → set Status: PASSED with the run date; the RETRO 2026-06-22 rows for d247b19/85af2c6 stand as live-verified.
• FAIL → file each failure as a numbered finding in BACKLOG.md (action + exact repro + the render/log signal that was wrong), fix, then re-run only the failed checks. Set Status: FAILED until green.