@gajae-code/tui 0.17.2 → 0.17.5

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [0.17.5] - 2026-09-24
+
+### Fixed
+
+- `Text` rows, including custom-background rows, no longer exceed the viewport width.
+
+### Performance
+
+- Layout-only frames reuse a cached transcript prefix instead of copying and re-normalizing every row. Off-screen prefix identity is still checked by reference, and only the viewport window is normalized. Emitted bytes stay the same.
+
+- `Text` measures each row once and slices overflow instead of measuring again. `Loader` no longer re-clamps its rows.
+
+## [0.17.4] - 2026-09-23
+
+## [0.17.3] - 2026-09-22
+
+### Performance
+
+- Avoid unsupported Kitty placement extraction on ordinary non-Kitty input frames.
+- Reuse unchanged editor logical-line layouts, including keyboard shrink/join paths that previously retained deleted-line cache entries.
+- Reuse the byte/line admission decision for exact cached Markdown highlights instead of rescanning unchanged fenced code.
+- Add a native-highlight input-to-synchronized-write benchmark with same-frame visibility checks. Scheduling, preparation, force precedence, and output revisions are unchanged.
+
+- Avoid allocating fallback arrays while attributing Kitty placements during frame assembly. Emitted terminal bytes are unchanged.
+
+- Hold the raw frame by reference instead of copying every transcript line during frame assembly. Emitted terminal bytes are unchanged.
+
 ## [0.17.2] - 2026-09-18
 
 ## [0.17.1] - 2026-09-17

package/dist/types/components/editor.d.ts

@@ -98,6 +98,8 @@ export declare class Editor implements Component, Focusable {
     invalidate(): void;
     render(width: number): string[];
     handleInput(data: string): void;
+    /** Test-only seam: retained per-logical-line layout entries. */
+    get logicalLayoutCacheSize(): number;
     /** Test-only seam: current wrap-cache entry count (memory-bound assertions). */
     get wrappedLineCacheSize(): number;
     getText(): string;

package/dist/types/components/markdown.d.ts

@@ -21,6 +21,7 @@ export declare function resetMarkdownHighlightCallCount(): void;
 export declare const __markdownPerfCounters: {
     lexerInvocations: number;
     lexedBytes: number;
+    highlightAdmissionScans: number;
     reset(): void;
 };
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */

package/dist/types/tui.d.ts

@@ -364,6 +364,16 @@ type TuiRenderCounterSnapshot = {
     widthReflowScanRows: number;
     widthReflowVisibleWidthCalls: number;
     kittyPlacementScanRows: number;
+    kittyPlacementReferenceRows: number;
+    /** Rows copied into the frame while the render scope is layout-only. */
+    layoutAssemblyRows: number;
+    /** Off-screen prefix comparisons performed by a layout-only frame. */
+    layoutOffscreenPrefixCompares: number;
+    /**
+     * Stable prefix rows copied into a fresh layout frame. Zero when the spare prefix is reused.
+     * The fresh slice also copies the viewport window, which is rewritten immediately.
+     */
+    layoutPrefixLineCopies: number;
 };
 /**
  * TUI - Main class for managing terminal UI with differential rendering
@@ -376,6 +386,7 @@ export declare class TUI extends Container {
     onDebug?: () => void;
     static resetRenderCountersForTest(): void;
     static getRenderCountersForTest(): TuiRenderCounterSnapshot;
+    getRenderedLineForTest(index: number): string | undefined;
     getRenderPreparationStateForTest(): {
         pending: number;
         holes: number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.17.2",
+	"version": "0.17.5",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.17.2",
-		"@gajae-code/utils": "0.17.2",
+		"@gajae-code/natives": "0.17.5",
+		"@gajae-code/utils": "0.17.5",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/components/editor.ts

@@ -443,6 +443,7 @@ export class Editor implements Component, Focusable {
 	#wrappedLineCache: CachedWrappedLine[] = [];
 	#docVersion = 0;
 	#layoutCache: LayoutCache | undefined;
+	#logicalLayoutCache: Array<{ text: string; width: number; cursorCol: number | undefined; lines: LayoutLine[] }> = [];
 
 	// Emacs-style kill ring
 	#killRing = new KillRing();
@@ -754,11 +755,20 @@ export class Editor implements Component, Focusable {
 	}
 
 	invalidate(): void {
+		this.#logicalLayoutCache.length = 0;
 		this.#wrappedLineCache.length = 0;
 		this.#layoutCache = undefined;
 	}
 
+	#trimLogicalLayoutCache(): void {
+		// Retain at most one layout per current logical line, never deleted tails.
+		if (this.#logicalLayoutCache.length > this.#state.lines.length) {
+			this.#logicalLayoutCache.length = this.#state.lines.length;
+		}
+	}
+
 	#bumpDocumentVersion(): void {
+		this.#trimLogicalLayoutCache();
 		this.#docVersion += 1;
 		this.#layoutCache = undefined;
 	}
@@ -1163,6 +1173,16 @@ export class Editor implements Component, Focusable {
 	}
 
 	handleInput(data: string): void {
+		try {
+			this.#handleInput(data);
+		} finally {
+			// Undo snapshots invalidate before mutation; trim after all input paths,
+			// including early returns and nested bracketed-paste handling.
+			this.#trimLogicalLayoutCache();
+		}
+	}
+
+	#handleInput(data: string): void {
 		const kb = getKeybindings();
 
 		// Handle character jump mode (awaiting next character to jump to)
@@ -1585,6 +1605,11 @@ export class Editor implements Component, Focusable {
 		return wrapped;
 	}
 
+	/** Test-only seam: retained per-logical-line layout entries. */
+	get logicalLayoutCacheSize(): number {
+		return this.#logicalLayoutCache.length;
+	}
+
 	/** Test-only seam: current wrap-cache entry count (memory-bound assertions). */
 	get wrappedLineCacheSize(): number {
 		return this.#wrappedLineCache.length;
@@ -1624,6 +1649,16 @@ export class Editor implements Component, Focusable {
 	}
 
 	#layoutLogicalLine(lineIndex: number, contentWidth: number): LayoutLine[] {
+		const text = this.#state.lines[lineIndex] || "";
+		const cursorCol = lineIndex === this.#state.cursorLine ? this.#state.cursorCol : undefined;
+		const cached = this.#logicalLayoutCache[lineIndex];
+		if (cached?.text === text && cached.width === contentWidth && cached.cursorCol === cursorCol) return cached.lines;
+		const lines = this.#buildLogicalLine(lineIndex, contentWidth);
+		this.#logicalLayoutCache[lineIndex] = { text, width: contentWidth, cursorCol, lines };
+		return lines;
+	}
+
+	#buildLogicalLine(lineIndex: number, contentWidth: number): LayoutLine[] {
 		__editorPerfCounters.layoutLogicalLinesProcessed += 1;
 		const line = this.#state.lines[lineIndex] || "";
 		const isCurrentLine = lineIndex === this.#state.cursorLine;
@@ -1722,6 +1757,7 @@ export class Editor implements Component, Focusable {
 	}
 
 	#layoutText(contentWidth: number): LayoutLine[] {
+		this.#trimLogicalLayoutCache();
 		__editorPerfCounters.layoutTextInvocations += 1;
 		const key = this.#makeLayoutCacheKey(contentWidth);
 		const cached = this.#layoutCache;

package/src/components/loader.ts

@@ -1,7 +1,6 @@
 import { type AnimationRegistration, registerAnimationCallback } from "../animation-scheduler";
 import { isRemoteTerminalSession, isUnderTerminalMultiplexer } from "../terminal-capabilities";
 import type { TUI } from "../tui";
-import { sliceByColumn, visibleWidth } from "../utils";
 import { Text } from "./text";
 
 const SPINNER_ADVANCE_MS = 80;
@@ -67,14 +66,8 @@ export class Loader extends Text {
 	}
 
 	render(width: number): string[] {
-		const lines = ["", ...super.render(width)];
-		for (let i = 0; i < lines.length; i++) {
-			const line = lines[i];
-			if (visibleWidth(line) > width) {
-				lines[i] = sliceByColumn(line, 0, width, true);
-			}
-		}
-		return lines;
+		// Leading blank is the spacer; Text already fits each row to `width`.
+		return ["", ...super.render(width)];
 	}
 
 	start() {

package/src/components/markdown.ts

@@ -214,9 +214,11 @@ export function resetMarkdownHighlightCallCount(): void {
 export const __markdownPerfCounters = {
 	lexerInvocations: 0,
 	lexedBytes: 0,
+	highlightAdmissionScans: 0,
 	reset(): void {
 		this.lexerInvocations = 0;
 		this.lexedBytes = 0;
+		this.highlightAdmissionScans = 0;
 	},
 };
 
@@ -452,6 +454,7 @@ export class Markdown implements Component {
 	}
 
 	#exceedsHighlightCap(code: string): boolean {
+		__markdownPerfCounters.highlightAdmissionScans += 1;
 		// UTF-8 requires at least one byte per UTF-16 code unit, including lone
 		// surrogates. Reject obviously oversized input without scanning or hashing it.
 		if (code.length > MAX_HIGHLIGHT_BYTES) return true;
@@ -467,10 +470,13 @@ export class Markdown implements Component {
 
 	#highlightCodeBlock(code: string, lang: string): string[] | null {
 		if (!this.#theme.highlightCode) return null;
-		if (this.#exceedsHighlightCap(code)) return null;
+		// Avoid building/hashing keys for obviously oversized input. A cache hit
+		// already passed the immutable byte/line caps; only misses need a scan.
+		if (code.length > MAX_HIGHLIGHT_BYTES) return null;
 		const key = `${objectId(this.#theme)}\x00${lang}\x00${code}`;
 		const cached = highlightCache.get(key);
 		if (cached?.lang === lang && cached.code === code) return cached.lines;
+		if (this.#exceedsHighlightCap(code)) return null;
 		highlightCallCount += 1;
 		const result = this.#theme.highlightCode(code, lang || undefined);
 		highlightCache.set(key, { lang, code, lines: result });

package/src/components/text.ts

@@ -6,6 +6,7 @@ import {
 	extractViewportAnchorRows,
 	padding,
 	replaceTabs,
+	sliceByColumn,
 	type ViewportAnchorSpan,
 	visibleWidth,
 	wrapTextWithAnsi,
@@ -101,8 +102,14 @@ export class Text implements Component {
 		const contentLines: string[] = [];
 		for (const line of wrappedLines) {
 			const lineWithMargins = leftMargin + line + rightMargin;
-			if (this.#customBgFn) contentLines.push(applyBackgroundToLine(lineWithMargins, width, this.#customBgFn));
-			else contentLines.push(lineWithMargins + padding(Math.max(0, width - visibleWidth(lineWithMargins))));
+			// A wrapped grapheme can still be wider than the viewport. Measure once,
+			// then slice instead of padding. Background functions do not change width.
+			const measured = visibleWidth(lineWithMargins);
+			const fitted =
+				measured > width
+					? sliceByColumn(lineWithMargins, 0, width, true)
+					: lineWithMargins + padding(width - measured);
+			contentLines.push(this.#customBgFn ? this.#customBgFn(fitted) : fitted);
 		}
 		const emptyLine = padding(width);
 		const emptyLines = Array.from({ length: this.#paddingY }, () =>

package/src/tui.ts

@@ -821,6 +821,16 @@ type TuiRenderCounterSnapshot = {
 	widthReflowScanRows: number;
 	widthReflowVisibleWidthCalls: number;
 	kittyPlacementScanRows: number;
+	kittyPlacementReferenceRows: number;
+	/** Rows copied into the frame while the render scope is layout-only. */
+	layoutAssemblyRows: number;
+	/** Off-screen prefix comparisons performed by a layout-only frame. */
+	layoutOffscreenPrefixCompares: number;
+	/**
+	 * Stable prefix rows copied into a fresh layout frame. Zero when the spare prefix is reused.
+	 * The fresh slice also copies the viewport window, which is rewritten immediately.
+	 */
+	layoutPrefixLineCopies: number;
 };
 type RenderCommitWaiter = {
 	resolve: (committed: boolean) => void;
@@ -995,6 +1005,12 @@ export class TUI extends Container {
 	#latestRenderedPlacementOwners = new Map<string, KittyPlacementOwner>();
 	#kittyPlacementSpans: KittyPlacementSpan[] = [];
 	#latestRaw: string[] = [];
+	// Spare frame for a repeated layout tick. Its off-screen prefix is the prefix of the
+	// frame that last took this path, so only the viewport window is rewritten.
+	#layoutSpareRaw: string[] | null = null;
+	#layoutSpareRendered: string[] | null = null;
+	#layoutSpareValid = false;
+	static #viewportNormalizeOverscan = 8;
 	#durableLineCount = 0;
 	#durableRenderedLines: string[] = [];
 	#durableRawLines: string[] = [];
@@ -1187,6 +1203,10 @@ export class TUI extends Container {
 		widthReflowScanRows: 0,
 		widthReflowVisibleWidthCalls: 0,
 		kittyPlacementScanRows: 0,
+		kittyPlacementReferenceRows: 0,
+		layoutAssemblyRows: 0,
+		layoutOffscreenPrefixCompares: 0,
+		layoutPrefixLineCopies: 0,
 	};
 
 	static resetRenderCountersForTest(): void {
@@ -1197,6 +1217,10 @@ export class TUI extends Container {
 			widthReflowScanRows: 0,
 			widthReflowVisibleWidthCalls: 0,
 			kittyPlacementScanRows: 0,
+			kittyPlacementReferenceRows: 0,
+			layoutAssemblyRows: 0,
+			layoutOffscreenPrefixCompares: 0,
+			layoutPrefixLineCopies: 0,
 		};
 	}
 
@@ -1204,6 +1228,10 @@ export class TUI extends Container {
 		return { ...TUI.#renderCounters };
 	}
 
+	getRenderedLineForTest(index: number): string | undefined {
+		return this.#latestRenderedLines[index];
+	}
+
 	getRenderPreparationStateForTest(): { pending: number; holes: number; failedRanges: number } {
 		return {
 			pending: this.#preparationBlocked.size,
@@ -2858,6 +2886,9 @@ export class TUI extends Container {
 		this.#latestRenderedLines = [];
 		this.#kittyPlacementSpans = [];
 		this.#latestRaw = [];
+		this.#layoutSpareRaw = null;
+		this.#layoutSpareRendered = null;
+		this.#layoutSpareValid = false;
 		this.#durableLineCount = 0;
 		this.#nativeScrollbackAdmissionPending = false;
 		this.#durableRenderedLines.length = 0;
@@ -4567,8 +4598,97 @@ export class TUI extends Container {
 		this.#recordPaintedViewportObservation(this.#viewportTopRow, height, false);
 	}
 
+	/**
+	 * Reuse the committed off-screen prefix when a layout tick's cached transcript still
+	 * matches it by reference. Only the viewport window is copied and normalized.
+	 * Returns null when that prefix changed so the caller keeps the full-frame path.
+	 */
+	#reuseCachedLayoutPrefix(
+		width: number,
+		height: number,
+		beforeLines: string[],
+		anchorLines: string[],
+		afterLines: string[],
+		spareValid: boolean,
+	): {
+		newLines: string[];
+		rawLines: string[];
+		diffStart: number;
+		cursorPos: { row: number; col: number } | null;
+	} | null {
+		const total = beforeLines.length + anchorLines.length + afterLines.length;
+		if (total === 0 || this.#latestRaw.length !== total || this.#latestRenderedLines.length !== total) return null;
+		const winTop = Math.max(0, total - height - TUI.#viewportNormalizeOverscan);
+		const prefixLength = beforeLines.length + anchorLines.length;
+		const anchorOverrides = new Map<number, string>();
+		const rawAt = (index: number): string => {
+			if (index < beforeLines.length) return beforeLines[index] ?? "";
+			if (index < prefixLength) {
+				const anchorIndex = index - beforeLines.length;
+				return anchorOverrides.get(anchorIndex) ?? anchorLines[anchorIndex] ?? "";
+			}
+			return afterLines[index - prefixLength] ?? "";
+		};
+		const scanStart = Math.max(0, total - height);
+		const bottom: string[] = [];
+		for (let row = scanStart; row < total; row++) bottom.push(rawAt(row));
+		const extracted = this.#extractCursorPosition(bottom, bottom.length);
+		for (let index = 0; index < bottom.length; index++) {
+			const row = scanStart + index;
+			const updated = bottom[index];
+			if (updated === undefined || updated === rawAt(row)) continue;
+			if (row < beforeLines.length) beforeLines[row] = updated;
+			else if (row < prefixLength) anchorOverrides.set(row - beforeLines.length, updated);
+			else afterLines[row - prefixLength] = updated;
+		}
+		let stable = winTop <= this.#latestRaw.length;
+		let compared = 0;
+		for (let index = 0; stable && index < winTop; index++) {
+			compared += 1;
+			if (rawAt(index) !== this.#latestRaw[index]) stable = false;
+		}
+		if (!stable) return null;
+		TUI.#renderCounters.layoutOffscreenPrefixCompares += compared;
+
+		const spareRaw = this.#layoutSpareRaw;
+		const spareRendered = this.#layoutSpareRendered;
+		let nextRaw: string[];
+		let nextRendered: string[];
+		if (
+			spareValid &&
+			spareRaw !== null &&
+			spareRendered !== null &&
+			spareRaw.length === total &&
+			spareRendered.length === total &&
+			spareRaw !== this.#latestRaw &&
+			spareRendered !== this.#latestRenderedLines &&
+			spareRendered !== this.#previousLines
+		) {
+			nextRaw = spareRaw;
+			nextRendered = spareRendered;
+		} else {
+			nextRaw = this.#latestRaw.slice();
+			nextRendered = this.#latestRenderedLines.slice();
+			TUI.#renderCounters.layoutPrefixLineCopies += winTop;
+		}
+		for (let index = winTop; index < total; index++) {
+			const rawLine = rawAt(index);
+			nextRaw[index] = rawLine;
+			nextRendered[index] = rawLine;
+		}
+		this.#normalizeLinesForEmit(nextRendered, width, winTop);
+		this.#trimLineCachesForRender(total);
+		this.#layoutSpareRaw = this.#latestRaw;
+		this.#layoutSpareRendered = this.#latestRenderedLines;
+		this.#layoutSpareValid = true;
+		const cursorPos = extracted === null ? null : { row: extracted.row + scanStart, col: extracted.col };
+		return { newLines: nextRendered, rawLines: nextRaw, diffStart: winTop, cursorPos };
+	}
+
 	#doRender(): void {
 		if (this.#stopped || !this.terminalAvailable) return;
+		const layoutSpareValid = this.#layoutSpareValid;
+		this.#layoutSpareValid = false;
 		const transcriptIdentityReplaced = this.#transcriptIdentityReplaced;
 		const restartViewportRepaintPending = this.#restartViewportRepaintPending;
 		const resizeRenderMutationQueued = this.#resizeRenderMutationQueued;
@@ -4595,9 +4715,22 @@ export class TUI extends Container {
 		const renderTreeStart = renderMetrics.now();
 		const renderScope = this.#renderScope;
 		this.#renderScope = "full";
-		const renderedLines: string[] = [];
+		let renderedLines: string[] = [];
 		const renderedChildren = new Map<Component, string[]>();
 		let anchorFrame: ViewportAnchorFrame | null = null;
+		let reusedAnchor: { start: number; lines: string[] } | null = null;
+		const layoutPrefixEligible =
+			renderScope === "layout" &&
+			this.#virtualViewport &&
+			this.#previousWidth === width &&
+			this.#previousWidth !== 0 &&
+			this.#previousHeight === height &&
+			this.overlayStack.length === 0 &&
+			!this.#mouseSelectionActive &&
+			this.#manualViewportTop === undefined &&
+			this.#latestRaw.length > 0 &&
+			this.#latestRenderedLines.length === this.#latestRaw.length &&
+			this.#previousLines === this.#latestRenderedLines;
 		let previousKittyPlacementSpans = this.#kittyPlacementSpans;
 		const placementOwners = new Map<string, KittyPlacementOwner>();
 		const pinnedChildIndex =
@@ -4624,7 +4757,12 @@ export class TUI extends Container {
 			const safeLines = reuseCached ? cached.safeLines : rendered.lines.map(stripTerminalEraseControls);
 			const kittyPlacements = reuseCached
 				? cached.kittyPlacements
-				: rendered.lines.map(line => [...extractKittyPlacementReferences(line)]);
+				: TERMINAL.imageProtocol === ImageProtocol.Kitty
+					? rendered.lines.map(line => {
+							TUI.#renderCounters.kittyPlacementReferenceRows++;
+							return [...extractKittyPlacementReferences(line)];
+						})
+					: [];
 			if (!reuseCached && componentRevision !== undefined && source !== null) {
 				this.#viewportAnchorRenderCache = {
 					component: child,
@@ -4643,48 +4781,49 @@ export class TUI extends Container {
 				anchorFrame = { startRow: childStart, anchors: rendered.anchors };
 			}
 			const owner: KittyPlacementOwner = hasStickySuffix && childIndex >= pinnedChildIndex ? "suffix" : "transcript";
+			if (layoutPrefixEligible && reuseCached) {
+				reusedAnchor = { start: childStart, lines: safeLines };
+				if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
+					for (let lineIndex = 0; lineIndex < rendered.lines.length; lineIndex++) {
+						const placements = kittyPlacements[lineIndex];
+						if (placements !== undefined) {
+							for (const placement of placements) {
+								placementOwners.set(this.#kittyPlacementKey(placement), owner);
+							}
+						}
+					}
+				}
+				continue;
+			}
 			for (let lineIndex = 0; lineIndex < rendered.lines.length; lineIndex++) {
-				for (const placement of kittyPlacements[lineIndex] ?? []) {
-					placementOwners.set(this.#kittyPlacementKey(placement), owner);
+				const placements = kittyPlacements[lineIndex];
+				if (placements !== undefined) {
+					for (const placement of placements) {
+						placementOwners.set(this.#kittyPlacementKey(placement), owner);
+					}
 				}
 				renderedLines.push(safeLines[lineIndex] ?? rendered.lines[lineIndex]!);
+				if (renderScope === "layout") TUI.#renderCounters.layoutAssemblyRows += 1;
 			}
 		}
+		const frameLineCount = renderedLines.length + (reusedAnchor?.lines.length ?? 0);
 		const sourceTranscriptLineCount = hasStickySuffix
 			? this.children
 					.slice(0, pinnedChildIndex)
 					.reduce((count, child) => count + this.#pinnedChildLines(child, renderedChildren).length, 0)
-			: renderedLines.length;
+			: frameLineCount;
 		const anchorRenderFailed = viewportAnchorRenderFailureCount !== anchorRenderFailureCountBefore;
-		let newLines = this.#constrainPinnedSuffix(renderedLines, height, renderedChildren);
 		this.#viewportAnchorFrame = anchorFrame;
 		if (renderMetrics.enabled) renderMetrics.recordHelper("renderTree", renderMetrics.now() - renderTreeStart);
-
-		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, placementOwners);
+		let suffixRowCount = 0;
+		if (hasStickySuffix) {
+			for (let index = pinnedChildIndex; index < this.children.length; index++) {
+				suffixRowCount += this.#pinnedChildLines(this.children[index]!, renderedChildren).length;
+			}
 		}
+		const layoutPrefixBlocked =
+			hasStickySuffix && (suffixRowCount > height || (height > 0 && frameLineCount < height));
 
-		// Extract cursor position (marker must be found before diff comparison)
-		const cursorPos = this.#extractCursorPosition(newLines, height);
-		this.#lastCursorPosition = cursorPos;
-
-		newLines = this.#applyMouseSelection(newLines);
-
-		// Terminate every non-image line so the latest frame mirrors emitted bytes
-		// (closes SGR + OSC 8 hyperlink state). Must run after cursor extraction
-		// because the marker is embedded mid-line, and before any diff/full render
-		// path so cache comparisons stay byte-accurate.
 		// Width/height change detection (used for normalization reuse and repaint decisions).
 		const widthChanged = this.#previousWidth !== 0 && this.#previousWidth !== width;
 		const widthMetadataChanged = this.#previousWidth > 0 && this.#previousWidth !== width;
@@ -4697,49 +4836,114 @@ export class TUI extends Container {
 		const heightChanged = this.#previousHeight !== 0 && this.#previousHeight !== height;
 		const initialRender = this.#previousLines.length === 0 && this.#maxLinesRendered === 0;
 		let coalescedWidthAppend = false;
-
-		// 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).
-		const VIEWPORT_NORMALIZE_OVERSCAN = 8;
-		const rawLines = newLines.slice();
-		const total = rawLines.length;
+		const VIEWPORT_NORMALIZE_OVERSCAN = TUI.#viewportNormalizeOverscan;
+		let newLines = renderedLines;
+		let rawLines = renderedLines;
+		let cursorPos: { row: number; col: number } | null = null;
 		let diffStart = 0;
 		let usedWindowNormalize = false;
-		if (
-			this.#virtualViewport &&
-			!widthChanged &&
-			this.#latestRaw.length > 0 &&
-			this.#latestRenderedLines.length === this.#latestRaw.length
-		) {
-			const winTop = Math.max(0, total - height - VIEWPORT_NORMALIZE_OVERSCAN);
-			if (winTop <= this.#latestRenderedLines.length && winTop <= this.#latestRaw.length) {
-				let stable = true;
-				for (let i = 0; i < winTop; i++) {
-					if (rawLines[i] !== this.#latestRaw[i]) {
-						stable = false;
-						break;
-					}
+		let stitched = false;
+		if (reusedAnchor !== null && layoutPrefixEligible && !layoutPrefixBlocked) {
+			const reused = this.#reuseCachedLayoutPrefix(
+				width,
+				height,
+				renderedLines.slice(0, reusedAnchor.start),
+				reusedAnchor.lines,
+				renderedLines.slice(reusedAnchor.start),
+				layoutSpareValid,
+			);
+			if (reused !== null) {
+				stitched = true;
+				newLines = reused.newLines;
+				rawLines = reused.rawLines;
+				cursorPos = reused.cursorPos;
+				diffStart = reused.diffStart;
+				usedWindowNormalize = true;
+			}
+		}
+		if (!stitched) {
+			this.#layoutSpareRaw = null;
+			this.#layoutSpareRendered = null;
+			if (reusedAnchor !== null) {
+				if (renderScope === "layout") TUI.#renderCounters.layoutAssemblyRows += reusedAnchor.lines.length;
+				const anchorLineCount = reusedAnchor.lines.length;
+				const merged = new Array<string>(renderedLines.length + anchorLineCount);
+				for (let index = 0; index < reusedAnchor.start; index++) merged[index] = renderedLines[index]!;
+				for (let index = 0; index < anchorLineCount; index++) {
+					merged[reusedAnchor.start + index] = reusedAnchor.lines[index]!;
 				}
-				if (stable) {
-					const windowed = this.#latestRenderedLines.slice(0, winTop);
-					for (let i = winTop; i < total; i++) {
-						windowed.push(rawLines[i]);
+				const afterCount = renderedLines.length - reusedAnchor.start;
+				for (let index = 0; index < afterCount; index++) {
+					merged[reusedAnchor.start + anchorLineCount + index] = renderedLines[reusedAnchor.start + index]!;
+				}
+				renderedLines = merged;
+			}
+			newLines = this.#constrainPinnedSuffix(renderedLines, 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)
+			if (this.overlayStack.length > 0) {
+				newLines = this.#compositeOverlays(newLines, width, height, placementOwners);
+			}
+			// Extract cursor position (marker must be found before diff comparison)
+			cursorPos = this.#extractCursorPosition(newLines, height);
+			newLines = this.#applyMouseSelection(newLines);
+			// Terminate every non-image line so the latest frame mirrors emitted bytes
+			// (closes SGR + OSC 8 hyperlink state). Must run after cursor extraction
+			// because the marker is embedded mid-line, and before any diff/full render
+			// path so cache comparisons stay byte-accurate.
+			// Reassigned below, never mutated in place -- a reference is the snapshot.
+			rawLines = newLines;
+			diffStart = 0;
+			usedWindowNormalize = false;
+			// 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).
+			if (
+				this.#virtualViewport &&
+				!widthChanged &&
+				this.#latestRaw.length > 0 &&
+				this.#latestRenderedLines.length === this.#latestRaw.length
+			) {
+				const winTop = Math.max(0, rawLines.length - height - VIEWPORT_NORMALIZE_OVERSCAN);
+				if (winTop <= this.#latestRenderedLines.length && winTop <= this.#latestRaw.length) {
+					let stable = true;
+					for (let i = 0; i < winTop; i++) {
+						if (renderScope === "layout") TUI.#renderCounters.layoutOffscreenPrefixCompares += 1;
+						if (rawLines[i] !== this.#latestRaw[i]) {
+							stable = false;
+							break;
+						}
+					}
+					if (stable) {
+						const windowed = this.#latestRenderedLines.slice(0, winTop);
+						for (let i = winTop; i < rawLines.length; i++) {
+							windowed.push(rawLines[i]!);
+						}
+						this.#normalizeLinesForEmit(windowed, width, winTop);
+						this.#trimLineCachesForRender(rawLines.length);
+						newLines = windowed;
+						diffStart = winTop;
+						usedWindowNormalize = true;
 					}
-					this.#normalizeLinesForEmit(windowed, width, winTop);
-					this.#trimLineCachesForRender(total);
-					newLines = windowed;
-					diffStart = winTop;
-					usedWindowNormalize = true;
 				}
 			}
+			if (!usedWindowNormalize) {
+				newLines = this.#applyLineResetsAndTruncate(rawLines.slice(), width);
+			}
 		}
-		if (!usedWindowNormalize) {
-			newLines = this.#applyLineResetsAndTruncate(rawLines.slice(), width);
-		}
+		const nextTranscriptLineCount = sourceTranscriptLineCount;
+		const nextSuffixLineCount = hasStickySuffix ? Math.max(0, newLines.length - nextTranscriptLineCount) : 0;
+		this.#lastCursorPosition = cursorPos;
+		const total = rawLines.length;
 		if (renderMetrics.enabled) {
 			renderMetrics.recordLineCount("rendered", total);
 			renderMetrics.recordLineCount("normalized", total - diffStart);