@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/tools/write.ts

@@ -1,5 +1,7 @@
+import * as path from "node:path";
 import type { HighlightStream } from "@linxiraos/pi-natives";
 import type { Component } from "../tui";
+import { fencedCode } from "../components/markdown";
 import { Text } from "../components/text";
 import { getLanguageFromPath } from "../lang-from-path";
 import { createHighlightStream, highlightCode, type Theme } from "../theme/theme";
@@ -31,8 +33,7 @@ import {
 	type ProcWriteDetails,
 } from "./proc-render";
 import type { TspTone } from "@linxiraos/pi-wire";
-import { code, compact, node, span } from "../native/describe";
-import { registerNativeBlob } from "../native/blobs";
+import { code, compact, md, node, span } from "../native/describe";
 import type { NativeChild, NativeNode } from "../native/node";
 import { diagnosticsBadge, diagnosticsSection, displayPath, errorText, fileHref, resultText } from "./native-view";
 import { describeCfgWrite, renderCfgWrite, type CfgWriteDetails } from "./cfg-render";
@@ -45,6 +46,7 @@ import type {
 	RenderResultOptions,
 	ToolActivityContext,
 	ToolActivitySummary,
+	ToolFigure,
 	ToolRenderer,
 } from "./renderer";
 import { splitUrlScheme } from "./url-scheme-host";
@@ -91,8 +93,31 @@ interface WriteRenderArgs {
 const WRITE_PREVIEW_LINES = 6;
 /** Collapsed native write body: the first lines of the file (§7.3). */
 const NATIVE_WRITE_PREVIEW = { lines: 8 } as const;
-/** Tallest rendered SVG preview, in lines; collapsed, the card shows just the picture. */
-const NATIVE_SVG_PREVIEW_LINES = 16;
+/**
+ * Collapsed clamp of a write drawn as a figure: Tern's model figure (its head
+ * over a 320px stage) clears the clamp's fade at 16px lines.
+ */
+const NATIVE_FIGURE_PREVIEW_LINES = 26;
+
+/**
+ * Fence language per extension of a written file that transcripts draw as a
+ * figure, as they draw that fence in assistant text: svg and mermaid, plus
+ * the 3D formats only Tern draws (stencil-markdown's model fences).
+ */
+const FIGURE_FENCES: Readonly<Record<string, string>> = {
+	svg: "svg",
+	mmd: "mermaid",
+	mermaid: "mermaid",
+	obj: "obj",
+	ply: "ply",
+	wrl: "wrl",
+	vrml: "vrml",
+	x3dv: "x3dv",
+	stl: "stl",
+	gltf: "gltf",
+	usda: "usda",
+	usd: "usd",
+};
 
 /** A write tool result as the renderer receives it. */
 interface WriteResult {
@@ -101,26 +126,46 @@ interface WriteResult {
 	isError?: boolean;
 }
 
-/** Cached SVG preview node on its result, so the content is encoded and hashed once per write. */
-const kSvgPreview = Symbol("write.svgPreview");
+/**
+ * The fence a file write draws as while its content streams and after: its
+ * extension names a figure language and it has content, closed once the args
+ * are final. None for URL-card writes, or after an error.
+ */
+function writeFigure(
+	args: WriteRenderArgs | undefined,
+	result: WriteResult | undefined,
+	options: RenderResultOptions,
+): ToolFigure | undefined {
+	if (result?.isError || result?.details?.xdev) return undefined;
+	const rawPath =
+		typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
+	const lang = FIGURE_FENCES[path.extname(rawPath).slice(1).toLowerCase()];
+	const content = args?.content;
+	if (!lang || typeof content !== "string" || !/\S/.test(content) || writeUrlCard(rawPath, result?.details)) {
+		return undefined;
+	}
+	return {
+		lang,
+		source: content.includes("\r") ? content.replace(/\r/g, "") : content,
+		closed: result !== undefined || options.argsComplete === true,
+	};
+}
 
-interface TaggedWriteResult extends WriteResult {
-	[kSvgPreview]?: { content: string; node: NativeNode };
+/**
+ * The `md` node drawing a figure write as its fence draws in a reply: open
+ * and streaming while the content arrives. A mermaid figure waits for the
+ * fence to close, as Tern shows an open one as code, which the source is.
+ */
+function describeFigure(figure: ToolFigure | undefined): NativeNode | undefined {
+	if (!figure || (figure.lang === "mermaid" && !figure.closed)) return undefined;
+	const text = fencedCode(figure.lang, figure.source, { open: !figure.closed });
+	return { ...md(text, { role: "zeta.tool.write.figure", stream: !figure.closed }), key: "figure" };
 }
 
-/** Native `image` node drawing written SVG `content`, cached on `result`. */
-function describeSvgPreview(result: TaggedWriteResult, content: string, alt: string): NativeNode {
-	const cached = result[kSvgPreview];
-	if (cached?.content === content) return cached.node;
-	const blob = registerNativeBlob(new TextEncoder().encode(content), "image/svg+xml");
-	const preview = node("image", {
-		blob,
-		alt,
-		role: "zeta.tool.write.image",
-		max: { h: `${NATIVE_SVG_PREVIEW_LINES}lines` },
-	});
-	result[kSvgPreview] = { content, node: preview };
-	return preview;
+/** The written content as numbered code, keyed so it keeps its node as the figure above it comes and goes. */
+function describeSource(rawPath: string, content: string): NativeNode {
+	const lang = rawPath ? getLanguageFromPath(rawPath) : undefined;
+	return { ...code(content, { lang, numbers: true }), key: "source" };
 }
 
 function countLines(text: string): number {
@@ -592,40 +637,49 @@ export const writeToolRenderer = {
 		// back to the normalizing stringify.
 		const content = typeof args.content === "string" ? args.content : normalizeDisplayText(args.content);
 		const streamingCache = createRenderedStringCache();
-		return framedToolCard(uiTheme, () => {
-			const body = content
-				? formatStreamingContent(
-						content,
-						Boolean(options?.expanded),
-						lang,
-						uiTheme,
-						options?.spinnerFrame,
-						streamingCache,
-						// `options` is the ToolExecutionComponent's persistent
-						// render-state object — a stable identity across reveal ticks
-						// that keys the incremental preview state. `argsComplete`
-						// flushes the trailing line through the highlighter once.
-						options,
-						options?.argsComplete,
-					)
-				: "";
-			const bodyLines = body ? body.split("\n") : [];
-			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
-			return {
-				header,
-				sections: bodyLines.length > 0 ? [{ content: bodyLines }] : [],
-				phase: "pending",
-				borderColor: "borderMuted",
-			};
-		});
+		return framedToolCard(
+			uiTheme,
+			() => {
+				const body = content
+					? formatStreamingContent(
+							content,
+							Boolean(options?.expanded),
+							lang,
+							uiTheme,
+							options?.spinnerFrame,
+							streamingCache,
+							// `options` is the ToolExecutionComponent's persistent
+							// render-state object — a stable identity across reveal ticks
+							// that keys the incremental preview state. `argsComplete`
+							// flushes the trailing line through the highlighter once.
+							options,
+							options?.argsComplete,
+						)
+					: "";
+				const bodyLines = body ? body.split("\n") : [];
+				while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
+				return {
+					header,
+					sections: bodyLines.length > 0 ? [{ content: bodyLines }] : [],
+					phase: "pending",
+					borderColor: "borderMuted",
+				};
+			},
+			// The highlighted body in `streamingCache` does not depend on width, and re-highlighting every committed
+			// card on each resize replay costs seconds; only the incremental highlighter state goes.
+			{ onReleaseRenderCaches: () => delete options?.[writeStreamingPreviewStateKey] },
+		);
 	},
 
 	renderResult(
 		result: WriteResult,
-		options: RenderResultOptions & { renderContext?: WriteRenderContext },
+		options: RenderResultOptions & WriteStreamingPreviewStateCarrier & { renderContext?: WriteRenderContext },
 		uiTheme: Theme,
 		args?: WriteRenderArgs,
 	): Component {
+		// Write merges call and result, so this builder runs once per display rebuild after the result arrives and the
+		// call card never renders again: its incremental highlighter state is dead from here on.
+		delete options[writeStreamingPreviewStateKey];
 		const cardPath =
 			typeof args?.path === "string" ? args.path : typeof args?.file_path === "string" ? args.file_path : "";
 		const routed = writeUrlCard(cardPath, result.details);
@@ -687,36 +741,41 @@ export const writeToolRenderer = {
 		const diagnostics = result.details?.diagnostics;
 
 		const previewCache = createRenderedStringCache();
-		return framedToolCard(uiTheme, () => {
-			const { expanded } = options;
-			let body = renderContentPreview(fileContent, expanded, lang, uiTheme, previewCache);
-			if (isPartial && progressText) {
-				const safeProgressText = truncateToWidth(
-					replaceTabs(progressText),
-					TRUNCATE_LENGTHS.LINE,
-					Ellipsis.Unicode,
-				);
-				body = `${uiTheme.fg("muted", safeProgressText)}${body ? `\n${body}` : ""}`;
-			}
-			if (!isPartial && diagnostics) {
-				const diagText = formatDiagnostics(diagnostics, expanded, uiTheme, fp =>
-					uiTheme.getLangIcon(getLanguageFromPath(fp)),
-				);
-				if (diagText.trim()) {
-					const diagLines = diagText.split("\n");
-					const firstNonEmpty = diagLines.findIndex(line => line.trim());
-					if (firstNonEmpty >= 0) body += `\n${diagLines.slice(firstNonEmpty).join("\n")}`;
+		return framedToolCard(
+			uiTheme,
+			() => {
+				const { expanded } = options;
+				let body = renderContentPreview(fileContent, expanded, lang, uiTheme, previewCache);
+				if (isPartial && progressText) {
+					const safeProgressText = truncateToWidth(
+						replaceTabs(progressText),
+						TRUNCATE_LENGTHS.LINE,
+						Ellipsis.Unicode,
+					);
+					body = `${uiTheme.fg("muted", safeProgressText)}${body ? `\n${body}` : ""}`;
 				}
-			}
-			const bodyLines = body.split("\n");
-			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
-			return {
-				header,
-				sections: bodyLines.length > 0 ? [{ content: bodyLines }] : [],
-				phase: isPartial ? "partial" : "success",
-				borderColor: "borderMuted",
-			};
-		});
+				if (!isPartial && diagnostics) {
+					const diagText = formatDiagnostics(diagnostics, expanded, uiTheme, fp =>
+						uiTheme.getLangIcon(getLanguageFromPath(fp)),
+					);
+					if (diagText.trim()) {
+						const diagLines = diagText.split("\n");
+						const firstNonEmpty = diagLines.findIndex(line => line.trim());
+						if (firstNonEmpty >= 0) body += `\n${diagLines.slice(firstNonEmpty).join("\n")}`;
+					}
+				}
+				const bodyLines = body.split("\n");
+				while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
+				return {
+					header,
+					sections: bodyLines.length > 0 ? [{ content: bodyLines }] : [],
+					phase: isPartial ? "partial" : "success",
+					borderColor: "borderMuted",
+				};
+			},
+			// No release hook: `previewCache` holds the width-independent highlighted preview, which resize replay
+			// would otherwise re-highlight for every committed card.
+		);
 	},
 	describeCall(
 		args: WriteRenderArgs,
@@ -739,17 +798,12 @@ export const writeToolRenderer = {
 			return describeXdevCall(xdev.name, args.content, options, options.renderContext?.resolveXdevMounted);
 		}
 		const content = normalizeDisplayText(args.content);
+		// A figure write draws as it arrives, over its streaming source.
+		const figure = writeFigure(args, undefined, options);
 		return {
 			tool: writeToolHead(rawPath, content),
-			body: content
-				? [
-						code(content, {
-							lang: rawPath ? getLanguageFromPath(rawPath) : undefined,
-							numbers: true,
-						}),
-					]
-				: [],
-			preview: NATIVE_WRITE_PREVIEW,
+			body: content ? compact([describeFigure(figure), describeSource(rawPath, content)]) : [],
+			preview: figure ? { lines: NATIVE_FIGURE_PREVIEW_LINES } : NATIVE_WRITE_PREVIEW,
 		};
 	},
 
@@ -776,22 +830,20 @@ export const writeToolRenderer = {
 		});
 		if (result.isError) return { tool, tone: "error", body: [errorText(resultText(result))] };
 		const progressText = resultText(result);
-		// A finished SVG write leads with the drawing; its source follows below the collapsed clamp.
-		const svg = !isPartial && fileContent.trim().length > 0 && rawPath.toLowerCase().endsWith(".svg");
+		// A figure write leads with the drawing, drawn as its fence in a reply;
+		// its source follows below the collapsed clamp.
+		const figure = writeFigure(args, result, options);
 		const body = compact<NativeChild>([
 			isPartial &&
 				progressText.length > 0 &&
 				node("text", { spans: [span(progressText, "muted")], truncate: "end" }),
-			svg && describeSvgPreview(result, fileContent, displayPath(rawPath)),
-			fileContent.length > 0 &&
-				code(fileContent, {
-					lang: rawPath ? getLanguageFromPath(rawPath) : undefined,
-					numbers: true,
-				}),
+			describeFigure(figure),
+			fileContent.length > 0 && describeSource(rawPath, fileContent),
 			diagnosticsSection(diagnostics),
 		]);
-		return { tool, body, preview: svg ? { lines: NATIVE_SVG_PREVIEW_LINES } : NATIVE_WRITE_PREVIEW };
+		return { tool, body, preview: figure ? { lines: NATIVE_FIGURE_PREVIEW_LINES } : NATIVE_WRITE_PREVIEW };
 	},
+	figure: writeFigure,
 	mergeCallAndResult: true,
 	// The collapsed pending preview follows the streaming edge with a tail
 	// window once the content outgrows it (`… (N earlier lines)` + last rows);

package/src/tools/yield.d.ts

@@ -0,0 +1,22 @@
+import type { Theme } from "../theme/theme";
+import type { Component } from "../tui";
+import type { NativeToolView, RenderResultContextOptions, RenderResultOptions, ToolRenderResult } from "./renderer";
+import type { YieldItem } from "./task";
+/** `yield` arguments as sent; strict-mode providers send omitted optionals as `null`. */
+interface YieldRenderArgs {
+    type?: string | string[] | null;
+    data?: unknown;
+    error?: string | null;
+    /** 1-based workpool item number. */
+    key?: number;
+}
+/** Shows a `yield` call's submitted data instead of its model-facing acknowledgement. */
+export declare const yieldToolRenderer: {
+    renderCall(args: YieldRenderArgs, options: RenderResultOptions, theme: Theme): Component;
+    renderResult(result: ToolRenderResult<YieldItem>, options: RenderResultContextOptions, theme: Theme, args?: YieldRenderArgs): Component;
+    describeCall(args: YieldRenderArgs, options: RenderResultOptions): NativeToolView;
+    describeResult(result: ToolRenderResult<YieldItem>, _options: RenderResultContextOptions, args?: YieldRenderArgs): NativeToolView;
+    mergeCallAndResult: true;
+    animatedPendingPreview: true;
+};
+export {};

package/src/tools/yield.ts

@@ -0,0 +1,225 @@
+/**
+ * Transcript renderer for the subagent `yield` tool ("Submit Result"). Its
+ * reply ("Result submitted.") is for the model; the card shows what was
+ * submitted: the section labels or workpool item in the head, the data as a
+ * JSON tree (Markdown when it is a string), and the reported or rejected error.
+ */
+import { formatCount, isRecord, sanitizeText } from "@linxiraos/pi-utils";
+import { compact, md } from "../native/describe";
+import { OwnerMemo } from "../native/memo";
+import type { NativeChild } from "../native/node";
+import { formatOutputPaneLines, styleToolOutputLine } from "../render/output-pane";
+import { formatExpandHint, sanitizeDisplayLines, truncateToWidth } from "../render/render-utils";
+import type { StatusLineOptions } from "../render/status-line";
+import { plainToolCard, type ToolCardPhase } from "../render/tool-card";
+import type { Theme } from "../theme/theme";
+import type { Component } from "../tui";
+import { wrapTextWithAnsi } from "../utils";
+import {
+	describeJsonTree,
+	JSON_TREE_MAX_DEPTH_COLLAPSED,
+	JSON_TREE_MAX_DEPTH_EXPANDED,
+	JSON_TREE_MAX_LINES_COLLAPSED,
+	JSON_TREE_MAX_LINES_EXPANDED,
+	JSON_TREE_SCALAR_LEN_COLLAPSED,
+	JSON_TREE_SCALAR_LEN_EXPANDED,
+	renderJsonTreeLines,
+} from "./json-tree";
+import { errorText, noteText, resultText } from "./native-view";
+import type {
+	NativeToolView,
+	RenderResultContextOptions,
+	RenderResultOptions,
+	ToolRenderer,
+	ToolRenderResult,
+} from "./renderer";
+import type { YieldItem } from "./task";
+
+const TITLE = "Submit Result";
+
+/** Collapsed rows of string data (a report) in the ANSI card. */
+const TEXT_ROWS_COLLAPSED = 4;
+
+/** `yield` arguments as sent; strict-mode providers send omitted optionals as `null`. */
+interface YieldRenderArgs {
+	type?: string | string[] | null;
+	data?: unknown;
+	error?: string | null;
+	/** 1-based workpool item number. */
+	key?: number;
+}
+
+/** One `yield` call as its card shows it, read from the args and, once settled, the result. */
+interface Submission {
+	/** Section labels or workpool item the call fills; absent for a whole result. */
+	target?: string;
+	/** The accepted (normalized) data once settled, else the data as sent. */
+	data: unknown;
+	/** The failure the call reports, or why the tool rejected it. */
+	error?: string;
+	settled: boolean;
+	/** Accepted although it failed the output schema. */
+	overridden: boolean;
+	/** Where a settled call without data takes its result from. */
+	note?: string;
+}
+
+function readSubmission(
+	args: YieldRenderArgs | undefined,
+	result: ToolRenderResult<YieldItem> | undefined,
+): Submission {
+	const details = result?.isError ? undefined : result?.details;
+	const type = details?.type ?? args?.type ?? undefined;
+	const incremental = Array.isArray(type) && type.length > 0;
+	const data = details?.data !== undefined ? details.data : (args?.data ?? undefined);
+	let error = args?.error || undefined;
+	if (result?.isError) error = resultText(result) || `${TITLE} failed`;
+	else if (result && details?.status === "aborted") error = details.error || resultText(result) || "Aborted";
+	const settled = result !== undefined;
+	return {
+		target: typeof args?.key === "number" ? `item ${args.key}` : incremental ? type.join(", ") : undefined,
+		data,
+		error,
+		settled,
+		overridden: details?.schemaOverridden === true,
+		note:
+			settled && error === undefined && data === undefined
+				? incremental
+					? "Takes the last message as this section"
+					: "Ends with the sections submitted earlier, or the last message"
+				: undefined,
+	};
+}
+
+/** Head fact for container data (`13 fields`, `4 items`). */
+function sizeMeta(data: unknown): string | undefined {
+	if (Array.isArray(data)) return formatCount("item", data.length);
+	if (isRecord(data)) return formatCount("field", Object.keys(data).length);
+	return undefined;
+}
+
+function describeData(data: unknown, streaming: boolean): NativeChild | undefined {
+	if (data === undefined) return undefined;
+	if (typeof data === "string") return data.trim() ? md(data, { stream: streaming }) : noteText("(empty)");
+	// Open to the depth cap: the data is the card's whole point, and the
+	// collapsed card's preview clamp already bounds what shows.
+	return describeJsonTree(data, { hiddenRootKeys: [], openDepth: JSON_TREE_MAX_DEPTH_EXPANDED });
+}
+
+function describeSubmission(s: Submission, streaming: boolean): NativeToolView {
+	const size = sizeMeta(s.data);
+	return {
+		tool: {
+			title: TITLE,
+			target: s.target,
+			targetKind: s.target ? "text" : undefined,
+			meta: size ? [size] : undefined,
+			badges: s.overridden ? [{ text: "schema overridden", tone: "warning" }] : undefined,
+		},
+		tone: s.settled && s.error !== undefined ? "error" : undefined,
+		body: compact([
+			s.error !== undefined ? errorText(s.error) : undefined,
+			describeData(s.data, streaming),
+			s.note ? noteText(s.note, "dim") : undefined,
+		]),
+	};
+}
+
+function dataLines(data: unknown, expanded: boolean, width: number, theme: Theme): string[] {
+	if (data === undefined) return [];
+	if (typeof data === "string") {
+		return [
+			...formatOutputPaneLines(
+				{
+					lines: sanitizeText(data).trimEnd().split("\n"),
+					expanded,
+					collapsedMaxLines: TEXT_ROWS_COLLAPSED,
+					styleLine: line => truncateToWidth(styleToolOutputLine(line, theme), width),
+				},
+				theme,
+			).lines,
+		];
+	}
+	const tree = renderJsonTreeLines(data, theme, {
+		maxDepth: expanded ? JSON_TREE_MAX_DEPTH_EXPANDED : JSON_TREE_MAX_DEPTH_COLLAPSED,
+		maxLines: expanded ? JSON_TREE_MAX_LINES_EXPANDED : JSON_TREE_MAX_LINES_COLLAPSED,
+		maxScalarLen: expanded ? JSON_TREE_SCALAR_LEN_EXPANDED : JSON_TREE_SCALAR_LEN_COLLAPSED,
+		sanitizeText,
+		hiddenRootKeys: [],
+	});
+	if (tree.truncated) tree.lines.push(expanded ? theme.fg("dim", "…") : formatExpandHint(theme, false, true));
+	return tree.lines;
+}
+
+function renderSubmission(s: Submission, options: RenderResultOptions, theme: Theme): Component {
+	// The body is spinner-invariant; rebuild it only on expansion or width change.
+	let memo: { expanded: boolean; width: number; lines: readonly string[] } | undefined;
+	return plainToolCard(
+		theme,
+		({ contentWidth }) => {
+			const running = options.spinnerFrame !== undefined;
+			const failed = s.settled && s.error !== undefined;
+			const size = sizeMeta(s.data);
+			const status: StatusLineOptions = {
+				icon: !s.settled ? (running ? "running" : "pending") : failed ? "error" : "done",
+				spinnerFrame: options.spinnerFrame,
+				title: TITLE,
+				description: s.target,
+				badge: s.overridden ? { label: "schema overridden", color: "warning" } : undefined,
+				meta: size ? [size] : undefined,
+			};
+			const phase: ToolCardPhase = !s.settled ? (running ? "running" : "partial") : failed ? "error" : "success";
+			if (memo === undefined || memo.expanded !== options.expanded || memo.width !== contentWidth) {
+				const lines: string[] = [];
+				// Wrapped in full: a schema rejection names every offending field.
+				if (s.error !== undefined) {
+					for (const line of sanitizeDisplayLines(s.error)) {
+						lines.push(...wrapTextWithAnsi(theme.fg("error", line), Math.max(1, contentWidth)));
+					}
+				}
+				lines.push(...dataLines(s.data, options.expanded, contentWidth, theme));
+				if (s.note) lines.push(theme.fg("dim", s.note));
+				memo = { expanded: options.expanded, width: contentWidth, lines };
+			}
+			return { status, phase, body: memo.lines };
+		},
+		{ paddingX: 1, paddingY: 1, ignoreTight: true, onInvalidate: () => (memo = undefined) },
+	);
+}
+
+const callMemo = new OwnerMemo<NativeToolView>();
+const resultMemo = new OwnerMemo<NativeToolView>();
+
+/** Shows a `yield` call's submitted data instead of its model-facing acknowledgement. */
+export const yieldToolRenderer = {
+	renderCall(args: YieldRenderArgs, options: RenderResultOptions, theme: Theme): Component {
+		return renderSubmission(readSubmission(args, undefined), options, theme);
+	},
+
+	renderResult(
+		result: ToolRenderResult<YieldItem>,
+		options: RenderResultContextOptions,
+		theme: Theme,
+		args?: YieldRenderArgs,
+	): Component {
+		return renderSubmission(readSubmission(args, result), options, theme);
+	},
+
+	describeCall(args: YieldRenderArgs, options: RenderResultOptions): NativeToolView {
+		const streaming = options.argsComplete === false;
+		return callMemo.get(args, [streaming], () => describeSubmission(readSubmission(args, undefined), streaming));
+	},
+
+	describeResult(
+		result: ToolRenderResult<YieldItem>,
+		_options: RenderResultContextOptions,
+		args?: YieldRenderArgs,
+	): NativeToolView {
+		return resultMemo.get(result.content, [args, result.details, result.isError], () =>
+			describeSubmission(readSubmission(args, result), false),
+		);
+	},
+
+	mergeCallAndResult: true,
+	animatedPendingPreview: true,
+} satisfies ToolRenderer<YieldRenderArgs, YieldItem>;

package/src/tui.d.ts

@@ -78,6 +78,10 @@ export interface TUIStartOptions {
      * Paint without owning stdin: the terminal stays in cooked mode (kernel
      * echo + line editing at the hardware cursor) until {@link TUI.enableInput}
      * switches to raw input and replays the kernel-buffered keystrokes.
+     *
+     * A terminal expected to speak TSP needs raw input from the start, so it
+     * gets it; its keystrokes are held instead (TSP events and the cell-size
+     * reply still apply) until {@link TUI.releaseHeldInput} replays them.
      */
     deferInput?: boolean;
 }
@@ -150,6 +154,11 @@ export interface Component {
     describeScreen?(cx: DescribeContext): NativeScreen;
     /** User actions on nodes this component described (toggle, select, activate, custom). */
     handleNativeEvent?(event: NativeUiEvent): void;
+    /**
+     * Pure preflight for focused input that must precede TUI-wide input listeners
+     * and debug shortcuts. A true result routes the event to this component first.
+     */
+    capturesInput?(data: string): boolean;
     /**
      * Optional handler for keyboard input when component has focus
      */
@@ -164,6 +173,16 @@ export interface Component {
      * Called when theme changes or when component needs to re-render from scratch.
      */
     invalidate?(): void;
+    /**
+     * Optional hook to drop memoized render output (rows, parse and wrap state)
+     * that the next `render()` can rebuild from state the component keeps.
+     * Unlike {@link invalidate}, it must not rebuild anything eagerly: no
+     * renderer or extension callbacks, no image conversions, and no child
+     * replacement or disposal. The next render must return the same rows it
+     * would have returned without the release. Components without it are
+     * simply not released.
+     */
+    releaseRenderCaches?(): void;
     /**
      * Optional hook to set whether this component ignores tight layout mode.
      */
@@ -303,6 +322,7 @@ export declare class Container implements Component {
     /** Dispose every child, then detach it from this container. */
     disposeChildren(): void;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /**
      * Propagate teardown to children. Call when the container's children are
      * being permanently discarded (not when they are detached for reuse — use
@@ -471,6 +491,22 @@ export declare class TUI extends Container {
      * path. Idempotent; no-op when input was never deferred.
      */
     enableInput(): void;
+    /**
+     * Replay the keystrokes held since a TSP `deferInput` start through the
+     * normal input path, then deliver input live. Call once the app's key
+     * handlers are installed so a hotkey pressed during startup still fires.
+     * Only keys typed while the start-time focus owner had focus are held. The
+     * hold survives a stop/start until released. Idempotent; no-op when nothing
+     * is held.
+     */
+    releaseHeldInput(): void;
+    /**
+     * Hand held-key ownership from `previous` to `next` when the app replaces
+     * the component focused at start (a swapped-in custom editor), so keys
+     * typed into the replacement stay queued behind the held ones instead of
+     * overtaking them. No-op unless `previous` owns the held keys.
+     */
+    replaceHeldFocus(previous: Component, next: Component): void;
     addStartListener(listener: StartListener): () => void;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;