@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/chat/user-message.ts

@@ -1,4 +1,5 @@
-import { applyBackgroundToLine, padding, visibleWidth } from "../utils";
+import { applyBackgroundToLine, padding, stripTerminalSequences, visibleWidth } from "../utils";
+import type { AnimationFrame, TranscriptPresentationTarget } from "../chrome/transcript-container";
 import { type Component, Container } from "../tui";
 import { Disclosure } from "../components/disclosure";
 import { Markdown } from "../components/markdown";
@@ -24,7 +25,13 @@ import type { ReactionTarget } from "./reaction";
 import { card, md, node, row, span, text } from "../native/describe";
 import { base64ImageNode } from "../native/blobs";
 import { hasTranscriptActions, runTranscriptAction } from "./transcript-actions";
-import { type NativeChild, type NativeNode, type NativeUiEvent, rootToggleExpanded } from "../native/node";
+import {
+	type DescribeContext,
+	type NativeChild,
+	type NativeNode,
+	type NativeUiEvent,
+	rootToggleExpanded,
+} from "../native/node";
 import { Memo } from "../native/memo";
 
 // OSC 133 shell integration: marks prompt zones for terminal multiplexers.
@@ -51,7 +58,7 @@ const OSC133_ZONE_CLOSE = OSC133_ZONE_END + OSC133_COMMAND_START + OSC133_COMMAN
 
 /** How a user bubble styles its prose and chips (see {@link userBubbleColor}). */
 export interface UserBubbleOptions {
-	/** Materialized `file://` targets per attached image, indexed by chip number. */
+	/** Filesystem paths for attached image chips, indexed by chip number. */
 	imageLinks?: readonly (string | undefined)[];
 	/** The message's attached images in chip order (`#1` first); a native bubble shows them. */
 	images?: readonly ImageContent[];
@@ -118,7 +125,8 @@ export function userBubbleColor(
  * (see {@link ReactionTarget}) drawn right-aligned in the bubble's top padding row;
  * a live-steered message carries a `*` marker left-aligned in the same row.
  */
-export class UserMessageComponent extends Container implements ReactionTarget {
+export class UserMessageComponent extends Container implements ReactionTarget, TranscriptPresentationTarget {
+	#allocation = Number.POSITIVE_INFINITY;
 	// Memoized OSC 133 zone wrapping keyed on the underlying container render
 	// (same source ref ⇒ identical rows ⇒ reuse the wrapped copy). Keeps this
 	// component reference-stable for the transcript's incremental assembly and
@@ -137,6 +145,8 @@ export class UserMessageComponent extends Container implements ReactionTarget {
 	readonly #tokens: RegExp;
 	#reaction: string | undefined;
 	#native: NativeNode | undefined;
+	/** The terminal's clock {@link #native} was described with. */
+	#nativeHour12: boolean | undefined;
 
 	constructor(text: string, options: UserBubbleOptions = {}) {
 		super();
@@ -169,6 +179,12 @@ export class UserMessageComponent extends Container implements ReactionTarget {
 		this.addChild(markdown);
 	}
 
+	override releaseRenderCaches(): void {
+		this.#zoneSource = undefined;
+		this.#zoneLines = undefined;
+		super.releaseRenderCaches();
+	}
+
 	setReaction(emoji: string): void {
 		if (this.#reaction === emoji) return;
 		this.#reaction = emoji;
@@ -184,17 +200,20 @@ export class UserMessageComponent extends Container implements ReactionTarget {
 	 * agent's reaction are chips at the bottom-right, so a reaction landing
 	 * later updates the frame in place, even deep in scrollback.
 	 */
-	override describe(): NativeNode {
-		if (this.#native) return this.#native;
+	override describe(cx?: DescribeContext): NativeNode {
+		// The terminal's clock: Bun's own default locale ignores the user's.
+		const hour12 = cx?.hour12;
+		if (this.#native && this.#nativeHour12 === hour12) return this.#native;
+		this.#nativeHour12 = hour12;
 		const children: NativeChild[] = [];
 		if (!this.#synthetic && hasTranscriptActions()) {
 			const tools: NativeChild[] = [];
 			if (this.#timestamp !== undefined) {
 				const at = new Date(this.#timestamp);
 				tools.push(
-					text([span(at.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }), "dim mono")], {
+					text([span(at.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", hour12 }), "dim mono")], {
 						role: "zeta.user.time",
-						title: at.toLocaleString(),
+						title: at.toLocaleString([], { hour12 }),
 					}),
 				);
 			}
@@ -270,11 +289,47 @@ export class UserMessageComponent extends Container implements ReactionTarget {
 		return applyBackgroundToLine(` ${marker}${padding(gap)}${emoji}`, width, this.#bgColor);
 	}
 
+	/** Apply the transcript allocator's current viewport reservation. */
+	setTranscriptAllocation(rows: number, _frame?: AnimationFrame): void {
+		this.#allocation = Math.max(0, Math.trunc(rows));
+	}
+
+	isTranscriptBlockFinalized(): boolean {
+		return true;
+	}
+
+	/**
+	 * Single-row emergency representation for the overflow transcript layout:
+	 * renders the first content line instead of the blank top padding row, and
+	 * omits OSC 133 shell integration markers so moving live blocks across the
+	 * viewport does not leave stale prompt marks on lines it no longer occupies.
+	 */
+	renderTranscriptBlockEmergencyRow(width: number): string | undefined {
+		return this.#selectEmergencyRow(super.render(width));
+	}
+
+	#selectEmergencyRow(lines: readonly string[]): string | undefined {
+		if (lines.length === 0) return undefined;
+		if (lines.length >= 3) {
+			for (let i = 1; i < lines.length - 1; i++) {
+				if (stripTerminalSequences(lines[i]!).trim().length > 0) {
+					return lines[i];
+				}
+			}
+			return lines[1];
+		}
+		return lines[0];
+	}
+
 	override render(width: number): readonly string[] {
 		const lines = super.render(width);
 		if (lines.length === 0) {
 			return lines;
 		}
+		if (this.#allocation === 1) {
+			const emergency = this.#selectEmergencyRow(lines);
+			if (emergency !== undefined) return [emergency];
+		}
 		if (this.#zoneSource === lines && this.#zoneLines !== undefined) {
 			return this.#zoneLines;
 		}
@@ -326,6 +381,10 @@ class SyntheticSummary implements Component {
 		this.#summary = summary;
 	}
 
+	releaseRenderCaches(): void {
+		this.#cache = undefined;
+	}
+
 	invalidate(): void {
 		this.#cache = undefined;
 	}
@@ -414,6 +473,10 @@ export class CollapsedSyntheticMessageComponent implements Component {
 		this.#disclosure.invalidate();
 	}
 
+	releaseRenderCaches(): void {
+		this.#disclosure.releaseRenderCaches();
+	}
+
 	dispose(): void {
 		this.#disclosure.dispose();
 	}

package/src/chrome/shared.ts

@@ -10,6 +10,59 @@ export function sanitizeStatusText(text: string): string {
 	return sanitizeDisplaySingleLine(text).replace(/ +/g, " ").trim();
 }
 
+/** 7-bit SGR (`ESC [ <params> m`) — the one escape family a hook status may keep. */
+const SGR_RE = /\x1b\[[0-9;:]*m/g;
+const SGR_RESET = "\x1b[0m";
+const WHITESPACE_RE = /\s/;
+
+/**
+ * Like {@link sanitizeStatusText}, but keeps 7-bit SGR so extensions can colour
+ * `ctx.ui.setStatus` text. Every other escape (OSC links/titles, DCS/PM/APC,
+ * 7- and 8-bit CSI), C0/C1, lone surrogates, newlines and tabs are sanitized at
+ * least as strictly as in `sanitizeStatusText`; space runs collapse and edges
+ * trim (`String#trim` whitespace) by visible text, regardless of SGR placement.
+ * A styled result always ends with `\x1b[0m`.
+ */
+export function sanitizeHookStatusText(input: string): string {
+	// Drop lone surrogates before splitting, as `sanitizeText` does, so stripped escapes
+	// cannot fuse surrogate halves from neighbouring chunks into a new character.
+	const wellFormed = input.toWellFormed();
+	const text = wellFormed === input ? input : wellFormed.replaceAll("\ufffd", "");
+	SGR_RE.lastIndex = 0;
+	if (!SGR_RE.test(text)) return sanitizeStatusText(text); // byte-identical for unstyled input
+	let out = "";
+	// SGR codes and whitespace seen since the last visible char, in source order.
+	let pending = "";
+	let lastWasSpace = false;
+	let hasVisible = false;
+	let cursor = 0;
+	SGR_RE.lastIndex = 0;
+	for (;;) {
+		const match = SGR_RE.exec(text);
+		// `sanitizeText` runs `Bun.stripANSI` only when an ESC is present; a chunk between SGR
+		// codes often has none, so strip explicitly to drop 8-bit (C1) sequence payloads.
+		const chunk = sanitizeDisplaySingleLine(Bun.stripANSI(text.slice(cursor, match ? match.index : text.length)));
+		for (const ch of chunk) {
+			if (WHITESPACE_RE.test(ch)) {
+				// Leading whitespace drops; ASCII space runs collapse even across SGR codes.
+				if (hasVisible && !(ch === " " && lastWasSpace)) pending += ch;
+				lastWasSpace = ch === " ";
+				continue;
+			}
+			out += pending + ch;
+			pending = "";
+			lastWasSpace = false;
+			hasVisible = true;
+		}
+		if (!match) break;
+		pending += match[0];
+		cursor = match.index + match[0].length;
+	}
+	if (!hasVisible) return "";
+	// Trailing whitespace trims; trailing SGR codes stay (they never contain whitespace).
+	return out + pending.replace(/\s+/g, "") + SGR_RESET;
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Tab Bar Theme
 // ═══════════════════════════════════════════════════════════════════════════

package/src/chrome/status-notice.ts

@@ -1,6 +1,6 @@
 import { Spacer } from "../components/spacer";
 import { Text } from "../components/text";
-import { node } from "../native/describe";
+import { EMPTY_NODE, node } from "../native/describe";
 import type { NativeNode } from "../native/node";
 import { styledSpans } from "../native/spans";
 import { Container } from "../tui";
@@ -8,33 +8,51 @@ import { Container } from "../tui";
 /** How long a native status toast stays up (ms). */
 const TOAST_TTL = 2400;
 
+/** How a {@link StatusNotice} shows. */
+export interface StatusNoticeOptions {
+	/** Styles the ANSI line; resolved at render so a theme change re-shapes it. */
+	styleFn?: (text: string) => string;
+	/**
+	 * Whether a native terminal toasts it (default). False keeps the notice to
+	 * the ANSI transcript: background chatter such as MCP connection progress,
+	 * which would otherwise re-toast on every server that connects or fails.
+	 */
+	toast?: boolean;
+}
+
 /**
  * A transient status notice (`showStatus`: "Thinking blocks: hidden", "Copied
  * to clipboard"). The ANSI render appends a blank row and the dim line to the
  * transcript; a native terminal shows it as a toast instead, so notices never
- * pile up in the history. Updating the text re-shows the toast.
+ * pile up in the history. Updating the text re-shows the toast; a notice
+ * with `toast: false` describes nothing natively.
  */
 export class StatusNotice extends Container {
 	readonly #text: Text;
 	#message: string;
+	#toast: boolean;
 	#native: NativeNode | undefined;
 
-	constructor(message: string, styleFn?: (text: string) => string) {
+	constructor(message: string, options: StatusNoticeOptions = {}) {
 		super();
 		this.#message = message;
-		this.#text = new Text(message, 1, 0).setStyleFn(styleFn);
+		this.#toast = options.toast ?? true;
+		this.#text = new Text(message, 1, 0).setStyleFn(options.styleFn);
 		this.addChild(new Spacer(1));
 		this.addChild(this.#text);
 	}
 
-	setMessage(message: string, styleFn?: (text: string) => string): void {
-		this.#text.setStyleFn(styleFn);
+	setMessage(message: string, options: StatusNoticeOptions = {}): void {
+		const toast = options.toast ?? true;
+		this.#text.setStyleFn(options.styleFn);
 		this.#text.setText(message);
-		if (message !== this.#message) this.#native = undefined;
+		if (message !== this.#message || toast !== this.#toast) this.#native = undefined;
 		this.#message = message;
+		this.#toast = toast;
 	}
 
 	override describe(): NativeNode {
+		if (!this.#toast) return EMPTY_NODE;
 		if (this.#native) return this.#native;
 		// Callers may pass pre-styled text; a toast takes plain text.
 		const plain = styledSpans(this.#message)

package/src/chrome/transcript-container.d.ts

@@ -63,6 +63,12 @@ export interface TranscriptViewportSpan {
 export declare class TranscriptContainer extends Container {
     #private;
     addChild(component: Component): void;
+    /**
+     * `#entries` mirrors `children`; move both together or the next `#syncEntries`
+     * pays a full O(n) rebuild.
+     */
+    insertChildAt(component: Component, index: number): void;
+    /** Removes `component` if {@link canRemoveBlock} allows it; otherwise does nothing. */
     removeChild(component: Component): void;
     clear(): void;
     setToolActivityVisible(visible: boolean): void;

package/src/chrome/transcript-container.ts

@@ -1,9 +1,11 @@
 import { type Component, Container, type HistoryBatch } from "../tui";
 import * as logger from "@linxiraos/pi-utils/logger";
 import { popLoopPhase, pushLoopPhase } from "@linxiraos/pi-utils";
+import { renderForScrollback } from "../components/image";
 import { col } from "../native/describe";
 import type { NativeNode } from "../native/node";
 import { isNativeSettled, settleNative } from "../native/settle";
+import { TERMINAL } from "../terminal-capabilities";
 import { isUsageRowBlock } from "../overlays/usage-row";
 import { isToolActivityComponent } from "./tool-activity";
 
@@ -56,6 +58,12 @@ export interface AppendOnlyTranscriptBlock {
 
 interface FinalizableBlock {
 	isTranscriptBlockFinalized?(): boolean;
+	/**
+	 * A finalized block whose rows still wait on async work (an SVG figure's
+	 * raster). Retirement holds until it lands: committed rows can never be
+	 * repainted, so retiring early would freeze a placeholder into scrollback.
+	 */
+	isTranscriptBlockPending?(): boolean;
 	/** Render the row that must remain represented under emergency viewport pressure. */
 	renderTranscriptBlockEmergencyRow?(width: number): string | undefined;
 }
@@ -89,6 +97,13 @@ interface TranscriptEntry {
 	 * state for emitted-row slicing but never emits another mid-stream row.
 	 */
 	stableFrozen: boolean;
+	/**
+	 * Cached "renders at least one image line" result for the settled-image
+	 * flush, keyed by width and image protocol (the probe upgrade re-encodes
+	 * text-fallback blocks into graphics). Rows of a settled block are frozen,
+	 * so a hit is exact.
+	 */
+	imageScan: { width: number; protocol: string | null; hasImageRows: boolean } | undefined;
 }
 
 type RetirementPolicy = "pressure" | "flush";
@@ -120,7 +135,7 @@ const EMPTY_STABLE_ROWS: readonly TranscriptStableRow[] = [];
 
 function isFinalized(component: Component): boolean {
 	const block = component as Component & FinalizableBlock;
-	return block.isTranscriptBlockFinalized?.() ?? true;
+	return (block.isTranscriptBlockFinalized?.() ?? true) && block.isTranscriptBlockPending?.() !== true;
 }
 
 function blockMode(component: Component): TranscriptBlockMode {
@@ -199,6 +214,7 @@ export class TranscriptContainer extends Container {
 	 */
 	#frameRows = new Map<TranscriptEntry, readonly string[]>();
 	#frameRowsWidth = 0;
+	#releaseFailures = new WeakSet<Component>();
 	/** The `children` array `#entries` last mirrored; see {@link #syncEntries}. */
 	#syncedChildren: Component[] | undefined;
 	/** Forces the next {@link #syncEntries} to compare every entry, not just the live tail. */
@@ -218,16 +234,42 @@ export class TranscriptContainer extends Container {
 			stableRowCountByWidth: new Map(),
 			emitted: 0,
 			stableFrozen: false,
+			imageScan: undefined,
 		});
-		// Callers may splice a just-added block into place (insert after an
-		// anchor); re-check the whole list once instead of trusting positions.
+		// `children` is public and may be edited externally; re-check the whole
+		// list once instead of trusting positions. Insert-after-anchor callers
+		// use insertChildAt, which keeps both arrays in lockstep.
 		this.#entriesUnverified = true;
 	}
 
+	/**
+	 * `#entries` mirrors `children`; move both together or the next `#syncEntries`
+	 * pays a full O(n) rebuild.
+	 */
+	insertChildAt(component: Component, index: number): void {
+		this.addChild(component);
+		const from = this.children.length - 1;
+		if (index >= from) {
+			this.#entriesUnverified = false;
+			return;
+		}
+		const [moved] = this.children.splice(from, 1);
+		if (moved) this.children.splice(index, 0, moved);
+		const [entry] = this.#entries.splice(this.#entries.length - 1, 1);
+		if (entry) this.#entries.splice(index, 0, entry);
+		// Both arrays moved in lockstep, so the live-tail check applies again.
+		this.#entriesUnverified = false;
+	}
+
+	/** Removes `component` if {@link canRemoveBlock} allows it; otherwise does nothing. */
 	override removeChild(component: Component): void {
-		if (this.children.indexOf(component) < 0 || !this.canRemoveBlock(component)) return;
-		super.removeChild(component);
-		this.#entries = this.#entries.filter(candidate => candidate.component !== component);
+		const index = this.#removableIndex(component);
+		if (index < 0) return;
+		// #removableIndex synced entries, which now mirror children index for
+		// index. This class renders through its own entries, never Container's
+		// memoized render, so splicing children directly is the whole removal.
+		this.children.splice(index, 1);
+		this.#entries.splice(index, 1);
 		this.#frontier = Math.min(this.#frontier, this.#entries.length);
 		this.#childStartRows.delete(component);
 	}
@@ -282,14 +324,24 @@ export class TranscriptContainer extends Container {
 
 	/** Whether a transient block may be discarded without leaving tape history. */
 	canRemoveBlock(component: Component): boolean {
+		return this.#removableIndex(component) >= 0;
+	}
+
+	/**
+	 * Syncs entries, then returns `component`'s index if it can be discarded
+	 * without leaving tape history (not committed, not emitted, not in an
+	 * offered batch), else -1.
+	 */
+	#removableIndex(component: Component): number {
 		this.#syncEntries();
-		const index = this.#entries.findIndex(entry => entry.component === component);
-		if (index < 0) return false;
+		// Removable blocks are transient ones near the live tail, so search from there.
+		const index = this.#entries.findLastIndex(entry => entry.component === component);
+		if (index < 0) return -1;
 		const entry = this.#entries[index]!;
-		if (entry.state === "committed" || entry.emitted > 0) return false;
-		if (this.#offered?.kind === "commit" && index < this.#offered.end) return false;
-		if (this.#offered?.kind === "append" && index === this.#offered.entry) return false;
-		return true;
+		if (entry.state === "committed" || entry.emitted > 0) return -1;
+		if (this.#offered?.kind === "commit" && index < this.#offered.end) return -1;
+		if (this.#offered?.kind === "append" && index === this.#offered.entry) return -1;
+		return index;
 	}
 
 	/**
@@ -576,7 +628,10 @@ export class TranscriptContainer extends Container {
 			popLoopPhase();
 		}
 		this.#replayPending = false;
-		if (rows.length === 0) return undefined;
+		if (rows.length === 0) {
+			this.#releaseCommittedRenderCaches();
+			return undefined;
+		}
 		const batch: HistoryBatch = { id: this.#nextBatchId++, rows, kind: "replay" };
 		this.#offered = { batch, kind: "replay" };
 		return batch;
@@ -659,9 +714,20 @@ export class TranscriptContainer extends Container {
 			if (!fits && appendHead === undefined) break;
 		}
 		const overflowing = keep > 0 || this.#liveCount() >= MAX_LIVE_BLOCKS;
+		// Graphics rows must reach native scrollback as soon as their block is
+		// finalized, not when the screen next overflows: live placements are
+		// repainted into the reserved-row block every frame, and on terminals
+		// whose live-region sixel does not stick (Windows Terminal) the image
+		// stays invisible until the exit flush commits the block.
+		// Retire the settled prefix through its last image-bearing block; the
+		// flush-at-stop path remains the fallback for what is still live then.
+		let imageFlushLimit = -1;
 		if (policy === "pressure" && !overflowing) {
-			this.#pinnedFrontier = undefined;
-			return undefined;
+			imageFlushLimit = this.#settledImageFlushLimit(width);
+			if (imageFlushLimit < 0) {
+				this.#pinnedFrontier = undefined;
+				return undefined;
+			}
 		}
 
 		if (appendHead !== undefined && keep > 0) {
@@ -687,8 +753,11 @@ export class TranscriptContainer extends Container {
 		}
 
 		// Shutdown retires everything eligible; pressure retires exactly the
-		// blocks that no longer fit, plus whatever the live-block cap demands.
+		// blocks that no longer fit, plus whatever the live-block cap demands
+		// — or, without overflow, the settled prefix through its last
+		// image-bearing block (graphics must land in scrollback promptly).
 		let limit = this.#frontier + keep;
+		if (imageFlushLimit >= 0) limit = Math.max(limit, imageFlushLimit);
 		if (this.#liveCount() >= MAX_LIVE_BLOCKS) {
 			limit = Math.max(limit, this.#frontier + (this.#liveCount() - (MAX_LIVE_BLOCKS - 1)));
 		}
@@ -740,6 +809,8 @@ export class TranscriptContainer extends Container {
 				this.#retireEntry(this.#entries[index]!);
 			}
 			this.#frontier = offered.end;
+		} else {
+			this.#releaseCommittedRenderCaches();
 		}
 		this.#offered = undefined;
 		if (this.#replayRequested) this.#startReplay();
@@ -759,6 +830,7 @@ export class TranscriptContainer extends Container {
 			const entry = this.#entries[index]!;
 			this.#setAllocation(entry.component, Number.MAX_SAFE_INTEGER, this.#lastFrame);
 			const block = trimBlankEdges(entry.component.render(width));
+			if (entry.state === "committed") this.#releaseRenderCaches(entry);
 			if (block.length === 0) continue;
 			if (rows.length > 0) rows.unshift("");
 			rows.unshift(...block);
@@ -806,6 +878,7 @@ export class TranscriptContainer extends Container {
 		for (const entry of this.#entries) {
 			this.#setAllocation(entry.component, Number.MAX_SAFE_INTEGER, this.#lastFrame);
 			const block = this.#renderEntry(entry, width);
+			if (entry.state === "committed") this.#releaseRenderCaches(entry);
 			if (block.length === 0) continue;
 			if (rows.length > 0) rows.push("");
 			this.#childStartRows.set(entry.component, rows.length);
@@ -1000,9 +1073,11 @@ export class TranscriptContainer extends Container {
 			// Only the range head is sliced by its emitted stable prefix; every other
 			// entry renders whole, so the append-only verification pass (a second
 			// full render of the block's stable prefix) is skipped for them. This
-			// keeps a complete-ledger replay at one render per block.
-			const rendered =
-				index === start ? this.#renderEntry(entry, width) : trimBlankEdges(entry.component.render(width));
+			// keeps a complete-ledger replay at one render per block. These rows go
+			// to native scrollback, where nothing can repaint them.
+			const rendered = renderForScrollback(() =>
+				index === start ? this.#renderEntry(entry, width) : trimBlankEdges(entry.component.render(width)),
+			);
 			const emittedRows = index === start ? this.#renderStablePrefix(entry, entry.emitted, width).length : 0;
 			const block = rendered.slice(emittedRows);
 			reached = index + 1;
@@ -1045,6 +1120,29 @@ export class TranscriptContainer extends Container {
 		entry.stableRows = EMPTY_STABLE_ROWS;
 		entry.renderedStableByWidth = new Map();
 		entry.stableRowCountByWidth = new Map();
+		this.#frameRows.delete(entry);
+		this.#releaseRenderCaches(entry);
+	}
+
+	#releaseCommittedRenderCaches(): void {
+		for (let index = 0; index < this.#frontier; index++) {
+			this.#releaseRenderCaches(this.#entries[index]!);
+		}
+	}
+
+	#releaseRenderCaches(entry: TranscriptEntry): void {
+		const release = entry.component.releaseRenderCaches;
+		if (release === undefined) return;
+		try {
+			release.call(entry.component);
+		} catch (err) {
+			if (this.#releaseFailures.has(entry.component)) return;
+			this.#releaseFailures.add(entry.component);
+			logger.warn("Transcript block failed to release render caches", {
+				component: entry.component.constructor.name,
+				error: String(err),
+			});
+		}
 	}
 
 	#startReplay(): void {
@@ -1146,6 +1244,14 @@ export class TranscriptContainer extends Container {
 				continue;
 			}
 			this.#setAllocation(candidate.entry.component, 1, frame);
+			const emergency = (
+				candidate.entry.component as Component & FinalizableBlock
+			).renderTranscriptBlockEmergencyRow?.(width);
+			if (emergency !== undefined) {
+				output.push(emergency);
+				owners.push(candidate.entry.component);
+				continue;
+			}
 			const rendered = this.#renderEntry(candidate.entry, width).slice(
 				this.#projectedEmittedRowCount(candidate.entry, candidate.index, width),
 			);
@@ -1168,6 +1274,42 @@ export class TranscriptContainer extends Container {
 		}
 	}
 
+	/**
+	 * End (exclusive) of the settled prefix that must retire for its graphics
+	 * rows to land in native scrollback now: one past the last image-bearing
+	 * settled entry, or -1 when the prefix holds no image block. Entries after
+	 * a non-settled block cannot retire yet, so the walk stops at the first
+	 * one — an unfinalized image keeps waiting, exactly like at stop.
+	 */
+	#settledImageFlushLimit(width: number): number {
+		let last = -1;
+		for (let index = this.#frontier; index < this.#entries.length; index++) {
+			const entry = this.#entries[index]!;
+			if (entry.state !== "settled") break;
+			if (this.#hasImageRows(entry, width)) last = index;
+		}
+		return last < 0 ? -1 : last + 1;
+	}
+
+	/** Whether the block's measured rows carry an image sequence (cached per width and protocol). */
+	#hasImageRows(entry: TranscriptEntry, width: number): boolean {
+		const protocol = TERMINAL.imageProtocol;
+		const cached = entry.imageScan;
+		if (cached !== undefined && cached.width === width && cached.protocol === protocol) return cached.hasImageRows;
+		let hasImageRows = false;
+		if (protocol !== null) {
+			const rows = this.#measuredRows(entry, width);
+			for (let index = 0; index < rows.length; index++) {
+				if (TERMINAL.isImageLine(rows[index]!)) {
+					hasImageRows = true;
+					break;
+				}
+			}
+		}
+		entry.imageScan = { width, protocol, hasImageRows };
+		return hasImageRows;
+	}
+
 	#liveEntries(): Array<{ entry: TranscriptEntry; index: number }> {
 		const start = this.#offered?.kind === "commit" ? this.#offered.end : this.#frontier;
 		const live: Array<{ entry: TranscriptEntry; index: number }> = [];
@@ -1212,6 +1354,7 @@ export class TranscriptContainer extends Container {
 					stableRowCountByWidth: new Map(),
 					emitted: 0,
 					stableFrozen: false,
+					imageScan: undefined,
 				},
 		);
 		this.#frontier = this.#entries.findIndex(entry => entry.state !== "committed");

package/src/components/box.d.ts

@@ -30,6 +30,7 @@ export declare class Box implements Component {
     setBgFn(bgFn?: (text: string) => string): void;
     setBorder(border?: BoxBorder): void;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /**
      * A `card` when the box has a border or background: the background token
      * picks tone/role (user message, tool state, selection), a border colour

package/src/components/box.ts

@@ -135,6 +135,11 @@ export class Box implements Component {
 		}
 	}
 
+	releaseRenderCaches(): void {
+		this.#invalidateCache();
+		for (const child of this.children) child.releaseRenderCaches?.();
+	}
+
 	/**
 	 * A `card` when the box has a border or background: the background token
 	 * picks tone/role (user message, tool state, selection), a border colour

package/src/components/disclosure.d.ts

@@ -36,6 +36,7 @@ export declare class Disclosure implements Component {
     setExpanded(expanded: boolean): void;
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
+    releaseRenderCaches(): void;
     dispose(): void;
     debugState(): Record<string, unknown>;
     get debugChildren(): readonly Component[];

package/src/components/disclosure.ts

@@ -100,6 +100,14 @@ export class Disclosure implements Component {
 		this.#body?.invalidate?.();
 	}
 
+	releaseRenderCaches(): void {
+		this.#cache = undefined;
+		this.#boundedCache = undefined;
+		this.#summary?.releaseRenderCaches?.();
+		this.#collapsedBody?.releaseRenderCaches?.();
+		this.#body?.releaseRenderCaches?.();
+	}
+
 	dispose(): void {
 		if (this.#disposed) return;
 		this.#disposed = true;