fix(tui): isolate transient overlays from native scrollback

Author: hetaoBackend

docs/tui-capabilities.md

@@ -20,6 +20,10 @@ redraw preserve pending output and native history. Explicit resume-start history
 clearing remains a separate startup policy. Native image history is retained until
 the terminal itself evicts it.
 
+Transient overlays use an alternate buffer so opening, nesting or resizing panels
+cannot place menu rows in native history. Closing the last overlay restores the
+main buffer and reconciles background output; terminal shutdown also restores it.
+
 ## Output speed
 
 The activity line and completed-turn summary show provider output tokens divided by

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

@@ -163,7 +163,7 @@
     },
     {
       "path": "tui-main-screen.ts",
-      "currentSha256": "ba062254468194ab92576dbdf342a96180e68c999a3763b206b49cef191ad523",
+      "currentSha256": "0095b75384b9f99cc979e55c5ef40a94c58d79ea9e9394ad978ad61f0c2db3d8",
       "changeIds": [
         "L005",
         "L017",
@@ -179,7 +179,7 @@
       ],
       "upstreamCommit": "6c4f360264397c59801f6da2bdac13e3b1fcbe91",
       "reason": "Align bounded regular-mode projections with emitted row identities and preserve native history across folding, footer shrink, redraw and resize.",
-      "behaviorImpact": "Native scrollback retains emitted snapshots and pre-launch shell history. Automatic folding and footer updates preserve scrolling; unmatched projections archive the visible body and start a labelled snapshot. Resize retains pending rows, forced redraw retains physical state, and historical image resources survive viewport repaints."
+      "behaviorImpact": "Native scrollback retains emitted snapshots and pre-launch shell history. Automatic folding and footer updates preserve scrolling; unmatched projections archive the visible body and start a labelled snapshot. Resize retains pending rows, forced redraw retains physical state, and historical image resources survive viewport repaints. Transient overlays use a separate terminal buffer and return to main on close or stop, preserving main geometry across resize."
     },
     {
       "path": "tui.ts",

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

@@ -211,6 +211,7 @@ Remove `L024` when the selected Pi baseline natively matches legacy-terminal `Ct
 - Minimal difference: an optional `ScrollbackLayout` carries stable transcript row identities and a body/footer boundary through the public component API. MainScreen aligns a bounded logical cache at a shared nonblank row with unchanged text. Read groups identify individual member rows rather than the group's changing first cell. Later edits to already-emitted history do not replay it. Reclaimed rows remain between body and footer, preserving tables and the input cursor.
 - Reconstruction: an unmatched projection commits the old visible body, erases addressable rows in place, and starts a labelled snapshot. It never emits ED 3 or uses ED 2. Footer overflow retains its physical offset; newly appended body rows are emitted before replacing the footer. Historical Kitty resources are not freed by a viewport repaint.
 - Geometry: resize uses the hardware cursor's screen row to determine the retained origin. Safe anchors preserve every pending row, including a burst arriving during resize; an unalignable reflow starts a labelled snapshot. Forced redraw and regular/fullscreen state transfers retain physical coordinates and anchors.
+- Transient screens: visible overlays share an alternate buffer until the last one closes. Main-buffer anchors and cursor geometry are retained independently through every resize; stop restores the main buffer before returning terminal ownership. Panel rows never enter native history.
 - Evidence: engine and application regressions verify host scroll position, unique emitted rows, Todo completion, grouped reads and long-turn/turn-window eviction, contiguous tables, transient panels, cursor placement, bounded caches, oversized footers, resize bursts, image-resource lifetime, forced refresh, and mode-state restore under xterm and an ED 2 clear-to-scrollback model.
 - Boundary: old native rows retain their historical text and wrapping. Explicit resume-start clearing is unchanged. Native remote-host and cross-platform acceptance remain separate from local emulator verification.
 - Removal condition: the selected upstream engine supports immutable native output with bounded anchored live projections.

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

@@ -136,8 +136,17 @@ export class TuiMainScreen extends TuiBase implements TUI {
 	private hadOverlays = false;
 	private scrollbackLayout: ScrollbackLayout | undefined;
 	private segmentHeader = false;
+	private overlayScreenActive = false;
+	private overlayScreenWidth = 0;
+	private overlayMainReflowed = false;
+	private renderingMainOnStop = false;
 
 	protected override onTerminalResize(): void {
+		if (this.overlayScreenActive) {
+			this.updateOverlayMainGeometry();
+			this.requestRender();
+			return;
+		}
 		// Some hosts repeat resize notifications while scrolling or reconnecting.
 		// An unchanged geometry must not clear and replay native scrollback.
 		if (this.previousWidth === this.terminal.columns && this.previousHeight === this.terminal.rows) return;
@@ -159,14 +168,17 @@ export class TuiMainScreen extends TuiBase implements TUI {
 	}
 
 	override stop(options: TuiStopOptions = {}): void {
-		// Flush pending output before handing the main screen back to its host.
-		this.cancelResize();
-		// Ordinary stop must retain the latest transcript even when output is held.
-		// Mode switches already captured the current render state before stop.
-		if (!this.stopped && (this.resizePending || (!options.preserveScreen && this.hasPendingRender()))) {
-			this.doRender();
+		this.renderingMainOnStop = true;
+		try {
+			// Flush the main document and exit 1049 before returning terminal ownership.
+			this.cancelResize();
+			if (!this.stopped && (this.overlayScreenActive || this.resizePending || (!options.preserveScreen && this.hasPendingRender()))) {
+				this.doRender();
+			}
+			super.stop(options);
+		} finally {
+			this.renderingMainOnStop = false;
 		}
-		super.stop(options);
 	}
 
 	captureRenderState(): TuiMainScreenRenderState {
@@ -292,8 +304,66 @@ export class TuiMainScreen extends TuiBase implements TUI {
 		return this.deleteKittyImages(ids);
 	}
 
+	private renderOverlayScreen(): void {
+		const width = this.terminal.columns;
+		const height = this.terminal.rows;
+		if (!this.overlayScreenActive) {
+			this.terminal.write("\x1b[?1049h");
+			this.overlayScreenActive = true;
+			this.overlayScreenWidth = this.previousWidth > 0 ? this.previousWidth : width;
+		}
+		this.updateOverlayMainGeometry();
+		const background = this.render(width).slice(-height).map((line) => isImageLine(line) ? "" : line.replace(OSC133_ZONE_PREFIX, ""));
+		const lines = this.compositeOverlays(background, width, height).slice(-height);
+		const cursor = this.extractCursorPosition(lines, height);
+		this.applyLineResets(lines);
+		const output = new BoundedTerminalWriter((data) => this.terminal.write(data));
+		output.append("\x1b[?2026h");
+		for (let row = 0; row < height; row++) {
+			output.append(`\x1b[${row + 1};1H\x1b[2K${lines[row] ?? ""}`);
+		}
+		if (cursor) output.append(`\x1b[${cursor.row + 1};${cursor.col + 1}H`);
+		output.append(cursor && this.getShowHardwareCursor() ? "\x1b[?25h" : "\x1b[?25l");
+		output.append("\x1b[?2026l");
+		output.flush();
+	}
+
+	private updateOverlayMainGeometry(): void {
+		const width = this.terminal.columns;
+		const height = this.terminal.rows;
+		// The inactive main buffer still resizes. Track its cursor-based origin
+		// independently of the cursor used by the transient overlay screen.
+		const oldCursor = Math.max(0, this.hardwareCursorRow - this.previousViewportTop);
+		if (this.previousHeight > 0 && height !== this.previousHeight) {
+			if (height < this.previousHeight) this.previousViewportTop += Math.max(0, oldCursor - height + 1);
+			else if (oldCursor === this.previousHeight - 1) {
+				this.previousViewportTop = Math.max(0, this.previousViewportTop - (height - this.previousHeight));
+			}
+		}
+		if (this.overlayScreenWidth !== width && this.previousLines.some((line) =>
+			!isImageLine(line) && visibleWidth(line) > Math.min(width, this.overlayScreenWidth))) {
+			this.overlayMainReflowed = true;
+		}
+		this.overlayScreenWidth = width;
+		this.previousHeight = height;
+	}
+
 	protected doRender(): void {
 		if (this.stopped) return;
+		// Transient screens must never enter native history, even when the host
+		// shrinks before delivering its resize notification. Keep them on 1049.
+		if (!this.renderingMainOnStop && this.hasOverlay()) {
+			this.renderOverlayScreen();
+			return;
+		}
+		const returningFromOverlay = this.overlayScreenActive;
+		if (returningFromOverlay) {
+			this.updateOverlayMainGeometry();
+			this.terminal.write("\x1b[?1049l");
+			this.overlayScreenActive = false;
+		}
+		const overlayMainReflowed = this.overlayMainReflowed;
+		this.overlayMainReflowed = false;
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
 		const widthChanged = this.previousWidth !== 0 && this.previousWidth !== width;
@@ -340,7 +410,7 @@ export class TuiMainScreen extends TuiBase implements TUI {
 		const replacedTranscript = !!nextScrollbackLayout && !!oldScrollbackLayout?.anchors.length &&
 			(evictedVisibleBlock || !oldScrollbackLayout.anchors.some(({ id }) => currentAnchorIds.has(id)));
 		let anchored = false;
-		if (!replacedTranscript && nextScrollbackLayout && oldScrollbackLayout && this.viewportLayouts[0]?.component === this.children[0] && prevViewportTop > 0 &&
+		if (!overlayMainReflowed && !replacedTranscript && nextScrollbackLayout && oldScrollbackLayout && this.viewportLayouts[0]?.component === this.children[0] && prevViewportTop > 0 &&
 			this.previousLines.every((line) => isImageLine(line) || visibleWidth(line) <= width)) {
 			const currentRows = new Map(nextScrollbackLayout.anchors.map(({ id, row }) => [id, row]));
 			let match: { before: number; after: number } | undefined;
@@ -411,7 +481,7 @@ export class TuiMainScreen extends TuiBase implements TUI {
 		// screen instead. The composer stays at the bottom, historical rows stay unique,
 		// and later output consumes this temporary space before scrolling again.
 		if (
-			(stableLayout || anchored || !nextScrollbackLayout) && ((!widthChanged && !heightChanged && !this.resizePending) || anchored) &&
+			(stableLayout || anchored || !nextScrollbackLayout) && ((!widthChanged && !heightChanged && !this.resizePending) || anchored || (returningFromOverlay && !overlayMainReflowed)) &&
 			prevViewportTop > 0 && newLines.length > prevViewportTop &&
 			newLines.length < prevViewportTop + height &&
 			!this.hasImageAtOrBelow(this.previousLines, prevViewportTop) && !this.hasImageAtOrBelow(newLines, prevViewportTop)
@@ -432,11 +502,6 @@ export class TuiMainScreen extends TuiBase implements TUI {
 			}
 		}
 
-		// Composite overlays into the rendered lines (before differential compare)
-		if (this.hasOverlayEntries) {
-			newLines = this.compositeOverlays(newLines, width, height);
-		}
-
 		// Extract cursor position before applying line resets (marker must be found first)
 		let cursorPos = this.extractCursorPosition(newLines, height);
 
@@ -453,7 +518,7 @@ export class TuiMainScreen extends TuiBase implements TUI {
 				viewportOnly = false;
 			}
 			const start = viewportOnly ? prevViewportTop : 0;
-			if (clear && !viewportOnly && this.previousLines.length > 0 && (prevViewportTop > 0 || replacedTranscript) && !this.segmentHeader) {
+			if (clear && !viewportOnly && this.previousLines.length > 0 && (prevViewportTop > 0 || replacedTranscript || overlayMainReflowed) && !this.segmentHeader) {
 				this.segmentHeader = true;
 				newLines.unshift(segmentLabel.slice(0, width));
 				if (cursorPos) cursorPos = { ...cursorPos, row: cursorPos.row + 1 };
@@ -471,8 +536,8 @@ export class TuiMainScreen extends TuiBase implements TUI {
 				// Before starting a new snapshot, commit the old visible transcript.
 				// Otherwise a projection with no overlap would silently discard rows
 				// that had been displayed but had not reached native history yet.
-				const archiveRows = !viewportOnly && (prevViewportTop > 0 || replacedTranscript)
-					? widthChanged ? height : Math.min(height, Math.max(0, previousBodyEnd - prevViewportTop)) : 0;
+				const archiveRows = !viewportOnly && (prevViewportTop > 0 || replacedTranscript || overlayMainReflowed)
+					? widthChanged || overlayMainReflowed ? height : Math.min(height, Math.max(0, previousBodyEnd - prevViewportTop)) : 0;
 				if (archiveRows > 0) {
 					for (let row = archiveRows; row < height; row++) {
 						output.append(`\x1b[${row + 1};1H\x1b[2K`);
@@ -537,12 +602,16 @@ export class TuiMainScreen extends TuiBase implements TUI {
 		// Preserve the emitted prefix only when it can still be aligned. A genuine
 		// reflow without a safe anchor starts a labelled snapshot rather than dropping
 		// pending output by painting only the final screenful.
-		const resizeOriginPreserved = anchored || this.previousLines.slice(0, prevViewportTop).every((line, row) =>
-			visibleWidth(line) <= width && stripTerminalSequences(line) === stripTerminalSequences(newLines[row] ?? ""));
+		const resizeOriginPreserved = !overlayMainReflowed && (anchored || this.previousLines.slice(0, prevViewportTop).every((line, row) =>
+			visibleWidth(line) <= width && stripTerminalSequences(line) === stripTerminalSequences(newLines[row] ?? "")));
 		if (replacedTranscript) {
 			fullRender(true);
 			return;
 		}
+		if (returningFromOverlay) {
+			fullRender(true, resizeOriginPreserved);
+			return;
+		}
 		if (this.resizePending) {
 			fullRender(true, resizeOriginPreserved);
 			if (this.resizeTimer === undefined) this.resizePending = false;

packages/tui/test/unit/tui-background-work-panel.test.ts

@@ -375,6 +375,7 @@ describe('Tasks in the regular terminal viewport', () => {
         expect(terminal.getViewport()).toEqual(
           afterShrink,
         );
+        const historyAfterShrink = terminal.getScrollBuffer();
         const presenter = new TuiOverlayRegularFeaturePresenter(terminal, tui, () =>
           tui.requestRender(),
         );
@@ -387,10 +388,8 @@ describe('Tasks in the regular terminal viewport', () => {
         handle.close();
         tui.renderNow();
         await terminal.flush();
-        expect(terminal.getViewport()).toEqual(
-          [...chatLines, 'COMPOSER', 'STATUS'].slice(-terminal.rows),
-        );
-        expect(terminal.getScrollBuffer()).toEqual([...chatLines, 'COMPOSER', 'STATUS']);
+        expect(terminal.getViewport()).toEqual(afterShrink);
+        expect(terminal.getScrollBuffer()).toEqual(historyAfterShrink);
         handle = presenter.show(panel, panel);
         tui.setFocus(handle.focus);
         tui.renderNow();
@@ -428,8 +427,13 @@ describe('Tasks in the regular terminal viewport', () => {
           await terminal.flush();
           expect(terminal.getScrollBuffer().join('\n')).not.toContain('task-row-');
         });
-        for (const line of chatLines)
-          expect(terminal.getScrollBuffer().filter((row) => row === line)).toHaveLength(1);
+        const history = terminal.getScrollBuffer();
+        const boundary = history.findLastIndex((line) => line.startsWith('── Transcript refreshed'));
+        const currentSnapshot = history.slice(boundary + 1).filter(Boolean);
+        expect(currentSnapshot).toEqual([...chatLines, 'COMPOSER', 'STATUS']);
+        if (shrinkRows === 15) {
+          expect(history.slice(0, boundary)).toEqual(historyAfterShrink.slice(0, boundary));
+        }
         expect(terminal.getViewport().join('\n')).toContain('STATUS');
       } finally {
         tui.stop();

packages/tui/test/unit/tui-feature-viewport-contract.test.ts

@@ -220,8 +220,22 @@ describe.each(Object.entries(factories))('%s regular viewport lifecycle', (_name
         await vi.waitFor(async () => {
           await terminal.flush();
           const expected = [...chat(), ...Array(Math.max(0, rows - chat().length)).fill('')];
-          expect(terminal.getViewport()).toEqual(expected.slice(-rows));
-          expect(terminal.getScrollBuffer()).toEqual(expected);
+          const visible = terminal.getViewport().filter(Boolean);
+          expect(visible).toEqual(chat().slice(-visible.length));
+          const history = terminal.getScrollBuffer().filter(Boolean);
+          const boundary = history.findIndex((line) => line.startsWith('── Transcript refreshed'));
+          if (chatCount === 80 && rows === 8) {
+            // Deletion reached native history: retain the old snapshot, then label
+            // the current document. Transient panels must occur in neither segment.
+            expect(history.slice(0, boundary)).toEqual([
+              ...Array.from({ length: 80 }, (_, index) => `BACKGROUND-${index}`),
+              'COMPOSER', 'STATUS',
+            ]);
+            expect(history.slice(boundary + 1)).toEqual(chat());
+          } else {
+            expect(boundary).toBe(-1);
+            expect(history).toEqual(expected.filter(Boolean));
+          }
         });
       } finally {
         host.dispose();