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

package/src/render/code-cell.ts

@@ -0,0 +1,244 @@
+/**
+ * Render a code or markdown cell with optional output section.
+ */
+import { Markdown } from "../components/markdown";
+import { getMarkdownTheme, highlightCode, type Theme } from "../theme/theme";
+import { formatDuration, formatExpandHint, formatMoreItems, formatStatusIcon, replaceTabs } from "./render-utils";
+import { outputBlockContentWidth, renderOutputBlock } from "./output-block";
+import { formatOutputPaneLines, splitTerminalOutputLines, styleToolOutputLine } from "./output-pane";
+import type { State } from "./types";
+
+/** Content and display limits for a code preview with optional output. */
+export interface CodeCellOptions {
+	code: string;
+	language?: string;
+	index?: number;
+	total?: number;
+	title?: string;
+	status?: "pending" | "running" | "warning" | "complete" | "error";
+	spinnerFrame?: number;
+	duration?: number;
+	output?: string;
+	outputMaxLines?: number;
+	codeMaxLines?: number;
+	/**
+	 * Show the LAST `codeMaxLines` rows (the live streaming edge) instead of the
+	 * first, with a "… N earlier lines" marker on top. Lets a pending preview
+	 * follow code as it is written while staying bounded. Ignored when `expanded`.
+	 */
+	codeTail?: boolean;
+	expanded?: boolean;
+	/**
+	 * Prefix the header with the cell's language icon (resolved through the
+	 * active symbol preset: nerd-font devicon, unicode emoji, or ascii
+	 * shorthand). Opt-in so only the eval kernel renderer labels each cell;
+	 * read/write/browser code cells stay icon-free.
+	 */
+	showLanguage?: boolean;
+	width: number;
+	codeStartLine?: number;
+	codeLineNumbers?: Array<number | null>;
+}
+
+function getState(status?: CodeCellOptions["status"]): State | undefined {
+	if (!status) return undefined;
+	if (status === "complete") return "success";
+	if (status === "error") return "error";
+	if (status === "warning") return "warning";
+	if (status === "running") return "running";
+	return "pending";
+}
+
+function formatHeader(options: CodeCellOptions, theme: Theme): { title: string; meta?: string } {
+	const { index, total, title, status, spinnerFrame, duration, language, showLanguage } = options;
+	const parts: string[] = [];
+	if (showLanguage && language) {
+		const langIcon = theme.getLangIconStyled(language);
+		if (langIcon) parts.push(langIcon);
+	}
+	if (status) {
+		const icon = formatStatusIcon(
+			status === "complete"
+				? "done"
+				: status === "error"
+					? "error"
+					: status === "warning"
+						? "warning"
+						: status === "running"
+							? "running"
+							: "pending",
+			theme,
+			spinnerFrame,
+		);
+		if (status === "pending" || status === "running") {
+			parts.push(`${icon} ${theme.fg("muted", status)}`);
+		} else {
+			parts.push(icon);
+		}
+	}
+	if (index !== undefined && total !== undefined && total > 1) {
+		parts.push(theme.fg("accent", `[${index + 1}/${total}]`));
+	}
+	if (title) {
+		parts.push(theme.fg("toolTitle", title));
+	}
+	const headerTitle = parts.length > 0 ? parts.join(" ") : theme.fg("toolTitle", "Code");
+
+	const metaParts: string[] = [];
+	if (duration !== undefined) {
+		metaParts.push(theme.fg("dim", `(${formatDuration(duration)})`));
+	}
+	if (metaParts.length === 0) return { title: headerTitle };
+	return { title: headerTitle, meta: metaParts.join(theme.fg("dim", theme.sep.dot)) };
+}
+
+function renderCellOutput(
+	output: string | undefined,
+	expanded: boolean,
+	outputMaxLines: number,
+	theme: Theme,
+): readonly string[] {
+	if (!output?.trim()) return [];
+	return formatOutputPaneLines(
+		{
+			lines: splitTerminalOutputLines(output),
+			expanded,
+			collapsedMaxLines: outputMaxLines,
+			edge: "head",
+			styleLine: line => styleToolOutputLine(line, theme),
+			formatHidden: hidden => formatMoreItems(hidden, "line"),
+		},
+		theme,
+	).lines;
+}
+
+/** Render a syntax-highlighted code preview and its optional output block. */
+export function renderCodeCell(options: CodeCellOptions, theme: Theme): string[] {
+	const {
+		code,
+		language,
+		output,
+		expanded = false,
+		outputMaxLines = 6,
+		codeMaxLines = 12,
+		width,
+		codeStartLine,
+		codeLineNumbers,
+	} = options;
+	const { title, meta } = formatHeader(options, theme);
+	const state = getState(options.status);
+
+	const normalizedCode = replaceTabs(code ?? "");
+	const rawCodeLines = splitTerminalOutputLines(normalizedCode);
+	const maxCodeLines = expanded ? rawCodeLines.length : Math.min(rawCodeLines.length, codeMaxLines);
+	const hiddenCodeLines = rawCodeLines.length - maxCodeLines;
+	const tail = options.codeTail === true && !expanded && hiddenCodeLines > 0;
+	const startIndex = tail ? rawCodeLines.length - maxCodeLines : 0;
+	const visibleCode = rawCodeLines.slice(startIndex, startIndex + maxCodeLines).join("\n");
+	const codeLines = highlightCode(visibleCode, language);
+
+	let visibleLineNumbers: Array<number | null> | undefined;
+	let lineNumberWidth = 0;
+	if (codeLineNumbers) {
+		visibleLineNumbers = codeLineNumbers.slice(startIndex, startIndex + maxCodeLines);
+	} else if (codeStartLine !== undefined) {
+		visibleLineNumbers = Array.from({ length: maxCodeLines }, (_, i) => codeStartLine + startIndex + i);
+	}
+
+	if (visibleLineNumbers) {
+		const validLineNums = visibleLineNumbers.filter((n): n is number => n !== null && n !== undefined);
+		const maxVal = validLineNums.length > 0 ? Math.max(...validLineNums) : 0;
+		if (maxVal > 0) {
+			lineNumberWidth = Math.max(2, String(maxVal).length);
+		}
+	}
+
+	if (lineNumberWidth > 0 && visibleLineNumbers) {
+		for (let i = 0; i < codeLines.length; i++) {
+			const lineNum = visibleLineNumbers[i];
+			const gutter =
+				lineNum !== null && lineNum !== undefined
+					? String(lineNum).padStart(lineNumberWidth, " ")
+					: " ".repeat(lineNumberWidth);
+			codeLines[i] = theme.fg("dim", `${gutter} `) + codeLines[i];
+		}
+	}
+
+	if (hiddenCodeLines > 0) {
+		const hint = formatExpandHint(theme, expanded, hiddenCodeLines > 0);
+		const gutterPad = lineNumberWidth > 0 ? " ".repeat(lineNumberWidth + 1) : "";
+		if (tail) {
+			// Earlier rows scrolled above the live tail window — mark them on top so
+			// the newest streamed line stays pinned to the bottom of the box.
+			const earlier = `… ${hiddenCodeLines} earlier line${hiddenCodeLines === 1 ? "" : "s"}${hint ? ` ${hint}` : ""}`;
+			codeLines.unshift(theme.fg("dim", gutterPad + earlier));
+		} else {
+			const moreLine = `${formatMoreItems(hiddenCodeLines, "line")}${hint ? ` ${hint}` : ""}`;
+			codeLines.push(theme.fg("dim", gutterPad + moreLine));
+		}
+	}
+
+	const outputLines = renderCellOutput(output, expanded, outputMaxLines, theme);
+
+	const sections: Array<{ label?: string; lines: readonly string[] }> = [{ lines: codeLines }];
+	if (outputLines.length > 0) {
+		sections.push({ label: theme.fg("toolTitle", "Output"), lines: outputLines });
+	}
+
+	return renderOutputBlock({ header: title, headerMeta: meta, state, sections, width }, theme);
+}
+
+/** Content and display limits for a Markdown preview with optional output. */
+export interface MarkdownCellOptions {
+	content: string;
+	index?: number;
+	total?: number;
+	title?: string;
+	status?: "pending" | "running" | "warning" | "complete" | "error";
+	spinnerFrame?: number;
+	duration?: number;
+	output?: string;
+	outputMaxLines?: number;
+	contentMaxLines?: number;
+	expanded?: boolean;
+	width: number;
+}
+
+/** Render a Markdown preview and its optional output block. */
+export function renderMarkdownCell(options: MarkdownCellOptions, theme: Theme): string[] {
+	const { content, output, expanded = false, outputMaxLines = 6, contentMaxLines = 12, width } = options;
+	const codeOptions: CodeCellOptions = {
+		code: "",
+		index: options.index,
+		total: options.total,
+		title: options.title,
+		status: options.status,
+		spinnerFrame: options.spinnerFrame,
+		duration: options.duration,
+		width,
+	};
+	const { title, meta } = formatHeader(codeOptions, theme);
+	const state = getState(options.status);
+
+	// Markdown component manages its own wrapping at the same inner width as
+	// `renderOutputBlock`, so collapsed row caps are applied after final wrapping.
+	const innerWidth = Math.max(20, outputBlockContentWidth(width));
+	const allLines = content.trim() ? new Markdown(content, 0, 0, getMarkdownTheme()).render(innerWidth) : [];
+	const maxContentLines = expanded ? allLines.length : Math.min(allLines.length, contentMaxLines);
+	const contentLines = allLines.slice(0, maxContentLines);
+	const hiddenContentLines = allLines.length - maxContentLines;
+	if (hiddenContentLines > 0) {
+		const hint = formatExpandHint(theme, expanded, hiddenContentLines > 0);
+		const moreLine = `${formatMoreItems(hiddenContentLines, "line")}${hint ? ` ${hint}` : ""}`;
+		contentLines.push(theme.fg("dim", moreLine));
+	}
+
+	const outputLines = renderCellOutput(output, expanded, outputMaxLines, theme);
+
+	const sections: Array<{ label?: string; lines: readonly string[] }> = [{ lines: contentLines }];
+	if (outputLines.length > 0) {
+		sections.push({ label: theme.fg("toolTitle", "Output"), lines: outputLines });
+	}
+
+	return renderOutputBlock({ header: title, headerMeta: meta, state, sections, width }, theme);
+}

package/src/render/file-list.ts

@@ -0,0 +1,58 @@
+/**
+ * Render file listings with optional icons and metadata.
+ */
+import { getLanguageFromPath } from "../lang-from-path";
+import type { Theme } from "../theme/theme";
+import { renderTreeList } from "./tree-list";
+
+/** A file-list item with optional display metadata. */
+export interface FileEntry {
+	path: string;
+	/** Absolute filesystem path. When provided together with {@link FileListOptions.hyperlinkFn}, the
+	 * rendered path text is wrapped in an OSC 8 hyperlink. */
+	absPath?: string;
+	isDirectory?: boolean;
+	meta?: string;
+}
+
+/** Files and presentation options for a tree-style listing. */
+export interface FileListOptions {
+	files: FileEntry[];
+	expanded?: boolean;
+	maxCollapsed?: number;
+	showIcons?: boolean;
+	/** When provided, called with the entry's absolute path and the ANSI-styled display string to
+	 * optionally wrap the path in an OSC 8 hyperlink. Only invoked when {@link FileEntry.absPath} is set. */
+	hyperlinkFn?: (absPath: string, displayText: string) => string;
+}
+
+/** Render file entries as a themed tree listing. */
+export function renderFileList(options: FileListOptions, theme: Theme): string[] {
+	const { files, expanded = false, maxCollapsed = 8, showIcons = true, hyperlinkFn } = options;
+
+	return renderTreeList(
+		{
+			items: files,
+			expanded,
+			maxCollapsed,
+			itemType: "file",
+			renderItem: entry => {
+				const isDirectory = entry.isDirectory ?? entry.path.endsWith("/");
+				const displayPath = entry.path;
+				const lang = isDirectory ? undefined : getLanguageFromPath(displayPath);
+				const icon = !showIcons
+					? ""
+					: isDirectory
+						? theme.fg("accent", theme.icon.folder)
+						: theme.fg("muted", theme.getLangIcon(lang));
+				const labelColor = isDirectory ? "accent" : "toolOutput";
+				const meta = entry.meta ? ` ${theme.fg("dim", entry.meta)}` : "";
+				const iconPrefix = icon ? `${icon} ` : "";
+				const pathStr = theme.fg(labelColor, displayPath);
+				const linkedPath = entry.absPath && hyperlinkFn ? hyperlinkFn(entry.absPath, pathStr) : pathStr;
+				return `${iconPrefix}${linkedPath}${meta}`;
+			},
+		},
+		theme,
+	);
+}

package/src/render/hyperlink.ts

@@ -0,0 +1,192 @@
+/**
+ * OSC 8 terminal hyperlink support for paths and URLs.
+ *
+ * Wraps display text in `ESC ] 8 ; id=HASH ; URI ESC \ TEXT ESC ] 8 ; ; ESC \`
+ * sequences when the active terminal supports hyperlinks and the user setting
+ * permits it. Falls back to plain text when disabled.
+ */
+import * as url from "node:url";
+import { setTerminalHyperlinks, TERMINAL, type TerminalId } from "../terminal-capabilities";
+
+const OSC = "\x1b]";
+const ST = "\x1b\\";
+const BEL = "\x07";
+
+/**
+ * The terminal's detected OSC 8 capability, captured once at import before any
+ * policy application mutates {@link TERMINAL}.hyperlinks. `auto` resolves against
+ * this immutable value so a prior `always`/`off` selection can never poison
+ * detection when the user switches back to `auto`.
+ */
+const DETECTED_TERMINAL_HYPERLINKS = TERMINAL.hyperlinks;
+type HyperlinkMode = "off" | "auto" | "always";
+let hyperlinkMode: HyperlinkMode = "auto";
+
+/** Stable 8-char hex ID derived from a URI — hints terminals to coalesce identical adjacent links. */
+function buildLinkId(uri: string): string {
+	let h = 0;
+	for (let i = 0; i < uri.length; i++) {
+		// FNV-1a-inspired mix — good enough for a UI hint, no deps
+		h = (Math.imul(31, h) + uri.charCodeAt(i)) | 0;
+	}
+	return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * Build the OSC 8 target for a file path on `terminalId`.
+ *
+ * A `file:` URI handed to an editor has to be a plain path. `Paths.get(URI)`
+ * rejects one carrying a query or a fragment outright — `IllegalArgumentException:
+ * URI has a query component` / `URI has a fragment component` — so appending
+ * `?line=` made every JVM-based language server (Kotlin LSP, Eclipse JDT LS)
+ * fail *every* request for the resulting document, and VS Code reads the query
+ * as part of the resource identity rather than as a cursor position: a blank
+ * editor tab that navigates nowhere and persists across window reloads (#12109).
+ *
+ * The VS Code family instead navigates the documented
+ * `vscode://file/<path>:<line>:<col>` form. Everywhere else the plain `file:`
+ * URI is right, with the location left in the visible text — terminals that
+ * parse a `path:line:col` suffix resolve that on their own.
+ */
+export function fileUriForTerminal(
+	filePath: string,
+	opts: { line?: number; col?: number } | undefined,
+	terminalId: TerminalId,
+): string {
+	if (terminalId !== "vscode") return url.pathToFileURL(filePath).href;
+	// vscode:// takes a filesystem path with forward slashes. Encode each
+	// segment independently so separators and a Windows drive colon stay
+	// structural while reserved bytes in file names cannot become URI syntax.
+	const asPath = filePath.replace(/\\/gu, "/");
+	const encodedPath = asPath
+		.split("/")
+		.map((segment, index) => (index === 0 && /^[a-z]:$/iu.test(segment) ? segment : encodeURIComponent(segment)))
+		.join("/");
+	const position =
+		opts?.line === undefined ? "" : opts.col === undefined ? `:${opts.line}` : `:${opts.line}:${opts.col}`;
+	return `vscode://file${encodedPath.startsWith("/") ? "" : "/"}${encodedPath}${position}`;
+}
+
+/** Build the OSC 8 target for `filePath` on this terminal. */
+function buildFileUri(filePath: string, opts?: { line?: number; col?: number }): string {
+	return fileUriForTerminal(filePath, opts, TERMINAL.id);
+}
+
+/**
+ * Returns true when OSC 8 hyperlinks should be emitted.
+ *
+ * Respects `tui.hyperlinks` setting:
+ * - `"off"`: never
+ * - `"auto"`: when `process.stdout.isTTY`, `NO_COLOR` is unset, and the detected terminal reports hyperlink support
+ * - `"always"`: unconditionally (useful for viewers that support OSC 8 without advertising it)
+ * Uses the last policy pushed by the host, defaulting to `"auto"`.
+ */
+export function isHyperlinkEnabled(): boolean {
+	return resolveHyperlinkMode(hyperlinkMode);
+}
+
+function resolveHyperlinkMode(mode: HyperlinkMode): boolean {
+	if (mode === "off") return false;
+	if (mode === "always") return true;
+	// auto: respect the detected capability (immutable snapshot, not the mutable
+	// runtime flag that applyHyperlinkSetting overwrites) and NO_COLOR.
+	if (Bun.env.NO_COLOR) return false;
+	if (!process.stdout.isTTY) return false;
+	return DETECTED_TERMINAL_HYPERLINKS;
+}
+
+/**
+ * Push the resolved `tui.hyperlinks` policy into {@link TERMINAL}.hyperlinks, the
+ * effective flag that pi-tui renderers gating on it directly — the Markdown
+ * component's `[text](url)`/bare-URL links and the status-line PR link — consult.
+ *
+ * Detection stays immutable in {@link DETECTED_TERMINAL_HYPERLINKS}, so this only
+ * ever writes the effective decision; `auto` transitions restore real detection
+ * via {@link isHyperlinkEnabled}. Called at TUI startup and whenever the setting
+ * changes at runtime.
+ * Accepts the raw (unvalidated) setting value; anything but a known mode falls
+ * back to the last policy pushed by the host.
+ */
+export function applyHyperlinkSetting(mode?: unknown): void {
+	if (mode === "off" || mode === "auto" || mode === "always") hyperlinkMode = mode;
+	setTerminalHyperlinks(isHyperlinkEnabled());
+}
+
+function safeHyperlinkUri(uri: string): string | undefined {
+	if (!uri || /[\x00-\x1f\x7f]/.test(uri)) return undefined;
+	return uri;
+}
+
+function wrapHyperlinkCore(uri: string, displayText: string, terminator: typeof ST | typeof BEL): string {
+	// Do not double-wrap if the text already embeds an OSC 8 sequence.
+	if (displayText.includes("\x1b]8;")) return displayText;
+	const safeUri = safeHyperlinkUri(uri);
+	if (!safeUri) return displayText;
+	const id = buildLinkId(safeUri);
+	return `${OSC}8;id=${id};${safeUri}${terminator}${displayText}${OSC}8;;${terminator}`;
+}
+
+function wrapHyperlink(uri: string, displayText: string): string {
+	if (!isHyperlinkEnabled()) return displayText;
+	return wrapHyperlinkCore(uri, displayText, ST);
+}
+
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at `uri`.
+ *
+ * Returns `displayText` unchanged when hyperlinks are disabled, `uri` contains
+ * terminal control bytes, or `displayText` already contains an OSC 8 sequence.
+ */
+export function uriHyperlink(uri: string, displayText: string): string {
+	return wrapHyperlink(uri, displayText);
+}
+
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at an HTTP(S) URL.
+ * `www.example.com` inputs are linked as `https://www.example.com`.
+ */
+export function urlHyperlink(url: string, displayText: string): string {
+	const normalized = url.match(/^www\./i) ? `https://${url}` : url;
+	try {
+		const parsed = new URL(normalized);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return displayText;
+		return wrapHyperlink(parsed.href, displayText);
+	} catch {
+		return displayText;
+	}
+}
+
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at an HTTP(S) URL,
+ * bypassing terminal capability auto-detection. Used for auth prompts where
+ * an inert "click" label blocks login on terminals whose capabilities are
+ * not advertised. Still returns plain text when the host has explicitly opted
+ * out by pushing the `"off"` policy.
+ */
+export function urlHyperlinkAlways(url: string, displayText: string): string {
+	if (hyperlinkMode === "off") return displayText;
+	const normalized = url.match(/^www\./i) ? `https://${url}` : url;
+	try {
+		const parsed = new URL(normalized);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return displayText;
+		return wrapHyperlinkCore(parsed.href, displayText, BEL);
+	} catch {
+		return displayText;
+	}
+}
+
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at a filesystem path.
+ *
+ * Returns `displayText` unchanged when hyperlinks are disabled or when
+ * the text already contains an OSC 8 sequence (prevents double-wrapping).
+ * Relative paths resolve against the current working directory before URI
+ * encoding so the OSC 8 target is always a valid `file://` URL.
+ *
+ * @param filePath - Filesystem path
+ * @param displayText - Text to render as the hyperlink anchor (may contain ANSI codes)
+ * @param opts - Optional line/col position appended as `?line=N&col=M` query params
+ */
+export function fileHyperlink(filePath: string, displayText: string, opts?: { line?: number; col?: number }): string {
+	return wrapHyperlink(buildFileUri(filePath, opts), displayText);
+}

package/src/render/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Public exports for shared TUI components.
+ */
+
+export * from "./code-cell";
+export * from "./file-list";
+export * from "./hyperlink";
+export * from "./output-block";
+export * from "./output-pane";
+export * from "./render-utils";
+export * from "./sixel";
+export * from "./status-line";
+export * from "./tool-card";
+export * from "./tree-list";
+export * from "./types";
+export * from "./utils";
+export * from "./width-aware-text";