@oh-my-pi/pi-tui 18.2.4 → 18.2.6

package/src/render/sixel.ts

@@ -0,0 +1,69 @@
+import { $env, $flag } from "@oh-my-pi/pi-utils";
+
+const SIXEL_START_REGEX = /\x1bP(?:[0-9;]*)q/u;
+const SIXEL_END_SEQUENCE = "\x1b\\";
+const SIXEL_END_BELL = "\x07";
+const SIXEL_SEQUENCE_REGEX = /\x1bP(?:[0-9;]*)q[\s\S]*?(?:\x1b\\|\x07)/gu;
+const SIXEL_PLACEHOLDER_PREFIX = "__OMP_SIXEL_SEQUENCE_";
+
+/**
+ * Returns whether SIXEL passthrough is explicitly enabled.
+ *
+ * Both gates must be enabled to preserve SIXEL control sequences:
+ * - PI_FORCE_IMAGE_PROTOCOL=sixel
+ * - PI_ALLOW_SIXEL_PASSTHROUGH=1
+ */
+export function isSixelPassthroughEnabled(): boolean {
+	const forcedProtocol = $env.PI_FORCE_IMAGE_PROTOCOL?.trim().toLowerCase();
+	return forcedProtocol === "sixel" && $flag("PI_ALLOW_SIXEL_PASSTHROUGH");
+}
+/** Returns true when the text contains a SIXEL start sequence. */
+export function containsSixelSequence(text: string): boolean {
+	return SIXEL_START_REGEX.test(text);
+}
+
+/**
+ * Returns a boolean mask indicating which lines belong to a SIXEL sequence block.
+ * Supports multi-line SIXEL payloads generated by libsixel.
+ */
+export function getSixelLineMask(lines: readonly string[]): boolean[] {
+	let inSequence = false;
+	return lines.map(line => {
+		const hasStart = containsSixelSequence(line);
+		if (hasStart) {
+			inSequence = true;
+		}
+		const isSixelLine = inSequence;
+		if (inSequence && (line.includes(SIXEL_END_SEQUENCE) || line.includes(SIXEL_END_BELL))) {
+			inSequence = false;
+		}
+		return isSixelLine;
+	});
+}
+
+/** Returns true when the line contains a SIXEL start sequence. */
+export function isSixelLine(line: string): boolean {
+	return containsSixelSequence(line);
+}
+
+/**
+ * Sanitizes text while preserving embedded SIXEL sequences when passthrough is enabled.
+ */
+export function sanitizeWithOptionalSixelPassthrough(text: string, sanitize: (text: string) => string): string {
+	if (!isSixelPassthroughEnabled() || !containsSixelSequence(text)) {
+		return sanitize(text);
+	}
+
+	const preservedSequences: string[] = [];
+	const tokenized = text.replace(SIXEL_SEQUENCE_REGEX, match => {
+		const token = `${SIXEL_PLACEHOLDER_PREFIX}${preservedSequences.length}__`;
+		preservedSequences.push(match);
+		return token;
+	});
+
+	const sanitized = sanitize(tokenized);
+	return sanitized.replace(/__OMP_SIXEL_SEQUENCE_(\d+)__/gu, (_, indexText: string) => {
+		const index = Number.parseInt(indexText, 10);
+		return preservedSequences[index] ?? "";
+	});
+}

package/src/render/status-line.ts

@@ -0,0 +1,55 @@
+/**
+ * Standardized status header rendering for tool output.
+ */
+import type { Theme, ThemeColor } from "../theme/theme";
+import { formatStatusIcon, type ToolUIStatus } from "./render-utils";
+
+/** Status icon, title, description, and metadata for a single header row. */
+export interface StatusLineOptions {
+	icon?: ToolUIStatus;
+	/** Pre-rendered glyph that replaces the status icon (e.g. a magnifier for
+	 * search-family tools). Takes precedence over `icon`. */
+	iconOverride?: string;
+	spinnerFrame?: number;
+	title: string;
+	titleColor?: ThemeColor;
+	description?: string;
+	badge?: { label: string; color: ThemeColor };
+	meta?: string[];
+}
+
+/**
+ * Flatten CR/LF runs in caller-supplied header fragments so a single newline
+ * embedded in `description` or `meta` cannot expand the status line into
+ * multiple rows — which would otherwise break the bordered output block the
+ * header sits on. Tab characters are left alone; tool renderers that need
+ * tab-safe text run `replaceTabs()` themselves.
+ */
+function flattenForHeader(text: string): string {
+	return text.replace(/\r\n?|\n/g, " ");
+}
+
+/** Render a single-line status header, flattening multiline fields. */
+export function renderStatusLine(options: StatusLineOptions, theme: Theme): string {
+	const icon =
+		options.iconOverride ?? (options.icon ? formatStatusIcon(options.icon, theme, options.spinnerFrame) : "");
+	const titleColor = options.titleColor ?? "accent";
+	const title = theme.fg(titleColor, flattenForHeader(options.title));
+	let line = icon ? `${icon} ${title}` : title;
+
+	if (options.description) {
+		line += `: ${theme.fg("muted", flattenForHeader(options.description))}`;
+	}
+
+	if (options.badge) {
+		const { label, color } = options.badge;
+		line += ` ${theme.fg(color, `${theme.format.bracketLeft}${flattenForHeader(label)}${theme.format.bracketRight}`)}`;
+	}
+
+	const meta = options.meta?.map(flattenForHeader).filter(value => value.trim().length > 0) ?? [];
+	if (meta.length > 0) {
+		line += ` ${theme.fg("dim", meta.join(theme.sep.dot))}`;
+	}
+
+	return line;
+}

package/src/render/tool-card.ts

@@ -0,0 +1,272 @@
+import { Text } from "../components/text";
+import type { Theme, ThemeColor } from "../theme/theme";
+import type { Component } from "../tui";
+import { getPaddingX } from "../utils";
+import {
+	CachedOutputBlock,
+	markFramedBlockComponent,
+	outputBlockContentWidth,
+	type OutputBlockOptions,
+} from "./output-block";
+import { renderStatusLine, type StatusLineOptions } from "./status-line";
+import type { State } from "./types";
+import { getStateBgColor } from "./utils";
+
+/** Lifecycle distinctions shared by tool call and result cards. */
+export type ToolCardPhase = "pending" | "running" | "partial" | "success" | "warning" | "error" | "info";
+
+/** Fixed card topology. Framed cards own their border; plain cards flow inline. */
+export type ToolCardVariant = "framed" | "plain";
+
+/** Lazily rendered slot content. Components retain their own width caches. */
+export type ToolCardContent = readonly string[] | Component | ((width: number) => readonly string[] | Component);
+
+/** A labeled body section in a tool card. */
+export interface ToolCardSection {
+	label?: string;
+	content: ToolCardContent;
+	separator?: boolean;
+}
+
+/** Snapshot returned by a ToolCard builder on each render. */
+export interface ToolCardSnapshot {
+	/** Pre-rendered header. Prefer `status` for ordinary tool lifecycle rows. */
+	header?: string;
+	/** Structured status header, rendered by the shared status-line primitive. */
+	status?: StatusLineOptions;
+	headerMeta?: string;
+	phase?: ToolCardPhase;
+	body?: ToolCardContent;
+	sections?: readonly ToolCardSection[];
+	footer?: ToolCardContent;
+	applyBg?: boolean;
+	contentPaddingLeft?: number;
+	contentPaddingRight?: number;
+	borderColor?: ThemeColor;
+}
+
+/** Width information supplied to a ToolCard's lazy snapshot builder. */
+export interface ToolCardBuildContext {
+	width: number;
+	/** Inner width for the default one-column framed padding. */
+	contentWidth: number;
+	/** Compute an inner width when this snapshot opts into custom frame padding. */
+	contentWidthFor(contentPaddingLeft?: number, contentPaddingRight?: number): number;
+}
+
+/** Construction options whose topology remains fixed for a card's lifetime. */
+export interface ToolCardOptions {
+	variant: ToolCardVariant;
+	paddingX?: number;
+	paddingY?: number;
+	ignoreTight?: boolean;
+	onInvalidate?: () => void;
+	onDispose?: () => void;
+}
+
+/** Map transcript lifecycle terminology onto the output frame's visual states. */
+export function toolCardState(phase: ToolCardPhase | undefined): State | undefined {
+	if (phase === "partial") return "pending";
+	if (phase === "info") return undefined;
+	return phase;
+}
+
+function isRenderedLines(value: readonly string[] | Component): value is readonly string[] {
+	return Array.isArray(value);
+}
+
+function resolveContent(content: ToolCardContent, width: number): { lines: readonly string[]; component?: Component } {
+	const resolved = typeof content === "function" ? content(width) : content;
+	if (isRenderedLines(resolved)) return { lines: resolved };
+	return { lines: resolved.render(width), component: resolved };
+}
+
+/**
+ * Cached tool-card layout with lazy body/section/footer children. The builder
+ * may read mutable streaming state at render time; unchanged snapshots retain
+ * their rendered array identity through CachedOutputBlock or Text.
+ */
+export class ToolCard implements Component {
+	readonly #theme: Theme;
+	readonly #options: ToolCardOptions;
+	readonly #build: (context: ToolCardBuildContext) => ToolCardSnapshot;
+	readonly #block = new CachedOutputBlock();
+	#lastBlockOptions?: OutputBlockOptions;
+	#plainText: Text;
+	#plainKey = "";
+	#renderedChildren: Component[] = [];
+	#disposed = false;
+
+	constructor(theme: Theme, options: ToolCardOptions, build: (context: ToolCardBuildContext) => ToolCardSnapshot) {
+		this.#theme = theme;
+		this.#options = options;
+		this.#build = build;
+		this.#plainText = new Text("", options.paddingX ?? 0, options.paddingY ?? 0);
+		this.#plainText.setIgnoreTight(options.ignoreTight ?? true);
+		if (options.variant === "framed") markFramedBlockComponent(this);
+	}
+
+	render(width: number): readonly string[] {
+		const configuredPadding = this.#options.paddingX ?? 0;
+		const plainPadding = this.#options.ignoreTight === false ? getPaddingX(configuredPadding) : configuredPadding;
+		const defaultContentWidth =
+			this.#options.variant === "framed" ? outputBlockContentWidth(width) : Math.max(1, width - plainPadding * 2);
+		const snapshot = this.#build({
+			width,
+			contentWidth: defaultContentWidth,
+			contentWidthFor: (contentPaddingLeft?: number, contentPaddingRight?: number) =>
+				this.#options.variant === "framed"
+					? outputBlockContentWidth(width, contentPaddingLeft, contentPaddingRight)
+					: defaultContentWidth,
+		});
+		const contentWidth =
+			this.#options.variant === "framed"
+				? outputBlockContentWidth(width, snapshot.contentPaddingLeft, snapshot.contentPaddingRight)
+				: defaultContentWidth;
+
+		const previousChildren = this.#renderedChildren;
+		const nextChildren: Component[] = [];
+		const nextChildSet = new Set<Component>();
+		const retainChild = (component: Component | undefined): void => {
+			if (!component || nextChildSet.has(component)) return;
+			nextChildSet.add(component);
+			nextChildren.push(component);
+		};
+		const sections: Array<{ label?: string; lines: readonly string[]; separator?: boolean }> = [];
+		if (snapshot.body) {
+			const body = resolveContent(snapshot.body, contentWidth);
+			sections.push({ lines: body.lines });
+			retainChild(body.component);
+		}
+		for (const section of snapshot.sections ?? []) {
+			const resolved = resolveContent(section.content, contentWidth);
+			sections.push({ label: section.label, lines: resolved.lines, separator: section.separator });
+			retainChild(resolved.component);
+		}
+		if (snapshot.footer) {
+			const footer = resolveContent(snapshot.footer, contentWidth);
+			sections.push({ lines: footer.lines, separator: sections.length > 0 });
+			retainChild(footer.component);
+		}
+		for (const previousChild of previousChildren) {
+			if (!nextChildSet.has(previousChild)) previousChild.dispose?.();
+		}
+		this.#renderedChildren = nextChildren;
+
+		const state = toolCardState(snapshot.phase);
+		const header = snapshot.header ?? (snapshot.status ? renderStatusLine(snapshot.status, this.#theme) : undefined);
+		if (this.#options.variant === "framed") {
+			const previousOptions = this.#lastBlockOptions;
+			const previousSections = previousOptions?.sections;
+			const sectionsStable =
+				previousSections?.length === sections.length &&
+				sections.every((section, index) => {
+					const previous = previousSections[index];
+					return (
+						previous?.label === section.label &&
+						previous.lines === section.lines &&
+						previous.separator === section.separator
+					);
+				});
+			const reusableOptions =
+				previousOptions?.width === width &&
+				previousOptions.header === header &&
+				previousOptions.headerMeta === snapshot.headerMeta &&
+				previousOptions.state === state &&
+				previousOptions.applyBg === snapshot.applyBg &&
+				previousOptions.contentPaddingLeft === snapshot.contentPaddingLeft &&
+				previousOptions.contentPaddingRight === snapshot.contentPaddingRight &&
+				previousOptions.borderColor === snapshot.borderColor &&
+				sectionsStable
+					? previousOptions
+					: undefined;
+			const blockOptions: OutputBlockOptions = reusableOptions ?? {
+				header,
+				headerMeta: snapshot.headerMeta,
+				state,
+				sections,
+				width,
+				applyBg: snapshot.applyBg,
+				contentPaddingLeft: snapshot.contentPaddingLeft,
+				contentPaddingRight: snapshot.contentPaddingRight,
+				borderColor: snapshot.borderColor,
+			};
+			this.#lastBlockOptions = blockOptions;
+			return this.#block.render(blockOptions, this.#theme);
+		}
+
+		const lines: string[] = [];
+		if (header) {
+			lines.push(snapshot.headerMeta ? `${header} ${snapshot.headerMeta}` : header);
+		}
+		for (const section of sections) {
+			if (section.separator && lines.length > 0) lines.push("");
+			if (section.label) lines.push(section.label);
+			lines.push(...section.lines);
+		}
+		const text = lines.join("\n");
+		const key = `${width}:${text.length}:${Bun.hash(text).toString(36)}:${state ?? "info"}:${snapshot.applyBg ?? true}`;
+		if (key !== this.#plainKey) {
+			this.#plainKey = key;
+			this.#plainText.setText(text);
+			this.#plainText.setCustomBgFn(
+				state && snapshot.applyBg !== false ? value => this.#theme.bg(getStateBgColor(state), value) : undefined,
+			);
+		}
+		return this.#plainText.render(width);
+	}
+
+	get debugChildren(): readonly Component[] {
+		return this.#renderedChildren;
+	}
+
+	get wantsKeyRelease(): boolean {
+		return this.#renderedChildren.some(child => child.wantsKeyRelease === true);
+	}
+
+	handleInput(data: string): void {
+		for (const child of this.#renderedChildren) child.handleInput?.(data);
+	}
+
+	setIgnoreTight(ignore: boolean): void {
+		this.#options.ignoreTight = ignore;
+		this.#plainText.setIgnoreTight(ignore);
+		for (const child of this.#renderedChildren) child.setIgnoreTight?.(ignore);
+		this.invalidate();
+	}
+
+	invalidate(): void {
+		this.#block.invalidate();
+		this.#lastBlockOptions = undefined;
+		this.#plainKey = "";
+		this.#plainText.invalidate();
+		for (const child of this.#renderedChildren) child.invalidate?.();
+		this.#options.onInvalidate?.();
+	}
+
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		for (const child of this.#renderedChildren) child.dispose?.();
+		this.#options.onDispose?.();
+		this.#renderedChildren = [];
+	}
+}
+
+/** Construct a lazy framed tool card. */
+export function framedToolCard(
+	theme: Theme,
+	build: (context: ToolCardBuildContext) => ToolCardSnapshot,
+	options: Omit<ToolCardOptions, "variant"> = {},
+): ToolCard {
+	return new ToolCard(theme, { ...options, variant: "framed" }, build);
+}
+
+/** Construct a lazy inline tool card, optionally state-tinted. */
+export function plainToolCard(
+	theme: Theme,
+	build: (context: ToolCardBuildContext) => ToolCardSnapshot,
+	options: Omit<ToolCardOptions, "variant"> = {},
+): ToolCard {
+	return new ToolCard(theme, { ...options, variant: "plain" }, build);
+}

package/src/render/tree-list.ts

@@ -0,0 +1,188 @@
+/**
+ * Hierarchical tree list rendering helper.
+ */
+
+import type { Theme } from "../theme/theme";
+import { visibleWidth } from "../utils";
+import { TreeView } from "../components/tree-view";
+import { formatMoreItems } from "./render-utils";
+import type { TreeContext } from "./types";
+import { getTreeBranch, getTreeContinuePrefix } from "./utils";
+
+/** Tree items and callbacks controlling their presentation. */
+export interface TreeListOptions<T> {
+	items: T[];
+	expanded?: boolean;
+	maxCollapsed?: number;
+	/** Strict total-line budget for collapsed mode. When set (and not expanded),
+	 *  rendered item lines plus the trailing summary line must fit within this budget.
+	 */
+	maxCollapsedLines?: number;
+	itemType?: string;
+	truncateFrom?: "start" | "end";
+	/** Caller-supplied trailing summary line. When set (and not expanded),
+	 *  `renderTreeList` renders exactly the provided `items` (the caller has
+	 *  already applied its own selection/cap) and appends this text as the
+	 *  final `└` row, with the last item using `├`. Empty string renders the
+	 *  items with no summary. Bypasses the built-in truncation/`maxCollapsed`
+	 *  path. */
+	trailingSummary?: string;
+	/** Called once per item with `isLast: false` during budget calculation;
+	 *  line count MUST NOT vary based on `isLast`. */
+	renderItem: (item: T, context: TreeContext) => string | string[];
+}
+
+type TreeListRow = { kind: "item"; index: number; lines: string[] } | { kind: "summary"; text: string };
+
+/** Render tree items with themed branches and optional expansion. */
+export function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): string[] {
+	const {
+		items,
+		expanded = false,
+		maxCollapsed = 8,
+		maxCollapsedLines,
+		itemType = "item",
+		truncateFrom = "end",
+		renderItem,
+	} = options;
+	const maxItems = expanded ? items.length : Math.min(items.length, maxCollapsed);
+	const linesBudget = !expanded && maxCollapsedLines !== undefined ? maxCollapsedLines : Infinity;
+	const branchPrefix = `${theme.fg("dim", getTreeBranch(false, theme))} `;
+	const lastPrefix = `${theme.fg("dim", getTreeBranch(true, theme))} `;
+	const branchContinuePrefix = theme.fg("dim", getTreeContinuePrefix(false, theme));
+	const lastContinuePrefix = theme.fg("dim", getTreeContinuePrefix(true, theme));
+	const prefixWidth = Math.max(
+		visibleWidth(branchPrefix),
+		visibleWidth(lastPrefix),
+		visibleWidth(branchContinuePrefix),
+		visibleWidth(lastContinuePrefix),
+	);
+
+	const toItemRow = (itemIndex: number): TreeListRow => {
+		const rendered = renderItem(items[itemIndex], {
+			index: itemIndex,
+			isLast: false,
+			depth: 0,
+			theme,
+			prefix: "",
+			continuePrefix: "",
+			prefixWidth,
+		});
+		return { kind: "item", index: itemIndex, lines: Array.isArray(rendered) ? rendered : rendered ? [rendered] : [] };
+	};
+
+	// Caller-driven collapse: render exactly the provided items (the caller
+	// already picked/capped them) plus an optional trailing summary row. The
+	// walking-viewport todo policy uses this so item selection lives in the
+	// todo domain, not here.
+	if (!expanded && options.trailingSummary !== undefined) {
+		const summary = options.trailingSummary;
+		const roots: TreeListRow[] = [];
+		for (let i = 0; i < items.length; i++) {
+			roots.push(toItemRow(i));
+		}
+		if (summary !== "") {
+			roots.push({ kind: "summary", text: theme.fg("muted", summary) });
+		}
+		return renderTreeListRows(roots, theme);
+	}
+
+	const candidateIndices: number[] = [];
+	if (truncateFrom === "start") {
+		const startCandidateIdx = Math.max(0, items.length - maxItems);
+		for (let i = startCandidateIdx; i < items.length; i++) {
+			candidateIndices.push(i);
+		}
+	} else {
+		for (let i = 0; i < maxItems; i++) {
+			candidateIndices.push(i);
+		}
+	}
+
+	// Pre-render each candidate item once.
+	// isLast cannot be known at this point (fittingCount is not yet determined);
+	// renderItem implementations MUST NOT vary line count based on isLast.
+	const preRendered: string[][] = [];
+	for (let i = 0; i < candidateIndices.length; i++) {
+		const itemIdx = candidateIndices[i];
+		const rendered = renderItem(items[itemIdx], {
+			index: itemIdx,
+			isLast: false,
+			depth: 0,
+			theme,
+			prefix: "",
+			continuePrefix: "",
+			prefixWidth,
+		});
+		preRendered.push(Array.isArray(rendered) ? rendered : rendered ? [rendered] : []);
+	}
+
+	let displayedSlice: { start: number; end: number };
+	let remaining: number;
+	let fittedLineCount = 0;
+
+	if (truncateFrom === "start") {
+		let fittingCount = candidateIndices.length;
+		if (linesBudget !== Infinity) {
+			fittingCount = 0;
+			for (let i = candidateIndices.length - 1; i >= 0; i--) {
+				const count = preRendered[i].length;
+				const remainingBefore = candidateIndices[i];
+				const reservedSummaryLines = remainingBefore > 0 ? 1 : 0;
+				if (fittedLineCount + count + reservedSummaryLines > linesBudget) break;
+				fittedLineCount += count;
+				fittingCount++;
+			}
+		}
+		const start = candidateIndices.length - fittingCount;
+		displayedSlice = { start, end: candidateIndices.length };
+		remaining = candidateIndices.length > 0 ? candidateIndices[start] : 0;
+	} else {
+		let fittingCount = candidateIndices.length;
+		if (linesBudget !== Infinity) {
+			fittingCount = 0;
+			for (let i = 0; i < candidateIndices.length; i++) {
+				const count = preRendered[i].length;
+				const remainingAfter = items.length - (i + 1);
+				const reservedSummaryLines = remainingAfter > 0 ? 1 : 0;
+				if (fittedLineCount + count + reservedSummaryLines > linesBudget) break;
+				fittedLineCount += count;
+				fittingCount = i + 1;
+			}
+		}
+		displayedSlice = { start: 0, end: fittingCount };
+		remaining = items.length - fittingCount;
+	}
+
+	const hasSummary = !expanded && remaining > 0 && (linesBudget === Infinity || fittedLineCount < linesBudget);
+
+	const roots: TreeListRow[] = [];
+	if (truncateFrom === "start" && hasSummary) {
+		roots.push({ kind: "summary", text: theme.fg("muted", formatMoreItems(remaining, itemType)) });
+	}
+	for (let i = displayedSlice.start; i < displayedSlice.end; i++) {
+		roots.push({ kind: "item", index: candidateIndices[i], lines: preRendered[i]! });
+	}
+	if (truncateFrom === "end" && hasSummary) {
+		roots.push({ kind: "summary", text: theme.fg("muted", formatMoreItems(remaining, itemType)) });
+	}
+	return renderTreeListRows(roots, theme);
+}
+
+/**
+ * Emit pre-rendered item/summary roots through the shared keyed hierarchy.
+ * Roots are siblings in display order, so the first N-1 rows draw `├` and the
+ * final row draws `└` — matching the historical branch/continuation geometry.
+ * Formatting adapters render unbounded, so truncation stays disabled here.
+ */
+function renderTreeListRows(roots: TreeListRow[], theme: Theme): string[] {
+	const tree = new TreeView<TreeListRow, number>({
+		roots,
+		getKey: item => (item.kind === "summary" ? -1 : item.index),
+		getChildren: () => [],
+		theme,
+		truncateRows: false,
+		renderRow: item => (item.kind === "summary" ? [item.text] : item.lines),
+	});
+	return [...tree.render(Number.POSITIVE_INFINITY)];
+}

package/src/render/types.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared types for TUI rendering components.
+ */
+import type { Theme } from "../theme/theme";
+
+/** Visual state of a rendered tool output. */
+export type State = "pending" | "running" | "success" | "error" | "warning";
+
+/** Position and theme context passed to tree item renderers. */
+export interface TreeContext {
+	index: number;
+	isLast: boolean;
+	depth: number;
+	theme: Theme;
+	prefix: string;
+	continuePrefix: string;
+	/** Maximum rendered branch/continuation prefix width reserved during pre-rendering. */
+	prefixWidth?: number;
+}