fix(tui): erase viewport redraws without saving stale history (#309)

Author: hetaoBackend

docs/tui-capabilities.md

@@ -90,7 +90,9 @@ screen, the renderer keeps native scrollback and the Composer position stable.
 Freed rows temporarily remain blank at the top of the active screen and subsequent
 output reuses them. This avoids resetting the host's scroll position when a turn
 finishes. Redundant resize notifications with unchanged dimensions do not rebuild
-history.
+history. Viewport-only redraws erase rows in place so terminals that save a cleared
+screen to scrollback, including Apple Terminal, do not retain the old Composer,
+status line or duplicate transcript rows.
 
 When a change removes or replaces text already in scrollback, the renderer still
 reconstructs the current session to avoid stale or duplicate history. Real resizes

packages/tui/src/tui/engine/LOCAL_CHANGES.json

@@ -163,11 +163,11 @@
     },
     {
       "path": "tui-main-screen.ts",
-      "currentSha256": "73789fb955252262ad03907446e4f4a6052bfcb86bf2a4fdc77ddaa1dd7ee9ee",
-      "changeIds": ["L005", "L017", "L027", "L033", "L034", "L037", "L038"],
+      "currentSha256": "5d499306f4b92d443c350dd944fbdc11b6ed7c74a030eb1e7e020890bc30fdb7",
+      "changeIds": ["L005", "L017", "L027", "L033", "L034", "L037", "L038", "L039"],
       "upstreamCommit": "6c4f360264397c59801f6da2bdac13e3b1fcbe91",
       "reason": "Keep strict TypeScript fixes and stream full and differential renders through Pi's bounded terminal writer. 缩放期间仅重绘可见尾部 常规模式在差分比较前剥离行首 OSC 133 zone 标记。 内容收缩或历史内容变化触发回退重绘时仅更新可见区域。",
-      "behaviorImpact": "Regular updates preserve native scrollback. Visible text-only shrink with unchanged historical text temporarily pads the active screen to preserve host scrolling and the input position; later output reuses this space. Historical text replacement or removal still reconstructs the session to avoid stale or duplicate history. Rebuilding clears pre-launch shell scrollback. Genuine resize retains delayed history replay; redundant same-size notifications are ignored."
+      "behaviorImpact": "Regular viewport redraws erase rows in place so hosts that save an erased screen to scrollback do not retain stale transcript or footer rows. Visible text-only shrink with unchanged historical text temporarily pads the active screen to preserve host scrolling and the input position; later output reuses this space. Historical text replacement or removal still reconstructs the session to avoid stale or duplicate history. Rebuilding clears pre-launch shell scrollback. Genuine resize retains delayed history replay; redundant same-size notifications are ignored."
     },
     {
       "path": "tui.ts",

packages/tui/src/tui/engine/LOCAL_CHANGES.md

@@ -146,3 +146,11 @@ Remove `L024` when the selected Pi baseline natively matches legacy-terminal `Ct
 - Boundary: padding is confined to the active screen. Historical text replacement/removal, real resize, overlays and image reflow retain the structural reconstruction path. Blank rows can temporarily separate native history from the visible tail; this is preferable to clearing and replaying the terminal's scrollback during ordinary completion. No mouse capture is enabled in regular mode.
 - Evidence: local-delta tests use xterm's host scroll API independently of the hardware cursor, reproduce the pre-fix jump to line zero, and verify stable scrolling, Composer position, unique history, reclaimed space, corrected-history reconstruction and resize behavior. The product queue/feature tests continue to cover canonical history replacement. Native Windows Terminal and UU Remote acceptance remain separate.
 - Removal condition: the selected Pi baseline preserves host scrolling and unique history through visible shrink.
+
+## L039: Erase regular viewport redraws in place
+
+- Product contract: repainting the visible regular-mode screen must not append the previous transcript, Composer or status line to native history.
+- Minimal difference: viewport-only full redraws home the cursor, erase each screen row with EL 2 using cursor-down movement, and return home before painting. This avoids ED 2, which saves the old screen to scrollback in Apple Terminal. Full structural reconstruction still clears and rebuilds history.
+- Evidence: local-delta tests exercise xterm and a clear-to-scrollback host model, covering historical style changes, simultaneous growth, short-document shrink, subsequent differential output, host scrolling and resize preview/replay. Native Apple Terminal replay of synthetic renderer output reproduces duplicate rows before the fix and preserves the exact document afterward.
+- Boundary: native replay covers synthetic output, not every live-model interaction or other terminal emulator.
+- Removal condition: the selected Pi baseline supplies equivalent in-place viewport erasure without retaining stale rows in native history.

packages/tui/src/tui/engine/tui-main-screen.ts

@@ -348,7 +348,18 @@ export class TuiMainScreen extends TuiBase implements TUI {
 			output.append("\x1b[?2026h"); // Begin synchronized output
 			if (clear) {
 				output.append(this.deleteKittyImages(this.previousKittyImageIds));
-				output.append(viewportOnly ? "\x1b[2J\x1b[H" : "\x1b[2J\x1b[H\x1b[3J");
+				if (viewportOnly) {
+					// ED 2 saves the old screen to scrollback in Apple Terminal. Erase
+					// each row in place so old transcript/footer rows cannot survive there.
+					output.append("\x1b[H");
+					for (let row = 0; row < height; row++) {
+						if (row > 0) output.append("\x1b[1B");
+						output.append("\x1b[2K");
+					}
+					output.append("\x1b[H");
+				} else {
+					output.append("\x1b[2J\x1b[H\x1b[3J");
+				}
 			}
 			for (let i = start; i < newLines.length; i++) {
 				if (i > start) output.append("\r\n");

packages/tui/test/unit/tui-engine-local-deltas.test.ts

@@ -37,6 +37,14 @@ class RecordingVirtualTerminal extends VirtualTerminal {
   }
 }
 
+// Apple Terminal preserves the old screen in scrollback on ED 2. Model that
+// behavior explicitly: xterm's default erase implementation does not expose it.
+class ClearToScrollbackTerminal extends RecordingVirtualTerminal {
+  override write(data: string): void {
+    super.write(data.replaceAll('\x1b[2J', `\x1b[${this.rows};1H${'\r\n'.repeat(this.rows)}\x1b[2J`));
+  }
+}
+
 class MutableLines implements Component {
   lines: string[] = [];
 
@@ -48,6 +56,68 @@ class MutableLines implements Component {
 }
 
 describe('MCode Pi Engine local deltas', () => {
+  describe.each([
+    ['xterm', RecordingVirtualTerminal],
+    ['clear-to-scrollback host', ClearToScrollbackTerminal],
+  ] as const)('%s viewport repaint', (_name, Terminal) => {
+    it.each([0, 30])('keeps unique history after a style update and %i new rows', async (growth) => {
+      const terminal = new Terminal(60, 12);
+      const tui = new TuiMainScreen(terminal);
+      const component = new MutableLines();
+      const answer = Array.from({ length: 40 }, (_, index) => `Answer ${index}`);
+      component.lines = [...answer, `old composer${CURSOR_MARKER}`, 'running'];
+      tui.addChild(component);
+      tui.renderNow();
+      await terminal.flush();
+      terminal.scrollLines(-10);
+      const before = terminal.getScrollPosition();
+      terminal.takeWrites();
+
+      const more = Array.from({ length: growth }, (_, index) => `More ${index}`);
+      component.lines = [...answer, ...more, `composer${CURSOR_MARKER}`, 'idle'];
+      component.lines[0] = '\x1b[1mAnswer 0\x1b[0m';
+      tui.renderNow();
+      await terminal.flush();
+
+      expect(terminal.getScrollBuffer()).toEqual([...answer, ...more, 'composer', 'idle']);
+      expect(terminal.getScrollPosition().viewport).toBe(before.viewport);
+      expect(terminal.getCursorPosition()).toEqual({ x: 8, y: 10 });
+      const writes = terminal.takeWrites();
+      expect(writes).not.toContain('\x1b[2J');
+      expect(writes).not.toContain('\x1b[3J');
+
+      // Subsequent differential output must still overwrite the current footer.
+      component.lines.splice(-2, 0, 'Next response');
+      tui.renderNow();
+      await terminal.flush();
+      expect(terminal.getScrollBuffer()).toEqual([...answer, ...more, 'Next response', 'composer', 'idle']);
+      terminal.scrollLines(1000);
+      expect(terminal.getViewport().slice(-3)).toEqual(['Next response', 'composer', 'idle']);
+    });
+
+    it('erases stale rows when a short document shrinks', async () => {
+      const terminal = new Terminal(60, 12);
+      const tui = new TuiMainScreen(terminal);
+      tui.setClearOnShrink(true);
+      const component = new MutableLines();
+      component.lines = ['answer', 'activity 1', 'activity 2', `old composer${CURSOR_MARKER}`, 'running'];
+      tui.addChild(component);
+      tui.renderNow();
+      await terminal.flush();
+      terminal.takeWrites();
+
+      component.lines = ['answer', `composer${CURSOR_MARKER}`, 'idle'];
+      tui.renderNow();
+      await terminal.flush();
+
+      expect(terminal.getScrollBuffer()).toEqual(['answer', 'composer', 'idle', ...Array<string>(9).fill('')]);
+      expect(terminal.getCursorPosition()).toEqual({ x: 8, y: 1 });
+      const writes = terminal.takeWrites();
+      expect(writes).not.toContain('\x1b[2J');
+      expect(writes).not.toContain('\x1b[3J');
+    });
+  });
+
   it.each([1, 8, 30])('preserves a scrolled host viewport when %i visible activity rows settle', async (activityRows) => {
     const terminal = new RecordingVirtualTerminal(60, 44);
     const tui = new TuiMainScreen(terminal);
@@ -330,8 +400,11 @@ describe('MCode Pi Engine local deltas', () => {
     expect(terminal.getCursorPosition()).toEqual({ x: 8, y: 1 });
   });
 
-  it('still previews the resized tail and restores ordered scrollback after resize settles', async () => {
-    const terminal = new RecordingVirtualTerminal(67, 44);
+  it.each([
+    ['xterm', RecordingVirtualTerminal],
+    ['clear-to-scrollback host', ClearToScrollbackTerminal],
+  ] as const)('previews the resized tail and restores ordered scrollback on %s', async (_name, Terminal) => {
+    const terminal = new Terminal(67, 44);
     const tui = new TuiMainScreen(terminal);
     const component = new MutableLines();
     component.lines = [
@@ -348,7 +421,13 @@ describe('MCode Pi Engine local deltas', () => {
       terminal.resize(60, 30);
       tui.renderNow();
       await terminal.flush();
-      expect(terminal.takeWrites()).not.toContain('\x1b[3J');
+      const previewWrites = terminal.takeWrites();
+      expect(previewWrites).not.toContain('\x1b[2J');
+      expect(previewWrites).not.toContain('\x1b[3J');
+      expect(terminal.getScrollBuffer()).toEqual([
+        ...Array.from({ length: 80 }, (_, index) => `Answer line ${index}`),
+        'composer',
+      ]);
       expect(terminal.getViewport()).toEqual([
         ...Array.from({ length: 29 }, (_, index) => `Answer line ${index + 51}`),
         'composer',