@oh-my-pi/pi-tui 18.2.3 → 18.2.5

package/src/render/output-block.ts

@@ -0,0 +1,267 @@
+/**
+ * Bordered output container with optional header and sections.
+ */
+import { ImageProtocol, TERMINAL } from "../terminal-capabilities";
+import type { Theme, ThemeColor } from "../theme/theme";
+import type { Component } from "../tui";
+import { Ellipsis, padding, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
+import { getSixelLineMask } from "./sixel";
+import type { State } from "./types";
+import type { RenderCache } from "./utils";
+import { getStateBgColor, Hasher, padToWidth } from "./utils";
+
+/** Sections and presentation options for a bordered output block. */
+export interface OutputBlockOptions {
+	header?: string;
+	headerMeta?: string;
+	state?: State;
+	sections?: Array<{ label?: string; lines: readonly string[]; separator?: boolean }>;
+	width: number;
+	applyBg?: boolean;
+	contentPaddingLeft?: number;
+	contentPaddingRight?: number;
+	/** Override the state-derived border color. Used for muted "legacy" tool
+	 * frames that should not visually compete with framed-output tools. */
+	borderColor?: ThemeColor;
+}
+
+const FRAMED_BLOCK_COMPONENT = Symbol("framedBlockComponent");
+
+/** A component marked as rendering its own output frame. */
+export type FramedBlockComponent = Component & { [FRAMED_BLOCK_COMPONENT]?: true };
+
+/** Mark a component as owning its output frame. */
+export function markFramedBlockComponent<T extends Component>(component: T): T & FramedBlockComponent {
+	(component as T & FramedBlockComponent)[FRAMED_BLOCK_COMPONENT] = true;
+	return component as T & FramedBlockComponent;
+}
+
+/** Return whether a component owns its output frame. */
+export function isFramedBlockComponent(component: Component): boolean {
+	return (component as FramedBlockComponent)[FRAMED_BLOCK_COMPONENT] === true;
+}
+
+type BlockRow =
+	| { kind: "bar"; leftChar: string; rightChar: string; label?: string; meta?: string }
+	| { kind: "bottom"; leftChar: string; rightChar: string }
+	| { kind: "content"; inner: string }
+	| { kind: "sixel"; raw: string };
+
+function normalizeContentPaddingLeft(value: number | undefined): number {
+	if (value === undefined || !Number.isFinite(value)) return 1;
+	return Math.max(0, Math.floor(value));
+}
+
+/**
+ * Inner content width that {@link renderOutputBlock} wraps its body to, for a
+ * given outer `width`: both vertical borders plus symmetric content padding.
+ * An explicit left padding of zero keeps legacy flush blocks flush on both
+ * sides unless a right padding is provided separately.
+ */
+export function outputBlockContentWidth(
+	width: number,
+	contentPaddingLeft?: number,
+	contentPaddingRight?: number,
+): number {
+	const left = normalizeContentPaddingLeft(contentPaddingLeft);
+	const right = normalizeContentPaddingLeft(contentPaddingRight ?? left);
+	return Math.max(1, width - 2 - left - right);
+}
+
+/** Render a bordered output block with optional header and sections. */
+export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[] {
+	const { header, headerMeta, state, sections = [], width, applyBg = true } = options;
+	const h = theme.boxRound.horizontal;
+	const v = theme.boxRound.vertical;
+	const cap = h.repeat(3);
+	const lineWidth = Math.max(0, width);
+	// Border colors: running/pending use accent, success uses dim (gray), error/warning keep their colors
+	const borderColor: ThemeColor =
+		options.borderColor ??
+		(state === "error"
+			? "error"
+			: state === "warning"
+				? "warning"
+				: state === "running" || state === "pending"
+					? "accent"
+					: "dim");
+	const border = (text: string) => theme.fg(borderColor, text);
+	const bgFn = (() => {
+		if (!state || !applyBg) return undefined;
+		const bgAnsi = theme.getBgAnsi(getStateBgColor(state));
+		// Keep block background stable even if inner content contains SGR resets (e.g. "\x1b[0m"),
+		// which would otherwise clear the outer background mid-line.
+		return (text: string) => {
+			const stabilized = text
+				.replace(/\x1b\[(?:0)?m/g, m => `${m}${bgAnsi}`)
+				.replace(/\x1b\[49m/g, m => `${m}${bgAnsi}`);
+			return `${bgAnsi}${stabilized}\x1b[49m`;
+		};
+	})();
+
+	const contentPaddingLeft = normalizeContentPaddingLeft(options.contentPaddingLeft);
+	const contentPaddingRight = normalizeContentPaddingLeft(options.contentPaddingRight ?? contentPaddingLeft);
+	const contentWidth = Math.max(
+		0,
+		lineWidth - visibleWidth(v) - contentPaddingLeft - contentPaddingRight - visibleWidth(v),
+	);
+	const contentLeftPadding = contentPaddingLeft > 0 ? padding(contentPaddingLeft) : "";
+	const contentRightPadding = contentPaddingRight > 0 ? padding(contentPaddingRight) : "";
+
+	// ── Layout pass: collect row descriptors before emitting the bordered lines. ──
+	const rows: BlockRow[] = [];
+	rows.push({
+		kind: "bar",
+		leftChar: theme.boxRound.topLeft,
+		rightChar: theme.boxRound.topRight,
+		label: header,
+		meta: headerMeta,
+	});
+
+	const normalizedSections = sections.length > 0 ? sections : [{ lines: [] as string[] }];
+	for (let sectionIndex = 0; sectionIndex < normalizedSections.length; sectionIndex++) {
+		const section = normalizedSections[sectionIndex]!;
+		// A labeled section always draws its titled separator bar. A label-less
+		// section can still request a plain divider via `separator`, but only
+		// between sections — leading with one would just double the header bar.
+		if (section.label) {
+			rows.push({
+				kind: "bar",
+				leftChar: theme.boxRound.teeRight,
+				rightChar: theme.boxRound.teeLeft,
+				label: section.label,
+			});
+		} else if (section.separator && sectionIndex > 0) {
+			rows.push({
+				kind: "bar",
+				leftChar: theme.boxRound.teeRight,
+				rightChar: theme.boxRound.teeLeft,
+			});
+		}
+		const allLines = section.lines.flatMap(l => l.split("\n"));
+		const sixelLineMask = TERMINAL.imageProtocol === ImageProtocol.Sixel ? getSixelLineMask(allLines) : undefined;
+		for (let lineIndex = 0; lineIndex < allLines.length; lineIndex++) {
+			const line = allLines[lineIndex]!;
+			if (sixelLineMask?.[lineIndex]) {
+				rows.push({ kind: "sixel", raw: line });
+				continue;
+			}
+			const wrappedLines = wrapTextWithAnsi(line.trimEnd(), contentWidth);
+			for (const wrappedLine of wrappedLines) {
+				const innerPadding = padding(Math.max(0, contentWidth - visibleWidth(wrappedLine)));
+				rows.push({ kind: "content", inner: `${wrappedLine}${innerPadding}` });
+			}
+		}
+	}
+
+	rows.push({ kind: "bottom", leftChar: theme.boxRound.bottomLeft, rightChar: theme.boxRound.bottomRight });
+
+	const H = rows.length;
+
+	const renderBar = (row: { leftChar: string; rightChar: string; label?: string; meta?: string }): string => {
+		const leftGlyphs = `${row.leftChar}${cap}`;
+		const rightGlyph = row.rightChar;
+		if (lineWidth <= 0) return border(leftGlyphs) + border(rightGlyph);
+		const labelText = [row.label, row.meta].filter(Boolean).join(theme.sep.dot);
+		if (!labelText) {
+			// No header: draw a clean, continuous top/separator bar (no 1-col gap).
+			const fillCount = Math.max(0, lineWidth - visibleWidth(leftGlyphs) - visibleWidth(rightGlyph));
+			return `${border(leftGlyphs)}${border(h.repeat(fillCount))}${border(rightGlyph)}`;
+		}
+		const rawLabel = ` ${labelText} `;
+		const leftWidth = visibleWidth(leftGlyphs);
+		const rightWidth = visibleWidth(rightGlyph);
+		const maxLabelWidth = Math.max(0, lineWidth - leftWidth - rightWidth);
+		const trimmedLabel = truncateToWidth(rawLabel, maxLabelWidth);
+		const labelWidth = visibleWidth(trimmedLabel);
+		const fillCount = Math.max(0, lineWidth - leftWidth - labelWidth - rightWidth);
+		const fillGlyphs = h.repeat(fillCount);
+		return `${border(leftGlyphs)}${trimmedLabel}${border(fillGlyphs)}${border(rightGlyph)}`;
+	};
+
+	const renderBottom = (row: { leftChar: string; rightChar: string }): string => {
+		const leftGlyphs = `${row.leftChar}${cap}`;
+		const rightGlyph = row.rightChar;
+		const fillCount = Math.max(0, lineWidth - visibleWidth(leftGlyphs) - visibleWidth(rightGlyph));
+		const fillGlyphs = h.repeat(fillCount);
+		return `${border(leftGlyphs)}${border(fillGlyphs)}${border(rightGlyph)}`;
+	};
+
+	const renderContent = (inner: string): string =>
+		`${border(v)}${contentLeftPadding}${inner}${contentRightPadding}${border(v)}`;
+
+	const clipFrame = lineWidth < Math.max(visibleWidth(cap) + 2, contentPaddingLeft + contentPaddingRight + 2);
+	const lines: string[] = [];
+	for (let r = 0; r < H; r++) {
+		const row = rows[r]!;
+		if (row.kind === "sixel") {
+			lines.push(row.raw);
+			continue;
+		}
+		const line =
+			row.kind === "bar" ? renderBar(row) : row.kind === "bottom" ? renderBottom(row) : renderContent(row.inner);
+		lines.push(padToWidth(clipFrame ? truncateToWidth(line, lineWidth, Ellipsis.Omit) : line, lineWidth, bgFn));
+	}
+
+	return lines;
+}
+
+/**
+ * Cached wrapper around `renderOutputBlock`.
+ *
+ * Since output blocks are re-rendered on every frame (via `render(width)` closures),
+ * but their content rarely changes, this cache avoids redundant `visibleWidth()` and
+ * `padding()` computations on ~99% of render calls.
+ */
+export class CachedOutputBlock {
+	#cache?: RenderCache;
+	#lastOptions?: OutputBlockOptions;
+
+	/** Render with caching. Returns the cached (shared, caller-immutable) lines if options haven't changed. */
+	render(options: OutputBlockOptions, theme: Theme): readonly string[] {
+		// Reference fast path: rebuild paths often hand back the same options
+		// object when nothing changed; skip the full content hash entirely.
+		if (this.#lastOptions === options && this.#cache) return this.#cache.lines;
+		const key = this.#buildKey(options);
+		if (this.#cache?.key === key) {
+			this.#lastOptions = options;
+			return this.#cache.lines;
+		}
+		const lines = renderOutputBlock(options, theme);
+		this.#cache = { key, lines };
+		this.#lastOptions = options;
+		return lines;
+	}
+
+	/** Invalidate the cache, forcing a rebuild on next render. */
+	invalidate(): void {
+		this.#cache = undefined;
+		this.#lastOptions = undefined;
+	}
+
+	#buildKey(options: OutputBlockOptions): bigint {
+		const h = new Hasher();
+		h.u32(options.width);
+		h.u32(normalizeContentPaddingLeft(options.contentPaddingLeft));
+		h.u32(
+			normalizeContentPaddingLeft(
+				options.contentPaddingRight ?? normalizeContentPaddingLeft(options.contentPaddingLeft),
+			),
+		);
+		h.optional(options.header);
+		h.optional(options.headerMeta);
+		h.optional(options.state);
+		h.optional(options.borderColor);
+		h.bool(options.applyBg ?? true);
+		if (options.sections) {
+			for (const s of options.sections) {
+				h.optional(s.label);
+				h.bool(s.separator ?? false);
+				for (const line of s.lines) {
+					h.str(line);
+				}
+			}
+		}
+		return h.digest();
+	}
+}

package/src/render/output-pane.ts

@@ -0,0 +1,299 @@
+import { Text } from "../components/text";
+import { ImageProtocol, TERMINAL } from "../terminal-capabilities";
+import type { Theme } from "../theme/theme";
+import type { Component } from "../tui";
+import { getPaddingX } from "../utils";
+import { truncateToVisualLines } from "../chrome/visual-truncate";
+import { getSixelLineMask } from "./sixel";
+import { formatExpandHint, replaceTabs } from "./render-utils";
+
+/** Which side of an output stream remains visible when the pane is capped. */
+export type OutputPaneEdge = "head" | "tail";
+
+/** Inputs for the shared output capping and styling algorithm. */
+export interface OutputPaneFormatOptions {
+	lines: readonly string[];
+	expanded: boolean;
+	collapsedMaxLines: number;
+	expandedMaxLines?: number;
+	edge?: OutputPaneEdge;
+	/** Apply the cap after terminal-width wrapping instead of to logical rows. */
+	visual?: boolean;
+	/** Content width used by visual capping. Required when `visual` is true. */
+	width?: number;
+	styleLine?: (line: string, index: number) => string;
+	/** Keep sixel payload rows byte-for-byte and show the complete payload. */
+	uncapSixel?: boolean;
+	showHiddenMarker?: boolean;
+	showExpandHint?: boolean;
+	showExpandHintWhenUncapped?: boolean;
+	formatHidden?: (hidden: number, shown: number, total: number, edge: OutputPaneEdge) => string;
+}
+
+/** Result of formatting one bounded output pane. */
+export interface OutputPaneFormatResult {
+	lines: readonly string[];
+	hiddenCount: number;
+	hasSixel: boolean;
+}
+
+/**
+ * Split terminal text without allowing carriage-return progress updates to
+ * corrupt following TUI rows. The final segment after a bare CR wins, matching
+ * a terminal cursor-return overwrite.
+ */
+export function splitTerminalOutputLines(text: string): string[] {
+	return text.split(/\r?\n/u).map(line => {
+		const carriageReturn = line.lastIndexOf("\r");
+		return carriageReturn < 0 ? line : line.slice(carriageReturn + 1);
+	});
+}
+
+function defaultHiddenLabel(hidden: number, shown: number, total: number, edge: OutputPaneEdge): string {
+	return edge === "tail"
+		? `… (${hidden} earlier lines, showing ${shown} of ${total})`
+		: `… ${hidden} more line${hidden === 1 ? "" : "s"}`;
+}
+
+/**
+ * Style and cap output rows for code cells, tool cards, and live execution
+ * panes. Sixel rows are never styled or split; with `uncapSixel`, the complete
+ * payload is retained so terminal image protocols remain valid.
+ */
+export function formatOutputPaneLines(options: OutputPaneFormatOptions, theme: Theme): OutputPaneFormatResult {
+	const edge = options.edge ?? "head";
+	const rawLines = options.lines;
+	const sixelMask =
+		TERMINAL.imageProtocol === ImageProtocol.Sixel && rawLines.length > 0 ? getSixelLineMask(rawLines) : undefined;
+	const hasSixel = sixelMask?.some(Boolean) ?? false;
+	const styledLines = rawLines.map((line, index) =>
+		sixelMask?.[index] ? line : (options.styleLine?.(line, index) ?? line),
+	);
+
+	const configuredLimit = options.expanded ? options.expandedMaxLines : options.collapsedMaxLines;
+	const limit = hasSixel && options.uncapSixel ? undefined : configuredLimit;
+	let visibleLines: readonly string[] = styledLines;
+	let hiddenCount = 0;
+
+	if (limit !== undefined && Number.isFinite(limit)) {
+		const boundedLimit = Math.max(0, Math.floor(limit));
+		if (boundedLimit === 0) {
+			visibleLines = [];
+			hiddenCount = styledLines.length;
+		} else if (options.visual && edge === "tail") {
+			const visual = truncateToVisualLines(styledLines.join("\n"), boundedLimit, Math.max(1, options.width ?? 1));
+			visibleLines = visual.visualLines;
+			hiddenCount = visual.skippedCount;
+		} else if (options.visual) {
+			const rendered = new Text(styledLines.join("\n"), 0, 0).render(Math.max(1, options.width ?? 1));
+			visibleLines = rendered.slice(0, boundedLimit);
+			hiddenCount = Math.max(0, rendered.length - visibleLines.length);
+		} else if (styledLines.length > boundedLimit) {
+			hiddenCount = styledLines.length - boundedLimit;
+			visibleLines = edge === "tail" ? styledLines.slice(-boundedLimit) : styledLines.slice(0, boundedLimit);
+		}
+	}
+
+	const lines = [...visibleLines];
+	if (hiddenCount > 0 && options.showHiddenMarker !== false) {
+		const label = (options.formatHidden ?? defaultHiddenLabel)(
+			hiddenCount,
+			visibleLines.length,
+			hiddenCount + visibleLines.length,
+			edge,
+		);
+		const hint = options.showExpandHint === false ? "" : formatExpandHint(theme, options.expanded, true);
+		const marker = theme.fg("dim", `${label}${hint ? ` ${hint}` : ""}`);
+		if (edge === "tail") lines.unshift(marker);
+		else lines.push(marker);
+	} else if (!options.expanded && options.showExpandHintWhenUncapped) {
+		const hint = formatExpandHint(theme, false, true);
+		if (hint) lines.push(hint);
+	}
+
+	return { lines, hiddenCount, hasSixel };
+}
+
+/** Mutable options for a live {@link OutputPane}. */
+export interface OutputPaneOptions extends Omit<OutputPaneFormatOptions, "lines"> {
+	paddingX?: number;
+	leadingBlank?: boolean;
+	maxStoredLines?: number;
+	/** Normalize each logical row before it enters the retained stream. */
+	normalizeLine?: (line: string) => string;
+}
+
+/**
+ * Stateful, cached output viewport. Streaming callers append chunks while
+ * settled callers may replace all rows. Unchanged renders preserve array
+ * identity through the inner Text cache.
+ */
+export class OutputPane implements Component {
+	readonly #theme: Theme;
+	#options: OutputPaneOptions;
+	#lines: string[] = [];
+	#pendingCarriageReturn = false;
+	#text: Text;
+	#renderKey = "";
+
+	constructor(theme: Theme, options: OutputPaneOptions, text = "") {
+		this.#theme = theme;
+		this.#options = { ...options };
+		this.#text = new Text("", options.paddingX ?? 0, 0);
+		if (text) this.setText(text);
+	}
+
+	/** Replace the complete output snapshot. */
+	setText(text: string): void {
+		this.setLines(text ? splitTerminalOutputLines(text) : []);
+	}
+
+	/** Replace the complete output snapshot with caller-owned immutable rows. */
+	setLines(lines: readonly string[]): void {
+		const normalizeLine = this.#options.normalizeLine;
+		const normalized = normalizeLine ? lines.map(line => normalizeLine(line)) : [...lines];
+		this.#lines = this.#clampStoredLines(normalized);
+		this.#pendingCarriageReturn = false;
+		this.invalidate();
+	}
+
+	/**
+	 * Append a streaming chunk. Bare CR overwrites the current logical row;
+	 * a CRLF split across chunks remains a newline, so chunked and whole-text
+	 * ingestion produce the same settled rows.
+	 */
+	append(chunk: string): void {
+		if (!chunk) return;
+		let index = 0;
+		if (this.#pendingCarriageReturn) {
+			this.#pendingCarriageReturn = false;
+			if (chunk[0] === "\n") {
+				this.#startLine();
+				index = 1;
+			} else {
+				this.#replaceTail("");
+			}
+		}
+
+		let segmentStart = index;
+		while (index < chunk.length) {
+			const char = chunk[index];
+			if (char !== "\r" && char !== "\n") {
+				index++;
+				continue;
+			}
+			this.#appendToTail(chunk.slice(segmentStart, index));
+			if (char === "\n") {
+				this.#startLine();
+			} else if (index + 1 < chunk.length) {
+				if (chunk[index + 1] === "\n") {
+					this.#startLine();
+					index++;
+				} else {
+					this.#replaceTail("");
+				}
+			} else {
+				this.#pendingCarriageReturn = true;
+			}
+			index++;
+			segmentStart = index;
+		}
+		this.#appendToTail(chunk.slice(segmentStart));
+		this.#lines = this.#clampStoredLines(this.#lines);
+		this.invalidate();
+	}
+
+	/** Settle a trailing bare carriage return once no later LF can pair with it. */
+	finish(): void {
+		if (!this.#pendingCarriageReturn) return;
+		this.#pendingCarriageReturn = false;
+		this.#replaceTail("");
+		this.invalidate();
+	}
+
+	/** Update presentation without replacing streamed content. */
+	configure(options: Partial<OutputPaneOptions>): void {
+		const previousPadding = this.#options.paddingX ?? 0;
+		this.#options = { ...this.#options, ...options };
+		const nextPadding = this.#options.paddingX ?? 0;
+		if (previousPadding !== nextPadding) this.#text = new Text("", nextPadding, 0);
+		this.#lines = this.#clampStoredLines(this.#lines);
+		this.invalidate();
+	}
+
+	setExpanded(expanded: boolean): void {
+		if (this.#options.expanded === expanded) return;
+		this.#options = { ...this.#options, expanded };
+		this.invalidate();
+	}
+
+	get lineCount(): number {
+		return this.#lines.length;
+	}
+
+	get hasSixel(): boolean {
+		if (TERMINAL.imageProtocol !== ImageProtocol.Sixel || this.#lines.length === 0) return false;
+		return getSixelLineMask(this.#lines).some(Boolean);
+	}
+
+	getText(): string {
+		return this.#lines.join("\n");
+	}
+
+	render(width: number): readonly string[] {
+		const paddingX = getPaddingX(this.#options.paddingX ?? 0);
+		const contentWidth = Math.max(1, width - paddingX * 2);
+		const formatted = formatOutputPaneLines(
+			{
+				...this.#options,
+				lines: this.#lines,
+				width: contentWidth,
+			},
+			this.#theme,
+		);
+		const content = `${this.#options.leadingBlank && formatted.lines.length > 0 ? "\n" : ""}${formatted.lines.join("\n")}`;
+		const key = `${width}:${content.length}:${Bun.hash(content).toString(36)}`;
+		if (key !== this.#renderKey) {
+			this.#renderKey = key;
+			this.#text.setText(content);
+		}
+		return this.#text.render(width);
+	}
+
+	invalidate(): void {
+		this.#renderKey = "";
+		this.#text.invalidate();
+	}
+
+	#appendToTail(text: string): void {
+		if (!text) return;
+		if (this.#lines.length === 0) this.#lines.push("");
+		const last = this.#lines.length - 1;
+		this.#replaceTail(`${this.#lines[last]}${text}`);
+	}
+
+	#replaceTail(text: string): void {
+		const normalizeLine = this.#options.normalizeLine;
+		const normalized = normalizeLine ? normalizeLine(text) : text;
+		if (this.#lines.length === 0) this.#lines.push(normalized);
+		else this.#lines[this.#lines.length - 1] = normalized;
+	}
+
+	#startLine(): void {
+		if (this.#lines.length === 0) this.#lines.push("");
+		this.#lines.push("");
+	}
+
+	#clampStoredLines(lines: string[]): string[] {
+		const maxStoredLines = this.#options.maxStoredLines;
+		if (maxStoredLines === undefined || lines.length <= maxStoredLines) return lines;
+		const boundedMax = Math.max(0, Math.floor(maxStoredLines));
+		return boundedMax === 0 ? [] : lines.slice(-boundedMax);
+	}
+}
+
+/** Default styling for plain tool output while preserving existing ANSI. */
+export function styleToolOutputLine(line: string, theme: Theme): string {
+	const normalized = replaceTabs(line);
+	return normalized.includes("\x1b[") ? normalized : theme.fg("toolOutput", normalized);
+}