@luan.sh/pi-libtui 0.3.8

package/src/native-binary.ts

@@ -0,0 +1,189 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const REPOSITORY = "https://github.com/luan/agents";
+const BUILDS_KEY = Symbol.for("pi-libtui/native-builds/v1");
+
+/** A Rust binary from this repository's `crates/` that an extension shells out to. */
+export interface NativeBinary {
+	/** Cargo package name, as passed to `cargo install`. */
+	readonly crate: string;
+	/** Executable name without platform suffix. */
+	readonly binaryName: string;
+	/** Environment variable that overrides discovery with an explicit path. */
+	readonly env: string;
+}
+
+export interface NativeBinaryOptions {
+	readonly environment: Readonly<Record<string, string | undefined>>;
+	readonly platform: NodeJS.Platform;
+	/** Directory that holds per-crate, per-revision builds (`<root>/<crate>/<rev>/bin/<name>`). */
+	readonly nativeRoot: string;
+	/** Git revision of this repository the binary must be built from. */
+	readonly rev: string;
+	/** Directory to walk up from when looking for a development checkout. */
+	readonly developmentStart?: string;
+	isExecutable(path: string): boolean;
+}
+
+export type NativeBinaryLocation =
+	| { readonly kind: "found"; readonly path: string }
+	| { readonly kind: "build"; readonly installRoot: string; readonly path: string }
+	| { readonly kind: "unbuilt-checkout"; readonly checkout: string };
+
+export const TERMINAL_BRIDGE: NativeBinary = {
+	crate: "terminal-bridge",
+	binaryName: "terminal_bridge",
+	env: "PI_TERMINAL_BRIDGE_BINARY",
+};
+
+/**
+ * Locate a native binary without side effects. Order: the override env var, the managed build for
+ * this revision, then a development checkout's `target/`. A miss says what would fix it.
+ */
+export function locateNativeBinary(binary: NativeBinary, options: NativeBinaryOptions): NativeBinaryLocation {
+	const override = options.environment[binary.env];
+	if (override !== undefined) {
+		const path = override.trim();
+		if (!path) throw new Error(`${binary.env} is set but empty`);
+		if (!options.isExecutable(path)) throw new Error(`${binary.env} is not executable: ${path}`);
+		return { kind: "found", path };
+	}
+	const binaryName = options.platform === "win32" ? `${binary.binaryName}.exe` : binary.binaryName;
+	const installRoot = join(options.nativeRoot, binary.crate, options.rev);
+	const managed = join(installRoot, "bin", binaryName);
+	if (options.isExecutable(managed)) return { kind: "found", path: managed };
+	const checkout = options.developmentStart ? findCheckoutRoot(options.developmentStart, binary.crate) : undefined;
+	if (checkout) {
+		for (const profile of ["release", "debug"]) {
+			const candidate = resolve(checkout, "target", profile, binaryName);
+			if (options.isExecutable(candidate)) return { kind: "found", path: candidate };
+		}
+		return { kind: "unbuilt-checkout", checkout };
+	}
+	return { kind: "build", installRoot, path: managed };
+}
+
+/** `cargo install` arguments that build `binary` at `rev` into `installRoot/bin`. */
+export function nativeBuildArguments(binary: NativeBinary, rev: string, installRoot: string): readonly string[] {
+	return ["install", "--git", REPOSITORY, "--rev", rev, "--root", installRoot, "--locked", binary.crate];
+}
+
+export interface EnsureNativeBinaryHooks {
+	/** Called once when a build starts, so a UI can explain the delay. */
+	onBuild?(message: string): void;
+}
+
+/**
+ * Resolve a native binary for this process, building it on first use. Builds are keyed by crate and
+ * revision under Pi's agent directory and shared by every installed pi-libtui copy.
+ */
+export async function ensureNativeBinary(binary: NativeBinary, hooks: EnsureNativeBinaryHooks = {}): Promise<string> {
+	const options = processOptions();
+	const location = locateNativeBinary(binary, options);
+	if (location.kind === "found") return location.path;
+	if (location.kind === "unbuilt-checkout") {
+		throw new Error(
+			`${binary.binaryName} is not built in ${location.checkout}. Run cargo build --release -p ${binary.crate}`,
+		);
+	}
+	const builds = sharedBuilds();
+	const existing = builds.get(location.path);
+	if (existing) return existing;
+	hooks.onBuild?.(`Building ${binary.binaryName} (first use); this takes a minute.`);
+	const build = runCargo(nativeBuildArguments(binary, options.rev, location.installRoot), location.installRoot)
+		.then(() => {
+			if (!isExecutable(location.path)) throw new Error(`cargo install did not produce ${location.path}`);
+			return location.path;
+		})
+		.finally(() => builds.delete(location.path));
+	builds.set(location.path, build);
+	return build;
+}
+
+export function terminalBridgeBinaryPath(): Promise<string> {
+	return ensureNativeBinary(TERMINAL_BRIDGE);
+}
+
+/** The pack step records the exact source commit independently of npm versions. */
+export function nativeRevision(): string {
+	const revision = readFileSync(new URL("../native-revision", import.meta.url), "utf8").trim();
+	if (!/^[a-f0-9]{40}$/.test(revision)) throw new Error("Invalid native source revision; reinstall the package.");
+	return revision;
+}
+
+function processOptions(): NativeBinaryOptions {
+	return {
+		environment: process.env,
+		platform: process.platform,
+		nativeRoot: join(getAgentDir(), "native"),
+		rev: nativeRevision(),
+		developmentStart: import.meta.dirname,
+		isExecutable,
+	};
+}
+
+function sharedBuilds(): Map<string, Promise<string>> {
+	const slots = globalThis as Record<PropertyKey, unknown>;
+	const existing = slots[BUILDS_KEY];
+	if (existing instanceof Map) return existing as Map<string, Promise<string>>;
+	const created = new Map<string, Promise<string>>();
+	slots[BUILDS_KEY] = created;
+	return created;
+}
+
+function runCargo(args: readonly string[], installRoot: string): Promise<void> {
+	mkdirSync(installRoot, { recursive: true });
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn("cargo", args, { stdio: ["ignore", "ignore", "pipe"], env: process.env });
+		let stderr = "";
+		child.stderr.on("data", (chunk: Buffer) => {
+			stderr = `${stderr}${chunk.toString("utf8")}`.slice(-8_000);
+		});
+		child.on("error", (error: NodeJS.ErrnoException) => {
+			reject(
+				error.code === "ENOENT"
+					? new Error("cargo was not found. Install Rust from https://rustup.rs to build native tools.")
+					: error,
+			);
+		});
+		child.on("close", (code) => {
+			if (code === 0) resolvePromise();
+			else
+				reject(new Error(`cargo ${args.join(" ")} failed (code ${code})${stderr.trim() ? `:\n${stderr.trim()}` : ""}`));
+		});
+	});
+}
+
+function isExecutable(path: string): boolean {
+	try {
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Walk up to the Cargo workspace that contains the crate, if the start directory lives in one. */
+function findCheckoutRoot(start: string, crate: string): string | undefined {
+	let current = resolve(start);
+	for (;;) {
+		if (isReadable(join(current, "Cargo.toml")) && isReadable(join(current, "crates", crate, "Cargo.toml"))) {
+			return current;
+		}
+		const parent = dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}
+
+function isReadable(path: string): boolean {
+	try {
+		accessSync(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/overlay/anchored.ts

@@ -0,0 +1,91 @@
+import type { OverlayOptions } from "@earendil-works/pi-tui";
+
+/** Zero-based terminal rectangle occupied by an anchored overlay. */
+export interface AnchoredOverlayRect {
+	/** Zero-based column of the rectangle's left edge. */
+	x: number;
+	/** Zero-based row of the rectangle's top edge. */
+	y: number;
+	/** Render width in terminal columns. */
+	width: number;
+	/** Render height in terminal rows. */
+	height: number;
+}
+
+/** Pi overlay options paired with the exact rectangle those options occupy. */
+export interface AnchoredOverlayPlacement {
+	/** Options to pass to Pi's overlay host. */
+	options: OverlayOptions;
+	/** Exact zero-based screen rectangle used for pointer translation. */
+	rect: AnchoredOverlayRect;
+}
+
+/** Terminal geometry and desired size used to place an anchored overlay. */
+export interface AnchoredOverlayRequest {
+	/** Available terminal width in columns. */
+	terminalCols: number;
+	/** Available terminal height in rows. */
+	terminalRows: number;
+	/** Zero-based screen row of the cell beside which the overlay should appear. */
+	anchorRow: number;
+	/** Zero-based screen column of the cell beside which the overlay should appear. */
+	anchorCol: number;
+	/** Requested overlay width before terminal-edge clamping. */
+	desiredWidth: number;
+	/** Requested overlay height before terminal-edge clamping. */
+	height: number;
+	/** Number of cells between the anchor and overlay; defaults to one. */
+	gap?: number;
+	/** Horizontal policy; centered overlays clamp around the anchor instead of sitting beside it. */
+	horizontalPlacement?: "adjacent" | "center";
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+	return Math.max(minimum, Math.min(value, maximum));
+}
+
+/**
+ * Places an overlay beside a screen cell and returns the exact matching rect.
+ * It prefers below/right, flips to above/left when that fits, then clamps.
+ *
+ * @param request Terminal bounds, anchor cell, and requested overlay geometry.
+ * @returns Pi overlay options and their exact clamped zero-based screen rectangle.
+ */
+export function placeAnchoredOverlay(request: AnchoredOverlayRequest): AnchoredOverlayPlacement {
+	const terminalCols = Math.max(0, Math.floor(request.terminalCols));
+	const terminalRows = Math.max(0, Math.floor(request.terminalRows));
+	const gap = Math.max(0, Math.floor(request.gap ?? 1));
+	const width = Math.min(terminalCols, Math.max(0, Math.floor(request.desiredWidth)));
+	const height = Math.min(terminalRows, Math.max(0, Math.floor(request.height)));
+	const anchorCol = clamp(Math.floor(request.anchorCol), 0, Math.max(0, terminalCols - 1));
+	const anchorRow = clamp(Math.floor(request.anchorRow), 0, Math.max(0, terminalRows - 1));
+
+	const right = anchorCol + gap;
+	const left = anchorCol - width - gap + 1;
+	const x =
+		request.horizontalPlacement === "center"
+			? clamp(Math.round(anchorCol - width / 2), 0, Math.max(0, terminalCols - width))
+			: right + width <= terminalCols
+				? right
+				: left >= 0
+					? left
+					: clamp(right, 0, Math.max(0, terminalCols - width));
+
+	const below = anchorRow + gap;
+	const above = anchorRow - height - gap + 1;
+	const y =
+		below + height <= terminalRows ? below : above >= 0 ? above : clamp(below, 0, Math.max(0, terminalRows - height));
+
+	const rect = { x, y, width, height };
+	return {
+		rect,
+		options: {
+			anchor: "top-left",
+			row: y,
+			col: x,
+			width,
+			maxHeight: height,
+			margin: 0,
+		},
+	};
+}

package/src/overlay/detail-card.ts

@@ -0,0 +1,158 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	compositeTuiLine,
+	sliceByColumn,
+	stripTerminalSequences,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import { tuiTheme } from "../color/theme.ts";
+import type { MouseRect, MouseRegistry, ScreenDecorationContext } from "../mouse.ts";
+
+export interface DetailCardContent {
+	readonly title: string;
+	readonly rows: readonly string[];
+}
+
+export interface HoverDetailCardTarget {
+	readonly rect: MouseRect;
+	readonly content: DetailCardContent;
+}
+
+export interface HoverDetailCardOptions {
+	readonly id: string;
+	readonly theme: Theme;
+	readonly registry: MouseRegistry;
+	readonly priority?: number;
+	readonly pointerPriority?: number;
+	getTarget(screen: readonly string[], context: ScreenDecorationContext): HoverDetailCardTarget | undefined;
+}
+
+export interface HoverDetailCardMount {
+	dispose(): void;
+}
+
+/** Mount the same annotation-style detail card over any screen-locatable pill. */
+export function mountHoverDetailCard(options: HoverDetailCardOptions): HoverDetailCardMount {
+	let target: HoverDetailCardTarget | undefined;
+	let hovered = false;
+	const removeDecorator = options.registry.registerScreenDecorator({
+		id: options.id,
+		priority: options.priority ?? 5_000,
+		decorate(screen, context) {
+			target = context.hasOverlay ? undefined : options.getTarget(screen, context);
+			if (!target) hovered = false;
+			if (!hovered || !target) return screen;
+			return decorateDetailCard(
+				screen,
+				renderDetailCard(options.theme, target.content, context.width),
+				{ row: target.rect.y, col: target.rect.x },
+				context.width,
+			);
+		},
+	});
+	const removeRegion = options.registry.registerOverlayRegion({
+		id: options.id,
+		priority: options.pointerPriority ?? 500,
+		getRect: () => target?.rect,
+		onMouse(event) {
+			const next = event.type !== "leave";
+			const changed = hovered !== next;
+			hovered = next;
+			return changed || next;
+		},
+	});
+	return {
+		dispose() {
+			target = undefined;
+			hovered = false;
+			removeDecorator();
+			removeRegion();
+		},
+	};
+}
+
+/** Render the shared annotation-style hover card. */
+export function renderDetailCard(theme: Theme, content: DetailCardContent, availableWidth: number): string[] {
+	const contentWidth = Math.max(
+		visibleWidth(content.title) + 5,
+		...content.rows.flatMap((row) => row.split("\n")).map((row) => visibleWidth(row) + 2),
+	);
+	const width = Math.max(4, Math.min(60, availableWidth, contentWidth));
+	const innerWidth = Math.max(1, width - 2);
+	const rows = wrapRows(content.rows, innerWidth, 7);
+	const colors = tuiTheme(theme);
+	const border = (text: string): string => colors.fg("border", text);
+	const fittedTitle = truncateToWidth(content.title, Math.max(0, width - 5), "");
+	const titleWidth = visibleWidth(fittedTitle);
+	const top = colors.bg(
+		"surface.raised",
+		`${border("╭─ ")}${colors.fg("text.secondary", fittedTitle)}${border(
+			` ${"─".repeat(Math.max(0, width - titleWidth - 5))}╮`,
+		)}`,
+	);
+	const body = rows.map((row) => {
+		const text = truncateToWidth(row, innerWidth, "");
+		return colors.bg(
+			"surface.raised",
+			`${border("│")}${colors.fg("text.primary", text)}${" ".repeat(Math.max(0, innerWidth - visibleWidth(text)))}${border("│")}`,
+		);
+	});
+	return [top, ...body, colors.bg("surface.raised", border(`╰${"─".repeat(width - 2)}╯`))];
+}
+
+/** Composite a detail card beside an inline anchor. */
+export function decorateDetailCard(
+	screen: readonly string[],
+	card: readonly string[],
+	anchor: { readonly row: number; readonly col: number },
+	width: number,
+): string[] {
+	const result = [...screen];
+	const cardWidth = Math.min(width, Math.max(0, ...card.map((line) => visibleWidth(line))));
+	const x = Math.max(0, Math.min(anchor.col, Math.max(0, width - cardWidth)));
+	const below = anchor.row + 1;
+	const y = below + card.length <= result.length ? below : Math.max(0, anchor.row - card.length);
+	for (const [offset, line] of card.entries()) {
+		const row = y + offset;
+		if (row >= result.length) break;
+		const overlayWidth = Math.min(cardWidth, width - x);
+		const clipped = sliceByColumn(line, 0, overlayWidth, true);
+		const base = result[row] ?? "";
+		result[row] = compositeTuiLine(base, clipped, x, overlayWidth, overlayTotalWidth(base, x, overlayWidth, width));
+	}
+	return result;
+}
+
+export function overlayTotalWidth(base: string, start: number, overlayWidth: number, width: number): number {
+	const afterStart = start + overlayWidth;
+	const after = sliceByColumn(base, afterStart, Math.max(0, width - afterStart), true);
+	const afterVisible = visibleWidth(after);
+	const afterContent = visibleWidth(stripTerminalSequences(after).replace(/\s+$/u, ""));
+	const hasStyledPadding = /\x1b\[[0-9;]*m/u.test(after);
+	const preservedAfter = afterContent > 0 || hasStyledPadding ? afterVisible : 0;
+	return Math.min(width, Math.max(afterStart, afterStart + preservedAfter));
+}
+
+function wrapRows(sourceRows: readonly string[], width: number, maxRows: number): string[] {
+	const wrapped: string[] = [];
+	for (const source of sourceRows) {
+		for (const logicalLine of source.split("\n")) {
+			let remaining = logicalLine;
+			do {
+				const row = sliceByColumn(remaining, 0, width, true);
+				wrapped.push(row);
+				remaining = sliceByColumn(
+					remaining,
+					visibleWidth(row),
+					Math.max(0, visibleWidth(remaining) - visibleWidth(row)),
+					true,
+				);
+			} while (remaining.length > 0);
+		}
+	}
+	if (wrapped.length <= maxRows) return wrapped;
+	const result = wrapped.slice(0, maxRows);
+	result[maxRows - 1] = `${sliceByColumn(result[maxRows - 1] ?? "", 0, Math.max(0, width - 1), true)}…`;
+	return result;
+}