terminal-tui-debugging

Spawn the application in an isolated Terminal MCP session at the failing terminal dimensions, wait for a stable frame, then dispatch one input at a time and capture the screen buffer after each step. Compare the observed buffer against the expected visual state to isolate the defect.

Use four layers: model tests for state transitions and keymaps, render tests for deterministic frame snapshots at fixed sizes, PTY tests for ANSI escapes and resize handling, and Terminal MCP sessions for live interactive diagnosis. Test at the lowest layer that reproduces the failure.

For Bubble Tea, unit-test Update and View directly and use teatest for fixed-size output and synthetic key messages. For Ratatui, use ratatui::backend::TestBackend with snapshot testing via insta, reserving tmux or PTY harnesses for real resize behavior.

Use pure Lua tests for parsing and layout math, headless Neovim child processes for plugin APIs and buffers, and RPC for inspecting editor state. Use Terminal MCP when the visible surface matters, such as floating windows, splits, cursor, colors, and redraw.

Layout behavior depends on terminal dimensions, so always create sessions with the exact failing cols and rows or record the default dimensions when reporting defects. Resize events propagate through SIGWINCH, which PTY tests can validate explicitly.

Use startRecording and stopRecording to capture complex or timing-dependent defects as asciicast artifacts for human replay and documentation. Recordings are not the primary correctness oracle; automated model, render, and PTY tests should carry regression coverage.