tui-render-debug

TUI Render Debugging

Use this skill when pi-go's Bubble Tea interface is broken in a terminal: text appears in the wrong row or column, the sidebar moves, old frames remain after a resize, or a redraw repairs the display.

Establish the symptom

Capture the exact terminal, TERM, COLORTERM, TERMINAL_EMULATOR, terminal size, and whether a full redraw or switching terminal modes repairs the frame. Compare the broken frame with the next clean frame. A clean redraw after a bad incremental frame points to renderer cursor state, not necessarily to bad View() geometry.

For JetBrains IDE terminals, record TERMINAL_EMULATOR=JetBrains-JediTerm. JediTerm can report TERM=xterm-256color while mishandling cursor-backward-tab (CSI Z, CBT), which makes Bubble Tea's differential renderer believe the cursor is in a different column than the emulator.

Separate output leaks from renderer drift

The interactive TUI owns the terminal. Search the active path for direct output:

rg -n 'fmt\.Print|log\.Print|os\.(Stdout|Stderr)|slog\.' internal cmd

Routine diagnostics must use the session logger. User-facing notices must use the TUI message or notice channel. A subprocess's stdout and stderr must be captured and surfaced as a tool result. Direct writes can move the cursor, but the absence of leaked stderr does not rule out a renderer incompatibility.

Build a red-capable repro

Use a PTY with the affected environment and capture stdout and stderr separately. Count and inspect control sequences in stdout; stderr should contain only diagnostics expected outside the frame.

For renderer-level tests, create an ultraviolet.TerminalRenderer with the affected environment, move from a later column to an earlier column, and assert that unsupported CBT is not emitted. Replay the captured bytes through a JediTerm-compatible emulator when available. Also verify ordinary xterm and tmux/screen environments remain unchanged.

Fix decisions

Keep frame geometry tests independent: every rendered row must match the terminal width, the rail must stay in one display column, and no ANSI escape may leak into visible content. Do not solve a terminal capability bug by changing layout constants.

When the Bubble Tea dependency has no per-capability switch, isolate a compatibility environment to Bubble Tea's renderer. Preserve the original environment for subprocesses and use the original environment for color-profile detection. Prefer disabling only the broken capability when the dependency supports it; otherwise use the narrowest compatible renderer profile and add a comment explaining why.

Verification

Run the focused regression test first, then the full TUI package, race tests for the affected seam, golangci-lint run ./internal/tui/..., and a build. Re-run the PTY capture and confirm the affected terminal no longer drifts while normal terminal output and colors remain intact.