@oh-my-pi/pi-tui 18.2.4 → 18.2.6

package/src/chat/assistant-message.ts

@@ -0,0 +1,1214 @@
+import type { AssistantMessage, ImageContent, TextContent } from "@oh-my-pi/pi-ai";
+import { type Component, Container } from "../tui";
+import { Image, type ImageBudget } from "../components/image";
+import { ImageProtocol, TERMINAL } from "../terminal-capabilities";
+import { Markdown, type MarkdownTheme } from "../components/markdown";
+import { Spacer } from "../components/spacer";
+import { Text } from "../components/text";
+import { formatNumber } from "@oh-my-pi/pi-utils";
+import chalk from "@oh-my-pi/pi-utils/chalk";
+import { LRUCache } from "@oh-my-pi/pi-utils/lru";
+import type { AssistantThinkingRenderer } from "./extension-types";
+import { ensureThemeSync, getMarkdownTheme, theme } from "../theme";
+import { EMPTY_LINK_TARGETS, resolveImageOptions } from "../render/render-utils";
+import { WidthAwareText } from "../render";
+import { convertImageToPng } from "./image-loading";
+import { canonicalizeMessage, formatThinkingForDisplay, hasDisplayableThinking } from "./thinking-display";
+import { resolveAssistantErrorPresentation } from "./transcript-render-helpers";
+import { type CacheInvalidation, CacheInvalidationMarkerComponent } from "./cache-invalidation-marker";
+import { formatErrorBlock } from "../chrome/error-block";
+import { type ServedModelMismatch, ServedModelMarkerComponent } from "./served-model-marker";
+import { isReactionTarget, type ReactionSplit, type ReactionTarget, splitReaction } from "./reaction";
+import { isRowPrefix, type TranscriptStableRow, trimBlankEdges } from "../chrome/transcript-container";
+
+/**
+ * Max wrapped rows of a turn-ending provider error rendered inline in the
+ * transcript. Bounds pathological error bodies — e.g. a proxy 502 whose body
+ * is a full HTML page — so they can't flood the scrollback, while a long
+ * single-line body wraps to the width instead of being cut at a fixed column.
+ * Full text is still kept in the persisted session.
+ */
+const MAX_TRANSCRIPT_ERROR_ROWS = 8;
+const EMPTY_STABLE_RENDER: readonly string[] = [];
+
+type ThinkingContentBlock = Extract<AssistantMessage["content"][number], { type: "thinking" }>;
+type DisplayThinkingContentBlock = ThinkingContentBlock & { rawThinking?: string };
+type StablePart = { kind: "thinking" | "text"; text: string } | { kind: "spacer" };
+
+/**
+ * One published prefix of the block's finished content. Later snapshots extend
+ * earlier ones part-wise (only the final part may grow), so rendered stable
+ * rows only ever gain a suffix — the append-only transcript contract that lets
+ * them retire into native scrollback mid-stream.
+ */
+interface StableSnapshot {
+	// Earlier parts are immutable; only the final part needs a historical offset.
+	readonly partCount: number;
+	readonly lastTextLength: number;
+}
+
+function isSnapshotExtension(previous: readonly StablePart[], current: readonly StablePart[]): boolean {
+	if (previous.length > current.length) return false;
+	for (let index = 0; index < previous.length; index++) {
+		const before = previous[index]!;
+		const after = current[index]!;
+		if (before.kind !== after.kind) return false;
+		if (before.kind === "spacer" || after.kind === "spacer") continue;
+		const isLast = index === previous.length - 1;
+		if (isLast ? !after.text.startsWith(before.text) : after.text !== before.text) return false;
+	}
+	return true;
+}
+
+function resolveThinkingDisplay(block: ThinkingContentBlock, proseOnly: boolean): { text: string; visible: boolean } {
+	const rawThinking = (block as DisplayThinkingContentBlock).rawThinking;
+	// When rawThinking is set, `block.thinking` is already the formatted display
+	// text that buildDisplayMessage produced (then revealed/sliced by the
+	// streaming controller) — re-running the formatter would double-process it,
+	// and the growing revealed slice would never hit the per-tick memo. Only
+	// format raw (non-display) thinking blocks.
+	const formatted = rawThinking !== undefined ? block.thinking : formatThinkingForDisplay(block.thinking, proseOnly);
+	return {
+		text: formatted.trim(),
+		visible: hasDisplayableThinking(rawThinking ?? block.thinking, formatted),
+	};
+}
+
+/**
+ * Frames for the streaming "thinking" pulse rendered in place of a hidden
+ * thinking block while the model is still producing it. A single fixed-width
+ * starburst cycles through facets (✻ ✼ ❉ ❊ ✺ ✹ ✸ ✶) so the indicator animates
+ * in place without shifting the line or the trailing speed badge. The dwell per
+ * frame eases between {@link THINKING_DOTS_FRAME_MS_MIN} and
+ * {@link THINKING_DOTS_FRAME_MS_MAX} across each revolution (see
+ * {@link AssistantMessageComponent.thinkingDotsFrameDelay}).
+ */
+const THINKING_DOTS_FRAMES = ["✻", "✼", "❉", "❊", "✺", "✹", "✸", "✶"] as const;
+/**
+ * Pulse cadence bounds (ms). Each frame's dwell eases between these on a
+ * raised-cosine "breath" — quickest at the cycle start, slowest at its midpoint —
+ * so the starburst accelerates and slows instead of ticking at one fixed rate.
+ * Mean ≈ 150ms, snappier than the previous flat 320ms.
+ */
+const THINKING_DOTS_FRAME_MS_MIN = 70;
+const THINKING_DOTS_FRAME_MS_MAX = 230;
+
+/** Rolling window (ms) over which streaming-rate observations are averaged. */
+const SPEED_WINDOW_MS = 3000;
+/** Color/clamp ceiling: a rate at or above this maps to the full accent color. */
+const SPEED_MAX = 200;
+
+/**
+ * Session-wide streaming-speed gauge. Only one thinking indicator animates at a
+ * time, so a single shared instance accumulates instantaneous tok/s observations
+ * and reports their windowed average — smoothing the jumpy per-delta numbers.
+ * Each thinking block resets the gauge on its first live sample (see
+ * {@link AssistantMessageComponent.updateContent}) so the average reflects only
+ * the active block, never a previous turn's trailing rate. Components feed it
+ * deltas (not cumulative totals), so a fresh turn restarting its token count at
+ * zero never produces a spike.
+ */
+class SpeedTracker {
+	#observations: Array<{ time: number; rate: number }> = [];
+
+	#prune(now: number): void {
+		const threshold = now - SPEED_WINDOW_MS;
+		while (this.#observations.length > 0 && this.#observations[0]!.time < threshold) {
+			this.#observations.shift();
+		}
+	}
+
+	/** Record one instantaneous tok/s reading, clamped to {@link SPEED_MAX} so a
+	 *  single oversized delta (e.g. a buffered reflow tick) can't poison the
+	 *  windowed average. Non-finite/negative rates ignored. */
+	observe(rate: number, now = performance.now()): void {
+		if (!Number.isFinite(rate) || rate < 0) return;
+		this.#observations.push({ time: now, rate: Math.min(rate, SPEED_MAX) });
+		this.#prune(now);
+	}
+
+	/** Windowed-average tok/s; 0 once observations age out of the window. */
+	getSpeed(now = performance.now()): number {
+		this.#prune(now);
+		if (this.#observations.length === 0) return 0;
+		let sum = 0;
+		for (const o of this.#observations) sum += o.rate;
+		return sum / this.#observations.length;
+	}
+
+	reset(): void {
+		this.#observations = [];
+	}
+}
+
+/** One gauge for the whole session — see {@link SpeedTracker}. */
+const sharedSpeedTracker = new SpeedTracker();
+
+/** Test-only: clear the shared gauge so observations don't leak across cases. */
+export function resetThinkingSpeedTracker(): void {
+	sharedSpeedTracker.reset();
+}
+
+/**
+ * Linear-interpolate two `#rrggbb` colors in sRGB space. `t` clamps to [0,1]:
+ * `t = 0` → `from`, `t = 1` → `to`. Drives the streaming speed badge, fading
+ * from a dim gray toward the theme accent as tok/s rises.
+ */
+function lerpHex(from: string, to: string, t: number): string {
+	const k = t < 0 ? 0 : t > 1 ? 1 : t;
+	const fr = Number.parseInt(from.slice(1, 3), 16);
+	const fg = Number.parseInt(from.slice(3, 5), 16);
+	const fb = Number.parseInt(from.slice(5, 7), 16);
+	const tr = Number.parseInt(to.slice(1, 3), 16);
+	const tg = Number.parseInt(to.slice(3, 5), 16);
+	const tb = Number.parseInt(to.slice(5, 7), 16);
+	const r = Math.round(fr + (tr - fr) * k);
+	const g = Math.round(fg + (tg - fg) * k);
+	const b = Math.round(fb + (tb - fb) * k);
+	return `#${((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1)}`;
+}
+
+/**
+ * Renders an assistant message; streaming content remains mutable until the
+ * provider finalizes it because later deltas can revise earlier Markdown.
+ * The exception is the leading run of visible thinking blocks: raw thinking
+ * only ever appends, so its frozen Markdown prefix publishes as append-only
+ * stable rows ({@link AppendOnlyTranscriptBlock}) and can retire into native
+ * scrollback while the block still streams — a long reasoning trace is no
+ * longer clipped to the mutable viewport.
+ */
+export class AssistantMessageComponent extends Container {
+	readonly transcriptBlockMode = "appendOnly" as const;
+	#contentContainer: Container;
+	#markerSlot: Container;
+	#cacheMarker?: CacheInvalidationMarkerComponent;
+	#servedModelMarker?: ServedModelMarkerComponent;
+	#lastMessage?: AssistantMessage;
+	#emergencyText?: Markdown;
+	#toolImagesByCallId = new Map<string, ImageContent[]>();
+	#convertedKittyImages = new Map<string, ImageContent>();
+	#showImages = true;
+	#showToolResultImages = true;
+	#kittyConversionsInFlight = new Set<string>();
+	#transcriptBlockFinalized: boolean;
+	/** See {@link setMidStreamPublication}; the wire's `stream-revision` axis decides it. */
+	#midStreamPublication = true;
+	/**
+	 * When true, the turn-ending `Error: …` line for `stopReason === "error"` is
+	 * suppressed because the same error is currently shown in the pinned banner
+	 * above the editor (see `EventController` + `ErrorBannerComponent`). Avoids
+	 * rendering the identical error twice (inline + banner) at the error moment.
+	 * Restored to `false` when the banner is cleared at the next turn so the
+	 * transcript keeps the error in history.
+	 */
+	#errorPinned = false;
+	/**
+	 * Whether the inline turn-ending error block renders its full body instead of
+	 * the {@link MAX_TRANSCRIPT_ERROR_ROWS}-capped preview. Toggled by
+	 * {@link setExpanded} so Ctrl+O (tool-output expansion) reveals a long
+	 * provider error whose tail would otherwise be unreachable in the live TUI.
+	 */
+	#errorExpanded = false;
+	/**
+	 * True when the current {@link updateContent} message carries a truncatable
+	 * inline provider error (the `#appendErrorBlock` path) — set whether or not
+	 * the inline block was actually drawn, so it stays true even while the error
+	 * is suppressed under a pinned banner. Gates {@link setExpanded} so toggling
+	 * expansion only re-renders assistant turns that carry such an error, not
+	 * every message in the transcript.
+	 */
+	#hasTruncatableError = false;
+	/**
+	 * Monotonic content version reported to the transcript container via
+	 * {@link getTranscriptBlockVersion}. Bumped by {@link updateContent} — the
+	 * choke point every mutator funnels through, including post-finalize changes
+	 * such as `setErrorPinned(false)` restoring the inline error at the next
+	 * turn's `agent_start`, late tool-result images, and async Kitty conversions.
+	 */
+	#blockVersion = 0;
+	/** Whether the last updateContent carried an in-flight streaming partial; such
+	 *  renders bypass the markdown module LRU (see Markdown.transientRenderCache). */
+	#lastUpdateTransient = false;
+	// Fast-path state: reuse Markdown children when message shape is stable during streaming.
+	#fastPathKey: string | undefined;
+	#fastPathItems:
+		| Array<{ md: Markdown; contentIndex: number; blockType: "text" | "thinking"; lastText: string }>
+		| undefined;
+	/** Live "thinking" pulse shown in place of a hidden thinking block while it
+	 *  streams; undefined when not animating. Driven by {@link #thinkingDotsTimer}. */
+	#thinkingDots: Text | undefined;
+	#thinkingDotsTimer: NodeJS.Timeout | undefined;
+	#thinkingDotsFrame = 0;
+	/** Previous cumulative provider token count + timestamp, for deriving this
+	 *  block's instantaneous streaming rate fed into {@link sharedSpeedTracker}.
+	 *  Undefined until the first thinking update of this block. */
+	#lastTokenCount: number | undefined;
+	#lastTokenTime = 0;
+	/** Published width-independent stable prefixes; grows only, never retracts. */
+	#stableSnapshots: StableSnapshot[] = [];
+	#stableParts: readonly StablePart[] = [];
+	#nextStableRowId = 0;
+	#transcriptStableRows: TranscriptStableRow[] = [];
+	/**
+	 * Rendered rows per published snapshot index and width. The container asks
+	 * for several different counts in one frame (emitted, offered end,
+	 * projected, pressure-loop +1s); a 2-entry LRU thrashes across those and
+	 * re-renders the whole prefix per miss. Sized generously so the live prefix
+	 * stays cached; cleared on reset/finalize like before.
+	 */
+	#stableRenderCache = new LRUCache<string, readonly string[]>({ max: 64 });
+	/** Provider-reported tokens in the live thinking block — reasoning tokens when
+	 *  the provider streams them, else total output — shown dimmed beside the
+	 *  speed badge. 0 when no thinking is streaming. */
+	#thinkingTokens = 0;
+	/** Whether this block has observed a positive provider-token delta — i.e. it is
+	 *  genuinely streaming tokens right now. Gates the numeric speed badge so the
+	 *  session-wide {@link sharedSpeedTracker} can't surface a previous turn's rate
+	 *  on a fresh block that has no live token throughput of its own. */
+	#thinkingRateLive = false;
+
+	#textColorTransform?: (text: string) => string;
+	#linkTargets: ReadonlyMap<string, string> = EMPTY_LINK_TARGETS;
+	#markdownTheme: MarkdownTheme | undefined;
+	/** Block this reply reacts to; undefined when the preceding block takes no reactions. */
+	#reactionTarget: ReactionTarget | undefined;
+	/** Reaction lifted from the reply's opening emoji, once resolved. */
+	#reaction: string | undefined;
+
+	setTextColorTransform(transform?: (text: string) => string): void {
+		this.#textColorTransform = transform;
+	}
+
+	#getProseTheme(): MarkdownTheme {
+		if (this.#markdownTheme) return this.#markdownTheme;
+		const base = getMarkdownTheme();
+		const snapshot = this.#linkTargets;
+		const markdownTheme = snapshot.size > 0 ? { ...base, resolveLink: (href: string) => snapshot.get(href) } : base;
+		this.#markdownTheme = markdownTheme;
+		return markdownTheme;
+	}
+
+	/**
+	 * Install resolved destinations for model-authored prose links. A fresh
+	 * theme object is required whenever the map changes because Markdown's
+	 * render cache keys themes by object identity.
+	 */
+	setLinkTargets(targets: ReadonlyMap<string, string>): void {
+		if (
+			targets === this.#linkTargets ||
+			(targets.size === this.#linkTargets.size &&
+				[...targets].every(([href, target]) => this.#linkTargets.get(href) === target))
+		) {
+			return;
+		}
+		this.#linkTargets = targets;
+		this.#markdownTheme = undefined;
+		this.#fastPathKey = undefined;
+		this.#fastPathItems = undefined;
+		if (this.#lastMessage) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	/**
+	 * Choose the block this reply reacts to from the transcript it is about to
+	 * join: the nearest preceding reaction-capable block (the user's bubble),
+	 * looking past turn attachments such as file mentions or injected notices
+	 * but never past an earlier reply — a continuation after tool calls has
+	 * nothing to react to. Call before adding this component. An
+	 * already-resolved reaction is re-applied, and a message rendered verbatim
+	 * for lack of a target is re-rendered with its reaction stripped.
+	 */
+	pickReactionTarget(transcript: readonly Component[]): void {
+		this.#reactionTarget = undefined;
+		for (let index = transcript.length - 1; index >= 0; index--) {
+			const block = transcript[index]!;
+			if (isReactionTarget(block)) {
+				this.#reactionTarget = block;
+				break;
+			}
+			if (block instanceof AssistantMessageComponent) break;
+		}
+		if (this.#reaction !== undefined) this.#reactionTarget?.setReaction(this.#reaction);
+		if (this.#lastMessage && this.#openingText(this.#lastMessage)?.split.emoji !== undefined) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	/** The reply's first non-empty text block with its reaction split, if any. */
+	#openingText(message: AssistantMessage): { index: number; block: TextContent; split: ReactionSplit } | undefined {
+		const index = message.content.findIndex(content => content.type === "text" && content.text.length > 0);
+		const block = message.content[index];
+		if (block?.type !== "text") return undefined;
+		return { index, block, split: splitReaction(block.text) };
+	}
+
+	/**
+	 * Display form of `message` with the reaction handled: stripped and
+	 * forwarded to the target once resolved, withheld entirely while a streaming
+	 * prefix could still become one, and left verbatim when there is no target.
+	 */
+	#displayMessage(message: AssistantMessage, transient: boolean): AssistantMessage {
+		const opening = this.#openingText(message);
+		if (!opening) return message;
+		const { index, block, split } = opening;
+		let text: string;
+		if (split.emoji !== undefined) {
+			if (this.#reaction !== split.emoji) {
+				this.#reaction = split.emoji;
+				this.#reactionTarget?.setReaction(split.emoji);
+			}
+			if (!this.#reactionTarget) return message;
+			text = split.body;
+		} else if (split.pending && transient) {
+			text = "";
+		} else {
+			return message;
+		}
+		const content = message.content.slice();
+		content[index] = { ...block, text };
+		return { ...message, content };
+	}
+	#hideThinkingBlock: boolean;
+	readonly #onImageUpdate?: () => void;
+	readonly #thinkingRenderers: readonly AssistantThinkingRenderer[];
+	readonly #imageBudget?: ImageBudget;
+	#proseOnlyThinking: boolean;
+
+	constructor(
+		message?: AssistantMessage,
+		hideThinkingBlock = false,
+		onImageUpdate?: () => void,
+		thinkingRenderers: readonly AssistantThinkingRenderer[] = [],
+		imageBudget?: ImageBudget,
+		proseOnlyThinking = true,
+		linkTargets?: ReadonlyMap<string, string>,
+	) {
+		super();
+		this.#hideThinkingBlock = hideThinkingBlock;
+		this.#onImageUpdate = onImageUpdate;
+		this.#thinkingRenderers = thinkingRenderers;
+		this.#imageBudget = imageBudget;
+		this.#proseOnlyThinking = proseOnlyThinking;
+
+		ensureThemeSync();
+		this.#transcriptBlockFinalized = message !== undefined;
+		if (linkTargets?.size) this.#linkTargets = linkTargets;
+
+		// Container for text/thinking content.
+		this.#contentContainer = new Container();
+		this.addChild(this.#contentContainer);
+
+		// Cache-miss usage arrives only at message end. Keep its divider after
+		// streamed content so rows already emitted to native history remain a
+		// prefix of this append-only block.
+		this.#markerSlot = new Container();
+		this.addChild(this.#markerSlot);
+
+		if (message) {
+			this.updateContent(message);
+		}
+	}
+
+	/**
+	 * Show or clear the trailing cache-invalidation divider. Set at `message_end`
+	 * (live) or during rebuild, once the turn's usage is known and compared
+	 * against the previous turn's cache footprint.
+	 */
+	setCacheInvalidation(info: CacheInvalidation | undefined): void {
+		this.#cacheMarker = info ? new CacheInvalidationMarkerComponent(info) : undefined;
+		this.#refreshMarkers();
+	}
+
+	/**
+	 * Show or clear the trailing served-model divider. Set once the turn's
+	 * signed thinking block (or router report) has named the model that actually
+	 * answered, when it differs from the one requested.
+	 */
+	setServedModelMismatch(info: ServedModelMismatch | undefined): void {
+		this.#servedModelMarker = info ? new ServedModelMarkerComponent(info) : undefined;
+		this.#refreshMarkers();
+	}
+
+	#refreshMarkers(): void {
+		this.#markerSlot.clear();
+		if (this.#servedModelMarker) this.#markerSlot.addChild(this.#servedModelMarker);
+		if (this.#cacheMarker) this.#markerSlot.addChild(this.#cacheMarker);
+		this.#blockVersion++;
+	}
+
+	override invalidate(): void {
+		super.invalidate();
+		// Theme/symbol changes arrive via invalidate(). Fast-path children captured
+		// their theme at construction, so drop them and force the teardown path to
+		// rebuild with the current theme. Streaming updates call updateContent()
+		// directly and keep the fast path.
+		this.#markdownTheme = undefined;
+		this.#fastPathKey = undefined;
+		this.#fastPathItems = undefined;
+		if (this.#lastMessage) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	setHideThinkingBlock(hide: boolean): void {
+		this.#hideThinkingBlock = hide;
+	}
+
+	/**
+	 * Allow or withhold retiring finished lines into native scrollback while the
+	 * turn is still streaming. Wires the `stream-revision` axis marks as able to
+	 * revise already-streamed text must withhold it: published bytes go to
+	 * terminal history once and cannot be retracted, so a later revision would
+	 * leave the reader with a stale copy. Withholding costs only reachability —
+	 * the block still retires whole when the turn ends.
+	 */
+	setMidStreamPublication(allowed: boolean): void {
+		this.#midStreamPublication = allowed;
+	}
+
+	setProseOnlyThinking(proseOnly: boolean): void {
+		this.#proseOnlyThinking = proseOnly;
+	}
+
+	override dispose(): void {
+		this.#stopThinkingAnimation();
+		super.dispose();
+	}
+
+	/**
+	 * Whether to render the animated "thinking" pulse in place of the suppressed
+	 * reasoning: only while this block is still streaming (not yet finalized — the
+	 * in-flight message always carries `stopReason: "stop"`, so finalization is the
+	 * only reliable live signal), thinking is hidden, no tool call has started, and
+	 * the active tail block is a thinking block (the model is reasoning right now).
+	 * Once text starts, a tool call streams, or the block is sealed, the pulse ends.
+	 */
+	#shouldAnimateThinking(message: AssistantMessage): boolean {
+		if (!this.#hideThinkingBlock || this.#transcriptBlockFinalized) return false;
+		let tail: "text" | "thinking" | undefined;
+		for (const content of message.content) {
+			if (content.type === "toolCall") return false;
+			if (content.type === "text" && canonicalizeMessage(content.text)) tail = "text";
+			else if (content.type === "thinking" && canonicalizeMessage(content.thinking)) tail = "thinking";
+		}
+		return tail === "thinking";
+	}
+
+	#thinkingDotsLabel(): string {
+		const glyph = THINKING_DOTS_FRAMES[this.#thinkingDotsFrame % THINKING_DOTS_FRAMES.length] ?? "…";
+		const coloredGlyph = theme.fg("thinkingText", glyph);
+		const thinkingLabel = theme.fg("muted", " Thinking");
+		const rate = Math.min(SPEED_MAX, sharedSpeedTracker.getSpeed());
+		// The numeric badge ("<total> · <rate> toks/s") only renders while this block
+		// is genuinely streaming provider tokens. A block that has observed no token
+		// delta (e.g. a provider that reports usage only at turn end) or whose rate
+		// has decayed to zero (a streaming lull) drops it entirely — the persistent
+		// text label keeps the pulse descriptive for terminals and screen readers.
+		// The liveness flag also stops the session-wide gauge from leaking a previous
+		// turn's rate onto a fresh token-less block.
+		if (!this.#thinkingRateLive || rate < 0.05) return coloredGlyph + thinkingLabel;
+		// Total provider tokens, dimmed, sit next to the pulse.
+		const totalSpan = this.#thinkingTokens > 0 ? theme.fg("dim", ` · ${formatNumber(this.#thinkingTokens)}`) : "";
+		// Speed badge color: dim gray at rest, brightening toward the theme accent as
+		// streaming speed climbs (gray → bright accent). Ease (sqrt) so typical
+		// mid-stream rates already read as clearly accent-tinted instead of staying
+		// gray until the rarely-hit SPEED_MAX ceiling.
+		const ratio = Math.sqrt(rate / SPEED_MAX);
+		const hex = lerpHex(theme.getColorHex("dim"), theme.getAccentColorHex(), ratio);
+		const rateText = ` · ${rate.toFixed(1)} toks/s`;
+		const rateSpan = theme.getColorMode() === "truecolor" ? chalk.hex(hex)(rateText) : theme.fg("muted", rateText);
+		return coloredGlyph + thinkingLabel + totalSpan + rateSpan;
+	}
+
+	#startThinkingAnimation(): void {
+		if (this.#thinkingDotsTimer) return;
+		this.#scheduleThinkingFrame();
+	}
+
+	/** Eased dwell (ms) for the current pulse frame: a raised cosine over the
+	 *  8-frame cycle, continuous across the wrap, so the rotation breathes rather
+	 *  than advancing at a fixed interval. */
+	#thinkingDotsFrameDelay(): number {
+		const phase = (1 - Math.cos((2 * Math.PI * this.#thinkingDotsFrame) / THINKING_DOTS_FRAMES.length)) / 2;
+		return THINKING_DOTS_FRAME_MS_MIN + (THINKING_DOTS_FRAME_MS_MAX - THINKING_DOTS_FRAME_MS_MIN) * phase;
+	}
+
+	/** Self-rescheduling timeout (not a fixed interval) so each frame can pick its
+	 *  own eased dwell. */
+	#scheduleThinkingFrame(): void {
+		this.#thinkingDotsTimer = setTimeout(() => this.#advanceThinkingDots(), this.#thinkingDotsFrameDelay());
+		this.#thinkingDotsTimer.unref?.();
+	}
+
+	#advanceThinkingDots(): void {
+		this.#thinkingDotsTimer = undefined;
+		if (!this.#thinkingDots) {
+			this.#stopThinkingAnimation();
+			return;
+		}
+		this.#thinkingDotsFrame = (this.#thinkingDotsFrame + 1) % THINKING_DOTS_FRAMES.length;
+		if (this.#thinkingDots.setText(this.#thinkingDotsLabel())) {
+			this.#onImageUpdate?.();
+		}
+		this.#scheduleThinkingFrame();
+	}
+
+	#stopThinkingAnimation(): void {
+		if (this.#thinkingDotsTimer) {
+			clearTimeout(this.#thinkingDotsTimer);
+			this.#thinkingDotsTimer = undefined;
+		}
+		this.#thinkingDotsFrame = 0;
+	}
+
+	/**
+	 * Toggle suppression of the inline `Error: …` line while the same error is
+	 * pinned in the banner above the editor. Re-renders so the change is visible.
+	 */
+	setErrorPinned(pinned: boolean): void {
+		if (this.#errorPinned === pinned) return;
+		this.#errorPinned = pinned;
+		if (this.#lastMessage) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	/**
+	 * Expand or collapse the inline turn-ending error block so Ctrl+O
+	 * (tool-output expansion) can reveal a long provider error's hidden tail.
+	 * Only re-renders when the current message carries a truncatable error, so
+	 * toggling expansion across the transcript skips ordinary turns. Works even
+	 * while the error is pinned in the banner: the inline block is drawn (in full)
+	 * when expanded so the complete body is reachable without sending a message.
+	 */
+	setExpanded(expanded: boolean): void {
+		if (this.#errorExpanded === expanded) return;
+		this.#errorExpanded = expanded;
+		if (this.#hasTruncatableError && this.#lastMessage) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	isTranscriptBlockFinalized(): boolean {
+		return this.#transcriptBlockFinalized;
+	}
+
+	override render(width: number): readonly string[] {
+		const rows = super.render(width);
+		this.#publishStableSnapshot(rows, width);
+		return rows;
+	}
+
+	/** Width-independent stable identities for the streamed leading thinking run. */
+	getTranscriptStableRows(): readonly TranscriptStableRow[] {
+		return this.#transcriptStableRows;
+	}
+
+	/**
+	 * Drop every published thinking stable row. Called by the transcript
+	 * container during a visibility-driven destructive replay so the head no
+	 * longer re-emits reasoning captured while thinking was visible. Safe only
+	 * because the paired display reset clears the scrollback those rows occupied
+	 * — see {@link AppendOnlyTranscriptBlock.resetTranscriptStableRows}.
+	 */
+	resetTranscriptStableRows(): void {
+		this.#stableSnapshots = [];
+		this.#stableParts = [];
+		this.#transcriptStableRows = [];
+		this.#stableRenderCache.clear();
+	}
+
+	renderTranscriptStableRows(count: number, width: number): readonly string[] {
+		const index = Math.min(Math.trunc(count), this.#stableSnapshots.length);
+		if (index <= 0) return EMPTY_STABLE_RENDER;
+		const key = `${index}:${width}`;
+		const cached = this.#stableRenderCache.get(key);
+		if (cached) return cached;
+		const snapshot = this.#stableSnapshots[index - 1]!;
+		const parts = this.#stableParts.slice(0, snapshot.partCount);
+		const last = parts.at(-1);
+		if (last && last.kind !== "spacer") {
+			parts[parts.length - 1] = { kind: last.kind, text: last.text.slice(0, snapshot.lastTextLength) };
+		}
+		const rows = this.#renderStableSnapshot(parts, width);
+		this.#stableRenderCache.set(key, rows);
+		return rows;
+	}
+
+	/**
+	 * Publish the block's finished prefix as stable transcript rows so a long
+	 * stream can retire into native scrollback mid-turn instead of being clipped
+	 * to the live viewport until the turn ends. Finished means bytes that can no
+	 * longer change: closed child blocks, plus the streaming child's frozen
+	 * Markdown prefix. Published bytes may already sit in terminal history, so
+	 * every guard skips publication and nothing ever retracts it.
+	 */
+	#publishStableSnapshot(rendered: readonly string[], width: number): void {
+		if (!this.#midStreamPublication) return;
+		const parts = this.#currentStableSnapshot();
+		if (!parts) return;
+		const last = parts.at(-1);
+		if (!last || last.kind === "spacer") return;
+		const snapshot = { partCount: parts.length, lastTextLength: last.text.length };
+		const previous = this.#stableSnapshots.at(-1);
+		if (previous && !isSnapshotExtension(this.#stableParts, parts)) return;
+		if (previous?.partCount === snapshot.partCount && previous.lastTextLength === snapshot.lastTextLength) return;
+		const currentRows = this.#renderStableSnapshot(parts, width);
+		// The container verifies stable rows against the blank-trimmed render.
+		if (!isRowPrefix(currentRows, trimBlankEdges(rendered))) return;
+		const previousRows = previous
+			? this.renderTranscriptStableRows(this.#stableSnapshots.length, width)
+			: EMPTY_STABLE_RENDER;
+		if (!isRowPrefix(previousRows, currentRows)) return;
+		// Each stable row must add at least one physical row at every width.
+		if (currentRows.length === previousRows.length) return;
+		this.#stableParts = parts;
+		this.#stableSnapshots.push(snapshot);
+		this.#transcriptStableRows.push({ key: `thinking:${this.#nextStableRowId++}` });
+		this.#stableRenderCache.set(`${this.#stableSnapshots.length}:${width}`, currentRows);
+	}
+
+	/**
+	 * Width-independent parts eligible for publication right now: the leading
+	 * run of finished blocks, ending inside the streaming block at Markdown's
+	 * frozen boundary. Undefined whenever any prefix byte could still change
+	 * (finalized or non-transient renders, marker rows, extension components,
+	 * hidden thinking, or no frozen prefix yet).
+	 */
+	#currentStableSnapshot(): readonly StablePart[] | undefined {
+		if (this.#transcriptBlockFinalized || !this.#lastUpdateTransient) return undefined;
+		if (this.#markerSlot.children.length > 0) return undefined;
+		const items = this.#fastPathItems;
+		if (!items || items.length === 0) return undefined;
+		const parts: StablePart[] = [];
+		let itemIndex = 0;
+		for (const child of this.#contentContainer.children) {
+			const item = items[itemIndex];
+			if (item?.md === child) {
+				if (itemIndex === items.length - 1) {
+					// Streaming child: publish Markdown's frozen prefix, and only
+					// once non-blank content exists past it — the block's last
+					// non-blank line is still being written (thinking's prose fold
+					// may rewrite it) and must stay out of published bytes.
+					const raw = item.md.getLastRenderStableText();
+					const frozen = raw.trim();
+					if (frozen.length > 0 && /\S/.test(item.lastText.slice(raw.length))) {
+						parts.push({ kind: item.blockType, text: frozen });
+					}
+					break;
+				}
+				// Closed child: only the streaming tail may mutate in place, so
+				// everything before it is final.
+				parts.push({ kind: item.blockType, text: item.lastText });
+				itemIndex++;
+				continue;
+			}
+			if (child instanceof Spacer) {
+				parts.push({ kind: "spacer" });
+				continue;
+			}
+			// Unknown child (thinking extension, pulse, image, error row): stop.
+			break;
+		}
+		while (parts.at(-1)?.kind === "spacer") parts.pop();
+		if (parts.length === 0) return undefined;
+		return parts;
+	}
+
+	#renderStableSnapshot(parts: readonly StablePart[], width: number): readonly string[] {
+		const rows: string[] = [];
+		for (const part of parts) {
+			if (part.kind === "spacer") {
+				rows.push("");
+				continue;
+			}
+			// Constructor args mirror the live child Markdown exactly so these
+			// rows are byte-identical to the block render's prefix — including the
+			// trim the live children apply, which drops the trailing blank line a
+			// frozen prefix still carries.
+			const text = part.text.trim();
+			const markdown =
+				part.kind === "text"
+					? new Markdown(
+							text,
+							1,
+							0,
+							this.#getProseTheme(),
+							this.#textColorTransform ? { color: this.#textColorTransform } : undefined,
+							0,
+						)
+					: new Markdown(text, 1, 0, getMarkdownTheme(), {
+							color: (value: string) => theme.fg("thinkingText", value),
+							italic: true,
+						});
+			rows.push(...markdown.render(width));
+		}
+		return rows;
+	}
+
+	/** Render completed prose rather than an earlier thinking row under emergency viewport pressure. */
+	renderTranscriptBlockEmergencyRow(width: number): string | undefined {
+		if (!this.#transcriptBlockFinalized) return undefined;
+		return this.#emergencyText?.render(width)[0];
+	}
+
+	getTranscriptBlockVersion(): number {
+		return this.#blockVersion;
+	}
+
+	markTranscriptBlockFinalized(): void {
+		this.#transcriptBlockFinalized = true;
+		this.#stableRenderCache.clear();
+		this.#stopThinkingAnimation();
+		// If the live pulse was on screen when the block sealed, drop the fast path
+		// and rebuild so the placeholder is removed — finalized blocks never animate.
+		if (this.#thinkingDots) {
+			this.#fastPathKey = undefined;
+			this.#fastPathItems = undefined;
+			if (this.#lastMessage) this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	applyRetryRecovery(retryRecovery: AssistantMessage["retryRecovery"]): void {
+		if (!this.#lastMessage || !retryRecovery) return;
+		this.setErrorPinned(false);
+		this.updateContent({ ...this.#lastMessage, retryRecovery });
+	}
+
+	messagePersistenceKey(): string | undefined {
+		if (!this.#lastMessage) return undefined;
+		return [
+			"assistant",
+			this.#lastMessage.timestamp,
+			this.#lastMessage.provider,
+			this.#lastMessage.model,
+			this.#lastMessage.responseId ?? "",
+			this.#lastMessage.stopReason,
+		].join(":");
+	}
+
+	/**
+	 * Render a turn-ending provider error inline, wrapped to the render width.
+	 * Collapsed (default), the block keeps {@link MAX_TRANSCRIPT_ERROR_ROWS}
+	 * wrapped rows and ends with a dim `ctrl+o`/expand hint when rows were cut,
+	 * so a pathological body — e.g. the HTML page a proxy returns on a 502 —
+	 * can't flood the transcript. Expanded (via {@link setExpanded}), every row
+	 * is rendered so the complete message is reachable. Mirrors
+	 * {@link ErrorBannerComponent}. The caller owns the separating Spacer.
+	 */
+	#appendErrorBlock(message: string): void {
+		const maxRows = this.#errorExpanded ? Number.POSITIVE_INFINITY : MAX_TRANSCRIPT_ERROR_ROWS;
+		this.#contentContainer.addChild(
+			new WidthAwareText(
+				contentWidth =>
+					formatErrorBlock(message, contentWidth, maxRows, (line, index) =>
+						theme.fg("error", index === 0 ? `Error: ${line}` : line),
+					),
+				1,
+				0,
+			),
+		);
+	}
+
+	/** Toggle rendering for assistant-native and tool-result images. */
+	setImagesVisible(visible: boolean): void {
+		if (this.#showImages === visible) return;
+		this.#showImages = visible;
+		if (this.#lastMessage) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	/** Toggle only images produced by tool results; assistant-native images remain governed by setImagesVisible. */
+	setToolResultImagesVisible(visible: boolean): void {
+		if (this.#showToolResultImages === visible) return;
+		this.#showToolResultImages = visible;
+		if (this.#lastMessage) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	setToolResultImages(toolCallId: string, images: ImageContent[]): void {
+		if (!toolCallId) return;
+		const validImages = images.filter(img => img.type === "image" && img.data && img.mimeType);
+		for (const key of Array.from(this.#convertedKittyImages.keys())) {
+			if (key.startsWith(`${toolCallId}:`)) {
+				this.#convertedKittyImages.delete(key);
+			}
+		}
+		for (const key of Array.from(this.#kittyConversionsInFlight)) {
+			if (key.startsWith(`${toolCallId}:`)) {
+				this.#kittyConversionsInFlight.delete(key);
+			}
+		}
+		if (validImages.length === 0) {
+			this.#toolImagesByCallId.delete(toolCallId);
+		} else {
+			this.#toolImagesByCallId.set(toolCallId, validImages);
+			this.#convertImagesForKitty(validImages.map((image, index) => ({ image, key: `${toolCallId}:${index}` })));
+		}
+		if (this.#lastMessage) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	#convertImagesForKitty(entries: Array<{ image: ImageContent; key: string }>): void {
+		if (TERMINAL.imageProtocol !== ImageProtocol.Kitty) return;
+		for (const { image, key } of entries) {
+			if (image.mimeType === "image/png") continue;
+			if (this.#convertedKittyImages.has(key) || this.#kittyConversionsInFlight.has(key)) continue;
+			this.#kittyConversionsInFlight.add(key);
+			convertImageToPng(image)
+				.then(converted => {
+					this.#kittyConversionsInFlight.delete(key);
+					this.#convertedKittyImages.set(key, converted);
+					if (this.#lastMessage) {
+						this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+					}
+					this.#onImageUpdate?.();
+				})
+				.catch(() => {
+					this.#kittyConversionsInFlight.delete(key);
+				});
+		}
+	}
+
+	#renderImageEntries(entries: Array<{ image: ImageContent; key: string }>, withLeadingSpacer: boolean): void {
+		if (!this.#showImages || entries.length === 0) return;
+		this.#convertImagesForKitty(entries);
+
+		if (withLeadingSpacer) this.#contentContainer.addChild(new Spacer(1));
+		for (const { image, key } of entries) {
+			const displayImage =
+				TERMINAL.imageProtocol === ImageProtocol.Kitty && image.mimeType !== "image/png"
+					? this.#convertedKittyImages.get(key)
+					: image;
+			if (TERMINAL.imageProtocol && displayImage) {
+				this.#contentContainer.addChild(
+					new Image(
+						displayImage.data,
+						displayImage.mimeType,
+						{ fallbackColor: (text: string) => theme.fg("toolOutput", text) },
+						{ ...resolveImageOptions(), budget: this.#imageBudget, imageKey: key },
+					),
+				);
+				continue;
+			}
+			this.#contentContainer.addChild(new Text(theme.fg("toolOutput", `[Image: ${image.mimeType}]`), 1, 0));
+		}
+	}
+
+	#renderToolImages(): void {
+		if (!this.#showToolResultImages) return;
+		const entries = Array.from(this.#toolImagesByCallId.entries()).flatMap(([toolCallId, images]) =>
+			images.map((image, index) => ({ image, key: `${toolCallId}:${index}` })),
+		);
+		this.#renderImageEntries(entries, true);
+	}
+
+	#appendThinkingExtensions(contentIndex: number, thinkingIndex: number, text: string): void {
+		for (const renderer of this.#thinkingRenderers) {
+			try {
+				const component = renderer(
+					{
+						contentIndex,
+						thinkingIndex,
+						text,
+						requestRender: () => this.#onImageUpdate?.(),
+					},
+					theme,
+				);
+				if (component) {
+					this.#contentContainer.addChild(component);
+				}
+			} catch {
+				// Ignore extension renderer failures and keep the original thinking block visible.
+			}
+		}
+	}
+
+	#computeShapeKey(message: AssistantMessage): string {
+		const parts: string[] = [`htb:${this.#hideThinkingBlock ? 1 : 0}|pot:${this.#proseOnlyThinking ? 1 : 0}`];
+		for (const content of message.content) {
+			if (content.type === "text") {
+				parts.push(canonicalizeMessage(content.text) ? "T1" : "T0");
+			} else if (content.type === "thinking") {
+				if (this.#hideThinkingBlock) {
+					// Match the pulse's empty/nonempty transition without formatting hidden text.
+					parts.push(canonicalizeMessage(content.thinking) ? "KH" : "K0");
+				} else {
+					parts.push(resolveThinkingDisplay(content, this.#proseOnlyThinking).visible ? "KV" : "K0");
+				}
+			} else {
+				// Non-rendered blocks (toolCall, redactedThinking, …) still occupy a
+				// content index. Encode their position so an inserted/removed one shifts
+				// the key and forces the teardown path instead of mis-indexing children.
+				parts.push(`O:${content.type}`);
+			}
+		}
+		return parts.join("|");
+	}
+
+	#canFastPath(message: AssistantMessage): boolean {
+		for (const content of message.content) {
+			if (content.type === "toolCall" || content.type === "image") return false;
+		}
+		if (this.#toolImagesByCallId.size > 0) return false;
+		const errorPresentation = resolveAssistantErrorPresentation(message);
+		if (errorPresentation.kind === "compact-recovered") return false;
+		if (
+			errorPresentation.kind === "full" &&
+			!(message.stopReason === "error" && this.#errorPinned && !this.#errorExpanded)
+		) {
+			return false;
+		}
+		// Extension stability: if thinking renderers exist and any tracked thinking
+		// block's text changed, extensions may produce a different child count.
+		if (!this.#hideThinkingBlock && this.#thinkingRenderers.length > 0 && this.#fastPathItems) {
+			for (const item of this.#fastPathItems) {
+				if (item.blockType === "thinking") {
+					const content = message.content[item.contentIndex];
+					if (content?.type === "thinking") {
+						const display = resolveThinkingDisplay(content, this.#proseOnlyThinking);
+						if (display.text !== item.lastText) return false;
+					}
+				}
+			}
+		}
+		return true;
+	}
+
+	#tryFastPathUpdate(message: AssistantMessage, opts?: { transient?: boolean }): boolean {
+		if (!this.#fastPathKey || !this.#fastPathItems) return false;
+		if (!this.#canFastPath(message)) {
+			this.#fastPathKey = undefined;
+			this.#fastPathItems = undefined;
+			return false;
+		}
+		if (this.#computeShapeKey(message) !== this.#fastPathKey) {
+			this.#fastPathKey = undefined;
+			this.#fastPathItems = undefined;
+			return false;
+		}
+		const transient = opts?.transient === true;
+		// Shape is identical — setText only on Markdown children whose source changed.
+		this.#applyItemTransience(transient);
+		for (let i = 0; i < this.#fastPathItems.length; i++) {
+			const item = this.#fastPathItems[i]!;
+			const content = message.content[item.contentIndex];
+			if (!content) {
+				this.#fastPathKey = undefined;
+				this.#fastPathItems = undefined;
+				return false;
+			}
+			let newText: string;
+			if (item.blockType === "text" && content.type === "text") {
+				newText = content.text.trim();
+			} else if (item.blockType === "thinking" && content.type === "thinking") {
+				newText = resolveThinkingDisplay(content, this.#proseOnlyThinking).text;
+			} else {
+				this.#fastPathKey = undefined;
+				this.#fastPathItems = undefined;
+				return false;
+			}
+			if (newText !== item.lastText) {
+				// Only the last (actively streaming) block may mutate in place: a
+				// delta into an earlier block would invalidate rows the settled
+				// walk already declared final, so tear down and rebuild instead.
+				if (i < this.#fastPathItems.length - 1) {
+					this.#fastPathKey = undefined;
+					this.#fastPathItems = undefined;
+					return false;
+				}
+				item.md.setText(newText);
+				item.lastText = newText;
+			}
+		}
+		if (this.#thinkingDots) {
+			if (this.#thinkingDots.setText(this.#thinkingDotsLabel())) {
+				this.#onImageUpdate?.();
+			}
+		}
+		return true;
+	}
+
+	updateContent(message: AssistantMessage, opts?: { transient?: boolean }): void {
+		this.#blockVersion++;
+		this.#lastMessage = message;
+		this.#lastUpdateTransient = opts?.transient === true;
+		// Everything below renders the display form; #lastMessage keeps the
+		// verbatim message so re-renders re-derive the reaction deterministically.
+		message = this.#displayMessage(message, this.#lastUpdateTransient);
+
+		// Streaming-speed gauge: only a live, in-flight render of the single
+		// animating hidden-thinking block feeds the shared session tracker. The
+		// token count is the provider's own cumulative output — reasoning tokens when
+		// reported (Gemini's thoughtsTokenCount, OpenAI's reasoning_tokens), else
+		// total output tokens — never a character estimate, which undercounts when
+		// the provider streams a summarized reasoning trace. An instantaneous tok/s
+		// is derived from this block's delta and handed to the windowed averager.
+		// Only transient renders count: the final non-transient render at
+		// message_end carries the turn's end-of-stream usage, whose jump would spike
+		// the gauge and pollute the next block. Providers that report usage only at
+		// turn end leave the live count flat, so the rate stays 0 and the badge
+		// self-suppresses (see #thinkingDotsLabel).
+		const isThinkingNow = this.#lastUpdateTransient && this.#shouldAnimateThinking(message);
+		if (isThinkingNow) {
+			const currentTokens = message.usage.reasoningTokens ?? message.usage.output;
+			this.#thinkingTokens = currentTokens;
+			const now = performance.now();
+			if (this.#lastTokenCount !== undefined) {
+				const tokenDelta = currentTokens - this.#lastTokenCount;
+				const elapsedMs = now - this.#lastTokenTime;
+				if (tokenDelta > 0 && elapsedMs > 0) {
+					// First live sample of this block: drop the session gauge's prior-turn
+					// observations so the windowed average reflects only this block.
+					if (!this.#thinkingRateLive) sharedSpeedTracker.reset();
+					sharedSpeedTracker.observe((tokenDelta / elapsedMs) * 1000, now);
+					this.#thinkingRateLive = true;
+				}
+			}
+			this.#lastTokenCount = currentTokens;
+			this.#lastTokenTime = now;
+		} else {
+			this.#lastTokenCount = undefined;
+			this.#thinkingTokens = 0;
+			this.#thinkingRateLive = false;
+		}
+
+		// Fast path: reuse Markdown children when shape is stable during streaming
+		if (this.#tryFastPathUpdate(message, opts)) return;
+
+		// Clear content container
+		this.#contentContainer.clear();
+		this.#emergencyText = undefined;
+		this.#thinkingDots = undefined;
+		this.#hasTruncatableError = false;
+
+		// Determine if we should capture Markdown instances for next fast path
+		const shouldCapture = this.#canFastPath(message);
+		const captureItems:
+			| Array<{ md: Markdown; contentIndex: number; blockType: "text" | "thinking"; lastText: string }>
+			| undefined = shouldCapture ? [] : undefined;
+
+		const hasVisibleContent = message.content.some(
+			c =>
+				(c.type === "text" && canonicalizeMessage(c.text)) ||
+				(c.type === "image" && c.data && c.mimeType) ||
+				(!this.#hideThinkingBlock &&
+					c.type === "thinking" &&
+					resolveThinkingDisplay(c, this.#proseOnlyThinking).visible),
+		);
+
+		// Render content in order
+		let thinkingIndex = 0;
+		let hasRenderedContent = false;
+		for (let i = 0; i < message.content.length; i++) {
+			const content = message.content[i];
+			if (content.type === "text" && canonicalizeMessage(content.text)) {
+				// Set paddingY=0 to avoid extra spacing before tool executions
+				const trimmed = content.text.trim();
+				const mdOptions = this.#textColorTransform ? { color: this.#textColorTransform } : undefined;
+				const md = new Markdown(trimmed, 1, 0, this.#getProseTheme(), mdOptions, 0);
+				this.#contentContainer.addChild(md);
+				this.#emergencyText = md;
+				captureItems?.push({ md, contentIndex: i, blockType: "text", lastText: trimmed });
+				hasRenderedContent = true;
+			} else if (content.type === "thinking") {
+				if (this.#hideThinkingBlock) {
+					thinkingIndex += 1;
+					continue;
+				}
+				const display = resolveThinkingDisplay(content, this.#proseOnlyThinking);
+				if (!display.visible) continue;
+				const thinkingText = display.text;
+				// Add spacing only when another visible assistant content block follows.
+				// This avoids a superfluous blank line before separately-rendered tool execution blocks.
+				const hasVisibleContentAfter = message.content
+					.slice(i + 1)
+					.some(
+						c =>
+							(c.type === "text" && canonicalizeMessage(c.text)) ||
+							(c.type === "image" && c.data && c.mimeType) ||
+							(c.type === "thinking" && resolveThinkingDisplay(c, this.#proseOnlyThinking).visible),
+					);
+
+				// Thinking traces in thinkingText color, italic
+				const md = new Markdown(thinkingText, 1, 0, getMarkdownTheme(), {
+					color: (text: string) => theme.fg("thinkingText", text),
+					italic: true,
+				});
+				md.transientRenderCache = this.#lastUpdateTransient;
+				this.#contentContainer.addChild(md);
+				captureItems?.push({ md, contentIndex: i, blockType: "thinking", lastText: thinkingText });
+				this.#appendThinkingExtensions(i, thinkingIndex, thinkingText);
+				hasRenderedContent = true;
+				thinkingIndex += 1;
+				if (hasVisibleContentAfter) {
+					this.#contentContainer.addChild(new Spacer(1));
+				}
+			} else if (content.type === "image" && content.data && content.mimeType) {
+				this.#renderImageEntries([{ image: content, key: `native:${i}` }], hasRenderedContent);
+				hasRenderedContent ||= this.#showImages;
+			}
+		}
+
+		if (this.#shouldAnimateThinking(message)) {
+			if (hasVisibleContent) this.#contentContainer.addChild(new Spacer(1));
+			this.#thinkingDots = new Text(this.#thinkingDotsLabel(), 1, 0);
+			this.#contentContainer.addChild(this.#thinkingDots);
+			this.#startThinkingAnimation();
+		} else {
+			this.#stopThinkingAnimation();
+		}
+
+		this.#renderToolImages();
+		const errorPresentation = resolveAssistantErrorPresentation(message);
+		const hasToolCalls = message.content.some(c => c.type === "toolCall");
+		if (errorPresentation.kind === "compact-recovered") {
+			this.#contentContainer.addChild(new Spacer(1));
+			this.#contentContainer.addChild(new Text(theme.fg("dim", errorPresentation.text), 1, 0));
+		} else if (!hasToolCalls && errorPresentation.kind === "full") {
+			if (message.stopReason === "aborted") {
+				this.#contentContainer.addChild(new Spacer(1));
+				this.#contentContainer.addChild(new Text(theme.fg("error", errorPresentation.text), 1, 0));
+			} else {
+				// Non-aborted provider error: a truncatable inline block. Mark it so
+				// setExpanded re-renders even while the same error is pinned above.
+				this.#hasTruncatableError = true;
+				// Suppress the inline block only while pinned AND collapsed — the
+				// banner already shows the capped error there. When expanded, draw
+				// the inline block in full so the complete body is reachable without
+				// sending a message; the pinned banner stays a short reminder.
+				if (!(message.stopReason === "error" && this.#errorPinned) || this.#errorExpanded) {
+					this.#contentContainer.addChild(new Spacer(1));
+					this.#appendErrorBlock(errorPresentation.text);
+				}
+			}
+		}
+		// Store fast-path state for next call
+		if (shouldCapture) {
+			this.#fastPathItems = captureItems;
+			this.#fastPathKey = this.#computeShapeKey(message);
+			this.#applyItemTransience(this.#lastUpdateTransient);
+		} else {
+			this.#fastPathKey = undefined;
+			this.#fastPathItems = undefined;
+		}
+	}
+
+	/**
+	 * Only the actively streaming (last) markdown renders in transient mode;
+	 * completed blocks render final — syntax-highlighted, module-LRU-cached,
+	 * byte-stable — so their rows can settle into native scrollback mid-turn
+	 * and are byte-identical to the finalize render.
+	 */
+	#applyItemTransience(transient: boolean): void {
+		const items = this.#fastPathItems;
+		if (!items) return;
+		for (let i = 0; i < items.length; i++) {
+			items[i]!.md.transientRenderCache = transient && i === items.length - 1;
+		}
+	}
+}