v1.5.1 regression: TUI row offset drift when scrolling (all terminals)

[maxfi]

Summary

Scrolling the session list produces rendering artifacts (duplicated/offset rows) on all terminals — Ghostty 1.3.1, macOS Terminal.app, and Warp. This is a regression from v0.27.5, where the TUI rendered correctly.

full_repaint = true in [display] reduces the severity but does not eliminate it — drift accumulates between the 2-second tick clears.

Steps to Reproduce

1. Upgrade from v0.27.5 to v1.5.1
2. Open Agent Deck TUI with several sessions
3. Scroll up and down the session list (j/k or mouse wheel)
4. Observe rows rendering with increasing vertical offset / duplication

Environment

• Agent Deck: v1.5.1
• Previously working: v0.27.5
• Terminals tested: Ghostty 1.3.1, macOS Terminal.app, Warp (all affected)
• tmux: 3.6a
• OS: Ubuntu (server via SSH), macOS (client)
• full_repaint = true: Enabled, reduces but doesn't fix

Analysis

This is not the same as #327 (Ghostty-specific grapheme width mismatch). That issue was terminal-specific; this reproduces on all terminals.

Rendering deps unchanged

Bubble Tea, lipgloss, and go-runewidth versions are identical between v0.27.5 and v1.5.1:

• bubbletea v1.3.10
• lipgloss v1.1.0
• go-runewidth v0.0.21

Suspected root cause: CSIuReader stdin wrapper

v1.5.1 added tea.WithInput(ui.NewCSIuReader(os.Stdin)) to the tea.NewProgram call at cmd/agent-deck/main.go:624. This wraps stdin with a buffering/translation layer for CSI u keyboard compatibility.

The csiuReader.Read() at internal/ui/keyboard_compat.go:292 adds a translation pass between raw terminal bytes and Bubble Tea. This changes the Read() timing characteristics — if buffering causes reads to be delayed or batched, it could affect how Bubble Tea handles WindowSizeMsg events during scrolling, causing the renderer to use stale height/width values for one or more frames and producing the offset drift.

The codebase's own comments at home.go:8840 describe exactly this failure mode:

"Uses lipgloss.Width() for measurement to stay consistent with lipgloss.JoinHorizontal's internal width calculation. Using a different measurement can disagree by even 1 character, causing JoinHorizontal to pad all lines to the wider measurement. This makes the joined output exceed terminal width, lines wrap, and Bubble Tea's renderer loses cursor tracking — producing duplicated/stacked content (the 'scrolling artifact' bug)."

Why full_repaint doesn't fully fix it

full_repaint only fires tea.ClearScreen on the tick handler (every 2s at home.go:4299), not on key/scroll/mouse events. Drift accumulates between clears.

Suggested fix directions

1. Investigate CSIuReader timing — compare Bubble Tea rendering behavior with and without the tea.WithInput wrapper
2. Extend full_repaint to fire on tea.KeyMsg / tea.MouseMsg — not just ticks
3. Gate CSIuReader behind a config flag or terminal detection so it only activates on terminals that need it

Diagnostic suggestion

Building from source with tea.WithInput(ui.NewCSIuReader(os.Stdin)) removed from main.go:624 would confirm or rule out the CSIuReader as the cause.

[asheshgoplani]

Investigation update — partially related to your concern, not fully addressed.

What #619 addresses

PR #619 adds a mechanism guard test that locks in the csiuFileReader embedding trick (the mechanism commit 817a616 introduced to keep Bubble Tea's raw-mode setup working while CSI u translation is active). That guards against the raw-mode aspect of the CSIuReader concern.

What #619 does NOT address

Your specific concern is about Read() timing/buffering — how the csiuReader translation layer changes the cadence of bytes reaching Bubble Tea, potentially delaying WindowSizeMsg handling during scroll, causing the row-offset drift you see.

That's a different class of issue than the type-assertion one. It would require:

• Isolating whether the drift reproduces without the wrapper (hard — removing it breaks underscore input on your terminal)
• Or analyzing whether CSI u translation introduces measurable latency for WindowSizeMsg
• Or testing if the drift persists with full_repaint = true AND a synthetic patched version that moves CSI u translation to the tea.KeyMsg layer (removing the stdin wrap entirely)

Next steps

• I'll keep v1.5.1 regression: TUI row offset drift when scrolling (all terminals) #607 OPEN after test(#544,#607): regression guard for csiuFileReader raw-mode mechanism #619 merges.
• Considering a follow-up PR that moves CSI u translation to the Update() level (as originally suggested by PR fix: remove CSIuReader from tea.WithInput — breaks terminal raw mode #538's author Franz) so the stdin path is untouched and Read() timing characteristics match unwrapped stdin. That would likely resolve the scroll drift AND preserve underscore input. Tracking separately.

Thanks for the deep dive in your original report — your analysis was extremely helpful.

[asheshgoplani]

Thank you for the exceptionally thorough bug report, @maxfi — the data-flow analysis you attached (CSIuReader timing, the full_repaint tick cadence, even the home.go:8840 self-documenting comment) is what turned this into a one-hour fix instead of a three-day guessing game.

Shipped in v1.7.12 as PR #637.

Fix summary

When full_repaint = true, the Update loop now appends tea.ClearScreen on every tea.KeyMsg and mouse-wheel tea.MouseMsg — not only on the 2-second tick that fires tea.ClearScreen today. That closes the drift window between tick-based clears, which is where you were seeing the duplicated/offset rows accumulate.

Approach taken among the three you suggested: #2 — extend full_repaint to fire on KeyMsg/MouseMsg. Rationale:

• Option 1 (investigate CSIuReader timing) would have been a multi-day dive that risked regressing the Shift+letter keys silently dropped — CSI u reader not wired into input pipeline #535 Wayland/tmux CSI-u fix.
• Option 3 (gate CSIuReader behind a flag or terminal detection) is more invasive and would have created two code paths to maintain.
• Option 2 is gated by your existing full_repaint opt-in, so default-users get zero behaviour change, and it's a single intervention at the Bubble Tea boundary — 30 lines in one file.

To verify on v1.7.12

1. agent-deck --version → Agent Deck v1.7.12.
2. Confirm full_repaint = true is set under [display] in ~/.config/agent-deck/config.toml.
3. Hold j/k or spin the mouse wheel over the session list. No drift should accumulate, and non-wheel mouse clicks should NOT flicker (a regression guard test pins that).

If you still see any drift on v1.7.12, please reopen — the fix is behaviour-gated so reproducing it would point at a deeper CSIuReader timing issue that I'd then want to chase with you.

Regression coverage: 7 tests in internal/ui/home_repaint_test.go landed as TDD RED before the fix, pinned in .claude/release-tests.yaml. Future refactors that accidentally narrow the clear-on-nav rule will break the suite.