pi-libtui 0.3.2

package/src/editor/composition.ts

@@ -0,0 +1,53 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** The editor factory shape exposed by Pi's interactive UI. */
+export type EditorFactory = NonNullable<ReturnType<ExtensionContext["ui"]["getEditorComponent"]>>;
+
+/** The small UI surface required to compose editor factories. */
+export type EditorUi = Pick<ExtensionContext["ui"], "getEditorComponent" | "setEditorComponent">;
+
+/** Wrap an existing editor factory while preserving other installed layers. */
+export type EditorLayer = (previous: EditorFactory | undefined) => EditorFactory;
+
+interface EditorLayerState {
+	base: EditorFactory | undefined;
+	layers: Map<symbol, EditorLayer>;
+	applied: EditorFactory | undefined;
+}
+
+const states = new WeakMap<object, EditorLayerState>();
+
+function compose(state: EditorLayerState): EditorFactory | undefined {
+	let factory = state.base;
+	for (const layer of state.layers.values()) factory = layer(factory);
+	return factory;
+}
+
+/** Install an idempotently removable editor layer on one Pi UI instance. */
+export function installEditorLayer(ui: EditorUi, id: symbol, layer: EditorLayer): () => void {
+	const key = ui as object;
+	let state = states.get(key);
+	if (!state) {
+		state = { base: ui.getEditorComponent(), layers: new Map(), applied: undefined };
+		states.set(key, state);
+	}
+	state.layers.set(id, layer);
+	const applied = compose(state);
+	state.applied = applied;
+	ui.setEditorComponent(applied);
+
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		const current = states.get(key);
+		if (!current || current.layers.get(id) !== layer) return;
+		current.layers.delete(id);
+		if (ui.getEditorComponent() === current.applied) {
+			const next = compose(current);
+			current.applied = next;
+			ui.setEditorComponent(next);
+		}
+		if (current.layers.size === 0) states.delete(key);
+	};
+}

package/src/editor/layout.ts

@@ -0,0 +1,81 @@
+import type { Component, TUI } from "@earendil-works/pi-tui";
+
+// type-boundary: Pi 0.84.x keeps its active layout root and stack entries private; the guards below narrow them.
+type PiLayoutValue = unknown;
+
+interface LayoutEntry {
+	component: Component;
+	minSize?: number;
+}
+
+export interface EditorMinimumRowsLease {
+	reconcile(editor: Component): void;
+	dispose(): void;
+}
+
+function isComponent(value: PiLayoutValue): value is Component {
+	return typeof value === "object" && value !== null && typeof Reflect.get(value, "render") === "function";
+}
+
+function isLayoutEntry(value: PiLayoutValue): value is LayoutEntry {
+	return typeof value === "object" && value !== null && isComponent(Reflect.get(value, "component"));
+}
+
+function childComponents(component: Component): readonly Component[] {
+	const children = Reflect.get(component, "children") as PiLayoutValue;
+	return Array.isArray(children) ? children.filter(isComponent) : [];
+}
+
+function layoutEntries(component: Component): readonly LayoutEntry[] {
+	const entries = Reflect.get(component, "entries") as PiLayoutValue;
+	return Array.isArray(entries) ? entries.filter(isLayoutEntry) : [];
+}
+
+function contains(root: Component, target: Component, seen = new Set<object>()): boolean {
+	if (root === target) return true;
+	if (seen.has(root)) return false;
+	seen.add(root);
+	return childComponents(root).some((child) => contains(child, target, seen));
+}
+
+function editorEntry(root: Component, editor: Component, seen = new Set<object>()): LayoutEntry | undefined {
+	if (seen.has(root)) return undefined;
+	seen.add(root);
+	for (const entry of layoutEntries(root)) {
+		const nested = editorEntry(entry.component, editor, seen);
+		if (nested) return nested;
+		if (contains(entry.component, editor)) return entry;
+	}
+	for (const child of childComponents(root)) {
+		const nested = editorEntry(child, editor, seen);
+		if (nested) return nested;
+	}
+	return undefined;
+}
+
+/** Adapt Pi's dock allocation to a borderless editor while tolerating hosts without the expected private layout shape. */
+export function installEditorMinimumRows(tui: TUI, minimumRows: number): EditorMinimumRowsLease {
+	const rows = Math.max(0, Math.floor(minimumRows));
+	let active = true;
+	let entry: LayoutEntry | undefined;
+	let originalMinimum: number | undefined;
+	return {
+		reconcile(editor) {
+			if (!active) return;
+			if (!entry || !contains(entry.component, editor)) {
+				const root = Reflect.get(tui as object, "layoutRoot") as PiLayoutValue;
+				if (!isComponent(root)) return;
+				entry = editorEntry(root, editor);
+				if (!entry) return;
+				originalMinimum = entry.minSize;
+			}
+			entry.minSize = rows;
+		},
+		dispose() {
+			if (!active) return;
+			active = false;
+			if (entry?.minSize === rows) entry.minSize = originalMinimum;
+			tui.requestRender();
+		},
+	};
+}

package/src/editor/presentation.ts

@@ -0,0 +1,35 @@
+import { CustomEditor, type KeybindingsManager, type Theme } from "@earendil-works/pi-coding-agent";
+import type { EditorTheme, TUI } from "@earendil-works/pi-tui";
+import { tuiTheme } from "../color/theme.ts";
+
+/**
+ * Adapt pi-libtui semantic colors to every color role in Pi's native editor.
+ * @param theme Active Pi theme used to generate semantic pi-libtui colors.
+ * @returns A complete native `EditorTheme` for borders and autocomplete rows.
+ */
+export function semanticEditorTheme(theme: Theme): EditorTheme {
+	const colors = tuiTheme(theme);
+	return {
+		borderColor: (text) => colors.fg("border", text),
+		selectList: {
+			selectedPrefix: (text) => colors.fg("accent", text),
+			selectedText: (text) => colors.fg("accent", text),
+			description: (text) => colors.fg("text.muted", text),
+			scrollInfo: (text) => colors.fg("text.muted", text),
+			noMatch: (text) => colors.fg("text.muted", text),
+		},
+	};
+}
+
+/** Pi's extensible editor with all native color roles owned by pi-libtui. */
+export class SemanticEditor extends CustomEditor {
+	/**
+	 * Create an extensible Pi editor backed by pi-libtui semantic colors.
+	 * @param tui TUI instance used by the native editor.
+	 * @param theme Active Pi theme converted through {@link semanticEditorTheme}.
+	 * @param keybindings Active application keybindings forwarded to `CustomEditor`.
+	 */
+	constructor(tui: TUI, theme: Theme, keybindings: KeybindingsManager) {
+		super(tui, semanticEditorTheme(theme), keybindings);
+	}
+}

package/src/editor/protocol.ts

@@ -0,0 +1,188 @@
+export const EDITOR_REGISTRY_KEY = Symbol.for("pi-libtui/editor/registry/v1");
+export const EDITOR_PROTOCOL = "pi-libtui/editor/registry/v1" as const;
+
+export interface EditorPasteHandler {
+	readonly id: string;
+	readonly priority?: number;
+	handle(text: string): string | undefined;
+}
+
+export interface EditorRenderDecorator {
+	readonly id: string;
+	readonly priority?: number;
+	decorate(lines: readonly string[], width: number): string[];
+}
+
+export interface EditorRegistry {
+	readonly protocol: typeof EDITOR_PROTOCOL;
+	readonly version: 1;
+	registerPasteHandler(handler: EditorPasteHandler): () => void;
+	registerRenderDecorator(decorator: EditorRenderDecorator): () => void;
+}
+
+interface RegistryState {
+	pasteHandlers: EditorPasteHandler[];
+	renderDecorators: EditorRenderDecorator[];
+}
+
+// type-boundary: Symbol.for capabilities can be populated by another extension realm; these validators narrow them.
+type UntrustedRegistryValue = unknown;
+
+const STATE_KEY = Symbol.for("pi-libtui/editor/registry-state/v1");
+const states = new WeakMap<EditorRegistry, RegistryState>();
+
+function isRecord(value: UntrustedRegistryValue): value is Record<PropertyKey, UntrustedRegistryValue> {
+	return value !== null && typeof value === "object";
+}
+
+function hasPriority(value: Record<PropertyKey, UntrustedRegistryValue>): boolean {
+	return value.priority === undefined || (typeof value.priority === "number" && Number.isFinite(value.priority));
+}
+
+function isPasteHandler(value: UntrustedRegistryValue): value is EditorPasteHandler {
+	return isRecord(value) && typeof value.id === "string" && hasPriority(value) && typeof value.handle === "function";
+}
+
+function isRenderDecorator(value: UntrustedRegistryValue): value is EditorRenderDecorator {
+	return isRecord(value) && typeof value.id === "string" && hasPriority(value) && typeof value.decorate === "function";
+}
+
+function isState(value: UntrustedRegistryValue): value is RegistryState {
+	if (!isRecord(value)) return false;
+	return (
+		Array.isArray(value.pasteHandlers) &&
+		value.pasteHandlers.every(isPasteHandler) &&
+		Array.isArray(value.renderDecorators) &&
+		value.renderDecorators.every(isRenderDecorator)
+	);
+}
+
+function stateOf(value: UntrustedRegistryValue): RegistryState | undefined {
+	if (!isRecord(value)) return undefined;
+	try {
+		const state = Reflect.get(value, STATE_KEY) as UntrustedRegistryValue;
+		return isState(state) ? state : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function isRegistry(value: UntrustedRegistryValue): value is EditorRegistry {
+	if (!isRecord(value)) return false;
+	try {
+		return (
+			value.protocol === EDITOR_PROTOCOL &&
+			value.version === 1 &&
+			typeof value.registerPasteHandler === "function" &&
+			typeof value.registerRenderDecorator === "function" &&
+			stateOf(value) !== undefined
+		);
+	} catch {
+		return false;
+	}
+}
+
+function stateFor(registry: EditorRegistry): RegistryState {
+	const local = states.get(registry);
+	if (local && isState(local)) return local;
+	const shared = stateOf(registry);
+	if (shared) {
+		states.set(registry, shared);
+		return shared;
+	}
+	const state: RegistryState = { pasteHandlers: [], renderDecorators: [] };
+	try {
+		Object.defineProperty(registry, STATE_KEY, { value: state, enumerable: false });
+	} catch {
+		// A malformed non-configurable state from another realm must not break local editor dispatch.
+	}
+	states.set(registry, state);
+	return state;
+}
+
+function ordered<T extends { readonly priority?: number }>(values: readonly T[]): T[] {
+	return [...values].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0));
+}
+
+function removeIdentity<T>(values: T[], value: T): void {
+	const index = values.indexOf(value);
+	if (index >= 0) values.splice(index, 1);
+}
+
+function replaceById<T extends { readonly id: string }>(values: T[], value: T): void {
+	const index = values.findIndex((existing) => existing.id === value.id);
+	if (index >= 0) {
+		values[index] = value;
+		return;
+	}
+	values.push(value);
+}
+
+function removeActiveById<T extends { readonly id: string }>(values: T[], value: T): void {
+	const index = values.findIndex((existing) => existing.id === value.id && existing === value);
+	if (index >= 0) values.splice(index, 1);
+}
+
+export function dispatchEditorPaste(registry: EditorRegistry, text: string): string | undefined {
+	for (const handler of ordered(stateFor(registry).pasteHandlers)) {
+		try {
+			const replacement = handler.handle(text);
+			if (replacement !== undefined) return replacement;
+		} catch {
+			// Optional feature handlers must not break the editor's native paste path.
+		}
+	}
+	return undefined;
+}
+
+export function dispatchEditorRender(registry: EditorRegistry, lines: string[], width: number): string[] {
+	let rendered = lines;
+	for (const decorator of ordered(stateFor(registry).renderDecorators)) {
+		try {
+			const next = decorator.decorate(rendered, width);
+			if (Array.isArray(next) && next.every((line) => typeof line === "string")) rendered = next;
+		} catch {
+			// Rendering from one optional feature must not take down the editor.
+		}
+	}
+	return rendered;
+}
+
+/** Resolve the process-wide editor registry without activating any Pi host behavior. */
+export function ensureEditorRegistry(scope: typeof globalThis = globalThis): EditorRegistry {
+	const slots = scope as Record<PropertyKey, UntrustedRegistryValue>;
+	const existing = slots[EDITOR_REGISTRY_KEY];
+	if (isRegistry(existing)) {
+		const state = stateOf(existing);
+		if (state) states.set(existing, state);
+		return existing;
+	}
+
+	const registry: EditorRegistry = {
+		protocol: EDITOR_PROTOCOL,
+		version: 1,
+		registerPasteHandler(handler) {
+			const handlers = stateFor(registry).pasteHandlers;
+			handlers.push(handler);
+			let active = true;
+			return () => {
+				if (!active) return;
+				active = false;
+				removeIdentity(handlers, handler);
+			};
+		},
+		registerRenderDecorator(decorator) {
+			const decorators = stateFor(registry).renderDecorators;
+			replaceById(decorators, decorator);
+			let active = true;
+			return () => {
+				if (!active) return;
+				active = false;
+				removeActiveById(decorators, decorator);
+			};
+		},
+	};
+	stateFor(registry);
+	slots[EDITOR_REGISTRY_KEY] = registry;
+	return registry;
+}

package/src/editor.ts

@@ -0,0 +1,41 @@
+export { SemanticEditor, semanticEditorTheme } from "./editor/presentation.ts";
+export {
+	composeEditorStatus,
+	editorCompositionCadenceMs,
+	editorCompositionContentWidth,
+	editorStatusSeparator,
+	type EditorBottomTreatment,
+	type EditorCompositionPreview,
+	type EditorCompositionRenderOptions,
+	type EditorCompositionStatus,
+	type EditorCompositionStyle,
+	type EditorPromptMarkerMotion,
+	type EditorRailStyle,
+	type EditorStatusBandStyle,
+	type EditorStatusSeparator,
+	type EditorSurfaceStyle,
+	type EditorTopTreatment,
+	renderEditorComposition,
+	renderEditorCompositionPreview,
+	renderEditorCompositionStatus,
+} from "./editor/chrome.ts";
+export {
+	type EditorFactory,
+	type EditorLayer,
+	type EditorUi,
+	installEditorLayer,
+} from "./editor/composition.ts";
+export {
+	type EditorMinimumRowsLease,
+	installEditorMinimumRows,
+} from "./editor/layout.ts";
+export {
+	dispatchEditorPaste,
+	dispatchEditorRender,
+	EDITOR_PROTOCOL,
+	EDITOR_REGISTRY_KEY,
+	type EditorPasteHandler,
+	type EditorRegistry,
+	type EditorRenderDecorator,
+	ensureEditorRegistry,
+} from "./editor/protocol.ts";

package/src/extension.ts

@@ -0,0 +1,30 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Color256Preview } from "./color/preview.ts";
+import { claimLibtuiExtensionHost } from "./host/extension-host.ts";
+import { FullscreenOverlay, fullscreenOverlayOptions } from "./overlay/fullscreen.ts";
+import { registerRequestAnimation } from "./request-animation.ts";
+
+export default function libtuiExtension(pi: ExtensionAPI): void {
+	const host = claimLibtuiExtensionHost(pi);
+	if (!host) return;
+	registerRequestAnimation(pi);
+	pi.registerCommand("libtui:colors", {
+		description: "Show the active terminal's 256-color palette",
+		handler: async (_args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/libtui:colors requires the interactive TUI.", "warning");
+				return;
+			}
+			await ctx.ui.custom<void>(
+				(tui, theme, _keybindings, done) =>
+					new FullscreenOverlay(tui, theme, new Color256Preview(theme, done), "256 colors · Esc or q to close"),
+				{ overlay: true, overlayOptions: fullscreenOverlayOptions() },
+			);
+		},
+	});
+	pi.on("session_start", (_event, ctx) => host.start(ctx));
+	pi.on("session_shutdown", async (event, ctx) => {
+		await host.shutdown(ctx, event.reason === "reload");
+		if (event.reason === "reload" || event.reason === "quit") host.release();
+	});
+}

package/src/folding.ts

@@ -0,0 +1,192 @@
+/** Process-wide capability for Vim-style transcript folding. */
+export const FOLDING_REGISTRY_KEY = Symbol.for("pi-libtui/folding/registry/v2");
+export const FOLDING_PROTOCOL = "pi-libtui/folding/registry/v2" as const;
+
+export type FoldOperation = "open" | "close" | "open-all" | "close-all";
+export const FOLD_TARGET_AT_ROW = Symbol.for("pi-libtui/folding/target-at-row/v1");
+
+/** A visible component that can be opened and closed by a host interaction mode. */
+export interface FoldTarget {
+	/** Whether this target is currently closed. */
+	isFolded(): boolean;
+	/** Open this target. */
+	open(): void;
+	/** Close this target. */
+	close(): void;
+}
+
+/** Structural component capability for resolving a fold from a rendered local row. */
+export interface FoldTargetAtRow {
+	readonly [FOLD_TARGET_AT_ROW]: (row: number) => FoldTarget | undefined;
+}
+
+/** Shared registry used by copy mode and other keyboard hosts. */
+export interface FoldingRegistry {
+	readonly protocol: typeof FOLDING_PROTOCOL;
+	readonly version: 2;
+	register(target: FoldTarget): () => void;
+	setCurrent(target: FoldTarget | undefined): void;
+	readonly current: FoldTarget | undefined;
+	/** Whether this exact target is still registered with the current renderer. */
+	has(target: FoldTarget): boolean;
+	/** Apply one operation to an explicitly resolved target, or to pointer focus when omitted. */
+	apply(operation: FoldOperation, target?: FoldTarget | null): boolean;
+}
+
+// type-boundary: Symbol.for state may come from another installed libtui realm; validate it before use.
+type UntrustedValue = unknown;
+type RegistryState = { targets: FoldTarget[]; current?: FoldTarget };
+const states = new WeakMap<FoldingRegistry, RegistryState>();
+const STATE_KEY = Symbol.for("pi-libtui/folding/registry-state/v2");
+
+function isRecord(value: UntrustedValue): value is Record<PropertyKey, UntrustedValue> {
+	return value !== null && typeof value === "object";
+}
+
+function isRegistry(value: UntrustedValue): value is FoldingRegistry {
+	if (!isRecord(value)) return false;
+	try {
+		return (
+			value.protocol === FOLDING_PROTOCOL &&
+			value.version === 2 &&
+			typeof value.register === "function" &&
+			typeof value.setCurrent === "function" &&
+			typeof value.has === "function" &&
+			typeof value.apply === "function" &&
+			stateOf(value) !== undefined
+		);
+	} catch {
+		return false;
+	}
+}
+
+function stateFor(registry: FoldingRegistry): RegistryState {
+	const existing = states.get(registry);
+	if (existing && isState(existing)) return existing;
+	const shared = stateOf(registry);
+	if (shared) {
+		states.set(registry, shared);
+		return shared;
+	}
+	const state: RegistryState = { targets: [] };
+	try {
+		Object.defineProperty(registry, STATE_KEY, { value: state, enumerable: false });
+	} catch {
+		// A malformed non-configurable state from another realm must not break local folding behavior.
+	}
+	states.set(registry, state);
+	return state;
+}
+
+function stateOf(value: UntrustedValue): RegistryState | undefined {
+	if (!isRecord(value)) return undefined;
+	try {
+		const state = Reflect.get(value, STATE_KEY) as UntrustedValue;
+		return isState(state) ? state : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function isState(value: UntrustedValue): value is RegistryState {
+	if (!isRecord(value) || !Array.isArray(value.targets) || !value.targets.every(isFoldTarget)) return false;
+	return value.current === undefined || (isFoldTarget(value.current) && value.targets.includes(value.current));
+}
+
+function removeIdentity(values: FoldTarget[], value: FoldTarget): void {
+	const index = values.indexOf(value);
+	if (index >= 0) values.splice(index, 1);
+}
+
+function isFoldTarget(value: UntrustedValue): value is FoldTarget {
+	if (!isRecord(value)) return false;
+	try {
+		return (
+			typeof value.isFolded === "function" && typeof value.open === "function" && typeof value.close === "function"
+		);
+	} catch {
+		return false;
+	}
+}
+
+/** Resolve a registered fold target from a component-local rendered row. */
+export function foldTargetAt(component: object, row: number): FoldTarget | undefined {
+	if (!Number.isFinite(row) || row < 0) return undefined;
+	const provider = Reflect.get(component, FOLD_TARGET_AT_ROW) as UntrustedValue;
+	if (typeof provider !== "function") return undefined;
+	try {
+		const target = Reflect.apply(provider, component, [Math.floor(row)]) as UntrustedValue;
+		return isFoldTarget(target) ? target : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Resolve or create the process-wide folding registry. */
+export function ensureFoldingRegistry(scope: typeof globalThis = globalThis): FoldingRegistry {
+	const slots = scope as Record<PropertyKey, UntrustedValue>;
+	const existing = slots[FOLDING_REGISTRY_KEY];
+	if (isRegistry(existing)) {
+		const state = stateOf(existing);
+		if (state) states.set(existing, state);
+		return existing;
+	}
+	const registry: FoldingRegistry = {
+		protocol: FOLDING_PROTOCOL,
+		version: 2,
+		register(target) {
+			const state = stateFor(registry);
+			state.targets.push(target);
+			return () => {
+				removeIdentity(state.targets, target);
+				if (state.current === target) state.current = undefined;
+			};
+		},
+		setCurrent(target) {
+			const state = stateFor(registry);
+			state.current = target && state.targets.includes(target) ? target : undefined;
+		},
+		get current() {
+			return stateFor(registry).current;
+		},
+		has(target) {
+			return stateFor(registry).targets.includes(target);
+		},
+		apply(operation, target) {
+			const state = stateFor(registry);
+			const targets = operation.endsWith("-all")
+				? [...state.targets]
+				: target && state.targets.includes(target)
+					? [target]
+					: target === undefined && state.current
+						? [state.current]
+						: [];
+			if (targets.length === 0) return false;
+			const open = operation === "open" || operation === "open-all";
+			let applied = false;
+			for (const target of targets) {
+				try {
+					if (open) target.open();
+					else target.close();
+					applied = true;
+				} catch {
+					// A feature-owned fold must not take down copy mode.
+				}
+			}
+			return applied;
+		},
+	};
+	stateFor(registry);
+	slots[FOLDING_REGISTRY_KEY] = registry;
+	return registry;
+}
+
+/**
+ * Clear a target only when it still owns the current pointer/focus slot.
+ * Leave/focus-out events can arrive after another target has already become
+ * current, so an old component must not clear the newer row.
+ */
+export function clearFoldingCurrent(target: FoldTarget, scope: typeof globalThis = globalThis): void {
+	const registry = ensureFoldingRegistry(scope);
+	if (registry.current === target) registry.setCurrent(undefined);
+}