@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/modes/components/transcript-container.ts

@@ -1,15 +1,49 @@
-import { type Component, Container, type NativeScrollbackLiveRegion, TERMINAL } from "@prometheus-ai/tui";
+import {
+	type Component,
+	Container,
+	type NativeScrollbackCommittedRows,
+	type NativeScrollbackLiveRegion,
+	type RenderStablePrefix,
+	type ViewportTailProvider,
+} from "@prometheus-ai/tui";
 
-const kSnapshot = Symbol("transcript.frozenRender");
+const kSnapshot = Symbol("transcript.liveDiffSnapshot");
 
-interface FrozenRender {
+/**
+ * Per-block render cache: the block's previous stripped contribution plus the
+ * derived append-only state. Still-live blocks use it as input to
+ * {@link deriveLiveCommitState}; finalized blocks wholly inside already
+ * committed native scrollback can replay it without calling render().
+ */
+interface LiveDiffSnapshot {
 	width: number;
-	lines: string[];
+	lines: readonly string[];
 	generation: number;
+	appendOnly: boolean;
+	/**
+	 * Frames remaining until a block that rewrote an interior row may re-earn
+	 * append-only status. `0` means the block is not under rewrite suspicion.
+	 */
+	volatileCooldown: number;
+	/**
+	 * Stable-prefix ratchet (see {@link deriveLiveCommitState}): leading rows
+	 * promoted as commit-safe because they stayed visibly identical for
+	 * {@link STABLE_PREFIX_COMMIT_FRAMES} consecutive frames, plus the in-flight
+	 * candidate run and its age.
+	 */
+	stablePrefixLength: number;
+	candidatePrefixLength: number;
+	candidatePrefixAge: number;
+	/**
+	 * Topmost row index ever observed rewritten in place (see
+	 * {@link deriveLiveCommitState}): the stable-prefix ratchet never promotes
+	 * rows at/after it. `Infinity` until the first rewrite.
+	 */
+	rewriteFloor: number;
 }
 
 interface SnapshotCarrier {
-	[kSnapshot]?: FrozenRender;
+	[kSnapshot]?: LiveDiffSnapshot;
 }
 
 /**
@@ -17,16 +51,32 @@ interface SnapshotCarrier {
  * result, an assistant message mid-stream) reports `false` so the container
  * keeps it inside the live (repaintable) region instead of freezing it. Blocks
  * without the method are treated as finalized — the default, stable behavior.
- *
- * `isTranscriptBlockAppendOnly` marks a still-live block whose rendered rows
- * only grow at the bottom and never re-layout (a streaming assistant reply).
- * Such a block's scrolled-off head is safe to commit to native scrollback even
- * while live; blocks that omit it (tool previews that collapse to a compact
- * result) keep their mutable rows deferred. Default is `false`.
  */
 interface FinalizableBlock {
 	isTranscriptBlockFinalized?(): boolean;
-	isTranscriptBlockAppendOnly?(): boolean;
+	/**
+	 * Monotonic content version for blocks that can still mutate *after*
+	 * reporting finalized (e.g. `AssistantMessageComponent`: the inline error
+	 * restored at the next turn's `agent_start`, late tool-result images). The
+	 * committed-scrollback render bypass only replays a block's previous rows
+	 * when the version is unchanged; without this signal a post-finalize
+	 * mutation would stay invisible until a global invalidation. Blocks that
+	 * never mutate post-finalize simply omit the method.
+	 */
+	getTranscriptBlockVersion?(): number;
+	/**
+	 * Whether a still-live block's visually settled leading rows are durable —
+	 * guaranteed to survive the block's remaining transitions (finalize,
+	 * displacement) byte-stable — and may therefore be promoted as commit-safe
+	 * by {@link deriveLiveCommitState}. Blocks whose pending render is
+	 * provisional (a tool call's tail-window streaming preview, replaced
+	 * wholesale by the result render) return `false`: committing such rows
+	 * strands a stale copy in immutable terminal history the moment the real
+	 * content re-lays-out the block (the engine audit recommits below it —
+	 * "duplication, never loss"). Absent = `true`, the default for blocks
+	 * whose live rows persist (a streaming assistant message).
+	 */
+	isTranscriptBlockCommitStable?(): boolean;
 }
 
 function isBlockFinalized(child: Component): boolean {
@@ -34,59 +84,382 @@ function isBlockFinalized(child: Component): boolean {
 	return fn ? fn.call(child) : true;
 }
 
-function isBlockAppendOnly(child: Component): boolean {
-	const fn = (child as Component & FinalizableBlock).isTranscriptBlockAppendOnly;
-	return fn ? fn.call(child) : false;
+function getBlockVersion(child: Component): number | undefined {
+	const fn = (child as Component & FinalizableBlock).getTranscriptBlockVersion;
+	return fn ? fn.call(child) : undefined;
+}
+
+function isBlockCommitStable(child: Component): boolean {
+	const fn = (child as Component & FinalizableBlock).isTranscriptBlockCommitStable;
+	return fn ? fn.call(child) : true;
+}
+
+// A "plain blank" row is empty or whitespace-only with no ANSI bytes. It marks
+// separation padding (a `Spacer`, or a no-background `paddingY` row) as opposed
+// to a background-colored padding row, whose escape sequences contain `\S` and
+// are therefore preserved as part of a block's visual design.
+const NON_WHITESPACE = /\S/;
+function isPlainBlank(line: string): boolean {
+	return !NON_WHITESPACE.test(line);
+}
+
+// Strip leading/trailing plain-blank rows so each block contributes only its
+// visible body; the container owns the gaps between blocks. Returns the input
+// array unchanged when there is nothing to trim (no allocation on the hot path).
+function stripPlainBlankEdges(lines: readonly string[]): readonly string[] {
+	let start = 0;
+	let end = lines.length;
+	while (start < end && isPlainBlank(lines[start]!)) start++;
+	while (end > start && isPlainBlank(lines[end - 1]!)) end--;
+	return start === 0 && end === lines.length ? lines : lines.slice(start, end);
+}
+
+/**
+ * One block's recorded contribution to the assembled transcript: the raw array
+ * reference its render() returned, the stripped contribution derived from it,
+ * and where those rows landed. Reference-compared on the next render — per the
+ * Component render contract, an identical raw reference proves the block's
+ * rows are byte-identical, so the stripped contribution and the assembled rows
+ * can be reused without re-deriving anything.
+ */
+interface BlockSegment {
+	component: Component;
+	rawRef: readonly string[];
+	contribution: readonly string[];
+	width: number;
+	generation: number;
+	/** Frame row of this block's first emitted row (the separator when present). */
+	startRow: number;
+	/** Rows emitted: separator + contribution (0 for empty contributions). */
+	rowCount: number;
+	sep: number;
+	/** Whether the block reported finalized when this segment was rendered. */
+	finalized: boolean;
+	/** Block version observed when this segment was rendered (see {@link FinalizableBlock}). */
+	version: number | undefined;
+}
+
+const EMPTY_SEGMENTS: BlockSegment[] = [];
+/** Shared empty result for an empty viewport-tail render (no allocation). */
+const EMPTY_TAIL: readonly string[] = [];
+
+interface LiveCommitState {
+	appendOnly: boolean;
+	volatileCooldown: number;
+	stablePrefixLength: number;
+	candidatePrefixLength: number;
+	candidatePrefixAge: number;
+	rewriteFloor: number;
+	safeLength: number;
+}
+
+/**
+ * Render frames a block must stay clean (static or append-shaped) after an
+ * interior rewrite before its rows become committable again. A one-off
+ * re-layout (a codespan finalizing across a wrap boundary, a paragraph
+ * re-parsed as a heading) only suspends commits briefly — the pinned emitter
+ * appends from the stalled high-water mark, so the gap backfills contiguously
+ * once the block re-earns append-only. Periodic animations (a spinner rewrites
+ * its row every few frames) keep resetting the countdown and never re-earn it,
+ * so genuinely volatile blocks stay deferred. Frames arrive at most at the
+ * TUI's 30 Hz render cadence, so 30 frames ≈ 1s of clean streaming.
+ */
+const VOLATILE_REARM_FRAMES = 30;
+
+/**
+ * Consecutive frames a leading row run must stay visibly identical before it
+ * is promoted as commit-safe even though the block's tail keeps rewriting.
+ * Append-only detection alone is all-or-nothing per block: one perpetually
+ * ticking row (a task tool's progress tree, per-agent cost/tool counters, a
+ * log line spinner) suspends commits for the WHOLE block forever, so once the
+ * block outgrows the viewport its static head — e.g. a task's prompt/context
+ * markdown — is neither committed to native scrollback nor on screen: the
+ * transcript reads as cut off for the entire (possibly minutes-long) run.
+ * The ratchet commits the settled head while only the genuinely volatile tail
+ * stays deferred. If a promoted row is later rewritten (a collapsing
+ * preview), the engine's committed-prefix audit re-anchors and recommits —
+ * duplication, never loss — and the ratchet retreats to the divergence.
+ */
+const STABLE_PREFIX_COMMIT_FRAMES = 30;
+
+/**
+ * Rows at a live block's tail treated as the volatile streaming edge. Real
+ * streaming is not strictly append-only at the bottom: the in-flight markdown
+ * paragraph re-wraps as words arrive (rewriting its last 1-2 visual rows), an
+ * unclosed token (`**bold`, a half-streamed link) re-renders when its closer
+ * arrives, and a wrap-shrink moves the last word onto a new row. Divergence
+ * confined to this zone is clean growth, and the zone itself is held back
+ * from the offered commit boundary — so a tolerated rewrite can never touch a
+ * row the engine may have committed. Width 4 covers the observed shapes (≤2
+ * rows) with margin for wide glyphs and multi-row token spans; the cost is
+ * only that the last 4 rows of a live block commit at finalization instead of
+ * mid-stream, which is invisible (they are on screen — the viewport is always
+ * taller than the holdback).
+ */
+const TAIL_VOLATILITY_ROWS = 4;
+
+/**
+ * Visible-content form of a row: SGR/OSC bytes and trailing pad spaces are
+ * write framing, not content. A styled line's closing escape moves when the
+ * line stops being the last of its span (a wrapped thinking paragraph growing
+ * by one row), and width-padded rows shift their trailing spaces as text
+ * grows; both leave the on-screen cells identical and must not count as a
+ * rewrite of a committed-candidate row. Committed scrollback rows are written
+ * with a full SGR/OSC reset terminator, so escape-placement drift between
+ * visually identical renders cannot bleed styles across rows.
+ */
+function normalizeRow(line: string): string {
+	return Bun.stripANSI(line).trimEnd();
+}
+
+function rowsVisiblyEqual(prev: string, cur: string): boolean {
+	return prev === cur || normalizeRow(prev) === normalizeRow(cur);
+}
+
+/**
+ * Whether `cur` is `prev` grown in place: the visible content of `prev` is a
+ * strict-or-equal prefix of `cur`'s (token streaming appending to the cursor
+ * row). Escape placement and pad drift are ignored, same as rowsVisiblyEqual.
+ */
+function rowVisiblyGrew(prev: string, cur: string): boolean {
+	return normalizeRow(cur).startsWith(normalizeRow(prev));
+}
+
+function hasValidSnapshot(
+	snapshot: LiveDiffSnapshot | undefined,
+	width: number,
+	generation: number,
+): snapshot is LiveDiffSnapshot {
+	return snapshot !== undefined && snapshot.generation === generation && snapshot.width === width;
+}
+
+function commonPrefixLength(prev: readonly string[], cur: readonly string[]): number {
+	const limit = Math.min(prev.length, cur.length);
+	let i = 0;
+	while (i < limit && rowsVisiblyEqual(prev[i]!, cur[i]!)) i++;
+	return i;
+}
+
+function commonSuffixLength(prev: readonly string[], cur: readonly string[], prefixLength: number): number {
+	const limit = Math.min(prev.length - prefixLength, cur.length - prefixLength);
+	let i = 0;
+	while (i < limit && rowsVisiblyEqual(prev[prev.length - 1 - i]!, cur[cur.length - 1 - i]!)) i++;
+	return i;
+}
+
+function deriveLiveCommitState(
+	previous: LiveDiffSnapshot | undefined,
+	current: readonly string[],
+	width: number,
+	generation: number,
+): LiveCommitState {
+	let appendOnly = false;
+	let volatileCooldown = 0;
+	let stablePrefixLength = 0;
+	let candidatePrefixLength = 0;
+	let candidatePrefixAge = 0;
+	let rewriteFloor = Number.POSITIVE_INFINITY;
+	let trailingRowGrowth = false;
+	if (hasValidSnapshot(previous, width, generation)) {
+		appendOnly = previous.appendOnly;
+		volatileCooldown = previous.volatileCooldown;
+		stablePrefixLength = previous.stablePrefixLength;
+		candidatePrefixLength = previous.candidatePrefixLength;
+		candidatePrefixAge = previous.candidatePrefixAge;
+		rewriteFloor = previous.rewriteFloor;
+
+		const prefixLength = commonPrefixLength(previous.lines, current);
+		const staticRender = prefixLength === previous.lines.length && prefixLength === current.length;
+		let cleanFrame = true;
+		if (!staticRender) {
+			const suffixLength = commonSuffixLength(previous.lines, current, prefixLength);
+			// Append-only growth never rewrites a row that may already have scrolled
+			// into native scrollback; it only grows the block at/near its tail. Two
+			// shapes qualify:
+			// - a pure insertion that preserves every previous row across a
+			//   matching prefix + suffix (a bottom append, or an insertion above
+			//   stable trailing chrome like a streaming tool's footer/border);
+			// - a rewrite whose divergence BEGINS inside the trailing
+			//   TAIL_VOLATILITY_ROWS of the previous render — the streaming edge:
+			//   the in-flight paragraph re-wrapping as words arrive (its last 1-2
+			//   visual rows), an unclosed markdown token (`**bold`) re-rendering
+			//   when its closer streams in, a wrap-shrink pushing the last word
+			//   onto an appended row. That zone is held back from `safeLength`
+			//   below, so a tolerated rewrite can never touch a row that was
+			//   offered for commit.
+			// The anchor matters: the gap must START in the tail zone, not merely
+			// be small — a one-row ticker mid-block with stable rows beneath it
+			// would otherwise classify clean, get offered past, and rewrite
+			// committed rows on every tick. Any deeper divergent row means the
+			// block re-laid-out committed-candidate content — a rewrite, which
+			// suspends commits until the block re-earns append-only.
+			const preservedEveryRow = prefixLength + suffixLength >= previous.lines.length;
+			const tailConfined = preservedEveryRow || prefixLength >= previous.lines.length - TAIL_VOLATILITY_ROWS;
+			if (tailConfined && current.length >= previous.lines.length) {
+				// Strict trailing-row growth: every previous row except the last
+				// is visibly unchanged and the last grew in place as a visible
+				// prefix, with no rows appended — a line accumulating tokens.
+				// The sole divergent row is the block's physical last row, which
+				// the engine's window floor never commits while it stays last
+				// (chunkTo ≤ windowTop ≤ last row index), so the volatile-tail
+				// holdback below is unnecessary: the whole body is offerable and
+				// the block's scrolled-off head reaches native scrollback.
+				trailingRowGrowth =
+					current.length === previous.lines.length &&
+					prefixLength === previous.lines.length - 1 &&
+					rowVisiblyGrew(previous.lines[prefixLength]!, current[prefixLength]!);
+				if (volatileCooldown === 0) appendOnly = true;
+				// Clean growth inserts/rewrites rows at the divergence; a floor
+				// inside the preserved suffix travels down with it, a floor at or
+				// above the divergent zone stays put (conservative: a stale floor
+				// index can only point at an earlier row, never a later one).
+				const delta = current.length - previous.lines.length;
+				if (delta > 0 && Number.isFinite(rewriteFloor)) {
+					const suffixStart = Math.max(prefixLength, previous.lines.length - suffixLength);
+					if (rewriteFloor >= suffixStart) rewriteFloor += delta;
+				}
+			} else {
+				cleanFrame = false;
+				appendOnly = false;
+				volatileCooldown = VOLATILE_REARM_FRAMES;
+			}
+		}
+		if (cleanFrame && volatileCooldown > 0) volatileCooldown--;
+
+		// Stable-prefix ratchet, independent of append-only. `prefixLength` is
+		// this frame's visibly-unchanged leading run; the candidate accumulates
+		// the MINIMUM prefix across a STABLE_PREFIX_COMMIT_FRAMES window, so
+		// promotion means every promoted row stayed identical for the whole
+		// window (row r is inside frame i's common prefix iff r < p_i, so
+		// r < min(p) holds for every frame of the window). A row settling
+		// mid-window promotes at most two windows later. The engine audit owns
+		// any promoted rows that already committed (recommit, never loss).
+		if (prefixLength < stablePrefixLength) {
+			// A divergence inside the promoted run is the ratchet's proof of
+			// over-promotion: this row was visibly stable for a full window,
+			// got promoted (and likely committed), and then mutated anyway — a
+			// slow ticker (an agent row's tool/cost counter, a growing progress
+			// tree), not settling content. It will mutate again, and every
+			// promote→mutate cycle makes the engine audit recommit, spraying a
+			// stale snapshot of the block into native scrollback. Floor the
+			// ratchet at the divergence permanently: rows above it may still
+			// promote, rows at/below it never re-promote while the block lives.
+			// One-off re-layouts before any promotion (a call→result frame
+			// transition, a codespan finalizing) never hit this branch, and the
+			// append-only re-arm path commits the full block regardless of the
+			// floor.
+			rewriteFloor = Math.min(rewriteFloor, prefixLength);
+			stablePrefixLength = prefixLength;
+			candidatePrefixLength = prefixLength;
+			candidatePrefixAge = 0;
+		} else {
+			candidatePrefixLength =
+				candidatePrefixAge === 0 ? prefixLength : Math.min(candidatePrefixLength, prefixLength);
+			candidatePrefixAge++;
+			if (candidatePrefixAge >= STABLE_PREFIX_COMMIT_FRAMES) {
+				// Cap at the volatile-tail holdback: a long static stretch would
+				// otherwise promote the streaming edge itself (min prefix == full
+				// length), and the next chunk's tail re-wrap would then rewrite
+				// offered rows.
+				stablePrefixLength = Math.min(
+					candidatePrefixLength,
+					rewriteFloor,
+					Math.max(0, current.length - TAIL_VOLATILITY_ROWS),
+				);
+				candidatePrefixLength = prefixLength;
+				candidatePrefixAge = 0;
+			}
+		}
+	}
+
+	return {
+		appendOnly,
+		volatileCooldown,
+		stablePrefixLength,
+		candidatePrefixLength,
+		candidatePrefixAge,
+		rewriteFloor,
+		// A clean-streaming block's body is committable up to the volatile-tail
+		// holdback (the streaming edge is never offered, so its tolerated
+		// rewrites can never touch committed rows); otherwise the settled head
+		// still is — only the volatile tail stays deferred. Strict in-place
+		// growth of the trailing row skips the holdback: its only mutable row
+		// is the block's last, which cannot commit while it remains last.
+		safeLength: appendOnly
+			? trailingRowGrowth
+				? current.length
+				: Math.max(stablePrefixLength, current.length - TAIL_VOLATILITY_ROWS, 0)
+			: stablePrefixLength,
+	};
 }
 
 /**
- * Transcript container that freezes the rendered output of every block except
- * the bottom-most (live) one on terminals where committed native scrollback is
- * immutable.
+ * Transcript container that renders every block's current content each frame
+ * and reports the live-region seam (`NativeScrollbackLiveRegion`) that gates
+ * the engine's append-only scrollback commits.
  *
- * On ED3-risk terminals with an unobservable viewport (ghostty/kitty/iTerm2/…)
- * the renderer cannot clear saved lines (`\x1b[3J` may yank a reader) or query
- * whether the user has scrolled, so any block that re-lays-out *after* it has
- * scrolled past the viewport leaves a stale duplicate above the live region
- * (a finalized assistant message re-wrapping, a tool preview collapsing to its
- * compact result, a late async tool completion). The renderer's only safe move
- * for such an offscreen edit is to not repaint — which is correct only if the
- * committed region never changes underneath it.
+ * The engine never rewrites committed history: rows above the seam that have
+ * entered the tape keep whatever bytes they were committed with ("let the
+ * history be"), while the visible window always repaints from each block's
+ * latest render — a late tool result, a post-finalize error pin, or an expand
+ * toggle is always reflected on screen. Blocks that are still mutating (an
+ * unfinalized tool, a streaming assistant message) stay below the seam so
+ * their rows do not enter history while they can still change; a streaming
+ * block whose render grows append-only deepens the seam through its settled
+ * head so a long reply's scrolled-off rows still reach scrollback mid-stream.
  *
- * This container provides that guarantee: a block's render is snapshotted while
- * it is the live (bottom-most) block, and once a newer block is appended it
- * replays the snapshot instead of recomputing. Mutations after a block leaves
- * live are intentionally deferred until the next checkpoint {@link thaw} (prompt
- * submit → native-scrollback rebuild), where the whole transcript is replayed
- * and any drift reconciles safely. On terminals that can rebuild history this
- * freezing is unnecessary, so it renders every block live for full fidelity.
+ * Assembly is incremental: the returned array is persistent and mutated in
+ * place. Each block's render is still called every frame, but a block whose
+ * render returned the same array reference at an unchanged offset reuses its
+ * previously assembled rows; the array is truncated and re-pushed only from
+ * the first divergent block. The leading byte-identical row count is reported
+ * through {@link RenderStablePrefix} so the engine can skip marker scanning,
+ * line preparation, and the committed-prefix audit for those rows.
  */
-export class TranscriptContainer extends Container implements NativeScrollbackLiveRegion {
-	// Bumped to invalidate every block's snapshot at once; a snapshot is only
-	// honored when its stored generation still matches.
+export class TranscriptContainer
+	extends Container
+	implements NativeScrollbackLiveRegion, NativeScrollbackCommittedRows, RenderStablePrefix, ViewportTailProvider
+{
+	// Bumped to retire every block's diff snapshot at once (theme change /
+	// clear); a snapshot is only honored when its stored generation matches.
 	#generation = 0;
-	// Line index where the live (repaintable) region began on the previous
-	// render — the start of the earliest still-mutating block, or the bottom
-	// block when everything is finalized. A block leaves the live region only
-	// once it has finalized AND a finalized block sits below it; the frame it
-	// crosses out is recomputed so it freezes at its true final content, not the
-	// mid-stream snapshot it last rendered while live (TUI render coalescing can
-	// advance a block's content in the very frame it stops being live).
-	#prevLiveStartIndex = 0;
 	// Local line index where the current live region begins in the most recent
-	// render. TUI extends the native-scrollback pinned region from this point
-	// through the live blocks and the root chrome rendered below them.
+	// render. TUI commits rows to native scrollback only above this seam (or
+	// the deeper commit-safe end below).
 	#nativeScrollbackLiveRegionStart: number | undefined;
-	// Local line index up to which the leading run of live blocks is append-only
-	// (a streaming assistant reply): everything in [liveRegionStart,
-	// commitSafeEnd) only grows at the bottom and never re-layouts, so its
-	// scrolled-off head is safe to commit to native scrollback. `undefined` when
-	// the first live block is volatile (a tool preview).
+	// Local line index up to which the leading run of live blocks is safe to
+	// commit. Finalized blocks contribute their full body; still-live blocks
+	// contribute only while their render has been observed growing without
+	// visibly rewriting a previously rendered interior row (escape placement
+	// and pad drift are ignored). A rewrite suspends the block's contribution
+	// until it re-earns append-only via VOLATILE_REARM_FRAMES clean frames;
+	// the engine then backfills the stalled gap.
 	#nativeScrollbackCommitSafeEnd: number | undefined;
-
+	// Local line index up to which the leading run of live blocks is DURABLE: a
+	// commit-stable block's full body is permanent content even while its interior
+	// rows re-lay-out (a streaming markdown table re-aligning columns), so the
+	// engine must append their scroll-off snapshot rather than drop it. Reported
+	// separately from the byte-stable commit-safe end because these rows may still
+	// drift after commit; the engine commits them audit-exempt. Provisional
+	// (commit-unstable) blocks never extend it.
+	#nativeScrollbackSnapshotSafeEnd: number | undefined;
+	// Persistent assembled transcript rows. Rows before the stable floor are
+	// byte-identical to the previous render; rows at/after it were re-pushed.
+	#lines: string[] = [];
+	#segments: BlockSegment[] = EMPTY_SEGMENTS;
+	#renderWidth = -1;
+	// Local rows already committed to native scrollback by the previous frame.
+	// Finalized blocks wholly before this boundary are immutable on-screen history;
+	// their previous contribution can be replayed without calling render().
+	#committedRows = 0;
+	// Stable-prefix floor accumulated across renders since the last
+	// getRenderStablePrefixRows() read (see RenderStablePrefix: reading
+	// consumes the report and re-bases the baseline). Out-of-band renders
+	// between engine frames lower it; they can never inflate it.
+	#stableRowsFloor = 0;
 	override invalidate(): void {
-		// A theme/global invalidation forces a full recompute on the rebuild that
-		// follows; retire every snapshot.
+		// Theme/global invalidation: retire every diff snapshot so stale styling
+		// is not diffed against the recolored render.
 		this.#generation++;
 		super.invalidate();
 	}
@@ -96,6 +469,16 @@ export class TranscriptContainer extends Container implements NativeScrollbackLi
 		super.clear();
 	}
 
+	setNativeScrollbackCommittedRows(rows: number): void {
+		this.#committedRows = Number.isFinite(rows) ? Math.max(0, Math.trunc(rows)) : 0;
+	}
+
+	getRenderStablePrefixRows(): number {
+		const value = Math.min(this.#stableRowsFloor, this.#lines.length);
+		this.#stableRowsFloor = this.#lines.length;
+		return value;
+	}
+
 	getNativeScrollbackLiveRegionStart(): number | undefined {
 		return this.#nativeScrollbackLiveRegionStart;
 	}
@@ -104,28 +487,111 @@ export class TranscriptContainer extends Container implements NativeScrollbackLi
 		return this.#nativeScrollbackCommitSafeEnd;
 	}
 
+	getNativeScrollbackSnapshotSafeEnd(): number | undefined {
+		return this.#nativeScrollbackSnapshotSafeEnd;
+	}
+
 	/**
-	 * Retire all frozen snapshots so the next render reflects each block's current
-	 * state. Call at reconciliation checkpoints (prompt submit) where the whole
-	 * transcript is replayed into native scrollback and any drift a frozen block
-	 * accumulated is reconciled.
+	 * Whether `component` sits below a still-mutating block — i.e. inside the
+	 * live region, where its rows cannot have been committed to native
+	 * scrollback yet (commits are prefix-only and stop at the first
+	 * still-live block). Callers that retract ephemeral blocks (IRC cards)
+	 * must check this: removing a block whose rows may already be in history
+	 * is an interior deletion of the committed prefix, which the engine can
+	 * only repair by recommitting everything below it — duplication.
 	 */
-	thaw(): void {
-		this.#generation++;
+	isWithinLiveRegion(component: Component): boolean {
+		const index = this.children.indexOf(component);
+		if (index < 0) return false;
+		for (let i = 0; i < index; i++) {
+			if (!isBlockFinalized(this.children[i]!)) return true;
+		}
+		return false;
 	}
 
-	override render(width: number): string[] {
+	/**
+	 * Whether `component` is inside the live (repaintable) region exactly as
+	 * {@link render} computes it: at/after the first still-mutating block, or
+	 * the transcript tail when every block has finalized. Unlike
+	 * {@link isWithinLiveRegion} (strictly below a still-mutating block, i.e.
+	 * guaranteed-uncommitted), this also counts the trailing block that anchors
+	 * the live region. Self-animating finalized blocks (a detached task's
+	 * shimmering progress rows) poll this to stop animating — and settle on
+	 * static bytes — the moment they sit above the seam, where their rows
+	 * become commit-eligible native-scrollback history.
+	 */
+	isBlockInLiveRegion(component: Component): boolean {
+		const children = this.children;
+		const index = children.indexOf(component);
+		if (index < 0) return false;
+		for (let i = 0; i <= index; i++) {
+			if (!isBlockFinalized(children[i]!)) return true;
+		}
+		// Every block at/before `index` finalized: the live region starts at the
+		// first unfinalized block below it, or at the last child when none exists.
+		for (let i = index + 1; i < children.length; i++) {
+			if (!isBlockFinalized(children[i]!)) return false;
+		}
+		return index === children.length - 1;
+	}
+
+	/**
+	 * Render only the bottom `maxRows` rows of the transcript at `width`, walking
+	 * blocks from the last toward the first and stopping the instant enough rows
+	 * are collected — blocks above the fold are never rendered. The engine's
+	 * resize viewport fast path uses this so a drag (a SIGWINCH burst, each event
+	 * a fresh width that misses every per-width cache) re-lays-out only the
+	 * handful of visible blocks instead of the whole history every event.
+	 *
+	 * State-isolated by contract: touches none of the persistent full-compose
+	 * fields (#lines, #segments, the per-block diff snapshots, the commit/stable
+	 * bookkeeping), so the authoritative full render on settle reconciles exactly
+	 * as if this never ran. Calling each block's render() still warms its own
+	 * per-width cache, which that settle render then reuses for free.
+	 *
+	 * Consecutive visible blocks are joined by exactly one blank separator, the
+	 * same rule render() applies, so the result equals the bottom of a full
+	 * render except for an at-most-one-row separator on the topmost included
+	 * block — a transient discrepancy the settle paint overwrites.
+	 */
+	renderViewportTail(width: number, maxRows: number): readonly string[] {
+		width = Math.max(1, width);
+		if (maxRows <= 0) return EMPTY_TAIL;
+		const collected: (readonly string[])[] = [];
+		let total = 0;
+		for (let i = this.children.length - 1; i >= 0 && total < maxRows; i--) {
+			const contribution = stripPlainBlankEdges(this.children[i]!.render(width));
+			if (contribution.length === 0) continue;
+			// One blank separator sits between this block and the (already
+			// collected) visible block below it.
+			if (collected.length > 0) total += 1;
+			collected.push(contribution);
+			total += contribution.length;
+		}
+		if (collected.length === 0) return EMPTY_TAIL;
+		const rows: string[] = [];
+		for (let k = collected.length - 1; k >= 0; k--) {
+			if (rows.length > 0) rows.push("");
+			const body = collected[k]!;
+			for (let j = 0; j < body.length; j++) rows.push(body[j]!);
+		}
+		return rows.length > maxRows ? rows.slice(rows.length - maxRows) : rows;
+	}
+
+	override render(width: number): readonly string[] {
 		width = Math.max(1, width);
 		this.#nativeScrollbackLiveRegionStart = undefined;
 		this.#nativeScrollbackCommitSafeEnd = undefined;
-		if (!TERMINAL.eagerEraseScrollbackRisk) return super.render(width);
+		this.#nativeScrollbackSnapshotSafeEnd = undefined;
 
 		const count = this.children.length;
+
 		// The live region spans from the earliest still-mutating block through the
-		// bottom. A block that has not finalized must stay repaintable: out-of-band
-		// inserts (TTSR/todo cards) can append a finalized block *below* a tool that
-		// is still awaiting its result, and freezing the tool there would strand its
-		// committed rows on the mid-stream preview the late result never reaches.
+		// bottom. A block that has not finalized must stay below the seam: out-of-
+		// band inserts (TTSR/todo cards) can append a finalized block *below* a
+		// tool that is still awaiting its result, and committing the tool there
+		// would strand its history rows on the mid-stream preview the late result
+		// never reaches.
 		let liveStartIndex = count - 1;
 		for (let i = 0; i < count; i++) {
 			if (!isBlockFinalized(this.children[i]!)) {
@@ -133,49 +599,208 @@ export class TranscriptContainer extends Container implements NativeScrollbackLi
 				break;
 			}
 		}
-		// Blocks at [prevLiveStart, liveStart) just crossed out of the live region;
-		// recompute them so they freeze at their final content. Everything below
-		// the lower of the two cutoffs was already frozen last frame and replays.
-		const replayCutoff = Math.min(liveStartIndex, this.#prevLiveStartIndex);
-		this.#prevLiveStartIndex = liveStartIndex;
-
-		const lines: string[] = [];
-		// Tracks whether we are still inside the leading run of append-only live
-		// blocks. The first non-append-only live block (or a finalized block below
-		// the live region's start, which cannot happen for a leading run) closes it.
+
+		const lines = this.#lines;
+		const previousSegments = this.#segments;
+		const segments: BlockSegment[] = new Array(count);
+		// Poisoned until the walk completes: a block render throwing mid-walk
+		// leaves the persistent array half-rebuilt, and the next render must
+		// not trust stale segments against it. Restored at the end.
+		this.#segments = EMPTY_SEGMENTS;
+		const stableFloorBefore = this.#stableRowsFloor;
+		this.#stableRowsFloor = 0;
+		// Stability requires the same width and, per segment, the same block at
+		// the same offset returning the same array reference. The first
+		// divergence truncates the persistent array there; everything after
+		// re-pushes.
+		let chainStable = this.#renderWidth === width;
+		this.#renderWidth = width;
+		// Entry-unstable (width change): the divergence truncation inside the
+		// loop only fires on a stable→unstable transition, so reset the
+		// persistent array here to keep the `!chainStable ⇒ lines.length === row`
+		// invariant — otherwise re-pushed rows land after the stale frame.
+		if (!chainStable) lines.length = 0;
+
+		// Tracks whether we are still inside the leading run of commit-safe live
+		// blocks. The first still-live volatile block closes it, but rendering
+		// continues so lower blocks remain visible.
 		let commitSafeOpen = true;
+		// The live-region start is recorded at the first visible row at/after
+		// liveStartIndex; empty leading blocks (or a separator) must not claim it
+		// early.
+		let liveRecorded = false;
+		// Frame row cursor: rows emitted (reused or pushed) so far.
+		let row = 0;
+		let stableRows = 0;
 		for (let i = 0; i < count; i++) {
 			const child = this.children[i]! as Component & SnapshotCarrier;
-			if (i >= liveStartIndex) {
-				if (i === liveStartIndex) this.#nativeScrollbackLiveRegionStart = lines.length;
+
+			// This child's contribution: its current render with plain-blank
+			// top/bottom edges stripped (the container owns inter-block gaps).
+			// Finalized blocks wholly inside committed native scrollback can reuse
+			// their previous contribution without calling render(): those rows are
+			// immutable terminal history for the current width/generation. Blocks
+			// outside committed history still render normally so late results,
+			// post-finalize re-layouts, and expand toggles remain visible.
+			const previousSnapshot = child[kSnapshot];
+			const previous = previousSegments[i];
+			const finalized = isBlockFinalized(child);
+			const version = getBlockVersion(child);
+			const committedReusable =
+				previous !== undefined &&
+				previous.component === child &&
+				previous.width === width &&
+				previous.generation === this.#generation &&
+				previous.startRow === row &&
+				previous.startRow + previous.rowCount <= this.#committedRows &&
+				finalized &&
+				// Only replay bytes that were themselves produced by a finalized
+				// render: a block finalizing between frames may have changed content
+				// while its rows were already committed via the append-only live
+				// path, so the first post-transition frame must render. Defense in
+				// depth on the transcript side — the TUI commit policy should keep
+				// that window closed, but the safety must not live there alone.
+				previous.finalized &&
+				// Post-finalize mutations (inline error restore, late tool images)
+				// bump the block version; a mismatch forces a real render so the
+				// committed-prefix audit can observe and re-anchor the change.
+				previous.version === version;
+			const raw = committedReusable ? previous.rawRef : child.render(width);
+			const reusable =
+				committedReusable ||
+				(previous !== undefined &&
+					previous.component === child &&
+					previous.rawRef === raw &&
+					previous.width === width &&
+					previous.generation === this.#generation);
+			const contribution = reusable ? previous.contribution : stripPlainBlankEdges(raw);
+			let liveCommitState: LiveCommitState | undefined;
+			// Provisional live renders (commit-unstable blocks) never feed the
+			// promotion machinery: their settled-looking rows are replaced
+			// wholesale on finalize, so offering them would commit a stale
+			// preview the result render can only duplicate, never erase.
+			if (i >= liveStartIndex && !finalized && isBlockCommitStable(child)) {
+				liveCommitState = deriveLiveCommitState(previousSnapshot, contribution, width, this.#generation);
+			}
+			// Cache the latest contribution as the next frame's diff input.
+			child[kSnapshot] = {
+				width,
+				lines: contribution,
+				generation: this.#generation,
+				appendOnly: liveCommitState?.appendOnly ?? false,
+				volatileCooldown: liveCommitState?.volatileCooldown ?? 0,
+				stablePrefixLength: liveCommitState?.stablePrefixLength ?? 0,
+				candidatePrefixLength: liveCommitState?.candidatePrefixLength ?? 0,
+				candidatePrefixAge: liveCommitState?.candidatePrefixAge ?? 0,
+				rewriteFloor: liveCommitState?.rewriteFloor ?? Number.POSITIVE_INFINITY,
+			};
+
+			// Empty (or stripped-to-nothing) children contribute nothing and never
+			// affect spacing or the live-region offsets. An empty still-live child
+			// still closes the commit-safe run: if it later gains rows, it pushes
+			// everything below it.
+			if (contribution.length === 0) {
+				if (i >= liveStartIndex && commitSafeOpen && !finalized) commitSafeOpen = false;
+				if (chainStable && !(reusable && previous.rowCount === 0 && previous.startRow === row)) {
+					chainStable = false;
+					lines.length = row;
+				}
+				if (chainStable) stableRows = row;
+				segments[i] = {
+					component: child,
+					rawRef: raw,
+					contribution,
+					width,
+					generation: this.#generation,
+					startRow: row,
+					rowCount: 0,
+					sep: 0,
+					finalized,
+					version,
+				};
+				continue;
+			}
+
+			// Every block is separated from preceding visible content by exactly one
+			// blank row — skipped when it opens the transcript or the prior row is
+			// already a plain blank (a fragment's own trailing pad), never doubling.
+			// `lines[row - 1]` is valid in both modes: reused rows are still present
+			// in the persistent array, re-pushed rows were just written.
+			const sep = row > 0 && !isPlainBlank(lines[row - 1]!) ? 1 : 0;
+
+			// The separator before the first live block stays in the committed
+			// prefix (it is deterministic once the prior block's body is settled),
+			// so the live region begins at the block's first content row.
+			if (!liveRecorded && i >= liveStartIndex) {
+				this.#nativeScrollbackLiveRegionStart = row + sep;
+				liveRecorded = true;
+			}
+
+			const rowCount = sep + contribution.length;
+			const stable = chainStable && reusable && previous.startRow === row && previous.sep === sep;
+			if (stable) {
+				stableRows = row + rowCount;
 			} else {
-				const snapshot = child[kSnapshot];
-				// Replay a frozen block's last live render. A stale generation
-				// (post-thaw) or width mismatch (resize, explicit rebuild) recomputes
-				// instead, as does a block that was still live last frame (i >= cutoff).
-				if (i < replayCutoff && snapshot && snapshot.generation === this.#generation && snapshot.width === width) {
-					lines.push(...snapshot.lines);
-					continue;
+				if (chainStable) {
+					chainStable = false;
+					lines.length = row;
 				}
+				if (sep) lines.push("");
+				for (let j = 0; j < contribution.length; j++) lines.push(contribution[j]!);
 			}
-			const rendered = child.render(width);
-			// Extend the commit-safe boundary through each leading append-only live
-			// block. `lines.length` here is this block's start offset; the boundary
-			// runs to the end of its rendered rows. The first volatile live block
-			// closes the run so its mutable rows stay deferred.
+
+			const blockStart = row + sep;
 			if (i >= liveStartIndex && commitSafeOpen) {
-				if (isBlockAppendOnly(child)) {
-					this.#nativeScrollbackCommitSafeEnd = lines.length + rendered.length;
-				} else {
-					commitSafeOpen = false;
+				const safeLength = finalized ? contribution.length : (liveCommitState?.safeLength ?? 0);
+				if (safeLength > 0) {
+					this.#nativeScrollbackCommitSafeEnd = blockStart + safeLength;
+				}
+				// Durable snapshot end: a commit-stable block's whole body is durable
+				// content — its scrolled-off rows are permanent even while interior
+				// rows re-lay-out (a streaming table re-aligning columns), so the
+				// engine must commit their snapshot on scroll-off rather than drop it.
+				// Finalized blocks are wholly durable; provisional (commit-unstable)
+				// blocks offer nothing beyond their byte-stable safe length.
+				const snapshotLength = finalized || isBlockCommitStable(child) ? contribution.length : safeLength;
+				if (snapshotLength > 0) {
+					this.#nativeScrollbackSnapshotSafeEnd = blockStart + snapshotLength;
 				}
+				// A finalized, fully safe block may let the contiguous safe run extend
+				// into blocks rendered below it. A still-live block keeps pushing lower
+				// rows around as it grows, so the run closes there.
+				if (!(finalized && safeLength >= contribution.length)) commitSafeOpen = false;
 			}
-			// Cache every block's latest render. While a block is in the live region
-			// this keeps its snapshot current; on the frame it crosses out, the
-			// recompute above refreshes it to the final state before it freezes.
-			child[kSnapshot] = { width, lines: rendered, generation: this.#generation };
-			lines.push(...rendered);
+
+			segments[i] = {
+				component: child,
+				rawRef: raw,
+				contribution,
+				width,
+				generation: this.#generation,
+				startRow: row,
+				rowCount,
+				sep,
+				finalized,
+				version,
+			};
+			row += rowCount;
 		}
+		// Trailing shrink: blocks removed from the tail leave stale rows behind
+		// when every surviving segment was reused.
+		if (lines.length !== row) lines.length = row;
+		this.#segments = segments;
+		this.#stableRowsFloor = Math.min(stableFloorBefore, stableRows, row);
 		return lines;
 	}
 }
+
+/**
+ * Groups a run of sibling rows (an IRC card's header + body, a file-mention
+ * list, a bordered command/version panel) into a single transcript child so the
+ * container spaces it as one block — one blank line above, none injected between
+ * its rows. Without this wrapper the rows would be top-level children and the
+ * container would put a blank line between each (and inside any border box).
+ * It is a plain {@link Container}; the named subclass documents intent and makes
+ * every manual block grouping greppable.
+ */
+export class TranscriptBlock extends Container {}