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

package/src/chrome/diff.ts

@@ -0,0 +1,266 @@
+import { diffWords } from "@oh-my-pi/pi-natives";
+import { DEFAULT_TAB_WIDTH, sanitizeText } from "@oh-my-pi/pi-utils";
+import { theme as activeTheme, getLanguageFromPath, highlightCode, type Theme } from "../theme/index";
+import { type CodeFrameMarker, formatCodeFrameLine, replaceTabs } from "../render/render-utils";
+/** SGR dim on / normal intensity — additive, preserves fg/bg colors. */
+const DIM = "\x1b[2m";
+const DIM_OFF = "\x1b[22m";
+
+/**
+ * Visualize leading whitespace (indentation) with dim glyphs.
+ * Tabs become ` → ` and spaces become `·`. Only affects whitespace
+ * before the first non-whitespace character; remaining tabs in code
+ * content are replaced with spaces (like replaceTabs).
+ */
+function visualizeIndent(text: string): string {
+	const match = text.match(/^([ \t]+)/);
+	if (!match) return replaceTabs(text);
+	const indent = match[1];
+	const rest = text.slice(indent.length);
+	const tabWidth = DEFAULT_TAB_WIDTH;
+	const leftPadding = Math.floor(tabWidth / 2);
+	const rightPadding = Math.max(0, tabWidth - leftPadding - 1);
+	const tabMarker = `${DIM}${" ".repeat(leftPadding)}→${" ".repeat(rightPadding)}${DIM_OFF}`;
+	let visible = "";
+	for (const ch of indent) {
+		if (ch === "\t") {
+			visible += tabMarker;
+		} else {
+			visible += `${DIM}·${DIM_OFF}`;
+		}
+	}
+	return `${visible}${replaceTabs(rest)}`;
+}
+
+/**
+ * Parse diff line to extract prefix, line number, and content.
+ * Supported formats: "+123|content" (canonical) and "+123 content" (legacy).
+ */
+function parseDiffLine(line: string): { prefix: CodeFrameMarker; lineNum: string; content: string } | null {
+	const canonical = line.match(/^([+-\s])(\s*\d+)\|(.*)$/);
+	if (canonical) {
+		return { prefix: canonical[1] as CodeFrameMarker, lineNum: canonical[2] ?? "", content: canonical[3] ?? "" };
+	}
+	const legacy = line.match(/^([+-\s])(?:(\s*\d+)\s)?(.*)$/);
+	if (!legacy) return null;
+	return { prefix: legacy[1] as CodeFrameMarker, lineNum: legacy[2] ?? "", content: legacy[3] ?? "" };
+}
+
+/**
+ * Compute word-level diff and render with inverse on changed parts.
+ * Uses diffWords which groups whitespace with adjacent words for cleaner highlighting.
+ * Strips leading whitespace from inverse to avoid highlighting indentation.
+ */
+function renderIntraLineDiff(
+	oldContent: string,
+	newContent: string,
+	renderTheme: Theme,
+): { removedLine: string; addedLine: string } {
+	const wordDiff = diffWords(oldContent, newContent);
+
+	let removedLine = "";
+	let addedLine = "";
+	let isFirstRemoved = true;
+	let isFirstAdded = true;
+
+	for (const part of wordDiff) {
+		if (part.removed) {
+			let value = part.value;
+			// Strip leading whitespace from the first removed part
+			if (isFirstRemoved) {
+				const leadingWs = value.match(/^(\s*)/)?.[1] || "";
+				value = value.slice(leadingWs.length);
+				removedLine += leadingWs;
+				isFirstRemoved = false;
+			}
+			if (value) {
+				removedLine += renderTheme.inverse(value);
+			}
+		} else if (part.added) {
+			let value = part.value;
+			// Strip leading whitespace from the first added part
+			if (isFirstAdded) {
+				const leadingWs = value.match(/^(\s*)/)?.[1] || "";
+				value = value.slice(leadingWs.length);
+				addedLine += leadingWs;
+				isFirstAdded = false;
+			}
+			if (value) {
+				addedLine += renderTheme.inverse(value);
+			}
+		} else {
+			removedLine += part.value;
+			addedLine += part.value;
+		}
+	}
+
+	return { removedLine, addedLine };
+}
+
+export interface RenderDiffOptions {
+	/** File path used to resolve indentation (.editorconfig + defaults) */
+	filePath?: string;
+	/** Theme used for diff colors and syntax highlighting; defaults to the active TUI theme. */
+	theme?: Theme;
+}
+
+/**
+ * Render a diff string with colored lines and intra-line change highlighting.
+ * - Context lines: dim/gray
+ * - Removed lines: red, with inverse on changed tokens
+ * - Added lines: green, with inverse on changed tokens
+ */
+export function renderDiff(diffText: string, options: RenderDiffOptions = {}): string {
+	const renderTheme = options.theme ?? activeTheme;
+	const lines = sanitizeText(diffText).split("\n");
+	const result: string[] = [];
+	const parsedLines = lines.map(parseDiffLine);
+	// Reserve 3 gutter digits: a streaming preview re-renders this diff as it
+	// grows, and a width derived purely from the current max line number widens
+	// at the 100-line crossing — re-padding every already-rendered row, which
+	// breaks the transcript's append-only commit detection and forces a full
+	// recommit of the block into native scrollback. A constant gutter through
+	// 999 lines keeps streamed rows byte-identical to the final result render.
+	const lineNumberWidth = parsedLines.reduce((width, parsed) => {
+		const lineNumber = parsed?.lineNum.trim() ?? "";
+		return Math.max(width, lineNumber.length);
+	}, 3);
+
+	// Batch-highlight context (unedited) lines so consecutive lines tokenize
+	// with full multi-line context. Highlighting is a no-op when no language
+	// can be detected from the file path.
+	const contextHighlights = highlightContextLines(parsedLines, options.filePath, renderTheme);
+	// Track the line number rendered on the previous emitted line so we can
+	// blank out duplicate gutters. Two cases trigger this:
+	//  1. Single-line replacement (`-N` followed by `+N`) — the `+N` repeats `N`.
+	//  2. Insertion followed by context (`+N` then ` N` if producer used oldLine).
+	let prevLineNum = "";
+
+	const formatLine = (prefix: CodeFrameMarker, lineNum: string, content: string): string => {
+		if (lineNum.trim().length === 0) {
+			prevLineNum = "";
+			return `${prefix}${content}`;
+		}
+		const trimmed = lineNum.trim();
+		const displayNum = trimmed === prevLineNum ? "" : trimmed;
+		prevLineNum = trimmed;
+		return formatCodeFrameLine(prefix, displayNum, content, lineNumberWidth);
+	};
+
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i];
+		const parsed = parseDiffLine(line);
+
+		if (!parsed) {
+			prevLineNum = "";
+			// Blank gap rows (and legacy "..." markers from older transcripts)
+			// mark non-contiguous diff regions; display them as a single dim
+			// unicode ellipsis.
+			const trimmed = line.trim();
+			const isGapRow = trimmed.length === 0 || trimmed === "..." || trimmed === "…";
+			result.push(renderTheme.fg("toolDiffContext", isGapRow ? "…" : replaceTabs(line)));
+			i++;
+			continue;
+		}
+
+		if (parsed.prefix === "-") {
+			const removedLines: { lineNum: string; content: string }[] = [];
+			while (i < lines.length) {
+				const p = parseDiffLine(lines[i]);
+				if (p?.prefix !== "-") break;
+				removedLines.push({ lineNum: p.lineNum, content: p.content });
+				i++;
+			}
+
+			const addedLines: { lineNum: string; content: string }[] = [];
+			while (i < lines.length) {
+				const p = parseDiffLine(lines[i]);
+				if (p?.prefix !== "+") break;
+				addedLines.push({ lineNum: p.lineNum, content: p.content });
+				i++;
+			}
+
+			if (removedLines.length === 1 && addedLines.length === 1) {
+				const removed = removedLines[0];
+				const added = addedLines[0];
+
+				const { removedLine, addedLine } = renderIntraLineDiff(
+					replaceTabs(removed.content),
+					replaceTabs(added.content),
+					renderTheme,
+				);
+
+				result.push(
+					renderTheme.fg("toolDiffRemoved", formatLine("-", removed.lineNum, visualizeIndent(removedLine))),
+				);
+				result.push(renderTheme.fg("toolDiffAdded", formatLine("+", added.lineNum, visualizeIndent(addedLine))));
+			} else {
+				for (const removed of removedLines) {
+					result.push(
+						renderTheme.fg("toolDiffRemoved", formatLine("-", removed.lineNum, visualizeIndent(removed.content))),
+					);
+				}
+				for (const added of addedLines) {
+					result.push(
+						renderTheme.fg("toolDiffAdded", formatLine("+", added.lineNum, visualizeIndent(added.content))),
+					);
+				}
+			}
+		} else if (parsed.prefix === "+") {
+			result.push(renderTheme.fg("toolDiffAdded", formatLine("+", parsed.lineNum, visualizeIndent(parsed.content))));
+			i++;
+		} else {
+			const highlighted = contextHighlights.get(i);
+			const content = highlighted !== undefined ? replaceTabs(highlighted) : visualizeIndent(parsed.content);
+			result.push(renderTheme.fg("toolDiffContext", formatLine(" ", parsed.lineNum, content)));
+			i++;
+		}
+	}
+
+	return result.join("\n");
+}
+
+/**
+ * Batch-highlight runs of consecutive context lines.
+ * Returns a map keyed by index in `parsedLines` to the highlighted content
+ * for that line. Lines whose language is unknown are not added to the map,
+ * letting callers fall back to the existing rendering path.
+ */
+function highlightContextLines(
+	parsedLines: Array<{ prefix: CodeFrameMarker; lineNum: string; content: string } | null>,
+	filePath: string | undefined,
+	renderTheme: Theme,
+): Map<number, string> {
+	const map = new Map<number, string>();
+	const lang = filePath ? getLanguageFromPath(filePath) : undefined;
+	if (!lang) return map;
+
+	let runIndices: number[] = [];
+	let runContents: string[] = [];
+	const flush = () => {
+		if (runContents.length === 0) return;
+		const highlighted = highlightCode(runContents.join("\n"), lang, renderTheme);
+		for (let k = 0; k < runIndices.length; k++) {
+			map.set(runIndices[k], highlighted[k] ?? runContents[k]);
+		}
+		runIndices = [];
+		runContents = [];
+	};
+
+	for (let j = 0; j < parsedLines.length; j++) {
+		const p = parsedLines[j];
+		// Collapse markers ("...") are emitted as context lines but are not real
+		// code; highlighting them produces nonsense (e.g. "..." → spread operator)
+		// and would also stitch together unrelated context blocks across the gap.
+		const isCollapseMarker = p?.prefix === " " && (p.content === "..." || p.content === "…");
+		if (p && p.prefix === " " && !isCollapseMarker) {
+			runIndices.push(j);
+			runContents.push(p.content);
+		} else {
+			flush();
+		}
+	}
+	flush();
+	return map;
+}

package/src/chrome/dynamic-border.ts

@@ -0,0 +1,36 @@
+import type { Component } from "../tui";
+import { fgOrPlain, theme } from "../theme/index";
+/**
+ * Dynamic border component that adjusts to viewport width.
+ *
+ * Note: the module-level `theme` may be `undefined` — when loaded through jiti
+ * (separate module cache) or from a second `src` module graph in npm-package
+ * installs, where the host bundle assigns `theme` but this copy never sees it
+ * (issue #5366). Both the default color and `render()` degrade to plain,
+ * unstyled output instead of crashing the TUI.
+ */
+export class DynamicBorder implements Component {
+	#color: (str: string) => string;
+	#cachedWidth = -1;
+	#cachedLines: string[] | undefined;
+
+	constructor(color: (str: string) => string = str => fgOrPlain("border", str)) {
+		this.#color = color;
+	}
+
+	invalidate(): void {
+		this.#cachedWidth = -1;
+		this.#cachedLines = undefined;
+	}
+
+	render(width: number): readonly string[] {
+		if (this.#cachedLines && this.#cachedWidth === width) {
+			return this.#cachedLines;
+		}
+		const horizontal = typeof theme === "undefined" ? "─" : theme.boxRound.horizontal;
+		const lines = [this.#color(horizontal.repeat(Math.max(1, width)))];
+		this.#cachedWidth = width;
+		this.#cachedLines = lines;
+		return lines;
+	}
+}

package/src/chrome/error-block.ts

@@ -0,0 +1,63 @@
+import * as os from "node:os";
+import { replaceTabs, truncateToWidth, wrapTextWithAnsi } from "../utils";
+import { sanitizeText } from "@oh-my-pi/pi-utils";
+import { expandKeyHint, shortenEmbeddedPaths, TRUNCATE_LENGTHS } from "../render/render-utils";
+import { theme } from "../theme/index";
+/** Indent for every row after the first, so continuations hang under the prefix. */
+const CONTINUATION_INDENT = "  ";
+
+/**
+ * Plain, bounded error text to sanitize before applying terminal styles.
+ * Match embedded home paths (including quoted names with spaces), not URL
+ * paths or home-prefix siblings. Callers retain the original error for logs.
+ */
+export function sanitizeErrorLine(
+	error: unknown,
+	maxWidth: number = TRUNCATE_LENGTHS.LINE,
+	homeDir: string = os.homedir(),
+): string {
+	const message = error instanceof Error ? error.message : String(error);
+	const text = shortenEmbeddedPaths(replaceTabs(sanitizeText(message.replace(/\r\n?/g, "\n"))), homeDir, true);
+	return truncateToWidth(text.replace(/\s+/g, " ").trim() || "Unknown error", Math.max(0, maxWidth));
+}
+
+/**
+ * Format a provider error into at most `maxRows` wrapped rows for a
+ * `WidthAwareText` of `contentWidth` cells. Lines wrap to the render width
+ * instead of being cut at a fixed column, so a long single-line body — a raw
+ * 400 JSON envelope, a `raw-http-request=` dump path — stays readable. Blank
+ * lines are dropped. When rows are cut, a dim `… +N more lines (<key> to
+ * expand)` row follows; pass `Infinity` to keep every row. `styleLine` colors
+ * logical line `index` and supplies line 0's prefix (`Error: `, the banner
+ * glyph). Shared by the inline transcript error and the pinned banner.
+ */
+export function formatErrorBlock(
+	message: string,
+	contentWidth: number,
+	maxRows: number,
+	styleLine: (line: string, index: number) => string,
+): string {
+	const lines = replaceTabs(message)
+		.split("\n")
+		.map(line => line.trim())
+		.filter(line => line.length > 0);
+	if (lines.length === 0) lines.push("Unknown error");
+	const wrapWidth = Math.max(1, contentWidth - CONTINUATION_INDENT.length);
+	const rows: string[] = [];
+	for (let index = 0; index < lines.length; index++) {
+		for (const row of wrapTextWithAnsi(styleLine(lines[index]!, index), wrapWidth)) {
+			rows.push(rows.length === 0 ? row : `${CONTINUATION_INDENT}${row}`);
+		}
+	}
+	if (rows.length > maxRows) {
+		const hidden = rows.length - maxRows;
+		rows.length = maxRows;
+		rows.push(
+			theme.fg(
+				"dim",
+				`${CONTINUATION_INDENT}… +${hidden} more line${hidden === 1 ? "" : "s"} (${expandKeyHint()} to expand)`,
+			),
+		);
+	}
+	return rows.join("\n");
+}

package/src/chrome/form-theme.ts

@@ -0,0 +1,10 @@
+import type { FormFieldTheme } from "../components/form";
+import { theme } from "../theme/theme";
+
+/** Shared accent form-field theme used by overlay dialogs. */
+export const formTheme: FormFieldTheme = {
+	label: text => theme.bold(theme.fg("accent", text)),
+	description: text => theme.fg("muted", text),
+	error: text => theme.fg("error", text),
+	hint: text => theme.fg("dim", text),
+};

package/src/chrome/format.ts

@@ -0,0 +1,66 @@
+import { renderProgressBar } from "../components/progress-bar";
+import { shimmerText } from "../theme/shimmer";
+import { theme as currentTheme, type Theme } from "../theme/theme";
+
+/** Title-case a provider id for display (`openai-codex` → `Openai Codex`). */
+export function formatProviderName(provider: string): string {
+	return provider
+		.split(/[-_]/g)
+		.map(part => (part ? part[0].toUpperCase() + part.slice(1) : ""))
+		.join(" ");
+}
+
+/** Format a millisecond duration as a coarse-grained human label. */
+export function formatCoarseDuration(ms: number): string {
+	const seconds = Math.max(0, Math.round(ms / 1000));
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.round(seconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.round(minutes / 60);
+	if (hours < 48) return `${hours}h`;
+	const days = Math.round(hours / 24);
+	return `${days}d`;
+}
+
+type ProgressBarTheme = Pick<Theme, "bold" | "fg" | "getFgAnsi">;
+
+const unstyledProgressBarTheme: ProgressBarTheme = {
+	fg(_color, text) {
+		return text;
+	},
+	bold(text) {
+		return text;
+	},
+	getFgAnsi() {
+		return "";
+	},
+};
+
+function resolveProgressBarTheme(uiTheme: ProgressBarTheme | undefined): ProgressBarTheme {
+	return uiTheme ?? currentTheme ?? unstyledProgressBarTheme;
+}
+
+/**
+ * Render an ASCII progress bar with a trailing percent label.
+ * `fraction` is clamped to `[0, 1]`. `undefined` renders a dotted placeholder.
+ */
+export function renderAsciiBar(fraction: number | undefined, width = 24, uiTheme?: ProgressBarTheme): string {
+	const progressBarTheme = resolveProgressBarTheme(uiTheme);
+	const shimmer = (text: string): string => shimmerText(text, progressBarTheme);
+	if (fraction === undefined) {
+		return renderProgressBar(undefined, width, {
+			prefix: "[",
+			suffix: "]",
+			style: { filled: "·", empty: "·", indeterminate: "·", styleBar: shimmer },
+		});
+	}
+	return renderProgressBar(fraction, width, {
+		min: 0,
+		max: 1,
+		prefix: "[",
+		suffix: "]",
+		showPercentage: true,
+		formatPercentage: value => `${Math.round(value * 100)}%`,
+		style: { filled: "█", empty: "░", styleBar: shimmer },
+	});
+}

package/src/chrome/index.ts

@@ -0,0 +1,21 @@
+// Shared chat/overlay chrome: borders, panels, transcript container, diff and error blocks.
+export * from "./chat-block";
+export * from "./context-thresholds";
+export * from "./countdown-timer";
+export * from "./diff";
+export * from "./dynamic-border";
+export * from "./error-block";
+export * from "./keybinding-hints";
+export * from "./message-divider";
+export * from "./message-frame";
+export * from "./message-notice";
+export * from "./overlay-box";
+export * from "./segment-track";
+export * from "./select-list-mouse-routing";
+export * from "./selector-helpers";
+export * from "./shared";
+export * from "./streaming-panel";
+export * from "./tool-activity";
+export * from "./transcript-container";
+export * from "./transcript-status";
+export * from "./visual-truncate";

package/src/chrome/keybinding-hints.ts

@@ -0,0 +1,55 @@
+/**
+ * Utilities for formatting keybinding hints in the UI.
+ */
+import { getKeybindings, type Keybinding } from "../keybindings";
+import { type AppKeybinding, formatKeyHints, type KeybindingsManager } from "../app-keybindings";
+import { theme } from "../theme/index";
+/**
+ * Get display string for an editor action.
+ */
+export function editorKey(action: Keybinding): string {
+	return formatKeyHints(getKeybindings().getKeys(action));
+}
+
+/**
+ * Get display string for an app action.
+ */
+export function appKey(keybindings: KeybindingsManager, action: AppKeybinding): string {
+	return formatKeyHints(keybindings.getKeys(action));
+}
+
+/**
+ * Format a keybinding hint with consistent styling: dim key, muted description.
+ * Looks up the key from editor keybindings automatically.
+ *
+ * @param action - Keybinding action name (e.g., "tui.select.confirm", "app.tools.expand")
+ * @param description - Description text (e.g., "to expand", "cancel")
+ * @returns Formatted string with dim key and muted description
+ */
+export function keyHint(action: Keybinding, description: string): string {
+	return theme.fg("dim", editorKey(action)) + theme.fg("muted", ` ${description}`);
+}
+
+/**
+ * Format a keybinding hint for app-level actions.
+ * Requires the KeybindingsManager instance.
+ *
+ * @param keybindings - KeybindingsManager instance
+ * @param action - App keybinding name (e.g., "app.interrupt", "app.editor.external")
+ * @param description - Description text
+ * @returns Formatted string with dim key and muted description
+ */
+export function appKeyHint(keybindings: KeybindingsManager, action: AppKeybinding, description: string): string {
+	return theme.fg("dim", appKey(keybindings, action)) + theme.fg("muted", ` ${description}`);
+}
+
+/**
+ * Format a raw key string with description (for non-configurable keys like ↑↓).
+ *
+ * @param key - Raw key string
+ * @param description - Description text
+ * @returns Formatted string with dim key and muted description
+ */
+export function rawKeyHint(key: string, description: string): string {
+	return theme.fg("dim", key) + theme.fg("muted", ` ${description}`);
+}

package/src/chrome/live-board.ts

@@ -0,0 +1,123 @@
+/**
+ * Transient multi-line status board for standalone CLI commands.
+ *
+ * Repaints a caller-rendered block of lines in place at ~12.5fps while
+ * permanent output logged through {@link LiveBoard.log} scrolls above it.
+ * Non-TTY outputs disable rendering entirely and `log` degrades to plain
+ * writes, so callers keep one code path for both modes.
+ */
+import { replaceTabs, truncateToWidth } from "../utils";
+import { ensureThemeSync, theme } from "../theme/theme";
+
+const RENDER_INTERVAL_MS = 80;
+
+/** Output contract for the live board (satisfied by `process.stdout`). */
+export interface LiveBoardOutput {
+	isTTY?: boolean;
+	columns?: number;
+	rows?: number;
+	write(text: string): boolean;
+}
+
+/** Live repaint handle returned by {@link createLiveBoard}. */
+export interface LiveBoard {
+	readonly interactive: boolean;
+	/** Print a permanent line above the board; plain write when non-interactive. */
+	log(text: string): void;
+	/** Repaint immediately after a state change instead of waiting for the next tick. */
+	repaint(): void;
+	/** Clear the board, stop the timer, and restore the cursor. */
+	close(): void;
+}
+
+/**
+ * Create a live board whose content comes from `render(spinner, width)` on
+ * every tick. An empty render result paints nothing and releases the cursor,
+ * so an idle board never interferes with other terminal UI (e.g. pickers).
+ */
+export function createLiveBoard(
+	render: (spinner: string, width: number) => string[],
+	output: LiveBoardOutput = process.stdout,
+): LiveBoard {
+	const interactive = output.isTTY === true;
+	let frame = 0;
+	let lineCount = 0;
+	let cursorHidden = false;
+	let closed = false;
+	let timer: NodeJS.Timeout | undefined;
+
+	const dimensions = (): { width: number; maxRows: number } => {
+		const columns = output.columns ?? 0;
+		const rows = output.rows ?? 0;
+		return {
+			width: Number.isFinite(columns) && columns > 0 ? Math.trunc(columns) : 80,
+			maxRows: Math.max(4, (Number.isFinite(rows) && rows > 0 ? Math.trunc(rows) : 24) - 2),
+		};
+	};
+
+	const paint = (lines: string[]): void => {
+		// Erase each line explicitly and cap it to the terminal width so the
+		// `\x1b[<n>A` cursor-up always matches the logical line count, even in
+		// raw-mode terminals without ONLCR where wrapped rows would otherwise
+		// staircase into scrollback.
+		if (lines.length === 0 && lineCount === 0) return;
+		const { width } = dimensions();
+		let out = lineCount > 0 ? `\x1b[${lineCount}A` : "";
+		out += "\r";
+		if (lines.length > 0) {
+			out += `${lines.map(line => `\x1b[2K${truncateToWidth(replaceTabs(line), width)}`).join("\r\n")}\r\n`;
+		}
+		out += "\x1b[0J";
+		if (lines.length > 0 && !cursorHidden) {
+			out += "\x1b[?25l";
+			cursorHidden = true;
+		} else if (lines.length === 0 && cursorHidden) {
+			out += "\x1b[?25h";
+			cursorHidden = false;
+		}
+		output.write(out);
+		lineCount = lines.length;
+	};
+
+	const repaint = (): void => {
+		if (!interactive || closed) return;
+		const { width, maxRows } = dimensions();
+		ensureThemeSync();
+		const frames = theme.getSpinnerFrames("activity");
+		const spinner = frames[frame % frames.length] ?? "*";
+		let lines = render(spinner, width);
+		if (lines.length > maxRows) {
+			lines = [...lines.slice(0, maxRows - 1), `… +${lines.length - (maxRows - 1)} more`];
+		}
+		paint(lines);
+	};
+
+	if (interactive) {
+		timer = setInterval(() => {
+			frame += 1;
+			repaint();
+		}, RENDER_INTERVAL_MS);
+		timer.unref?.();
+	}
+
+	return {
+		interactive,
+		log(text) {
+			if (closed || !interactive) {
+				output.write(`${text}\n`);
+				return;
+			}
+			paint([]);
+			output.write(`${text}\n`);
+			repaint();
+		},
+		repaint,
+		close() {
+			if (closed) return;
+			closed = true;
+			if (!interactive) return;
+			clearInterval(timer);
+			paint([]);
+		},
+	};
+}

package/src/chrome/local-date.ts

@@ -0,0 +1,20 @@
+/** formatLocalCalendarDate formats a Date as YYYY-MM-DD in the host local timezone. */
+export function formatLocalCalendarDate(date: Date = new Date()): string {
+	const year = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${year}-${month}-${day}`;
+}
+
+/** Format a local date and minute with a compact numeric UTC offset. */
+export function formatLocalDateTimeWithOffset(date: Date): string {
+	const offsetMinutes = date.getTimezoneOffset();
+	const offsetSign = offsetMinutes <= 0 ? "+" : "-";
+	const absoluteOffset = Math.abs(offsetMinutes);
+	const offsetHours = Math.floor(absoluteOffset / 60);
+	const offsetRemainderMinutes = absoluteOffset % 60;
+	const pad2 = (value: number): string => String(value).padStart(2, "0");
+	return `${formatLocalCalendarDate(date)} ${pad2(date.getHours())}:${pad2(date.getMinutes())} ${offsetSign}${pad2(
+		offsetHours,
+	)}:${pad2(offsetRemainderMinutes)}`;
+}