@anthodev/pi-tools-style 0.1.3 → 0.2.0

package/src/config-menu.ts

@@ -0,0 +1,261 @@
+import { getSettingsListTheme, type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Container, SettingsList, Text, type SettingItem, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+
+import { getSettings, isShellEnabledByConfig, isToolEnabledByConfig } from "./settings.js";
+import type { IconMode } from "./tool-icon.js";
+import { getToolPresentationCatalog, isToolRendererEnabled, type ToolPresentationCatalogEntry } from "./tool-renderer.js";
+
+/**
+ * Change emitted by the config menu. The caller owns persistence and runtime effects; the menu only
+ * reports the row the user changed.
+ */
+export type ToolsStyleConfigChange =
+	| { readonly kind: "enabled"; readonly enabled: boolean }
+	| { readonly kind: "iconMode"; readonly iconMode: IconMode }
+	| { readonly kind: "shellEnabled"; readonly enabled: boolean }
+	| { readonly kind: "tool"; readonly name: string; readonly enabled: boolean };
+
+const ENABLED_ID = "global.enabled";
+const ICON_MODE_ID = "global.iconMode";
+const SHELL_ENABLED_ID = "global.shellEnabled";
+const TOOL_ID_PREFIX = "tool:";
+
+const ON = "on";
+const OFF = "off";
+const ICON_MODES = ["ascii", "nerd-font", "off"] as const;
+const NATIVE_RANK: Record<string, number> = {
+	bash: 0,
+	powershell: 1,
+	read: 2,
+	edit: 3,
+	write: 4,
+	find: 5,
+	grep: 6,
+	ls: 7,
+};
+const NATIVE_COUNT = Object.keys(NATIVE_RANK).length;
+
+const ENABLED_DESCRIPTION = "Renders tool calls with the tools-style presentation for this session.";
+const ICON_MODE_DESCRIPTION = "Icon set used in tool call titles.";
+const SHELL_ENABLED_DESCRIPTION = "Applies the tools-style presentation to direct shell command output.";
+const EXPOSED_NOTE = "Currently exposed by this session.";
+const OFFLINE_NOTE = "Not currently exposed; preference is retained for this exact name.";
+const CONDITIONAL_NOTE = "Applies when this tool uses a supported renderer; third-party self-renderers remain unchanged.";
+const EFFECTIVE_OFF_NOTE = "Global styling is off, so this preference takes effect only when global styling is on.";
+
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/g;
+const MAX_VISIBLE_ROWS = 15;
+const HEADER = "Tools style configuration";
+const HELPER = "Type to search. Enter or Space changes the selected value, Escape closes.";
+
+function iconModeOf(value: string): IconMode | undefined {
+	switch (value) {
+		case "ascii":
+		case "nerd-font":
+		case "off":
+			return value;
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Display-only sanitising: control characters would corrupt the terminal grid, and built-in search
+ * only reads the label. The row id and the emitted tool name always keep the exact identity.
+ */
+function displayName(name: string): string {
+	return name.replace(CONTROL_CHARACTERS, "");
+}
+
+/** Own-property lookup: reserved-looking names must never resolve inherited values. */
+function nativeRank(name: string): number | undefined {
+	return Object.hasOwn(NATIVE_RANK, name) ? NATIVE_RANK[name] : undefined;
+}
+
+/** Native tools first in their existing order, then every other exact name sorted deterministically. */
+function orderEntries(entries: readonly ToolPresentationCatalogEntry[]): readonly ToolPresentationCatalogEntry[] {
+	return [...entries].sort((a, b) => {
+		const left = nativeRank(a.name);
+		const right = nativeRank(b.name);
+		if (left !== undefined || right !== undefined) {
+			return (left ?? NATIVE_COUNT) - (right ?? NATIVE_COUNT);
+		}
+		return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+	});
+}
+
+function toolDescription(entry: ToolPresentationCatalogEntry, globalOff: boolean): string {
+	const parts = [entry.available ? EXPOSED_NOTE : OFFLINE_NOTE];
+	// Availability and support are independent dimensions: an offline identity is still conditional
+	// unless owned-row evidence confirmed its renderer.
+	if (entry.support === "conditional") {
+		parts.push(CONDITIONAL_NOTE);
+	}
+	if (globalOff) {
+		parts.push(EFFECTIVE_OFF_NOTE);
+	}
+	return parts.join(" ");
+}
+
+function toolItem(entry: ToolPresentationCatalogEntry, globalOff: boolean): SettingItem {
+	return {
+		id: `${TOOL_ID_PREFIX}${entry.name}`,
+		label: displayName(entry.name),
+		description: toolDescription(entry, globalOff),
+		currentValue: isToolEnabledByConfig(entry.name) ? ON : OFF,
+		values: [ON, OFF],
+	};
+}
+
+/**
+ * Row ids are exact and collision-safe: the global rows are matched before the fixed `tool:` prefix,
+ * and only that fixed prefix is ever stripped, so names containing colons stay intact.
+ */
+function changeOf(id: string, value: string): ToolsStyleConfigChange | undefined {
+	if (id === ENABLED_ID) {
+		return { kind: "enabled", enabled: value === ON };
+	}
+	if (id === SHELL_ENABLED_ID) {
+		return { kind: "shellEnabled", enabled: value === ON };
+	}
+	if (id === ICON_MODE_ID) {
+		const iconMode = iconModeOf(value);
+		return iconMode === undefined ? undefined : { kind: "iconMode", iconMode };
+	}
+	if (id.startsWith(TOOL_ID_PREFIX)) {
+		return { kind: "tool", name: id.slice(TOOL_ID_PREFIX.length), enabled: value === ON };
+	}
+	return undefined;
+}
+
+export function openToolsStyleConfig(
+	pi: Pick<ExtensionAPI, "getAllTools">,
+	context: ExtensionCommandContext,
+	onChange: (change: ToolsStyleConfigChange) => Promise<void>,
+): Promise<void> {
+	if (context.mode !== "tui") {
+		return Promise.resolve();
+	}
+	return context.ui.custom<void>((tui, theme, _keybindings, done) => {
+		// The catalog is evaluated once per opening, so a later opening sees newly discovered tools.
+		const entries = orderEntries(getToolPresentationCatalog(pi.getAllTools()));
+		const globalOff = !isToolRendererEnabled();
+		const toolRows = entries.map((entry) => ({ entry, item: toolItem(entry, globalOff) }));
+		const items: SettingItem[] = [
+			{
+				id: ENABLED_ID,
+				label: "Tools style rendering",
+				description: ENABLED_DESCRIPTION,
+				// Raw runtime state for this session, not the saved preference.
+				currentValue: isToolRendererEnabled() ? ON : OFF,
+				values: [ON, OFF],
+			},
+			{
+				id: ICON_MODE_ID,
+				label: "Icon mode",
+				description: ICON_MODE_DESCRIPTION,
+				currentValue: getSettings().iconMode,
+				values: [...ICON_MODES],
+			},
+			{
+				id: SHELL_ENABLED_ID,
+				label: "Shell commands (!/!!)",
+				description: SHELL_ENABLED_DESCRIPTION,
+				currentValue: isShellEnabledByConfig() ? ON : OFF,
+				values: [ON, OFF],
+			},
+			...toolRows.map((row) => row.item),
+		];
+
+		let closed = false;
+		const close = (): void => {
+			if (closed) {
+				return;
+			}
+			closed = true;
+			done(undefined);
+		};
+
+		const reportFailure = (): void => {
+			try {
+				context.ui.notify("Tools style: that change could not be saved", "warning");
+			} catch {
+				// Best-effort warning; the caller's promise already reports the failure.
+			}
+		};
+
+		/** Keeps every tool row's gate disclosure in step with the applied global choice. */
+		const refreshGateDisclosure = (enabled: boolean): void => {
+			const off = !enabled;
+			for (const row of toolRows) {
+				row.item.description = toolDescription(row.entry, off);
+			}
+		};
+
+		const emit = (id: string, newValue: string): void => {
+			const change = changeOf(id, newValue);
+			if (change === undefined) {
+				return;
+			}
+			if (change.kind === "enabled") {
+				// The row value and its disclosure move together, without rebuilding the menu.
+				refreshGateDisclosure(change.enabled);
+			}
+			let pending: Promise<void>;
+			try {
+				pending = onChange(change);
+			} catch {
+				reportFailure();
+				return;
+			}
+			void pending.then(undefined, reportFailure);
+		};
+
+		const settingsList = new SettingsList(
+			items,
+			Math.min(items.length + 2, MAX_VISIBLE_ROWS),
+			getSettingsListTheme(),
+			emit,
+			close,
+			{ enableSearch: true },
+		);
+
+		const container = new Container();
+		container.addChild(new Text(theme.fg("accent", HEADER), 1, 0));
+		container.addChild(new Text(theme.fg("dim", HELPER), 1, 0));
+		container.addChild(settingsList);
+
+		return {
+			render(width: number): string[] {
+				return container.render(width);
+			},
+			invalidate(): void {
+				container.invalidate();
+			},
+			// Every key byte is delegated to the SDK component, which owns search and value cycling.
+			handleInput(data: string): void {
+				if (closed) {
+					return;
+				}
+				settingsList.handleInput(data);
+				if (!closed) {
+					tui.requestRender();
+				}
+			},
+			handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+				if (closed) {
+					return undefined;
+				}
+				const result = container.handleMouse(event);
+				if (!closed) {
+					tui.requestRender();
+				}
+				return result;
+			},
+			dispose(): void {
+				// Writes stay detached: settlements must not repaint or mutate this disposed component.
+				closed = true;
+			},
+		};
+	});
+}

package/src/frame.ts

@@ -1,120 +1,313 @@
+import { keyHint, type Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
 import {
-	stripTerminalSequences,
+	Container,
+	Text,
 	truncateToWidth,
 	visibleWidth,
+	wrapTextWithAnsi,
+	type Component,
 } from "@earendil-works/pi-tui";
+import { getIconMode } from "./settings.js";
+import { formatToolTitle } from "./tool-icon.js";
+import { getToolSpinnerFrame, toolSpinnerFrame } from "./tool-spinner.js";
+import type { EntryLinesComponent, ToolSection, ToolSnapshot, ToolView } from "./tool-presentation.js";
+import type { ToolChildBounds, ToolLayout } from "./tool-renderer.js";
 
 const RESET = "\u001b[0m";
 const DEFAULT_PADDING = 1;
-const MINIMUM_FRAME_WIDTH = 5;
-const HORIZONTAL_RULE = /^[─━═╌╍┄┅┈┉-]+$/u;
 const TERMINAL_IMAGE_SEQUENCES = [
 	"\u001b_G", // Kitty graphics protocol
 	"\u001b]1337;File=", // iTerm2 inline images
-	"\u001bPq", // Sixel device control string
-	"\u0090q", // Eight-bit Sixel device control string
 ] as const;
+const SIXEL_SEQUENCE = /(?:\u001bP|\u0090)[0-9;]*q/u;
+// SDK wrapping can retain a grapheme wider than its width. These are the branches
+// that can exceed the usual one/two-cell base width in Pi's graphemeWidth.
+const DEFENSIVE_PADDED_ROW = /[\t\r\n\p{Mark}\uFF00-\uFFEF\u0E33\u0EB3]/u;
+const TEXT_RENDER = Text.prototype.render;
+const TEXT_INVALIDATE = Text.prototype.invalidate;
+const CONTAINER_RENDER = Container.prototype.render;
+const CONTAINER_INVALIDATE = Container.prototype.invalidate;
+const CONTAINER_HANDLE_MOUSE = Container.prototype.handleMouse;
 
-export interface FrameOptions {
-	horizontalPadding?: number;
-	styleBorder?: (value: string) => string;
-	title?: string;
-}
-
-export function frameContentWidth(
-	width: number,
-	horizontalPadding = DEFAULT_PADDING,
-): number {
-	const padding = normalizePadding(horizontalPadding);
-	return Math.max(0, Math.floor(width) - 2 - padding * 2);
-}
-
-export function frameLines(
-	sourceLines: readonly string[],
-	width: number,
-	options: FrameOptions = {},
-): string[] {
-	const lines = [...sourceLines];
-	const outerWidth = Math.floor(width);
-	const padding = normalizePadding(options.horizontalPadding);
-
-	if (
-		lines.length === 0 ||
-		outerWidth < MINIMUM_FRAME_WIDTH ||
-		containsTerminalImage(lines)
-	) {
-		return lines;
-	}
-
-	const contentWidth = frameContentWidth(outerWidth, padding);
-	if (contentWidth < 1) return lines;
-
-	const styleBorder = options.styleBorder ?? identity;
-	const horizontalPadding = " ".repeat(padding);
-	const top = renderTopBorder(outerWidth, options.title, styleBorder);
-	const bottom = styleBorder(`╰${"─".repeat(outerWidth - 2)}╯`);
-	const body = lines.map((line) => {
-		const content = truncateToWidth(line, contentWidth, "");
-		const remaining = Math.max(0, contentWidth - visibleWidth(content));
-
-		const reset = content.includes("\u001b") ? RESET : "";
-		return `${styleBorder("│")}${horizontalPadding}${content}${reset}${" ".repeat(
-			remaining,
-		)}${horizontalPadding}${styleBorder("│")}`;
-	});
-
-	return [top, ...body, bottom];
-}
 
 export function containsTerminalImage(lines: readonly string[]): boolean {
 	return lines.some((line) =>
-		TERMINAL_IMAGE_SEQUENCES.some((sequence) => line.includes(sequence)),
+		TERMINAL_IMAGE_SEQUENCES.some((sequence) => line.includes(sequence))
+			|| SIXEL_SEQUENCE.test(line),
 	);
 }
 
-export function trimOuterRules(sourceLines: readonly string[]): string[] {
-	const lines = [...sourceLines];
-
-	const firstRuleIndex =
-		lines.length > 1 &&
-		stripTerminalSequences(lines[0] ?? "").trim() === "" &&
-		isHorizontalRule(lines[1] ?? "")
-			? 1
-			: 0;
-	const lastRuleIndex = lines.length - 1;
+/** Public Container handlers only forward; opaque or overridden handlers own interaction. */
+export function isInteractiveToolComponent(component: Component): boolean {
+	if (typeof component.handleInput === "function") return true;
+	if (component instanceof Container && component.handleMouse === CONTAINER_HANDLE_MOUSE) {
+		return component.children.some(isInteractiveToolComponent);
+	}
+	return typeof component.handleMouse === "function";
+}
 
-	if (
-		firstRuleIndex < lastRuleIndex &&
-		isHorizontalRule(lines[firstRuleIndex] ?? "") &&
-		isHorizontalRule(lines[lastRuleIndex] ?? "")
-	) {
-		return lines.slice(firstRuleIndex + 1, lastRuleIndex);
+/** Only public static bodies can skip a generic renderer's ordinary clock invalidation. */
+export function hasStableToolBody(component: Component): boolean {
+	if (component instanceof Text) {
+		return component.render === TEXT_RENDER && component.invalidate === TEXT_INVALIDATE;
 	}
+	if (component instanceof Container) {
+		return component.render === CONTAINER_RENDER && component.invalidate === CONTAINER_INVALIDATE
+			&& component.children.every(hasStableToolBody);
+	}
+	return false;
+}
 
-	return lines;
+interface RenderedSection {
+	section: ToolSection;
+	rows: readonly string[];
 }
 
-function renderTopBorder(
+/**
+ * Compose a single semantic card and assign intact sections to the two Pi slots.
+ * Interaction routing belongs to ToolPresentation; bounds retain the real children.
+ */
+export function layoutToolView(
+	view: ToolView,
+	snapshot: ToolSnapshot,
+	theme: Theme,
 	width: number,
-	rawTitle: string | undefined,
-	styleBorder: (value: string) => string,
-): string {
-	const title = normalizeTitle(rawTitle);
-	const maxTitleWidth = Math.max(0, width - 6);
-
-	if (!title || maxTitleWidth < 1) {
-		return styleBorder(`╭${"─".repeat(width - 2)}╮`);
+	spinnerFrameIndex?: number,
+): ToolLayout {
+	const outerWidth = Math.max(1, Math.floor(width));
+	const framed = view.layout === "framed";
+	const padding = framed
+		? normalizePadding(snapshot.context.outputPad)
+		: Math.min(normalizePadding(snapshot.context.outputPad), Math.floor((outerWidth - 1) / 2));
+	const childWidth = Math.max(1, outerWidth - (framed ? 2 : 0) - 2 * padding);
+	const rendered = new Map<Component, readonly string[]>();
+	const sections: RenderedSection[] = [];
+	// Rendering is done before decoration or previews: an image escapes the entire card.
+	for (const section of view.sections) {
+		let childRows = rendered.get(section.component);
+		if (!childRows) {
+			childRows = section.component.render(childWidth);
+			rendered.set(section.component, childRows);
+		}
+		sections.push({ section, rows: childRows });
+	}
+	const layout: ToolLayout = {
+		callRows: [],
+		resultRows: [],
+		callChildBounds: [],
+		resultChildBounds: [],
+		callOffset: 0,
+		resultOffset: 0,
+	};
+	const callBounds: ToolChildBounds[] = [];
+	const resultBounds: ToolChildBounds[] = [];
+	layout.callChildBounds = callBounds;
+	layout.resultChildBounds = resultBounds;
+	const hasResult = snapshot.result !== undefined;
+	if (sections.some(({ rows }) => containsTerminalImage(rows))) {
+		for (const slot of ["call", "result"] as const) {
+			const output = slot === "call" || !hasResult ? layout.callRows : layout.resultRows;
+			const bounds = slot === "call" || !hasResult ? callBounds : resultBounds;
+			for (const entry of sections) {
+				if (entry.section.slot !== slot || entry.rows.length === 0) continue;
+				bounds.push({ component: entry.section.component, x: 0, y: output.length, width: childWidth, height: entry.rows.length });
+				output.push(...entry.rows);
+			}
+		}
+		layout.resultOffset = layout.callRows.length;
+		return layout;
 	}
 
-	const visibleTitle = truncateToWidth(title, maxTitleWidth, "");
-	const prefix = `╭─ ${visibleTitle} `;
-	const fill = "─".repeat(Math.max(1, width - visibleWidth(prefix) - 1));
-	return `${styleBorder(prefix)}${styleBorder(fill)}${styleBorder("╮")}`;
+	const borderColor: ThemeColor = view.tone === "error" || view.head.status === "error"
+		? "error"
+		: view.tone === "warning" || view.head.status === "cancelled"
+			? "warning"
+			: view.head.status === "pending" || view.head.status === "running"
+				? "accent"
+				: "borderMuted";
+	const background = theme.getBgAnsi(borderColor === "error" ? "toolErrorBg"
+		: view.head.status === "pending" || view.head.status === "running" ? "toolPendingBg" : "toolSuccessBg");
+	const paint = (line: string) => {
+		if (!background) return line;
+		// Reapply the card background after any SGR resetting it, including compound SGRs.
+		const stabilized = line.replace(/\u001b\[([0-9;]*)m/gu, (sequence: string, parameters: string) => {
+			const codes = parameters.split(";");
+			for (let index = 0; index < codes.length; index++) {
+				const code = codes[index];
+				if (code === "" || code === "0" || code === "49") return sequence + background;
+				// RGB/palette channels may contain 0 or 49 without being SGR resets.
+				if (code === "38" || code === "48" || code === "58") {
+					index += codes[index + 1] === "2" ? 4 : codes[index + 1] === "5" ? 2 : 0;
+				}
+			}
+			return sequence;
+		});
+		return background + stabilized + "\u001b[49m";
+	};
+	const border = (text: string) => theme.fg(borderColor, text);
+	const capWidth = Math.min(3, Math.max(0, outerWidth - 2));
+	const cap = "─".repeat(capWidth);
+	const barBudget = Math.max(0, outerWidth - capWidth - 4);
+	const bar = (left: string, right: string, label: string) => {
+		const text = barBudget > 0 && label ? ` ${truncateToWidth(label, barBudget, "…")} ` : "";
+		const fill = "─".repeat(Math.max(0, outerWidth - 2 - capWidth - visibleWidth(text)));
+		return paint(border(left + cap) + text + border(fill + right));
+	};
+	const pad = " ".repeat(padding);
+	const body = (line: string, padded = false) => {
+		// Children own their ANSI text. Close styles/links only outside their content.
+		const reset = line.includes("\u001b") ? "\u001b]8;;\u001b\\" + RESET : "";
+		const fill = padded ? "" : " ".repeat(Math.max(0, childWidth - visibleWidth(line)));
+		return paint(framed
+			? border("│") + pad + line + reset + fill + pad + border("│")
+			: pad + line + reset + fill + pad);
+	};
+	const headerWidth = Math.max(0, outerWidth - (framed ? Math.min(3, outerWidth - 2) + 4 : 2 * padding));
+	const header = semanticHeader(view, snapshot, theme, borderColor, headerWidth, spinnerFrameIndex);
+	let headerText = header.text;
+	let serializeHeader: (text: string) => string;
+	if (framed) {
+		headerText = barBudget > 0 ? truncateToWidth(headerText, barBudget, "…") : "";
+		const gap = headerText ? " " : "";
+		const fill = "─".repeat(Math.max(0, outerWidth - 2 - capWidth - header.width - 2 * gap.length));
+		const left = border("╭" + cap) + gap;
+		const right = gap + border(fill + "╮");
+		serializeHeader = (text) => paint(left + text + right);
+	} else {
+		const reset = headerText.includes("\u001b") ? "\u001b]8;;\u001b\\" + RESET : "";
+		const right = reset + " ".repeat(Math.max(0, childWidth - header.width)) + pad;
+		serializeHeader = (text) => paint(pad + text + right);
+	}
+	const preparedHeader = serializeHeader(headerText);
+	layout.callRows.push(preparedHeader);
+	if (!view.sections.some(({ component }) => isInteractiveToolComponent(component)
+		|| (snapshot.presentation === "generic" && !hasStableToolBody(component)))) {
+		const refreshText = header.refreshText;
+		layout.refreshHeader = refreshText
+			? (frameIndex) => { layout.callRows[0] = serializeHeader(refreshText(frameIndex)); }
+			: () => { layout.callRows[0] = preparedHeader; };
+	}
+	for (const slot of ["call", "result"] as const) {
+		const output = slot === "call" || !hasResult ? layout.callRows : layout.resultRows;
+		const bounds = slot === "call" || !hasResult ? callBounds : resultBounds;
+		for (const entry of sections) {
+			if (entry.section.slot !== slot || entry.rows.length === 0) continue;
+			const interactive = isInteractiveToolComponent(entry.section.component);
+			let content: readonly string[] = entry.rows;
+			let padded = entry.section.renderedWidth === "padded" && !interactive;
+			let hidden = 0;
+			const preview = !view.expanded && entry.section.preview !== false && !interactive
+				? entry.section.previewPolicy ?? view.preview : undefined;
+			if (preview?.unit === "entries") {
+				padded = false;
+				const entries = (entry.section.component as Partial<EntryLinesComponent>).entryLines;
+				if (!entries) throw new Error("Entry previews require logical entryLines");
+				const count = Math.max(0, Math.floor(preview.count));
+				hidden = Math.max(0, entries.length - count);
+				const selected = preview.edge === "tail" ? entries.slice(hidden) : entries.slice(0, count);
+				content = selected.flatMap((line) => wrapTextWithAnsi(line, childWidth));
+			} else if (!interactive) {
+				if (padded) {
+					let wrapped: string[] | undefined;
+					for (let index = 0; index < entry.rows.length; index++) {
+						const line = entry.rows[index]!;
+						if ((childWidth < 2 || DEFENSIVE_PADDED_ROW.test(line))
+							&& (visibleWidth(line) > childWidth || line.includes("\n"))) {
+							wrapped ??= entry.rows.slice(0, index);
+							wrapped.push(...wrapTextWithAnsi(line, childWidth));
+						} else {
+							wrapped?.push(line);
+						}
+					}
+					if (wrapped) {
+						content = wrapped;
+						padded = false;
+					}
+				} else {
+					content = entry.rows.flatMap((line) => visibleWidth(line) > childWidth || line.includes("\n")
+						? wrapTextWithAnsi(line, childWidth) : [line]);
+				}
+				if (preview) {
+					const count = Math.max(0, Math.floor(preview.count));
+					hidden = Math.max(0, content.length - count);
+					content = preview.edge === "tail" ? content.slice(hidden) : content.slice(0, count);
+				}
+			}
+			if (content.length === 0 && hidden === 0) continue;
+			// The semantic Input/Command label stays on the call section for producers and tests;
+			// the rendered card shows the supplied body directly, with no Input or Command divider.
+			const labelText = slot === "call" && (entry.section.label === "Input" || entry.section.label === "Command")
+				? undefined
+				: entry.section.label;
+			if (labelText) {
+				const label = theme.fg("muted", labelText);
+				output.push(framed ? bar("├", "┤", label) : body(truncateToWidth(label, childWidth, "…")));
+			}
+			if (content.length > 0) {
+				bounds.push({ component: entry.section.component, x: padding + (framed ? 1 : 0), y: output.length, width: childWidth, height: content.length });
+				for (const line of content) output.push(body(line, padded));
+			}
+			if (hidden > 0) {
+				const unit = preview?.unit === "entries" ? "entries" : "lines";
+				const hint = theme.fg("dim", `… ${hidden} more ${unit} ${keyHint("app.tools.expand", "to expand")}`);
+				for (const line of wrapTextWithAnsi(hint, childWidth)) output.push(body(line));
+			}
+		}
+	}
+	if (framed) {
+		(hasResult ? layout.resultRows : layout.callRows).push(paint(border(`╰${"─".repeat(Math.max(0, outerWidth - 2))}╯`)));
+	}
+	layout.resultOffset = layout.callRows.length;
+	return layout;
 }
 
-function isHorizontalRule(line: string): boolean {
-	const visible = stripTerminalSequences(line).trim();
-	return visible.length > 0 && HORIZONTAL_RULE.test(visible);
+function semanticHeader(view: ToolView, snapshot: ToolSnapshot, theme: Theme, color: ThemeColor, width: number, spinnerFrameIndex?: number) {
+	const mode = getIconMode();
+	const status = view.head.status;
+	// The shell adapter supplies its native-loader clock; public tools isolate per render-context state.
+	const runningSymbol = (frameIndex?: number) => frameIndex === undefined
+		? toolSpinnerFrame(snapshot.context.state, mode) : getToolSpinnerFrame(mode, frameIndex);
+	const symbol = mode === "off" ? status
+		: status === "running" ? runningSymbol(spinnerFrameIndex)
+			: status === "pending" ? mode === "nerd-font" ? "○" : "?"
+				: status === "done" ? mode === "nerd-font" ? "✓" : "ok"
+					: status === "error" ? mode === "nerd-font" ? "✗" : "!"
+						: mode === "nerd-font" ? "⊘" : "-";
+	const duration = view.head.durationMs;
+	const final = status === "done" || status === "error" || status === "cancelled";
+	const state = theme.fg(color, symbol);
+	const timing = final && duration !== undefined && Number.isFinite(duration) && duration >= 0
+		? theme.fg("dim", duration < 1000 ? `${Math.round(duration)}ms` : `${(duration / 1000).toFixed(1)}s`) : "";
+	const ending = [state, timing].filter(Boolean).join(" · ");
+	const endingWidth = visibleWidth(ending);
+	const target = view.head.target;
+	// Reserve room for the callable identity even when title or metadata competes with it.
+	const targetReserve = target ? Math.min(16, Math.floor(width / 3)) : 0;
+	const titleBudget = Math.max(0, width - endingWidth - 3 - targetReserve - (targetReserve ? 1 : 0));
+	const title = theme.bold(theme.fg("toolTitle", truncateToWidth(formatToolTitle(view.head.title, mode), titleBudget, "…")));
+	const metaBudget = Math.max(0, width - visibleWidth(title) - endingWidth - 6 - targetReserve - (targetReserve ? 1 : 0));
+	const rawMeta = view.head.meta.filter(Boolean).join(" · ");
+	const meta = metaBudget > 0 && rawMeta ? theme.fg("dim", truncateToWidth(rawMeta, metaBudget, "…")) : "";
+	const fixed = [title, meta, ending].filter(Boolean).join(" · ");
+	const targetBudget = Math.max(0, width - visibleWidth(fixed) - 1);
+	const multiline = target.includes("\n") || target.includes("\r");
+	const summary = target.split(/\r?\n/u)[0] ?? "";
+	const visibleTarget = targetBudget > 0 && target
+		? theme.fg("toolOutput", truncateToWidth(summary + (multiline ? " …" : ""), targetBudget, "…")) : "";
+	const first = [title, visibleTarget].filter(Boolean).join(" ");
+	const prefix = [first, meta].filter(Boolean).join(" · ");
+	const beforeState = prefix ? prefix + " · " : "";
+	const rawText = beforeState + ending;
+	const text = truncateToWidth(rawText, width, "…");
+	return {
+		text,
+		width: visibleWidth(text),
+		// A running glyph is the last visible cell. If truncation removed it, the
+		// prepared header is static; otherwise its one-cell budget never changes.
+		...(status === "running" && mode !== "off" && visibleWidth(rawText) <= width
+			? { refreshText: (frameIndex?: number) => beforeState + theme.fg(color, runningSymbol(frameIndex)) }
+			: {}),
+	};
 }
 
 function normalizePadding(value: number | undefined): number {
@@ -122,11 +315,3 @@ function normalizePadding(value: number | undefined): number {
 	return Math.max(0, Math.floor(value));
 }
 
-function normalizeTitle(value: string | undefined): string {
-	if (!value) return "";
-	return stripTerminalSequences(value).replace(/\s+/gu, " ").trim();
-}
-
-function identity(value: string): string {
-	return value;
-}