@oh-my-pi/pi-tui 18.3.5 → 18.4.1

package/src/chat/image-loading.ts

@@ -110,6 +110,87 @@ export async function convertImageToPng(image: ImageContent): Promise<ImageConte
 	return { ...image, data, mimeType: "image/png" };
 }
 
+/**
+ * Byte ceiling for {@link convertImageToPngShared}'s resident conversions.
+ * Converted PNGs are larger than the webp/jpeg they came from, so the cache is
+ * bounded and evicts least-recently-used entries rather than growing with the
+ * session's image history.
+ */
+const PNG_CACHE_MAX_BYTES = 32 * 1024 * 1024;
+
+/** Least-recently-used first; {@link touchPngCache} re-inserts on hit. */
+const pngCache = new Map<string, ImageContent>();
+let pngCacheBytes = 0;
+const pngConversionsInFlight = new Map<string, Promise<ImageContent>>();
+
+/** Cache lookup that also marks `key` as most recently used. */
+function touchPngCache(key: string): ImageContent | undefined {
+	const hit = pngCache.get(key);
+	if (!hit) return undefined;
+	pngCache.delete(key);
+	pngCache.set(key, hit);
+	return hit;
+}
+
+/**
+ * Content-addressed identity of an image payload, stable across components and
+ * transcript rebuilds. Callers key their own per-image state by this instead of
+ * positional ids like `${toolCallId}:${index}`, which go stale when the images
+ * behind a position are replaced.
+ */
+export function imagePayloadKey(image: ImageContent): string {
+	return `${image.mimeType}:${image.data.length}:${Bun.hash(image.data)}`;
+}
+
+/**
+ * The PNG conversion of `image` when one is still resident, else `undefined`.
+ * Synchronous so renderers can use an already-converted image on the spot
+ * instead of scheduling another async re-render.
+ */
+export function cachedPngConversion(image: ImageContent): ImageContent | undefined {
+	return touchPngCache(imagePayloadKey(image));
+}
+
+/**
+ * Converts `image` to PNG at most once per distinct payload: concurrent callers
+ * share one in-flight conversion and later callers hit {@link pngCache}.
+ * Kitty-graphics renderers use this because `convertImageToPng` is a full
+ * decode plus re-encode, and the same image is delivered repeatedly (read-result
+ * replay) and rebuilt from scratch on resume, rewind, and `/tree` navigation.
+ *
+ * Rejections are not cached — a payload that failed to decode is retried by the
+ * next caller, matching {@link convertImageToPng}'s contract.
+ */
+export function convertImageToPngShared(image: ImageContent): Promise<ImageContent> {
+	const key = imagePayloadKey(image);
+	const cached = touchPngCache(key);
+	if (cached) return Promise.resolve(cached);
+	const running = pngConversionsInFlight.get(key);
+	if (running) return running;
+	const conversion = convertImageToPng(image)
+		.then(({ data }) => {
+			pngConversionsInFlight.delete(key);
+			// Only the payload is shared; caller-specific fields (`url`,
+			// `providerFile`, `detail`) describe the source image, not this PNG.
+			const converted: ImageContent = { type: "image", data, mimeType: "image/png" };
+			pngCache.set(key, converted);
+			pngCacheBytes += data.length;
+			for (const [oldest, entry] of pngCache) {
+				if (pngCacheBytes <= PNG_CACHE_MAX_BYTES) break;
+				if (oldest === key) continue;
+				pngCache.delete(oldest);
+				pngCacheBytes -= entry.data.length;
+			}
+			return converted;
+		})
+		.catch(error => {
+			pngConversionsInFlight.delete(key);
+			throw error;
+		});
+	pngConversionsInFlight.set(key, conversion);
+	return conversion;
+}
+
 export async function ensureSupportedImageInput(image: ImageContent): Promise<ImageContent | null> {
 	if (SUPPORTED_INPUT_IMAGE_MIME_TYPES.has(image.mimeType)) {
 		return image;

package/src/chat/tool-execution.ts

@@ -1,3 +1,4 @@
+import type { ImageContent } from "@oh-my-pi/pi-ai";
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import { Box } from "../components/box";
 import { SPINNER_ADVANCE_MS } from "../components/loader";
@@ -26,7 +27,7 @@ import { isWaitingPollDetails } from "../tools/wait";
 import { formatStatusIcon, replaceTabs, resolveImageOptions } from "../render/render-utils";
 import type { XdevMountedState } from "../tools/xdev";
 import { isFramedBlockComponent, markFramedBlockComponent, renderStatusLine, WidthAwareText } from "../render/index";
-import { convertImageToPng } from "./image-loading";
+import { cachedPngConversion, convertImageToPngShared, imagePayloadKey } from "./image-loading";
 import { sanitizeWithOptionalSixelPassthrough } from "../render/sixel";
 import { renderDiff } from "../chrome/diff";
 import { type AnimationFrame, trimBlankEdges } from "../chrome/transcript-container";
@@ -296,8 +297,13 @@ export class ToolExecutionComponent extends Container {
 	#editMode?: EditMode;
 	#editDiffPreview?: PerFileDiffPreview[];
 	#previewReady?: PromiseWithResolvers<void>;
-	// Cached converted images for Kitty protocol (which requires PNG), keyed by index
-	#convertedImages: Map<number, { data: string; mimeType: string }> = new Map();
+	// Payload keys whose Kitty PNG conversion is already awaited; the converted
+	// images themselves live in the process-wide cache behind
+	// `convertImageToPngShared`, so rebuilt components reuse them.
+	#kittyConversionsAwaited = new Set<string>();
+	// Conversions this component displays, held so a later re-render still finds
+	// them after the bounded shared cache evicts them.
+	#kittyConverted = new Map<string, ImageContent>();
 	// Spinner animation for partial task results
 	#spinnerFrame?: number;
 	#spinnerActive = false;
@@ -545,26 +551,32 @@ export class ToolExecutionComponent extends Container {
 		if (TERMINAL.imageProtocol !== ImageProtocol.Kitty) return;
 		if (!this.#result) return;
 
-		const imageBlocks = this.#getAllImageBlocks();
-
-		for (let i = 0; i < imageBlocks.length; i++) {
-			const img = imageBlocks[i];
+		for (const img of this.#getAllImageBlocks()) {
 			if (!img.data || !img.mimeType) continue;
-			// Skip if already PNG or already converted
+			// Skip if already PNG or already converted anywhere in this process
 			if (img.mimeType === "image/png") continue;
-			if (this.#convertedImages.has(i)) continue;
+			const image: ImageContent = { type: "image", data: img.data, mimeType: img.mimeType };
+			const key = imagePayloadKey(image);
+			if (this.#kittyConverted.has(key)) continue;
+			const cached = cachedPngConversion(image);
+			if (cached) {
+				this.#kittyConverted.set(key, cached);
+				continue;
+			}
+			if (this.#kittyConversionsAwaited.has(key)) continue;
+			this.#kittyConversionsAwaited.add(key);
 
 			// Convert async - catch errors from processing
-			const index = i;
-			convertImageToPng({ type: "image", data: img.data, mimeType: img.mimeType })
+			convertImageToPngShared(image)
 				.then(converted => {
-					this.#convertedImages.set(index, converted);
+					this.#kittyConverted.set(key, converted);
 					this.#displayInputVersion++;
 					this.#updateDisplay();
 					this.#ui.requestRender();
 				})
 				.catch(() => {
 					// Ignore conversion failures - display will use original image format
+					this.#kittyConversionsAwaited.delete(key);
 				});
 		}
 	}
@@ -840,7 +852,9 @@ export class ToolExecutionComponent extends Container {
 	}
 
 	override render(width: number): readonly string[] {
-		if (!this.#toolActivityVisible || this.#allocation === 0) return [];
+		if (!this.#toolActivityVisible || this.#allocation === 0 || (this.#toolName === "wait" && this.#isBenignSkip())) {
+			return [];
+		}
 		let lines = super.render(width);
 		if (this.#allocation < 3) {
 			// A squeezed allocation degrades only blocks that genuinely overflow it.
@@ -929,6 +943,12 @@ export class ToolExecutionComponent extends Container {
 		this.#renderState.executionStarted = this.#executionStarted;
 		this.#renderState.spinnerFrame = this.#spinnerFrame;
 
+		// Interrupted waits carry only model-facing retry guidance, not user-facing output.
+		if (this.#toolName === "wait" && this.#isBenignSkip()) {
+			this.#contentBox.clear();
+			return;
+		}
+
 		// Non-self-framing tools (custom/extension renderers and the generic
 		// fallback) get a padded, state-tinted block — built-ins that draw their
 		// own frame opt out below via the framed-component mark. A benign skip
@@ -1201,7 +1221,11 @@ export class ToolExecutionComponent extends Container {
 				const img = imageBlocks[i];
 				if (TERMINAL.imageProtocol && this.#showImages && img.data && img.mimeType) {
 					// Use converted PNG for Kitty protocol if available
-					const converted = this.#convertedImages.get(i);
+					const source: ImageContent = { type: "image", data: img.data, mimeType: img.mimeType };
+					const converted =
+						TERMINAL.imageProtocol === ImageProtocol.Kitty && img.mimeType !== "image/png"
+							? (this.#kittyConverted.get(imagePayloadKey(source)) ?? cachedPngConversion(source))
+							: undefined;
 					const imageData = converted?.data ?? img.data;
 					const imageMimeType = converted?.mimeType ?? img.mimeType;
 

package/src/chat/transcript-entry.ts

@@ -68,6 +68,22 @@ export function isUserRequestEntry(entry: TranscriptEntryLike | { type: string }
 	return false;
 }
 
+/**
+ * Recent transcript tail starting at a user-request boundary, so tool calls
+ * and results stay together. ChatTranscriptBuilder drops a tool result whose
+ * initiating call was sliced away, so a tail of orphaned results can leave
+ * the picker without any target.
+ *
+ * A whole user turn may exceed `limit`; paginate rendering if one turn grows too large.
+ */
+export function recentTranscriptEntries(entries: TranscriptEntryLike[], limit = 600): TranscriptEntryLike[] {
+	if (entries.length <= limit) return entries;
+	for (let index = entries.length - limit; index > 0; index--) {
+		if (isUserRequestEntry(entries[index]!)) return entries.slice(index);
+	}
+	return entries;
+}
+
 /** Editable user request text, preserving skill invocation syntax. */
 export function userTurnDraft(entry: TranscriptEntryLike): string | undefined {
 	const message = transcriptEntryMessage(entry);

package/src/chrome/transcript-container.ts

@@ -1,5 +1,6 @@
 import { type Component, Container, type HistoryBatch } from "../tui";
 import * as logger from "@oh-my-pi/pi-utils/logger";
+import { popLoopPhase, pushLoopPhase } from "@oh-my-pi/pi-utils";
 import { isToolActivityComponent } from "./tool-activity";
 
 /** Shared animation time supplied by the constrained transcript root. */
@@ -95,6 +96,15 @@ type Offered =
 const MAX_LIVE_BLOCKS = 256;
 /** Grace before a pressure-blocked frontier is reported; a streaming block may legitimately hold it briefly. */
 const PINNED_FRONTIER_WARN_MS = 30_000;
+/**
+ * Wall-clock budget for composing one retirement batch. A resumed session
+ * hands the container its whole ledger at once, and rendering all of it in the
+ * frame that first paints it blocks the loop for as long as that render takes
+ * (#12933). Retirement stops after the first block that crosses the budget;
+ * the remainder follows on the next frames, which the TUI schedules through
+ * timers, so terminal input runs between batches.
+ */
+const RETIREMENT_BUDGET_MS = 8;
 const EMPTY_ROWS: readonly string[] = [];
 const EMPTY_STABLE_ROWS: readonly TranscriptStableRow[] = [];
 
@@ -290,20 +300,32 @@ export class TranscriptContainer extends Container {
 		this.#replayRequested = false;
 	}
 
-	/** Total rows the live, un-emitted tail occupies at `width`. */
-	liveRowCount(width: number): number {
+	/**
+	 * Total rows the live, un-emitted tail occupies at `width`.
+	 *
+	 * `limit` stops the walk once the total passes it: measuring a resumed
+	 * session's whole ledger costs one full render per block, and callers only
+	 * compare the height against a viewport budget. Past `limit` the result is
+	 * a lower bound, guaranteed only to be greater than `limit`.
+	 */
+	liveRowCount(width: number, limit = Number.POSITIVE_INFINITY): number {
 		this.#syncEntries();
 		this.#settleFinalized();
 		let total = 0;
 		for (const { entry, index } of this.#liveEntries()) {
-			this.#setAllocation(entry.component, Number.MAX_SAFE_INTEGER, this.#lastFrame);
-			const rendered = this.#renderEntry(entry, width);
-			const block = rendered.slice(this.#projectedEmittedRowCount(entry, index, width));
+			const block = this.#liveBlockRows(entry, index, width);
 			if (block.length > 0) total += block.length + (total > 0 ? 1 : 0);
+			if (total > limit) break;
 		}
 		return total;
 	}
 
+	/** One live block's un-emitted rows at `width`, rendered against its full-height allocation. */
+	#liveBlockRows(entry: TranscriptEntry, index: number, width: number): readonly string[] {
+		this.#setAllocation(entry.component, Number.MAX_SAFE_INTEGER, this.#lastFrame);
+		return this.#renderEntry(entry, width).slice(this.#projectedEmittedRowCount(entry, index, width));
+	}
+
 	/** Block spans of the last `renderViewport` output, in output coordinates. Empty when the tail is empty. */
 	getLastViewportSpans(): readonly TranscriptViewportSpan[] {
 		return this.#lastViewportSpans;
@@ -339,23 +361,37 @@ export class TranscriptContainer extends Container {
 			return EMPTY_ROWS;
 		}
 
+		// Collect newest-first and stop one block past what the viewport can
+		// hold: beyond that the emergency layout is already certain, and every
+		// further block would cost a full render to produce rows no frame can
+		// show — the whole ledger on a resumed session's first paint (#12933).
 		const shown: Array<{ entry: TranscriptEntry; index: number }> = [];
 		const blocks: (readonly string[])[] = [];
-		let total = 0;
-		for (const candidate of live) {
-			this.#setAllocation(candidate.entry.component, Number.MAX_SAFE_INTEGER, frame);
-			const rendered = this.#renderEntry(candidate.entry, width);
-			const block = rendered.slice(this.#projectedEmittedRowCount(candidate.entry, candidate.index, width));
+		let unrendered = 0;
+		for (let cursor = live.length - 1; cursor >= 0; cursor--) {
+			if (shown.length > capacity) {
+				unrendered = cursor + 1;
+				break;
+			}
+			const candidate = live[cursor]!;
+			const block = this.#liveBlockRows(candidate.entry, candidate.index, width);
 			if (block.length === 0) continue;
-			total += block.length + (shown.length > 0 ? 1 : 0);
 			shown.push(candidate);
 			blocks.push(block);
 		}
+		shown.reverse();
+		blocks.reverse();
+		let total = 0;
+		for (const block of blocks) total += block.length + (total > 0 ? 1 : 0);
 		if (shown.length === 0) {
 			this.#lastViewportSpans = [];
 			return EMPTY_ROWS;
 		}
-		if (shown.length > capacity) return this.#renderEmergency(shown, width, capacity, frame);
+		if (shown.length > capacity) {
+			// Blocks the walk never reached are still transcript state: the
+			// emergency layout consults them only where it must.
+			return this.#renderEmergency(shown, live.slice(0, unrendered), width, capacity, frame);
+		}
 		if (total <= capacity) {
 			const output: string[] = [];
 			const owners: (Component | undefined)[] = [];
@@ -430,7 +466,15 @@ export class TranscriptContainer extends Container {
 			return this.#offered.kind === "replay" ? this.#offered.batch : undefined;
 		}
 		if (!this.#replayPending) return undefined;
-		const rows = this.#renderReplay(width);
+		// The one path that must compose the whole ledger in a single frame; the
+		// phase label attributes any watchdog block here instead of "unknown".
+		pushLoopPhase("ui.transcript-replay");
+		let rows: readonly string[];
+		try {
+			rows = this.#renderReplay(width);
+		} finally {
+			popLoopPhase();
+		}
 		this.#replayPending = false;
 		if (rows.length === 0) return undefined;
 		const batch: HistoryBatch = { id: this.#nextBatchId++, rows, kind: "replay" };
@@ -455,7 +499,7 @@ export class TranscriptContainer extends Container {
 			const after = this.#renderStablePrefix(entry, offered.emittedEnd, width);
 			rows = after.slice(before.length);
 		} else if (offered.kind === "commit") {
-			rows = this.#renderRange(this.#frontier, offered.end, width, true);
+			rows = this.#renderRange(this.#frontier, offered.end, width, true).rows;
 		} else {
 			rows = this.#renderReplay(width);
 		}
@@ -474,58 +518,74 @@ export class TranscriptContainer extends Container {
 		const room = Math.max(0, Math.trunc(capacity));
 		const live = this.#liveEntries();
 		if (live.length === 0) return undefined;
-		// oxlint-disable-next-line unicorn/no-new-array -- length preallocation
-		const rendered: (readonly string[])[] = new Array(live.length);
-		// oxlint-disable-next-line unicorn/no-new-array -- length preallocation
-		const heights: number[] = new Array(live.length);
-		let total = 0;
-		let visible = 0;
-		for (let index = 0; index < live.length; index++) {
-			const candidate = live[index]!;
-			this.#setAllocation(candidate.entry.component, Number.MAX_SAFE_INTEGER, this.#lastFrame);
-			const renderedEntry = this.#renderEntry(candidate.entry, width);
-			const rows = renderedEntry.slice(
-				this.#renderStablePrefix(candidate.entry, candidate.entry.emitted, width).length,
-			);
-			rendered[index] = rows;
-			heights[index] = rows.length;
-			if (rows.length > 0) total += rows.length + (visible++ > 0 ? 1 : 0);
-		}
-		const overflowing = total > room || this.#liveCount() >= MAX_LIVE_BLOCKS;
-		if (policy === "pressure" && !overflowing) {
-			this.#pinnedFrontier = undefined;
-			return undefined;
-		}
 
+		// Only a render publishes a block's stable rows, so the head renders
+		// before its progressive-append eligibility is read.
 		const head = this.#entries[this.#frontier];
-		if (
+		if (head !== undefined) this.#liveBlockRows(head, this.#frontier, width);
+		const appendHead =
 			policy === "pressure" &&
-			total > room &&
 			head?.mode === "appendOnly" &&
 			!head.stableFrozen &&
 			head.state !== "committed" &&
 			head.emitted < head.stableRows.length
-		) {
+				? head
+				: undefined;
+
+		// Measure the live tail newest-first and stop at the first block that
+		// does not fit: `keep` counts the leading blocks bound for scrollback,
+		// and everything behind them stays unmeasured. Measuring the whole live
+		// region costs one full render per block, which on a resumed session's
+		// first paint is every message it ever had (#12933). The progressive
+		// append path below needs the exact live height to size its emission,
+		// and only runs while a streaming head pins retirement.
+		let tailRows = 0;
+		let liveRows = 0;
+		let keep = 0;
+		let fits = true;
+		for (let cursor = live.length - 1; cursor >= 0; cursor--) {
+			const candidate = live[cursor]!;
+			const height = this.#liveBlockRows(candidate.entry, candidate.index, width).length;
+			if (height > 0) liveRows += height + (liveRows > 0 ? 1 : 0);
+			if (fits) {
+				const next = height > 0 ? tailRows + height + (tailRows > 0 ? 1 : 0) : tailRows;
+				if (next > room) {
+					fits = false;
+					keep = cursor + 1;
+				} else {
+					tailRows = next;
+				}
+			}
+			if (!fits && appendHead === undefined) break;
+		}
+		const overflowing = keep > 0 || this.#liveCount() >= MAX_LIVE_BLOCKS;
+		if (policy === "pressure" && !overflowing) {
+			this.#pinnedFrontier = undefined;
+			return undefined;
+		}
+
+		if (appendHead !== undefined && keep > 0) {
 			// Emit as many finished rows as the overflow needs, in one batch. A
 			// fast stream adds finished rows quicker than one per pressure cycle,
 			// and the live region has to fall back under `room` to stay readable:
 			// rows left behind here are rows dropped from the top of the viewport.
-			const overflow = total - room;
-			const before = this.#renderStablePrefix(head, head.emitted, width);
-			let emittedEnd = head.emitted;
+			// `liveRows` is exact here: the append path measured every live block.
+			const overflow = liveRows - room;
+			const before = this.#renderStablePrefix(appendHead, appendHead.emitted, width);
+			let emittedEnd = appendHead.emitted;
 			let rows: readonly string[] = EMPTY_ROWS;
-			while (emittedEnd < head.stableRows.length && rows.length < overflow) {
-				const after = this.#renderStablePrefix(head, emittedEnd + 1, width);
+			while (emittedEnd < appendHead.stableRows.length && rows.length < overflow) {
+				const after = this.#renderStablePrefix(appendHead, emittedEnd + 1, width);
 				if (!isRowPrefix(before, after) || after.length === before.length) {
-					if (emittedEnd === head.emitted) {
-						this.#freezeStableRows(head, EMPTY_ROWS, "semantic row render added no suffix");
+					if (emittedEnd === appendHead.emitted) {
+						this.#freezeStableRows(appendHead, EMPTY_ROWS, "semantic row render added no suffix");
 					}
 					break;
 				}
 				rows = after.slice(before.length);
 				emittedEnd += 1;
 			}
-			if (emittedEnd > head.emitted) {
+			if (emittedEnd > appendHead.emitted) {
 				const batch: HistoryBatch = {
 					id: this.#nextBatchId++,
 					rows,
@@ -537,31 +597,41 @@ export class TranscriptContainer extends Container {
 			}
 		}
 
-		let end = this.#frontier;
-		let freed = 0;
-		let index = 0;
-		while (end < this.#entries.length && this.#entries[end]!.state === "settled") {
-			if (
-				policy === "pressure" &&
-				total - freed <= room &&
-				this.#liveCount() - (end - this.#frontier) < MAX_LIVE_BLOCKS
-			)
-				break;
-			freed += heights[index]! > 0 ? heights[index]! + 1 : 0;
-			end++;
-			index++;
+		// Shutdown retires everything eligible; pressure retires exactly the
+		// blocks that no longer fit, plus whatever the live-block cap demands.
+		let limit = this.#frontier + keep;
+		if (this.#liveCount() >= MAX_LIVE_BLOCKS) {
+			limit = Math.max(limit, this.#frontier + (this.#liveCount() - (MAX_LIVE_BLOCKS - 1)));
 		}
+		if (policy === "flush") limit = this.#entries.length;
+		let end = this.#frontier;
+		while (end < limit && end < this.#entries.length && this.#entries[end]!.state === "settled") end++;
 		if (end === this.#frontier) {
 			if (policy === "pressure") this.#notePinnedFrontier();
 			return undefined;
 		}
 		this.#pinnedFrontier = undefined;
+		pushLoopPhase("ui.transcript-retire");
+		let retirement: { rows: readonly string[]; end: number };
+		try {
+			// Shutdown must hand over the full prefix; a live frame stops at the
+			// budget and offers the rest on the next frames.
+			retirement = this.#renderRange(
+				this.#frontier,
+				end,
+				width,
+				true,
+				policy === "flush" ? undefined : RETIREMENT_BUDGET_MS,
+			);
+		} finally {
+			popLoopPhase();
+		}
 		const batch: HistoryBatch = {
 			id: this.#nextBatchId++,
-			rows: this.#renderRange(this.#frontier, end, width, true),
+			rows: retirement.rows,
 			kind: "append",
 		};
-		this.#offered = { batch, end, kind: "commit" };
+		this.#offered = { batch, end: retirement.end, kind: "commit" };
 		return batch;
 	}
 
@@ -578,8 +648,7 @@ export class TranscriptContainer extends Container {
 			entry.emitted = offered.emittedEnd;
 		} else if (offered.kind === "commit") {
 			for (let index = this.#frontier; index < offered.end; index++) {
-				this.#entries[index]!.state = "committed";
-				this.#entries[index]!.emitted = 0;
+				this.#retireEntry(this.#entries[index]!);
 			}
 			this.#frontier = offered.end;
 		}
@@ -632,7 +701,7 @@ export class TranscriptContainer extends Container {
 
 	#renderEntry(entry: TranscriptEntry, width: number): readonly string[] {
 		const rendered = trimBlankEdges(entry.component.render(width));
-		if (entry.mode === "mutable" || entry.stableFrozen) return rendered;
+		if (entry.state === "committed" || entry.mode === "mutable" || entry.stableFrozen) return rendered;
 		const appendOnly = entry.component as Component & AppendOnlyTranscriptBlock;
 		const stable = appendOnly.getTranscriptStableRows();
 		if (!isStablePrefix(entry.stableRows, stable)) {
@@ -733,8 +802,25 @@ export class TranscriptContainer extends Container {
 		});
 	}
 
-	#renderRange(start: number, end: number, width: number, trailingBlank: boolean): readonly string[] {
+	/**
+	 * Compose entries `[start, end)` as one ordered retirement payload.
+	 *
+	 * `budgetMs` stops the walk after the first block that crosses it — always
+	 * at least one block — and reports the index actually reached, so a single
+	 * frame never renders more of a resumed ledger than it can afford (#12933).
+	 * Callers that must emit a whole prefix (replay, shutdown flush, recompose
+	 * of an already offered batch) omit it.
+	 */
+	#renderRange(
+		start: number,
+		end: number,
+		width: number,
+		trailingBlank: boolean,
+		budgetMs?: number,
+	): { rows: readonly string[]; end: number } {
 		const rows: string[] = [];
+		const startedAt = budgetMs === undefined ? 0 : performance.now();
+		let reached = start;
 		for (let index = start; index < end; index++) {
 			const entry = this.#entries[index]!;
 			this.#setAllocation(entry.component, Number.MAX_SAFE_INTEGER, this.#lastFrame);
@@ -746,16 +832,19 @@ export class TranscriptContainer extends Container {
 				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);
-			if (block.length === 0) continue;
-			if (rows.length > 0) rows.push("");
-			rows.push(...block);
+			reached = index + 1;
+			if (block.length > 0) {
+				if (rows.length > 0) rows.push("");
+				rows.push(...block);
+			}
+			if (budgetMs !== undefined && performance.now() - startedAt >= budgetMs) break;
 		}
 		if (trailingBlank && rows.length > 0) rows.push("");
-		return rows;
+		return { rows, end: reached };
 	}
 
 	#renderReplay(width: number): readonly string[] {
-		const rows = Array.from(this.#renderRange(0, this.#frontier, width, true));
+		const rows = Array.from(this.#renderRange(0, this.#frontier, width, true).rows);
 		const head = this.#entries[this.#frontier];
 		if (head?.mode === "appendOnly" && head.emitted > 0) {
 			this.#setAllocation(head.component, Number.MAX_SAFE_INTEGER, this.#lastFrame);
@@ -773,24 +862,61 @@ export class TranscriptContainer extends Container {
 			const rendered = this.#renderEntry(entry, width);
 			if (entry.emitted !== entry.stableRows.length) return;
 			if (this.#renderStablePrefix(entry, entry.emitted, width).length !== rendered.length) return;
-			entry.state = "committed";
-			entry.emitted = 0;
+			this.#retireEntry(entry);
 			this.#frontier++;
 		}
 	}
 
+	#retireEntry(entry: TranscriptEntry): void {
+		entry.state = "committed";
+		entry.emitted = 0;
+		entry.stableRows = EMPTY_STABLE_ROWS;
+		entry.renderedStableByWidth = new Map();
+		entry.stableRowCountByWidth = new Map();
+	}
+
 	#startReplay(): void {
 		const head = this.#entries[this.#frontier];
 		this.#replayPending = this.#frontier > 0 || (head?.mode === "appendOnly" && head.emitted > 0);
 		this.#replayRequested = false;
 	}
 
+	/**
+	 * One-row-per-block fallback for a live region that cannot fit the viewport.
+	 * `behind` holds the older live blocks `renderViewport` deliberately left
+	 * unrendered. Only its active blocks (few) and the newest settled block
+	 * offering an emergency row are rendered, so the summary count and the
+	 * surviving emergency row match a full walk without rendering the ledger.
+	 */
 	#renderEmergency(
 		shown: readonly { entry: TranscriptEntry; index: number }[],
+		behind: readonly { entry: TranscriptEntry; index: number }[],
 		width: number,
 		rows: number,
 		frame: AnimationFrame,
 	): readonly string[] {
+		let hiddenBelow = 0;
+		for (const candidate of behind) {
+			if (candidate.entry.state !== "active") continue;
+			if (this.#liveBlockRows(candidate.entry, candidate.index, width).length > 0) hiddenBelow++;
+		}
+		let behindEmergency: { candidate: { entry: TranscriptEntry; index: number }; row: string } | null | undefined;
+		const findBehindEmergency = () => {
+			if (behindEmergency !== undefined) return behindEmergency;
+			behindEmergency = null;
+			for (let index = behind.length - 1; index >= 0; index--) {
+				const candidate = behind[index]!;
+				if (candidate.entry.state !== "settled") continue;
+				const block = candidate.entry.component as Component & FinalizableBlock;
+				if (block.renderTranscriptBlockEmergencyRow === undefined) continue;
+				if (this.#liveBlockRows(candidate.entry, candidate.index, width).length === 0) continue;
+				const row = block.renderTranscriptBlockEmergencyRow(width);
+				if (row === undefined) continue;
+				behindEmergency = { candidate, row };
+				break;
+			}
+			return behindEmergency;
+		};
 		let visibleRows = rows;
 		let visible: { entry: TranscriptEntry; index: number }[] = [];
 		let emergencyCandidate: { entry: TranscriptEntry; index: number } | undefined;
@@ -812,8 +938,16 @@ export class TranscriptContainer extends Container {
 				visible = [candidate, ...visible.slice(1)];
 				break;
 			}
+			if (emergencyCandidate === undefined) {
+				const found = findBehindEmergency();
+				if (found !== null) {
+					emergencyCandidate = found.candidate;
+					emergencyRow = found.row;
+					visible = [found.candidate, ...visible.slice(1)];
+				}
+			}
 
-			let activeTotal = 0;
+			let activeTotal = hiddenBelow;
 			for (const candidate of shown) {
 				if (candidate.entry.state === "active") activeTotal++;
 			}