@gajae-code/tui 0.11.11 → 0.12.1

package/src/tui.ts

@@ -10,9 +10,12 @@ import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
 import type { Terminal } from "./terminal";
 import {
+	encodeKittyPlacementDelete,
+	extractKittyPlacementReferences,
 	ImageProtocol,
 	isImageProtocolForced,
 	isUnderTerminalMultiplexer,
+	type KittyPlacementReference,
 	setCellDimensions,
 	setTerminalImageProtocol,
 	TERMINAL,
@@ -39,6 +42,11 @@ 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;
+
+/** DA1 (`CSI ? … c`) and XTSMGRAPHICS (`CSI ? … S`) replies to the sixel probe. */
+const DEVICE_REPORT_PATTERN = /^\x1b\[\?[\d;]*[cS]$/u;
 
 function stripTerminalControls(text: string): string {
 	return Bun.stripANSI(text)
@@ -190,6 +198,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 +636,27 @@ type TuiRenderCounterSnapshot = {
 	debugRedrawAppendWrites: number;
 	differentialGuardVisibleWidthCalls: number;
 };
+type RenderCommitWaiter = {
+	resolve: (committed: boolean) => void;
+	timer: NodeJS.Timeout;
+};
+
+type KittyPlacementOwner = "transcript" | "suffix" | "overlay";
+
+type KittyPlacementSpan = KittyPlacementReference & {
+	row: number;
+	owner: KittyPlacementOwner;
+};
+
+type KittyPlacementRegion = {
+	top: number;
+	bottom: number;
+};
+
+type KittyPlacementDeletePlan = {
+	deletedKeys: Set<string>;
+	output: string;
+};
 
 /**
  * TUI - Main class for managing terminal UI with differential rendering
@@ -631,6 +665,9 @@ export class TUI extends Container {
 	terminal: Terminal;
 	#previousLines: string[] = [];
 	#latestRenderedLines: string[] = [];
+	#latestRenderedTranscriptLineCount = 0;
+	#latestRenderedSuffixLineCount = 0;
+	#latestRenderedPlacementOwners = new Map<string, KittyPlacementOwner>();
 	/**
 	 * Raw (pre-normalization) lines from the previous frame, kept only when the
 	 * virtual-viewport flag is on. Used to detect whether the off-screen prefix is
@@ -638,6 +675,7 @@ export class TUI extends Container {
 	 * return stable string instances) so its normalized form can be reused (bounded normalize).
 	 */
 	#previousRaw: string[] = [];
+	#kittyPlacementSpans: KittyPlacementSpan[] = [];
 	#lineNormalizationCache = new Map<string, LineNormalizationCacheEntry>();
 	#lineEmitWidthCache = new Map<string, number>();
 	#lineTruncationCache = new Map<string, string>();
@@ -651,7 +689,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 +721,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 +756,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 +814,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 +828,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 +891,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 +960,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 +987,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 +1040,28 @@ 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 previousManualViewportTop = this.#manualViewportTop;
+		const previousManualViewportAnchor = this.#manualViewportAnchor;
+		const previousManualViewportFallbackAnchors = this.#manualViewportFallbackAnchors;
+		const previousReconcileMissingViewportAnchor = this.#reconcileMissingViewportAnchor;
+
+		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 +1070,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;
@@ -963,7 +1147,8 @@ export class TUI extends Container {
 			}
 		}
 		this.#manualViewportTop = targetViewportTop;
-		return this.#repaintViewportFromLines(
+		let contentPainted = false;
+		const painted = this.#repaintViewportFromLines(
 			this.#previousLines,
 			width,
 			height,
@@ -971,29 +1156,93 @@ export class TUI extends Container {
 			null,
 			"manual viewport scroll",
 			this.#manualViewportAnchor !== null,
+			() => {
+				contentPainted = true;
+				this.#manualTranscriptLineCount = this.#latestRenderedTranscriptLineCount;
+				this.#manualSuffixLineCount = this.#latestRenderedSuffixLineCount;
+			},
+			false,
+			this.#kittyPlacementSpans,
+			this.#kittyPlacementSpansForLines(this.#previousLines, this.#latestRenderedPlacementOwners),
+			{
+				transcriptLineCount: this.#latestRenderedTranscriptLineCount,
+				suffixLineCount: this.#latestRenderedSuffixLineCount,
+			},
 		);
+		if (!contentPainted) {
+			this.#manualViewportTop = previousManualViewportTop;
+			this.#manualViewportAnchor = previousManualViewportAnchor;
+			this.#manualViewportFallbackAnchors = previousManualViewportFallbackAnchors;
+			this.#reconcileMissingViewportAnchor = previousReconcileMissingViewportAnchor;
+		}
+		return painted;
+	}
+
+	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.#latestRenderedSuffixLineCount,
+		);
+		const liveLines = paddedLiveLines.lines;
+		const liveTranscriptLineCount = this.#latestRenderedTranscriptLineCount;
+		const liveSuffixLineCount = this.#latestRenderedSuffixLineCount + paddedLiveLines.insertedBlankRows;
+		const liveKittyPlacementSpans = this.#kittyPlacementSpansForLines(liveLines, this.#latestRenderedPlacementOwners);
+		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;
+				this.#manualTranscriptLineCount = liveTranscriptLineCount;
+				this.#manualSuffixLineCount = liveSuffixLineCount;
+				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,
+			this.#kittyPlacementSpans,
+			liveKittyPlacementSpans,
+			{ transcriptLineCount: liveTranscriptLineCount, suffixLineCount: liveSuffixLineCount },
 		);
-		if (repainted) this.#previousLines = liveLines;
-		return repainted;
 	}
 
 	/**
@@ -1097,6 +1346,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 +1364,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 +1423,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;
@@ -1316,13 +1620,29 @@ export class TUI extends Container {
 
 	stop(): void {
 		this.flushTerminalCleanup();
+		const placementCleanup = this.#kittyPlacementDeletePlan(this.#kittyPlacementSpans, [], [], true).output;
+		if (placementCleanup.length > 0 && this.#writeTerminal(placementCleanup)) this.#kittyPlacementSpans = [];
 		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
@@ -1353,6 +1673,7 @@ export class TUI extends Container {
 		this.#previousLines = [];
 		this.#latestRenderedLines = [];
 		this.#previousRaw = [];
+		this.#kittyPlacementSpans = [];
 		this.#lineNormalizationCache.clear();
 		this.#lineTruncationCache.clear();
 		this.#lineEmitWidthCache.clear();
@@ -1383,19 +1704,79 @@ 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);
 			// A forced full redraw supersedes any queued input-priority render.
 			this.#inputRenderPending = false;
 			this.#previousLines = [];
@@ -1408,12 +1789,6 @@ export class TUI extends Container {
 			this.#previousHeight = -1; // -1 triggers heightChanged, forcing a full clear
 			this.#lineNormalizationCacheLimit = 0;
 			this.#lineTruncationCacheLimit = 0;
-			if (!preserveViewportCursor) {
-				this.#cursorRow = 0;
-				this.#hardwareCursorRow = 0;
-				this.#viewportTopRow = 0;
-				this.#maxLinesRendered = 0;
-			}
 			if (this.#renderTimer) {
 				clearTimeout(this.#renderTimer);
 				this.#renderTimer = undefined;
@@ -1422,12 +1797,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 +1828,7 @@ export class TUI extends Container {
 		if (this.#renderRequested) return;
 		this.#renderRequested = true;
 		process.nextTick(() => this.#scheduleRender());
+		return;
 	}
 
 	#scheduleRender(): void {
@@ -1462,10 +1843,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 +1873,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 +1908,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);
@@ -1563,6 +1952,15 @@ export class TUI extends Container {
 			return;
 		}
 
+		// DA1 and XTSMGRAPHICS replies belong to the sixel probe, whose listener runs
+		// above. Reaching this point means the probe already finished, timed out, or
+		// was cleared by a stop()/start() cycle while the terminal still owed the
+		// reply. These are terminal-to-host reports, never user input, so drop them
+		// instead of typing them into the focused component.
+		if (DEVICE_REPORT_PATTERN.test(data)) {
+			return;
+		}
+
 		// Global debug key handler (registry: tui.global.debug, default Shift+Ctrl+D)
 		if (getKeybindings().matches(data, "tui.global.debug") && this.onDebug) {
 			this.onDebug();
@@ -1595,16 +1993,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 +2017,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;
@@ -1872,7 +2280,12 @@ export class TUI extends Container {
 	}
 
 	/** Composite all overlays into content lines (in stack order, later = on top). */
-	#compositeOverlays(lines: string[], termWidth: number, termHeight: number): string[] {
+	#compositeOverlays(
+		lines: string[],
+		termWidth: number,
+		termHeight: number,
+		placementOwners?: Map<string, KittyPlacementOwner>,
+	): string[] {
 		if (this.overlayStack.length === 0) return lines;
 		const result = [...lines];
 		for (const entry of this.overlayStack) entry.mouseBounds = undefined;
@@ -1933,6 +2346,11 @@ export class TUI extends Container {
 					// (components should already respect width, but this ensures it)
 					const truncatedOverlayLine =
 						visibleWidth(overlayLines[i]) > w ? sliceByColumn(overlayLines[i], 0, w, true) : overlayLines[i];
+					if (placementOwners !== undefined) {
+						for (const placement of extractKittyPlacementReferences(truncatedOverlayLine)) {
+							placementOwners.set(this.#kittyPlacementKey(placement), "overlay");
+						}
+					}
 					result[idx] = this.#compositeLineAt(result[idx], truncatedOverlayLine, col, w, termWidth);
 					modifiedLines.add(idx);
 				}
@@ -2150,33 +2568,194 @@ export class TUI extends Container {
 		return lines;
 	}
 
-	#padBeforeBottomPinnedComponent(
+	#kittyPlacementKey(reference: KittyPlacementReference): string {
+		return `${reference.imageId}:${reference.placementId}`;
+	}
+
+	#kittyPlacementSpansForLines(
 		lines: string[],
-		height: number,
-		renderedChildren: Map<Component, string[]>,
-	): string[] {
-		const component = this.#bottomPinnedComponent;
-		if (component === null || lines.length >= height) return lines;
+		owners: ReadonlyMap<string, KittyPlacementOwner>,
+	): KittyPlacementSpan[] {
+		const placements: KittyPlacementSpan[] = [];
+		for (let row = 0; row < lines.length; row++) {
+			for (const placement of extractKittyPlacementReferences(lines[row])) {
+				placements.push({
+					...placement,
+					row,
+					owner: owners.get(this.#kittyPlacementKey(placement)) ?? "transcript",
+				});
+			}
+		}
+		return placements;
+	}
+
+	#kittyPlacementIntersectsRegion(placement: KittyPlacementSpan, region: KittyPlacementRegion): boolean {
+		return placement.row < region.bottom && placement.row + placement.rows > region.top;
+	}
+
+	#kittyPlacementDeletePlan(
+		previous: KittyPlacementSpan[],
+		next: KittyPlacementSpan[],
+		overwrittenRegions: KittyPlacementRegion[],
+		deleteAll = false,
+		overwrittenOwners: KittyPlacementOwner[] = [],
+	): KittyPlacementDeletePlan {
+		const deletedKeys = new Set<string>();
+		if (TERMINAL.imageProtocol !== ImageProtocol.Kitty) return { deletedKeys, output: "" };
+		const nextByKey = new Map(next.map(placement => [this.#kittyPlacementKey(placement), placement]));
+		let output = "";
+		for (const placement of previous) {
+			const key = this.#kittyPlacementKey(placement);
+			if (deletedKeys.has(key)) continue;
+			const candidate = nextByKey.get(key);
+			const changed =
+				candidate === undefined || candidate.row !== placement.row || candidate.rows !== placement.rows;
+			const overwritten =
+				deleteAll ||
+				overwrittenOwners.includes(placement.owner) ||
+				overwrittenRegions.some(region => this.#kittyPlacementIntersectsRegion(placement, region));
+			if (!changed && !overwritten) continue;
+			deletedKeys.add(key);
+			output += encodeKittyPlacementDelete(placement);
+		}
+		return { deletedKeys, output };
+	}
+
+	#kittyCommittedPlacementsAfterPaint(
+		previous: KittyPlacementSpan[],
+		next: KittyPlacementSpan[],
+		deletePlan: KittyPlacementDeletePlan,
+		emittedRegions: KittyPlacementRegion[],
+	): KittyPlacementSpan[] {
+		const committed = new Map<string, KittyPlacementSpan>();
+		for (const placement of previous) {
+			const key = this.#kittyPlacementKey(placement);
+			if (!deletePlan.deletedKeys.has(key)) committed.set(key, placement);
+		}
+		for (const placement of next) {
+			if (!emittedRegions.some(region => placement.row >= region.top && placement.row < region.bottom)) continue;
+			committed.set(this.#kittyPlacementKey(placement), placement);
+		}
+		return [...committed.values()];
+	}
+
+	#kittyViewportTopIncludingPlacementAnchors(viewportTop: number, placements: KittyPlacementSpan[]): number {
+		let resolvedTop = viewportTop;
+		let changed: boolean;
+		do {
+			const priorTop = resolvedTop;
+			for (const placement of placements) {
+				if (placement.row < resolvedTop && placement.row + placement.rows > resolvedTop) {
+					resolvedTop = placement.row;
+				}
+			}
+			changed = resolvedTop !== priorTop;
+		} while (changed);
+		return resolvedTop;
+	}
 
-		let pinnedStart = -1;
-		for (let i = this.children.length - 1; i >= 0; i--) {
-			if (this.children[i] === component) {
-				pinnedStart = i;
+	#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;
+	}
+
+	#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, suffixLineCount = this.#manualSuffixLineCount): number {
+		const noticeRows = this.#manualOutputNotice && height > suffixLineCount ? 1 : 0;
+		return Math.max(0, height - suffixLineCount - noticeRows);
 	}
 	#resolveManualAnchor(frame: ViewportAnchorFrame): number | null {
 		const anchor = this.#manualViewportAnchor;
@@ -2235,23 +2814,65 @@ export class TUI extends Container {
 		cursorPos: { row: number; col: number } | null,
 		reason: string,
 		allowPastLiveBottom = false,
+		onPainted?: () => void,
+		paintLive = false,
+		placementsToClear: KittyPlacementSpan[] = this.#kittyPlacementSpans,
+		placementsToPaint: KittyPlacementSpan[] = placementsToClear,
+		geometry?: { transcriptLineCount: number; suffixLineCount: number },
 	): boolean {
+		const paintManual = this.#manualViewportTop !== undefined && !paintLive;
+		const transcriptLineCount = geometry?.transcriptLineCount ?? this.#manualTranscriptLineCount;
+		const suffixLineCount = geometry?.suffixLineCount ?? this.#manualSuffixLineCount;
 		if (height <= 0 || width <= 0) return false;
-		const maxViewportTop = Math.max(0, lines.length - (allowPastLiveBottom ? 1 : height));
-		const nextViewportTop = Math.max(0, Math.min(maxViewportTop, viewportTop));
+		const maxViewportTop = Math.max(
+			0,
+			!paintManual
+				? lines.length - (allowPastLiveBottom ? 1 : height)
+				: allowPastLiveBottom
+					? lines.length - 1
+					: transcriptLineCount - this.#manualTranscriptCapacity(height, suffixLineCount),
+		);
+		let nextViewportTop = Math.max(0, Math.min(maxViewportTop, viewportTop));
+		if (paintManual)
+			nextViewportTop = this.#kittyViewportTopIncludingPlacementAnchors(nextViewportTop, placementsToPaint);
 		const currentScreenRow = Math.max(0, Math.min(height - 1, this.#hardwareCursorRow - this.#viewportTopRow));
-		let buffer = "\x1b[?2026h";
+		const transcriptCapacity = paintManual ? this.#manualTranscriptCapacity(height, suffixLineCount) : height;
+		const noticeRows = paintManual && this.#manualOutputNotice && height > suffixLineCount ? 1 : 0;
+		const deletePlan = this.#kittyPlacementDeletePlan(
+			placementsToClear,
+			placementsToPaint,
+			[{ top: this.#viewportTopRow, bottom: this.#viewportTopRow + height }],
+			false,
+			paintManual ? ["suffix", "overlay"] : [],
+		);
+		const emittedRegions: KittyPlacementRegion[] = paintManual
+			? [
+					{ top: nextViewportTop, bottom: nextViewportTop + transcriptCapacity },
+					{ top: transcriptLineCount, bottom: transcriptLineCount + suffixLineCount },
+				]
+			: [{ top: nextViewportTop, bottom: nextViewportTop + height }];
+		let buffer = `\x1b[?2026h${deletePlan.output}`;
 		if (currentScreenRow > 0) {
 			buffer += `\x1b[${currentScreenRow}A`;
 		}
 		buffer += "\r";
-
+		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[transcriptLineCount + suffixRow] ?? "")
+						: paintManual && lineIndex >= transcriptLineCount
+							? ""
+							: (lines[lineIndex] ?? "");
+			committedTranscriptRows.push(
+				screenRow < transcriptCapacity && lineIndex < transcriptLineCount ? lineIndex : null,
+			);
 			const isImage = TERMINAL.isImageLine(line);
 			if (!isImage && this.#visibleWidthForDifferentialGuard(line) > width) {
 				let truncatedLine = truncateToWidth(line, width, Ellipsis.Omit);
@@ -2270,20 +2891,32 @@ 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;
+		let contentWritten = false;
+		const writeSucceeded = this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, lines.length, () => {
+			contentWritten = true;
+			this.#hardwareCursorRow = cursorToRow;
+			this.#committedTranscriptRows = committedTranscriptRows;
+			this.#cursorRow = Math.max(0, lines.length - 1);
+			this.#maxLinesRendered = lines.length;
+			this.#viewportTopRow = nextViewportTop;
+			if (paintManual) this.#manualViewportTop = nextViewportTop;
+			this.#kittyPlacementSpans = this.#kittyCommittedPlacementsAfterPaint(
+				placementsToClear,
+				placementsToPaint,
+				deletePlan,
+				emittedRegions,
+			);
+			onPainted?.();
+		});
+		if (!contentWritten) 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;
+		return writeSucceeded;
 	}
 
 	#doRender(): void {
@@ -2304,27 +2937,50 @@ export class TUI extends Container {
 		const renderedLines: string[] = [];
 		const renderedChildren = new Map<Component, string[]>();
 		let anchorFrame: ViewportAnchorFrame | null = null;
+		let previousKittyPlacementSpans = this.#kittyPlacementSpans;
+		const placementOwners = new Map<string, KittyPlacementOwner>();
+		const pinnedChildIndex =
+			this.#bottomPinnedComponent === null ? -1 : this.children.indexOf(this.#bottomPinnedComponent);
+		const hasStickySuffix = pinnedChildIndex >= 0;
 		const anchorRenderFailureCountBefore = viewportAnchorRenderFailureCount;
-		for (const child of this.children) {
+		for (let childIndex = 0; childIndex < this.children.length; childIndex++) {
+			const child = this.children[childIndex];
 			const rendered = safeRenderComponentWithViewportAnchors(child, width, "tui-child");
 			renderedChildren.set(child, rendered.lines);
 			if (child === this.#viewportAnchorComponent && rendered.anchors.some(anchor => anchor !== null)) {
 				anchorFrame = { startRow: renderedLines.length, anchors: rendered.anchors };
 			}
-			for (const line of rendered.lines) renderedLines.push(line);
+			const owner: KittyPlacementOwner = hasStickySuffix && childIndex >= pinnedChildIndex ? "suffix" : "transcript";
+			for (const line of rendered.lines) {
+				for (const placement of extractKittyPlacementReferences(line)) {
+					placementOwners.set(this.#kittyPlacementKey(placement), owner);
+				}
+				renderedLines.push(line);
+			}
 		}
+		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;
 		}
+		const nextTranscriptLineCount = sourceTranscriptLineCount;
+		const nextSuffixLineCount = hasStickySuffix ? Math.max(0, newLines.length - nextTranscriptLineCount) : 0;
 
 		// Composite overlays into the rendered lines (before differential compare)
 		if (this.overlayStack.length > 0) {
-			newLines = this.#compositeOverlays(newLines, width, height);
+			newLines = this.#compositeOverlays(newLines, width, height, placementOwners);
 		}
 
 		// Extract cursor position (marker must be found before diff comparison)
@@ -2341,9 +2997,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).
@@ -2392,9 +3048,37 @@ export class TUI extends Container {
 			renderMetrics.recordLineCount("measured", total - diffStart);
 			if (usedWindowNormalize) renderMetrics.recordLineCount("offscreenScan", diffStart);
 		}
+		const nextKittyPlacementSpans = this.#kittyPlacementSpansForLines(newLines, placementOwners);
 		this.#latestRenderedLines = newLines;
+		this.#latestRenderedTranscriptLineCount = nextTranscriptLineCount;
+		this.#latestRenderedSuffixLineCount = nextSuffixLineCount;
+		this.#latestRenderedPlacementOwners = placementOwners;
+		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) {
+			const committedManualViewportTop = this.#manualViewportTop;
+			const committedManualViewportAnchor = this.#manualViewportAnchor;
+			const committedManualViewportFallbackAnchors = this.#manualViewportFallbackAnchors;
+			const committedReconcileMissingViewportAnchor = this.#reconcileMissingViewportAnchor;
+			const restoreManualIntent = (): void => {
+				this.#manualViewportTop = committedManualViewportTop;
+				this.#manualViewportAnchor = committedManualViewportAnchor;
+				this.#manualViewportFallbackAnchors = committedManualViewportFallbackAnchors;
+				this.#reconcileMissingViewportAnchor = committedReconcileMissingViewportAnchor;
+			};
+			let contentPainted = false;
 			let resolvedAnchorTop = anchorFrame === null ? null : this.#resolveManualAnchor(anchorFrame);
 			if (
 				this.#manualViewportAnchor !== null &&
@@ -2412,6 +3096,7 @@ export class TUI extends Container {
 				if (anchorRenderFailed) {
 					// Keep semantic intent armed for recovery, but render the diagnostic frame
 					// instead of masking a provider failure behind stale transcript content.
+					contentPainted = false;
 					this.#repaintViewportFromLines(
 						newLines,
 						width,
@@ -2420,16 +3105,27 @@ export class TUI extends Container {
 						null,
 						"failed semantic viewport render",
 						true,
+						() => {
+							contentPainted = true;
+							this.#previousLines = newLines;
+							this.#previousWidth = width;
+							this.#previousHeight = height;
+							this.#manualTranscriptLineCount = nextTranscriptLineCount;
+							this.#manualSuffixLineCount = nextSuffixLineCount;
+						},
+						false,
+						previousKittyPlacementSpans,
+						nextKittyPlacementSpans,
+						{ transcriptLineCount: nextTranscriptLineCount, suffixLineCount: nextSuffixLineCount },
 					);
-					this.#previousLines = newLines;
-					this.#previousWidth = width;
-					this.#previousHeight = height;
+					if (!contentPainted) restoreManualIntent();
 					return;
 				}
 				// A formerly valid semantic target is temporarily absent (provider removal,
 				// replacement, eviction, or object deletion). Keep the last resolved frame
 				// instead of silently reinterpreting manual intent as a numeric viewport.
 				const retainedLines = this.#previousLines.length > 0 ? this.#previousLines : newLines;
+				contentPainted = false;
 				this.#repaintViewportFromLines(
 					retainedLines,
 					width,
@@ -2438,9 +3134,15 @@ export class TUI extends Container {
 					null,
 					"unresolved semantic viewport render",
 					true,
+					() => {
+						contentPainted = true;
+						this.#previousWidth = width;
+						this.#previousHeight = height;
+					},
+					false,
+					previousKittyPlacementSpans,
 				);
-				this.#previousWidth = width;
-				this.#previousHeight = height;
+				if (!contentPainted) restoreManualIntent();
 				return;
 			}
 			const nextViewportTop = resolvedAnchorTop ?? this.#manualViewportTop;
@@ -2448,6 +3150,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])
 			) {
@@ -2455,62 +3158,110 @@ export class TUI extends Container {
 			}
 			this.#manualViewportTop = nextViewportTop;
 			this.#reconcileMissingViewportAnchor = false;
-			if (
-				this.#repaintViewportFromLines(
-					newLines,
-					width,
-					height,
-					nextViewportTop,
-					null,
-					"manual viewport render",
-					this.#manualViewportAnchor !== null,
-				)
-			) {
-				this.#previousLines = newLines;
-				this.#previousWidth = width;
-				this.#previousHeight = height;
-			}
+			contentPainted = false;
+			this.#repaintViewportFromLines(
+				newLines,
+				width,
+				height,
+				nextViewportTop,
+				null,
+				"manual viewport render",
+				this.#manualViewportAnchor !== null,
+				() => {
+					contentPainted = true;
+					this.#previousLines = newLines;
+					this.#previousWidth = width;
+					this.#previousHeight = height;
+					this.#paintedManualOutputNotice = this.#manualOutputNotice;
+					this.#manualTranscriptLineCount = nextTranscriptLineCount;
+					this.#manualSuffixLineCount = nextSuffixLineCount;
+				},
+				false,
+				previousKittyPlacementSpans,
+				nextKittyPlacementSpans,
+				{ transcriptLineCount: nextTranscriptLineCount, suffixLineCount: nextSuffixLineCount },
+			);
+			if (!contentPainted) restoreManualIntent();
 			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) => boolean;
+		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
+			const deletePlan = this.#kittyPlacementDeletePlan(
+				previousKittyPlacementSpans,
+				nextKittyPlacementSpans,
+				[],
+				clear,
+			);
+			let buffer = `\x1b[?2026h${deletePlan.output}`; // 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;
+					this.#kittyPlacementSpans = this.#kittyCommittedPlacementsAfterPaint(
+						previousKittyPlacementSpans,
+						nextKittyPlacementSpans,
+						deletePlan,
+						[{ top: Number.NEGATIVE_INFINITY, bottom: Number.POSITIVE_INFINITY }],
+					);
+					this.#manualTranscriptLineCount = nextTranscriptLineCount;
+					this.#manualSuffixLineCount = nextSuffixLineCount;
+				})
+			)
+				return;
 		};
 
-		const viewportRepaint = (reason: string): void => {
+		viewportRepaint = (reason: string, targetViewportTop = Math.max(0, newLines.length - height)): boolean => {
 			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";
+			const deletePlan = this.#kittyPlacementDeletePlan(previousKittyPlacementSpans, nextKittyPlacementSpans, [
+				{ top: prevViewportTop, bottom: prevViewportTop + height },
+			]);
+			let buffer = `\x1b[?2026h${deletePlan.output}`;
 			if (currentScreenRow > 0) {
 				buffer += `\x1b[${currentScreenRow}A`;
 			}
@@ -2539,25 +3290,34 @@ 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;
+			let contentWritten = false;
+			this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length, () => {
+				contentWritten = true;
+				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;
+				this.#kittyPlacementSpans = this.#kittyCommittedPlacementsAfterPaint(
+					previousKittyPlacementSpans,
+					nextKittyPlacementSpans,
+					deletePlan,
+					[{ top: nextViewportTop, bottom: nextViewportTop + height }],
+				);
+				this.#manualTranscriptLineCount = nextTranscriptLineCount;
+				this.#manualSuffixLineCount = nextSuffixLineCount;
+			});
+			if (!contentWritten) return false;
 
 			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;
+			return true;
 		};
 
 		const debugRedraw = this.#debugRedraw;
@@ -2576,14 +3336,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 +3416,23 @@ 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;
+		if (firstChanged >= 0) {
+			const changedTop = firstChanged;
+			let expanded: boolean;
+			do {
+				const priorTop = firstChanged;
+				const priorBottom = lastChanged + 1;
+				for (const placement of previousKittyPlacementSpans) {
+					const placementBottom = placement.row + placement.rows;
+					if (placement.row >= priorBottom || placementBottom <= priorTop) continue;
+					firstChanged = Math.min(firstChanged, placement.row);
+					lastChanged = Math.max(lastChanged, placementBottom - 1);
+				}
+				expanded = firstChanged !== priorTop || lastChanged + 1 !== priorBottom;
+			} while (expanded);
+			if (firstChanged !== changedTop) appendStart = false;
+		}
 
 		// No changes - but still need to update hardware cursor position if it moved
 		if (firstChanged === -1) {
@@ -2658,10 +3446,59 @@ export class TUI extends Container {
 			viewportRepaint(`content contraction changed viewport top (${prevViewportTop} -> ${nextLiveViewportTop})`);
 			return;
 		}
+		if (
+			appendedLines &&
+			nextLiveViewportTop > prevViewportTop &&
+			previousKittyPlacementSpans.some(placement =>
+				this.#kittyPlacementIntersectsRegion(placement, {
+					top: prevViewportTop,
+					bottom: prevViewportTop + height,
+				}),
+			)
+		) {
+			viewportRepaint(
+				`content append moved a Kitty placement viewport (${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;
+			if (
+				!viewportRepaint(
+					`staging committed scrollback frontier before resumed admission (${prevViewportTop} -> ${resumeViewportTop} -> ${nextLiveViewportTop})`,
+					resumeViewportTop,
+				)
+			) {
+				return;
+			}
+			previousKittyPlacementSpans = this.#kittyPlacementSpans;
+			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) {
-				let buffer = "\x1b[?2026h";
+				const deletePlan = this.#kittyPlacementDeletePlan(previousKittyPlacementSpans, nextKittyPlacementSpans, [
+					{ top: firstChanged, bottom: lastChanged + 1 },
+				]);
+				let buffer = `\x1b[?2026h${deletePlan.output}`;
 				// Move to end of new content (clamp to 0 for empty content)
 				const targetRow = Math.max(0, newLines.length - 1);
 				const lineDiff = computeLineDiff(targetRow);
@@ -2691,18 +3528,37 @@ 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);
+						this.#kittyPlacementSpans = this.#kittyCommittedPlacementsAfterPaint(
+							previousKittyPlacementSpans,
+							nextKittyPlacementSpans,
+							deletePlan,
+							[],
+						);
+						this.#manualTranscriptLineCount = nextTranscriptLineCount;
+						this.#manualSuffixLineCount = nextSuffixLineCount;
+					})
+				)
+					return;
 			}
 			this.#previousLines = newLines;
 			this.#previousWidth = width;
 			this.#previousHeight = height;
 			this.#maxLinesRendered = newLines.length;
 			this.#viewportTopRow = Math.max(0, newLines.length - height);
+			this.#manualTranscriptLineCount = nextTranscriptLineCount;
+			this.#manualSuffixLineCount = nextSuffixLineCount;
 			return;
 		}
 
@@ -2729,7 +3585,10 @@ export class TUI extends Container {
 
 		// Render from first changed line to end
 		// Build buffer with all updates wrapped in synchronized output
-		let buffer = "\x1b[?2026h"; // Begin synchronized output
+		const deletePlan = this.#kittyPlacementDeletePlan(previousKittyPlacementSpans, nextKittyPlacementSpans, [
+			{ top: firstChanged, bottom: lastChanged + 1 },
+		]);
+		let buffer = `\x1b[?2026h${deletePlan.output}`; // Begin synchronized output
 		const prevViewportBottom = prevViewportTop + height - 1;
 		const moveTargetRow = appendStart ? firstChanged - 1 : firstChanged;
 		if (moveTargetRow > prevViewportBottom) {
@@ -2811,7 +3670,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 +3703,30 @@ 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;
+				this.#kittyPlacementSpans = this.#kittyCommittedPlacementsAfterPaint(
+					previousKittyPlacementSpans,
+					nextKittyPlacementSpans,
+					deletePlan,
+					[{ top: firstChanged, bottom: renderEnd + 1 }],
+				);
+				this.#manualTranscriptLineCount = nextTranscriptLineCount;
+				this.#manualSuffixLineCount = nextSuffixLineCount;
+			})
+		)
+			return;
 	}
 
 	/**
@@ -2933,6 +3801,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 +3811,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 +3831,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;
 	}
 }