@linxiraos/pi-tui 1.2.1 → 1.3.0

package/src/chat/advisor-message.ts

@@ -4,9 +4,9 @@ import { visibleWidth } from "../utils";
 import type { AdvisorMessageDetails, AdvisorNote, AdvisorSeverity } from "./messages";
 import { formatBadge, replaceTabs, type ToolUIColor, wrapTextWithAnsi } from "../render/render-utils";
 import { Ellipsis, truncateToWidth } from "../render";
-import { getThemeEpoch, type Theme } from "../theme";
-import type { TspSpan } from "@linxiraos/pi-wire";
-import { card, span, text } from "../native/describe";
+import type { Theme } from "../theme";
+import type { TspSpan, TspTone } from "@linxiraos/pi-wire";
+import { card, node, span, text } from "../native/describe";
 import { type NativeNode, type NativeUiEvent, rootToggleExpanded } from "../native/node";
 import { plainText } from "../native/spans";
 import { Memo } from "../native/memo";
@@ -111,13 +111,16 @@ class AdvisorNotes implements Component {
 	}
 }
 
+/** The advisor a note came from; undefined for the implicit single ("default") advisor, which goes unlabeled. */
+function sourceOf(entry: AdvisorNote): string | undefined {
+	return entry.advisor && entry.advisor !== "default" ? entry.advisor : undefined;
+}
+
 /** Wrapped, truncated rail rows for a single note; shared by both branches. */
 function renderAdvisorNote(entry: AdvisorNote, width: number, uiTheme: Theme): string[] {
 	const badge = entry.severity ? `${formatBadge(entry.severity, severityColor(entry.severity), uiTheme)} ` : "";
-	// Multi-advisor: attribute the note to its source. The implicit
-	// single ("default") advisor renders unlabeled, as before.
-	const who =
-		entry.advisor && entry.advisor !== "default" ? `${uiTheme.fg("dim", `[${replaceTabs(entry.advisor)}]`)} ` : "";
+	const source = sourceOf(entry);
+	const who = source ? `${uiTheme.fg("dim", `[${replaceTabs(source)}]`)} ` : "";
 	const age = entry.turnsAgo !== undefined ? `${uiTheme.fg("dim", `T-${entry.turnsAgo}`)} ` : "";
 	const railGlyph = uiTheme.symbol("advisor.rail");
 	const rail = uiTheme.fg(severityColor(entry.severity), railGlyph);
@@ -145,16 +148,47 @@ function renderAdvisorNote(entry: AdvisorNote, width: number, uiTheme: Theme): s
 	);
 }
 
-/** Native spans for one note: severity badge, advisor attribution, then the note text. */
-function advisorNoteSpans(entry: AdvisorNote): TspSpan[] {
+/** A note's rank in the native callout: its severity, `note` when it has none. */
+type AdvisorRank = AdvisorSeverity | "note";
+
+/** Ranks worst first: the callout wears the worst rank among its notes. */
+const RANKS: readonly AdvisorRank[] = ["blocker", "concern", "nit", "note"];
+
+/** Each rank's native look, GitHub-alert style: card/icon tone, Tern icon name, label and its span style. */
+const RANK_LOOK: Record<AdvisorRank, { tone: TspTone; icon: string; label: string; style: string }> = {
+	blocker: { tone: "error", icon: "octagon-alert", label: "Blocker", style: "error strong" },
+	concern: { tone: "warning", icon: "warn", label: "Concern", style: "warning strong" },
+	nit: { tone: "neutral", icon: "lightbulb", label: "Nit", style: "strong" },
+	note: { tone: "neutral", icon: "info", label: "Note", style: "strong" },
+};
+
+function rankOf(entry: AdvisorNote): AdvisorRank {
+	return entry.severity ?? "note";
+}
+
+/** The callout's title: one note's rank (`Concern`), else a tally worst first (`1 blocker · 2 concerns`). */
+function tallySpans(notes: readonly AdvisorNote[]): TspSpan[] {
+	if (notes.length === 1) {
+		const { label, style } = RANK_LOOK[rankOf(notes[0]!)];
+		return [span(label, style)];
+	}
 	const spans: TspSpan[] = [];
-	if (entry.severity)
-		spans.push(span(entry.severity.toUpperCase(), `${severityColor(entry.severity)} strong`), span(" "));
-	if (entry.advisor && entry.advisor !== "default") spans.push(span(`[${entry.advisor}] `, "dim"));
-	spans.push(span(plainText(entry.note), "customMessageText"));
+	for (const rank of RANKS) {
+		const count = notes.filter(entry => rankOf(entry) === rank).length;
+		if (count === 0) continue;
+		if (spans.length > 0) spans.push(span(" · ", "dim"));
+		spans.push(span(`${count} ${rank}${count === 1 ? "" : "s"}`, RANK_LOOK[rank].style));
+	}
 	return spans;
 }
 
+/** Native spans for one note: its advisor when the callout mixes several, then the text. */
+function noteSpans(entry: AdvisorNote, attribute: boolean): TspSpan[] {
+	const who = attribute ? sourceOf(entry) : undefined;
+	const body = span(plainText(entry.note));
+	return who ? [span(`${who} · `, "dim"), body] : [body];
+}
+
 /** The advisor card: shared by the controlled expansion getter and native toggles. */
 export interface AdvisorMessageCard extends Component {
 	/** Transcript-wide expansion (`Ctrl+O`); clears a toggle made in the terminal. */
@@ -168,6 +202,9 @@ export interface AdvisorMessageCard extends Component {
  * output (whose `thinkingText` color equals `toolOutput` in most themes):
  * a bold `customMessageLabel` header tag (skill-card convention), a heavy
  * rail tinted per-note severity, and the note body on the default text color.
+ * Natively it is a callout tinted by its worst note: that severity's icon and
+ * the tally head it, the advisor's name ends the head, and with several notes
+ * each leads with its own severity icon.
  *
  * `getExpanded` owns expansion; a native toggle overrides it for this card
  * until the next transcript-wide change.
@@ -193,24 +230,40 @@ export function createAdvisorMessageCard(
 	};
 	const nativeMemo = new Memo();
 	const describeCard = (isExpanded: boolean): NativeNode => {
-		const head: TspSpan[] = [
-			span(`${uiTheme.status.info} Advisor`, "customMessageLabel strong"),
-			span(` ${notes.length} ${notes.length === 1 ? "note" : "notes"}`, "dim"),
-		];
-		if (blockers > 0) head.push(span(`${uiTheme.sep.dot}${blockers} blocker${blockers === 1 ? "" : "s"}`, "error"));
-		const body = notes.map((entry, index) =>
-			text(advisorNoteSpans(entry), { wrap: "word", role: "zeta.advisor.note", key: `n${index}` }),
+		const look = RANK_LOOK[RANKS.find(rank => notes.some(entry => rankOf(entry) === rank)) ?? "note"];
+		const sources = new Set(notes.map(sourceOf));
+		const [sole] = sources;
+		const head = node(
+			"row",
+			{ gap: "sm", align: "center", role: "zeta.advisor.head" },
+			[
+				node("icon", { name: look.icon, tone: look.tone }),
+				text(tallySpans(notes), { grow: 1 }),
+				text([span(sources.size === 1 && sole ? sole : "Advisor", "dim")], { role: "zeta.advisor.source" }),
+			],
+			"head",
 		);
+		const attribute = sources.size > 1;
+		const body = notes.map((entry, index) => {
+			const spans = noteSpans(entry, attribute);
+			if (notes.length === 1) return text(spans, { wrap: "word", role: "zeta.advisor.note", key: `n${index}` });
+			const { tone, icon, label } = RANK_LOOK[rankOf(entry)];
+			return node(
+				"row",
+				{ gap: "sm", align: "start", role: "zeta.advisor.note", tone },
+				[node("icon", { name: icon, tone, aria: label }), text(spans, { wrap: "word", grow: 1, shrink: 1 })],
+				`n${index}`,
+			);
+		});
 		return card(
 			{
 				role: "zeta.advisor",
-				tone: blockers > 0 ? "error" : "info",
-				head,
+				tone: look.tone,
 				collapsible: notes.length > COLLAPSED_NOTES,
 				collapsed: notes.length > COLLAPSED_NOTES ? !isExpanded : undefined,
 				preview: notes.length > COLLAPSED_NOTES ? "auto" : undefined,
 			},
-			body,
+			[head, ...body],
 		);
 	};
 
@@ -231,7 +284,7 @@ export function createAdvisorMessageCard(
 		},
 		describe(): NativeNode {
 			const isExpanded = expanded();
-			return nativeMemo.get([isExpanded, getThemeEpoch()], () => describeCard(isExpanded));
+			return nativeMemo.get([isExpanded], () => describeCard(isExpanded));
 		},
 		setExpanded(value: boolean): void {
 			lastGlobal = value;

package/src/chat/assistant-message.d.ts

@@ -2,7 +2,7 @@ import type { AssistantMessage, ImageContent } from "@linxiraos/pi-ai";
 import { type Component, Container } from "../tui";
 import { type ImageBudget } from "../components/image";
 import type { AssistantThinkingRenderer } from "./extension-types";
-import type { NativeNode, NativeUiEvent } from "../native/node";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node";
 import { type CacheInvalidation } from "./cache-invalidation-marker";
 import { type ServedModelMismatch } from "./served-model-marker";
 import { type TranscriptStableRow } from "../chrome/transcript-container";
@@ -99,13 +99,13 @@ export declare class AssistantMessageComponent extends Container {
      * head's `title`. With `hideThinkingBlock` only the live head shows (collapsed)
      * and a finished thought emits nothing.
      */
-    describe(): NativeNode;
+    describe(cx?: DescribeContext): NativeNode;
     /**
      * A TTSR rule rewound this partial answer: a native terminal dims it and
      * tags it `↺ rewound` (the ANSI render leaves it as it stopped).
      */
     markRewound(): void;
-    /** Mirrors a thinking section collapsed or expanded in the terminal. */
+    /** Mirrors a thinking section collapsed or expanded in the terminal; runs its controls' clicks. */
     handleNativeEvent(event: NativeUiEvent): void;
     /** Width-independent stable identities for the streamed leading thinking run. */
     getTranscriptStableRows(): readonly TranscriptStableRow[];
@@ -130,7 +130,12 @@ export declare class AssistantMessageComponent extends Container {
     setTableChartsVisible(visible: boolean): void;
     /** Toggle only images produced by tool results; assistant-native images remain governed by setImagesVisible. */
     setToolResultImagesVisible(visible: boolean): void;
-    setToolResultImages(toolCallId: string, images: ImageContent[]): void;
+    /**
+     * A grouped read's result images, and `mediaPath`: the file it read that Tern's media viewer
+     * shows (read details), which a native host supporting `media` shows by path instead of the
+     * images. A media-only result (a model, a PDF) passes no images.
+     */
+    setToolResultImages(toolCallId: string, images: ImageContent[], mediaPath?: string): void;
     updateContent(message: AssistantMessage, opts?: {
         transient?: boolean;
     }): void;

package/src/chat/assistant-message.ts

@@ -1,12 +1,16 @@
 import type { AssistantMessage, ImageContent, TextContent } from "@linxiraos/pi-ai";
+import { presentNarrationAsAnswer } from "@linxiraos/pi-ai/utils/narration";
 import { type Component, Container } from "../tui";
 import { Image, type ImageBudget } from "../components/image";
 import { ImageProtocol, TERMINAL } from "../terminal-capabilities";
 import {
 	type DefaultTextStyle,
+	holdPartialTableRow,
 	Markdown,
 	type MarkdownTheme,
 	rewriteMarkdownLinkDestinations,
+	speculativeStreamingSource,
+	streamingMarkdownSource,
 } from "../components/markdown";
 import { Spacer } from "../components/spacer";
 import { Text } from "../components/text";
@@ -17,9 +21,10 @@ import type { AssistantThinkingRenderer } from "./extension-types";
 import { ensureThemeSync, getMarkdownTheme, getMarkdownThemeWithLinkTargets, getThemeEpoch, theme } from "../theme";
 import { card, col, elapsed, node, span, text } from "../native/describe";
 import { hasTranscriptActions, runTranscriptAction } from "./transcript-actions";
-import type { NativeChild, NativeNode, NativeUiEvent } from "../native/node";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
 import { isNativeRendering } from "../native/state";
-import { NativeImageCache } from "../native/blobs";
+import { NativeImageCache, nativeMediaNode } from "../native/blobs";
+import { linkedImageText } from "../prompt/image-references";
 import { Memo } from "../native/memo";
 import { EMPTY_LINK_TARGETS, resolveImageOptions } from "../render/render-utils";
 import { WidthAwareText } from "../render";
@@ -35,7 +40,7 @@ import { formatTurnUsage, type TurnUsageSummary } from "../overlays/usage-row";
 import { FigureMarkdown } from "./figure-markdown";
 import { svgFigureRendering } from "./svg-figure";
 import { hasSvgFence } from "./svg-source";
-import { describeTableChart, hasChartTable, lookupTableChart, splitTableCharts } from "./table-chart";
+import { chartFence, hasChartTable, lookupTableChart, splitTableCharts } from "./table-chart";
 
 /**
  * Max wrapped rows of a turn-ending provider error rendered inline in the
@@ -111,6 +116,14 @@ interface StableRenderInputs {
 	readonly color: ((text: string) => string) | undefined;
 }
 
+/**
+ * A partial last thinking line the prose fold may still drop: the start of a
+ * fence marker (`` ` ``, `~`) or of an empty `<!-- -->` sentinel. Once it turns
+ * into either, the fold's ellipsis lands back on the line above it
+ * (`formatThinkingForDisplay`), so that line is not yet settled.
+ */
+const UNSETTLED_THINKING_TAIL = /(?:^|\n)[^\S\n]*(?:`{1,2}|~{1,2}|<(?:!(?:-(?:-[^\S\n]*-{0,2})?)?)?)[^\S\n]*$/;
+
 function isSnapshotExtension(previous: readonly StablePart[], current: readonly StablePart[]): boolean {
 	if (previous.length > current.length) return false;
 	for (let index = 0; index < previous.length; index++) {
@@ -250,6 +263,8 @@ export class AssistantMessageComponent extends Container {
 	#lastMessage?: AssistantMessage;
 	#emergencyText?: ProseBlock;
 	#toolImagesByCallId = new Map<string, ImageContent[]>();
+	/** File each grouped read showed that Tern's media viewer shows, for native `media` nodes. */
+	#toolMediaPathByCallId = new Map<string, string>();
 	/**
 	 * Payload keys ({@link imagePayloadKey}) whose Kitty PNG conversion this
 	 * component is awaiting, so a re-delivered image neither re-encodes nor
@@ -798,7 +813,8 @@ export class AssistantMessageComponent extends Container {
 	 * head's `title`. With `hideThinkingBlock` only the live head shows (collapsed)
 	 * and a finished thought emits nothing.
 	 */
-	override describe(): NativeNode {
+	override describe(cx?: DescribeContext): NativeNode {
+		const media = cx?.supports("media") === true;
 		const tail = this.#displayedMessage ? this.#thinkingTailIndex(this.#displayedMessage) : undefined;
 		const rate =
 			tail !== undefined && this.#lastUpdateTransient && this.#thinkingRateLive
@@ -813,9 +829,10 @@ export class AssistantMessageComponent extends Container {
 			this.#errorExpanded,
 			this.#nativeViewVersion,
 			rate,
+			media,
 			getThemeEpoch(),
 		];
-		return this.#native.get(key, () => this.#describeMessage(tail, rate));
+		return this.#native.get(key, () => this.#describeMessage(tail, rate, media));
 	}
 
 	/**
@@ -828,10 +845,10 @@ export class AssistantMessageComponent extends Container {
 		this.#nativeViewVersion++;
 	}
 
-	/** Mirrors a thinking section collapsed or expanded in the terminal. */
+	/** Mirrors a thinking section collapsed or expanded in the terminal; runs its controls' clicks. */
 	handleNativeEvent(event: NativeUiEvent): void {
 		if (event.type === "action") {
-			this.#handleErrorAction(event.act);
+			this.#handleAction(event.act);
 			return;
 		}
 		if (event.type !== "toggle" || !event.key.startsWith("k")) return;
@@ -841,7 +858,7 @@ export class AssistantMessageComponent extends Container {
 		this.#nativeViewVersion++;
 	}
 
-	#describeMessage(thinkingTail: number | undefined, rate: number): NativeNode {
+	#describeMessage(thinkingTail: number | undefined, rate: number, media: boolean): NativeNode {
 		const message = this.#displayedMessage;
 		const previousParts = this.#nativeParts;
 		const parts = new Map<string, { text: string; stream: boolean; node: NativeNode }>();
@@ -854,12 +871,19 @@ export class AssistantMessageComponent extends Container {
 					: {
 							text: source,
 							stream,
-							node: node("md", stream ? { text: source, stream: true } : { text: source }, undefined, key),
+							// A streaming node renders its open link or math span as already closed, as the TUI does.
+							node: node(
+								"md",
+								stream ? { text: speculativeStreamingSource(source), stream: true } : { text: source },
+								undefined,
+								key,
+							),
 						};
 			parts.set(slot, entry);
 			return entry.node;
 		};
 		const children: NativeChild[] = [];
+		let answered = false;
 		if (message) {
 			const live = !this.#transcriptBlockFinalized && this.#lastUpdateTransient;
 			let tailIndex = -1;
@@ -876,7 +900,10 @@ export class AssistantMessageComponent extends Container {
 				const content = message.content[index]!;
 				const streaming = live && index === tailIndex;
 				if (content.type === "text" && canonicalizeMessage(content.text)) {
-					const source = content.text.trim();
+					answered = true;
+					// A native terminal sizes table columns by every row it gets: send a growing row once
+					// its line ends. Hold before trimming, which would drop the newline ending a finished row.
+					const source = (streaming ? holdPartialTableRow(content.text) : content.text).trim();
 					// The terminal renders this source itself and would resolve a relative
 					// link against its own idea of the cwd: hand it the session-resolved
 					// targets (resolved once the segment closes, so never while streaming).
@@ -893,7 +920,7 @@ export class AssistantMessageComponent extends Container {
 						children.push(markdown(`t${index}`, `t${index}`, linked(source, streaming), streaming));
 						continue;
 					}
-					// A chart follows its table as an SVG image node; the prose splits around it.
+					// A chart follows its table as an ```svg figure the terminal colors; the prose splits around it.
 					const segments = splitTableCharts(source, streaming);
 					segments.forEach((segment, part) => {
 						const slot = part === 0 ? `t${index}` : `t${index}.${part}`;
@@ -904,7 +931,7 @@ export class AssistantMessageComponent extends Container {
 						}
 						const chart = lookupTableChart(segment.table);
 						if (chart instanceof Promise) this.#awaitChart(chart);
-						else if (chart) children.push(describeTableChart(chart, slot));
+						else if (chart) children.push(markdown(slot, slot, chartFence(chart), false));
 					});
 				} else if (content.type === "thinking") {
 					const display = resolveThinkingDisplay(content, this.#proseOnlyThinking);
@@ -960,9 +987,26 @@ export class AssistantMessageComponent extends Container {
 				}
 			}
 			if (this.#showImages && this.#showToolResultImages) {
+				// Reads of files Tern's media viewer shows: the host loads each file once by path, no bytes uploaded.
+				const shownPaths = new Set<string>();
+				if (media) {
+					for (const [toolCallId, mediaPath] of this.#toolMediaPathByCallId) {
+						if (shownPaths.has(mediaPath)) continue;
+						shownPaths.add(mediaPath);
+						children.push(nativeMediaNode(mediaPath, `r${toolCallId}`));
+					}
+				}
 				for (const [toolCallId, images] of this.#toolImagesByCallId) {
+					if (media && this.#toolMediaPathByCallId.has(toolCallId)) continue;
 					images.forEach((image, index) => {
-						children.push(this.#nativeImages.get(`r${toolCallId}:${index}`, image.data, image.mimeType));
+						children.push(
+							this.#nativeImages.get(
+								`r${toolCallId}:${index}`,
+								image.data,
+								image.mimeType,
+								this.#toolMediaPathByCallId.get(toolCallId),
+							),
+						);
 					});
 				}
 			}
@@ -983,14 +1027,32 @@ export class AssistantMessageComponent extends Container {
 		}
 		if (this.#turnUsage) {
 			const usage = formatTurnUsage(this.#turnUsage);
+			const line: NativeChild[] = [];
+			// Led by Copy and a dot: `⧉ · 12.4s · 19K tok this turn`.
+			if (answered && hasTranscriptActions()) {
+				line.push(
+					// `copy-answer`, not Tern's local `copy` (that would copy the icon's empty label).
+					node(
+						"icon",
+						{
+							name: "copy",
+							role: "zeta.turn.copy",
+							title: "Copy answer",
+							aria: "Copy answer",
+							actions: { click: "copy-answer" },
+						},
+						undefined,
+						"copy",
+					),
+					node("text", { text: "·" }, undefined, "dot"),
+				);
+			}
+			line.push(node("text", { text: usage.text }, undefined, "text"));
 			children.push(
 				node(
 					"row",
 					{ role: "zeta.turn.usage", gap: "xs", align: "center", title: usage.title },
-					[
-						node("icon", { name: "time" }, undefined, "icon"),
-						node("text", { text: usage.text }, undefined, "text"),
-					],
+					line,
 					"turn-usage",
 				),
 			);
@@ -1081,11 +1143,24 @@ export class AssistantMessageComponent extends Container {
 		return card({ role: "zeta.error", tone: "error", key: "error" }, children);
 	}
 
-	/** Error frame action clicks: zeta's own retry, clipboard and model-picker paths. */
-	#handleErrorAction(act: string): void {
+	/** Control clicks (the error frame's actions, the turn footer's Copy): zeta's own retry, clipboard and model-picker paths. */
+	#handleAction(act: string): void {
 		if (act === "retry") runTranscriptAction({ act: "retry" });
 		else if (act === "switch-model") runTranscriptAction({ act: "switch-model" });
 		else if (act === "copy-error" && this.#errorText) runTranscriptAction({ act: "copy", text: this.#errorText });
+		else if (act === "copy-answer") {
+			const text = this.#answerText();
+			if (text) runTranscriptAction({ act: "copy", text });
+		}
+	}
+
+	/** The answer as the transcript shows it: its text blocks' markdown, a blank line apart, without thinking or tool calls. */
+	#answerText(): string {
+		const blocks: string[] = [];
+		for (const content of this.#displayedMessage?.content ?? []) {
+			if (content.type === "text" && canonicalizeMessage(content.text)) blocks.push(content.text.trim());
+		}
+		return blocks.join("\n\n");
 	}
 
 	/** Width-independent stable identities for the streamed leading thinking run. */
@@ -1198,17 +1273,23 @@ export class AssistantMessageComponent extends Container {
 					// 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.
+					// may rewrite it) and must stay out of published bytes. A
+					// partial thinking line the fold may still drop does not count.
+					// The frozen prefix is in streamingMarkdownSource form, so
+					// offsets into the block use that form too.
 					const raw = md.getLastRenderStableText();
 					const frozen = raw.trim();
-					if (frozen.length > 0 && /\S/.test(item.lastText.slice(raw.length))) {
+					let past = streamingMarkdownSource(item.lastText).slice(raw.length);
+					if (item.blockType === "thinking") past = past.replace(UNSETTLED_THINKING_TAIL, "");
+					if (frozen.length > 0 && /\S/.test(past)) {
 						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 });
+				// everything before it is final. Same form as the frozen prefix it
+				// published while streaming, so the snapshot still extends.
+				parts.push({ kind: item.blockType, text: streamingMarkdownSource(item.lastText) });
 				itemIndex++;
 				continue;
 			}
@@ -1493,8 +1574,15 @@ export class AssistantMessageComponent extends Container {
 		}
 	}
 
-	setToolResultImages(toolCallId: string, images: ImageContent[]): void {
+	/**
+	 * A grouped read's result images, and `mediaPath`: the file it read that Tern's media viewer
+	 * shows (read details), which a native host supporting `media` shows by path instead of the
+	 * images. A media-only result (a model, a PDF) passes no images.
+	 */
+	setToolResultImages(toolCallId: string, images: ImageContent[], mediaPath?: string): void {
 		if (!toolCallId) return;
+		if (mediaPath) this.#toolMediaPathByCallId.set(toolCallId, mediaPath);
+		else this.#toolMediaPathByCallId.delete(toolCallId);
 		const validImages = images.filter(img => img.type === "image" && img.data && img.mimeType);
 		if (validImages.length === 0) {
 			this.#toolImagesByCallId.delete(toolCallId);
@@ -1536,12 +1624,15 @@ export class AssistantMessageComponent extends Container {
 		}
 	}
 
-	#renderImageEntries(entries: Array<{ image: ImageContent; key: string }>, withLeadingSpacer: boolean): void {
+	#renderImageEntries(
+		entries: Array<{ image: ImageContent; key: string; sourcePath?: 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) {
+		for (const { image, key, sourcePath } of entries) {
 			let displayImage: ImageContent | undefined = image;
 			if (TERMINAL.imageProtocol === ImageProtocol.Kitty && image.mimeType !== "image/png") {
 				displayImage = this.#kittyConversion(image);
@@ -1555,6 +1646,7 @@ export class AssistantMessageComponent extends Container {
 						{ fallbackColor: (text: string) => theme.fg("toolOutput", text) },
 						{
 							...resolveImageOptions(),
+							sourcePath,
 							budget: this.#imageBudget,
 							imageKey: key,
 							requestRender: this.#onImageUpdate,
@@ -1563,15 +1655,18 @@ export class AssistantMessageComponent extends Container {
 				);
 				continue;
 			}
-			this.#contentContainer.addChild(new Text(theme.fg("toolOutput", `[Image: ${image.mimeType}]`), 1, 0));
+			this.#contentContainer.addChild(
+				new Text(theme.fg("toolOutput", linkedImageText(`[Image: ${image.mimeType}]`, image, sourcePath)), 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}` })),
-		);
+		const entries = Array.from(this.#toolImagesByCallId.entries()).flatMap(([toolCallId, images]) => {
+			const sourcePath = this.#toolMediaPathByCallId.get(toolCallId);
+			return images.map((image, index) => ({ image, key: `${toolCallId}:${index}`, sourcePath }));
+		});
 		this.#renderImageEntries(entries, true);
 	}
 
@@ -1714,7 +1809,8 @@ export class AssistantMessageComponent extends Container {
 		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);
+		// Narration the provider returned as thinking renders as answer text.
+		message = this.#displayMessage(presentNarrationAsAnswer(message), this.#lastUpdateTransient);
 		this.#displayedMessage = message;
 
 		// Streaming-speed gauge: only a live, in-flight render of the single

package/src/chat/bash-execution.ts

@@ -31,6 +31,7 @@ import {
 import { span, text } from "../native/describe";
 import { type DescribeContext, type NativeNode, type NativeUiEvent, rootToggleExpanded } from "../native/node";
 import { NativeImageCache } from "../native/blobs";
+import { imageLinksEnabled, linkedImageSpan, linkedImageText } from "../prompt/image-references";
 import { Memo } from "../native/memo";
 
 const STREAMING_LINE_CAP = PREVIEW_LINES * 5;
@@ -172,14 +173,18 @@ export class BashExecutionComponent extends Container {
 			this.#expanded,
 			this.#showImages,
 			this.#images.length,
+			// Image nodes and placeholders carry links only under an enabled policy.
+			imageLinksEnabled(),
 		];
 		return this.#native.get(key, () => {
 			const images = this.#images.map((image, index) =>
 				this.#showImages
 					? this.#nativeImages.get(`img${index}`, image.data, image.mimeType)
 					: text([
-							span(
+							linkedImageSpan(
 								imageFallback(image.mimeType, getImageDimensions(image.data, image.mimeType) ?? undefined),
+								image,
+								undefined,
 								"muted",
 							),
 						]),
@@ -418,7 +423,7 @@ export class BashExecutionComponent extends Container {
 			} else {
 				const dimensions = getImageDimensions(image.data, image.mimeType) ?? undefined;
 				this.#contentContainer.addChild(
-					new Text(theme.fg("muted", imageFallback(image.mimeType, dimensions)), 1, 0),
+					new Text(theme.fg("muted", linkedImageText(imageFallback(image.mimeType, dimensions), image)), 1, 0),
 				);
 			}
 		}

package/src/chat/figure-markdown.d.ts

@@ -1,5 +1,5 @@
 import type { ImageBudget } from "../components/image";
-import type { Markdown } from "../components/markdown";
+import { type Markdown } from "../components/markdown";
 import { Container } from "../tui";
 export interface FigureMarkdownOptions {
     /** Markdown for one prose run (and a failed figure's code fallback); FigureMarkdown drives its transience. */
@@ -32,7 +32,12 @@ export declare class FigureMarkdown extends Container {
     /**
      * The trimmed prose ahead of the first figure, or "" when the block opens
      * with one. These are the only rows plain Markdown reproduces byte for
-     * byte, so they are all a transcript may publish ahead of the figure.
+     * byte, so they are all a transcript may publish ahead of the figure. While
+     * that prose is still the streaming tail (no figure follows it yet), only
+     * its settled prefix ({@link Markdown.getLastRenderStableText}) qualifies:
+     * the rest is still being written. Both forms are in
+     * {@link streamingMarkdownSource} form, so the settled prefix stays a byte
+     * prefix of the whole run once a figure splits it off.
      */
     get leadingProse(): string;
     /** Whether a figure's final source still waits for its raster, or a chart for its pick or raster. */

package/src/chat/figure-markdown.ts

@@ -1,6 +1,6 @@
 import type { Tokens } from "@linxiraos/pi-utils/marked";
 import type { ImageBudget } from "../components/image";
-import type { Markdown } from "../components/markdown";
+import { type Markdown, streamingMarkdownSource } from "../components/markdown";
 import { Spacer } from "../components/spacer";
 import { Container } from "../tui";
 import { SvgFigure, svgFigureRendering } from "./svg-figure";
@@ -68,11 +68,18 @@ export class FigureMarkdown extends Container {
 	/**
 	 * The trimmed prose ahead of the first figure, or "" when the block opens
 	 * with one. These are the only rows plain Markdown reproduces byte for
-	 * byte, so they are all a transcript may publish ahead of the figure.
+	 * byte, so they are all a transcript may publish ahead of the figure. While
+	 * that prose is still the streaming tail (no figure follows it yet), only
+	 * its settled prefix ({@link Markdown.getLastRenderStableText}) qualifies:
+	 * the rest is still being written. Both forms are in
+	 * {@link streamingMarkdownSource} form, so the settled prefix stays a byte
+	 * prefix of the whole run once a figure splits it off.
 	 */
 	get leadingProse(): string {
 		const first = this.#parts[0];
-		return first?.kind === "markdown" ? first.text : "";
+		if (first?.kind !== "markdown") return "";
+		if (this.#transient && this.#parts.length === 1) return first.md.getLastRenderStableText().trim();
+		return streamingMarkdownSource(first.text);
 	}
 
 	/** Whether a figure's final source still waits for its raster, or a chart for its pick or raster. */

package/src/chat/image-loading.ts

@@ -1,5 +1,10 @@
 import type { ImageContent, Model } from "@linxiraos/pi-ai";
-import { formatBytes, parseImageMetadata, SUPPORTED_IMAGE_MIME_TYPES } from "@linxiraos/pi-utils";
+import {
+	decodeBase64ImageData,
+	formatBytes,
+	parseImageMetadata,
+	SUPPORTED_IMAGE_MIME_TYPES,
+} from "@linxiraos/pi-utils";
 
 export const MAX_IMAGE_INPUT_BYTES = 20 * 1024 * 1024;
 
@@ -83,11 +88,9 @@ const DECODE_PROBE_EDGE_PX = 1;
  * truth on both sides. Callers on hot paths must cache the verdict.
  */
 export async function imageDecodeFailureReason(image: ImageContent): Promise<string | null> {
-	if (!/^[A-Za-z0-9+/]*={0,2}$/.test(image.data)) return "invalid base64 image data";
-	const normalizedData = image.data.replace(/=+$/, "");
-	const bytes = Buffer.from(image.data, "base64");
-	if (bytes.length === 0) return "empty image data";
-	if (bytes.toString("base64").replace(/=+$/, "") !== normalizedData) return "invalid base64 image data";
+	const decoded = decodeBase64ImageData(image.data);
+	if (decoded.reason !== undefined) return decoded.reason;
+	const { bytes } = decoded;
 	const detected = parseImageMetadata(bytes);
 	if (detected && detected.mimeType !== image.mimeType.toLowerCase()) {
 		return `declared ${image.mimeType} but contains ${detected.mimeType}`;