[Bug] TUI clears the whole screen on content shrink and on height resize, causing visible flicker

[vinchey]

Affected area

TUI

What happened?

packages/tui emits ESC[2J (full screen clear) on several render paths. Each one is a visible flash. Differential rendering itself is fine; the flashes all come from full-redraw branches.

Counted ESC[2J writes with the package's own headless VirtualTerminal harness:

Scenario	fullRedraw	ESC[2J
Pure append, 40 lines streamed	0	0
Spinner, middle line only, 60 frames	0	0
Long transcript growing past the viewport	0	0
Content shrink (collapsing tool output) x10	10	10
Height jitter, 12 resizes	12	12
Width jitter, 8 resizes	8	8

PI_DEBUG_REDRAW=1 attributes them to three branches:

12  terminal height changed          tui.ts:1696
10  deleted lines moved viewport up  tui.ts:1753
 8  terminal width changed           tui.ts:1687

This is platform independent; the harness runs on headless xterm. Windows only sees the resize cases more often because ConPTY emits more resize events.

Shrink path. The comment at tui.ts:1804-1808 assumes a shrink is one-off:

A shrink ... That is a one-time event, so it costs no recurring flicker.

In practice collapsing and expanding tool output alternates, so it flashes on every toggle: 10 clears for 10 collapse cycles.

Height path. This one has already round-tripped:

Commit	Change	Result
0925fafe3	Removed the height full redraw	Shipped in 0.51.1
dabcda0db	Restored it	Fixed editor and footer disappearing on height resize
16937947b	Added a Termux carve-out	Fixed history replaying on keyboard toggle

So any fix has to hold three things at once: no flash on height change, editor and footer stay visible, and Termux keyboard toggles do not replay history. The current heightChanged && !isTermuxSession() gate is a platform branch standing in for viewport-aligned incremental repaint.

Steps to reproduce

const terminal = new LoggingVirtualTerminal(80, 24);
const tui = new TUI(terminal);
// render 60 lines, then collapse to 12 and back, five times
for (let i = 0; i < 5; i++) {
  component.lines = lines(12); tui.requestRender(); await terminal.waitForRender();
  component.lines = lines(60); tui.requestRender(); await terminal.waitForRender();
}
// terminal.getWrites() contains 5 ESC[2J

Interactively: run a task that produces long tool output, then collapse and expand it repeatedly, or drag the terminal's height.

Expected behavior

Collapsing tool output repaints the visible window in place without clearing the screen. Height changes realign the viewport without replaying the transcript.

Prime Agent version

0.7.2 (source checkout, 9f95011)

Environment

Windows 11, Windows Terminal / ConPTY; reproduced platform independently via @xterm/headless

Additional context

fullRender(clear, preserveViewport) already has an in-place repaint path that rewrites the visible window with per-line ESC[2K and emits no screen clear.

For the shrink branch, every retained line is byte-identical (firstChanged is past the end of the new content), so routing it to that path lands the same output without the flash. I have that patched locally as a one-line change plus two regression tests; it takes scenario 4 from 10 clears to 0, and the other five scenarios are unchanged. The new tests fail with the change reverted.

Height changes look like the same shape of problem but are riskier given the history above, and would need someone who can validate on both Termux and a desktop terminal. Width changes are listed for completeness but are a genuinely different case, since wrapping changes.

Separately, PI_DEBUG_REDRAW=1 currently crashes the TUI rather than helping diagnose this:

Error: ENOENT: no such file or directory, open 'C:\Users\<user>\.prime\agent\pi-debug.log'
    at logRedraw (packages/tui/src/tui.ts:1675:7)

logRedraw calls appendFileSync with no mkdirSync, and hardcodes ~/.prime/agent rather than following PRIME_AGENT_CODING_AGENT_DIR. PI_TUI_DEBUG=1 has the same shape of problem with a hardcoded /tmp/tui. I had to create the directory by hand before I could collect the attribution table above.