pi-agent-zh 17.1.8

package/src/modes/components/assistant-message.ts

@@ -0,0 +1,972 @@
+import type { AssistantMessage, ImageContent } from "@oh-my-pi/pi-ai";
+import {
+	Container,
+	Image,
+	type ImageBudget,
+	ImageProtocol,
+	Markdown,
+	replaceTabs,
+	Spacer,
+	TERMINAL,
+	Text,
+} from "@oh-my-pi/pi-tui";
+import { formatNumber } from "@oh-my-pi/pi-utils";
+import chalk from "chalk";
+import type { AssistantThinkingRenderer } from "../../extensibility/extensions/types";
+import { getMarkdownTheme, theme } from "../../modes/theme/theme";
+import { expandKeyHint, getPreviewLines, resolveImageOptions, TRUNCATE_LENGTHS } from "../../tools/render-utils";
+import { canonicalizeMessage, formatThinkingForDisplay, hasDisplayableThinking } from "../../utils/thinking-display";
+import { resolveAssistantErrorPresentation } from "../utils/transcript-render-helpers";
+import { type CacheInvalidation, CacheInvalidationMarkerComponent } from "./cache-invalidation-marker";
+
+/**
+ * Max lines 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. Blank lines are dropped and each
+ * line is width-truncated by {@link getPreviewLines}. Full text is still kept in
+ * the persisted session.
+ */
+const MAX_TRANSCRIPT_ERROR_LINES = 8;
+
+/** Opening or closing fence of a code block: ≥3 backticks/tildes plus info string. */
+const CODE_FENCE_LINE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+
+type ThinkingContentBlock = Extract<AssistantMessage["content"][number], { type: "thinking" }>;
+type DisplayThinkingContentBlock = ThinkingContentBlock & { rawThinking?: string };
+
+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),
+	};
+}
+
+/**
+ * Whether `text` contains a ` ```mermaid ` fence (open or closed) outside
+ * ordinary code fences. Mermaid defers native-scrollback settling wholesale
+ * (see {@link AssistantMessageComponent.getTranscriptBlockSettledRows}): its
+ * ASCII rendering resolves asynchronously, so even a completed fence can
+ * re-layout rows that already looked settled. Fence-aware so a mermaid
+ * example inside a regular code block never triggers the deferral.
+ */
+function containsMermaidFence(text: string): boolean {
+	let fence: string | null = null;
+	for (const line of text.split("\n")) {
+		const fenceMatch = CODE_FENCE_LINE.exec(line);
+		if (fence !== null) {
+			// Inside a code block: only a bare matching closing fence ends it.
+			if (
+				fenceMatch &&
+				fenceMatch[2]!.trim() === "" &&
+				fenceMatch[1]![0] === fence[0] &&
+				fenceMatch[1]!.length >= fence.length
+			) {
+				fence = null;
+			}
+			continue;
+		}
+		if (fenceMatch) {
+			if (/^mermaid\b/.test(fenceMatch[2]!.trim())) return true;
+			fence = fenceMatch[1]!;
+		}
+	}
+	return false;
+}
+
+/**
+ * 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)}`;
+}
+
+/**
+ * Component that renders a complete assistant message
+ */
+export class AssistantMessageComponent extends Container {
+	#contentContainer: Container;
+	#markerSlot: Container;
+	#lastMessage?: AssistantMessage;
+	#toolImagesByCallId = new Map<string, ImageContent[]>();
+	#convertedKittyImages = new Map<string, ImageContent>();
+	#showImages = true;
+	#kittyConversionsInFlight = new Set<string>();
+	#transcriptBlockFinalized: boolean;
+	/**
+	 * True while any rendered item carries a ` ```mermaid ` fence. Mermaid's
+	 * ASCII form resolves asynchronously and can re-layout rows that already
+	 * looked settled, so settling defers until the message finalizes. See
+	 * {@link getTranscriptBlockSettledRows}. Recomputed in
+	 * {@link updateContent} ahead of the fast-path return, so it tracks every
+	 * stream tick. Streaming GFM tables need no gate: they live in markdown's
+	 * unfrozen tail while re-aligning and render deterministically once their
+	 * block completes.
+	 */
+	#containsMermaidSource = false;
+	/**
+	 * 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_LINES}-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;
+	/** Width of the most recent render(); the settled-rows walk reads child
+	 *  renders at exactly this width (L1 cache hits). */
+	#lastRenderWidth = 0;
+	// 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;
+	/** 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;
+
+	setTextColorTransform(transform?: (text: string) => string): void {
+		this.#textColorTransform = transform;
+	}
+	constructor(
+		message?: AssistantMessage,
+		private hideThinkingBlock = false,
+		private readonly onImageUpdate?: () => void,
+		private readonly thinkingRenderers: readonly AssistantThinkingRenderer[] = [],
+		private readonly imageBudget?: ImageBudget,
+		private proseOnlyThinking = true,
+	) {
+		super();
+		this.#transcriptBlockFinalized = message !== undefined;
+
+		// Slim cache-invalidation divider, populated above the content when this
+		// turn's request lost the prompt cache (see setCacheInvalidation).
+		this.#markerSlot = new Container();
+		this.addChild(this.#markerSlot);
+
+		// Container for text/thinking content
+		this.#contentContainer = new Container();
+		this.addChild(this.#contentContainer);
+
+		if (message) {
+			this.updateContent(message);
+		}
+	}
+
+	/**
+	 * Show or clear the slim cache-invalidation divider above this turn. Set at
+	 * `message_end` (live) or during rebuild, once the turn's usage is known and
+	 * compared against the previous turn's cache footprint. Bumps the transcript
+	 * block version so the change repaints even after content finalized.
+	 */
+	setCacheInvalidation(info: CacheInvalidation | undefined): void {
+		this.#markerSlot.clear();
+		if (info) {
+			this.#markerSlot.addChild(new CacheInvalidationMarkerComponent(info));
+		}
+		this.#blockVersion++;
+	}
+
+	override invalidate(): void {
+		super.invalidate();
+		// Theme/symbol changes arrive via invalidate(). Fast-path children captured
+		// getMarkdownTheme() 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.#fastPathKey = undefined;
+		this.#fastPathItems = undefined;
+		if (this.#lastMessage) {
+			this.updateContent(this.#lastMessage, { transient: this.#lastUpdateTransient });
+		}
+	}
+
+	override render(width: number): readonly string[] {
+		this.#lastRenderWidth = width;
+		return super.render(width);
+	}
+
+	setHideThinkingBlock(hide: boolean): void {
+		this.hideThinkingBlock = hide;
+	}
+
+	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;
+	}
+
+	/**
+	 * Settled leading rows for mid-stream native-scrollback commits (see
+	 * `FinalizableBlock.getTranscriptBlockSettledRows`). Completed content
+	 * blocks render in final form (non-transient) and settle in full; the
+	 * actively streaming markdown contributes its rendered frozen-token
+	 * prefix. The walk stops at the first child that is not declared
+	 * byte-stable (the animated thinking pulse, extension components, images,
+	 * error rows), and a cache-invalidation marker above the content defers
+	 * settling entirely. Mermaid anywhere defers wholesale — its ASCII
+	 * rendering resolves asynchronously and can re-layout settled-looking
+	 * rows. Reads only L1-cached child renders at the width recorded by this
+	 * frame's render().
+	 */
+	getTranscriptBlockSettledRows(): number {
+		if (this.#transcriptBlockFinalized || !this.#lastUpdateTransient) return 0;
+		if (this.#containsMermaidSource) return 0;
+		if (this.#markerSlot.children.length > 0) return 0;
+		const items = this.#fastPathItems;
+		const width = this.#lastRenderWidth;
+		if (!items || items.length === 0 || width <= 0) return 0;
+		const streaming = items[items.length - 1]!.md;
+		// Items are captured in child order: match completed mds positionally.
+		let itemIndex = 0;
+		let settled = 0;
+		for (const child of this.#contentContainer.children) {
+			if (child === streaming) return settled + streaming.getLastRenderSettledRows();
+			if (itemIndex < items.length - 1 && items[itemIndex]!.md === child) {
+				itemIndex++;
+				settled += child.render(width).length;
+				continue;
+			}
+			if (child instanceof Spacer) {
+				settled += child.render(width).length;
+				continue;
+			}
+			// Not declared byte-stable: the boundary stops here.
+			return settled;
+		}
+		return settled;
+	}
+
+	getTranscriptBlockVersion(): number {
+		return this.#blockVersion;
+	}
+
+	markTranscriptBlockFinalized(): void {
+		this.#transcriptBlockFinalized = true;
+		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. Collapsed (default), it drops
+	 * blank lines, clamps the line count to {@link MAX_TRANSCRIPT_ERROR_LINES},
+	 * and width-truncates each line so a pathological body — e.g. the HTML page a
+	 * proxy returns on a 502 — can't flood the transcript, appending a dim
+	 * `ctrl+o`/expand hint when lines were hidden. Expanded (via
+	 * {@link setExpanded}), it renders the full body — tabs replaced, blank lines
+	 * preserved — letting {@link Text} word-wrap each line to the render width so
+	 * the complete message is reachable. Mirrors {@link ErrorBannerComponent}.
+	 */
+	#appendErrorBlock(message: string): void {
+		if (this.#errorExpanded) {
+			const [first = "Unknown error", ...rest] = replaceTabs(message.replace(/\s+$/, "")).split("\n");
+			this.#contentContainer.addChild(new Text(theme.fg("error", `Error: ${first}`), 1, 0));
+			for (const line of rest) {
+				this.#contentContainer.addChild(new Text(theme.fg("error", `  ${line}`), 1, 0));
+			}
+			return;
+		}
+		const total = message.split("\n").filter(l => l.trim()).length;
+		const lines = getPreviewLines(message, MAX_TRANSCRIPT_ERROR_LINES, TRUNCATE_LENGTHS.LINE);
+		if (lines.length === 0) lines.push("Unknown error");
+		// The caller owns the separating Spacer; adding one here doubled the gap.
+		this.#contentContainer.addChild(new Text(theme.fg("error", `Error: ${lines[0]}`), 1, 0));
+		for (const line of lines.slice(1)) {
+			this.#contentContainer.addChild(new Text(theme.fg("error", `  ${line}`), 1, 0));
+		}
+		if (total > lines.length) {
+			const hidden = total - lines.length;
+			this.#contentContainer.addChild(
+				new Text(
+					theme.fg("dim", `  … +${hidden} more line${hidden === 1 ? "" : "s"} (${expandKeyHint()} to expand)`),
+					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 });
+		}
+	}
+
+	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);
+			new Bun.Image(Buffer.from(image.data, "base64"))
+				.png()
+				.toBase64()
+				.then(data => {
+					this.#kittyConversionsInFlight.delete(key);
+					this.#convertedKittyImages.set(key, {
+						type: "image",
+						data,
+						mimeType: "image/png",
+					});
+					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 {
+		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") {
+				const display = resolveThinkingDisplay(content, this.proseOnlyThinking);
+				if (!display.visible) parts.push("K0");
+				else if (this.hideThinkingBlock) parts.push("KH");
+				else parts.push("KV");
+			} 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.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;
+
+		// 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;
+		}
+
+		// Mermaid ASCII rendering resolves asynchronously, so a fence anywhere
+		// in the rendered source (text or visible thinking) defers settling; see
+		// getTranscriptBlockSettledRows. Detected from raw source — a Markdown
+		// parser only resolves the fence once it closes, but the stale commits
+		// would happen mid-stream.
+		this.#containsMermaidSource = message.content.some(content => {
+			if (content.type === "text") return containsMermaidFence(content.text);
+			if (content.type === "thinking" && !this.hideThinkingBlock) {
+				const display = resolveThinkingDisplay(content, this.proseOnlyThinking);
+				return display.visible && containsMermaidFence(display.text);
+			}
+			return 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.#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, getMarkdownTheme(), mdOptions);
+				this.#contentContainer.addChild(md);
+				captureItems?.push({ md, contentIndex: i, blockType: "text", lastText: trimmed });
+				hasRenderedContent = true;
+			} else if (content.type === "thinking" && resolveThinkingDisplay(content, this.proseOnlyThinking).visible) {
+				const thinkingText = resolveThinkingDisplay(content, this.proseOnlyThinking).text;
+				if (this.hideThinkingBlock) {
+					thinkingIndex += 1;
+					continue;
+				}
+				// 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;
+		}
+	}
+}