@quandev104/pi-style 0.1.1

package/extension-src/pi-style/shared/box.ts

@@ -0,0 +1,805 @@
+// Boxed tool-call/result rendering primitives.
+//
+// Two deliberate design points:
+//
+// 1. Background painting is removed. Boxed lines are foreground-only; the
+//    enclosing native ToolExecutionComponent container applies the semantic
+//    status background (toolPendingBg / toolErrorBg / toolSuccessBg), and the
+//    message-block Box applies customMessageBg. This avoids double-background
+//    conflicts and keeps pi-style's patches renderer-scoped.
+//
+// 2. Theme functions are accessed through a minimal structural interface
+//    (BoxTheme) instead of `any`.
+
+import { homedir } from "node:os";
+import { relative, resolve } from "node:path";
+import type { Component } from "@earendil-works/pi-tui";
+import { fgHex, isHexColor, stripAnsi } from "./ansi.js";
+import { formatToolMetrics, getElapsedMs, type MetricResultLike } from "./elapsed.js";
+import {
+	boxedResultRenderBudget,
+	clampRenderLine,
+	DEFAULT_COLLAPSED_RENDER_LINES,
+	fastBoxLineContent,
+	safeTruncateToWidth,
+	safeVisibleWidth,
+	safeWrapTextWithAnsi,
+} from "./render-budget.js";
+import { getThemeExtra } from "./theme-extras.js";
+
+/** Minimal structural view of Pi's Theme as used by the boxed renderers. */
+export interface BoxTheme {
+	fg(color: string, text: string): string;
+	bold?(text: string): string;
+	italic?(text: string): string;
+	inverse?(text: string): string;
+	getColorMode?(): string;
+}
+
+export interface BoxedRenderOptions {
+	widthKey?: string;
+	isError?: boolean;
+	isPartial?: boolean;
+	isPending?: boolean;
+	pendingText?: string;
+	state?: Record<string, unknown>;
+	/** Wall-clock elapsed override (used when metrics are not in result.details). */
+	elapsedMs?: number;
+}
+
+export function isExpanded(options: { expanded?: boolean } | undefined): boolean {
+	return typeof options?.expanded === "boolean" ? options.expanded : false;
+}
+
+export function shortenPath(path: string): string {
+	const home = homedir();
+	if (path.startsWith(home)) return `~${path.slice(home.length)}`;
+	return path;
+}
+
+export function resolveAbsolutePath(rawPath: string, cwd: string): string {
+	const path = rawPath.trim();
+	if (!path) return "";
+
+	const home = process.env.HOME;
+	if (home && (path === "~" || path.startsWith("~/"))) {
+		return path === "~" ? home : resolve(home, path.slice(2));
+	}
+
+	return resolve(cwd, path);
+}
+
+export function resolveRelativePath(rawPath: string, cwd: string): string {
+	const absPath = resolveAbsolutePath(rawPath, cwd);
+	if (!absPath) return "(unknown)";
+	const relPath = relative(cwd, absPath).replace(/\\/g, "/");
+	return relPath || ".";
+}
+
+export function replaceTabs(text: string): string {
+	return text.replace(/\t/g, "   ");
+}
+
+export function getTextOutput(result: MetricResultLike | undefined): string {
+	if (!result?.content) return "";
+	const textBlocks = result.content.filter((contentBlock) => {
+		if (!contentBlock || typeof contentBlock !== "object") return false;
+		return (contentBlock as { type?: unknown }).type === "text";
+	});
+	return textBlocks
+		.map((contentBlock) => String((contentBlock as { text?: unknown }).text ?? ""))
+		.join("\n")
+		.replace(/\r/g, "");
+}
+
+export function stripTrailingNotice(text: string): string {
+	const normalized = (text ?? "").replace(/\r/g, "").trimEnd();
+	if (!normalized) return "";
+	if (normalized.startsWith("[") && normalized.endsWith("]")) return "";
+	const noticeStart = normalized.lastIndexOf("\n\n[");
+	if (noticeStart >= 0 && normalized.endsWith("]")) {
+		return normalized.slice(0, noticeStart).trimEnd();
+	}
+	return normalized;
+}
+
+export function extractTrailingNotice(text: string): string | null {
+	const normalized = (text ?? "").replace(/\r/g, "").trimEnd();
+	if (!normalized) return null;
+	if (normalized.startsWith("[") && normalized.endsWith("]")) return normalized;
+	const noticeStart = normalized.lastIndexOf("\n\n[");
+	if (noticeStart >= 0 && normalized.endsWith("]")) {
+		return normalized.slice(noticeStart + 2).trimEnd();
+	}
+	return null;
+}
+
+export function countLines(text: string): number {
+	const normalized = (text ?? "").replace(/\r/g, "").replace(/\n+$/g, "");
+	if (!normalized) return 0;
+	return normalized.split("\n").length;
+}
+
+export function countWords(text: string): number {
+	let count = 0;
+	let inWord = false;
+	for (const char of text) {
+		const isWord = /[\p{L}\p{N}_'-]/u.test(char);
+		if (isWord && !inWord) count++;
+		inWord = isWord;
+	}
+	return count;
+}
+
+function formatCompactCount(value: number): string {
+	if (value < 1000) return `${Math.round(value)}`;
+	if (value < 10000) return `${(value / 1000).toFixed(1)}k`;
+	if (value < 1000000) return `${Math.round(value / 1000)}k`;
+	if (value < 10000000) return `${(value / 1000000).toFixed(1)}M`;
+	return `${Math.round(value / 1000000)}M`;
+}
+
+export function formatBoxedWords(text: string): string {
+	return `✎ ~${formatCompactCount(countWords(text))} words`;
+}
+
+export function badge(theme: BoxTheme, label: string): string {
+	const tagBg = getThemeExtra(theme, "tagBgColor");
+	if (tagBg && isHexColor(tagBg)) {
+		return theme.inverse
+			? theme.inverse(fgHex(theme, tagBg, theme.bold ? theme.bold(` ${label} `) : ` ${label} `))
+			: fgHex(theme, tagBg, theme.bold ? theme.bold(` ${label} `) : ` ${label} `);
+	}
+	return theme.inverse ? theme.inverse(theme.bold ? theme.bold(` ${label} `) : ` ${label} `) : ` ${label} `;
+}
+
+export function parens(theme: BoxTheme, text: string, skipTextColor?: boolean): string {
+	const bracketColor = getThemeExtra(theme, "parensBracketColor");
+	const openParen = bracketColor && isHexColor(bracketColor) ? fgHex(theme, bracketColor, "(") : "(";
+	const closeParen = bracketColor && isHexColor(bracketColor) ? fgHex(theme, bracketColor, ")") : ")";
+	let innerBase: string;
+	if (skipTextColor) {
+		innerBase = text;
+	} else {
+		const textColor = getThemeExtra(theme, "parensTextColor");
+		innerBase = textColor && isHexColor(textColor) ? fgHex(theme, textColor, text) : text;
+	}
+	const inner = typeof theme?.bold === "function" ? theme.bold(innerBase) : `\x1b[1m${innerBase}\x1b[22m`;
+	return `${openParen}${inner}${closeParen}`;
+}
+
+const BOX_HORIZONTAL = "─";
+const BOX_VERTICAL = "│";
+const BOX_SIDE_PADDING = 2;
+const BOX_MIN_WIDTH = 12;
+const BOX_WIDTH_CACHE = new Map<string, number>();
+const COMPACT_TOOL_NAME_WIDTH = safeVisibleWidth("Search");
+const COMPACT_FOOTER_ELAPSED_WIDTH = 8;
+const COMPACT_FOOTER_EXTRA_WIDTH = 8;
+const COMPACT_FOOTER_WORDS_WIDTH = safeVisibleWidth("✎ ~1.2k words");
+
+export function boxWidth(width: number): number {
+	return Math.max(BOX_MIN_WIDTH, width);
+}
+
+export function boxInnerWidth(width: number): number {
+	return Math.max(1, boxWidth(width) - 2 - BOX_SIDE_PADDING * 2);
+}
+
+function _tightBoxWidth(
+	availableWidth: number,
+	contentLines: string[],
+	labelWidths: number[] = [],
+	widthKey?: string,
+): number {
+	const contentWidth = contentLines.reduce((max, line) => Math.max(max, safeVisibleWidth(line)), 0);
+	const labelWidth = labelWidths.reduce((max, width) => Math.max(max, width), 0);
+	const neededWidth = Math.max(
+		BOX_MIN_WIDTH,
+		contentWidth + 2 + BOX_SIDE_PADDING * 2,
+		labelWidth + 2 + BOX_SIDE_PADDING * 2,
+	);
+	const measuredWidth = Math.min(boxWidth(availableWidth), neededWidth);
+	if (!widthKey) return measuredWidth;
+	const cachedWidth = BOX_WIDTH_CACHE.get(widthKey) ?? 0;
+	const nextWidth = Math.min(boxWidth(availableWidth), Math.max(cachedWidth, measuredWidth));
+	BOX_WIDTH_CACHE.set(widthKey, nextWidth);
+	return nextWidth;
+}
+
+export function boxedToolWidthKey(toolName: string, detail: string): string {
+	return `${toolName}:${detail}`;
+}
+
+export function formatToolName(toolName: string): string {
+	const spaced = toolName
+		.replace(/[_-]+/g, " ")
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+		.trim();
+	return spaced.replace(/\b\w/g, (char) => char.toUpperCase()) || toolName;
+}
+
+function formatToolParamName(name: string): string {
+	const spaced = name
+		.replace(/[_-]+/g, " ")
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+		.trim();
+	return spaced ? spaced[0]?.toUpperCase() + spaced.slice(1) : name;
+}
+
+const MAX_PARAM_VALUE_LENGTH = 120;
+
+function formatOperationSummary(value: unknown): string | undefined {
+	if (!Array.isArray(value) || value.length === 0) return undefined;
+	if (!value.every((item) => item && typeof item === "object" && !Array.isArray(item))) return undefined;
+	const types = Array.from(new Set(value.map((item) => String((item as { type?: unknown }).type ?? "operation"))));
+	const typeSummary =
+		types.length === 1
+			? ` (${types[0]})`
+			: types.length > 1
+				? ` (${types.slice(0, 3).join(", ")}${types.length > 3 ? ", …" : ""})`
+				: "";
+	return `${value.length} ${value.length === 1 ? "operation" : "operations"}${typeSummary}`;
+}
+
+function formatToolParamValue(value: unknown): string {
+	if (value === undefined) return "";
+	if (value === null) return "null";
+	if (typeof value === "string") {
+		if (value.length <= MAX_PARAM_VALUE_LENGTH) return value;
+		return `${value.slice(0, MAX_PARAM_VALUE_LENGTH)}…`;
+	}
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		return formatOperationSummary(value) ?? `${value.length} ${value.length === 1 ? "item" : "items"}`;
+	}
+	if (typeof value === "object" && value !== null) {
+		const keys = Object.keys(value);
+		if (keys.length === 0) return "{}";
+		return `{${keys.length} ${keys.length === 1 ? "key" : "keys"}}`;
+	}
+	try {
+		const json = JSON.stringify(value);
+		if (json.length <= MAX_PARAM_VALUE_LENGTH) return json;
+		return `${json.slice(0, MAX_PARAM_VALUE_LENGTH)}…`;
+	} catch {
+		return String(value);
+	}
+}
+
+export function formatToolParamLines(args: unknown, theme?: BoxTheme): string[] {
+	if (args === undefined || args === null) return [];
+	if (typeof args !== "object" || Array.isArray(args)) {
+		const value = formatToolParamValue(args);
+		return value ? [`Params: ${value}`] : [];
+	}
+
+	const entries = Object.entries(args as Record<string, unknown>).filter(([, value]) => value !== undefined);
+	if (entries.length === 0) return [];
+
+	const lines: string[] = [];
+	for (const [key, value] of entries) {
+		const formattedValue = formatToolParamValue(value);
+		if (!formattedValue) continue;
+		const [firstLine = "", ...restLines] = formattedValue.replace(/\r/g, "").split("\n");
+		const keyLabel = formatToolParamName(key);
+		if (theme) {
+			lines.push(`${theme.fg("dim", `${keyLabel}:`)} ${theme.fg("text", firstLine)}`);
+			lines.push(...restLines.map((line) => `  ${theme.fg("text", line)}`));
+		} else {
+			lines.push(`${keyLabel}: ${firstLine}`);
+			lines.push(...restLines.map((line) => `  ${line}`));
+		}
+	}
+	return lines;
+}
+
+const RESET_INTENSITY = "\x1b[22m";
+
+function colorFromExtra(theme: BoxTheme, extraKey: string, fallbackColor: string, text: string): string {
+	const color = getThemeExtra(theme, extraKey);
+	if (color) {
+		if (isHexColor(color)) return fgHex(theme, color, text);
+		try {
+			return theme.fg(color, text);
+		} catch {
+			// Fall back to semantic theme color below.
+		}
+	}
+	return theme.fg(fallbackColor, text);
+}
+
+function formatBoxedStatusIcon(theme: BoxTheme, isError?: boolean): string {
+	const icon = isError ? "✗" : "✓";
+	return theme.fg(isError ? "error" : "success", icon);
+}
+
+export function formatBoxedToolTitle(theme: BoxTheme, name: string, isError?: boolean): string {
+	const rawTitle = `➔ ${name}`;
+	const coloredTitle = `${colorFromExtra(theme, "bashPromptColor", "bashMode", rawTitle)} ${formatBoxedStatusIcon(theme, isError)}`;
+	const title = typeof theme?.bold === "function" ? theme.bold(coloredTitle) : coloredTitle;
+	return `${title} ${boxText(theme, "|")}`;
+}
+
+function formatCompactBoxedToolTitle(theme: BoxTheme, name: string, isError?: boolean): string {
+	const paddedName = padVisibleRight(name, COMPACT_TOOL_NAME_WIDTH);
+	const rawTitle = `➔ ${paddedName}`;
+	const coloredTitle = `${colorFromExtra(theme, "bashPromptColor", "bashMode", rawTitle)} ${formatBoxedStatusIcon(theme, isError)}`;
+	const title = typeof theme?.bold === "function" ? theme.bold(coloredTitle) : coloredTitle;
+	return `${title} ${boxText(theme, "|")}`;
+}
+
+function boxText(theme: BoxTheme, text: string): string {
+	return `${RESET_INTENSITY}${theme.fg("borderMuted", text)}`;
+}
+function boxFrameText(theme: BoxTheme, text: string): string {
+	return `${RESET_INTENSITY}${theme.fg("border", text)}`;
+}
+
+export function boxedToolBgName(isError?: boolean, isPartial?: boolean): string {
+	return isPartial ? "toolPendingBg" : isError ? "toolErrorBg" : "toolSuccessBg";
+}
+
+export function boxBorder(theme: BoxTheme, left: string, right: string, width: number): string {
+	const renderedWidth = boxWidth(width);
+	const innerWidth = renderedWidth - 2;
+	return boxFrameText(theme, `${left}${BOX_HORIZONTAL.repeat(innerWidth)}${right}`);
+}
+
+function padVisibleRight(text: string, width: number): string {
+	return `${text}${" ".repeat(Math.max(0, width - safeVisibleWidth(text)))}`;
+}
+
+export function boxLineWithRight(theme: BoxTheme, left: string, right: string, width: number): string {
+	const renderedWidth = boxWidth(width);
+	const contentWidth = boxInnerWidth(renderedWidth);
+	const divider = ` ${boxText(theme, "|")} `;
+	const dividerWidth = safeVisibleWidth(divider);
+	const rightWidth = safeVisibleWidth(right);
+	const sidePad = " ".repeat(BOX_SIDE_PADDING);
+
+	if (!right || rightWidth + dividerWidth >= contentWidth) {
+		return boxLine(theme, right || left, renderedWidth);
+	}
+
+	const maxLeftWidth = Math.max(1, contentWidth - dividerWidth - rightWidth - 1);
+	const truncatedLeft = safeTruncateToWidth(left, maxLeftWidth, "…");
+	const gap = " ".repeat(Math.max(1, contentWidth - safeVisibleWidth(truncatedLeft) - dividerWidth - rightWidth));
+	return `${boxFrameText(theme, BOX_VERTICAL)}${sidePad}${truncatedLeft}${gap}${divider}${right}${sidePad}${boxFrameText(theme, BOX_VERTICAL)}`;
+}
+
+export function boxLine(theme: BoxTheme, content: string, width: number): string {
+	const renderedWidth = boxWidth(width);
+	const contentWidth = boxInnerWidth(renderedWidth);
+	const fastContent = fastBoxLineContent(content, contentWidth);
+	const sidePad = " ".repeat(BOX_SIDE_PADDING);
+	if (fastContent) {
+		const fill = " ".repeat(Math.max(0, contentWidth - fastContent.visibleWidth));
+		return `${boxFrameText(theme, BOX_VERTICAL)}${sidePad}${fastContent.text}${fill}${sidePad}${boxFrameText(theme, BOX_VERTICAL)}`;
+	}
+
+	const truncated = safeTruncateToWidth(content, contentWidth, "…");
+	const fill = " ".repeat(Math.max(0, contentWidth - safeVisibleWidth(truncated)));
+	return `${boxFrameText(theme, BOX_VERTICAL)}${sidePad}${truncated}${fill}${sidePad}${boxFrameText(theme, BOX_VERTICAL)}`;
+}
+
+export function boxInsetDivider(theme: BoxTheme, width: number): string {
+	const renderedWidth = boxWidth(width);
+	const lineWidth = boxInnerWidth(renderedWidth);
+	const sidePad = " ".repeat(BOX_SIDE_PADDING);
+	return `${boxFrameText(theme, BOX_VERTICAL)}${sidePad}${boxText(theme, BOX_HORIZONTAL.repeat(lineWidth))}${sidePad}${boxFrameText(theme, BOX_VERTICAL)}`;
+}
+
+export function boxedWrappedLines(theme: BoxTheme, content: string, width: number): string[] {
+	return safeWrapTextWithAnsi(content, boxInnerWidth(width)).map((line) => boxLine(theme, line, width));
+}
+
+function boxedTruncatedLine(theme: BoxTheme, content: string, width: number): string {
+	return boxLine(theme, safeTruncateToWidth(content, boxInnerWidth(width), "…"), width);
+}
+
+type RenderLinesCache = {
+	width: number;
+	lines: string[];
+};
+
+function pushBoundedLines(target: string[], lines: string[], maxLines: number): boolean {
+	const slots = maxLines - target.length;
+	if (slots <= 0) return false;
+	if (lines.length > slots) {
+		target.push(...lines.slice(0, slots));
+		return false;
+	}
+	target.push(...lines);
+	return true;
+}
+
+function renderBoxedOutputLines(
+	theme: BoxTheme,
+	outputLines: string[],
+	width: number,
+	rawLineBudget = DEFAULT_COLLAPSED_RENDER_LINES,
+): string[] {
+	const budget = boxedResultRenderBudget(rawLineBudget);
+	const headLimit = Math.max(0, Math.min(budget.headLines, budget.maxRenderedLines));
+	const tailLimit = Math.max(0, Math.min(budget.tailLines, Math.max(0, budget.maxRenderedLines - headLimit - 1)));
+	const head: string[] = [];
+	let nextInputIndex = 0;
+	let truncated = false;
+
+	for (; nextInputIndex < outputLines.length; nextInputIndex++) {
+		const line = boxedTruncatedLine(theme, outputLines[nextInputIndex] ?? "", width);
+		if (!pushBoundedLines(head, [line], headLimit)) {
+			truncated = true;
+			nextInputIndex++;
+			break;
+		}
+	}
+
+	if (!truncated && nextInputIndex >= outputLines.length) return head;
+
+	const tail: string[] = [];
+	const tailStart = Math.max(nextInputIndex, outputLines.length - tailLimit);
+	for (let i = tailStart; i < outputLines.length; i++) {
+		const line = boxedTruncatedLine(theme, outputLines[i] ?? "", width);
+		tail.push(line);
+		if (tail.length > tailLimit) tail.splice(0, tail.length - tailLimit);
+	}
+
+	const skippedInputLines = Math.max(0, tailStart - nextInputIndex);
+	const skippedText =
+		skippedInputLines > 0
+			? `… rendered output truncated; ${skippedInputLines} input lines skipped before tail`
+			: "… rendered output truncated";
+	return [...head, boxLine(theme, theme.fg("muted", skippedText), width), ...tail];
+}
+
+export function renderBoxedToolCall(
+	theme: BoxTheme,
+	toolName: string,
+	detailLines: string[],
+	options: BoxedRenderOptions = {},
+): Component {
+	let cache: RenderLinesCache | null = null;
+	return {
+		invalidate() {
+			cache = null;
+		},
+		render(width: number): string[] {
+			if (cache?.width === width) return cache.lines;
+			const title = formatBoxedToolTitle(theme, toolName, options.isError);
+			const renderedWidth = boxWidth(width);
+			const lines = [
+				boxBorder(theme, "┌", "┐", renderedWidth),
+				boxLine(theme, title, renderedWidth),
+				boxInsetDivider(theme, renderedWidth),
+				...detailLines.flatMap((line) => boxedWrappedLines(theme, line, renderedWidth)),
+			];
+			if (options.isPending) {
+				const pendingText = options.pendingText ?? "Waiting for output…";
+				lines.push(
+					boxInsetDivider(theme, renderedWidth),
+					...boxedWrappedLines(theme, `${theme.fg("muted", "…")} ${theme.fg("dim", pendingText)}`, renderedWidth),
+					boxBorder(theme, "└", "┘", renderedWidth),
+				);
+			}
+			cache = { width, lines };
+			return lines;
+		},
+	};
+}
+
+const COMPACT_FOOTER_KEY = "__piStyleCompactFooter";
+const COMPACT_FOOTER_ERROR_KEY = "__piStyleCompactFooterError";
+const COMPACT_FOOTER_PARTIAL_KEY = "__piStyleCompactFooterPartial";
+
+export function clearCompactBoxedFooter(state: Record<string, unknown> | undefined): void {
+	if (!state || typeof state !== "object") return;
+	delete state[COMPACT_FOOTER_KEY];
+	delete state[COMPACT_FOOTER_ERROR_KEY];
+	delete state[COMPACT_FOOTER_PARTIAL_KEY];
+}
+
+export function renderCompactBoxedToolCall(
+	theme: BoxTheme,
+	toolName: string,
+	detailLine: string,
+	options: BoxedRenderOptions = {},
+): Component {
+	return {
+		invalidate() {},
+		render(width: number): string[] {
+			const renderedWidth = boxWidth(width);
+			const title = `${formatCompactBoxedToolTitle(theme, toolName, options.isError)} ${detailLine}`;
+			const compactFooter =
+				typeof options.state?.[COMPACT_FOOTER_KEY] === "string" ? options.state[COMPACT_FOOTER_KEY] : "";
+			const _footerIsError = Boolean(options.state?.[COMPACT_FOOTER_ERROR_KEY]);
+			const _footerIsPartial = Boolean(options.state?.[COMPACT_FOOTER_PARTIAL_KEY]);
+			if (compactFooter) {
+				return [
+					boxBorder(theme, "┌", "┐", renderedWidth),
+					boxLineWithRight(theme, title, compactFooter, renderedWidth),
+					boxBorder(theme, "└", "┘", renderedWidth),
+				];
+			}
+
+			const lines = [boxBorder(theme, "┌", "┐", renderedWidth), boxLine(theme, title, renderedWidth)];
+			if (options.isPending) {
+				const pendingText = options.pendingText ?? "Waiting for output…";
+				lines.push(
+					boxInsetDivider(theme, renderedWidth),
+					...boxedWrappedLines(theme, `${theme.fg("muted", "…")} ${theme.fg("dim", pendingText)}`, renderedWidth),
+					boxBorder(theme, "└", "┘", renderedWidth),
+				);
+			}
+			return lines;
+		},
+	};
+}
+
+type BoxedResultBody = Component | ((contentWidth: number) => string[]);
+
+export function renderBoxedToolResult(
+	theme: BoxTheme,
+	body: BoxedResultBody,
+	options: {
+		outputLabel?: string;
+		footerLines?: string[];
+		emptyText?: string;
+		widthKey?: string;
+		referenceLines?: string[];
+		renderLineBudget?: number;
+		isError?: boolean;
+		isPartial?: boolean;
+	} = {},
+): Component {
+	let cache: RenderLinesCache | null = null;
+	return {
+		invalidate() {
+			cache = null;
+			if (typeof body !== "function") body.invalidate();
+		},
+		render(width: number): string[] {
+			if (cache?.width === width) return cache.lines;
+			const renderedWidth = boxWidth(width);
+			const maxContentWidth = boxInnerWidth(renderedWidth);
+			const bodyLines = typeof body === "function" ? body(maxContentWidth) : body.render(maxContentWidth);
+			const errorPrefix = options.isError ? [theme.fg("error", "✗ Error")] : [];
+			const outputLines =
+				bodyLines.length > 0
+					? [...errorPrefix, ...bodyLines]
+					: [theme.fg("muted", `∅ ${options.emptyText ?? "(no output)"}`)];
+			const footerLines = options.footerLines ?? [];
+			const renderedFooterLines =
+				footerLines.length > 0
+					? [boxInsetDivider(theme, renderedWidth), ...footerLines.map((line) => boxLine(theme, line, renderedWidth))]
+					: [];
+			const rendered = [
+				boxInsetDivider(theme, renderedWidth),
+				...renderBoxedOutputLines(theme, outputLines, renderedWidth, options.renderLineBudget ?? outputLines.length),
+				...renderedFooterLines,
+				boxBorder(theme, "└", "┘", renderedWidth),
+			];
+			cache = { width, lines: rendered };
+			return rendered;
+		},
+	};
+}
+
+export function formatBoxedWallTime(result: MetricResultLike | undefined): string {
+	const elapsedMs = getElapsedMs(result);
+	if (elapsedMs === undefined) return "--";
+	return `${(elapsedMs / 1000).toFixed(2)}s`;
+}
+
+export function formatBoxedFooterFromValues(
+	theme: BoxTheme,
+	elapsedMs: number | undefined,
+	output: string,
+	extraParts: string[] = [],
+	fixedColumns = false,
+): string {
+	const wall = elapsedMs === undefined ? "--" : `${(elapsedMs / 1000).toFixed(2)}s`;
+	const elapsedPart = `${theme.fg("text", "◷")} ${theme.fg("dim", wall)}`;
+	const extraPartList = extraParts.filter(Boolean).map((part) => theme.fg("dim", part));
+	const wordsPart = theme.fg("dim", formatBoxedWords(output));
+	const parts = fixedColumns
+		? [
+				padVisibleRight(elapsedPart, COMPACT_FOOTER_ELAPSED_WIDTH),
+				...extraPartList.map((part) => padVisibleRight(part, COMPACT_FOOTER_EXTRA_WIDTH)),
+				padVisibleRight(wordsPart, COMPACT_FOOTER_WORDS_WIDTH),
+			]
+		: [elapsedPart, ...extraPartList, wordsPart];
+	return parts.join(theme.fg("dim", " · "));
+}
+
+function formatBoxedFooterParts(
+	theme: BoxTheme,
+	result: MetricResultLike | undefined,
+	extraParts: string[] = [],
+	fixedColumns = false,
+	elapsedMs?: number,
+): string {
+	return formatBoxedFooterFromValues(
+		theme,
+		elapsedMs ?? getElapsedMs(result),
+		getTextOutput(result),
+		extraParts,
+		fixedColumns,
+	);
+}
+
+export function formatBoxedFooter(
+	theme: BoxTheme,
+	result: MetricResultLike | undefined,
+	extraParts: string[] = [],
+	elapsedMs?: number,
+): string {
+	return formatBoxedFooterParts(theme, result, extraParts, false, elapsedMs);
+}
+
+export function renderCompactBoxedFooter(
+	theme: BoxTheme,
+	result: MetricResultLike | undefined,
+	options: BoxedRenderOptions = {},
+): Component {
+	if (options.state && typeof options.state === "object") {
+		options.state[COMPACT_FOOTER_KEY] = formatBoxedFooterParts(theme, result, [], true, options.elapsedMs);
+		options.state[COMPACT_FOOTER_ERROR_KEY] = Boolean(options.isError);
+		options.state[COMPACT_FOOTER_PARTIAL_KEY] = Boolean(options.isPartial);
+		return { invalidate() {}, render: () => [] };
+	}
+
+	return {
+		invalidate() {},
+		render(width: number): string[] {
+			const renderedWidth = boxWidth(width);
+			return [
+				boxLine(theme, formatBoxedFooterParts(theme, result, [], false, options.elapsedMs), renderedWidth),
+				boxBorder(theme, "└", "┘", renderedWidth),
+			];
+		},
+	};
+}
+
+const TOOL_BODY_INDENT = 2;
+const TOOL_RIGHT_MARGIN = 1;
+
+export function renderToolCallHeader(
+	theme: BoxTheme,
+	label: string,
+	detail: string,
+	skipTextColor?: boolean,
+): Component {
+	return renderToolCallHeaderLines(theme, label, [parens(theme, detail, skipTextColor)]);
+}
+
+export function getToolBodyWidth(width: number, spaces = TOOL_BODY_INDENT): number {
+	return Math.max(1, width - spaces - TOOL_RIGHT_MARGIN);
+}
+
+export function renderToolCallHeaderLines(theme: BoxTheme, label: string, detailLines: string[]): Component {
+	const prefix = `${badge(theme, label)} `;
+	const indent = " ".repeat(safeVisibleWidth(prefix));
+	return {
+		invalidate() {},
+		render(width: number): string[] {
+			const bodyWidth = Math.max(1, width - safeVisibleWidth(prefix) - TOOL_RIGHT_MARGIN);
+			const output: string[] = [];
+			for (let i = 0; i < detailLines.length; i++) {
+				const wrapped = safeWrapTextWithAnsi(detailLines[i] ?? "", bodyWidth);
+				if (i === 0) {
+					output.push(`${prefix}${wrapped[0] ?? ""}`);
+					output.push(...wrapped.slice(1).map((line) => `${indent}${line}`));
+				} else {
+					output.push(...wrapped.map((line) => `${indent}${line}`));
+				}
+			}
+			return output.length > 0 ? output : [prefix.trimEnd()];
+		},
+	};
+}
+
+export function indentToolBody(text: string, spaces = TOOL_BODY_INDENT): string {
+	const indent = " ".repeat(spaces);
+	return text
+		.split("\n")
+		.map((line) => (line.length === 0 ? line : `${indent}${line}`))
+		.join("\n");
+}
+
+export function indentToolBodyLines(lines: string[], spaces = TOOL_BODY_INDENT): string[] {
+	const indent = " ".repeat(spaces);
+	return lines.map((line) => (line.length === 0 ? line : `${indent}${line}`));
+}
+
+export function formatToolOutputLine(
+	theme: BoxTheme,
+	line: string,
+	color: "toolOutput" | "error" | "text" = "toolOutput",
+): string {
+	if (color === "error") return theme.fg("error", line);
+
+	const clean = stripAnsi(line);
+	if (/^##\s/.test(clean)) return theme.fg("muted", line);
+	if (/^\?\?\s/.test(clean))
+		return theme.bold ? theme.bold(theme.fg("syntaxVariable", line)) : theme.fg("syntaxVariable", line);
+
+	return theme.fg(color, line);
+}
+
+function selectRenderLines(text: string, maxLines: number, tail = false): { lines: string[]; omitted: number } {
+	const source = text ?? "";
+	if (!source) return { lines: [], omitted: 0 };
+	const limit = Math.max(0, maxLines);
+	const selected: string[] = [];
+	let lineCount = 0;
+	let lineStart = 0;
+
+	for (let i = 0; i <= source.length; i++) {
+		if (i < source.length && source[i] !== "\n") continue;
+		const rawLine = source.slice(lineStart, i).replace(/\r/g, "");
+		lineCount++;
+		if (limit > 0) {
+			const line = clampRenderLine(rawLine);
+			if (tail) {
+				selected.push(line);
+				if (selected.length > limit) selected.shift();
+			} else if (selected.length < limit) {
+				selected.push(line);
+			}
+		}
+		lineStart = i + 1;
+	}
+
+	if (selected.length === 1 && selected[0] === "") return { lines: [], omitted: 0 };
+	return { lines: selected, omitted: Math.max(0, lineCount - selected.length) };
+}
+
+export function renderLines(
+	theme: BoxTheme,
+	text: string,
+	options: { expanded?: boolean },
+	cfg: { maxLines: number; tail?: boolean; color?: "toolOutput" | "error"; width?: number } = { maxLines: 10 },
+): string {
+	const color = cfg.color ?? "toolOutput";
+	const { lines, omitted } = selectRenderLines(text, cfg.maxLines, cfg.tail);
+	const renderWidth = cfg.width ? getToolBodyWidth(cfg.width) : undefined;
+	const renderLine = (line: string) => {
+		const rendered = renderWidth ? safeTruncateToWidth(line, renderWidth, "…") : line;
+		return formatToolOutputLine(theme, rendered, color);
+	};
+
+	if (lines.length === 0) return "";
+
+	let output = lines.map(renderLine).join("\n");
+	if (omitted <= 0) return output;
+
+	const hintText = isExpanded(options)
+		? `... ${omitted} more lines omitted by render budget`
+		: `... ${omitted} more lines, press Ctrl+o to expand`;
+	const hint = cfg.width ? safeTruncateToWidth(hintText, Math.max(1, cfg.width - 1), "…") : hintText;
+	output += theme.fg("muted", `\n\n${hint}`);
+
+	return output;
+}
+
+export function dimWithElapsed(theme: BoxTheme, summary: string, result: MetricResultLike | undefined): string {
+	const metrics = formatToolMetrics(result);
+	return metrics
+		? `${theme.fg("dim", summary)} ${theme.fg("dim", "–")} ${theme.italic ? theme.italic(theme.fg("muted", metrics)) : theme.fg("muted", metrics)}`
+		: theme.fg("dim", summary);
+}
+
+export function renderToolMetricsFooter(theme: BoxTheme, _width: number, metrics: string): string[] {
+	return metrics
+		? [theme.italic ? theme.italic(theme.fg("muted", `↳ ${metrics}`)) : theme.fg("muted", `↳ ${metrics}`)]
+		: [];
+}
+
+export type { MetricResultLike };
+// Re-exported metric helpers so renderers import from a single box module.
+export { getElapsedMs };