@luan.sh/pi-libtui 0.3.8

package/src/syntax.ts

@@ -0,0 +1,316 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import {
+	type DiffsHighlighter,
+	getFiletypeFromFileName,
+	getHighlighterIfLoaded,
+	getSharedHighlighter,
+	type SupportedLanguages,
+	type ThemedDiffResult,
+} from "@pierre/diffs";
+import type { TuiForegroundColor } from "./color/theme.ts";
+import { tuiTheme } from "./color/theme.ts";
+import { sanitizeTuiText } from "./content/terminal-text.ts";
+import { RenderedLinesCache } from "./render-cache.ts";
+
+const SHIKI_THEME = "github-dark";
+const SYNTAX_LANGUAGES = [
+	"c",
+	"cpp",
+	"csharp",
+	"css",
+	"dockerfile",
+	"elixir",
+	"fish",
+	"go",
+	"graphql",
+	"haskell",
+	"hcl",
+	"html",
+	"java",
+	"javascript",
+	"json",
+	"jsx",
+	"kotlin",
+	"lua",
+	"makefile",
+	"markdown",
+	"ocaml",
+	"perl",
+	"php",
+	"protobuf",
+	"python",
+	"r",
+	"ruby",
+	"rust",
+	"scss",
+	"sql",
+	"swift",
+	"toml",
+	"tsx",
+	"typescript",
+	"xml",
+	"yaml",
+	"zsh",
+] as const satisfies readonly SupportedLanguages[];
+const supportedLanguages = new Set<SupportedLanguages>(SYNTAX_LANGUAGES);
+let highlighterReady: Promise<DiffsHighlighter | undefined> | undefined;
+
+export interface SyntaxHighlightSpan {
+	readonly text: string;
+	readonly foreground?: TuiForegroundColor;
+	readonly emphasized?: boolean;
+}
+
+export interface SyntaxTextOptions {
+	theme: Theme;
+	text: string;
+	path?: string;
+	maxRows?: number;
+	maxCharacters?: number;
+	requestRender?: () => void;
+}
+
+/** Bounded, cached syntax-highlighted source or structured text without a container. */
+export class SyntaxText implements Component {
+	private readonly cache = new RenderedLinesCache();
+	private text: string;
+	private syntaxReadyRequested = false;
+
+	constructor(private readonly options: SyntaxTextOptions) {
+		// Restored tool details may predate a newly-added presentation field.
+		this.text = typeof options.text === "string" ? sanitizeTuiText(options.text) : "";
+	}
+
+	setText(text: string): void {
+		const normalized = typeof text === "string" ? sanitizeTuiText(text) : "";
+		if (normalized === this.text) return;
+		this.text = normalized;
+		this.cache.clear();
+	}
+
+	render(width: number): string[] {
+		const boundedWidth = Math.max(0, Math.floor(width));
+		if (boundedWidth === 0) return [];
+		this.requestSyntaxReady();
+		const maximum = finiteBound(this.options.maxCharacters, 200_000, 0);
+		const clipped = this.text.length > maximum ? `${this.text.slice(0, Math.max(0, maximum - 1))}…` : this.text;
+		const highlighterState = getHighlighterIfLoaded() ? "highlighted" : "plain";
+		return this.cache.get(boundedWidth, highlighterState, () => {
+			const colors = tuiTheme(this.options.theme);
+			const limit = finiteBound(this.options.maxRows, 500, 1);
+			const rows: string[] = [];
+			let omitted = false;
+			const sourceLines = clipped.split("\n");
+			const highlightedLines = highlightSyntaxBlock(clipped, this.options.path);
+			for (const [lineIndex, line] of sourceLines.entries()) {
+				const remainingRows = Math.max(1, limit - rows.length);
+				const lineBudget = Math.max(1_024, Math.min(20_000, boundedWidth * remainingRows * 2));
+				const lineClipped = line.length > lineBudget;
+				const sourceSpans = highlightedLines[lineIndex] ?? [];
+				const spans = sourceSpans.map((span) => span.text).join("") === line ? sourceSpans : [{ text: line }];
+				const visibleSpans = lineClipped ? [...truncateSyntaxSpans(spans, lineBudget - 1), { text: "…" }] : spans;
+				const styled = visibleSpans.map((span) => colors.fg(span.foreground ?? "text.primary", span.text)).join("");
+				for (const row of wrapTextWithAnsi(styled, boundedWidth)) {
+					rows.push(row);
+					if (rows.length > limit) {
+						omitted = true;
+						break;
+					}
+				}
+				if (lineClipped) omitted = true;
+				if (omitted) break;
+			}
+			if (!omitted) return rows;
+			return [
+				...rows.slice(0, limit - 1),
+				colors.fg("text.muted", truncateToWidth("… output omitted …", boundedWidth, "…")),
+			];
+		});
+	}
+
+	invalidate(): void {
+		this.cache.clear();
+	}
+
+	private requestSyntaxReady(): void {
+		if (this.syntaxReadyRequested || getHighlighterIfLoaded()) return;
+		this.syntaxReadyRequested = true;
+		void ensureSyntaxHighlighter().then((highlighter) => {
+			if (!highlighter) return;
+			this.cache.clear();
+			this.options.requestRender?.();
+		});
+	}
+}
+
+export function highlightSyntaxBlock(
+	text: string,
+	path: string | undefined,
+): readonly (readonly SyntaxHighlightSpan[])[] {
+	const plainLines = plainSyntaxLines(text);
+	const highlighter = getHighlighterIfLoaded();
+	if (!highlighter) return plainLines;
+	const language = languageForPath(path);
+	try {
+		const root = highlighter.codeToHast(text, {
+			lang: language,
+			theme: SHIKI_THEME,
+			defaultColor: false,
+			tokenizeTimeLimit: 0,
+		});
+		const lines = syntaxSpansFromLines(root);
+		while (lines.length < plainLines.length) lines.push([]);
+		return lines.slice(0, plainLines.length);
+	} catch {
+		return plainLines;
+	}
+}
+
+export function loadedDiffHighlighter(): DiffsHighlighter | undefined {
+	return getHighlighterIfLoaded();
+}
+
+export function whenSyntaxReady(callback: () => void): void {
+	void ensureSyntaxHighlighter().then(callback);
+}
+
+function ensureSyntaxHighlighter(): Promise<DiffsHighlighter | undefined> {
+	if (highlighterReady) return highlighterReady;
+	highlighterReady = getSharedHighlighter({ themes: [SHIKI_THEME], langs: [...SYNTAX_LANGUAGES] }).catch(
+		() => undefined,
+	);
+	return highlighterReady;
+}
+
+export function syntaxSpansFromPierreLine(
+	node: ThemedDiffResult["code"]["additionLines"][number],
+): readonly SyntaxHighlightSpan[] {
+	return syntaxSpansFromNode(node);
+}
+
+export function syntaxLanguage(path: string | undefined): SupportedLanguages {
+	return languageForPath(path);
+}
+
+function languageForPath(path: string | undefined): SupportedLanguages {
+	if (!path) return "text";
+	const language = getFiletypeFromFileName(path);
+	return supportedLanguages.has(language) ? language : "text";
+}
+
+type PierreSyntaxNode =
+	| ReturnType<DiffsHighlighter["codeToHast"]>
+	| ReturnType<DiffsHighlighter["codeToHast"]>["children"][number];
+
+function plainSyntaxLines(text: string): readonly (readonly SyntaxHighlightSpan[])[] {
+	return text.split("\n").map((line) => (line ? [{ text: line }] : []));
+}
+
+function syntaxSpansFromNode(node: PierreSyntaxNode): readonly SyntaxHighlightSpan[] {
+	const spans: SyntaxHighlightSpan[] = [];
+	collectSyntaxSpans(node, undefined, false, spans);
+	return spans;
+}
+
+function syntaxSpansFromLines(node: PierreSyntaxNode): SyntaxHighlightSpan[][] {
+	const lines: SyntaxHighlightSpan[][] = [[]];
+	for (const span of syntaxSpansFromNode(node)) {
+		const values = span.text.split("\n");
+		for (const [index, value] of values.entries()) {
+			pushSpan(lines.at(-1)!, { ...span, text: value });
+			if (index < values.length - 1) lines.push([]);
+		}
+	}
+	return lines;
+}
+
+function truncateSyntaxSpans(
+	spans: readonly SyntaxHighlightSpan[],
+	maximumCharacters: number,
+): readonly SyntaxHighlightSpan[] {
+	let remaining = Math.max(0, maximumCharacters);
+	const truncated: SyntaxHighlightSpan[] = [];
+	for (const span of spans) {
+		if (remaining === 0) break;
+		const text = span.text.slice(0, remaining);
+		if (!text) continue;
+		truncated.push({ ...span, text });
+		remaining -= text.length;
+	}
+	return truncated;
+}
+
+function collectSyntaxSpans(
+	node: PierreSyntaxNode,
+	foreground: TuiForegroundColor | undefined,
+	emphasized: boolean,
+	spans: SyntaxHighlightSpan[],
+): void {
+	if (node.type === "text") {
+		pushSpan(spans, { text: node.value, foreground, emphasized });
+		return;
+	}
+	if (node.type !== "root" && node.type !== "element") return;
+	const properties = node.type === "element" ? node.properties : undefined;
+	const nextForeground =
+		foregroundFromStyle(typeof properties?.style === "string" ? properties.style : undefined) ?? foreground;
+	const nextEmphasized = emphasized || (properties !== undefined && "data-diff-span" in properties);
+	for (const child of node.children) collectSyntaxSpans(child, nextForeground, nextEmphasized, spans);
+}
+
+function pushSpan(spans: SyntaxHighlightSpan[], span: SyntaxHighlightSpan): void {
+	if (!span.text) return;
+	const previous = spans.at(-1);
+	if (previous && sameForeground(previous.foreground, span.foreground) && previous.emphasized === span.emphasized) {
+		spans[spans.length - 1] = { ...previous, text: previous.text + span.text };
+		return;
+	}
+	spans.push(span);
+}
+
+function sameForeground(left: TuiForegroundColor | undefined, right: TuiForegroundColor | undefined): boolean {
+	if (left === right) return true;
+	if (typeof left === "string" || typeof right === "string" || !left || !right) return false;
+	return left.hue === right.hue && left.shade === right.shade;
+}
+
+function foregroundFromStyle(style: string | undefined): TuiForegroundColor | undefined {
+	const match = /(?:^|;)color:\s*#([0-9a-f]{6})(?:;|$)/iu.exec(style ?? "");
+	if (!match) return undefined;
+	const value = match[1]!;
+	const red = Number.parseInt(value.slice(0, 2), 16) / 255;
+	const green = Number.parseInt(value.slice(2, 4), 16) / 255;
+	const blue = Number.parseInt(value.slice(4, 6), 16) / 255;
+	const maximum = Math.max(red, green, blue);
+	const minimum = Math.min(red, green, blue);
+	const lightness = (maximum + minimum) / 2;
+	const delta = maximum - minimum;
+	if (delta < 0.08) return { hue: "gray", shade: shade(lightness) };
+	let hue = 0;
+	if (maximum === red) hue = ((green - blue) / delta + (green < blue ? 6 : 0)) / 6;
+	else if (maximum === green) hue = ((blue - red) / delta + 2) / 6;
+	else hue = ((red - green) / delta + 4) / 6;
+	const semanticHue =
+		hue < 1 / 24 || hue >= 23 / 24
+			? "red"
+			: hue < 5 / 24
+				? "yellow"
+				: hue < 10 / 24
+					? "green"
+					: hue < 14 / 24
+						? "cyan"
+						: hue < 19 / 24
+							? "blue"
+							: "magenta";
+	return { hue: semanticHue, shade: shade(lightness) };
+}
+
+function shade(lightness: number): 0 | 1 | 2 | 3 | 4 | 5 {
+	return Math.max(0, Math.min(5, Math.round(lightness * 5))) as 0 | 1 | 2 | 3 | 4 | 5;
+}
+
+function finiteBound(value: number | undefined, fallback: number, minimum: number): number {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(minimum, Math.floor(value)) : fallback;
+}

package/src/terminal/bridge-client.ts

@@ -0,0 +1,243 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+
+interface BridgeResponse<T> {
+	request_id: number;
+	ok: boolean;
+	result?: T;
+	error?: string;
+}
+
+// type-boundary: native bridge stdout is untrusted JSON; this parser validates the response envelope before dispatch.
+type BridgeResponseBoundary = unknown;
+
+function parseBridgeResponse(line: string): BridgeResponse<unknown> | undefined {
+	let value: BridgeResponseBoundary;
+	try {
+		value = JSON.parse(line);
+	} catch {
+		return undefined;
+	}
+	if (!value || typeof value !== "object") return undefined;
+	const candidate = value as Partial<BridgeResponse<unknown>>;
+	if (!Number.isSafeInteger(candidate.request_id) || typeof candidate.ok !== "boolean") return undefined;
+	if (candidate.ok === false && candidate.error !== undefined && typeof candidate.error !== "string") return undefined;
+	return candidate as BridgeResponse<unknown>;
+}
+
+export interface TerminalBridgeReadResponse {
+	chunks: Array<{ startSeq?: number; seq: number; stream: "stdout" | "stderr" | "pty"; bytes: Uint8Array }>;
+	nextSeq: number;
+	more?: boolean;
+	exited: boolean;
+	exitCode?: number | null;
+	closed: boolean;
+	failure?: string | null;
+}
+
+// type-boundary: native bridge result payloads are untrusted JSON; validate read results before consumers reduce them.
+type TerminalBridgeReadBoundary = unknown;
+
+const BASE64 = /^(?:[A-Za-z\d+/]{4})*(?:[A-Za-z\d+/]{2}==|[A-Za-z\d+/]{3}=)?$/;
+
+export function parseTerminalBridgeReadResponse(
+	value: TerminalBridgeReadBoundary,
+	expectedNextSeq?: number,
+): TerminalBridgeReadResponse | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const candidate = value as Partial<Record<keyof TerminalBridgeReadResponse, unknown>>;
+	if (!Array.isArray(candidate.chunks) || !Number.isSafeInteger(candidate.nextSeq) || Number(candidate.nextSeq) < 1)
+		return undefined;
+	if (typeof candidate.exited !== "boolean" || typeof candidate.closed !== "boolean") return undefined;
+	if (candidate.more !== undefined && typeof candidate.more !== "boolean") return undefined;
+	if (candidate.exitCode !== undefined && candidate.exitCode !== null && !Number.isSafeInteger(candidate.exitCode))
+		return undefined;
+	if (candidate.failure !== undefined && candidate.failure !== null && typeof candidate.failure !== "string")
+		return undefined;
+	const chunks: TerminalBridgeReadResponse["chunks"] = [];
+	let previousSeq = 0;
+	for (const value of candidate.chunks) {
+		if (!value || typeof value !== "object") return undefined;
+		const chunk = value as Partial<{
+			startSeq: number;
+			seq: number;
+			stream: "stdout" | "stderr" | "pty";
+			chunk: string;
+		}>;
+		const seq = Number(chunk.seq);
+		const startSeq = chunk.startSeq === undefined ? seq : Number(chunk.startSeq);
+		if (
+			!Number.isSafeInteger(chunk.seq) ||
+			seq < 1 ||
+			!Number.isSafeInteger(startSeq) ||
+			startSeq < 1 ||
+			startSeq > seq
+		)
+			return undefined;
+		if (previousSeq > 0 && startSeq !== previousSeq + 1) return undefined;
+		if (chunk.stream !== "stdout" && chunk.stream !== "stderr" && chunk.stream !== "pty") return undefined;
+		const bytes = decodeBase64(chunk.chunk);
+		if (!bytes) return undefined;
+		previousSeq = seq;
+		chunks.push({ startSeq, seq: previousSeq, stream: chunk.stream, bytes });
+	}
+	if (chunks.length > 0 && candidate.nextSeq !== previousSeq + 1) return undefined;
+	const first = chunks[0];
+	if (expectedNextSeq !== undefined && (first ? (first.startSeq ?? first.seq) : candidate.nextSeq) !== expectedNextSeq)
+		return undefined;
+	return {
+		chunks,
+		nextSeq: Number(candidate.nextSeq),
+		...(typeof candidate.more === "boolean" ? { more: candidate.more } : {}),
+		exited: candidate.exited,
+		...(typeof candidate.exitCode === "number" || candidate.exitCode === null ? { exitCode: candidate.exitCode } : {}),
+		closed: candidate.closed,
+		...(typeof candidate.failure === "string" || candidate.failure === null ? { failure: candidate.failure } : {}),
+	};
+}
+
+function decodeBase64(value: unknown): Uint8Array | undefined {
+	return typeof value === "string" && BASE64.test(value) ? Buffer.from(value, "base64") : undefined;
+}
+
+export interface TerminalBridgeClient {
+	request<T>(request: Record<string, unknown>): Promise<T>;
+	shutdown(): Promise<void>;
+}
+
+export interface TerminalBridgeClientDependencies {
+	readonly binaryPath: () => Promise<string>;
+	readonly spawnBridge: (binaryPath: string) => ChildProcessWithoutNullStreams;
+}
+
+const BRIDGE_SHUTDOWN_GRACE_MS = 1_000;
+
+/** Multiplex JSON-line requests over one shared native bridge process. */
+export function createTerminalBridgeClient({
+	binaryPath,
+	spawnBridge,
+}: TerminalBridgeClientDependencies): TerminalBridgeClient {
+	let child: ChildProcessWithoutNullStreams | undefined;
+	let nextRequestId = 1;
+	let closed = false;
+	let shutdownPromise: Promise<void> | undefined;
+	const pending = new Map<
+		number,
+		{ readonly owner: ChildProcessWithoutNullStreams; resolve(value: unknown): void; reject(error: Error): void }
+	>();
+
+	function rejectPending(error: Error, owner?: ChildProcessWithoutNullStreams): void {
+		for (const [requestId, request] of pending) {
+			if (owner && request.owner !== owner) continue;
+			pending.delete(requestId);
+			request.reject(error);
+		}
+	}
+
+	function fail(owner: ChildProcessWithoutNullStreams, error: Error): void {
+		if (child === owner) child = undefined;
+		rejectPending(error, owner);
+		if (owner.exitCode === null && owner.signalCode === null) owner.kill("SIGKILL");
+	}
+
+	async function getChild(): Promise<ChildProcessWithoutNullStreams> {
+		if (closed) throw new Error("terminal bridge is shut down");
+		if (child && child.exitCode === null && child.signalCode === null) return child;
+		const binary = await binaryPath();
+		if (closed) throw new Error("terminal bridge is shut down");
+		if (child && child.exitCode === null && child.signalCode === null) return child;
+		let lineBuffer = "";
+		let stderr = "";
+		const decoder = new StringDecoder("utf8");
+		const spawned = spawnBridge(binary);
+		child = spawned;
+		spawned.stdout.on("data", (data: Buffer) => {
+			lineBuffer += decoder.write(data);
+			for (;;) {
+				const newline = lineBuffer.indexOf("\n");
+				if (newline === -1) break;
+				const line = lineBuffer.slice(0, newline).trim();
+				lineBuffer = lineBuffer.slice(newline + 1);
+				if (!line) continue;
+				const response = parseBridgeResponse(line);
+				if (!response) {
+					fail(spawned, new Error("terminal bridge emitted an invalid response"));
+					return;
+				}
+				const request = pending.get(response.request_id);
+				if (!request || request.owner !== spawned) {
+					fail(spawned, new Error(`terminal bridge responded to unknown request ${response.request_id}`));
+					return;
+				}
+				pending.delete(response.request_id);
+				if (response.ok) request.resolve(response.result);
+				else request.reject(new Error(response.error ?? "terminal bridge request failed"));
+			}
+		});
+		spawned.stderr.on("data", (data: Buffer) => {
+			stderr = `${stderr}${data.toString("utf8")}`.slice(-16_000);
+		});
+		spawned.on("error", (error) => fail(spawned, error));
+		spawned.on("close", (code, signal) => {
+			const status = code === null ? `signal ${signal}` : `code ${code}`;
+			rejectPending(
+				new Error(`terminal bridge exited (${status})${stderr.trim() ? `: ${stderr.trim()}` : ""}`),
+				spawned,
+			);
+			if (child === spawned) child = undefined;
+		});
+		return spawned;
+	}
+
+	async function request<T>(value: Record<string, unknown>): Promise<T> {
+		const requestId = nextRequestId++;
+		const bridge = await getChild();
+		return new Promise<T>((resolve, reject) => {
+			pending.set(requestId, { owner: bridge, resolve: resolve as (value: unknown) => void, reject });
+			const rejectWrite = (error: Error): void => {
+				pending.delete(requestId);
+				reject(error);
+			};
+			try {
+				bridge.stdin.write(`${JSON.stringify({ ...value, request_id: requestId })}\n`, (error) => {
+					if (error) rejectWrite(error);
+				});
+			} catch (error) {
+				rejectWrite(error instanceof Error ? error : new Error("terminal bridge write failed"));
+			}
+		});
+	}
+
+	return {
+		request,
+		shutdown() {
+			if (shutdownPromise) return shutdownPromise;
+			shutdownPromise = (async () => {
+				const bridge = child;
+				const wasRunning = bridge && bridge.exitCode === null && bridge.signalCode === null;
+				const exited = wasRunning
+					? new Promise<void>((resolve) => bridge.once("close", () => resolve()))
+					: Promise.resolve();
+				const graceful = wasRunning
+					? request<{ shutdown: boolean }>({ op: "shutdown" }).catch(() => undefined)
+					: Promise.resolve();
+				const deadline = wasRunning
+					? setTimeout(() => {
+							if (bridge.exitCode === null && bridge.signalCode === null) bridge.kill("SIGKILL");
+						}, BRIDGE_SHUTDOWN_GRACE_MS)
+					: undefined;
+				deadline?.unref();
+				closed = true;
+				try {
+					await graceful;
+				} finally {
+					if (deadline) clearTimeout(deadline);
+					if (bridge && bridge.exitCode === null && bridge.signalCode === null) bridge.kill("SIGKILL");
+					rejectPending(new Error("terminal bridge is shut down"));
+					await exited;
+				}
+			})();
+			return shutdownPromise;
+		},
+	};
+}

package/src/terminal/embedding.ts

@@ -0,0 +1,6 @@
+const TOP_LEVEL_ZONE_MARKER = /\x1b\]133;[ABC](?:\x07|\x1b\\)/gu;
+
+/** Remove terminal-wide transcript zones before embedding rendered lines inside another surface. */
+export function stripTopLevelZoneMarkers(lines: readonly string[]): string[] {
+	return lines.map((line) => line.replace(TOP_LEVEL_ZONE_MARKER, ""));
+}