@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/tui.ts

@@ -29,13 +29,14 @@ import { col } from "./native/describe";
 import { TSP_PREFIX, type TspHello } from "./native/encode";
 import type { DescribeContext, NativeNode, NativeScreen, NativeSurfaceProvider, NativeUiEvent } from "./native/node";
 import { STDOUT_BACKLOG_CLEAR_BYTES, setAltScreenActive, type Terminal } from "./terminal";
+import { classifyTerminalMultiplexerModule, terminalMultiplexerSessions } from "./terminal-multiplexer";
 import {
 	encodeKittyDeleteAllImages,
 	encodeKittyDeleteImage,
+	encodeKittyDeletePlacement,
 	encodeKittyPlacementLine,
 	ImageProtocol,
 	isImageProtocolForced,
-	isInsideHerdr,
 	isInsideTerminalMultiplexer,
 	parseKittyDirectPlacementLine,
 	setCellDimensions,
@@ -44,15 +45,14 @@ import {
 	synchronizedOutputUserOverride,
 	TERMINAL,
 } from "./terminal-capabilities";
+import { compositeLineAt } from "./render/composite";
 import {
 	Ellipsis,
-	extractSegments,
 	getWidthConfigEpoch,
 	isOsc66Line,
 	normalizeTerminalOutput,
 	osc66MaxScale,
 	sliceByColumn,
-	sliceWithWidth,
 	truncateToWidth,
 	visibleWidth,
 } from "./utils";
@@ -88,6 +88,9 @@ const MIN_MAIN_AREA_COLUMNS = 64;
 const HIDE_CURSOR = "\x1b[?25l";
 const SYNC_OUTPUT_BEGIN = "\x1b[?2026h";
 const SYNC_OUTPUT_END = "\x1b[?2026l";
+// tmux expires synchronized output after one second. Renew during large
+// replays as the output queue drains, at complete sequence/row boundaries.
+const SYNC_OUTPUT_RENEW_BYTES = 16 * 1024;
 const DISABLE_AUTOWRAP = "\x1b[?7l";
 const ENABLE_AUTOWRAP = "\x1b[?7h";
 const PAINT_BEGIN = `${HIDE_CURSOR}${SYNC_OUTPUT_BEGIN}${DISABLE_AUTOWRAP}`;
@@ -196,6 +199,10 @@ export interface TUIStartOptions {
 	 * Paint without owning stdin: the terminal stays in cooked mode (kernel
 	 * echo + line editing at the hardware cursor) until {@link TUI.enableInput}
 	 * switches to raw input and replays the kernel-buffered keystrokes.
+	 *
+	 * A terminal expected to speak TSP needs raw input from the start, so it
+	 * gets it; its keystrokes are held instead (TSP events and the cell-size
+	 * reply still apply) until {@link TUI.releaseHeldInput} replays them.
 	 */
 	deferInput?: boolean;
 }
@@ -292,6 +299,12 @@ export interface Component {
 	/** User actions on nodes this component described (toggle, select, activate, custom). */
 	handleNativeEvent?(event: NativeUiEvent): void;
 
+	/**
+	 * Pure preflight for focused input that must precede TUI-wide input listeners
+	 * and debug shortcuts. A true result routes the event to this component first.
+	 */
+	capturesInput?(data: string): boolean;
+
 	/**
 	 * Optional handler for keyboard input when component has focus
 	 */
@@ -308,6 +321,16 @@ export interface Component {
 	 * Called when theme changes or when component needs to re-render from scratch.
 	 */
 	invalidate?(): void;
+	/**
+	 * Optional hook to drop memoized render output (rows, parse and wrap state)
+	 * that the next `render()` can rebuild from state the component keeps.
+	 * Unlike {@link invalidate}, it must not rebuild anything eagerly: no
+	 * renderer or extension callbacks, no image conversions, and no child
+	 * replacement or disposal. The next render must return the same rows it
+	 * would have returned without the release. Components without it are
+	 * simply not released.
+	 */
+	releaseRenderCaches?(): void;
 	/**
 	 * Optional hook to set whether this component ignores tight layout mode.
 	 */
@@ -538,6 +561,7 @@ export class Container implements Component {
 	clear(): void {
 		this.children = [];
 		this.#memoLines = undefined;
+		this.#memoChildLines = [];
 	}
 
 	/** Dispose every child, then detach it from this container. */
@@ -547,12 +571,23 @@ export class Container implements Component {
 	}
 
 	invalidate(): void {
+		// The per-child refs pin every row the children last rendered; dropping
+		// only the concatenation would keep all of them reachable.
 		this.#memoLines = undefined;
+		this.#memoChildLines = [];
 		for (const child of this.children) {
 			child.invalidate?.();
 		}
 	}
 
+	releaseRenderCaches(): void {
+		this.#memoLines = undefined;
+		this.#memoChildLines = [];
+		for (const child of this.children) {
+			child.releaseRenderCaches?.();
+		}
+	}
+
 	/**
 	 * Propagate teardown to children. Call when the container's children are
 	 * being permanently discarded (not when they are detached for reuse — use
@@ -611,6 +646,13 @@ interface HardwareCursorState {
 	visible: boolean;
 }
 
+/** A cursor-positioned image owned by a mutable viewport, never by history. */
+interface LiveImagePlacement {
+	imageId: number;
+	placementId: number;
+	line: string;
+}
+
 interface PreparedLine {
 	raw: string;
 	width: number;
@@ -817,6 +859,16 @@ export class TUI extends Container {
 	// shrink-then-regrow that never exceeds the pre-burst height (see the
 	// CPR-timeout fallback in #resolveResizeAnchor).
 	#resizeBurstPull = 0;
+	// Whether any step of the burst left the committed width / geometry. The
+	// terminal reflowed the normal buffer at every intermediate step, so a drag
+	// that returns to its starting size still shredded retained history and
+	// pushed unerased live rows into it; the settled refresh must key on the
+	// whole burst, not on the net change (see #prepareResizeReplay).
+	#resizeBurstWidthChanged = false;
+	#resizeBurstResized = false;
+	// A shrink can discard live rows below the cursor and push others into
+	// scrollback. Rebuild must repair that even when the burst ends taller.
+	#resizeBurstShrank = false;
 	// Geometry epoch: bumped on every resize transaction entry, so each CSI 6n
 	// request records the geometry it was parked under.
 	#geometryEpoch = 0;
@@ -846,6 +898,12 @@ export class TUI extends Container {
 	#preparedLineMemo = new Map<string, PreparedLine>();
 	#preparedLineMemoSpare = new Map<string, PreparedLine>();
 	#previousFrameLength = 0;
+	// Rows a transiently grown frame scrolled off the top without any history
+	// transaction committing them (see #emitPlanFrame). The shrink that follows
+	// the transient chrome row out pulls exactly these rows back, restoring the
+	// pre-growth screen; any append, replay, reset, resize, or overlay frame
+	// zeroes the count — those scrolls are committed or superseded.
+	#transientScrollPushed = 0;
 	#previousWidth = 0;
 	#previousHeight = 0;
 	// Physical width of the last provider frame. Scrollback reflow follows the
@@ -915,6 +973,16 @@ export class TUI extends Container {
 	static readonly #RESIZE_VIEWPORT_SETTLE_MS = 120;
 	/** Longest wait for a CPR reply before the settled repaint falls back. */
 	static readonly #RESIZE_PROBE_TIMEOUT_MS = 200;
+	/**
+	 * Smallest settled tmux replay that is preceded by a `Rebuilding…` notice.
+	 * The notice can only be published ahead of the replay (tmux holds the
+	 * pane's synchronized update until the replay ends), so it stays up for
+	 * exactly as long as tmux takes to ingest the replay. tmux next-3.9 on
+	 * Apple silicon ingests a real transcript replay at ~14 MiB/s, so this is
+	 * about half a second there. A smaller replay finishes before the notice
+	 * can be read, and showing it would only flash a status row.
+	 */
+	static readonly #RESIZE_REBUILD_NOTICE_MIN_BYTES = 7 * 1024 * 1024;
 	#inputRenderGraceUntilMs = 0;
 	// A scale-`s` OSC 66 heading reserves `s - 1` rows, and the protocol
 	// caps `s` at 7. This bounds spacer lookups and supplies enough context
@@ -924,8 +992,8 @@ export class TUI extends Container {
 	// settle window, leaving only Unicode placeholder cells. Hold the first image
 	// paint until that window has passed; later images render normally.
 	static readonly #GHOSTTY_INITIAL_IMAGE_DELAY_MS = 100;
-	#hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
-	#hardwareCursorState: HardwareCursorState | null = null;
+	#hardwareCursorRow = 0; // Normal-buffer cursor row, retained while the alternate buffer is active.
+	#hardwareCursorState: HardwareCursorState | null = null; // Current buffer's cursor paint/dedupe state.
 	#sixelProbePendingGraphics = false;
 	#sixelProbeBuffer = "";
 	#sixelProbeTimeout?: NodeJS.Timeout;
@@ -939,6 +1007,9 @@ export class TUI extends Container {
 	// Caps how many inline images render as live graphics; older ones fall back
 	// to text via a purge + full redraw. Cap is configured by the host app.
 	#imageBudget = new ImageBudget(DEFAULT_MAX_INLINE_IMAGES, () => this.requestRender());
+	#screenImagePlacements = new Map<number, LiveImagePlacement>();
+	#altImagePlacements = new Map<number, LiveImagePlacement>();
+	#nextImagePlacementId = 1;
 	#ghosttyInitialImageDelayDone = false;
 	#ghosttyInitialImageDelayTimer: RenderTimer | undefined;
 	#ghosttyImageReadyAtMs = 0;
@@ -952,6 +1023,17 @@ export class TUI extends Container {
 	#cancelPostmortemRestore?: () => void;
 	/** True between a `deferInput` start() and enableInput(). */
 	#inputDeferred = false;
+	/**
+	 * Keystrokes held since a TSP `deferInput` start, replayed by
+	 * releaseHeldInput(); undefined when not holding.
+	 */
+	#heldInput: string[] | undefined;
+	/**
+	 * The component focused when holding began. Only its keystrokes are held:
+	 * a dialog that takes focus meanwhile (a startup hook's select or confirm)
+	 * gets its input live.
+	 */
+	#heldFocus: Component | null = null;
 	// Always-on event-loop lag probe. The high default threshold keeps it quiet;
 	// it only logs `ui.loop-blocked` (with the current loop phase) when a frame
 	// budget is genuinely starved. Armed in start(), disarmed in stop().
@@ -982,15 +1064,25 @@ export class TUI extends Container {
 	#altToggleColumns = 0;
 	#altToggleRows = 0;
 	#altToggleEchoPending = false;
-	// True while an in-place resize transaction (Warp) is inside its settle
-	// window: the normal-buffer anchor is stale until the settled CPR probe
-	// resolves, so ordinary paints are dropped until then.
+	// True while an in-place resize waits for its settled rebuild (tmux) or
+	// anchor recovery (Warp): ordinary paints must not use the stale anchor.
 	#resizeInPlaceActive = false;
 	#resizeScrollbackMode: ResizeScrollbackMode = TUI.#initialResizeScrollbackMode();
 	#resizeReplaySize: string | undefined;
+	// The resize borrow's entry (live-viewport erase, CSI ?1049h, keyboard
+	// push), held for the first resize frame's synchronized update. Written on
+	// its own, the terminal can present the blank alternate screen for a frame
+	// before the resize frame lands.
+	#pendingAltEnter = "";
 	// Holds an alternate-screen exit until its replacement full paint can emit it
 	// atomically. It must survive a deferred Ghostty image frame.
 	#pendingAltExit = "";
+	// True while #pendingAltExit holds the resize borrow's own exit: the
+	// settle fused it into the destructive rebuild, so the terminal is still
+	// on the borrowed alt buffer until that frame is written. A SIGWINCH or a
+	// fullscreen overlay arriving first adopts the buffer instead of entering
+	// it again (see #settleResizeAltPaint).
+	#resizeAltExitFused = false;
 
 	// Tern Surface Protocol backend, created when the terminal answers the
 	// `hello` probe, or at start when the environment names Tern. Kept across
@@ -1177,6 +1269,8 @@ export class TUI extends Container {
 
 	#purgeInlineImages(): void {
 		const transmittedIds = this.#imageBudget.takeAllTransmittedIds();
+		this.#screenImagePlacements.clear();
+		this.#altImagePlacements.clear();
 		if (TERMINAL.imageProtocol !== ImageProtocol.Kitty) return;
 		for (const id of transmittedIds) {
 			this.terminal.write(encodeKittyDeleteImage(id));
@@ -1464,6 +1558,12 @@ export class TUI extends Container {
 		// `hello` query must go out now to confirm the surface.
 		const nativeExpected = this.terminal.tspExpected === true;
 		this.#inputDeferred = options?.deferInput === true && !nativeExpected;
+		// A restart (a startup dialog's external editor stops and restarts the
+		// TUI) keeps an existing hold: those keys still belong to the editor.
+		if (options?.deferInput === true && nativeExpected) {
+			this.#heldInput = [];
+			this.#heldFocus = this.#focusedComponent;
+		}
 		this.#watchdog.start();
 		this.#ghosttyInitialImageDelayDone = false;
 		this.#ghosttyImageReadyAtMs = this.#renderScheduler.now() + TUI.#GHOSTTY_INITIAL_IMAGE_DELAY_MS;
@@ -1477,12 +1577,19 @@ export class TUI extends Container {
 		this.terminal.onPrivateModeReport?.((mode, supported, confirmed = true, status) => {
 			if (mode !== 2026 || !confirmed) return;
 			if (synchronizedOutputUserOverride() !== null) return;
-			// Herdr's Ghostty VTE honors DEC 2026 even when DECRQM is unanswered or
-			// reports unrecognized (status 0). Other confirmed unsupported reports
-			// still disable: status 4 is permanently reset, and a three-argument
-			// callback (`status` omitted) is a definitive unsupported from a
-			// custom Terminal that does not distinguish DECRPM codes.
-			if (!supported && isInsideHerdr() && status === 0) return;
+			// Some multiplexer VTEs (Herdr's Ghostty pane) honor DEC 2026 even when
+			// DECRQM is unanswered or reports unrecognized (status 0). Other
+			// confirmed unsupported reports still disable: status 4 is permanently
+			// reset, and a three-argument callback (`status` omitted) is a
+			// definitive unsupported from a custom Terminal that does not
+			// distinguish DECRPM codes.
+			if (
+				!supported &&
+				status === 0 &&
+				terminalMultiplexerSessions().some(multiplexer => multiplexer.honorsSynchronizedOutput)
+			) {
+				return;
+			}
 			this.#setSynchronizedOutput(supported);
 		});
 		// Icons painted before the Glyph Protocol registration landed may sit in
@@ -1492,6 +1599,13 @@ export class TUI extends Container {
 			this.invalidate();
 			this.requestRender(true);
 		});
+		this.terminal.onSixelSupport?.(supported => {
+			if (!supported || this.#stopped || this.#nativeLive || this.terminal.tspExpected) return;
+			if (isImageProtocolForced()) return;
+			// Keep consuming an already-requested XTSMGRAPHICS reply until it
+			// arrives or times out, even though DA1 has established support.
+			this.#enableSixelProtocol();
+		});
 		this.terminal.onTspHello?.(hello => this.#onTspHello(hello));
 		this.terminal.start(
 			data => this.#handleInput(data),
@@ -1516,7 +1630,7 @@ export class TUI extends Container {
 						return;
 					}
 					this.#cancelResizeProbe();
-					if (this.#resizeRepaintsInPlace()) this.#beginResizeInPlacePaint();
+					if (this.#resizeAvoidsAltBuffer()) this.#beginResizeInPlacePaint();
 					else this.#beginResizeAltPaint(true);
 					return;
 				}
@@ -1545,7 +1659,7 @@ export class TUI extends Container {
 					this.requestRender(true);
 					return;
 				}
-				if (this.#resizeRepaintsInPlace()) {
+				if (this.#resizeAvoidsAltBuffer()) {
 					this.#beginResizeInPlacePaint();
 					return;
 				}
@@ -1705,7 +1819,7 @@ export class TUI extends Container {
 		this.#resizeSettleTimer?.cancel();
 		this.#resizeSettleTimer = undefined;
 		if (this.#altActive || this.#resizeAltActive) {
-			this.terminal.write(`${this.#keyboardEnhancementExit()}\x1b[?1049l`);
+			this.terminal.write(`${this.#takePendingAltEnter()}${this.#keyboardEnhancementExit()}\x1b[?1049l`);
 			setAltScreenActive(false);
 			this.#altActive = false;
 			this.#resizeAltActive = false;
@@ -1760,11 +1874,11 @@ export class TUI extends Container {
 		};
 	}
 	/**
-	 * Whether a resize repaints the visible window in place — no alternate-screen
-	 * borrow. Warp-only: Warp re-reports its size on alt-buffer toggles, so borrowing
-	 * there self-sustains. Every other terminal keeps the alt-borrow path. Inside a
-	 * multiplexer the mux owns the grid and consumes the toggles itself, so an
-	 * inherited Warp marker must not divert the mux-tuned borrow path.
+	 * Whether a resize only repaints the visible window in place, without history
+	 * replay. Warp re-reports its size on alt-buffer toggles, so borrowing there
+	 * self-sustains. Inside a multiplexer the mux owns the grid and consumes the
+	 * toggles itself, so an inherited Warp marker must not suppress its replay.
+	 * tmux's synchronized rebuild is selected separately in #resizeAvoidsAltBuffer.
 	 *
 	 * A ConPTY host is excluded for the same reason as a multiplexer: conhost owns
 	 * the grid the application writes to. Measured on conhost, resizing the
@@ -1783,6 +1897,21 @@ export class TUI extends Container {
 		return Bun.env.TERM_PROGRAM?.toLowerCase() === "warpterminal";
 	}
 
+	#resizeAvoidsAltBuffer(): boolean {
+		if (this.#resizeRepaintsInPlace()) return true;
+		// Unlike Warp's viewport-only repaint, tmux still rebuilds history.
+		// Restoring an alternate buffer schedules a tmux redraw that ends its
+		// synchronized update early, exposing the rest of a long replay.
+		return (
+			!this.#resizeAltActive &&
+			!this.#pendingAltExit &&
+			resizeInPlaceOverride() !== false &&
+			this.#resizeScrollbackMode === "rebuild" &&
+			this.#synchronizedOutputEnabled &&
+			classifyTerminalMultiplexerModule()?.altRestoreEndsSynchronizedOutput === true
+		);
+	}
+
 	#noteAltBufferToggle(): void {
 		this.#altToggleColumns = this.terminal.columns;
 		this.#altToggleRows = this.terminal.rows;
@@ -1816,17 +1945,23 @@ export class TUI extends Container {
 	#trackResizeBurst(): void {
 		const burstLastHeight = this.#resizeBurstLastHeight ?? this.#previousHeight;
 		if (this.terminal.rows > burstLastHeight) this.#resizeBurstGrew = true;
+		if (this.terminal.rows < burstLastHeight) this.#resizeBurstShrank = true;
 		this.#resizeBurstLastHeight = this.terminal.rows;
 		this.#resizeBurstPull += Math.max(0, this.terminal.rows - burstLastHeight);
+		// Latch against the physical width: with the sidebar reserving columns,
+		// `#previousWidth` holds the composed main-area width, which would arm
+		// the burst on every sidebar toggle.
+		if (this.terminal.columns !== this.#previousPhysicalWidth) this.#resizeBurstWidthChanged = true;
+		if (this.terminal.columns !== this.#previousPhysicalWidth || this.terminal.rows !== this.#previousHeight) {
+			this.#resizeBurstResized = true;
+		}
 		this.#geometryEpoch++;
 	}
 
 	/**
-	 * Coalesced in-place resize transaction for Warp-class terminals: never
-	 * borrows the alt buffer. Drag SIGWINCHes only re-arm the settle window, so a
-	 * drag emits no paints and no scrollback replay; once quiet, the transaction
-	 * snapshots the live window and runs the CPR anchor probe, and the single
-	 * settled repaint lands on the recovered anchor with no ED3 rewrap.
+	 * Coalesced resize without borrowing the alt buffer. Once quiet, tmux can
+	 * rebuild directly under synchronized output; viewport-only repaints recover
+	 * their anchor with CPR. The existing screen remains visible while waiting.
 	 */
 	#beginResizeInPlacePaint(): void {
 		if (this.#altActive) {
@@ -1838,7 +1973,9 @@ export class TUI extends Container {
 		this.#resizeSettleTimer?.cancel();
 		this.#forgetHardwareCursorState();
 		this.#recordHardwareCursorHidden();
-		if (this.#eraseLiveViewportForResize()) {
+		const erase = this.#liveViewportResizeErase();
+		if (erase !== "") {
+			this.terminal.write(erase);
 			// The erase parked the hardware cursor on the viewport's top row;
 			// snapshot the parked offset so the settled probe anchors there.
 			this.#parkedViewportOffset = 0;
@@ -1846,6 +1983,12 @@ export class TUI extends Container {
 		this.#resizeSettleTimer = this.#renderScheduler.scheduleRender(() => {
 			this.#resizeSettleTimer = undefined;
 			if (this.#stopped) return;
+			this.#prepareResizeReplay(this.terminal.columns, this.terminal.rows);
+			if (this.#clearScrollbackOnNextRender) {
+				this.#resizeInPlaceActive = false;
+				this.requestRender();
+				return;
+			}
 			this.#resizeProbeWindow = this.#providerWindow;
 			this.#resizeProbeOffset = this.#parkedViewportOffset;
 			this.#beginResizeAnchorProbe();
@@ -1867,13 +2010,14 @@ export class TUI extends Container {
 	 * cursor-relative addressing would start rows late; fall back to the same
 	 * bottom-preserving bound as resize-anchor recovery.
 	 *
-	 * Both erase paths leave the cursor on the viewport's top row. Returns true
-	 * when it erased (multiplexers skip it: an immediate erase races the pane
-	 * re-layout and blanks pulled-back committed rows).
+	 * Both erase paths leave the cursor on the viewport's top row. Returns the
+	 * erase sequence, or "" when there is nothing to erase (multiplexers skip
+	 * it: an immediate erase races the pane re-layout and blanks pulled-back
+	 * committed rows).
 	 */
-	#eraseLiveViewportForResize(): boolean {
+	#liveViewportResizeErase(): string {
 		if (!this.#hasEverRendered || this.#providerWindow.length === 0 || isInsideTerminalMultiplexer()) {
-			return false;
+			return "";
 		}
 		if (this.terminal.rows < this.#previousHeight) {
 			const staleRows = this.#reflowedRowCount(
@@ -1883,13 +2027,11 @@ export class TUI extends Container {
 				this.terminal.columns,
 			);
 			const top = Math.max(0, Math.min(this.#providerViewportTop, this.terminal.rows - staleRows));
-			this.terminal.write(`\x1b[?25l${this.#eraseBelowRow(top, this.terminal.rows)}`);
-		} else {
-			const up = this.#reflowedRowCount(this.#providerWindow, 0, this.#parkedViewportOffset, this.terminal.columns);
-			const eraseBelow = this.#eraseBelowCursorRow(this.terminal.columns, this.terminal.rows);
-			this.terminal.write(`\x1b[?25l${up > 0 ? `\x1b[${up}A` : ""}${eraseBelow}`);
+			return `\x1b[?25l${this.#eraseBelowRow(top, this.terminal.rows)}`;
 		}
-		return true;
+		const up = this.#reflowedRowCount(this.#providerWindow, 0, this.#parkedViewportOffset, this.terminal.columns);
+		const eraseBelow = this.#eraseBelowCursorRow(this.terminal.columns, this.terminal.rows);
+		return `\x1b[?25l${up > 0 ? `\x1b[${up}A` : ""}${eraseBelow}`;
 	}
 
 	/**
@@ -1905,15 +2047,27 @@ export class TUI extends Container {
 			return;
 		}
 		this.#trackResizeBurst();
-		if (!this.#resizeAltActive) {
+		if (!this.#resizeAltActive && this.#resizeAltExitFused) {
+			// The settled rebuild has not been written yet, so its fused exit never
+			// left the borrowed buffer: resume the borrow there. The live window was
+			// already stashed and the rebuild stays latched, so there is nothing to
+			// snapshot or erase, and entering again would stack another alt switch.
+			this.#resizeAltActive = true;
+			this.#pendingAltExit = "";
+			this.#resizeAltExitFused = false;
+		} else if (!this.#resizeAltActive) {
 			this.#resizeAltActive = true;
 			setAltScreenActive(true);
 			this.#altPreviousLines = [];
 			this.#altPreparedRows = [];
 			this.#forgetHardwareCursorState();
 			this.#recordHardwareCursorHidden();
-			// Blank the live region up front so a reflow-driven scroll can only push
-			// committed rows into scrollback. The pre-erase window is stashed for
+			// Blank the live region as the borrow enters so a reflow-driven scroll
+			// can only push committed rows into scrollback. The erase is computed
+			// against this SIGWINCH's geometry but rides in the first resize frame's
+			// synchronized update with the buffer switch (#pendingAltEnter), so
+			// neither the blanked normal screen nor the empty alternate one is ever
+			// presented. The pre-erase window is stashed for
 			// the settled CPR probe: its reflowed row count bounds the anchor to
 			// `height - staleRows`, so a mis-parked cursor (a single-step tmux zoom
 			// re-lays the pane before SIGWINCH delivery, moving the park target
@@ -1923,8 +2077,9 @@ export class TUI extends Container {
 				this.#resizeProbeWindow = this.#providerWindow;
 				this.#resizeProbeOffset = this.#parkedViewportOffset;
 			}
-			if (this.#eraseLiveViewportForResize()) {
-				// The erase parked the cursor on the viewport's top row, so the
+			const erase = this.#liveViewportResizeErase();
+			if (erase !== "") {
+				// The erase parks the cursor on the viewport's top row, so the
 				// parked offset no longer applies; carrying a stale nonzero offset
 				// into the probe would anchor the settled repaint above the real
 				// viewport top and overwrite visible committed rows.
@@ -1947,23 +2102,70 @@ export class TUI extends Container {
 			}
 			this.#noteAltBufferToggle();
 			this.#imageBudget.beginAltScreenLifecycle();
-			this.terminal.write(`\x1b[?1049h${this.#keyboardEnhancementEnter()}`);
+			this.#pendingAltEnter = `${erase}\x1b[?1049h${this.#keyboardEnhancementEnter()}`;
 		}
 		this.#resizeSettleTimer?.cancel();
 		this.#resizeSettleTimer = this.#renderScheduler.scheduleRender(() => {
 			this.#resizeSettleTimer = undefined;
 			if (this.#stopped || !this.#resizeAltActive) return;
-			this.#resizeAltActive = false;
-			this.#suppressResizeUntil = this.#renderScheduler.now() + 100;
-			this.#noteAltBufferToggle();
-			this.terminal.write(`${this.#keyboardEnhancementExit()}\x1b[?1049l`);
-			setAltScreenActive(false);
-			this.#altPreviousLines = [];
-			this.#altPreparedRows = [];
-			this.#beginResizeAnchorProbe();
+			this.#settleResizeAltPaint();
 		}, TUI.#RESIZE_VIEWPORT_SETTLE_MS);
 		this.requestRender(true);
 	}
+
+	/**
+	 * End the alt-buffer borrow once the resize settles.
+	 *
+	 * A settle that rebuilds history never needs the viewport anchor: the
+	 * destructive reset erases the screen and history and repaints from row
+	 * zero. Restoring the normal buffer on its own write would only expose the
+	 * reflowed stale screen for the CPR round trip, then clear it and stream
+	 * the replay — the one flash a large resize (a tmux zoom) still showed. So
+	 * that settle latches the rebuild now and fuses the restore into the same
+	 * synchronized write as ED2+ED3 and the replay: the terminal goes straight
+	 * from the resize frame to the rebuilt screen.
+	 *
+	 * Every other settle restores the normal buffer and probes the reflowed
+	 * anchor, which the non-destructive repaint depends on.
+	 */
+	#settleResizeAltPaint(): void {
+		this.#resizeAltActive = false;
+		this.#suppressResizeUntil = this.#renderScheduler.now() + 100;
+		this.#altPreviousLines = [];
+		this.#altPreparedRows = [];
+		const exitSequence = `${this.#keyboardEnhancementExit()}\x1b[?1049l`;
+		// Only the provider plan frame emits a pending exit, and an exit already
+		// pending (a fused overlay close) owns that slot.
+		if (this.#frameProvider !== undefined && this.#pendingAltExit === "") {
+			if (this.#resizeScrollbackMode === "rebuild") {
+				this.#prepareResizeReplay(this.terminal.columns, this.terminal.rows);
+			}
+			if (this.#clearScrollbackOnNextRender) {
+				// An entry no resize frame carried yet rides ahead of this exit in
+				// the rebuild frame (see #renderProviderFrame).
+				this.#pendingAltExit = exitSequence;
+				this.#resizeAltExitFused = true;
+				this.requestRender(true);
+				return;
+			}
+		}
+		this.#noteAltBufferToggle();
+		this.terminal.write(this.#takePendingAltEnter() + exitSequence);
+		setAltScreenActive(false);
+		this.#beginResizeAnchorProbe();
+	}
+	/**
+	 * Claim the resize borrow's entry for the write that carries it. A borrow
+	 * that ends before any frame painted (output backpressure deferred them)
+	 * still owes its entry, so the exit write prepends it: one write, never a
+	 * bare buffer switch the terminal could present.
+	 */
+	#takePendingAltEnter(): string {
+		const enter = this.#pendingAltEnter;
+		this.#pendingAltEnter = "";
+		return enter;
+	}
+
 	/**
 	 * Recover the reflowed viewport anchor after the resize settle window ends.
 	 * The terminal reflowed the restored normal buffer during the drag, so
@@ -2083,6 +2285,23 @@ export class TUI extends Container {
 		let top: number;
 		if (isInsideTerminalMultiplexer()) {
 			if (reportedRow !== undefined) {
+				// tmux can grow its grid before SIGWINCH reaches the app. A queued
+				// retirement frame can then overwrite pulled-down history at the old
+				// coordinates and park the cursor there. If a previously full viewport
+				// no longer reaches the bottom, replay its semantic history instead of
+				// trusting that potentially damaged physical copy. Ordinary grows with
+				// an intact bottom anchor still need no replay or additional wait.
+				if (
+					this.#resizeScrollbackMode === "rebuild" &&
+					classifyTerminalMultiplexerModule()?.growsBeforeSigwinch === true &&
+					!this.#resizeRepaintsInPlace() &&
+					this.#frameProvider?.beginHistoryReplay &&
+					this.#resizeBurstGrew &&
+					this.#providerViewportTop + probe.window.length >= this.#previousHeight &&
+					reportedTop + staleRows < height
+				) {
+					this.#prepareForcedRender(true);
+				}
 				// The parked cursor's reply is exact under multiplexer clipping:
 				// discards leave the cursor in place, pushes only occur after
 				// everything below it is discarded (the bottom row IS the
@@ -2195,6 +2414,35 @@ export class TUI extends Container {
 		this.terminal.enableInput?.();
 		this.#querySixelSupport();
 		this.#queryCellSize();
+		// The probes went out over the painted frame; a terminal that could not
+		// parse one left its bytes on the cursor row (see Terminal.enableInput).
+		this.requestRender(true);
+	}
+
+	/**
+	 * Replay the keystrokes held since a TSP `deferInput` start through the
+	 * normal input path, then deliver input live. Call once the app's key
+	 * handlers are installed so a hotkey pressed during startup still fires.
+	 * Only keys typed while the start-time focus owner had focus are held. The
+	 * hold survives a stop/start until released. Idempotent; no-op when nothing
+	 * is held.
+	 */
+	releaseHeldInput(): void {
+		const held = this.#heldInput;
+		if (held === undefined) return;
+		this.#heldInput = undefined;
+		if (this.#stopped) return;
+		for (const data of held) this.#handleInput(data);
+	}
+
+	/**
+	 * Hand held-key ownership from `previous` to `next` when the app replaces
+	 * the component focused at start (a swapped-in custom editor), so keys
+	 * typed into the replacement stay queued behind the held ones instead of
+	 * overtaking them. No-op unless `previous` owns the held keys.
+	 */
+	replaceHeldFocus(previous: Component, next: Component): void {
+		if (this.#heldInput !== undefined && this.#heldFocus === previous) this.#heldFocus = next;
 	}
 
 	addStartListener(listener: StartListener): () => void {
@@ -2220,17 +2468,19 @@ export class TUI extends Container {
 		// PI_FORCE_IMAGE_PROTOCOL choice — including its `off` kill switch — wins
 		// over the probe.
 		if (TERMINAL.imageProtocol) return;
+		// A Tern surface (live, or about to open optimistically at start) sends
+		// images through TSP; this also keeps held startup input free of probe
+		// listeners.
+		if (this.#nativeLive || this.terminal.tspExpected) return;
 		if (isImageProtocolForced()) return;
 		if (!process.stdin.isTTY || !process.stdout.isTTY) return;
 
 		this.#clearSixelProbeState();
 		this.#sixelProbePendingGraphics = true;
 		this.#sixelProbeUnsubscribe = this.addInputListener(data => this.#handleSixelProbeInput(data));
-		// XTSMGRAPHICS item 2 reports the terminal's maximum SIXEL geometry. DA1
-		// attribute 4 advertises SIXEL as well, but ProcessTerminal swallows every
-		// `CSI ? … c` reply for the whole session so a late one cannot leak into the
-		// composer (#8542): those bytes never reach an input listener, so this probe
-		// cannot read them.
+		// XTSMGRAPHICS item 2 reports the maximum SIXEL geometry. DA1 attribute 4
+		// arrives through onSixelSupport instead: ProcessTerminal consumes the
+		// reply bytes so they cannot leak into application input.
 		this.terminal.write("\x1b[?2;1;0S");
 		this.#sixelProbeTimeout = setTimeout(() => {
 			this.#finishSixelProbe(false);
@@ -2314,7 +2564,11 @@ export class TUI extends Container {
 
 	#finishSixelProbe(supported: boolean): void {
 		this.#clearSixelProbeState();
-		if (!supported || TERMINAL.imageProtocol) return;
+		if (supported) this.#enableSixelProtocol();
+	}
+
+	#enableSixelProtocol(): void {
+		if (TERMINAL.imageProtocol) return;
 
 		setTerminalImageProtocol(ImageProtocol.Sixel);
 		this.#queryCellSize();
@@ -2408,7 +2662,7 @@ export class TUI extends Container {
 		this.#cancelResizeProbe();
 		if (this.#resizeAltActive) {
 			this.#resizeAltActive = false;
-			this.terminal.write(`${this.#keyboardEnhancementExit()}\x1b[?1049l`);
+			this.terminal.write(`${this.#takePendingAltEnter()}${this.#keyboardEnhancementExit()}\x1b[?1049l`);
 			setAltScreenActive(false);
 		}
 		if (this.#altActive || this.#pendingAltExit) {
@@ -2419,7 +2673,7 @@ export class TUI extends Container {
 			// so the final OFF goes last or the shell keeps reporting.
 			const mouseExit = this.#mouseTracking !== "off" ? MOUSE_TRACKING_OFF : "";
 			const exitSequence = this.#pendingAltExit
-				? `${this.#pendingAltExit}${mouseExit}`
+				? `${this.#takePendingAltEnter()}${this.#pendingAltExit}${mouseExit}`
 				: `${mouseExit}${this.#keyboardEnhancementExit()}\x1b[?1049l`;
 			this.terminal.write(exitSequence);
 			setAltScreenActive(false);
@@ -2428,6 +2682,7 @@ export class TUI extends Container {
 			this.#altPreviousLines = [];
 			this.#altPreparedRows = [];
 			this.#pendingAltExit = "";
+			this.#resizeAltExitFused = false;
 		} else if (this.#mouseTracking !== "off") {
 			// Inline capture with no overlay: still owned by us at quit, so
 			// release it — otherwise the parent shell keeps mouse reporting
@@ -2582,6 +2837,13 @@ export class TUI extends Container {
 		if (this.#renderTimer) {
 			this.#renderTimer.cancel();
 			this.#renderTimer = undefined;
+			// The cancelled timer was the only callback owed to a pending ordinary
+			// request. Every caller paints right after (a forced or ordinary request
+			// it issues, or the render already in progress), and that paint serves
+			// the request. Leaving the flag set would turn every later ordinary
+			// request into a no-op: the resize settle's rebuild and all spinner
+			// frames would never paint until some forced render arrived.
+			this.#renderRequested = false;
 		}
 	}
 
@@ -2683,7 +2945,10 @@ export class TUI extends Container {
 				const tagEpoch = this.#cprColumnTags.get(column);
 				this.#cprColumnTags.delete(column);
 				const probe = this.#resizeProbe;
-				if (probe !== undefined && tagEpoch === probe.epoch) {
+				// tmux can resize its grid before the application receives SIGWINCH.
+				// A reply below our known screen is from that newer geometry: do not
+				// repaint it using the stale height. Wait for resize or the probe retry.
+				if (probe !== undefined && tagEpoch === probe.epoch && row >= 1 && row <= this.terminal.rows) {
 					this.#resolveResizeAnchor(Number(match[1]) - 1);
 				}
 			}
@@ -2693,12 +2958,47 @@ export class TUI extends Container {
 			data = data.slice(0, searchFrom + match.index) + data.slice(searchFrom + match.index + match[0].length);
 		}
 		if (data.length === 0) return;
+
+		if (this.#heldInput !== undefined && this.#focusedComponent === this.#heldFocus) {
+			this.#holdInput(data);
+			return;
+		}
+
+		// If focused component is an overlay, verify it's still visible (visibility can change due to
+		// terminal resize or visible() callback). Runs before the capture preflight below, which must
+		// target the effective focus owner, not a hidden overlay.
+		const focusedOverlay = this.overlayStack.find(o => o.component === this.#focusedComponent);
+		if (focusedOverlay && !this.#isOverlayVisible(focusedOverlay)) {
+			// Focused overlay is no longer visible, redirect to topmost visible overlay
+			const topVisible = this.#getTopmostVisibleOverlay();
+			if (topVisible) {
+				this.setFocus(topVisible.component);
+			} else {
+				// No visible overlays, restore to preFocus
+				this.setFocus(focusedOverlay.preFocus);
+			}
+		}
+
 		// Ctrl+C/Esc use app-level double-press windows. Give those gestures one
 		// frame to drain queued input before an ordinary repaint; delaying every
 		// key would make idle navigation pay a full frame of latency.
 		if (matchesKey(data, "ctrl+c") || matchesKey(data, "escape")) {
 			this.#inputRenderGraceUntilMs = this.#renderScheduler.now() + TUI.#INPUT_RENDER_GRACE_MS;
 		}
+
+		// A focused input owner can reserve its gesture before TUI-wide listeners
+		// and debug shortcuts see the key, then handle the raw event exactly once.
+		const focusedForCapture = this.#focusedComponent;
+		if (
+			focusedForCapture?.handleInput &&
+			(!isKeyRelease(data) || focusedForCapture.wantsKeyRelease) &&
+			focusedForCapture.capturesInput?.(data)
+		) {
+			focusedForCapture.handleInput(data);
+			this.requestRender();
+			return;
+		}
+
 		if (this.#inputListeners.size > 0) {
 			let current = data;
 			for (const listener of this.#inputListeners) {
@@ -2727,20 +3027,6 @@ export class TUI extends Container {
 			return;
 		}
 
-		// If focused component is an overlay, verify it's still visible
-		// (visibility can change due to terminal resize or visible() callback)
-		const focusedOverlay = this.overlayStack.find(o => o.component === this.#focusedComponent);
-		if (focusedOverlay && !this.#isOverlayVisible(focusedOverlay)) {
-			// Focused overlay is no longer visible, redirect to topmost visible overlay
-			const topVisible = this.#getTopmostVisibleOverlay();
-			if (topVisible) {
-				this.setFocus(topVisible.component);
-			} else {
-				// No visible overlays, restore to preFocus
-				this.setFocus(focusedOverlay.preFocus);
-			}
-		}
-
 		// Pass input to focused component (including Ctrl+C).
 		// The focused component can decide how to handle Ctrl+C.
 		// Opted-in components only dirty their focused subtree. Unregistered
@@ -2757,6 +3043,18 @@ export class TUI extends Container {
 		}
 	}
 
+	/**
+	 * Queue a keystroke typed before the app installed its key handlers; input
+	 * listeners see it once, on replay. The cell-size reply is a terminal report,
+	 * consumed now. Ctrl+C/Ctrl+D release the queue so a stalled startup stays
+	 * interruptible.
+	 */
+	#holdInput(data: string): void {
+		if (this.#consumeCellSizeResponse(data)) return;
+		this.#heldInput!.push(data);
+		if (matchesKey(data, "ctrl+c") || matchesKey(data, "ctrl+d")) this.releaseHeldInput();
+	}
+
 	#consumeCellSizeResponse(data: string): boolean {
 		// Response format: ESC [ 6 ; height ; width t
 		const match = data.match(/^\x1b\[6;(\d+);(\d+)t$/);
@@ -2955,103 +3253,87 @@ export class TUI extends Container {
 				if (idx < 0 || idx >= result.length) continue;
 				const truncatedOverlayLine =
 					visibleWidth(overlayLines[i]) > width ? sliceByColumn(overlayLines[i], 0, width, true) : overlayLines[i];
-				result[idx] = this.#compositeLineAt(result[idx], truncatedOverlayLine, col, width, termWidth);
+				result[idx] = compositeLineAt(result[idx], truncatedOverlayLine, col, width, termWidth);
 			}
 		}
 		return result;
 	}
 
-	/** Splice overlay content into a base line at a specific column. Single-pass optimized. */
-	#compositeLineAt(
-		baseLine: string,
-		overlayLine: string,
-		startCol: number,
-		overlayWidth: number,
-		totalWidth: number,
+	/**
+	 * Remove placements before their viewport cells are replaced. History uses
+	 * separate placement ids, so deleting a live copy cannot erase scrollback.
+	 */
+	#retireImagePlacements(
+		placements: Map<number, LiveImagePlacement>,
+		lines: readonly string[],
+		top: number,
+		repaint: boolean,
 	): string {
-		if (TERMINAL.isImageLine(baseLine)) {
-			// Full-width overlays such as /switch are opaque: replace the
-			// Unicode placeholder cells so the image cannot cover the modal.
-			// Partial overlays cannot safely splice placement control sequences.
-			if (startCol !== 0 || overlayWidth < totalWidth) return baseLine;
-			const overlay = sliceWithWidth(overlayLine, 0, totalWidth, true);
-			return SEGMENT_RESET + overlay.text + " ".repeat(Math.max(0, totalWidth - overlay.width));
-		}
-
-		// Single pass through baseLine extracts both before and after segments
-		const afterStart = startCol + overlayWidth;
-		const base = extractSegments(baseLine, startCol, afterStart, totalWidth - afterStart, true);
-
-		// Extract overlay with width tracking (strict=true to exclude wide chars at boundary)
-		const overlay = sliceWithWidth(overlayLine, 0, overlayWidth, true);
-
-		// Pad segments to target widths
-		const beforePad = Math.max(0, startCol - base.beforeWidth);
-		const overlayPad = Math.max(0, overlayWidth - overlay.width);
-		const actualBeforeWidth = Math.max(startCol, base.beforeWidth);
-		const actualOverlayWidth = Math.max(overlayWidth, overlay.width);
-		const afterTarget = Math.max(0, totalWidth - actualBeforeWidth - actualOverlayWidth);
-		const afterPad = Math.max(0, afterTarget - base.afterWidth);
-
-		// Compose result
-		const r = SEGMENT_RESET;
-		const result =
-			base.before +
-			" ".repeat(beforePad) +
-			r +
-			overlay.text +
-			" ".repeat(overlayPad) +
-			r +
-			base.after +
-			" ".repeat(afterPad);
-
-		// CRITICAL: Always verify and truncate to terminal width.
-		// This is the final safeguard against width overflow which would crash the TUI.
-		// Width tracking can drift from actual visible width due to:
-		// - Complex ANSI/OSC sequences (hyperlinks, colors)
-		// - Wide characters at segment boundaries
-		// - Edge cases in segment extraction
-		const resultWidth = visibleWidth(result);
-		if (resultWidth <= totalWidth) {
-			return result;
-		}
-		// Truncate with strict=true to ensure we don't exceed totalWidth
-		return sliceByColumn(result, 0, totalWidth, true);
+		let output = "";
+		for (const [row, placement] of placements) {
+			if (!repaint && lines[row - top] === placement.line) continue;
+			output += encodeKittyDeletePlacement(placement.imageId, placement.placementId);
+			placements.delete(row);
+		}
+		return output;
 	}
 
-	/**
-	 * Rewrite a Kitty direct-placement line for the viewport row it is written
-	 * at, clipping to the visible slice (see {@link encodeKittyPlacementLine})
-	 * under the placement id resolved by the budget's epoch tracking (see
-	 * {@link ImageBudget.resolvePlacementEmit}). `screenRow` -1 (write position
-	 * unknown) and non-placement image lines (placeholder grids, sixel, iTerm2,
-	 * tmux-wrapped) pass through verbatim.
-	 */
-	#imageLineSequence(line: string, screenRow: number, frameRow: number, committedTo: number): string {
+	/** Clip a direct placement and record its live owner; history placements have no mutable owner. */
+	#imageLineSequence(
+		line: string,
+		screenRow: number,
+		placements: Map<number, LiveImagePlacement> | undefined,
+		placementRow: number,
+	): string {
 		if (screenRow < 0) return line;
 		const parsed = parseKittyDirectPlacementLine(line);
 		if (!parsed) return line;
-		// The emitted placement attaches from the block's first *visible* row
-		// (the clip drops the rows above the viewport), so epoch tracking keys
-		// on that row — not the block origin, which may be long committed.
-		const placement = this.#imageBudget.resolvePlacementEmit(
-			parsed.imageId,
-			frameRow >= 0 ? frameRow - Math.min(parsed.rows - 1, screenRow) : -1,
-			committedTo,
+		const previous = placements?.get(placementRow);
+		const placementId = previous?.placementId ?? this.#nextImagePlacementId++;
+		const erase = previous ? encodeKittyDeletePlacement(previous.imageId, previous.placementId) : "";
+		placements?.set(placementRow, { imageId: parsed.imageId, placementId, line });
+		return (
+			erase +
+			encodeKittyPlacementLine({
+				imageId: parsed.imageId,
+				placementId,
+				columns: parsed.columns,
+				rows: parsed.rows,
+				screenRow,
+				imageHeightPx: this.#imageBudget.getPlacementGeometry(parsed.imageId)?.heightPx ?? 0,
+			})
 		);
-		if (!placement) return line;
-		return encodeKittyPlacementLine({
-			imageId: parsed.imageId,
-			placementId: placement.placementId,
-			columns: parsed.columns,
-			rows: parsed.rows,
-			screenRow,
-			imageHeightPx: placement.heightPx,
-		});
 	}
 
 	#terminalLine(line: PreparedLine): string {
-		return line.terminalContent + (line.hasOsc8 ? LINE_TERMINATOR : SEGMENT_RESET);
+		if (line.hasOsc8) return line.terminalContent + LINE_TERMINATOR;
+		return line.terminalContent.endsWith(SEGMENT_RESET) ? line.terminalContent : line.terminalContent + SEGMENT_RESET;
+	}
+
+	/** Encode padding with REP, which tmux expands into identical styled cells. */
+	#compactReplaySpaces(line: string): string {
+		let copied = 0;
+		let output = "";
+		for (let offset = 0; offset < line.length;) {
+			const spaces = line.indexOf("        ", offset);
+			if (spaces === -1) break;
+			const escape = line.indexOf("\x1b", offset);
+			if (escape !== -1 && escape < spaces) {
+				// Only inspect text outside CSI/OSC. Unknown control strings (for
+				// example DCS payloads) must remain byte-for-byte unchanged.
+				const introducer = line.charCodeAt(escape + 1);
+				if (introducer !== 0x5b && introducer !== 0x5d) return line;
+				const end = this.#ansiSequenceEnd(line, escape);
+				if (end < 0) break;
+				offset = end;
+				continue;
+			}
+			let end = spaces + 8;
+			while (line.charCodeAt(end) === 0x20) end++;
+			output += `${line.slice(copied, spaces)} \x1b[${end - spaces - 1}b`;
+			copied = offset = end;
+		}
+		return copied === 0 ? line : output + line.slice(copied);
 	}
 
 	#notifyPaint(paint: TuiPaint): void {
@@ -3128,12 +3410,21 @@ export class TUI extends Container {
 	 * out of scrollback), so replaying would write an identical duplicate — the
 	 * editor/status chrome included — below the retained copy. Skip it, matching
 	 * the `widthChanged`-gated commit-ledger logic in {@link #doRender}.
+	 *
+	 * Both gates key on the whole coalesced burst, not the net change: the
+	 * terminal reflowed the normal buffer at every intermediate geometry, so a
+	 * drag that ends where it started (80 → 60 → 80) has still rewrapped
+	 * retained history and pushed unerased live rows into it. Comparing only
+	 * the settled size against the committed one would skip the refresh and
+	 * leave those stale copies stacked above the repainted viewport.
 	 */
 	#prepareResizeReplay(width: number, height: number): void {
 		const size = `${width}x${height}`;
+		const widthChanged = this.#resizeBurstWidthChanged || width !== this.#previousPhysicalWidth;
+		const resized = this.#resizeBurstResized || widthChanged || height !== this.#previousHeight;
 		if (
 			!this.#hasEverRendered ||
-			(this.#previousPhysicalWidth === width && this.#previousHeight === height) ||
+			!resized ||
 			this.#resizeReplaySize === size ||
 			this.#resizeScrollbackMode === "preserve" ||
 			// In-place resizes (Warp) repaint the settled viewport once the drag
@@ -3150,15 +3441,38 @@ export class TUI extends Container {
 			this.#forceViewportRepaintOnNextRender = true;
 			return;
 		}
+		// A height-only settled resize rewraps nothing — rewrap is a width change
+		// everywhere. A pure height grow pulls committed scrollback down without
+		// polluting a copy, so the rebuild (an ED3 plus a full ledger replay)
+		// would be a destructive repaint that buys nothing. `rebuild` still
+		// refreshes on a burst shrink (the multiplexer pushes live pane rows into its
+		// scrollback; the destructive refresh is the only purge) and on a host
+		// that repaints its own grid (ConPTY's stale re-emission is untrusted).
 		if (this.#resizeScrollbackMode === "rebuild") {
+			// Every destructive cause warrants a rebuild: a burst shrink can push
+			// live rows into history (tmux discards rows below the cursor, then
+			// pushes rows above it; a later grow cannot undo that clipping or the
+			// provider's retirement), and ConPTY can repaint its own stale grid.
+			if (!widthChanged && this.terminal.hostOwnsGridOnResize !== true && !this.#resizeBurstShrank) return;
 			this.#prepareForcedRender(true);
 			return;
 		}
-		if (width === this.#previousPhysicalWidth) return;
+		if (!widthChanged) return;
 		provider.beginHistoryReplay();
 		this.#forceViewportRepaintOnNextRender = true;
 	}
 
+	/**
+	 * Bottom-row `Rebuilding…` notice, closed as its own synchronized update so
+	 * tmux forwards it before the replay that follows starts a new hold. Cursor
+	 * save/restore and no newline keep the row out of native scrollback; the
+	 * replay's ED2 erases it together with the rest of the screen.
+	 */
+	#rebuildNoticeSequence(width: number, height: number): string {
+		const label = truncateToWidth("↻ Rebuilding…", width, Ellipsis.Omit);
+		return `${this.#paintBeginSequence}\x1b7\x1b[${height};1H${SEGMENT_RESET}${ERASE_LINE}${label}${LINE_TERMINATOR}\x1b8${this.#paintEndSequence}`;
+	}
+
 	/**
 	 * Erase `row` and everything below it, absolute-addressed, without ever
 	 * issuing a full-screen clear. tmux and Windows conhost (#9597) archive a
@@ -3250,6 +3564,7 @@ export class TUI extends Container {
 		// resize in rebuild mode): erase native history and the viewport,
 		// then repaint from row zero.
 		const destructiveReset = this.#clearScrollbackOnNextRender;
+		const compactReplay = destructiveReset && classifyTerminalMultiplexerModule()?.expandsRepPadding === true;
 		if (destructiveReset) {
 			this.#providerViewportTop = 0;
 			this.#providerWindow = [];
@@ -3259,11 +3574,40 @@ export class TUI extends Container {
 		// screen. Appending K history rows moves the anchor down by K; the write
 		// scrolls only when history + viewport overflow the physical screen, and
 		// the rows that scroll off the top are exactly the oldest history rows.
+		//
+		// A frame that transiently grew (an editor suggestion row) scrolls the same
+		// way — the extra rows must become visible — but its push was never
+		// committed by a history transaction, so the shrink when the transient
+		// chrome row leaves pulls those rows back and restores the pre-growth
+		// anchor instead of parking the frame one row high above a trailing blank.
+		// Frames carrying a history transaction, a reset, an overlay, or a new
+		// geometry commit or supersede the scroll and track nothing.
 		const geometryStable = this.#hasEverRendered && this.#previousWidth === width && this.#previousHeight === height;
 		const startTop = destructiveReset ? 0 : Math.min(this.#providerViewportTop, Math.max(0, height - 1));
-		const newTop = Math.max(0, Math.min(startTop + historyRows.length, height - rows));
+		const transientFrame =
+			history === undefined && !destructiveReset && geometryStable && this.#getTopmostVisibleOverlay() === undefined;
+		let anchorPull = 0;
+		if (transientFrame && rows < this.#previousFrameLength) {
+			anchorPull = Math.min(Math.max(0, height - rows - startTop), this.#transientScrollPushed);
+		}
+		const newTop = Math.max(0, Math.min(startTop + historyRows.length, height - rows)) + anchorPull;
 		const pendingAltExit = this.#pendingAltExit;
-		let buffer = this.#paintBeginSequence + pendingAltExit;
+		// A fused resize exit whose borrow never painted still owes its entry.
+		let buffer = this.#paintBeginSequence + (pendingAltExit ? this.#takePendingAltEnter() : "") + pendingAltExit;
+		const renewSync =
+			destructiveReset &&
+			this.#resizeScrollbackMode === "rebuild" &&
+			this.#synchronizedOutputEnabled &&
+			classifyTerminalMultiplexerModule()?.expiresSynchronizedOutput === true;
+		let syncBytes = Buffer.byteLength(buffer);
+		const append = (sequence: string): void => {
+			buffer += sequence;
+			if (!renewSync) return;
+			syncBytes += Buffer.byteLength(sequence);
+			if (syncBytes < SYNC_OUTPUT_RENEW_BYTES) return;
+			buffer += SYNC_OUTPUT_BEGIN;
+			syncBytes = 0;
+		};
 		if (destructiveReset && TERMINAL.imageProtocol === ImageProtocol.Kitty) {
 			// A reset is explicitly destructive, so remove every placement—not only
 			// the ones this TUI tracked—then resend images composed for the clean
@@ -3275,7 +3619,7 @@ export class TUI extends Container {
 			// reset forgot are named explicitly here — their tracking is gone, so
 			// nothing downstream could find them again.
 			for (const id of this.#imageBudget.takeResetPurgeIds()) buffer += encodeKittyDeleteImage(id);
-			this.#imageBudget.resetPlacementEpochs();
+			this.#screenImagePlacements.clear();
 		}
 		if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
 			for (const id of this.#imageBudget.takePurgeIds()) buffer += encodeKittyDeleteImage(id);
@@ -3297,15 +3641,17 @@ export class TUI extends Container {
 		// erase reclaim the data, so the replay's placements then referenced an
 		// image the terminal no longer had and every inline image vanished
 		// after a settled width resize.
-		if (destructiveReset) buffer += "\x1b[H\x1b[2J\x1b[3J";
-		for (const sequence of this.#imageBudget.takeTransmits()) buffer += sequence;
+		if (destructiveReset) buffer += `${LINE_TERMINATOR}\x1b[H\x1b[2J\x1b[3J`;
 		const diffable =
+			anchorPull === 0 &&
 			geometryStable &&
 			historyRows.length === 0 &&
 			startTop === newTop &&
 			!this.#forceViewportRepaintOnNextRender &&
 			!destructiveReset &&
 			this.#providerWindow.length > 0;
+		buffer += this.#retireImagePlacements(this.#screenImagePlacements, prepared.lines, newTop, !diffable);
+		for (const sequence of this.#imageBudget.takeTransmits()) append(sequence);
 		if (diffable) {
 			for (let index = 0; index < rows; index++) {
 				if (
@@ -3324,9 +3670,8 @@ export class TUI extends Container {
 					current,
 					width,
 					newTop + index,
-					-1,
-					-1,
 					this.#osc66SpacerGlyphWidth(prepared.lines, index),
+					{ imagePlacements: this.#screenImagePlacements },
 				)}`;
 			}
 			if (this.#providerWindow.length > rows && newTop + rows < height) {
@@ -3342,29 +3687,45 @@ export class TUI extends Container {
 			if (pushed > this.#providerViewportTop && this.#providerWindow.length > 0) {
 				buffer += this.#eraseBelowRow(this.#providerViewportTop, height);
 			}
-			buffer += `\x1b[${startTop + 1};1H`;
-			let screenRow = startTop;
+			// The un-committed push of a transiently grown frame, returned from
+			// scrollback: `CSI Ps + T` scrolls the grid down Ps rows filling the
+			// top from scrollback (kitty's SD extension; terminals without it
+			// ignore the sequence and keep today's shifted layout). The write
+			// below then lands on the restored anchor; its rows exactly fill the
+			// screen, so nothing scrolls further.
+			if (anchorPull > 0) buffer += `\x1b[${anchorPull}+T`;
+			// A history-carrying write starts at the anchor and lets any overflow
+			// scroll; a pulled write owns the whole restored region below it.
+			const writeTop = historyRows.length > 0 || anchorPull === 0 ? startTop : newTop;
+			buffer += `\x1b[${writeTop + 1};1H`;
+			let screenRow = writeTop;
 			for (let index = 0; index < preparedHistory.lines.length; index++) {
 				if (screenRow > startTop) buffer += "\n";
-				buffer += this.#lineRewriteSequence(
-					preparedHistory.rows[index]!,
-					width,
-					Math.min(screenRow, height - 1),
-					-1,
-					-1,
-					this.#osc66SpacerGlyphWidth(preparedHistory.lines, index),
+				append(
+					this.#lineRewriteSequence(
+						preparedHistory.rows[index]!,
+						width,
+						Math.min(screenRow, height - 1),
+						this.#osc66SpacerGlyphWidth(preparedHistory.lines, index),
+						{ blankRow: compactReplay },
+					),
 				);
 				screenRow++;
 			}
 			for (let index = 0; index < rows; index++) {
 				if (screenRow > startTop) buffer += "\n";
-				buffer += this.#lineRewriteSequence(
-					prepared.rows[index]!,
-					width,
-					Math.min(screenRow, height - 1),
-					-1,
-					-1,
-					this.#osc66SpacerGlyphWidth(prepared.lines, index),
+				append(
+					this.#lineRewriteSequence(
+						prepared.rows[index]!,
+						width,
+						Math.min(screenRow, height - 1),
+						this.#osc66SpacerGlyphWidth(prepared.lines, index),
+						{
+							blankRow: compactReplay,
+							imagePlacements: index < replayViewportRows ? undefined : this.#screenImagePlacements,
+							imageRow: newTop + index,
+						},
+					),
 				);
 				screenRow++;
 			}
@@ -3389,6 +3750,14 @@ export class TUI extends Container {
 			this.#parkedViewportOffset = 0;
 		}
 		buffer += this.#paintEndSequence;
+		if (
+			renewSync &&
+			pendingAltExit === "" &&
+			this.#resizeReplaySize !== undefined &&
+			Buffer.byteLength(buffer) >= TUI.#RESIZE_REBUILD_NOTICE_MIN_BYTES
+		) {
+			this.terminal.write(this.#rebuildNoticeSequence(width, height));
+		}
 		this.terminal.write(buffer);
 		this.#debugPaint = {
 			lines: prepared.lines,
@@ -3399,6 +3768,7 @@ export class TUI extends Container {
 		if (pendingAltExit) {
 			this.#noteAltBufferToggle();
 			this.#pendingAltExit = "";
+			this.#resizeAltExitFused = false;
 			setAltScreenActive(false);
 		}
 		if (target) this.#recordHardwareCursorState(target);
@@ -3406,12 +3776,28 @@ export class TUI extends Container {
 		this.#providerWindow = mutablePreparedLines;
 		this.#providerPreparedRows = mutablePreparedRows;
 		this.#providerViewportTop = mutableTop;
+		// Track the un-committed scroll of a transiently grown frame so the
+		// matching shrink can pull exactly those rows back. Every committing or
+		// superseding frame zeroes the debt: history appends and replays own
+		// their scrolls, a reset wipes the ledger, a new geometry reflows it,
+		// and an overlay frame paints against full-screen padding.
+		if (transientFrame) {
+			const scrolledOff = Math.max(0, startTop + rows - height);
+			this.#transientScrollPushed =
+				Math.min(this.#transientScrollPushed + scrolledOff, Math.max(0, height - 1)) - anchorPull;
+			if (this.#transientScrollPushed < 0) this.#transientScrollPushed = 0;
+		} else {
+			this.#transientScrollPushed = 0;
+		}
 		this.#providerViewportPadTop = replayViewportRows - replayPrependedBlanks;
 		this.#previousWidth = width;
 		this.#previousHeight = height;
 		this.#resizeBurstGrew = false;
+		this.#resizeBurstShrank = false;
 		this.#resizeBurstLastHeight = undefined;
 		this.#resizeBurstPull = 0;
+		this.#resizeBurstWidthChanged = false;
+		this.#resizeBurstResized = false;
 		this.#previousFrameLength = mutablePreparedLines.length;
 		this.#clearScrollbackOnNextRender = false;
 		this.#forceViewportRepaintOnNextRender = false;
@@ -3457,11 +3843,9 @@ export class TUI extends Container {
 			return;
 		}
 		if (this.#resizeInPlaceActive && !this.#altActive) {
-			// In-place resize settling (Warp): the normal-buffer anchor is stale until
-			// the settled CPR probe resolves. Painting now would overwrite retained
-			// history and record the new geometry over the pending recovery, so drop
-			// the frame — the resolve repaints. Fullscreen overlay paints are
-			// buffer-isolated and still allowed.
+			// The normal-buffer anchor is stale until the settled rebuild or CPR
+			// recovery. Painting now would overwrite history and record the new
+			// geometry over the pending recovery, so defer until the settle.
 			return;
 		}
 
@@ -3483,9 +3867,19 @@ export class TUI extends Container {
 			// modified-key reporting sequence on the freshly entered alternate
 			// screen, or Esc/modified keys revert to legacy encoding inside
 			// fullscreen overlays (Ghostty/kitty/iTerm2).
-			this.#noteAltBufferToggle();
-			this.#imageBudget.beginAltScreenLifecycle();
-			this.terminal.write(`\x1b[?1049h${this.#keyboardEnhancementEnter()}`);
+			if (this.#resizeAltExitFused) {
+				// An overlay opened while the settled resize rebuild was still
+				// pending: the terminal never left the borrowed buffer, which already
+				// carries the pushed keyboard mode and its image store, so the overlay
+				// takes it over. The latched rebuild then lands with the overlay's
+				// own fused exit when it closes.
+				this.#pendingAltExit = "";
+				this.#resizeAltExitFused = false;
+			} else {
+				this.#noteAltBufferToggle();
+				this.#imageBudget.beginAltScreenLifecycle();
+				this.terminal.write(`\x1b[?1049h${this.#keyboardEnhancementEnter()}`);
+			}
 			this.#setMouseTracking(wantMouse);
 			setAltScreenActive(true);
 			this.terminal.hideCursor();
@@ -3589,6 +3983,7 @@ export class TUI extends Container {
 		if (this.#maybeDeferGhosttyInitialImagePaint()) return;
 		this.#emitPlanFrame(width, height, viewport, undefined, undefined);
 		this.#paintGutter(width, rawWidth, height, viewport.length);
+		this.#previousPhysicalWidth = rawWidth;
 	}
 
 	/**
@@ -3965,9 +4360,8 @@ export class TUI extends Container {
 		line: PreparedLine,
 		width: number,
 		screenRow = -1,
-		frameRow = -1,
-		committedTo = -1,
 		spacerGlyphWidth = -1,
+		options?: { blankRow?: boolean; imagePlacements?: Map<number, LiveImagePlacement>; imageRow?: number },
 	): string {
 		// End every rewrite at column zero. ConPTY can materialize a pending
 		// wrap before a following cursor-addressing sequence even while DECAWM is
@@ -3984,10 +4378,19 @@ export class TUI extends Container {
 		if (spacerGlyphWidth >= 0) {
 			rewrite = spacerGlyphWidth >= width ? "" : `${SEGMENT_RESET}\x1b[${spacerGlyphWidth}C${ERASE_TO_END_OF_LINE}`;
 		} else if (line.isImage) {
-			rewrite = ERASE_LINE + this.#imageLineSequence(line.line, screenRow, frameRow, committedTo);
+			rewrite =
+				ERASE_LINE +
+				this.#imageLineSequence(line.line, screenRow, options?.imagePlacements, options?.imageRow ?? screenRow);
 		} else {
 			const terminalLine = this.#terminalLine(line);
-			if (line.asciiWidth !== undefined) {
+			if (options?.blankRow) {
+				// A destructive replay starts on a cleared screen and advances only
+				// into fresh rows. Each line resets its rendition before scrolling,
+				// so those rows already have the default background. Re-erasing every
+				// row only adds terminal parser work; images and OSC 66 spacers keep
+				// their dedicated cleanup above.
+				rewrite = this.#compactReplaySpaces(terminalLine);
+			} else if (line.asciiWidth !== undefined) {
 				// Exact width model: skip the erase only when the row truly fills
 				// the line (an EL there would eat the last cell via pending-wrap).
 				rewrite = line.asciiWidth >= width ? terminalLine : terminalLine + ERASE_TO_END_OF_LINE;
@@ -4052,9 +4455,9 @@ export class TUI extends Container {
 
 	/**
 	 * Compose and paint a single fullscreen overlay frame on the alt buffer.
-	 * Cursor markers are stripped (the modal draws its own in-band caret and
-	 * keeps the hardware cursor hidden), and only the modal is composited over a
-	 * blank base — the transcript is never touched while the alt buffer is up.
+	 * Cursor markers are stripped from the frame, but only a focused cursor-mode
+	 * component owned by the fullscreen overlay may position the hardware cursor.
+	 * The normal transcript is never composited into the alternate buffer.
 	 */
 	#renderAltFrame(width: number, height: number): void {
 		// oxlint-disable-next-line unicorn/no-new-array -- alt-frame length preallocation
@@ -4064,8 +4467,18 @@ export class TUI extends Container {
 			this.#imageBudget.beginPass(false, true);
 			lines = this.#compositeOverlaysIntoWindow(base, width, height);
 		} while (this.#imageBudget.endPass());
-		const prepared = this.#prepareLinesArray(lines, width, this.#altPreparedRows, height, []);
-		this.#emitAltFrame(prepared, width, height, true);
+		const markers: { row: number; col: number }[] = [];
+		const prepared = this.#prepareLinesArray(lines, width, this.#altPreparedRows, height, markers);
+		const topOverlay = this.#getTopmostVisibleOverlay();
+		const focused = this.#focusedComponent;
+		const acceptsTerminalCursor =
+			topOverlay !== undefined &&
+			focused !== null &&
+			isFocusable(focused) &&
+			focused.focused &&
+			typeof focused.setUseTerminalCursor === "function" &&
+			isOverlayFocusTarget(topOverlay.component, focused);
+		this.#emitAltFrame(prepared, width, height, true, acceptsTerminalCursor ? (markers[0] ?? null) : null);
 	}
 
 	/**
@@ -4073,9 +4486,15 @@ export class TUI extends Container {
 	 * previous frame, or every row when the height changed, a repaint is forced,
 	 * or a changed frame holds OSC 66 text before or after. Emits only
 	 * sync-output brackets, cursor moves, and per-row rewrites — never ED3 or
-	 * any native-scrollback byte. The hardware cursor stays hidden here.
+	 * any native-scrollback byte.
 	 */
-	#emitAltFrame(prepared: PreparedLines, width: number, height: number, notifyPaint: boolean): void {
+	#emitAltFrame(
+		prepared: PreparedLines,
+		width: number,
+		height: number,
+		notifyPaint: boolean,
+		cursorPosition: { row: number; col: number } | null = null,
+	): void {
 		// The pass that composed this frame ran with `altScreen`, so the normal
 		// screen's own placements behind it are not treated as retired.
 		this.#imageBudget.limitResidentImages();
@@ -4084,17 +4503,14 @@ export class TUI extends Container {
 		// frame resolve against loaded data. The normal-screen path flushes these
 		// ahead of its paint; without this, an image first shown inside a
 		// fullscreen overlay (e.g. the settings shape preview) would render as
-		// blank placeholder cells until the overlay closed.
+		// blank placeholder cells until the overlay closed. A pending resize-borrow
+		// entry leads: the image commands address the alternate buffer's store.
+		let prelude = this.#takePendingAltEnter();
 		const purgeIds = this.#imageBudget.takePurgeIds();
 		if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
-			for (const id of purgeIds) this.terminal.write(encodeKittyDeleteImage(id));
-		}
-		const imageTransmits = this.#imageBudget.takeTransmits();
-		if (imageTransmits.length > 0) {
-			let transmitBuffer = "";
-			for (const seq of imageTransmits) transmitBuffer += seq;
-			this.terminal.write(transmitBuffer);
+			for (const id of purgeIds) prelude += encodeKittyDeleteImage(id);
 		}
+		for (const seq of this.#imageBudget.takeTransmits()) prelude += seq;
 		// A forced repaint (resetDisplay, requestRender(true)) rewrites every row
 		// even when the cached frame is byte-identical: the redraw gesture must
 		// repair a corrupted modal. So does a changed frame with OSC 66 text in
@@ -4111,6 +4527,7 @@ export class TUI extends Container {
 				prepared.rows.some((_row, r) =>
 					this.#rowNeedsRewrite(this.#altPreviousLines, this.#altPreparedRows, prepared.lines, prepared.rows, r),
 				));
+		prelude += this.#retireImagePlacements(this.#altImagePlacements, prepared.lines, 0, full);
 		let rowsBuffer = "";
 		for (let r = 0; r < height; r++) {
 			if (full) {
@@ -4126,17 +4543,44 @@ export class TUI extends Container {
 				prepared.rows[r]!,
 				width,
 				r,
-				-1,
-				-1,
 				this.#osc66SpacerGlyphWidth(prepared.lines, r),
+				{ imagePlacements: this.#altImagePlacements },
 			);
 		}
 		this.#altPreviousLines = prepared.lines;
 		this.#altPreparedRows = prepared.rows;
-		if (rowsBuffer === "") return;
-		this.terminal.write(`${this.#paintBeginSequence}${full ? "\x1b[H" : ""}${rowsBuffer}${this.#paintEndSequence}`);
-		this.#debugPaint = { lines: prepared.lines, windowTop: 0, altScreen: true };
-		if (notifyPaint) {
+		const target = this.#targetHardwareCursorState(cursorPosition, height);
+		const previousCursor = this.#hardwareCursorState;
+		const cursorChanged =
+			target === null
+				? previousCursor?.visible === true
+				: previousCursor === null ||
+					previousCursor.row !== target.row ||
+					previousCursor.col !== target.col ||
+					previousCursor.visible !== target.visible;
+		const placeCursor = target !== null && (rowsBuffer !== "" || cursorChanged);
+		const hideCursor = target === null && previousCursor?.visible === true;
+		if (rowsBuffer === "" && !placeCursor && !hideCursor) {
+			if (prelude !== "") this.terminal.write(prelude);
+			return;
+		}
+
+		let cursorBuffer = "";
+		if (placeCursor && target !== null) {
+			cursorBuffer = `\x1b[${target.row + 1};${target.col + 1}H${target.visible ? "\x1b[?25h" : "\x1b[?25l"}`;
+		} else if (hideCursor) {
+			cursorBuffer = "\x1b[?25l";
+		}
+		this.terminal.write(
+			`${this.#paintBeginSequence}${prelude}${full ? "\x1b[H" : ""}${rowsBuffer}${cursorBuffer}${this.#paintEndSequence}`,
+		);
+		this.#debugPaint = {
+			lines: prepared.lines,
+			windowTop: 0,
+			altScreen: true,
+			...(target === null ? {} : { cursor: { x: target.col, y: target.row, visible: target.visible } }),
+		};
+		if (notifyPaint && rowsBuffer !== "") {
 			this.#notifyPaint({
 				history: [],
 				viewport: prepared.lines,
@@ -4146,6 +4590,11 @@ export class TUI extends Container {
 				rows: height,
 			});
 		}
-		if (full) this.#fullRedrawCount += 1;
+		if (full && rowsBuffer !== "") this.#fullRedrawCount += 1;
+		// DEC 1049 restores the normal-buffer cursor on exit. Track this buffer's
+		// visibility and marker position without replacing that saved normal row,
+		// which stop() and a late native-surface handshake use after the restore.
+		if (target) this.#hardwareCursorState = target;
+		else this.#recordHardwareCursorHidden();
 	}
 }