@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/chat/table-chart.d.ts

@@ -0,0 +1,89 @@
+import type { Tokens } from "@linxiraos/pi-utils/marked";
+import { type ChartPlan } from "../charts/chart-plan";
+import { type TableAnalysis } from "../charts/table-data";
+import type { ImageBudget } from "../components/image";
+import type { NativeNode } from "../native/node";
+import type { Component } from "../tui";
+/**
+ * `smart`: a model refines the local guess where meaning decides (kind,
+ * columns, row names, ordering, polarity, focus, title; see {@link shouldJudge});
+ * `always`: the local best guess charts every table it reads as numeric;
+ * `off`: tables stay tables.
+ */
+export type TableChartMode = "smart" | "always" | "off";
+/** A table the host's planner picks a chart for ({@link shouldJudge}). */
+export interface TableChartRequest {
+    /** The table's Markdown source. */
+    readonly markdown: string;
+    readonly table: TableAnalysis;
+    /** The local best guess; the planner may keep it. */
+    readonly guess: ChartPlan;
+}
+/**
+ * Picks the chart for a multi-series table under `smart`: a plan, or `null`
+ * for no chart. A rejection falls back to the local guess.
+ */
+export type TableChartPlanner = (request: TableChartRequest) => Promise<ChartPlan | null>;
+/** A drawn chart, ready to resolve against the theme. */
+export interface TableChart {
+    /** SVG colored with figure tokens (`var(--accent)`, …). */
+    readonly svg: string;
+    readonly alt: string;
+    /** Size in SVG user units. */
+    readonly width: number;
+    readonly height: number;
+}
+/** The chart under a table: drawn, none, or a smart pick on its way (the promise settles once the cache holds it). */
+export type ChartLookup = TableChart | null | Promise<void>;
+/** One run of a Markdown block: prose (ending at a charted table), or the chart drawn after that table. */
+export type ChartSegment = {
+    readonly kind: "markdown";
+    readonly text: string;
+} | {
+    readonly kind: "chart";
+    readonly table: Tokens.Table;
+};
+/** Set how tables become charts (the host's `tui.autoGraph`) and its `smart` planner; the host rebuilds the transcript after. */
+export declare function setTableCharts(mode: TableChartMode, planner?: TableChartPlanner): void;
+/** How assistant tables currently become charts. */
+export declare function tableChartMode(): TableChartMode;
+/** Whether `markdown` may hold a table {@link splitTableCharts} would chart. */
+export declare function hasChartTable(markdown: string): boolean;
+/**
+ * Split `markdown` after each top-level table that has (or may get) a chart.
+ * A table still streaming at the block's tail is left whole: rows may follow.
+ */
+export declare function splitTableCharts(markdown: string, streaming: boolean): ChartSegment[];
+/**
+ * The chart for `table` under the current mode, read once per table source.
+ * Under `smart` the first lookup of a multi-series table asks the planner.
+ */
+export declare function lookupTableChart(table: Tokens.Table): ChartLookup;
+/**
+ * A native `image` node drawing `chart` from its SVG — no raster — resolved
+ * against the active theme; rebuilt when the theme changes.
+ */
+export declare function describeTableChart(chart: TableChart, key: string): NativeNode;
+export interface TableChartFigureOptions {
+    /** Shared inline-image budget. */
+    budget?: ImageBudget;
+    /** The chart's rows changed outside a text update: its pick or raster landed. */
+    onChange: () => void;
+}
+/**
+ * The chart under one table, as a terminal image a blank row below it. Looks
+ * the chart up on first render — a block rebuilt mid-stream never asks for a
+ * pick it drops — and renders nothing until it is drawn, or when the table
+ * gets no chart.
+ */
+export declare class TableChartFigure implements Component {
+    #private;
+    constructor(options: TableChartFigureOptions);
+    /** Point the figure at `table`. */
+    update(table: Tokens.Table): void;
+    /** Whether the chart is still being looked up, picked or drawn. */
+    get pending(): boolean;
+    render(width: number): readonly string[];
+    invalidate(): void;
+    dispose(): void;
+}

package/src/chat/table-chart.ts

@@ -0,0 +1,294 @@
+/**
+ * Charts drawn under numeric tables in assistant answers (the host's
+ * `tui.autoGraph`). {@link splitTableCharts} cuts a Markdown block after each
+ * top-level table that gets a chart; {@link lookupTableChart} plans, builds
+ * and draws that chart — locally under `always`, through the host's
+ * model-backed {@link TableChartPlanner} under `smart` for the tables
+ * {@link shouldJudge} picks — and caches it per table source. {@link TableChartFigure} shows it
+ * as a rasterized terminal image; {@link describeTableChart} hands a TSP
+ * terminal the SVG itself. Both resolve the figure tokens against the live
+ * theme, so a chart follows theme switches like the prose around it.
+ */
+import { logger } from "@linxiraos/pi-utils";
+import type { Token, Tokens } from "@linxiraos/pi-utils/marked";
+import { type ChartPlan, buildChart, planChart, shouldJudge, worthCharting } from "../charts/chart-plan";
+import { chartAlt, renderChartSvg } from "../charts/chart-svg";
+import { analyzeTable, type TableAnalysis } from "../charts/table-data";
+import type { ImageBudget } from "../components/image";
+import { lexDocument } from "../components/markdown";
+import { keyed } from "../native/describe";
+import { nativeImageNode } from "../native/blobs";
+import type { NativeNode } from "../native/node";
+import { getThemeEpoch } from "../theme";
+import type { Component } from "../tui";
+import { SvgFigure, svgFigurePalette } from "./svg-figure";
+import { prepareSvg } from "./svg-source";
+
+/**
+ * `smart`: a model refines the local guess where meaning decides (kind,
+ * columns, row names, ordering, polarity, focus, title; see {@link shouldJudge});
+ * `always`: the local best guess charts every table it reads as numeric;
+ * `off`: tables stay tables.
+ */
+export type TableChartMode = "smart" | "always" | "off";
+
+/** A table the host's planner picks a chart for ({@link shouldJudge}). */
+export interface TableChartRequest {
+	/** The table's Markdown source. */
+	readonly markdown: string;
+	readonly table: TableAnalysis;
+	/** The local best guess; the planner may keep it. */
+	readonly guess: ChartPlan;
+}
+
+/**
+ * Picks the chart for a multi-series table under `smart`: a plan, or `null`
+ * for no chart. A rejection falls back to the local guess.
+ */
+export type TableChartPlanner = (request: TableChartRequest) => Promise<ChartPlan | null>;
+
+/** A drawn chart, ready to resolve against the theme. */
+export interface TableChart {
+	/** SVG colored with figure tokens (`var(--accent)`, …). */
+	readonly svg: string;
+	readonly alt: string;
+	/** Size in SVG user units. */
+	readonly width: number;
+	readonly height: number;
+}
+
+/** The chart under a table: drawn, none, or a smart pick on its way (the promise settles once the cache holds it). */
+export type ChartLookup = TableChart | null | Promise<void>;
+
+/** One run of a Markdown block: prose (ending at a charted table), or the chart drawn after that table. */
+export type ChartSegment =
+	| { readonly kind: "markdown"; readonly text: string }
+	| { readonly kind: "chart"; readonly table: Tokens.Table };
+
+/** Tables cached per source; a long session keeps its recent charts without growing without bound. */
+const CACHE_LIMIT = 256;
+/** SVG user units per terminal column (16 per row on 1:2 cells), sizing native images. */
+const UNITS_PER_COLUMN = 8;
+/** A GFM delimiter row (`|---|:--:|`), the cheap test before lexing a block. */
+const DELIMITER_ROW = /^ {0,3}\|?[ \t]*:?-+:?[ \t]*\|/m;
+
+/** A table read once per source: its local guess and, once known, its chart. */
+interface ChartEntry {
+	readonly analysis: TableAnalysis;
+	readonly guess: ChartPlan | undefined;
+	/** The host's planner picks this table's chart. */
+	readonly smart: boolean;
+	/** `undefined` until drawn (or judged chartless). */
+	chart?: TableChart | null;
+	pending?: Promise<void>;
+}
+
+let chartMode: TableChartMode = "off";
+let chartPlanner: TableChartPlanner | undefined;
+const charts = new Map<string, ChartEntry>();
+/** The theme-resolved image node owning a chart's native bytes. */
+const kNativeImage = Symbol("tableChart.nativeImage");
+
+interface NativeTagged extends TableChart {
+	[kNativeImage]?: { epoch: number; image: NativeNode };
+}
+
+/** Set how tables become charts (the host's `tui.autoGraph`) and its `smart` planner; the host rebuilds the transcript after. */
+export function setTableCharts(mode: TableChartMode, planner?: TableChartPlanner): void {
+	chartMode = mode;
+	chartPlanner = planner;
+	charts.clear();
+}
+
+/** How assistant tables currently become charts. */
+export function tableChartMode(): TableChartMode {
+	return chartMode;
+}
+
+/** Whether `markdown` may hold a table {@link splitTableCharts} would chart. */
+export function hasChartTable(markdown: string): boolean {
+	return chartMode !== "off" && markdown.includes("|") && DELIMITER_ROW.test(markdown);
+}
+
+/**
+ * Split `markdown` after each top-level table that has (or may get) a chart.
+ * A table still streaming at the block's tail is left whole: rows may follow.
+ */
+export function splitTableCharts(markdown: string, streaming: boolean): ChartSegment[] {
+	if (chartMode === "off") return [{ kind: "markdown", text: markdown }];
+	const tokens = lexDocument(markdown);
+	const segments: ChartSegment[] = [];
+	let prose = "";
+	tokens.forEach((token, index) => {
+		prose += token.raw;
+		if (!isTable(token)) return;
+		const closed = !streaming || tokens.slice(index + 1).some(next => next.type !== "space");
+		const entry = closed ? chartEntry(token) : undefined;
+		if (!entry?.guess || entry.chart === null) return;
+		segments.push({ kind: "markdown", text: prose }, { kind: "chart", table: token });
+		prose = "";
+	});
+	if (prose.trim() || segments.length === 0) segments.push({ kind: "markdown", text: prose });
+	return segments;
+}
+
+function isTable(token: Token): token is Tokens.Table {
+	return token.type === "table";
+}
+
+/**
+ * The chart for `table` under the current mode, read once per table source.
+ * Under `smart` the first lookup of a multi-series table asks the planner.
+ */
+export function lookupTableChart(table: Tokens.Table): ChartLookup {
+	if (chartMode === "off") return null;
+	const entry = chartEntry(table);
+	if (entry.chart !== undefined) return entry.chart;
+	if (entry.pending) return entry.pending;
+	const { analysis, guess } = entry;
+	entry.pending = chartPlanner!({ markdown: table.raw, table: analysis, guess: guess! }).then(
+		plan => {
+			entry.chart = plan ? drawChart(analysis, plan) : null;
+		},
+		(error: unknown) => {
+			logger.debug("Smart table chart failed; drawing the local guess", { error: String(error) });
+			entry.chart = drawChart(analysis, guess!, true);
+		},
+	);
+	return entry.pending;
+}
+
+/**
+ * `table` read under the current mode, cached per source. A table the local
+ * guess decides is drawn at once; a smart pick waits for its first lookup.
+ */
+function chartEntry(table: Tokens.Table): ChartEntry {
+	const key = table.raw;
+	const cached = charts.get(key);
+	if (cached) {
+		// Re-insert so eviction drops the least recently read table.
+		charts.delete(key);
+		charts.set(key, cached);
+		return cached;
+	}
+	if (charts.size >= CACHE_LIMIT) charts.delete(charts.keys().next().value!);
+	const analysis = analyzeTable(
+		table.header.map(cell => cell.text),
+		table.rows.map(row => row.map(cell => cell.text)),
+	);
+	const guess = planChart(analysis);
+	const smart = chartMode === "smart" && chartPlanner !== undefined && shouldJudge(analysis, guess);
+	const entry: ChartEntry = { analysis, guess, smart };
+	if (!smart) entry.chart = guess ? drawChart(analysis, guess, true) : null;
+	charts.set(key, entry);
+	return entry;
+}
+
+/**
+ * Draw `plan`. A guess must also pass {@link worthCharting}; a model's pick
+ * already judged the chart worth drawing.
+ */
+function drawChart(analysis: TableAnalysis, plan: ChartPlan, guessed = false): TableChart | null {
+	const spec = buildChart(analysis, plan);
+	if (!spec || (guessed && !worthCharting(spec))) return null;
+	return { ...renderChartSvg(spec), alt: chartAlt(spec) };
+}
+
+/**
+ * A native `image` node drawing `chart` from its SVG — no raster — resolved
+ * against the active theme; rebuilt when the theme changes.
+ */
+export function describeTableChart(chart: TableChart, key: string): NativeNode {
+	const epoch = getThemeEpoch();
+	const tagged: NativeTagged = chart;
+	let entry = tagged[kNativeImage];
+	if (entry?.epoch !== epoch) {
+		const svg = prepareSvg(chart.svg, svgFigurePalette());
+		entry = {
+			epoch,
+			image: nativeImageNode(new TextEncoder().encode(svg), "image/svg+xml", {
+				alt: chart.alt,
+				w: chart.width,
+				h: chart.height,
+				max: { w: `${Math.round(chart.width / UNITS_PER_COLUMN)}ch` },
+			}),
+		};
+		tagged[kNativeImage] = entry;
+	}
+	return keyed(entry.image, key);
+}
+
+export interface TableChartFigureOptions {
+	/** Shared inline-image budget. */
+	budget?: ImageBudget;
+	/** The chart's rows changed outside a text update: its pick or raster landed. */
+	onChange: () => void;
+}
+
+/**
+ * The chart under one table, as a terminal image a blank row below it. Looks
+ * the chart up on first render — a block rebuilt mid-stream never asks for a
+ * pick it drops — and renders nothing until it is drawn, or when the table
+ * gets no chart.
+ */
+export class TableChartFigure implements Component {
+	readonly #options: TableChartFigureOptions;
+	readonly #figure: SvgFigure;
+	#table: Tokens.Table | undefined;
+	/** `undefined` while not looked up or waiting for a pick. */
+	#chart: TableChart | null | undefined;
+	#waiting = false;
+	#disposed = false;
+
+	constructor(options: TableChartFigureOptions) {
+		this.#options = options;
+		this.#figure = new SvgFigure({ budget: options.budget, onChange: options.onChange });
+	}
+
+	/** Point the figure at `table`. */
+	update(table: Tokens.Table): void {
+		if (table.raw === this.#table?.raw) return;
+		this.#table = table;
+		this.#chart = undefined;
+		this.#waiting = false;
+	}
+
+	/** Whether the chart is still being looked up, picked or drawn. */
+	get pending(): boolean {
+		return this.#table !== undefined && (this.#chart === undefined || (this.#chart !== null && this.#figure.pending));
+	}
+
+	render(width: number): readonly string[] {
+		if (this.#chart === undefined && !this.#waiting) this.#resolve();
+		if (!this.#chart) return [];
+		const rows = this.#figure.render(width);
+		return rows.length ? ["", ...rows] : rows;
+	}
+
+	invalidate(): void {
+		this.#figure.invalidate();
+	}
+
+	dispose(): void {
+		this.#disposed = true;
+		this.#figure.dispose();
+	}
+
+	#resolve(): void {
+		const table = this.#table;
+		if (!table) return;
+		const found = lookupTableChart(table);
+		if (found instanceof Promise) {
+			this.#waiting = true;
+			void found.then(() => {
+				if (this.#disposed || this.#table !== table) return;
+				this.#waiting = false;
+				this.#resolve();
+				this.#options.onChange();
+			});
+			return;
+		}
+		this.#chart = found;
+		if (found) this.#figure.update(found.svg, true);
+	}
+}

package/src/chat/tool-execution.d.ts

@@ -90,6 +90,8 @@ export declare class ToolExecutionComponent extends Container {
      * component-scoped so the TUI reuses every other root subtree (issue #4377).
      */
     tickSpinner(frame: number): void;
+    /** Whether the result's figure still waits for its raster; the transcript holds retirement meanwhile. */
+    isTranscriptBlockPending(): boolean;
     /**
      * Whether this block is ready to retire as immutable history. Partial
      * results, including detached background tasks, remain active and mutable

package/src/chat/tool-execution.ts

@@ -48,6 +48,7 @@ import {
 import type { XdevMountedState } from "../tools/xdev";
 import { isFramedBlockComponent, markFramedBlockComponent, renderStatusLine, WidthAwareText } from "../render/index";
 import { cachedPngConversion, convertImageToPngShared, imagePayloadKey } from "./image-loading";
+import { FenceFigure } from "./fence-figure";
 import { sanitizeWithOptionalSixelPassthrough } from "../render/sixel";
 import { renderDiff } from "../chrome/diff";
 import { type AnimationFrame, trimBlankEdges } from "../chrome/transcript-container";
@@ -110,10 +111,13 @@ function resolveEditModeForTool(toolName: string, tool: AgentTool | undefined):
 
 type ToolRendererStage = "call" | "result";
 
-/** A renderer's preview as the fallback card's clamp (`tail` becomes a head clamp of the same size). */
+/**
+ * A renderer's preview as the fallback card's clamp (`tail` becomes a head
+ * clamp of the same size; `children` leaves the clamping to the body's own previews).
+ */
 function cardPreview(preview: NativeToolView["preview"]): TspPreview | undefined {
 	if (preview === undefined) return { lines: DEFAULT_TERMINAL_PREVIEW_LINES };
-	if (preview === "none") return undefined;
+	if (preview === "none" || preview === "children") return undefined;
 	if (preview !== "auto" && "tail" in preview) return { lines: preview.tail };
 	return preview;
 }
@@ -169,6 +173,24 @@ class SafeToolRendererComponent implements Component {
 		invalidate.call(this.#component);
 	}
 
+	releaseRenderCaches(): void {
+		const release = this.#component.releaseRenderCaches;
+		if (release === undefined) return;
+		try {
+			release.call(this.#component);
+		} catch (err) {
+			if (!this.#warned) {
+				this.#warned = true;
+				logger.warn("Tool renderer failed", {
+					tool: this.#toolName,
+					stage: this.#stage,
+					phase: "releaseRenderCaches",
+					error: String(err),
+				});
+			}
+		}
+	}
+
 	setIgnoreTight(ignore: boolean): void {
 		const setIgnoreTight = this.#component.setIgnoreTight;
 		if (setIgnoreTight === undefined) return;
@@ -301,6 +323,8 @@ export class ToolExecutionComponent extends Container {
 	#multiFileBoxes: (Box | Spacer)[] = []; // Extra boxes for multi-file edit results
 	#imageComponents: Image[] = [];
 	#imageSpacers: Spacer[] = [];
+	/** The renderer's {@link ToolRenderer.figure} drawing; kept across rebuilds while its language is unchanged, so it redraws in place and its raster survives them. */
+	#figure: FenceFigure | undefined;
 	readonly #instanceId = ++toolExecutionInstanceSeq;
 	#toolName: string;
 	#toolLabel: string;
@@ -759,6 +783,11 @@ export class ToolExecutionComponent extends Container {
 		}
 	}
 
+	/** Whether the result's figure still waits for its raster; the transcript holds retirement meanwhile. */
+	isTranscriptBlockPending(): boolean {
+		return this.#toolActivityVisible && this.#figure?.pending === true;
+	}
+
 	/**
 	 * Whether this block is ready to retire as immutable history. Partial
 	 * results, including detached background tasks, remain active and mutable
@@ -941,11 +970,13 @@ export class ToolExecutionComponent extends Container {
 
 	/**
 	 * The native `collapsed` prop: the transcript's expand state, except that a
-	 * call streaming its body (edit, write) stays open until it settles, then
+	 * view that asks to be {@link NativeToolView.open} never starts folded, and
+	 * a call streaming its body (edit, write) stays open until it settles, then
 	 * folds like a finished thought. The user's own toggle still wins meanwhile:
 	 * the terminal keeps local collapse state until this prop changes.
 	 */
-	#nativeCollapsed(status: TspCardStatus): boolean {
+	#nativeCollapsed(status: TspCardStatus, view: NativeToolView): boolean {
+		if (view.open) return false;
 		const live = status === "pending" || status === "running";
 		return !this.#expanded && !(live && streamsBody(this.#toolName));
 	}
@@ -997,6 +1028,7 @@ export class ToolExecutionComponent extends Container {
 				target: head?.target,
 				targetKind: head?.targetKind,
 				lang: head?.lang,
+				command: head?.command,
 				href: head?.href,
 				meta: head?.meta,
 				badges: badges.length > 0 ? badges : undefined,
@@ -1008,7 +1040,7 @@ export class ToolExecutionComponent extends Container {
 				intent: typeof intent === "string" && intent ? plainText(intent) : undefined,
 				frame: inline ? "inline" : "card",
 				collapsible: hasBody,
-				collapsed: hasBody ? this.#nativeCollapsed(status) : undefined,
+				collapsed: hasBody ? this.#nativeCollapsed(status, view) : undefined,
 				preview: hasBody ? (preview === "auto" ? { lines: DEFAULT_TERMINAL_PREVIEW_LINES } : preview) : undefined,
 				tools: view.tools,
 				tone: view.tone,
@@ -1076,7 +1108,7 @@ export class ToolExecutionComponent extends Container {
 				tone: view.tone ?? NATIVE_STATUS_TONE[status],
 				status,
 				collapsible: hasBody,
-				collapsed: hasBody ? this.#nativeCollapsed(status) : undefined,
+				collapsed: hasBody ? this.#nativeCollapsed(status, view) : undefined,
 				preview: hasBody ? cardPreview(view.preview) : undefined,
 			},
 			children,
@@ -1096,11 +1128,14 @@ export class ToolExecutionComponent extends Container {
 	 * A renderer that throws falls back to the generic card.
 	 */
 	#nativeView(): NativeToolView {
+		const status = this.#nativeStatus();
 		const options: RenderResultContextOptions = {
 			expanded: this.#expanded,
 			isPartial: this.#isPartial,
 			argsComplete: this.#argsComplete,
 			executionStarted: this.#executionStarted,
+			elapsedMs: this.#elapsedMs(status),
+			cancelled: status === "cancelled",
 			renderContext: this.#buildRenderContext(),
 		};
 		// Custom tools (MCP, extensions) carry their own describe hooks, mirroring
@@ -1132,6 +1167,7 @@ export class ToolExecutionComponent extends Container {
 				body: [...(callView.body ?? []), ...(resultView.body ?? [])],
 				tone: resultView.tone ?? callView.tone,
 				preview: resultView.preview ?? callView.preview,
+				open: resultView.open ?? callView.open,
 				inline: resultView.inline ?? callView.inline,
 				tools: resultView.tools ?? callView.tools,
 			};
@@ -1611,6 +1647,7 @@ export class ToolExecutionComponent extends Container {
 			this.removeChild(spacer);
 		}
 		this.#imageSpacers = [];
+		this.#syncFigure();
 
 		if (this.#result) {
 			const imageBlocks = this.#getAllImageBlocks();
@@ -1639,7 +1676,12 @@ export class ToolExecutionComponent extends Container {
 						imageData,
 						imageMimeType,
 						{ fallbackColor: (s: string) => theme.fg("toolOutput", s) },
-						{ ...resolveImageOptions(), budget: this.#ui.imageBudget, imageKey: `te${this.#instanceId}:${i}` },
+						{
+							...resolveImageOptions(),
+							budget: this.#ui.imageBudget,
+							imageKey: `te${this.#instanceId}:${i}`,
+							requestRender: () => this.#ui.requestRender(),
+						},
 					);
 					this.#imageComponents.push(imageComponent);
 					this.addChild(imageComponent);
@@ -1649,6 +1691,43 @@ export class ToolExecutionComponent extends Container {
 		this.#renderedImageCount = this.#imageComponents.length;
 	}
 
+	/**
+	 * Mount the built-in renderer's figure under the card and feed it the fence
+	 * as it stands: the mounted one stays while its language is unchanged, so it
+	 * redraws in place as the args stream.
+	 */
+	#syncFigure(): void {
+		const result = this.#result;
+		const renderer = this.#tool?.renderCall || this.#tool?.renderResult ? undefined : this.#renderer;
+		const fence =
+			this.#isBenignSkip() || isNativeRendering()
+				? undefined
+				: renderer?.figure?.(
+						this.#args,
+						result && { content: result.content, details: result.details, isError: result.isError },
+						this.#renderState,
+					);
+		const drawable = fence !== undefined && FenceFigure.draws(fence, { showImages: this.#showImages });
+		let figure = this.#figure;
+		if (figure && (!drawable || figure.lang !== fence.lang)) {
+			this.removeChild(figure);
+			figure.dispose();
+			figure = this.#figure = undefined;
+		}
+		if (!drawable) return;
+		if (!figure) {
+			figure = this.#figure = new FenceFigure(fence.lang, {
+				budget: this.#ui.imageBudget,
+				onChange: () => {
+					this.#blockVersion++;
+					this.#ui.requestRender();
+				},
+			});
+			this.addChild(figure);
+		}
+		figure.update(fence);
+	}
+
 	#getCallArgsForRender(): unknown {
 		const renderArgs = this.#args;
 		if (!isEditLikeToolName(this.#toolName)) {

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

@@ -1,10 +1,11 @@
+import type { AnimationFrame, TranscriptPresentationTarget } from "../chrome/transcript-container";
 import { type Component, Container } from "../tui";
 import type { ImageContent } from "@linxiraos/pi-ai";
 import type { ReactionTarget } from "./reaction";
-import { type NativeNode, type NativeUiEvent } from "../native/node";
+import { type DescribeContext, type NativeNode, type NativeUiEvent } from "../native/node";
 /** How a user bubble styles its prose and chips (see {@link userBubbleColor}). */
 export interface UserBubbleOptions {
-    /** Materialized `file://` targets per attached image, indexed by chip number. */
+    /** Filesystem paths for attached image chips, indexed by chip number. */
     imageLinks?: readonly (string | undefined)[];
     /** The message's attached images in chip order (`#1` first); a native bubble shows them. */
     images?: readonly ImageContent[];
@@ -30,9 +31,10 @@ export declare function userBubbleColor(options?: UserBubbleOptions, tokenRegex?
  * (see {@link ReactionTarget}) drawn right-aligned in the bubble's top padding row;
  * a live-steered message carries a `*` marker left-aligned in the same row.
  */
-export declare class UserMessageComponent extends Container implements ReactionTarget {
+export declare class UserMessageComponent extends Container implements ReactionTarget, TranscriptPresentationTarget {
     #private;
     constructor(text: string, options?: UserBubbleOptions);
+    releaseRenderCaches(): void;
     setReaction(emoji: string): void;
     /**
      * A head-less user-toned frame with the prompt as markdown under its
@@ -42,9 +44,19 @@ export declare class UserMessageComponent extends Container implements ReactionT
      * agent's reaction are chips at the bottom-right, so a reaction landing
      * later updates the frame in place, even deep in scrollback.
      */
-    describe(): NativeNode;
+    describe(cx?: DescribeContext): NativeNode;
     /** Hover toolbar clicks: zeta's own copy and rewind commands. */
     handleNativeEvent(event: NativeUiEvent): void;
+    /** Apply the transcript allocator's current viewport reservation. */
+    setTranscriptAllocation(rows: number, _frame?: AnimationFrame): void;
+    isTranscriptBlockFinalized(): boolean;
+    /**
+     * Single-row emergency representation for the overflow transcript layout:
+     * renders the first content line instead of the blank top padding row, and
+     * omits OSC 133 shell integration markers so moving live blocks across the
+     * viewport does not leave stale prompt marks on lines it no longer occupies.
+     */
+    renderTranscriptBlockEmergencyRow(width: number): string | undefined;
     render(width: number): readonly string[];
 }
 /**
@@ -75,6 +87,7 @@ export declare class CollapsedSyntheticMessageComponent implements Component {
     handleNativeEvent(event: NativeUiEvent): void;
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
+    releaseRenderCaches(): void;
     dispose(): void;
     render(width: number): readonly string[];
 }