@gajae-code/tui 0.11.11 → 0.12.0

package/src/tui.ts

@@ -39,6 +39,8 @@ const SEGMENT_RESET = "\x1b[0m";
  */
 const LINE_TERMINATOR = "\x1b[0m\x1b]8;;\x07";
 const MOUSE_SELECTION_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/** Discrete mouse-wheel notch size in terminal rows (xterm/less-style). */
+export const DEFAULT_WHEEL_LINES = 3;
 
 function stripTerminalControls(text: string): string {
 	return Bun.stripANSI(text)
@@ -190,6 +192,11 @@ export interface ViewportAnchorSource {
 	id: ViewportAnchorId;
 }
 
+/** Identity and monotonic revision of the logical output producer. */
+export type ViewportOutputSource = {
+	identity: string;
+	revision: bigint;
+};
 export interface ViewportAnchorSourceRenderer extends Component {
 	renderWithViewportAnchorSource(width: number, source: ViewportAnchorSource): ViewportAnchorRender;
 }
@@ -623,6 +630,10 @@ type TuiRenderCounterSnapshot = {
 	debugRedrawAppendWrites: number;
 	differentialGuardVisibleWidthCalls: number;
 };
+type RenderCommitWaiter = {
+	resolve: (committed: boolean) => void;
+	timer: NodeJS.Timeout;
+};
 
 /**
  * TUI - Main class for managing terminal UI with differential rendering
@@ -651,7 +662,28 @@ export class TUI extends Container {
 	/** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
 	onDebug?: () => void;
 	#renderRequested = false;
+	#nextRenderGeneration = 0;
+	#renderRequestedGeneration = 0;
+	#committedRenderGeneration = 0;
+	#renderCommitWaiters = new Map<number, Set<RenderCommitWaiter>>();
+	#lastRenderWriteSucceeded = false;
 	#renderTimer: NodeJS.Timeout | undefined;
+	#widthSettleTimer: NodeJS.Timeout | undefined;
+	#widthSettleRepairPending = false;
+	#lastObservedWidth = 0;
+	// Trailing debounce for the settled width repair. Instance-local: taken from
+	// options.widthSettleMs when provided (deterministic harnesses pass 0 to
+	// disable), otherwise from GJC_TUI_WIDTH_SETTLE_MS / PI_TUI_WIDTH_SETTLE_MS,
+	// otherwise 1000. Sampled once at construction.
+	#widthSettleMs: number = TUI.#readWidthSettleMs();
+	static readonly #WIDTH_SETTLE_MS = 1000;
+
+	static #readWidthSettleMs(): number {
+		const raw = Bun.env.GJC_TUI_WIDTH_SETTLE_MS ?? Bun.env.PI_TUI_WIDTH_SETTLE_MS;
+		if (raw === undefined || raw === "") return TUI.#WIDTH_SETTLE_MS;
+		const parsed = Number.parseInt(raw, 10);
+		return Number.isFinite(parsed) && parsed >= 0 ? parsed : TUI.#WIDTH_SETTLE_MS;
+	}
 	#lastRenderAt = 0;
 	static readonly #MIN_RENDER_INTERVAL_MS = 16;
 	// Input-priority scheduling: an input keystroke must never be starved behind a
@@ -662,6 +694,9 @@ export class TUI extends Container {
 	#cursorRow = 0; // Logical cursor row (end of rendered content)
 	#hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
 	#viewportTopRow = 0; // Content row currently mapped to screen row 0
+	#scrollbackResumeViewportTop: number | undefined; // Reflowed history below this frontier is already committed
+	#nativeScrollbackViewportTop = 0;
+	#transcriptIdentityResetPending = false;
 	#manualViewportTop: number | undefined;
 	#viewportAnchorComponent: Component | null = null;
 	#viewportAnchorFrame: ViewportAnchorFrame | null = null;
@@ -694,6 +729,12 @@ export class TUI extends Container {
 	#mouseSelectionStart: MouseSelectionPoint | null = null;
 	#mouseSelectionEnd: MouseSelectionPoint | null = null;
 	#mouseSelectionDragged = false;
+	#viewportOutputSource: ViewportOutputSource | null = null;
+	#manualOutputNotice = false;
+	#manualTranscriptLineCount = 0;
+	#manualSuffixLineCount = 0;
+	#committedTranscriptRows: Array<number | null> = [];
+	#paintedManualOutputNotice = false;
 
 	#unsubscribeTabWidthChange?: () => void;
 	static #renderCounters: TuiRenderCounterSnapshot = {
@@ -746,6 +787,13 @@ export class TUI extends Container {
 		private readonly options: {
 			enableMouse?: boolean;
 			copySelection?: (text: string) => void | Promise<void>;
+			/**
+			 * Trailing debounce for the settled width repair, in ms. `0` disables the
+			 * settled repair (deterministic harnesses need this — a wall-clock-timed
+			 * full replay lands at nondeterministic logical positions). Defaults to
+			 * `GJC_TUI_WIDTH_SETTLE_MS` / `PI_TUI_WIDTH_SETTLE_MS`, then 1000.
+			 */
+			widthSettleMs?: number;
 		} = {},
 	) {
 		super();
@@ -753,6 +801,9 @@ export class TUI extends Container {
 		if (showHardwareCursor !== undefined) {
 			this.#showHardwareCursor = showHardwareCursor;
 		}
+		if (options.widthSettleMs !== undefined && Number.isFinite(options.widthSettleMs) && options.widthSettleMs >= 0) {
+			this.#widthSettleMs = options.widthSettleMs;
+		}
 		this.#imeCursorActive = !this.#showHardwareCursor && this.#useImeBlockCursor;
 		this.#unsubscribeTabWidthChange = onDefaultTabWidthChange(() => {
 			this.#lineTruncationCache.clear();
@@ -813,11 +864,58 @@ export class TUI extends Container {
 		}
 	}
 
+	override removeChild(component: Component): void {
+		this.#invalidateFocusForRemovedTree(component);
+		super.removeChild(component);
+	}
+
+	override clear(): void {
+		for (const child of this.children) this.#invalidateFocusForRemovedTree(child);
+		super.clear();
+	}
+
+	#invalidateFocusForRemovedTree(component: Component): void {
+		if (this.#focusedComponent !== null && this.#containsComponent(component, this.#focusedComponent)) {
+			this.setFocus(null);
+		}
+	}
+
+	#containsComponent(root: Component, target: Component): boolean {
+		if (root === target) return true;
+		return root instanceof Container && root.children.some(child => this.#containsComponent(child, target));
+	}
+
 	setBottomPinnedComponent(component: Component | null): void {
 		this.#bottomPinnedComponent = component;
 		this.requestRender();
 	}
 
+	/** Report the logical output producer revision without coupling TUI to message types. */
+	setViewportOutputSource(source: ViewportOutputSource | null): void {
+		const previous = this.#viewportOutputSource;
+		if (
+			(source === null && previous === null) ||
+			(source !== null &&
+				previous !== null &&
+				source.identity === previous.identity &&
+				source.revision === previous.revision)
+		) {
+			renderMetrics.recordStructuralCounter("viewportOutputSourceEqualNoops");
+			return;
+		}
+		const identityReset = source === null || previous === null || previous.identity !== source.identity;
+		// Same-identity revisions are a high-water mark. A delayed stale observation
+		// must not lower it, because observing that revision again would otherwise
+		// look like fresh output while the user owns the manual viewport.
+		if (!identityReset && source.revision < previous.revision) return;
+		if (!identityReset && source.revision > previous.revision && this.#manualViewportTop !== undefined) {
+			this.#manualOutputNotice = true;
+		}
+		if (identityReset || this.#manualViewportTop === undefined) this.#manualOutputNotice = false;
+		this.#viewportOutputSource = source;
+		this.requestRender();
+	}
+
 	/** Register the direct child whose rows are eligible for semantic viewport anchoring. */
 	setViewportAnchorComponent(component: Component | null): void {
 		if (component !== null && !isViewportAnchorProvider(component)) {
@@ -835,6 +933,21 @@ export class TUI extends Container {
 		this.#manualViewportFallbackAnchors = [];
 		this.#reconcileMissingViewportAnchor = false;
 		this.#viewportAnchorFrame = null;
+		this.#scrollbackResumeViewportTop = undefined;
+		this.#nativeScrollbackViewportTop = 0;
+		this.#transcriptIdentityResetPending = true;
+		this.#manualOutputNotice = false;
+		this.#paintedManualOutputNotice = false;
+		this.#committedTranscriptRows = [];
+		// The old transcript identity is being replaced wholesale, which supersedes
+		// any stale old-width artifact a deferred settle repair would have fixed.
+		// Cancel both the armed timer and a pending deferred repair so an unrelated
+		// later render cannot trigger an out-of-window full clear+replay.
+		if (this.#widthSettleTimer) {
+			clearTimeout(this.#widthSettleTimer);
+			this.#widthSettleTimer = undefined;
+		}
+		this.#widthSettleRepairPending = false;
 	}
 
 	/** Allow one semantic-neighbor reconciliation after a definitive same-transcript rebuild. */
@@ -847,22 +960,36 @@ export class TUI extends Container {
 		const height = this.terminal.rows;
 		const width = this.terminal.columns;
 		const frame = this.#viewportAnchorFrame;
-		if (height <= 0 || width <= 0 || this.#previousLines.length === 0 || frame === null) return false;
+		const transcriptCapacity = this.#manualTranscriptCapacity(height);
+		if (height <= 0 || width <= 0 || transcriptCapacity === 0 || this.#previousLines.length === 0 || frame === null)
+			return false;
 
-		const selectedRow = frame.anchors.findIndex(anchor => anchor?.id === id);
+		let selectedRow = frame.anchors.findIndex(anchor => anchor?.id === id);
+		if (alignment === "bottom") {
+			for (let row = frame.anchors.length - 1; row >= 0; row--) {
+				if (frame.anchors[row]?.id === id) {
+					selectedRow = row;
+					break;
+				}
+			}
+		}
 		const selected = selectedRow < 0 ? null : frame.anchors[selectedRow];
 		if (selected === null) return false;
 
-		const desiredScreenRow = alignment === "top" ? 0 : alignment === "center" ? Math.floor(height / 2) : height - 1;
+		const desiredScreenRow =
+			alignment === "top" ? 0 : alignment === "center" ? Math.floor(transcriptCapacity / 2) : transcriptCapacity - 1;
 		const targetViewportTop = Math.max(0, frame.startRow + selectedRow - desiredScreenRow);
 		this.#manualViewportAnchor = {
 			id: selected.id,
-			graphemeIndex: selected.graphemeStart,
-			cellOffset: selected.cellStart,
+			graphemeIndex:
+				alignment === "bottom"
+					? Math.max(selected.graphemeStart, selected.graphemeEnd - 1)
+					: selected.graphemeStart,
+			cellOffset: alignment === "bottom" ? Math.max(selected.cellStart, selected.cellEnd - 1) : selected.cellStart,
 			desiredScreenRow,
 		};
 		const firstCandidateRow = Math.max(0, targetViewportTop - frame.startRow);
-		const lastCandidateRow = Math.min(frame.anchors.length, targetViewportTop + height - frame.startRow);
+		const lastCandidateRow = Math.min(frame.anchors.length, targetViewportTop + transcriptCapacity - frame.startRow);
 		const fallbacks: ManualViewportAnchor[] = [];
 		for (let row = firstCandidateRow; row < lastCandidateRow; row++) {
 			const anchor = frame.anchors[row];
@@ -886,11 +1013,24 @@ export class TUI extends Container {
 		return true;
 	}
 
-	scrollViewportPages(direction: -1 | 1): boolean {
+	scrollViewportBy(
+		deltaRows: number,
+		options?: {
+			/** edge: PageUp/PageDown pin; stable: preserve/center pin for fine wheel motion */
+			pin?: "edge" | "stable";
+		},
+	): boolean {
 		const height = this.terminal.rows;
 		const width = this.terminal.columns;
 		if (height <= 0 || width <= 0 || this.#previousLines.length === 0) return false;
-		const maxViewportTop = Math.max(0, this.#previousLines.length - height);
+		if (!Number.isFinite(deltaRows)) return false;
+		const delta = Math.trunc(deltaRows);
+		if (delta === 0) return false;
+
+		const direction: -1 | 1 = delta < 0 ? -1 : 1;
+		const pin = options?.pin ?? "stable";
+		const transcriptCapacity = this.#manualTranscriptCapacity(height);
+		const maxViewportTop = Math.max(0, this.#manualTranscriptLineCount - transcriptCapacity);
 		let currentViewportTop = Math.max(0, Math.min(maxViewportTop, this.#manualViewportTop ?? this.#viewportTopRow));
 		const frame = this.#viewportAnchorFrame;
 		if (this.#manualViewportAnchor !== null) {
@@ -899,16 +1039,29 @@ export class TUI extends Container {
 			if (resolvedViewportTop === null) return false;
 			currentViewportTop = Math.max(0, Math.min(maxViewportTop, resolvedViewportTop));
 		}
-		const targetViewportTop = Math.max(
-			0,
-			Math.min(maxViewportTop, currentViewportTop + direction * Math.max(1, height - 1)),
-		);
+		const targetViewportTop = Math.max(0, Math.min(maxViewportTop, currentViewportTop + delta));
+		// Downward input at an already-live bottom is a no-op; it must not silently
+		// acquire manual ownership and freeze the next semantic output. Manual owners
+		// that reach the same boundary transition through the existing live transaction.
+		if (direction > 0 && targetViewportTop === maxViewportTop) {
+			if (this.#manualViewportTop === undefined && currentViewportTop === maxViewportTop) return true;
+			if (this.#manualViewportTop !== undefined) return this.followLiveViewport();
+		}
 		if (frame !== null) {
-			const desiredScreenRow = this.#manualViewportAnchor?.desiredScreenRow ?? (direction < 0 ? 0 : height - 1);
+			const desiredScreenRow =
+				this.#manualViewportAnchor?.desiredScreenRow ??
+				(pin === "edge"
+					? direction < 0
+						? 0
+						: Math.max(0, transcriptCapacity - 1)
+					: Math.floor(transcriptCapacity / 2));
 			const targetRow = targetViewportTop + desiredScreenRow - frame.startRow;
 			let selected: { row: number; anchor: ViewportAnchorRow } | undefined;
 			const firstCandidateRow = Math.max(0, targetViewportTop - frame.startRow);
-			const lastCandidateRow = Math.min(frame.anchors.length, targetViewportTop + height - frame.startRow);
+			const lastCandidateRow = Math.min(
+				frame.anchors.length,
+				targetViewportTop + transcriptCapacity - frame.startRow,
+			);
 			for (let row = firstCandidateRow; row < lastCandidateRow; row++) {
 				const anchor = frame.anchors[row];
 				if (anchor === null) continue;
@@ -974,26 +1127,63 @@ export class TUI extends Container {
 		);
 	}
 
+	scrollViewportPages(direction: -1 | 1): boolean {
+		const height = this.terminal.rows;
+		return this.scrollViewportBy(direction * Math.max(1, this.#manualTranscriptCapacity(height) - 1), {
+			pin: "edge",
+		});
+	}
+
 	followLiveViewport(): boolean {
 		if (this.#manualViewportTop === undefined) return false;
 		const height = this.terminal.rows;
 		const width = this.terminal.columns;
-		const liveLines = this.#latestRenderedLines;
+		const paddedLiveLines = this.#padBeforeBottomPinnedComponent(
+			this.#latestRenderedLines,
+			height,
+			this.#manualSuffixLineCount,
+		);
+		const liveLines = paddedLiveLines.lines;
+		let liveCursorPosition = this.#lastCursorPosition;
+		if (liveCursorPosition !== null && liveCursorPosition.row >= paddedLiveLines.insertionRow) {
+			liveCursorPosition = {
+				...liveCursorPosition,
+				row: liveCursorPosition.row + paddedLiveLines.insertedBlankRows,
+			};
+		}
 		const liveViewportTop = Math.max(0, liveLines.length - height);
-		this.#manualViewportTop = undefined;
-		this.#manualViewportAnchor = null;
-		this.#manualViewportFallbackAnchors = [];
-		this.#reconcileMissingViewportAnchor = false;
-		const repainted = this.#repaintViewportFromLines(
+		return this.#repaintViewportFromLines(
 			liveLines,
 			width,
 			height,
 			liveViewportTop,
-			this.#lastCursorPosition,
+			liveCursorPosition,
 			"manual viewport follow live",
+			false,
+			() => {
+				this.#manualViewportTop = undefined;
+				this.#manualViewportAnchor = null;
+				this.#manualViewportFallbackAnchors = [];
+				this.#reconcileMissingViewportAnchor = false;
+				this.#manualOutputNotice = false;
+				this.#committedTranscriptRows = [];
+				this.#paintedManualOutputNotice = false;
+				this.#lastCursorPosition = liveCursorPosition;
+				this.#previousLines = liveLines;
+				if (this.#scrollbackResumeViewportTop === undefined) {
+					this.#nativeScrollbackViewportTop = liveViewportTop;
+				}
+				// A settled width repair was deferred while the user was reading
+				// scrollback (repainting mid-read would have destroyed their
+				// position). The transactional live repaint above has committed, so
+				// manual state is safely released — now schedule the deferred full
+				// clear+replay that repairs old-width wrapping in history.
+				if (this.#widthSettleRepairPending) {
+					this.requestRender(true, "resize.width-settled.deferred");
+				}
+			},
+			true,
 		);
-		if (repainted) this.#previousLines = liveLines;
-		return repainted;
 	}
 
 	/**
@@ -1097,6 +1287,9 @@ export class TUI extends Container {
 	start(): void {
 		this.#stopped = false;
 		this.#terminalUnavailable = false;
+		// Seed the observed width so a spurious post-start resize event (iTerm2 tab
+		// activation, the self-sent SIGWINCH after resume) is not read as a reflow.
+		this.#lastObservedWidth = this.terminal.columns;
 		this.terminal.setMouseEnabled?.(this.options.enableMouse === true);
 		this.terminal.start(
 			data => this.#handleInput(data),
@@ -1112,6 +1305,57 @@ export class TUI extends Container {
 		this.requestRender(true);
 	}
 
+	/**
+	 * Wait for a specific render request generation to be written successfully.
+	 *
+	 * Render requests are coalesced, so committing a newer generation also commits
+	 * every older generation represented by that frame. A stopped or unavailable
+	 * terminal resolves waiters false so UI callers can fail open instead of
+	 * holding a session operation behind a dead renderer.
+	 */
+	waitForRenderCommit(generation: number, timeoutMs = 250): Promise<boolean> {
+		if (generation <= 0 || generation <= this.#committedRenderGeneration) return Promise.resolve(true);
+		if (this.#stopped || !this.terminalAvailable) return Promise.resolve(false);
+		return new Promise<boolean>(resolve => {
+			const waiter: RenderCommitWaiter = {
+				resolve,
+				timer: setTimeout(
+					() => {
+						const waiters = this.#renderCommitWaiters.get(generation);
+						if (waiters) {
+							waiters.delete(waiter);
+							if (waiters.size === 0) this.#renderCommitWaiters.delete(generation);
+						}
+						resolve(false);
+					},
+					Math.max(0, timeoutMs),
+				),
+			};
+			waiter.timer.unref?.();
+			const waiters = this.#renderCommitWaiters.get(generation) ?? new Set();
+			waiters.add(waiter);
+			this.#renderCommitWaiters.set(generation, waiters);
+		});
+	}
+
+	#settleRenderCommitWaiters(committed: boolean, generation = Number.POSITIVE_INFINITY): void {
+		if (committed) this.#committedRenderGeneration = Math.max(this.#committedRenderGeneration, generation);
+		for (const [waiterGeneration, waiters] of this.#renderCommitWaiters) {
+			if (committed && waiterGeneration > generation) continue;
+			this.#renderCommitWaiters.delete(waiterGeneration);
+			for (const waiter of waiters) {
+				clearTimeout(waiter.timer);
+				waiter.resolve(committed);
+			}
+		}
+	}
+
+	#commitRenderGeneration(generation: number): void {
+		if (generation <= 0) return;
+		if (this.#lastRenderWriteSucceeded) this.#settleRenderCommitWaiters(true, generation);
+		else if (this.#stopped || !this.terminalAvailable) this.#settleRenderCommitWaiters(false, generation);
+	}
+
 	get terminalAvailable(): boolean {
 		return !this.#terminalUnavailable && this.terminal.available;
 	}
@@ -1120,6 +1364,7 @@ export class TUI extends Container {
 		this.#terminalUnavailable = true;
 		this.#stopped = true;
 		this.#renderRequested = false;
+		this.#settleRenderCommitWaiters(false);
 		if (this.#renderTimer) {
 			clearTimeout(this.#renderTimer);
 			this.#renderTimer = undefined;
@@ -1318,11 +1563,25 @@ export class TUI extends Container {
 		this.flushTerminalCleanup();
 		this.#clearSixelProbeState();
 		this.#stopped = true;
+		this.#settleRenderCommitWaiters(false);
 		if (this.#renderTimer) {
 			clearTimeout(this.#renderTimer);
 			this.#renderTimer = undefined;
 			if (renderMetrics.enabled) renderMetrics.setTimerGauge("tui.renderTimer", 0);
 		}
+		if (this.#widthSettleTimer) {
+			clearTimeout(this.#widthSettleTimer);
+			this.#widthSettleTimer = undefined;
+		}
+		// An armed TIMER dies with the session, but an already-deferred repair
+		// (deadline passed while the user was reading scrollback) must survive a
+		// temporary stop/start (Ctrl-Z resume, external editor): manual viewport
+		// ownership survives restart, so followLiveViewport() still needs the flag
+		// to run the deferred repair. Without manual ownership the flag is moot —
+		// start() issues a forced full render that repairs everything anyway.
+		if (this.#manualViewportTop === undefined) {
+			this.#widthSettleRepairPending = false;
+		}
 		// Move cursor to the end of the content to prevent overwriting/artifacts on exit
 		if (this.#previousLines.length > 0) {
 			const targetRow = this.#previousLines.length; // Line after the last content
@@ -1383,19 +1642,81 @@ export class TUI extends Container {
 	 * is a no-op otherwise.
 	 */
 	requestResizeRender(): void {
-		const dimensionsChanged =
-			this.#previousWidth !== this.terminal.columns || this.#previousHeight !== this.terminal.rows;
-		this.requestRender(dimensionsChanged && !useViewportRepaintPath(this.terminal), "resize");
+		// Width is tracked against the last OBSERVED terminal width, not against
+		// #previousWidth (the last committed frame). Those diverge whenever resize
+		// events coalesce inside one frame budget: a 100->90->100 burst would leave
+		// #previousWidth at 100 the whole time, so a commit-keyed debounce would
+		// never see the second transition and could skip the only repair frame.
+		const observedWidth = this.terminal.columns;
+		const widthChanged = observedWidth !== this.#lastObservedWidth;
+		this.#lastObservedWidth = observedWidth;
+		const heightChanged = this.#previousHeight !== this.terminal.rows;
+		if (widthChanged) this.#scheduleWidthSettleRedraw();
+		this.requestRender(heightChanged && !useViewportRepaintPath(this.terminal), "resize");
+	}
+
+	/**
+	 * Width reflow leaves artifacts that the immediate resize frame does not always
+	 * repair: lines wrapped at the old column count can survive as stale bands — in
+	 * the live viewport and in scrollback history. The immediate frame is unchanged
+	 * by this timer — `#doRender` still promotes a real width change to
+	 * `fullRender`/`viewportRepaint` on the spot. What this adds is a single
+	 * trailing repair #WIDTH_SETTLE_MS after the last observed width change.
+	 *
+	 * The settled repair is a FULL transcript replay on every host, including
+	 * viewport-repaint hosts (tmux/screen/zellij, Windows Terminal, process
+	 * terminals) where per-SIGWINCH forced redraws are normally suppressed. That
+	 * per-event replay is the storm `resize-replay-storm.test.ts` pins against;
+	 * the debounce is what makes the full replay safe here — it happens once per
+	 * settled width sequence, so scrollback artifacts are repaired without
+	 * replaying the transcript on every resize event.
+	 *
+	 * Every observed width sequence gets exactly one repair, including one that
+	 * ends back at its starting width. Skipping the drag-and-return case would
+	 * require proving that a frame committed at the final geometry *after* the
+	 * final resize event, which the render pipeline does not guarantee; one extra
+	 * repaint is cheaper than a missed repair.
+	 *
+	 * Height-only changes are unaffected: they reflow nothing and keep their
+	 * existing behavior.
+	 */
+	#scheduleWidthSettleRedraw(): void {
+		if (this.#widthSettleMs <= 0) return;
+		if (this.#widthSettleTimer) clearTimeout(this.#widthSettleTimer);
+		this.#widthSettleTimer = setTimeout(() => {
+			this.#widthSettleTimer = undefined;
+			if (this.#stopped) return;
+			this.#widthSettleRepairPending = true;
+			// While the user is reading scrollback (manual viewport), a forced
+			// clear+replay would rip them out of history mid-read. Keep the flag
+			// armed instead; followLiveViewport() runs the deferred repair the
+			// moment they return to live.
+			if (this.#manualViewportTop !== undefined) return;
+			this.requestRender(true, "resize.width-settled");
+		}, this.#widthSettleMs);
+		this.#widthSettleTimer.unref?.();
 	}
 
 	requestRender(force = false, source = "unknown"): void {
+		this.requestRenderWithGeneration(force, source);
+	}
+
+	requestRenderWithGeneration(force = false, source = "unknown"): number {
+		const generation = ++this.#nextRenderGeneration;
+		this.#renderRequestedGeneration = Math.max(this.#renderRequestedGeneration, generation);
+		this.#requestRenderCore(force, source, generation);
+		return generation;
+	}
+
+	#requestRenderCore(force: boolean, source: string, generation: number): void {
 		if (!this.terminalAvailable) {
 			this.#markTerminalUnavailable();
 			return;
 		}
 		if (renderMetrics.enabled) renderMetrics.recordRequest(source);
 		if (force) {
-			const preserveViewportCursor = useViewportRepaintPath(this.terminal);
+			const preserveViewportCursor =
+				useViewportRepaintPath(this.terminal) || shouldPreserveScrollbackOnFullClear(this.terminal);
 			// A forced full redraw supersedes any queued input-priority render.
 			this.#inputRenderPending = false;
 			this.#previousLines = [];
@@ -1422,12 +1743,17 @@ export class TUI extends Container {
 			this.#renderRequested = true;
 			process.nextTick(() => {
 				if (this.#stopped || !this.#renderRequested) {
+					this.#settleRenderCommitWaiters(false, generation);
 					return;
 				}
+				const requestedGeneration = this.#renderRequestedGeneration;
+				this.#renderRequestedGeneration = 0;
 				this.#renderRequested = false;
 				this.#lastRenderAt = performance.now();
+				this.#lastRenderWriteSucceeded = false;
 				const t0 = renderMetrics.now();
 				this.#doRender();
+				this.#commitRenderGeneration(requestedGeneration);
 				if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
 			});
 			return;
@@ -1448,6 +1774,7 @@ export class TUI extends Container {
 		if (this.#renderRequested) return;
 		this.#renderRequested = true;
 		process.nextTick(() => this.#scheduleRender());
+		return;
 	}
 
 	#scheduleRender(): void {
@@ -1462,10 +1789,14 @@ export class TUI extends Container {
 			if (this.#stopped || !this.#renderRequested) {
 				return;
 			}
+			const requestedGeneration = this.#renderRequestedGeneration;
+			this.#renderRequestedGeneration = 0;
 			this.#renderRequested = false;
 			this.#lastRenderAt = performance.now();
+			this.#lastRenderWriteSucceeded = false;
 			const t0 = renderMetrics.now();
 			this.#doRender();
+			this.#commitRenderGeneration(requestedGeneration);
 			if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
 			if (this.#renderRequested) {
 				this.#scheduleRender();
@@ -1488,10 +1819,14 @@ export class TUI extends Container {
 			this.#renderTimer = undefined;
 			if (renderMetrics.enabled) renderMetrics.setTimerGauge("tui.renderTimer", 0);
 		}
+		const requestedGeneration = this.#renderRequestedGeneration;
+		this.#renderRequestedGeneration = 0;
 		this.#renderRequested = false;
 		this.#lastRenderAt = performance.now();
+		this.#lastRenderWriteSucceeded = false;
 		const t0 = renderMetrics.now();
 		this.#doRender();
+		this.#commitRenderGeneration(requestedGeneration);
 		if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
 	}
 
@@ -1519,7 +1854,7 @@ export class TUI extends Container {
 			if (mouse.x > this.terminal.columns || mouse.y > this.terminal.rows) return;
 			if (mouse.kind === "wheel") {
 				this.#clearMouseSelection();
-				this.scrollViewportPages(mouse.direction!);
+				this.scrollViewportBy(mouse.direction! * DEFAULT_WHEEL_LINES, { pin: "stable" });
 			} else if (mouse.kind === "click") {
 				this.#beginMouseSelection(mouse);
 				const focusedOverlay = this.overlayStack.find(o => o.component === this.#focusedComponent);
@@ -1595,16 +1930,23 @@ export class TUI extends Container {
 		}
 	}
 
-	#mouseSelectionPoint(mouse: MouseEvent): MouseSelectionPoint {
-		return {
-			line: this.#viewportTopRow + mouse.y - 1,
-			column: mouse.x - 1,
-		};
+	#mouseSelectionPoint(mouse: MouseEvent): MouseSelectionPoint | null {
+		if (this.#manualViewportTop === undefined) {
+			return { line: this.#viewportTopRow + mouse.y - 1, column: mouse.x - 1 };
+		}
+		const line = this.#committedTranscriptRows[mouse.y - 1];
+		return line === null || line === undefined || line < 0 || line >= this.#manualTranscriptLineCount
+			? null
+			: { line, column: mouse.x - 1 };
 	}
 
 	#beginMouseSelection(mouse: MouseEvent): void {
 		if (!this.options.copySelection) return;
 		const point = this.#mouseSelectionPoint(mouse);
+		if (point === null) {
+			this.#clearMouseSelection();
+			return;
+		}
 		this.#mouseSelectionStart = point;
 		this.#mouseSelectionEnd = point;
 		this.#mouseSelectionDragged = false;
@@ -1612,13 +1954,16 @@ export class TUI extends Container {
 
 	#updateMouseSelection(mouse: MouseEvent): void {
 		if (this.#mouseSelectionStart === null) return;
-		this.#mouseSelectionEnd = this.#mouseSelectionPoint(mouse);
+		const point = this.#mouseSelectionPoint(mouse);
+		if (point === null) return;
+		this.#mouseSelectionEnd = point;
 		this.#mouseSelectionDragged = true;
 	}
 
 	#finishMouseSelection(mouse: MouseEvent): void {
 		if (this.#mouseSelectionStart === null) return;
-		this.#mouseSelectionEnd = this.#mouseSelectionPoint(mouse);
+		const point = this.#mouseSelectionPoint(mouse);
+		if (point !== null) this.#mouseSelectionEnd = point;
 		if (!this.#mouseSelectionDragged || !this.options.copySelection) {
 			this.#clearMouseSelection();
 			return;
@@ -2150,33 +2495,108 @@ export class TUI extends Container {
 		return lines;
 	}
 
-	#padBeforeBottomPinnedComponent(
-		lines: string[],
-		height: number,
-		renderedChildren: Map<Component, string[]>,
-	): string[] {
-		const component = this.#bottomPinnedComponent;
-		if (component === null || lines.length >= height) return lines;
+	#pinnedChildLines(component: Component, renderedChildren: Map<Component, string[]>): string[] {
+		const lines = renderedChildren.get(component);
+		if (lines === undefined) throw new Error("Missing rendered direct child for pinned suffix");
+		return lines;
+	}
 
-		let pinnedStart = -1;
-		for (let i = this.children.length - 1; i >= 0; i--) {
-			if (this.children[i] === component) {
-				pinnedStart = i;
+	#constrainedPinnedChildLines(lines: string[], remaining: number): string[] {
+		let cursorLine = -1;
+		for (let index = 0; index < lines.length; index++) {
+			if (lines[index].includes(CURSOR_MARKER)) {
+				cursorLine = index;
 				break;
 			}
 		}
+		if (cursorLine < 0) return lines.slice(-remaining);
+		const start = Math.max(0, Math.min(cursorLine, lines.length - remaining));
+		return lines.slice(start, start + remaining);
+	}
+
+	#componentContains(root: Component, target: Component | null): boolean {
+		if (target === null) return false;
+		if (root === target) return true;
+		return root instanceof Container && root.children.some(child => this.#componentContains(child, target));
+	}
+
+	#constrainPinnedSuffix(lines: string[], height: number, renderedChildren: Map<Component, string[]>): string[] {
+		const component = this.#bottomPinnedComponent;
+		if (component === null || height <= 0) return lines;
+		const pinnedStart = this.children.indexOf(component);
 		if (pinnedStart < 0) return lines;
 
-		let pinnedLineCount = 0;
-		for (let i = pinnedStart; i < this.children.length; i++) {
-			pinnedLineCount += (renderedChildren.get(this.children[i]) ?? []).length;
+		let suffixRowCount = 0;
+		for (let index = pinnedStart; index < this.children.length; index++) {
+			suffixRowCount += this.#pinnedChildLines(this.children[index], renderedChildren).length;
+		}
+		if (suffixRowCount <= height) return lines;
+
+		renderMetrics.recordStructuralCounter("pinnedSuffixOverflowFrames");
+		let focusedChild: Component | null = null;
+		for (let index = pinnedStart; index < this.children.length; index++) {
+			const child = this.children[index];
+			if (this.#componentContains(child, this.#focusedComponent)) {
+				focusedChild = child;
+				break;
+			}
+		}
+		const selectedRowCounts = new Map<Component, number>();
+		let remaining = height;
+		const allocate = (child: Component, maximumRows?: number): void => {
+			if (remaining === 0) return;
+			const rows = this.#pinnedChildLines(child, renderedChildren);
+			const alreadySelected = selectedRowCounts.get(child) ?? 0;
+			const count = Math.min(rows.length - alreadySelected, maximumRows ?? rows.length, remaining);
+			if (count === 0) return;
+			selectedRowCounts.set(child, alreadySelected + count);
+			remaining -= count;
+		};
+
+		// Reserve the focused cursor row before the status boundary, then let later
+		// decorative children compete in reverse order. A deferred allocation lets the
+		// focused child retain adjacent rows only after those priorities are satisfied.
+		if (focusedChild !== null) allocate(focusedChild, 1);
+		if (component !== focusedChild) allocate(component);
+		for (let index = this.children.length - 1; index >= pinnedStart; index--) {
+			const child = this.children[index];
+			if (child !== focusedChild && child !== component) allocate(child);
+		}
+		if (focusedChild !== null) allocate(focusedChild);
+
+		const transcriptEnd = lines.length - suffixRowCount;
+		lines.length = transcriptEnd;
+		let selectedRows = 0;
+		for (let index = pinnedStart; index < this.children.length; index++) {
+			const child = this.children[index];
+			const count = selectedRowCounts.get(child);
+			if (count === undefined) continue;
+			const constrained = this.#constrainedPinnedChildLines(this.#pinnedChildLines(child, renderedChildren), count);
+			selectedRows += constrained.length;
+			for (const row of constrained) lines.push(row);
+		}
+		renderMetrics.recordStructuralCounter("pinnedSuffixSelectedRows", selectedRows);
+		return lines;
+	}
+
+	#padBeforeBottomPinnedComponent(
+		lines: string[],
+		height: number,
+		pinnedLineCount: number,
+	): { lines: string[]; insertionRow: number; insertedBlankRows: number } {
+		if (pinnedLineCount <= 0 || lines.length >= height) {
+			return { lines, insertionRow: lines.length, insertedBlankRows: 0 };
 		}
 
-		const blankRows = height - lines.length;
-		const insertAt = Math.max(0, lines.length - pinnedLineCount);
+		const insertedBlankRows = height - lines.length;
+		const insertionRow = Math.max(0, lines.length - pinnedLineCount);
 		const padded = [...lines];
-		padded.splice(insertAt, 0, ...Array.from({ length: blankRows }, () => ""));
-		return padded;
+		padded.splice(insertionRow, 0, ...Array.from({ length: insertedBlankRows }, () => ""));
+		return { lines: padded, insertionRow, insertedBlankRows };
+	}
+	#manualTranscriptCapacity(height: number): number {
+		const noticeRows = this.#manualOutputNotice && height > this.#manualSuffixLineCount ? 1 : 0;
+		return Math.max(0, height - this.#manualSuffixLineCount - noticeRows);
 	}
 	#resolveManualAnchor(frame: ViewportAnchorFrame): number | null {
 		const anchor = this.#manualViewportAnchor;
@@ -2235,9 +2655,19 @@ export class TUI extends Container {
 		cursorPos: { row: number; col: number } | null,
 		reason: string,
 		allowPastLiveBottom = false,
+		onPainted?: () => void,
+		paintLive = false,
 	): boolean {
+		const paintManual = this.#manualViewportTop !== undefined && !paintLive;
 		if (height <= 0 || width <= 0) return false;
-		const maxViewportTop = Math.max(0, lines.length - (allowPastLiveBottom ? 1 : height));
+		const maxViewportTop = Math.max(
+			0,
+			!paintManual
+				? lines.length - (allowPastLiveBottom ? 1 : height)
+				: allowPastLiveBottom
+					? lines.length - 1
+					: this.#manualTranscriptLineCount - this.#manualTranscriptCapacity(height),
+		);
 		const nextViewportTop = Math.max(0, Math.min(maxViewportTop, viewportTop));
 		const currentScreenRow = Math.max(0, Math.min(height - 1, this.#hardwareCursorRow - this.#viewportTopRow));
 		let buffer = "\x1b[?2026h";
@@ -2246,12 +2676,25 @@ export class TUI extends Container {
 		}
 		buffer += "\r";
 
+		const transcriptCapacity = paintManual ? this.#manualTranscriptCapacity(height) : height;
+		const noticeRows = paintManual && this.#manualOutputNotice && height > this.#manualSuffixLineCount ? 1 : 0;
+		const committedTranscriptRows: Array<number | null> = [];
 		for (let screenRow = 0; screenRow < height; screenRow++) {
 			if (screenRow > 0) buffer += "\r\n";
 			buffer += "\x1b[2K";
 			const lineIndex = nextViewportTop + screenRow;
-			if (lineIndex >= lines.length) continue;
-			const line = lines[lineIndex];
+			const suffixRow = screenRow - transcriptCapacity - noticeRows;
+			const line =
+				paintManual && screenRow === transcriptCapacity && noticeRows > 0
+					? "New output — type to follow"
+					: paintManual && suffixRow >= 0
+						? (lines[this.#manualTranscriptLineCount + suffixRow] ?? "")
+						: paintManual && lineIndex >= this.#manualTranscriptLineCount
+							? ""
+							: (lines[lineIndex] ?? "");
+			committedTranscriptRows.push(
+				screenRow < transcriptCapacity && lineIndex < this.#manualTranscriptLineCount ? lineIndex : null,
+			);
 			const isImage = TERMINAL.isImageLine(line);
 			if (!isImage && this.#visibleWidthForDifferentialGuard(line) > width) {
 				let truncatedLine = truncateToWidth(line, width, Ellipsis.Omit);
@@ -2270,19 +2713,24 @@ export class TUI extends Container {
 			cursorSeq = cursor.seq;
 			cursorToRow = cursor.toRow;
 		}
-		this.#hardwareCursorRow = cursorToRow;
 		buffer += cursorSeq;
 		buffer += "\x1b[?2026l";
-		if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, lines.length)) return false;
+		if (
+			!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, lines.length, () => {
+				this.#hardwareCursorRow = cursorToRow;
+				this.#committedTranscriptRows = committedTranscriptRows;
+				this.#cursorRow = Math.max(0, lines.length - 1);
+				this.#maxLinesRendered = lines.length;
+				this.#viewportTopRow = nextViewportTop;
+				onPainted?.();
+			})
+		)
+			return false;
 
 		if (this.#debugRedraw) {
 			const msg = `[${new Date().toISOString()}] viewportRepaint: ${reason} (lines=${lines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
 			this.#appendDebugRedrawLog(msg);
 		}
-
-		this.#cursorRow = Math.max(0, lines.length - 1);
-		this.#maxLinesRendered = lines.length;
-		this.#viewportTopRow = nextViewportTop;
 		return true;
 	}
 
@@ -2313,13 +2761,30 @@ export class TUI extends Container {
 			}
 			for (const line of rendered.lines) renderedLines.push(line);
 		}
+		let pinnedChildIndex = -1;
+		for (let index = 0; index < this.children.length; index++) {
+			if (this.children[index] === this.#bottomPinnedComponent) {
+				pinnedChildIndex = index;
+				break;
+			}
+		}
+		const hasStickySuffix = pinnedChildIndex >= 0;
+		const sourceTranscriptLineCount = hasStickySuffix
+			? this.children
+					.slice(0, pinnedChildIndex)
+					.reduce((count, child) => count + this.#pinnedChildLines(child, renderedChildren).length, 0)
+			: renderedLines.length;
 		const anchorRenderFailed = viewportAnchorRenderFailureCount !== anchorRenderFailureCountBefore;
-		let newLines = renderedLines;
+		let newLines = this.#constrainPinnedSuffix(renderedLines, height, renderedChildren);
 		this.#viewportAnchorFrame = anchorFrame;
 		if (renderMetrics.enabled) renderMetrics.recordHelper("renderTree", renderMetrics.now() - renderTreeStart);
 
-		if (this.#bottomPinnedComponent !== null && height > 0) {
-			newLines = this.#padBeforeBottomPinnedComponent(newLines, height, renderedChildren);
+		if (hasStickySuffix && height > 0 && this.#manualViewportTop === undefined) {
+			newLines = this.#padBeforeBottomPinnedComponent(
+				newLines,
+				height,
+				newLines.length - sourceTranscriptLineCount,
+			).lines;
 		}
 
 		// Composite overlays into the rendered lines (before differential compare)
@@ -2341,9 +2806,9 @@ export class TUI extends Container {
 		const widthChanged = this.#previousWidth !== 0 && this.#previousWidth !== width;
 		const heightChanged = this.#previousHeight !== 0 && this.#previousHeight !== height;
 
-		// Normalize/truncate lines for emission. With the opt-in virtual-viewport flag
-		// (PI_TUI_VIRTUAL_VIEWPORT) we reuse the previous frame's normalized prefix when the
-		// off-screen raw prefix is unchanged (raw value equality per line; fast reference
+		// Normalize/truncate lines for emission. The virtual viewport is default-on;
+		// PI_TUI_VIRTUAL_VIEWPORT=0 opts out. When enabled, reuse the previous frame's
+		// normalized prefix when the off-screen raw prefix is unchanged (raw value equality
 		// short-circuit for cached components), so only the visible window is
 		// re-normalized and the diff starts at the window. Output is byte-identical to the
 		// full path (reused entries are deterministic normalizations of identical raw lines).
@@ -2393,6 +2858,21 @@ export class TUI extends Container {
 			if (usedWindowNormalize) renderMetrics.recordLineCount("offscreenScan", diffStart);
 		}
 		this.#latestRenderedLines = newLines;
+		this.#manualTranscriptLineCount = sourceTranscriptLineCount;
+		this.#manualSuffixLineCount = Math.max(0, newLines.length - sourceTranscriptLineCount);
+		const naturalViewportTop = Math.max(0, newLines.length - height);
+		const priorLogicalLineCount = Math.max(this.#previousLines.length, this.#maxLinesRendered);
+		if (this.#transcriptIdentityResetPending) {
+			this.#transcriptIdentityResetPending = false;
+		} else if (
+			newLines.length < priorLogicalLineCount &&
+			(naturalViewportTop < prevViewportTop || this.#manualViewportTop !== undefined)
+		) {
+			this.#scrollbackResumeViewportTop = Math.max(
+				this.#scrollbackResumeViewportTop ?? 0,
+				this.#nativeScrollbackViewportTop,
+			);
+		}
 
 		if (this.#manualViewportTop !== undefined) {
 			let resolvedAnchorTop = anchorFrame === null ? null : this.#resolveManualAnchor(anchorFrame);
@@ -2448,6 +2928,7 @@ export class TUI extends Container {
 				this.#previousWidth === width &&
 				this.#previousHeight === height &&
 				nextViewportTop === this.#manualViewportTop &&
+				this.#manualOutputNotice === this.#paintedManualOutputNotice &&
 				newLines.length === this.#previousLines.length &&
 				newLines.every((line, index) => line === this.#previousLines[index])
 			) {
@@ -2469,46 +2950,69 @@ export class TUI extends Container {
 				this.#previousLines = newLines;
 				this.#previousWidth = width;
 				this.#previousHeight = height;
+				this.#paintedManualOutputNotice = this.#manualOutputNotice;
 			}
 			return;
 		}
 		// Helper to clear scrollback and viewport and render all new lines
-		const fullRender = (clear: boolean, reason = "full render"): void => {
+		let viewportRepaint: (reason: string, targetViewportTop?: number) => void;
+		const fullRender = (clear: boolean, reason = "full render", forceScrollbackClear = false): void => {
+			if (
+				clear &&
+				!forceScrollbackClear &&
+				shouldPreserveScrollbackOnFullClear(this.terminal) &&
+				this.#scrollbackResumeViewportTop !== undefined
+			) {
+				viewportRepaint(`preserving full replay blocked after scrollback-unsafe contraction: ${reason}`);
+				return;
+			}
 			this.#fullRedrawCount += 1;
 			if (renderMetrics.enabled) renderMetrics.recordFullRedraw(reason);
 			let buffer = "\x1b[?2026h"; // Begin synchronized output
 			// Skip clearing scrollback (3J) in hosts where clear/replay can snap the
-			// native viewport away from the live prompt (tmux/screen, Windows ConPTY).
+			// native viewport away from the live prompt (tmux/screen, Windows ConPTY) —
+			// unless the caller explicitly needs history erased (the settled width
+			// repair, where a replay WITHOUT 3J would stack the new transcript on top
+			// of the stale-width copy instead of replacing it).
 			if (clear)
-				buffer += shouldPreserveScrollbackOnFullClear(this.terminal) ? "\x1b[2J\x1b[H" : "\x1b[2J\x1b[H\x1b[3J";
+				buffer +=
+					!forceScrollbackClear && shouldPreserveScrollbackOnFullClear(this.terminal)
+						? "\x1b[2J\x1b[H"
+						: "\x1b[2J\x1b[H\x1b[3J";
 			for (let i = 0; i < newLines.length; i++) {
 				if (i > 0) buffer += "\r\n";
 				// Lines were pre-terminated/normalized by #applyLineResets; image
 				// lines were left untouched there.
 				buffer += newLines[i];
 			}
-			this.#cursorRow = Math.max(0, newLines.length - 1);
-			const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, this.#cursorRow);
-			this.#hardwareCursorRow = toRow;
+			const cursorRow = Math.max(0, newLines.length - 1);
+			const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, cursorRow);
 			buffer += seq;
 			buffer += "\x1b[?2026l"; // End synchronized output
-			if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length)) return;
-			// Reset max lines when clearing, otherwise track growth
-			if (clear) {
-				this.#maxLinesRendered = newLines.length;
-			} else {
-				this.#maxLinesRendered = Math.max(this.#maxLinesRendered, newLines.length);
-			}
-			this.#viewportTopRow = Math.max(0, this.#maxLinesRendered - height);
-			this.#previousLines = newLines;
-			this.#previousWidth = width;
-			this.#previousHeight = height;
+			if (
+				!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length, () => {
+					this.#cursorRow = cursorRow;
+					this.#hardwareCursorRow = toRow;
+					this.#maxLinesRendered = clear ? newLines.length : Math.max(this.#maxLinesRendered, newLines.length);
+					this.#viewportTopRow = Math.max(0, this.#maxLinesRendered - height);
+					this.#nativeScrollbackViewportTop = clear
+						? this.#viewportTopRow
+						: Math.max(this.#nativeScrollbackViewportTop, this.#viewportTopRow);
+					if (clear && (forceScrollbackClear || !shouldPreserveScrollbackOnFullClear(this.terminal))) {
+						this.#scrollbackResumeViewportTop = undefined;
+					}
+					this.#previousLines = newLines;
+					this.#previousWidth = width;
+					this.#previousHeight = height;
+				})
+			)
+				return;
 		};
 
-		const viewportRepaint = (reason: string): void => {
+		viewportRepaint = (reason: string, targetViewportTop = Math.max(0, newLines.length - height)): void => {
 			this.#fullRedrawCount += 1;
 			if (renderMetrics.enabled) renderMetrics.recordFullRedraw(reason);
-			const nextViewportTop = Math.max(0, newLines.length - height);
+			const nextViewportTop = targetViewportTop;
 			const currentScreenRow = Math.max(0, Math.min(height - 1, hardwareCursorRow - prevViewportTop));
 			let buffer = "\x1b[?2026h";
 			if (currentScreenRow > 0) {
@@ -2539,25 +3043,25 @@ export class TUI extends Container {
 				cursorSeq = cursor.seq;
 				cursorToRow = cursor.toRow;
 			}
-			this.#hardwareCursorRow = cursorToRow;
 			buffer += cursorSeq;
 			buffer += "\x1b[?2026l";
-			if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length)) return;
+			if (
+				!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length, () => {
+					this.#hardwareCursorRow = cursorToRow;
+					this.#cursorRow = Math.max(0, newLines.length - 1);
+					this.#maxLinesRendered = newLines.length;
+					this.#viewportTopRow = nextViewportTop;
+					this.#previousLines = newLines;
+					this.#previousWidth = width;
+					this.#previousHeight = height;
+				})
+			)
+				return;
 
 			if (this.#debugRedraw) {
 				const msg = `[${new Date().toISOString()}] viewportRepaint: ${reason} (prev=${this.#previousLines.length}, new=${newLines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
 				this.#appendDebugRedrawLog(msg);
 			}
-			// Viewport repaint deliberately prioritizes the live viewport over
-			// historical scrollback repair. After offscreen changes, #previousLines
-			// tracks the desired logical transcript, not every byte emitted into the
-			// terminal scrollback.
-			this.#cursorRow = Math.max(0, newLines.length - 1);
-			this.#maxLinesRendered = newLines.length;
-			this.#viewportTopRow = nextViewportTop;
-			this.#previousLines = newLines;
-			this.#previousWidth = width;
-			this.#previousHeight = height;
 		};
 
 		const debugRedraw = this.#debugRedraw;
@@ -2576,14 +3080,26 @@ export class TUI extends Container {
 
 		// Width changes always need a full re-render because wrapping changes.
 		if (widthChanged) {
-			logRedraw(`terminal width changed (${this.#previousWidth} -> ${width})`);
-			if (useViewportRepaintPath(this.terminal)) {
-				// In viewport-repaint sessions a full replay can either pile the transcript
-				// back onto scrollback (tmux/screen) or visibly jump to the transcript top
-				// (Windows Terminal). Repaint the viewport only, mirroring the height-change
-				// branch and neutralizing fake width changes from requestRender(true).
+			if (this.#widthSettleRepairPending) {
+				logRedraw(`width settled (${this.#previousWidth} -> ${width})`);
+				// The one debounced post-resize repair: a full clear+replay so stale
+				// old-width wrapping is repaired in scrollback history too, not just
+				// the live viewport. forceScrollbackClear erases the stale-width
+				// history instead of stacking the replay on top of it. Safe against
+				// the replay storm because it runs once per settled width sequence,
+				// never once per SIGWINCH.
+				this.#widthSettleRepairPending = false;
+				fullRender(true, "width settled", true);
+			} else if (useViewportRepaintPath(this.terminal)) {
+				logRedraw(`terminal width changed (${this.#previousWidth} -> ${width})`);
+				// In viewport-repaint sessions a per-event full replay can either pile
+				// the transcript back onto scrollback (tmux/screen) or visibly jump to
+				// the transcript top (Windows Terminal). Repaint the viewport only,
+				// mirroring the height-change branch and neutralizing fake width
+				// changes from requestRender(true).
 				viewportRepaint(`terminal width changed (${this.#previousWidth} -> ${width})`);
 			} else {
+				logRedraw(`terminal width changed (${this.#previousWidth} -> ${width})`);
 				fullRender(true, "terminal width changed");
 			}
 			return;
@@ -2644,7 +3160,7 @@ export class TUI extends Container {
 			}
 			lastChanged = newLines.length - 1;
 		}
-		const appendStart = appendedLines && firstChanged === this.#previousLines.length && firstChanged > 0;
+		let appendStart = appendedLines && firstChanged === this.#previousLines.length && firstChanged > 0;
 
 		// No changes - but still need to update hardware cursor position if it moved
 		if (firstChanged === -1) {
@@ -2658,6 +3174,32 @@ export class TUI extends Container {
 			viewportRepaint(`content contraction changed viewport top (${prevViewportTop} -> ${nextLiveViewportTop})`);
 			return;
 		}
+		if (appendedLines && this.#scrollbackResumeViewportTop !== undefined && nextLiveViewportTop > prevViewportTop) {
+			const resumeViewportTop = this.#scrollbackResumeViewportTop;
+			if (nextLiveViewportTop <= resumeViewportTop) {
+				viewportRepaint(
+					`content expansion below committed scrollback frontier (${prevViewportTop} -> ${nextLiveViewportTop}, frontier=${resumeViewportTop})`,
+				);
+				return;
+			}
+
+			const previousLines = this.#previousLines;
+			const previousWidth = this.#previousWidth;
+			const previousHeight = this.#previousHeight;
+			viewportRepaint(
+				`staging committed scrollback frontier before resumed admission (${prevViewportTop} -> ${resumeViewportTop} -> ${nextLiveViewportTop})`,
+				resumeViewportTop,
+			);
+			this.#previousLines = previousLines;
+			this.#previousWidth = previousWidth;
+			this.#previousHeight = previousHeight;
+			prevViewportTop = resumeViewportTop;
+			viewportTop = resumeViewportTop;
+			hardwareCursorRow = this.#hardwareCursorRow;
+			firstChanged = resumeViewportTop;
+			appendStart = false;
+			this.#scrollbackResumeViewportTop = undefined;
+		}
 		// All changes are in deleted lines (nothing to render, just clear)
 		if (firstChanged >= newLines.length) {
 			if (this.#previousLines.length > newLines.length) {
@@ -2691,12 +3233,21 @@ export class TUI extends Container {
 				if (moveUp > 0) {
 					buffer += `\x1b[${moveUp}A`;
 				}
-				this.#cursorRow = targetRow;
 				const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, targetRow);
-				this.#hardwareCursorRow = toRow;
 				buffer += seq;
 				buffer += "\x1b[?2026l";
-				if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length)) return;
+				if (
+					!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length, () => {
+						this.#cursorRow = targetRow;
+						this.#hardwareCursorRow = toRow;
+						this.#previousLines = newLines;
+						this.#previousWidth = width;
+						this.#previousHeight = height;
+						this.#maxLinesRendered = newLines.length;
+						this.#viewportTopRow = Math.max(0, newLines.length - height);
+					})
+				)
+					return;
 			}
 			this.#previousLines = newLines;
 			this.#previousWidth = width;
@@ -2811,7 +3362,6 @@ export class TUI extends Container {
 		}
 
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, finalCursorRow);
-		this.#hardwareCursorRow = toRow;
 		buffer += seq;
 		buffer += "\x1b[?2026l"; // End synchronized output
 
@@ -2845,20 +3395,22 @@ export class TUI extends Container {
 			fs.writeFileSync(debugPath, debugData);
 		}
 
-		// Write entire buffer at once
-		if (!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length)) return;
-
-		// Track cursor position for next render.
-		// cursorRow tracks end of content (for viewport calculation).
-		// #hardwareCursorRow was already updated by #cursorControlSequence above.
-		this.#cursorRow = Math.max(0, newLines.length - 1);
-		// Track content height for viewport calculation
-		this.#maxLinesRendered = newLines.length;
-		this.#viewportTopRow = Math.max(0, newLines.length - height);
-
-		this.#previousLines = newLines;
-		this.#previousWidth = width;
-		this.#previousHeight = height;
+		// Write entire buffer at once. Once those bytes are accepted, the painted
+		// frame and geometry are authoritative even when the optional IME cursor
+		// write subsequently detaches the terminal.
+		if (
+			!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length, () => {
+				this.#hardwareCursorRow = toRow;
+				this.#cursorRow = Math.max(0, newLines.length - 1);
+				this.#maxLinesRendered = newLines.length;
+				this.#viewportTopRow = Math.max(0, newLines.length - height);
+				this.#nativeScrollbackViewportTop = Math.max(this.#nativeScrollbackViewportTop, this.#viewportTopRow);
+				this.#previousLines = newLines;
+				this.#previousWidth = width;
+				this.#previousHeight = height;
+			})
+		)
+			return;
 	}
 
 	/**
@@ -2933,6 +3485,7 @@ export class TUI extends Container {
 		buffer: string,
 		cursorPos: { row: number; col: number } | null,
 		totalLines: number,
+		onBufferWritten?: () => void,
 	): boolean {
 		const overlay = this.#postRenderEmitter?.();
 		if (overlay) {
@@ -2942,8 +3495,14 @@ export class TUI extends Container {
 			buffer += `\x1b[?2026h\x1b7${overlay}\x1b8\x1b[?2026l`;
 		}
 		if (!this.#writeTerminal(buffer)) return false;
-		if (!this.#imeCursorActive) return true;
-		return this.#writeCursorPosition(cursorPos, totalLines);
+		onBufferWritten?.();
+		if (!this.#imeCursorActive) {
+			this.#lastRenderWriteSucceeded = true;
+			return true;
+		}
+		const cursorWritten = this.#writeCursorPosition(cursorPos, totalLines);
+		if (cursorWritten) this.#lastRenderWriteSucceeded = true;
+		return cursorWritten;
 	}
 
 	/**
@@ -2956,8 +3515,9 @@ export class TUI extends Container {
 			return this.#hideCursor();
 		}
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, totalLines, this.#hardwareCursorRow);
-		this.#hardwareCursorRow = toRow;
 		// No \x1b[?2026h/l wrapper: synchronized output flushes terminal state and discards macOS IME composition.
-		return this.#writeTerminal(seq);
+		if (!this.#writeTerminal(seq)) return false;
+		this.#hardwareCursorRow = toRow;
+		return true;
 	}
 }