pi-libtui 0.3.2

package/src/render-epoch.ts

@@ -0,0 +1,48 @@
+const RENDER_EPOCH_KEY = Symbol.for("pi-libtui/render-epoch/v1");
+const RENDER_EPOCH_TAG = "pi-libtui/render-epoch/v1" as const;
+
+// type-boundary: Symbol.for state may come from another installed libtui realm; validate it before use.
+type UntrustedRenderEpochValue = unknown;
+
+interface RenderEpochRegistry {
+	readonly tag: typeof RENDER_EPOCH_TAG;
+	readonly current: () => number;
+	readonly bump: () => void;
+}
+
+function isRenderEpochRegistry(value: UntrustedRenderEpochValue): value is RenderEpochRegistry {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<RenderEpochRegistry>;
+	return (
+		candidate.tag === RENDER_EPOCH_TAG &&
+		typeof candidate.current === "function" &&
+		typeof candidate.bump === "function"
+	);
+}
+
+function renderEpochRegistry(scope: typeof globalThis = globalThis): RenderEpochRegistry {
+	const slots = scope as Record<PropertyKey, UntrustedRenderEpochValue>;
+	const existing = slots[RENDER_EPOCH_KEY];
+	if (isRenderEpochRegistry(existing)) return existing;
+
+	let epoch = 0;
+	const registry: RenderEpochRegistry = {
+		tag: RENDER_EPOCH_TAG,
+		current: () => epoch,
+		bump: () => {
+			epoch += 1;
+		},
+	};
+	slots[RENDER_EPOCH_KEY] = registry;
+	return registry;
+}
+
+/** Return the current process-wide rendering epoch. */
+export function getTuiRenderEpoch(): number {
+	return renderEpochRegistry().current();
+}
+
+/** Advance the rendering epoch after effective shared appearance changes. */
+export function bumpTuiRenderEpoch(): void {
+	renderEpochRegistry().bump();
+}

package/src/request-animation.ts

@@ -0,0 +1,160 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getTuiAppearance, requestPhaseAnimation, subscribeTuiAppearance, type TuiRequestPhase } from "./appearance.ts";
+import { activityPresentationCadenceMs, activityPresentationFrame } from "./activity-presentation.ts";
+import { tuiTheme } from "./color/theme.ts";
+import { type MotionMount, type MotionScheduler, sharedMotionScheduler } from "./motion.ts";
+
+type RequestAnimationUi = Pick<ExtensionContext["ui"], "setWorkingIndicator" | "setWorkingMessage" | "theme">;
+
+interface RequestAnimationContext {
+	ui: RequestAnimationUi;
+}
+
+interface RequestAnimationControllerOptions {
+	now?: () => number;
+	scheduler?: MotionScheduler;
+	width?: () => number;
+}
+
+/** Owns Pi's streaming status animation across thinking, working, and tool phases. */
+export class RequestAnimationController {
+	private readonly activeTools = new Set<string>();
+	private readonly now: () => number;
+	private readonly scheduler: MotionScheduler;
+	private readonly unsubscribeAppearance: () => void;
+	private readonly width: () => number;
+	private context?: RequestAnimationContext;
+	private mount?: MotionMount;
+	private phase?: TuiRequestPhase;
+	private phaseStartedAt = 0;
+	private thinking = false;
+
+	constructor(options: RequestAnimationControllerOptions = {}) {
+		this.now = options.now ?? (() => performance.now());
+		this.scheduler = options.scheduler ?? sharedMotionScheduler;
+		this.width = options.width ?? (() => Math.max(10, (process.stdout.columns || 80) - 4));
+		this.unsubscribeAppearance = subscribeTuiAppearance(() => {
+			if (!this.context) return;
+			this.remount();
+			this.render();
+		});
+	}
+
+	start(context: RequestAnimationContext): void {
+		this.stop();
+		this.context = context;
+		this.phase = "working";
+		this.phaseStartedAt = this.now();
+		context.ui.setWorkingIndicator({ frames: [] });
+		this.remount();
+		this.render();
+	}
+
+	finish(context?: RequestAnimationContext): void {
+		this.stop(context);
+	}
+
+	setThinking(active: boolean): void {
+		if (this.thinking === active) return;
+		this.thinking = active;
+		this.syncPhase();
+	}
+
+	startTool(toolCallId: string): void {
+		const before = this.activeTools.size;
+		this.activeTools.add(toolCallId);
+		if (this.activeTools.size !== before) this.syncPhase();
+	}
+
+	finishTool(toolCallId: string): void {
+		if (!this.activeTools.delete(toolCallId)) return;
+		this.syncPhase();
+	}
+
+	dispose(context?: RequestAnimationContext): void {
+		this.stop(context);
+		this.unsubscribeAppearance();
+	}
+
+	private stop(context?: RequestAnimationContext): void {
+		const ui = context?.ui ?? this.context?.ui;
+		this.mount?.dispose();
+		this.mount = undefined;
+		this.context = undefined;
+		this.phase = undefined;
+		this.thinking = false;
+		this.activeTools.clear();
+		if (!ui) return;
+		ui.setWorkingMessage();
+		ui.setWorkingIndicator();
+	}
+
+	private syncPhase(): void {
+		if (!this.context) return;
+		const next: TuiRequestPhase = this.thinking ? "thinking" : this.activeTools.size > 0 ? "tool" : "working";
+		if (next === this.phase) return;
+		this.phase = next;
+		this.phaseStartedAt = this.now();
+		this.remount();
+		this.render();
+	}
+
+	private remount(): void {
+		this.mount?.dispose();
+		this.mount = undefined;
+		if (!this.context || !this.phase) return;
+		const appearance = getTuiAppearance();
+		const presentation = requestPhaseAnimation(this.phase, appearance);
+		const cadenceMs = activityPresentationCadenceMs(
+			presentation,
+			appearance.animationSmoothness,
+			appearance.animationSpeed,
+		);
+		if (cadenceMs === undefined) return;
+		this.mount = this.scheduler.mount({ requestRender: () => this.render() }, { cadenceMs });
+	}
+
+	private render(): void {
+		if (!this.context || !this.phase) return;
+		const appearance = getTuiAppearance();
+		const presentation = requestPhaseAnimation(this.phase, appearance);
+		const frame = activityPresentationFrame(
+			tuiTheme(this.context.ui.theme),
+			presentation,
+			this.phase,
+			phaseLabel(this.phase),
+			this.now() - this.phaseStartedAt,
+			this.width(),
+			{
+				animationSpeed: appearance.animationSpeed,
+				animationSmoothness: appearance.animationSmoothness,
+			},
+		);
+		this.context.ui.setWorkingMessage(frame.marker ? `${frame.marker} ${frame.text}` : frame.text);
+	}
+}
+
+function phaseLabel(phase: TuiRequestPhase): string {
+	return phase === "thinking" ? "Thinking..." : phase === "tool" ? "Running..." : "Working...";
+}
+
+/** Bind the shared request animation to Pi's public lifecycle and status APIs. */
+export function registerRequestAnimation(pi: ExtensionAPI): RequestAnimationController {
+	const controller = new RequestAnimationController();
+	pi.on("agent_start", (_event, context) => controller.start(context));
+	pi.on("agent_end", (_event, context) => controller.finish(context));
+	pi.on("message_update", (event) => {
+		const type = event.assistantMessageEvent.type;
+		if (type === "thinking_start" || type === "thinking_delta") controller.setThinking(true);
+		if (type === "thinking_end" || type === "text_start" || type === "text_delta") controller.setThinking(false);
+	});
+	pi.on("message_end", () => controller.setThinking(false));
+	pi.on("tool_execution_start", (event) => controller.startTool(event.toolCallId));
+	pi.on("tool_execution_end", (event) => controller.finishTool(event.toolCallId));
+	pi.on("session_before_switch", (_event, context) => controller.finish(context));
+	pi.on("session_shutdown", (event, context) => {
+		if (event.reason === "reload" || event.reason === "quit") controller.dispose(context);
+		else controller.finish(context);
+	});
+	return controller;
+}

package/src/scrollbar.ts

@@ -0,0 +1,27 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { tuiTheme } from "./color/theme.ts";
+
+/** Paint the compact scrollbar shared by settings and expanded tool views. */
+export function applyScrollbar(
+	lines: readonly string[],
+	options: { theme: Theme; width: number; height: number; offset: number; total: number },
+): string[] {
+	const width = Math.max(0, Math.floor(options.width));
+	const height = Math.max(0, Math.floor(options.height));
+	if (width <= 1 || height === 0 || options.total <= height) return [...lines];
+	const output = [...lines];
+	const colors = tuiTheme(options.theme);
+	const thumbHeight = Math.max(1, Math.floor((height * height) / options.total));
+	const trackHeight = height - thumbHeight;
+	const maxOffset = Math.max(1, options.total - height);
+	const thumbStart = Math.min(trackHeight, Math.floor((Math.max(0, options.offset) * trackHeight) / maxOffset));
+	const contentWidth = Math.max(0, width - 2);
+	for (let row = 0; row < height; row += 1) {
+		const line = truncateToWidth(output[row] ?? "", contentWidth, "");
+		const padded = `${line}${" ".repeat(Math.max(0, contentWidth - visibleWidth(line)))}`;
+		const thumb = row >= thumbStart && row < thumbStart + thumbHeight;
+		output[row] = `${padded} ${thumb ? colors.fg("accent", "█") : colors.fg("text.muted", "│")}`;
+	}
+	return output;
+}

package/src/selection.ts

@@ -0,0 +1,148 @@
+export const SELECTION_REGISTRY_KEY = Symbol.for("pi-libtui/selection/v1");
+export const SELECTION_PROTOCOL = "pi-libtui/selection/v1" as const;
+
+export interface SelectionPoint {
+	row: number;
+	col: number;
+}
+
+export type SelectionShape = "character" | "line" | "column";
+export type MessageIdStability = "stable" | "best-effort";
+
+export interface SelectionOffsetRange {
+	start: number;
+	end: number;
+}
+
+export interface SelectionQuoteAnchor {
+	exact: string;
+	prefix?: string;
+	suffix?: string;
+}
+
+export interface SelectionSourceAnchor {
+	messageId?: string;
+	messageIdStability?: MessageIdStability;
+	offsets?: SelectionOffsetRange;
+	quote?: SelectionQuoteAnchor;
+}
+
+export interface NativeSelectionGeometry {
+	shape: SelectionShape;
+	logical: { start: SelectionPoint; end: SelectionPoint };
+	screen: { start: SelectionPoint; end: SelectionPoint };
+}
+
+export interface NativeSelectionCompleted extends NativeSelectionGeometry {
+	text: string;
+	source?: SelectionSourceAnchor;
+}
+
+export type SelectionCompletedListener = (selection: NativeSelectionCompleted) => void;
+export interface SelectionActionRequest extends NativeSelectionCompleted {
+	action: string;
+	/** Screen position used to anchor an action overlay, independent of the selected range. */
+	screenAnchor?: SelectionPoint;
+	/** Ask the selection host to display cursor-local feedback without writing into the transcript. */
+	showFeedback?(feedback: { message: string; kind: "success" | "warning" }): void;
+}
+export type SelectionActionResult = boolean;
+export type SelectionActionListener = (
+	request: SelectionActionRequest,
+) => SelectionActionResult | undefined | Promise<SelectionActionResult | undefined>;
+
+export interface SelectionRegistry {
+	readonly protocol: typeof SELECTION_PROTOCOL;
+	readonly version: 1;
+	onSelectionCompleted(listener: SelectionCompletedListener): () => void;
+	publishSelectionCompleted(selection: NativeSelectionCompleted): void;
+	onSelectionAction(listener: SelectionActionListener): () => void;
+	publishSelectionAction(request: SelectionActionRequest): Promise<SelectionActionResult>;
+}
+
+type RegistryState = { listeners: Set<SelectionCompletedListener>; actionListeners: Set<SelectionActionListener> };
+const STATE_KEY = Symbol.for("pi-libtui/selection-state/v1");
+const states = new WeakMap<SelectionRegistry, RegistryState>();
+
+// type-boundary: Symbol.for capabilities can be populated by another extension realm; this validator narrows the public methods.
+type UntrustedRegistryValue = unknown;
+
+function isRegistry(value: UntrustedRegistryValue): value is SelectionRegistry {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<SelectionRegistry>;
+	return (
+		candidate.protocol === SELECTION_PROTOCOL &&
+		candidate.version === 1 &&
+		typeof candidate.onSelectionCompleted === "function" &&
+		typeof candidate.publishSelectionCompleted === "function" &&
+		typeof candidate.onSelectionAction === "function" &&
+		typeof candidate.publishSelectionAction === "function"
+	);
+}
+
+function stateFor(registry: SelectionRegistry): RegistryState {
+	const existing = states.get(registry);
+	if (existing) return existing;
+	const shared = Reflect.get(registry as object, STATE_KEY) as UntrustedRegistryValue;
+	if (isState(shared)) {
+		states.set(registry, shared);
+		return shared;
+	}
+	const state = {
+		listeners: new Set<SelectionCompletedListener>(),
+		actionListeners: new Set<SelectionActionListener>(),
+	};
+	Object.defineProperty(registry, STATE_KEY, { value: state, enumerable: false, configurable: false });
+	states.set(registry, state);
+	return state;
+}
+
+function isState(value: UntrustedRegistryValue): value is RegistryState {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<RegistryState>;
+	return isSet(candidate.listeners) && isSet(candidate.actionListeners);
+}
+
+function isSet(value: UntrustedRegistryValue): value is Set<never> {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as { add?: UntrustedRegistryValue; delete?: UntrustedRegistryValue };
+	return typeof candidate.add === "function" && typeof candidate.delete === "function";
+}
+
+export function ensureSelectionRegistry(scope: typeof globalThis = globalThis): SelectionRegistry {
+	const slots = scope as Record<PropertyKey, UntrustedRegistryValue>;
+	const existing = slots[SELECTION_REGISTRY_KEY];
+	if (isRegistry(existing)) return existing;
+	const registry: SelectionRegistry = {
+		protocol: SELECTION_PROTOCOL,
+		version: 1,
+		onSelectionCompleted(listener) {
+			const state = stateFor(registry);
+			state.listeners.add(listener);
+			return () => state.listeners.delete(listener);
+		},
+		publishSelectionCompleted(selection) {
+			for (const listener of [...stateFor(registry).listeners]) {
+				try {
+					listener(selection);
+				} catch {
+					// Optional listeners must not affect native selection or clipboard behavior.
+				}
+			}
+		},
+		onSelectionAction(listener) {
+			const state = stateFor(registry);
+			state.actionListeners.add(listener);
+			return () => state.actionListeners.delete(listener);
+		},
+		async publishSelectionAction(request) {
+			const results = await Promise.allSettled(
+				[...stateFor(registry).actionListeners].map((listener) => Promise.resolve().then(() => listener(request))),
+			);
+			return results.some((result) => result.status === "fulfilled" && result.value === true);
+		},
+	};
+	stateFor(registry);
+	slots[SELECTION_REGISTRY_KEY] = registry;
+	return registry;
+}

package/src/split-pane.ts

@@ -0,0 +1,232 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import type { TuiMouseEvent } from "./mouse/events.ts";
+
+export const SPLIT_PANE_REGISTRY_KEY = Symbol.for("pi-libtui/split-panes/v2");
+export const SPLIT_PANE_PROTOCOL = "pi-libtui/split-panes/v2" as const;
+
+export type SplitPanePosition = "left" | "right";
+export type SplitPaneComponent = Component & {
+	/** The component already enforces the width passed to render. */
+	readonly rendersWithinWidth?: true;
+	/** Whether this input can only change the component after later asynchronous output. */
+	defersInputRender?(data: string): boolean;
+	onMouse?(event: TuiMouseEvent): boolean;
+	/** Return false while this pane should remain pointer- and action-interactive without taking keyboard focus. */
+	acceptsFocus?(): boolean;
+	dispose?(): void;
+};
+
+/** Renderer access available to a split-pane component. */
+export interface SplitPaneHost {
+	/** The active fullscreen renderer. */
+	readonly tui: TUI;
+	/** Current pane viewport size. Falls back to the renderer size until layout geometry exists. */
+	getTerminalSize(): { columns: number; rows: number };
+	requestRender(): void;
+	/** Focus this pane, remembering the component that should regain focus. */
+	focus(): void;
+	/** Restore the remembered focus target when this pane still owns focus. */
+	blur(): void;
+	/** Whether this pane currently receives terminal input. */
+	isFocused(): boolean;
+}
+
+export type SplitPaneComponentFactory = (host: SplitPaneHost, theme: Theme) => SplitPaneComponent;
+
+/** One optional pane composed beside Pi's complete fullscreen layout. */
+export interface SplitPaneDefinition {
+	/** Stable diagnostic identity for the contribution. */
+	readonly id: string;
+	/** Side of Pi's main pane. */
+	readonly position: SplitPanePosition;
+	/** Component created separately for each fullscreen renderer. */
+	readonly component: SplitPaneComponentFactory;
+	/** Initial pane width in terminal cells. */
+	readonly size: number;
+	/** Initial share of the terminal width when no committed size has been restored. */
+	readonly initialRatio?: number;
+	/** Called once when a pointer resize is committed. */
+	readonly onResize?: (size: number) => void;
+	/** Minimum width reserved for Pi's main pane. */
+	readonly minMainSize: number;
+	/** Empty cells beside the draggable border. Defaults to one. */
+	readonly gap?: number;
+	/** Visibility priority. Highest wins; the latest mount wins ties. Defaults to zero. */
+	readonly priority?: number;
+}
+
+/** Validated split-pane definition stored by the shared registry. */
+export interface MountedSplitPane extends Omit<SplitPaneDefinition, "gap" | "priority"> {
+	readonly gap: number;
+	readonly priority: number;
+}
+
+export interface SplitPaneRegistry {
+	readonly protocol: typeof SPLIT_PANE_PROTOCOL;
+	readonly version: 2;
+	mount(definition: SplitPaneDefinition): () => void;
+	current(): MountedSplitPane | undefined;
+	subscribe(listener: () => void): () => void;
+}
+
+interface SplitPaneRegistryState {
+	readonly panes: MountedSplitPane[];
+	readonly listeners: Array<() => void>;
+}
+
+const STATE_KEY = Symbol.for("pi-libtui/split-panes/state/v2");
+const states = new WeakMap<SplitPaneRegistry, SplitPaneRegistryState>();
+
+// type-boundary: Symbol.for capabilities can be populated by another extension realm; this validator narrows the public methods.
+type UntrustedRegistryValue = unknown;
+
+function isRegistry(value: UntrustedRegistryValue): value is SplitPaneRegistry {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<SplitPaneRegistry>;
+	return (
+		candidate.protocol === SPLIT_PANE_PROTOCOL &&
+		candidate.version === 2 &&
+		typeof candidate.mount === "function" &&
+		typeof candidate.current === "function" &&
+		typeof candidate.subscribe === "function"
+	);
+}
+
+function isState(value: UntrustedRegistryValue): value is SplitPaneRegistryState {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<SplitPaneRegistryState>;
+	return Array.isArray(candidate.panes) && Array.isArray(candidate.listeners);
+}
+
+function stateFor(registry: SplitPaneRegistry): SplitPaneRegistryState {
+	const cached = states.get(registry);
+	if (cached) return cached;
+	const shared = Reflect.get(registry as object, STATE_KEY) as UntrustedRegistryValue;
+	if (isState(shared)) {
+		states.set(registry, shared);
+		return shared;
+	}
+	const state: SplitPaneRegistryState = { panes: [], listeners: [] };
+	Object.defineProperty(registry, STATE_KEY, { configurable: false, enumerable: false, value: state });
+	states.set(registry, state);
+	return state;
+}
+
+function positiveInteger(value: number, name: string): number {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive integer`);
+	return value;
+}
+
+function nonNegativeInteger(value: number, name: string): number {
+	if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${name} must be a non-negative integer`);
+	return value;
+}
+
+function integer(value: number, name: string): number {
+	if (!Number.isSafeInteger(value)) throw new RangeError(`${name} must be a safe integer`);
+	return value;
+}
+
+function normalized(definition: SplitPaneDefinition): MountedSplitPane {
+	if (definition.id.trim().length === 0) throw new TypeError("split pane id must not be empty");
+	if (definition.position !== "left" && definition.position !== "right") {
+		throw new TypeError('split pane position must be "left" or "right"');
+	}
+	if (typeof definition.component !== "function") throw new TypeError("split pane component must be a factory");
+	const size = positiveInteger(definition.size, "split pane size");
+	if (
+		definition.initialRatio !== undefined &&
+		(!Number.isFinite(definition.initialRatio) || definition.initialRatio <= 0 || definition.initialRatio >= 1)
+	) {
+		throw new RangeError("split pane initial ratio must be between zero and one");
+	}
+	if (definition.onResize !== undefined && typeof definition.onResize !== "function") {
+		throw new TypeError("split pane resize callback must be a function");
+	}
+	return {
+		id: definition.id,
+		position: definition.position,
+		component: definition.component,
+		size,
+		...(definition.initialRatio === undefined ? {} : { initialRatio: definition.initialRatio }),
+		...(definition.onResize === undefined ? {} : { onResize: definition.onResize }),
+		minMainSize: positiveInteger(definition.minMainSize, "split pane minimum main size"),
+		gap: nonNegativeInteger(definition.gap ?? 1, "split pane gap"),
+		priority: integer(definition.priority ?? 0, "split pane priority"),
+	};
+}
+
+function currentPane(state: SplitPaneRegistryState): MountedSplitPane | undefined {
+	let selected: MountedSplitPane | undefined;
+	for (const pane of state.panes) {
+		if (!selected || pane.priority >= selected.priority) selected = pane;
+	}
+	return selected;
+}
+
+function removeIdentity<T>(values: T[], value: T): boolean {
+	const index = values.indexOf(value);
+	if (index < 0) return false;
+	values.splice(index, 1);
+	return true;
+}
+
+function notify(state: SplitPaneRegistryState): void {
+	for (const listener of [...state.listeners]) {
+		try {
+			listener();
+		} catch {
+			// Optional consumers must not break other split-pane contributions.
+		}
+	}
+}
+
+/** Resolve or create the process-wide split-pane registry. */
+export function ensureSplitPaneRegistry(scope: typeof globalThis = globalThis): SplitPaneRegistry {
+	const slots = scope as Record<PropertyKey, UntrustedRegistryValue>;
+	const existing = slots[SPLIT_PANE_REGISTRY_KEY];
+	if (isRegistry(existing)) {
+		stateFor(existing);
+		return existing;
+	}
+	const registry: SplitPaneRegistry = {
+		protocol: SPLIT_PANE_PROTOCOL,
+		version: 2,
+		mount(definition) {
+			const pane = normalized(definition);
+			const state = stateFor(registry);
+			const previous = currentPane(state);
+			state.panes.push(pane);
+			if (currentPane(state) !== previous) notify(state);
+			let disposed = false;
+			return () => {
+				if (disposed) return;
+				disposed = true;
+				const previous = currentPane(state);
+				if (removeIdentity(state.panes, pane) && currentPane(state) !== previous) notify(state);
+			};
+		},
+		current() {
+			return currentPane(stateFor(registry));
+		},
+		subscribe(listener) {
+			const state = stateFor(registry);
+			state.listeners.push(listener);
+			let disposed = false;
+			return () => {
+				if (disposed) return;
+				disposed = true;
+				removeIdentity(state.listeners, listener);
+			};
+		},
+	};
+	stateFor(registry);
+	slots[SPLIT_PANE_REGISTRY_KEY] = registry;
+	return registry;
+}
+
+/** Mount one pane beside Pi's fullscreen layout until the returned lease is disposed. */
+export function mountSplitPane(definition: SplitPaneDefinition, scope: typeof globalThis): () => void {
+	return ensureSplitPaneRegistry(scope).mount(definition);
+}