@gajae-code/tui 0.16.3 → 0.16.6

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [0.16.6] - 2026-09-07
+
+## [0.16.5] - 2026-09-07
+
+### Performance
+
+- Skip full-transcript resize-width scans on unchanged-width render frames while preserving the existing resize and forced-redraw checks.
+- Avoid copying unchanged terminal-control spans, reuse retained row widths, consume only the first grapheme for cursor operations, stop select-list width scans at their bounds, and avoid redundant background-row padding.
+
+### Fixed
+
+- Markdown cache ownership now finalizes after styling callbacks, so reentrant text replacement cannot inherit stale rejection hints and streaming completion releases local parse tokens. Cache diagnostics measure insertion-time payload sizes; returned render arrays are borrowed and must not be mutated.
+- Streaming Markdown retains only its current parse locally instead of publishing partial documents to the shared render/parse caches. Completed documents remain reusable, with 8 MiB render, 8 MiB parse and 4 MiB highlight accounted-payload budgets and per-entry limits. The render-cache diagnostic now includes UTF-16 keys, full token graphs, styled lines and anchors; it is not a live heap/RSS measurement.
+- Markdown reflow avoids redundant parse-cache admissions and repeated accounting of already rejected normalized content, without retaining completed parse tokens. Render payload accounting uses its owned layout schema, and oversized highlighting inputs are rejected earlier while preserving byte/line limits and guard ordering.
+
+## [0.16.4] - 2026-09-05
+
+### Added
+
+- Added cancellable, one-shot `enqueueBeforeRender` preparation on the existing frame scheduler and a single-owner `setRenderPreparationLifecycleCallbacks` seam for invalidation and restart preparation. Stop, terminal loss, and disposal cancel stale work; restart preparation runs before the first forced frame without adding another streaming timer.
+
 ## [0.16.3] - 2026-09-04
 
 ## [0.16.2] - 2026-09-04

package/README.md

@@ -44,6 +44,60 @@ tui.start();
 
 Main container that manages components and rendering.
 
+#### Frame preparation
+
+`tui.enqueueBeforeRender(callback: () => void): () => void` registers one synchronous,
+one-shot preparation and returns an idempotent cancellation function. It requests a
+normal full-mutation render on the existing 16 ms frame clock; it adds no timer and
+does not force or expedite a frame. Normal, forced, and input-priority frames drain
+the same snapshot before capturing render generations or reading layout, components,
+viewport sources, or caches. Ordinary render requests made by preparation join that
+frame without a request-only follow-up paint. Registrations made while draining run
+in a later frame; their generations cannot commit before that preparation executes,
+even when a newer ordinary request commits first or terminal output is queued.
+
+Cancellation removes callback references, including entries already captured but
+not yet invoked. Retained cancellation handles release their reference to the TUI
+and callback on cancellation, invocation (including failure), or lifecycle
+invalidation. Later cancellation calls are no-ops; an executing callback remains
+live until its synchronous invocation returns. Preparation exceptions are logged, unrelated callbacks continue,
+and the failed preparation's generation is not reported as successfully committed.
+Throwing or lifecycle-invalidated preparations immediately resolve their existing
+commit waiters `false`; late waiters for those generations also resolve `false`,
+even after a newer successful frame. Retired generations are stored as merged,
+sorted failure ranges, separate from live pending-frame exclusions. Contiguous
+failures compact into one range; separated failures retain distinct ranges to
+preserve exact outcomes. Historical failure ranges are not copied or scanned on
+each frame (waiter lookup uses binary search).
+History has no arbitrary expiry: its numeric storage is O(disjoint failed ranges),
+not bounded over an indefinitely alternating failure/success session. Empty active
+pending and hole sets do not imply bounded historical storage or prove leak freedom.
+Callbacks must be synchronous (do not pass async functions).
+
+The cancellation lifetime regression inspects Bun's heap snapshot for outgoing
+local closure/entry paths to the owner, callback and payload, while all targets
+remain deliberately rooted. Pending handles and an intentionally retaining arrow
+are positive controls; retired handles must lose those paths. This checks reference
+release without assuming when GC collects an object. It does not prove global leak
+freedom or exclude unrelated module, runtime or test-runner roots.
+
+`tui.setRenderPreparationLifecycleCallbacks(callbacks: { invalidate: () => void;
+beforeStart: () => void } | undefined): void` installs a **single** preparation owner.
+Replacing or clearing the owner invalidates its old queued and captured work and
+calls its `invalidate` synchronously. Stop, terminal loss, and disposal do the same;
+exceptions are logged without preventing cancellation. Disposal also clears the
+owner. Enqueue while stopped, unavailable, invalidating, or disposed retains no work.
+Disposal cancels pending render/width-settle timers and render requests; later normal,
+forced, input-priority, and resize requests cannot rearm the disposed renderer.
+
+After successful terminal setup, each `start()` calls `beforeStart` synchronously
+before its first forced render request. The owner can enqueue fresh preparation
+from its current authoritative state there, so restarting does not require another
+provider event. Failed setup does not rearm work; a throwing `beforeStart` is logged
+and its queued work is invalidated. Stop/start during a drain cannot revive that
+drain's old snapshot. This API is only a presentation-preparation lifecycle seam,
+not a general lifecycle event bus.
+
 ```typescript
 const tui = new TUI(terminal);
 tui.addChild(component);

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

@@ -1,8 +1,19 @@
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
 import { type ViewportAnchorSpan } from "../utils";
+/** Account retained payload, not live heap. Stop once admission is impossible. */
+export declare function getMarkdownCacheEntryAccountedSize(key: string, value: unknown, cap: number): number;
 /** Test-only clock seam for streaming throttle tests. */
 export declare function __setMarkdownNowForTest(now: (() => number) | undefined): void;
+export interface MarkdownCacheStats {
+    count: number;
+    accountedSize: number;
+    max: number;
+    maxSize: number;
+    maxEntrySize: number;
+}
+/** Detached diagnostics; exposes neither entries nor mutable budgets. */
+export declare function getMarkdownCacheStats(): Record<"render" | "parse" | "highlight", MarkdownCacheStats>;
 /** Test/diagnostic seam: number of synchronous highlight invocations since the last reset. */
 export declare function getMarkdownHighlightCallCount(): number;
 export declare function resetMarkdownHighlightCallCount(): void;
@@ -14,6 +25,10 @@ export declare const __markdownPerfCounters: {
 };
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export declare function clearRenderCache(): void;
+/**
+ * Insertion-time UTF-16 accounting of global keys/tokens/lines/anchors, not heap or RSS.
+ * Rendered arrays are borrowed cache payloads: callers must not mutate them.
+ */
 export declare function getRenderCacheRetainedBytes(): number;
 /**
  * Default text styling for markdown content.

package/dist/types/components/settings-list.d.ts

@@ -23,6 +23,7 @@ export interface SettingsListTheme {
 export declare class SettingsList implements Component {
     #private;
     constructor(items: SettingItem[], maxVisible: number, theme: SettingsListTheme, onChange: (id: string, newValue: string) => void, onCancel: () => void, onSelectionChange?: (item: SettingItem | undefined) => void, descriptionRows?: number);
+    get navigationLocked(): boolean;
     /** Update an item's currentValue */
     updateValue(id: string, newValue: string): void;
     /**

package/dist/types/tui.d.ts

@@ -361,6 +361,7 @@ type TuiRenderCounterSnapshot = {
     debugRedrawEnvReads: number;
     debugRedrawAppendWrites: number;
     differentialGuardVisibleWidthCalls: number;
+    widthReflowScanRows: number;
 };
 /**
  * TUI - Main class for managing terminal UI with differential rendering
@@ -373,6 +374,11 @@ export declare class TUI extends Container {
     onDebug?: () => void;
     static resetRenderCountersForTest(): void;
     static getRenderCountersForTest(): TuiRenderCounterSnapshot;
+    getRenderPreparationStateForTest(): {
+        pending: number;
+        holes: number;
+        failedRanges: number;
+    };
     overlayStack: {
         component: Component;
         options?: OverlayOptions;
@@ -495,6 +501,13 @@ export declare class TUI extends Container {
      */
     requestResizeRender(): void;
     requestRender(force?: boolean, source?: string): void;
+    /** Queue one synchronous preparation on the existing frame clock. Cancellation is idempotent. */
+    enqueueBeforeRender(callback: () => void): () => void;
+    /** One owner only: replacing or clearing it invalidates all old preparation work. */
+    setRenderPreparationLifecycleCallbacks(callbacks: {
+        invalidate: () => void;
+        beforeStart: () => void;
+    } | undefined): void;
     /** Request a frame whose mutation is known to be outside the viewport-anchor subtree. */
     requestLayoutRender(source?: string): void;
     requestRenderWithGeneration(force?: boolean, source?: string): number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.16.3",
+	"version": "0.16.6",
 	"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.16.3",
-		"@gajae-code/utils": "0.16.3",
+		"@gajae-code/natives": "0.16.6",
+		"@gajae-code/utils": "0.16.6",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/components/box.ts

@@ -161,13 +161,13 @@ export class Box implements Component {
 	}
 
 	#applyBg(line: string, width: number): string {
+		if (this.#bgFn) {
+			return applyBackgroundToLine(line, width, this.#bgFn);
+		}
 		const visLen = visibleWidth(line);
 		const padNeeded = Math.max(0, width - visLen);
 		const padded = line + padding(padNeeded);
 
-		if (this.#bgFn) {
-			return applyBackgroundToLine(padded, width, this.#bgFn);
-		}
 		return padded;
 	}
 }

package/src/components/editor.ts

@@ -1061,8 +1061,7 @@ export class Editor implements Component, Focusable {
 				if (after.length > 0) {
 					// Cursor is on a character (grapheme) - replace it with highlighted version
 					// Get the first grapheme from 'after'
-					const afterGraphemes = [...segmenter.segment(after)];
-					const firstGrapheme = afterGraphemes[0]?.segment || "";
+					const firstGrapheme = segmenter.segment(after)[Symbol.iterator]().next().value?.segment || "";
 					const restAfter = after.slice(firstGrapheme.length);
 					const cursor = `\x1b[7m${firstGrapheme}\x1b[0m`;
 					displayText = before + marker + cursor + restAfter;
@@ -2643,8 +2642,7 @@ export class Editor implements Component, Focusable {
 			const afterCursor = currentLine.slice(this.#state.cursorCol);
 
 			// Find the first grapheme at cursor
-			const graphemes = [...segmenter.segment(afterCursor)];
-			const firstGrapheme = graphemes[0];
+			const firstGrapheme = segmenter.segment(afterCursor)[Symbol.iterator]().next().value;
 			const graphemeLength = firstGrapheme ? firstGrapheme.segment.length : 1;
 
 			const before = currentLine.slice(0, this.#state.cursorCol);
@@ -2762,8 +2760,7 @@ export class Editor implements Component, Focusable {
 						this.#setCursorCol(this.#state.cursorCol + 1);
 					} else {
 						const afterCursor = currentLine.slice(this.#state.cursorCol);
-						const graphemes = [...segmenter.segment(afterCursor)];
-						const firstGrapheme = graphemes[0];
+						const firstGrapheme = segmenter.segment(afterCursor)[Symbol.iterator]().next().value;
 						this.#setCursorCol(this.#state.cursorCol + (firstGrapheme ? firstGrapheme.segment.length : 1));
 					}
 				} else if (this.#state.cursorLine < this.#state.lines.length - 1) {

package/src/components/input.ts

@@ -156,8 +156,7 @@ export class Input implements Component, Focusable {
 			this.#lastAction = null;
 			if (this.#cursor < this.#value.length) {
 				const afterCursor = this.#value.slice(this.#cursor);
-				const graphemes = [...segmenter.segment(afterCursor)];
-				const firstGrapheme = graphemes[0];
+				const firstGrapheme = segmenter.segment(afterCursor)[Symbol.iterator]().next().value;
 				this.#cursor += firstGrapheme ? firstGrapheme.segment.length : 1;
 			}
 			return;
@@ -231,8 +230,7 @@ export class Input implements Component, Focusable {
 		this.#pushUndo();
 
 		const afterCursor = this.#value.slice(this.#cursor);
-		const graphemes = [...segmenter.segment(afterCursor)];
-		const firstGrapheme = graphemes[0];
+		const firstGrapheme = segmenter.segment(afterCursor)[Symbol.iterator]().next().value;
 		const graphemeLength = firstGrapheme ? firstGrapheme.segment.length : 1;
 
 		this.#value = this.#value.slice(0, this.#cursor) + this.#value.slice(this.#cursor + graphemeLength);
@@ -442,8 +440,7 @@ export class Input implements Component, Focusable {
 
 		// Build line with fake cursor
 		// Insert cursor character at cursor position
-		const graphemes = [...segmenter.segment(visibleText.slice(cursorDisplay))];
-		const cursorGrapheme = graphemes[0];
+		const cursorGrapheme = segmenter.segment(visibleText.slice(cursorDisplay))[Symbol.iterator]().next().value;
 
 		const beforeCursor = visibleText.slice(0, cursorDisplay);
 		const atCursor = cursorGrapheme?.segment ?? " ";

package/src/components/markdown.ts

@@ -46,14 +46,95 @@ markdownParser.setOptions({
 // (Rust FFI) work for content/layout combinations already seen this session.
 
 const RENDER_CACHE_MAX = 256; // sane cap: ~256 distinct message × width combos
-const renderCache = new LRUCache<
-	string,
-	{ source: string; lines: string[]; anchorSpans?: Array<ViewportAnchorSpan | null> }
->({
+const DOCUMENT_CACHE_SIZE = 8 * 1024 * 1024;
+const DOCUMENT_ENTRY_SIZE = 1024 * 1024;
+
+/** Account retained payload, not live heap. Stop once admission is impossible. */
+export function getMarkdownCacheEntryAccountedSize(key: string, value: unknown, cap: number): number {
+	let size = 64 + key.length * 2;
+	const visited = new Set<object>();
+	const pending: Iterator<unknown>[] = [[value][Symbol.iterator]()];
+	function* objects(object: object, array: boolean): Generator<object> {
+		for (const name in object) {
+			if (!Object.hasOwn(object, name)) continue;
+			// Array indices are canonical uint32 strings, excluding 2^32 - 1.
+			const index = array ? Number(name) >>> 0 : 0;
+			if (!array || index === 0xffffffff || String(index) !== name) {
+				size += 16 + name.length * 2;
+				if (size > cap) return;
+			}
+			const child = (object as Record<string, unknown>)[name];
+			if (typeof child === "string") size += child.length * 2;
+			else if (typeof child === "number") size += 8;
+			else if (typeof child === "boolean") size += 4;
+			else if (child !== null && typeof child === "object") yield child;
+			if (size > cap) return;
+		}
+	}
+	while (pending.length && size <= cap) {
+		const next = pending[pending.length - 1].next();
+		if (next.done) {
+			pending.pop();
+			continue;
+		}
+		const item = next.value;
+		if (typeof item === "string") size += item.length * 2;
+		else if (typeof item === "number") size += 8;
+		else if (typeof item === "boolean") size += 4;
+		else if (item !== null && typeof item === "object" && !visited.has(item)) {
+			visited.add(item);
+			const array = Array.isArray(item);
+			size += array ? 24 + item.length * 8 : 32;
+			if (size <= cap) pending.push(objects(item, array));
+		}
+	}
+	return size > cap ? cap + 1 : size;
+}
+
+interface MarkdownRenderCacheEntry {
+	source: string;
+	lines: string[];
+	anchorSpans?: Array<ViewportAnchorSpan | null>;
+}
+
+const RENDER_ENTRY_BASE_SIZE = 64 + 32 + 16 + "source".length * 2 + 16 + "lines".length * 2 + 24;
+const ANCHOR_SPAN_SIZE =
+	32 + 4 * 16 + 4 * 8 + 2 * ("graphemeStart".length + "graphemeEnd".length + "cellStart".length + "cellEnd".length);
+
+function renderCacheEntrySize(entry: MarkdownRenderCacheEntry, key: string): number {
+	// These arrays and distinct span records are constructed exclusively by #render,
+	// with no custom properties, sharing or cycles. Account that owned schema without
+	// allocating the generic token-graph traversal machinery.
+	let size = RENDER_ENTRY_BASE_SIZE + key.length * 2 + entry.source.length * 2 + entry.lines.length * 8;
+	if (size > DOCUMENT_ENTRY_SIZE) return DOCUMENT_ENTRY_SIZE + 1;
+	for (const line of entry.lines) {
+		size += line.length * 2;
+		if (size > DOCUMENT_ENTRY_SIZE) return DOCUMENT_ENTRY_SIZE + 1;
+	}
+	if (entry.anchorSpans) {
+		size += 16 + "anchorSpans".length * 2 + 24 + entry.anchorSpans.length * 8;
+		if (size > DOCUMENT_ENTRY_SIZE) return DOCUMENT_ENTRY_SIZE + 1;
+		for (const span of entry.anchorSpans) {
+			if (span) size += ANCHOR_SPAN_SIZE;
+			if (size > DOCUMENT_ENTRY_SIZE) return DOCUMENT_ENTRY_SIZE + 1;
+		}
+	}
+	return size;
+}
+
+const renderCache = new LRUCache<string, MarkdownRenderCacheEntry>({
 	max: RENDER_CACHE_MAX,
+	maxSize: DOCUMENT_CACHE_SIZE,
+	maxEntrySize: DOCUMENT_ENTRY_SIZE,
+	sizeCalculation: renderCacheEntrySize,
 });
 const PARSE_CACHE_MAX = 128;
-const parseCache = new LRUCache<string, { source: string; tokens: Token[] }>({ max: PARSE_CACHE_MAX });
+const parseCache = new LRUCache<string, { source: string; tokens: Token[] }>({
+	max: PARSE_CACHE_MAX,
+	maxSize: DOCUMENT_CACHE_SIZE,
+	maxEntrySize: DOCUMENT_ENTRY_SIZE,
+	sizeCalculation: (value, key) => getMarkdownCacheEntryAccountedSize(key, value, DOCUMENT_ENTRY_SIZE),
+});
 const MARKDOWN_STREAM_THROTTLE_MS = 64;
 let markdownNow = (): number => performance.now();
 
@@ -76,20 +157,44 @@ export function __setMarkdownNowForTest(now: (() => number) | undefined): void {
 // appends only highlight new/changed blocks instead of re-highlighting the whole
 // prefix on every chunk. Bounded LRU; cleared on theme change via clearRenderCache().
 const HIGHLIGHT_CACHE_MAX = 512;
-const highlightCache = new LRUCache<string, string[]>({ max: HIGHLIGHT_CACHE_MAX });
+const HIGHLIGHT_ENTRY_SIZE = 512 * 1024;
+interface MarkdownHighlightCacheEntry {
+	lang: string;
+	code: string;
+	lines: string[];
+}
+
+const highlightCache = new LRUCache<string, MarkdownHighlightCacheEntry>({
+	max: HIGHLIGHT_CACHE_MAX,
+	maxSize: 4 * 1024 * 1024,
+	maxEntrySize: HIGHLIGHT_ENTRY_SIZE,
+	sizeCalculation: (value, key) => getMarkdownCacheEntryAccountedSize(key, value, HIGHLIGHT_ENTRY_SIZE),
+});
 
-function renderedLinesBytes(lines: readonly string[]): number {
-	let bytes = 0;
-	for (const line of lines) bytes += Buffer.byteLength(line, "utf8");
-	return bytes;
+export interface MarkdownCacheStats {
+	count: number;
+	accountedSize: number;
+	max: number;
+	maxSize: number;
+	maxEntrySize: number;
 }
 
-function anchorSpansBytes(spans: readonly (ViewportAnchorSpan | null)[]): number {
-	let bytes = spans.length * 8; // Array element references
-	for (const span of spans) {
-		if (span) bytes += 4 * 8; // Four numeric offsets
-	}
-	return bytes;
+/** Detached diagnostics; exposes neither entries nor mutable budgets. */
+export function getMarkdownCacheStats(): Record<"render" | "parse" | "highlight", MarkdownCacheStats> {
+	const snapshot = (cache: {
+		size: number;
+		calculatedSize: number;
+		max: number;
+		maxSize: number;
+		maxEntrySize: number;
+	}): MarkdownCacheStats => ({
+		count: cache.size,
+		accountedSize: cache.calculatedSize,
+		max: cache.max,
+		maxSize: cache.maxSize,
+		maxEntrySize: cache.maxEntrySize,
+	});
+	return { render: snapshot(renderCache), parse: snapshot(parseCache), highlight: snapshot(highlightCache) };
 }
 
 // F18: cap synchronous (Rust FFI) syntax highlighting so a single huge fenced block
@@ -133,16 +238,12 @@ export function clearRenderCache(): void {
 	highlightCache.clear();
 }
 
+/**
+ * Insertion-time UTF-16 accounting of global keys/tokens/lines/anchors, not heap or RSS.
+ * Rendered arrays are borrowed cache payloads: callers must not mutate them.
+ */
 export function getRenderCacheRetainedBytes(): number {
-	let bytes = 0;
-	for (const entry of renderCache.values()) {
-		bytes += Buffer.byteLength(entry.source, "utf8");
-		bytes += renderedLinesBytes(entry.lines);
-		if (entry.anchorSpans) bytes += anchorSpansBytes(entry.anchorSpans);
-	}
-	for (const entry of parseCache.values()) bytes += Buffer.byteLength(entry.source, "utf8");
-	for (const lines of highlightCache.values()) bytes += renderedLinesBytes(lines);
-	return bytes;
+	return renderCache.calculatedSize + parseCache.calculatedSize + highlightCache.calculatedSize;
 }
 
 // Stable numeric IDs for structural theme/style objects (no ID field on type).
@@ -267,6 +368,8 @@ export class Markdown implements Component {
 	#cachedWidth?: number;
 	#cachedLines?: string[];
 	#cachedAnchorSpans?: Array<ViewportAnchorSpan | null>;
+	#currentParse?: { source: string; tokens: Token[] };
+	#rejectedParseKey?: string;
 
 	#streaming = false;
 	#lastFullParseAt = 0;
@@ -297,6 +400,7 @@ export class Markdown implements Component {
 		if (options?.streaming !== undefined) {
 			this.setStreaming(options.streaming);
 		}
+		if (this.#text !== text) this.#rejectedParseKey = undefined;
 		this.#text = text;
 		if (this.#streaming) {
 			return;
@@ -336,6 +440,8 @@ export class Markdown implements Component {
 
 	dispose(): void {
 		this.#clearStaleThrottleTimer();
+		this.#currentParse = undefined;
+		this.#rejectedParseKey = undefined;
 	}
 
 	invalidate(): void {
@@ -346,14 +452,17 @@ export class Markdown implements Component {
 	}
 
 	#exceedsHighlightCap(code: string): boolean {
+		// 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;
+		// Check UTF-8 bytes before the JavaScript line scan so oversized Unicode
+		// blocks do not pay for a scan whose result cannot change rejection.
+		if (Buffer.byteLength(code, "utf8") > MAX_HIGHLIGHT_BYTES) return true;
 		let newlines = 0;
 		for (let i = 0; i < code.length; i++) {
-			if (code.charCodeAt(i) === 10) newlines += 1;
+			if (code.charCodeAt(i) === 10 && ++newlines >= MAX_HIGHLIGHT_LINES) return true;
 		}
-		if (newlines + 1 > MAX_HIGHLIGHT_LINES) return true;
-		// UTF-8 byte length (not UTF-16 code-unit count) so a non-ASCII block cannot
-		// exceed the advertised byte cap and still reach the synchronous highlighter.
-		return Buffer.byteLength(code, "utf8") > MAX_HIGHLIGHT_BYTES;
+		return false;
 	}
 
 	#highlightCodeBlock(code: string, lang: string): string[] | null {
@@ -361,10 +470,10 @@ export class Markdown implements Component {
 		if (this.#exceedsHighlightCap(code)) return null;
 		const key = `${objectId(this.#theme)}\x00${lang}\x00${code}`;
 		const cached = highlightCache.get(key);
-		if (cached) return cached;
+		if (cached?.lang === lang && cached.code === code) return cached.lines;
 		highlightCallCount += 1;
 		const result = this.#theme.highlightCode(code, lang || undefined);
-		highlightCache.set(key, result);
+		highlightCache.set(key, { lang, code, lines: result });
 		return result;
 	}
 
@@ -421,6 +530,7 @@ export class Markdown implements Component {
 
 		// Don't render anything if there's no actual text
 		if (!this.#text || this.#text.trim() === "") {
+			this.#currentParse = undefined;
 			const result: string[] = [];
 			// Update per-instance cache
 			this.#cachedText = this.#text;
@@ -430,8 +540,9 @@ export class Markdown implements Component {
 			return { lines: result, spans: this.#cachedAnchorSpans };
 		}
 
-		// Replace tabs with 3 spaces for consistent rendering
-		const normalizedText = replaceTabs(this.#text);
+		// Normalize tabs using the current configured indentation width.
+		const renderedText = this.#text;
+		const normalizedText = replaceTabs(renderedText);
 		this.#clearStaleThrottleTimer();
 		const contentKey = markdownContentKey(normalizedText);
 
@@ -450,10 +561,11 @@ export class Markdown implements Component {
 			(!includeAnchors || cached.anchorSpans !== undefined)
 		) {
 			// Populate L1 so subsequent calls from this instance are O(1) map lookup.
-			this.#cachedText = this.#text;
+			this.#cachedText = renderedText;
 			this.#cachedWidth = width;
 			this.#cachedLines = cached.lines;
 			this.#cachedAnchorSpans = cached.anchorSpans;
+			if (!this.#streaming || this.#currentParse?.source !== normalizedText) this.#currentParse = undefined;
 			return { lines: cached.lines, spans: cached.anchorSpans };
 		}
 
@@ -462,13 +574,17 @@ export class Markdown implements Component {
 		// final wrapped output must differ by width.
 		const cachedParse = parseCache.get(contentKey);
 		let tokens: Token[];
-		if (cachedParse !== undefined && cachedParse.source === normalizedText) {
+		if (this.#currentParse?.source === normalizedText) {
+			tokens = this.#currentParse.tokens;
+		} else if (cachedParse !== undefined && cachedParse.source === normalizedText) {
 			tokens = cachedParse.tokens;
 		} else {
 			__markdownPerfCounters.lexerInvocations += 1;
 			__markdownPerfCounters.lexedBytes += normalizedText.length;
 			tokens = markdownParser.lexer(normalizedText);
-			parseCache.set(contentKey, { source: normalizedText, tokens });
+		}
+		if (this.#streaming && this.#text === renderedText) {
+			this.#currentParse = { source: normalizedText, tokens };
 		}
 
 		// Convert tokens to styled terminal output. When anchoring, record each
@@ -615,8 +731,24 @@ export class Markdown implements Component {
 		const result = rawResult.length > 0 ? rawResult : [""];
 		const anchorSpans = rawResult.length > 0 ? rawAnchorSpans : wrappedSpans ? [null] : undefined;
 
+		// Styling callbacks may replace text or end streaming. Publish ownership
+		// only after they finish, and never attach an old rejection to new text.
+		if (!this.#streaming && this.#text === renderedText) {
+			const completedParse = parseCache.get(contentKey);
+			// Reparse rejected documents on reflow without retaining their tokens.
+			// Occupied collisions still retry admission to preserve replacement rules.
+			if (
+				completedParse?.source !== normalizedText &&
+				(this.#rejectedParseKey !== contentKey || completedParse !== undefined)
+			) {
+				parseCache.set(contentKey, { source: normalizedText, tokens });
+				this.#rejectedParseKey = parseCache.has(contentKey) ? undefined : contentKey;
+			}
+		}
+		if (!this.#streaming || this.#text !== renderedText) this.#currentParse = undefined;
+
 		// Update L1 per-instance cache
-		this.#cachedText = this.#text;
+		this.#cachedText = renderedText;
 		this.#cachedWidth = width;
 		this.#cachedLines = result;
 		this.#cachedAnchorSpans = anchorSpans;
@@ -624,7 +756,9 @@ export class Markdown implements Component {
 
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.
-		renderCache.set(cacheKey, { source: normalizedText, lines: result, ...(anchorSpans ? { anchorSpans } : {}) });
+		if (!this.#streaming) {
+			renderCache.set(cacheKey, { source: normalizedText, lines: result, ...(anchorSpans ? { anchorSpans } : {}) });
+		}
 
 		return { lines: result, spans: anchorSpans };
 	}

package/src/components/select-list.ts

@@ -241,9 +241,12 @@ export class SelectList implements Component {
 
 	#getPrimaryColumnWidth(): number {
 		const { min, max } = this.#getPrimaryColumnBounds();
-		const widestPrimary = this.#filteredItems.reduce((widest, item) => {
-			return Math.max(widest, visibleWidth(this.#getDisplayValue(item)) + PRIMARY_COLUMN_GAP);
-		}, 0);
+		if (min === max) return min;
+		let widestPrimary = 0;
+		for (const item of this.#filteredItems) {
+			widestPrimary = Math.max(widestPrimary, visibleWidth(this.#getDisplayValue(item)) + PRIMARY_COLUMN_GAP);
+			if (widestPrimary >= max) return max;
+		}
 
 		return clamp(widestPrimary, min, max);
 	}

package/src/components/settings-list.ts

@@ -62,6 +62,11 @@ export class SettingsList implements Component {
 		this.#notifySelectionChange();
 	}
 
+	get navigationLocked(): boolean {
+		const submenu = this.#submenuComponent as (Component & { navigationLocked?: boolean }) | null;
+		return submenu?.navigationLocked === true;
+	}
+
 	#clampSelectedIndex(): void {
 		if (this.#items.length === 0) {
 			this.#selectedIndex = 0;

package/src/tui.ts

@@ -147,15 +147,17 @@ function csiEnd(bytes: string, start: number): number | undefined {
  */
 function stripTerminalEraseControls(bytes: string): string {
 	let sanitized = "";
+	let spanStart = 0;
 	for (let index = 0; index < bytes.length; index += 1) {
 		const value = bytes.charCodeAt(index);
 		const isEscapeCsi = value === 0x1b && bytes.charCodeAt(index + 1) === 0x5b;
 		const isEightBitCsi = value === 0x9b;
-		if (value === 0x1b && index === bytes.length - 1) break;
-		if (!isEscapeCsi && !isEightBitCsi) {
-			sanitized += bytes[index];
-			continue;
+		if (value === 0x1b && index === bytes.length - 1) {
+			sanitized += bytes.slice(spanStart, index);
+			spanStart = bytes.length;
+			break;
 		}
+		if (!isEscapeCsi && !isEightBitCsi) continue;
 
 		const start = isEightBitCsi ? index + 1 : index + 2;
 		const end = csiEnd(bytes, start);
@@ -168,16 +170,19 @@ function stripTerminalEraseControls(bytes: string): string {
 				if (!CSI_PARAMETER(nextValue) && !CSI_INTERMEDIATE(nextValue)) break;
 				next += 1;
 			}
+			sanitized += bytes.slice(spanStart, index);
+			spanStart = next;
 			index = next - 1;
 			continue;
 		}
 		const final = bytes.charCodeAt(end);
-		if (final !== 0x4a && final !== 0x4b) {
-			sanitized += bytes.slice(index, end + 1);
+		if (final === 0x4a || final === 0x4b) {
+			sanitized += bytes.slice(spanStart, index);
+			spanStart = end + 1;
 		}
 		index = end;
 	}
-	return sanitized;
+	return spanStart === 0 ? bytes : sanitized + bytes.slice(spanStart);
 }
 type InputListenerResult = { consume?: boolean; data?: string } | undefined;
 type InputListener = (data: string) => InputListenerResult;
@@ -813,6 +818,7 @@ type TuiRenderCounterSnapshot = {
 	debugRedrawEnvReads: number;
 	debugRedrawAppendWrites: number;
 	differentialGuardVisibleWidthCalls: number;
+	widthReflowScanRows: number;
 };
 type RenderCommitWaiter = {
 	resolve: (committed: boolean) => void;
@@ -960,6 +966,20 @@ function hasDistinctPostContractionRows(
 	return false;
 }
 
+interface RenderPreparation {
+	callback?: () => void;
+	generation: number;
+	cancel?: () => void;
+}
+
+// Keep the public handle outside the enqueue scope: it must capture only the entry,
+// not the TUI or the original callback after the entry has been released.
+function createPreparationCancellation(entry: RenderPreparation): () => void {
+	return () => entry.cancel?.();
+}
+
+function cancelNoPreparation(): void {}
+
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -1009,6 +1029,21 @@ export class TUI extends Container {
 	#nextRenderGeneration = 0;
 	#renderRequestedGeneration = 0;
 	#committedRenderGeneration = 0;
+	#preparations = new Set<RenderPreparation>();
+	#preparationSnapshot: Set<RenderPreparation> | undefined;
+	#preparationEpoch = 0;
+	#preparationDrainEpoch = -1;
+	#preparationDisposed = false;
+	#preparationInvalidating = false;
+	#preparationLifecycle: { invalidate: () => void; beforeStart: () => void } | undefined;
+	// A newer ordinary request may commit while an older nested preparation is still pending.
+	// Keep holes in the high-water mark, including for waiters registered after that commit.
+	#preparationBlocked = new Set<number>();
+	#commitHoles = new Set<number>();
+	// Terminal failures are sorted, disjoint inclusive ranges, not per-frame exclusions.
+	#failedPreparationRanges: Array<[number, number]> = [];
+	// Captured by queued terminal writes; never consult the mutable queue at write settlement.
+	#frameCommitExclusions = new Set<number>();
 	#renderCommitWaiters = new Map<number, Set<RenderCommitWaiter>>();
 	#lastRenderWriteSucceeded = false;
 	/** Generation whose render path is currently capturing terminal output. */
@@ -1147,6 +1182,7 @@ export class TUI extends Container {
 		debugRedrawEnvReads: 0,
 		debugRedrawAppendWrites: 0,
 		differentialGuardVisibleWidthCalls: 0,
+		widthReflowScanRows: 0,
 	};
 
 	static resetRenderCountersForTest(): void {
@@ -1154,6 +1190,7 @@ export class TUI extends Container {
 			debugRedrawEnvReads: 0,
 			debugRedrawAppendWrites: 0,
 			differentialGuardVisibleWidthCalls: 0,
+			widthReflowScanRows: 0,
 		};
 	}
 
@@ -1161,6 +1198,14 @@ export class TUI extends Container {
 		return { ...TUI.#renderCounters };
 	}
 
+	getRenderPreparationStateForTest(): { pending: number; holes: number; failedRanges: number } {
+		return {
+			pending: this.#preparationBlocked.size,
+			holes: this.#commitHoles.size,
+			failedRanges: this.#failedPreparationRanges.length,
+		};
+	}
+
 	static #readDebugRedrawFlag(): boolean {
 		TUI.#renderCounters.debugRedrawEnvReads += 1;
 		return $pickflag("GJC_DEBUG_REDRAW", "PI_DEBUG_REDRAW");
@@ -1249,6 +1294,29 @@ export class TUI extends Container {
 	}
 
 	override dispose(): void {
+		if (this.#preparationDisposed) return;
+		this.#preparationDisposed = true;
+		this.#renderRequested = false;
+		this.#renderRequestedGeneration = 0;
+		this.#inputRenderPending = false;
+		this.#resizeRenderQueued = false;
+		this.#resizeRenderMutationQueued = false;
+		this.#renderMutationQueued = false;
+		this.#widthSettleRenderQueued = false;
+		this.#forcedRenderQueued = false;
+		this.#clearSixelProbeState();
+		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;
+		}
+		this.#invalidatePreparations();
+		this.#preparationLifecycle = undefined;
+		this.#settleRenderCommitWaiters(false);
 		this.#unsubscribeTabWidthChange?.();
 		this.#unsubscribeTabWidthChange = undefined;
 		this.#finalizeRasterLeases("terminal-loss");
@@ -2314,6 +2382,7 @@ export class TUI extends Container {
 		return true;
 	}
 	start(): void {
+		if (this.#preparationDisposed) return;
 		this.#stopped = false;
 		this.#terminalUnavailable = false;
 		this.#clearMouseSelection();
@@ -2321,31 +2390,36 @@ export class TUI extends Container {
 		// 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),
-			() => {
-				const hadRasterLease = this.#rasterLeases.size > 0;
-				this.#revokeRasterLeases("resize");
-				// Only a pet raster lease needs refreshed cell metrics on resize; a
-				// plain resize keeps the historical byte stream (no cell query).
-				if (hadRasterLease) this.#queryCellSize(true);
-				this.invalidate();
-				if (this.#pendingTerminalCleanup.length > 0 || this.#rasterCleanup.size > 0) {
-					// Retained pet/cleanup output must be flushed before the resize
-					// repaint so it cannot interleave behind the new frame.
-					this.notifyTerminalLifecycle({
-						kind: "explicit-cleanup",
-						source: "tui",
-						terminalGeneration: this.#terminalGeneration,
-					}).then(result => {
-						if (result.stillPending === 0) this.requestResizeRender();
-					});
-				} else {
-					this.requestResizeRender();
-				}
-			},
-		);
+		try {
+			this.terminal.setMouseEnabled?.(this.options.enableMouse === true);
+			this.terminal.start(
+				data => this.#handleInput(data),
+				() => {
+					const hadRasterLease = this.#rasterLeases.size > 0;
+					this.#revokeRasterLeases("resize");
+					// Only a pet raster lease needs refreshed cell metrics on resize; a
+					// plain resize keeps the historical byte stream (no cell query).
+					if (hadRasterLease) this.#queryCellSize(true);
+					this.invalidate();
+					if (this.#pendingTerminalCleanup.length > 0 || this.#rasterCleanup.size > 0) {
+						// Retained pet/cleanup output must be flushed before the resize
+						// repaint so it cannot interleave behind the new frame.
+						this.notifyTerminalLifecycle({
+							kind: "explicit-cleanup",
+							source: "tui",
+							terminalGeneration: this.#terminalGeneration,
+						}).then(result => {
+							if (result.stillPending === 0) this.requestResizeRender();
+						});
+					} else {
+						this.requestResizeRender();
+					}
+				},
+			);
+		} catch (error) {
+			this.#markTerminalUnavailable();
+			throw error;
+		}
 		if (this.#pendingTerminalCleanup.length > 0 || this.#rasterCleanup.size > 0) {
 			void this.notifyTerminalLifecycle({
 				kind: "availability-restored",
@@ -2356,6 +2430,14 @@ export class TUI extends Container {
 		this.#hideCursor();
 		this.#querySixelSupport();
 		this.#queryCellSize();
+		if (this.#stopped || !this.terminalAvailable) return;
+		const epoch = this.#preparationEpoch;
+		if (!this.#callPreparation(this.#preparationLifecycle?.beforeStart, "beforeStart")) {
+			this.#invalidatePreparations();
+			if (!this.#stopped && this.terminalAvailable && !this.#preparationDisposed) this.requestRender(true);
+			return;
+		}
+		if (epoch !== this.#preparationEpoch || this.#stopped || !this.terminalAvailable) return;
 		this.requestRender(true);
 	}
 
@@ -2368,8 +2450,10 @@ export class TUI extends Container {
 	 * 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);
+		if (this.#isFailedPreparation(generation)) return Promise.resolve(false);
+		if (generation <= 0 || (generation <= this.#committedRenderGeneration && !this.#commitHoles.has(generation)))
+			return Promise.resolve(true);
+		if (this.#stopped || !this.terminalAvailable || this.#preparationDisposed) return Promise.resolve(false);
 		return new Promise<boolean>(resolve => {
 			const waiter: RenderCommitWaiter = {
 				resolve,
@@ -2392,14 +2476,31 @@ export class TUI extends Container {
 		});
 	}
 
-	#settleRenderCommitWaiters(committed: boolean, generation = Number.POSITIVE_INFINITY): void {
-		if (committed) this.#committedRenderGeneration = Math.max(this.#committedRenderGeneration, generation);
+	#settleRenderCommitWaiters(
+		committed: boolean,
+		generation = Number.POSITIVE_INFINITY,
+		exclusions = this.#frameCommitExclusions,
+	): void {
+		if (committed) {
+			for (const blocked of exclusions) {
+				if (
+					blocked <= generation &&
+					blocked > this.#committedRenderGeneration &&
+					!this.#isFailedPreparation(blocked)
+				)
+					this.#commitHoles.add(blocked);
+			}
+			for (const hole of this.#commitHoles) {
+				if (hole <= generation && !exclusions.has(hole)) this.#commitHoles.delete(hole);
+			}
+			this.#committedRenderGeneration = Math.max(this.#committedRenderGeneration, generation);
+		}
 		for (const [waiterGeneration, waiters] of this.#renderCommitWaiters) {
-			if (committed && waiterGeneration > generation) continue;
+			if (committed && (waiterGeneration > generation || exclusions.has(waiterGeneration))) continue;
 			this.#renderCommitWaiters.delete(waiterGeneration);
 			for (const waiter of waiters) {
 				clearTimeout(waiter.timer);
-				waiter.resolve(committed);
+				waiter.resolve(committed && !this.#isFailedPreparation(waiterGeneration));
 			}
 		}
 	}
@@ -2440,6 +2541,7 @@ export class TUI extends Container {
 		this.#rasterLeases.clear();
 	}
 	#markTerminalUnavailable(settleRenderWaiters = true): void {
+		this.#invalidatePreparations();
 		this.#terminalGeneration++;
 		for (const record of this.#rasterCleanup.values()) record.terminalGeneration = this.#terminalGeneration;
 		this.#revokeRasterLeases("terminal-loss");
@@ -2676,6 +2778,7 @@ export class TUI extends Container {
 	}
 
 	stop(): void {
+		this.#invalidatePreparations();
 		// Invalidate every raster-queue body captured under the running epoch
 		// before any teardown: nothing queued before stop may write after
 		// restoration. Synchronous stop cleanup below writes directly.
@@ -2785,6 +2888,7 @@ export class TUI extends Container {
 	 * the last committed frame.
 	 */
 	requestResizeRender(): void {
+		if (this.#preparationDisposed) return;
 		// 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
@@ -2844,8 +2948,180 @@ export class TUI extends Container {
 		this.requestRenderWithGeneration(force, source);
 	}
 
+	/** Queue one synchronous preparation on the existing frame clock. Cancellation is idempotent. */
+	enqueueBeforeRender(callback: () => void): () => void {
+		if (this.#preparationDisposed || this.#preparationInvalidating || this.#stopped || !this.terminalAvailable)
+			return cancelNoPreparation;
+		const entry: RenderPreparation = { callback, generation: this.#nextRenderGeneration + 1 };
+		entry.cancel = () => {
+			entry.callback = undefined;
+			entry.cancel = undefined;
+			this.#preparations.delete(entry);
+			this.#preparationSnapshot?.delete(entry);
+			this.#preparationBlocked.delete(entry.generation);
+		};
+		this.#preparations.add(entry);
+		this.#preparationBlocked.add(entry.generation);
+		this.requestRenderWithGeneration(false, "preparation");
+		return createPreparationCancellation(entry);
+	}
+
+	/** One owner only: replacing or clearing it invalidates all old preparation work. */
+	setRenderPreparationLifecycleCallbacks(
+		callbacks: { invalidate: () => void; beforeStart: () => void } | undefined,
+	): void {
+		if (this.#preparationLifecycle === callbacks) return;
+		this.#invalidatePreparations();
+		this.#preparationLifecycle = this.#preparationDisposed ? undefined : callbacks;
+	}
+
+	#callPreparation(callback: (() => void) | undefined, where: string): boolean {
+		try {
+			callback?.();
+			return true;
+		} catch (error) {
+			logger.error("Render preparation failed", {
+				where,
+				error: error instanceof Error ? error.message : String(error),
+				stack: error instanceof Error ? error.stack : undefined,
+			});
+			return false;
+		}
+	}
+
+	#invalidatePreparations(): void {
+		this.#preparationEpoch++;
+		for (const generation of this.#preparationBlocked) this.#retirePreparation(generation);
+		for (const entry of this.#preparations) {
+			entry.callback = undefined;
+			entry.cancel = undefined;
+		}
+		for (const entry of this.#preparationSnapshot ?? []) {
+			entry.callback = undefined;
+			entry.cancel = undefined;
+		}
+		this.#preparations.clear();
+		this.#preparationSnapshot?.clear();
+		if (this.#preparationInvalidating) return;
+		this.#preparationInvalidating = true;
+		try {
+			this.#callPreparation(this.#preparationLifecycle?.invalidate, "invalidate");
+		} finally {
+			this.#preparationInvalidating = false;
+		}
+	}
+
+	#isFailedPreparation(generation: number): boolean {
+		let low = 0;
+		let high = this.#failedPreparationRanges.length;
+		while (low < high) {
+			const middle = (low + high) >>> 1;
+			const [start, end] = this.#failedPreparationRanges[middle];
+			if (generation < start) high = middle;
+			else if (generation > end) low = middle + 1;
+			else return true;
+		}
+		return false;
+	}
+
+	#retirePreparation(generation: number): void {
+		this.#preparationBlocked.delete(generation);
+		this.#commitHoles.delete(generation);
+		const ranges = this.#failedPreparationRanges;
+		let low = 0;
+		let high = ranges.length;
+		while (low < high) {
+			const middle = (low + high) >>> 1;
+			if (ranges[middle][1] < generation - 1) low = middle + 1;
+			else high = middle;
+		}
+		let start = generation;
+		let end = generation;
+		let next = low;
+		while (next < ranges.length && ranges[next][0] <= end + 1) {
+			start = Math.min(start, ranges[next][0]);
+			end = Math.max(end, ranges[next][1]);
+			next++;
+		}
+		ranges.splice(low, next - low, [start, end]);
+		const waiters = this.#renderCommitWaiters.get(generation);
+		this.#renderCommitWaiters.delete(generation);
+		for (const waiter of waiters ?? []) {
+			clearTimeout(waiter.timer);
+			waiter.resolve(false);
+		}
+	}
+
+	/** The only preparation boundary, before generation capture and all renderer reads. */
+	#renderPreparedFrame(): void {
+		if (this.#stopped || this.#preparationDisposed) return;
+		if (!this.terminalAvailable) {
+			this.#markTerminalUnavailable();
+			return;
+		}
+		const epoch = this.#preparationEpoch;
+		const snapshot = this.#preparations;
+		this.#preparations = new Set();
+		this.#preparationSnapshot = snapshot;
+		this.#preparationDrainEpoch = epoch;
+		try {
+			for (const entry of snapshot) {
+				if (epoch !== this.#preparationEpoch || this.#stopped || !this.terminalAvailable) break;
+				const callback = entry.callback;
+				entry.callback = undefined;
+				entry.cancel = undefined;
+				if (
+					callback &&
+					this.#callPreparation(callback, "beforeRender") &&
+					epoch === this.#preparationEpoch &&
+					!this.#stopped &&
+					this.terminalAvailable
+				) {
+					this.#preparationBlocked.delete(entry.generation);
+				} else if (callback) {
+					this.#retirePreparation(entry.generation);
+				}
+			}
+		} finally {
+			for (const entry of snapshot) {
+				entry.callback = undefined;
+				entry.cancel = undefined;
+			}
+			snapshot.clear();
+			this.#preparationSnapshot = undefined;
+		}
+		if (!this.terminalAvailable && !this.#stopped) this.#markTerminalUnavailable();
+		if (epoch !== this.#preparationEpoch || this.#stopped || !this.terminalAvailable || this.#preparationDisposed) {
+			if (!this.#stopped && this.terminalAvailable && !this.#preparationDisposed) this.#scheduleRender();
+			return;
+		}
+		const requestedGeneration = this.#renderRequestedGeneration;
+		this.#renderRequestedGeneration = 0;
+		this.#renderRequested = false;
+		this.#lastRenderAt = performance.now();
+		this.#lastRenderWriteSucceeded = false;
+		this.#frameCommitExclusions = new Set(this.#preparationBlocked);
+		const t0 = renderMetrics.now();
+		try {
+			this.#renderGenerationInProgress = requestedGeneration;
+			this.#doRender();
+			this.#commitRenderGeneration(requestedGeneration);
+		} finally {
+			this.#renderGenerationInProgress = 0;
+			this.#frameCommitExclusions = new Set();
+			if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
+			if (this.#preparations.size > 0 && epoch === this.#preparationEpoch) {
+				for (const entry of this.#preparations)
+					this.#renderRequestedGeneration = Math.max(this.#renderRequestedGeneration, entry.generation);
+				this.#renderRequested = true;
+				this.#scheduleRender();
+			}
+		}
+	}
+
 	#requestRenderWithScope(force: boolean, source: string, scope: "full" | "layout"): number {
 		const generation = ++this.#nextRenderGeneration;
+		if (this.#preparationDisposed) return generation;
 		this.#renderRequestedGeneration = Math.max(this.#renderRequestedGeneration, generation);
 		if (scope === "full") this.#renderScope = "full";
 		this.#requestRenderCore(force, source, generation);
@@ -2863,6 +3139,7 @@ export class TUI extends Container {
 	}
 
 	#requestRenderCore(force: boolean, source: string, generation: number): void {
+		if (this.#preparationDisposed) return;
 		if (!this.terminalAvailable) {
 			this.#markTerminalUnavailable();
 			return;
@@ -2905,6 +3182,7 @@ export class TUI extends Container {
 				this.#viewportTopRow = 0;
 				this.#maxLinesRendered = 0;
 			}
+			if (this.#preparationSnapshot && this.#preparationDrainEpoch === this.#preparationEpoch) return;
 			if (this.#renderTimer) {
 				clearTimeout(this.#renderTimer);
 				this.#renderTimer = undefined;
@@ -2916,20 +3194,12 @@ export class TUI extends Container {
 					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.#renderGenerationInProgress = requestedGeneration;
-				this.#doRender();
-				this.#renderGenerationInProgress = 0;
-				this.#commitRenderGeneration(requestedGeneration);
-				if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
+				this.#renderPreparedFrame();
 			});
 			return;
 		}
+		// Preparation mutations join this frame; nested registrations get the next normal frame.
+		if (this.#preparationSnapshot && this.#preparationDrainEpoch === this.#preparationEpoch) return;
 		// Input-priority path: expedite so the keystroke echoes within the next tick
 		// instead of waiting for (or behind) the frame-budget timer. Re-entrant input
 		// requests in the same turn coalesce via #inputRenderPending, so at most one
@@ -2950,7 +3220,7 @@ export class TUI extends Container {
 	}
 
 	#scheduleRender(): void {
-		if (this.#stopped || this.#renderTimer || !this.#renderRequested) {
+		if (this.#preparationDisposed || this.#stopped || this.#renderTimer || !this.#renderRequested) {
 			return;
 		}
 		const elapsed = performance.now() - this.#lastRenderAt;
@@ -2961,17 +3231,7 @@ 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.#renderGenerationInProgress = requestedGeneration;
-			this.#doRender();
-			this.#renderGenerationInProgress = 0;
-			this.#commitRenderGeneration(requestedGeneration);
-			if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
+			this.#renderPreparedFrame();
 			if (this.#renderRequested) {
 				this.#scheduleRender();
 			}
@@ -2993,17 +3253,7 @@ 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.#renderGenerationInProgress = requestedGeneration;
-		this.#doRender();
-		this.#renderGenerationInProgress = 0;
-		this.#commitRenderGeneration(requestedGeneration);
-		if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
+		this.#renderPreparedFrame();
 	}
 
 	#handleInput(data: string): void {
@@ -3798,6 +4048,7 @@ export class TUI extends Container {
 	#normalizeLinesForEmit(lines: string[], width: number, start = 0): string[] {
 		const widthCheckIndexes: number[] = [];
 		const widthCheckLines: string[] = [];
+		const retainedWidths: (number | undefined)[] = [];
 		for (let i = start; i < lines.length; i++) {
 			const line = lines[i];
 			if (TERMINAL.isImageLine(line)) continue;
@@ -3810,19 +4061,21 @@ export class TUI extends Container {
 				continue;
 			}
 			widthCheckIndexes.push(i);
-			widthCheckLines.push(normalized);
+			retainedWidths.push(entry.width);
+			if (entry.width === undefined) widthCheckLines.push(normalized);
 		}
 
 		const widths = widthCheckLines.length === 0 ? [] : visibleWidths(widthCheckLines);
 		const truncateIndexes: number[] = [];
 		const truncateLines: string[] = [];
+		let measuredIndex = 0;
 		for (let i = 0; i < widthCheckIndexes.length; i++) {
 			const lineIndex = widthCheckIndexes[i];
-			const normalized = widthCheckLines[i];
-			const measuredWidth = widths[i] ?? 0;
+			const entry = this.#normalizeLineForRender(lines[lineIndex]);
+			const { normalized } = entry;
+			const measuredWidth = retainedWidths[i] ?? widths[measuredIndex++] ?? 0;
+			entry.width = measuredWidth;
 			if (measuredWidth <= width) {
-				const entry = this.#normalizeLineForRender(lines[lineIndex]);
-				entry.width = measuredWidth;
 				this.#lineEmitWidthCache.set(entry.terminated, measuredWidth);
 				lines[lineIndex] = entry.terminated;
 				continue;
@@ -3831,7 +4084,9 @@ export class TUI extends Container {
 			const key = `${width}\0${normalized}`;
 			const cached = this.#lineTruncationCache.get(key);
 			if (cached !== undefined) {
-				this.#lineEmitWidthCache.set(cached, visibleWidth(cached));
+				if (!this.#lineEmitWidthCache.has(cached)) {
+					this.#lineEmitWidthCache.set(cached, visibleWidth(cached));
+				}
 				lines[lineIndex] = cached;
 				continue;
 			}
@@ -4832,10 +5087,12 @@ export class TUI extends Container {
 		}
 		const useViewportRepaintPath = this.#viewportRepaintHost();
 		const widthReflowRequired =
+			widthChanged &&
 			this.#previousWidth > 0 &&
-			rawLines.some(
-				line => !TERMINAL.isImageLine(line) && visibleWidth(line) > Math.min(this.#previousWidth, width),
-			);
+			rawLines.some(line => {
+				TUI.#renderCounters.widthReflowScanRows += 1;
+				return !TERMINAL.isImageLine(line) && visibleWidth(line) > Math.min(this.#previousWidth, width);
+			});
 		if (
 			widthChanged &&
 			!this.#legacyMultiplexerFullRender &&
@@ -5607,11 +5864,12 @@ export class TUI extends Container {
 			? (bytes: string) => this.#writeRasterPreservingRenderIngress(bytes)
 			: (bytes: string) => this.#writeProtectedRenderIngress(bytes);
 		const renderGeneration = this.#renderGenerationInProgress;
+		const commitExclusions = this.#frameCommitExclusions;
 		const write = () => {
 			if (!writeIngress(buffer)) return false;
 			onBufferWritten?.();
 			this.#lastRenderWriteSucceeded = true;
-			if (renderGeneration > 0) this.#settleRenderCommitWaiters(true, renderGeneration);
+			if (renderGeneration > 0) this.#settleRenderCommitWaiters(true, renderGeneration, commitExclusions);
 			const emission = this.#postRenderEmitter?.();
 			if (emission) {
 				const overlay = typeof emission === "string" ? emission : emission.payload;