pi-libtui 0.3.2

package/src/overlay/fullscreen.ts

@@ -0,0 +1,170 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	type Focusable,
+	isFocusable,
+	type OverlayOptions,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import { subscribeTuiAppearance } from "../appearance.ts";
+import { tuiTheme } from "../color/theme.ts";
+import { resolveTuiTitle, type TuiTitleSource } from "../decoration/status.ts";
+import { fitLine } from "../line-layout.ts";
+import type { TuiMouseEvent } from "../mouse.ts";
+
+type PointerComponent = Component & {
+	onMouse?: (event: TuiMouseEvent) => boolean;
+};
+
+type DisposableComponent = Component & {
+	dispose?(): void;
+};
+
+/**
+ * Returns Pi overlay options that cover the terminal from its top-left corner.
+ *
+ * @returns Full-width, full-height, zero-margin overlay options.
+ */
+export function fullscreenOverlayOptions(): OverlayOptions {
+	return {
+		anchor: "top-left",
+		width: "100%",
+		maxHeight: "100%",
+		margin: 0,
+	};
+}
+
+function topBorder(theme: Theme, title: string, width: number): string {
+	const colors = tuiTheme(theme);
+	const visibleTitle = truncateToWidth(title, Math.max(0, width - 5), "");
+	const label = visibleTitle ? ` ${colors.fg("accent", visibleTitle)} ` : "";
+	const used = 2 + visibleWidth(label) + 1;
+	return colors.fg("border", "╭─") + label + colors.fg("border", `${"─".repeat(Math.max(0, width - used))}╮`);
+}
+
+/** Covers the terminal with a bordered component while leaving the host TUI alive. */
+export class FullscreenOverlay implements Component, Focusable {
+	private readonly removeAppearanceSubscription: () => void;
+	private childWidth = 0;
+	private childHeight = 0;
+	private _focused = false;
+	private disposed = false;
+
+	/**
+	 * Creates a terminal-sized bordered host around a child component.
+	 *
+	 * @param tui Active Pi TUI whose terminal row count defines the overlay height.
+	 * @param theme Pi theme used to derive semantic border and title colors.
+	 * @param child Component rendered inside the one-cell frame.
+	 * @param title Static or dynamic title source rendered in the top border.
+	 */
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly child: DisposableComponent,
+		private readonly title: TuiTitleSource = "",
+	) {
+		this.removeAppearanceSubscription = subscribeTuiAppearance(() => this.tui.requestRender());
+	}
+
+	/** Whether this overlay and its focusable child own focus. */
+	get focused(): boolean {
+		return this._focused;
+	}
+	/**
+	 * Transfers focus to or from the focusable child.
+	 *
+	 * @param value Whether the overlay should own focus.
+	 */
+	set focused(value: boolean) {
+		this._focused = value;
+		if (isFocusable(this.child)) this.child.focused = value;
+	}
+
+	/**
+	 * Invalidates the child component when it supports invalidation.
+	 *
+	 * @returns Nothing.
+	 */
+	invalidate(): void {
+		this.child.invalidate?.();
+	}
+
+	/**
+	 * Releases the appearance subscription owned by this overlay.
+	 *
+	 * @returns Nothing.
+	 */
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.removeAppearanceSubscription();
+		this.child.dispose?.();
+	}
+
+	/**
+	 * Forwards raw terminal input to the child when it handles input.
+	 *
+	 * @param data Raw terminal input sequence from Pi.
+	 * @returns Nothing.
+	 */
+	handleInput(data: string): void {
+		this.child.handleInput?.(data);
+		this.tui.requestRender();
+	}
+
+	/**
+	 * Translates a frame-local pointer event into child coordinates and dispatches it.
+	 *
+	 * @param event Pointer event expressed in overlay-local coordinates.
+	 * @returns Whether the child handled the event; modal selection gestures are consumed anywhere inside the overlay.
+	 */
+	onMouse(event: TuiMouseEvent): boolean {
+		const blocksSelection = event.type === "press" || event.type === "drag" || event.type === "release";
+		const child = this.child as PointerComponent;
+		if (typeof child.onMouse !== "function") return blocksSelection;
+		const translated = { ...event, row: event.row - 1, col: event.col - 1 };
+		if (
+			event.type !== "leave" &&
+			(translated.row < 0 ||
+				translated.row >= this.childHeight ||
+				translated.col < 0 ||
+				translated.col >= this.childWidth)
+		)
+			return blocksSelection;
+		try {
+			return Reflect.apply(child.onMouse, child, [translated]) === true || blocksSelection;
+		} catch {
+			return blocksSelection;
+		}
+	}
+
+	/**
+	 * Renders a border and pads or clips the child to the current terminal height.
+	 *
+	 * @param width Available terminal width in columns.
+	 * @returns Exactly `tui.terminal.rows` rows when both dimensions can contain a frame, otherwise one blank fitted row.
+	 */
+	render(width: number): string[] {
+		const colors = tuiTheme(this.theme);
+		const height = Math.max(1, this.tui.terminal.rows);
+		if (width < 2 || height < 2) {
+			this.childWidth = 0;
+			this.childHeight = 0;
+			return [fitLine("", width)];
+		}
+		const innerWidth = width - 2;
+		const innerHeight = height - 2;
+		this.childWidth = innerWidth;
+		this.childHeight = innerHeight;
+		const content = this.child.render(innerWidth).slice(0, innerHeight);
+		while (content.length < innerHeight) content.push("");
+		return [
+			topBorder(this.theme, resolveTuiTitle(this.title), width),
+			...content.map((line) => `${colors.fg("border", "│")}${fitLine(line, innerWidth)}${colors.fg("border", "│")}`),
+			colors.fg("border", `╰${"─".repeat(innerWidth)}╯`),
+		];
+	}
+}

package/src/overlay/hover-tooltip.ts

@@ -0,0 +1,109 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
+import { compositeTuiLine, stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { sanitizeTuiText } from "../content/terminal-text.ts";
+import { renderKeyHint } from "../decoration/glyphs.ts";
+import { renderPill } from "../decoration/powerline-pill.ts";
+import type { MouseRect, MouseRegistry, ScreenDecorationContext } from "../mouse.ts";
+
+export interface HoverTooltipTarget {
+	readonly rect: MouseRect;
+	readonly label: string;
+	readonly shortcut?: KeyId;
+}
+
+export interface HoverTooltipMountOptions {
+	readonly id: string;
+	readonly theme: Theme;
+	readonly registry: MouseRegistry;
+	readonly priority?: number;
+	readonly pointerPriority?: number;
+	getTarget(screen: readonly string[], context: ScreenDecorationContext): HoverTooltipTarget | undefined;
+}
+
+export interface HoverTooltipMount {
+	dispose(): void;
+}
+
+/** Find one visible plain-text span in an ANSI-styled screen. */
+export function findScreenTextRect(screen: readonly string[], text: string): MouseRect | undefined {
+	for (const [row, line] of screen.entries()) {
+		const plain = stripTerminalSequences(line);
+		const index = plain.indexOf(text);
+		if (index < 0) continue;
+		return {
+			x: visibleWidth(plain.slice(0, index)),
+			y: row,
+			width: visibleWidth(text),
+			height: 1,
+		};
+	}
+	return undefined;
+}
+
+/** Mount a pointer-hover tooltip over any screen-locatable target. */
+export function mountHoverTooltip(options: HoverTooltipMountOptions): HoverTooltipMount {
+	let target: HoverTooltipTarget | undefined;
+	let hovered = false;
+	let disposed = 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;
+			return hovered && target ? compositeHoverTooltip(screen, context, options.theme, target) : screen;
+		},
+	});
+	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() {
+			if (disposed) return;
+			disposed = true;
+			target = undefined;
+			hovered = false;
+			removeDecorator();
+			removeRegion();
+		},
+	};
+}
+
+/** Composite a dim, borderless tooltip pill adjacent to a hovered target. */
+export function compositeHoverTooltip(
+	screen: readonly string[],
+	context: Pick<ScreenDecorationContext, "width" | "height">,
+	theme: Theme,
+	target: HoverTooltipTarget,
+): string[] {
+	const label = sanitizeTuiText(target.label).replaceAll("\n", " ").trim();
+	if (!label || context.width < 3 || context.height < 2) return [...screen];
+	const hint = target.shortcut ? ` ${renderKeyHint(theme, target.shortcut)}` : "";
+	const pill = renderPill(
+		theme,
+		{ icon: false, label: truncateToWidth(`${label}${hint}`, Math.max(1, context.width - 2), "") },
+		"surface.inset",
+		"text.muted",
+		undefined,
+		"\x1b[49m",
+		true,
+	);
+	const width = Math.min(context.width, visibleWidth(pill));
+	if (width === 0) return [...screen];
+	const below = target.rect.y + target.rect.height;
+	const y = below < context.height ? below : Math.max(0, target.rect.y - 1);
+	const center = target.rect.x + target.rect.width / 2;
+	const x = Math.max(0, Math.min(context.width - width, Math.round(center - width / 2)));
+	const result = [...screen];
+	result[y] = compositeTuiLine(result[y] ?? "", pill, x, width, context.width);
+	return result;
+}

package/src/overlay/modal-mount.ts

@@ -0,0 +1,118 @@
+import type { Component, Focusable } from "@earendil-works/pi-tui";
+import type { MouseRect, TuiMouseEvent } from "../mouse/events.ts";
+import { type MouseRegistry, registerModalPointerShield } from "../mouse/registry.ts";
+
+/** Pointer lifecycle translated into modal-component-local coordinates. */
+export interface ModalOverlayMouseEvent {
+	type: "enter" | "move" | "leave" | "press" | "release";
+	row: number;
+	col: number;
+	button?: 0 | 1 | 2;
+}
+
+/** A modal component that accepts overlay-local keyboard and pointer input. */
+export interface ModalOverlayComponent extends Component, Focusable {
+	handleInput(data: string): void;
+	handleMouse(event: ModalOverlayMouseEvent): boolean;
+	dispose?(): void;
+}
+
+/** Component wrapper returned to Pi for a mounted modal overlay. */
+export interface MountedModalOverlayComponent extends Component, Focusable {
+	handleInput(data: string): void;
+	dispose(): void;
+}
+
+/** Shared host mechanics for a screen-positioned modal component. */
+export interface ModalOverlayMountOptions {
+	/** Shared registry used by the active Pi pointer bridge. */
+	registry: MouseRegistry;
+	/** Stable diagnostic identity for the component's pointer region. */
+	id: string;
+	/** Current screen rectangle occupied by the component. */
+	getRect(): MouseRect | undefined;
+	/** Current screen rectangle whose selection gestures the modal must block. */
+	getShieldRect(): MouseRect | undefined;
+	/** Component hit priority; defaults to 10,000. */
+	priority?: number;
+	/** Shield hit priority; defaults immediately below the component region. */
+	shieldPriority?: number;
+}
+
+function componentMouseEvent(event: TuiMouseEvent): ModalOverlayMouseEvent | undefined {
+	if (
+		event.type !== "enter" &&
+		event.type !== "move" &&
+		event.type !== "leave" &&
+		event.type !== "press" &&
+		event.type !== "release"
+	)
+		return undefined;
+	return {
+		type: event.type,
+		row: event.row,
+		col: event.col,
+		...(event.button === undefined ? {} : { button: event.button }),
+	};
+}
+
+class MountedModalOverlay implements MountedModalOverlayComponent {
+	private readonly removeRegion: () => void;
+	private readonly removeShield: () => void;
+	private disposed = false;
+
+	constructor(
+		private readonly component: ModalOverlayComponent,
+		options: ModalOverlayMountOptions,
+	) {
+		const priority = options.priority ?? 10_000;
+		this.removeRegion = options.registry.registerOverlayRegion({
+			id: options.id,
+			priority,
+			getRect: options.getRect,
+			onMouse: (event) => {
+				const translated = componentMouseEvent(event);
+				return translated ? component.handleMouse(translated) : false;
+			},
+		});
+		this.removeShield = registerModalPointerShield(options.registry, {
+			id: `${options.id}.shield`,
+			priority: options.shieldPriority ?? priority - 1,
+			getRect: options.getShieldRect,
+		});
+	}
+
+	get focused(): boolean {
+		return this.component.focused;
+	}
+	set focused(value: boolean) {
+		this.component.focused = value;
+	}
+	render(width: number): string[] {
+		return this.component.render(width);
+	}
+	invalidate(): void {
+		this.component.invalidate();
+	}
+	handleInput(data: string): void {
+		this.component.handleInput(data);
+	}
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.removeRegion();
+		this.removeShield();
+		this.component.dispose?.();
+	}
+}
+
+/**
+ * Mounts a screen-positioned modal component with local pointer input, a
+ * selection shield, and one disposal owner for both registrations.
+ */
+export function mountModalOverlay(
+	component: ModalOverlayComponent,
+	options: ModalOverlayMountOptions,
+): MountedModalOverlayComponent {
+	return new MountedModalOverlay(component, options);
+}

package/src/panels.ts

@@ -0,0 +1,207 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, Focusable } from "@earendil-works/pi-tui";
+import type { SplitPaneHost, TuiIconName } from "pi-libtui";
+import type { TuiMouseEvent } from "pi-libtui/mouse";
+
+export const SIDE_PANEL_REGISTRY_KEY = Symbol.for("pi-panels/registry/v1");
+export const SIDE_PANEL_PROTOCOL = "pi-panels/registry/v1" as const;
+
+export type SidePanelContent = Component &
+	Partial<Focusable> & {
+		defersInputRender?(data: string): boolean;
+		dispose?(): void;
+		onMouse?(event: TuiMouseEvent): boolean;
+	};
+
+export interface SidePanelHeaderAction {
+	readonly label: string;
+	readonly actionId: string;
+}
+
+export interface SidePanelTab {
+	readonly id: string;
+	readonly label: string;
+	readonly icon?: TuiIconName | { readonly glyph: string };
+	readonly headerAction?: SidePanelHeaderAction;
+	readonly inputActions?: readonly string[];
+	create(host: SplitPaneHost, theme: Theme): SidePanelContent;
+	onClose?(): void;
+}
+
+export interface SidePanelEmptyAction {
+	readonly id: string;
+	readonly label: string;
+	readonly actionId: string;
+}
+
+export interface SidePanelSession {
+	readonly protocol: typeof SIDE_PANEL_PROTOCOL;
+	readonly version: 1;
+	addTab(tab: SidePanelTab, options?: { activate?: boolean; focus?: boolean }): void;
+	restoreTab(tab: SidePanelTab): void;
+	updateTab(tab: SidePanelTab): void;
+	removeTab(id: string): void;
+	activate(id: string): void;
+	activeTabId(): string | undefined;
+	registerEmptyAction(action: SidePanelEmptyAction): () => void;
+	show(options?: { focus?: boolean }): void;
+	toggle(): void;
+	toggleZoom(): void;
+	focus(): void;
+	focusMain(): void;
+	focusNext(): void;
+	activatePrevious(): void;
+	activateNext(): void;
+	isVisible(): boolean;
+	isZoomed(): boolean;
+	requestRender(): void;
+}
+
+export interface SidePanelProvider {
+	readonly id: string;
+	/** Identity of the Pi session that owns this contribution. */
+	readonly session: object;
+	attach(panel: SidePanelSession): undefined | (() => void);
+}
+
+export interface SidePanelRegistry {
+	readonly protocol: typeof SIDE_PANEL_PROTOCOL;
+	readonly version: 1;
+	register(provider: SidePanelProvider): () => void;
+	providers(): readonly SidePanelProvider[];
+	installHost(): SidePanelHost;
+	hasHost(): boolean;
+}
+
+export interface SidePanelHost {
+	attach(
+		session: object,
+		panel: SidePanelSession,
+		onError: (provider: SidePanelProvider, error: unknown) => void,
+	): () => void;
+	dispose(): void;
+}
+
+interface RegistryState {
+	readonly providers: Map<string, SidePanelProvider>;
+	host?: HostState;
+}
+
+interface HostState {
+	readonly identity: object;
+	session?: object;
+	panel?: SidePanelSession;
+	onError?: (provider: SidePanelProvider, error: unknown) => void;
+	readonly attachments: Map<string, { readonly provider: SidePanelProvider; readonly dispose?: () => void }>;
+}
+
+const state = new WeakMap<SidePanelRegistry, RegistryState>();
+type UntrustedRegistry = unknown;
+
+function isRegistry(value: UntrustedRegistry): value is SidePanelRegistry {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<SidePanelRegistry>;
+	return (
+		candidate.protocol === SIDE_PANEL_PROTOCOL &&
+		candidate.version === 1 &&
+		typeof candidate.register === "function" &&
+		typeof candidate.providers === "function" &&
+		typeof candidate.installHost === "function" &&
+		typeof candidate.hasHost === "function"
+	);
+}
+
+function registryState(registry: SidePanelRegistry): RegistryState {
+	const existing = state.get(registry);
+	if (existing) return existing;
+	const created = {
+		providers: new Map<string, SidePanelProvider>(),
+	};
+	state.set(registry, created);
+	return created;
+}
+
+function releaseAttachment(host: HostState, id: string): void {
+	const attachment = host.attachments.get(id);
+	if (!attachment) return;
+	host.attachments.delete(id);
+	try {
+		attachment.dispose?.();
+	} catch {
+		// Optional providers cannot block the host lifecycle.
+	}
+}
+
+function attachProvider(host: HostState, provider: SidePanelProvider): void {
+	if (!host.panel || provider.session !== host.session) return;
+	if (host.attachments.get(provider.id)?.provider === provider) return;
+	releaseAttachment(host, provider.id);
+	try {
+		host.attachments.set(provider.id, { provider, dispose: provider.attach(host.panel) });
+	} catch (error) {
+		host.onError?.(provider, error);
+	}
+}
+
+function detachSession(host: HostState): void {
+	for (const id of [...host.attachments.keys()]) releaseAttachment(host, id);
+	host.session = undefined;
+	host.panel = undefined;
+	host.onError = undefined;
+}
+
+export function ensureSidePanelRegistry(scope: typeof globalThis = globalThis): SidePanelRegistry {
+	const slots = scope as Record<PropertyKey, UntrustedRegistry>;
+	if (isRegistry(slots[SIDE_PANEL_REGISTRY_KEY])) return slots[SIDE_PANEL_REGISTRY_KEY];
+	const registry: SidePanelRegistry = {
+		protocol: SIDE_PANEL_PROTOCOL,
+		version: 1,
+		register(provider) {
+			const current = registryState(registry);
+			const replaced = current.providers.get(provider.id);
+			if (replaced && current.host) releaseAttachment(current.host, provider.id);
+			current.providers.set(provider.id, provider);
+			if (current.host) attachProvider(current.host, provider);
+			return () => {
+				if (current.providers.get(provider.id) !== provider) return;
+				current.providers.delete(provider.id);
+				if (current.host?.attachments.get(provider.id)?.provider === provider) {
+					releaseAttachment(current.host, provider.id);
+				}
+			};
+		},
+		providers: () => [...registryState(registry).providers.values()],
+		installHost() {
+			const current = registryState(registry);
+			if (current.host) detachSession(current.host);
+			const host: HostState = { identity: {}, attachments: new Map() };
+			current.host = host;
+			return {
+				attach(session, panel, onError) {
+					if (current.host !== host) return () => {};
+					detachSession(host);
+					host.session = session;
+					host.panel = panel;
+					host.onError = onError;
+					for (const provider of current.providers.values()) attachProvider(host, provider);
+					return () => {
+						if (current.host === host && host.session === session && host.panel === panel) detachSession(host);
+					};
+				},
+				dispose() {
+					if (current.host !== host) return;
+					detachSession(host);
+					current.host = undefined;
+				},
+			};
+		},
+		hasHost: () => registryState(registry).host !== undefined,
+	};
+	registryState(registry);
+	slots[SIDE_PANEL_REGISTRY_KEY] = registry;
+	return registry;
+}
+
+export function registerSidePanelProvider(provider: SidePanelProvider, scope: typeof globalThis): () => void {
+	return ensureSidePanelRegistry(scope).register(provider);
+}

package/src/render-cache.ts

@@ -0,0 +1,80 @@
+import { getTuiRenderEpoch } from "./render-epoch.ts";
+
+/** Options for a bounded exact-key cache. */
+interface ExactRenderCacheOptions {
+	/** Maximum retained entries. The least recently used entry is evicted first. */
+	maxEntries?: number;
+}
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(1, Math.floor(value)) : fallback;
+}
+
+/** A small exact-key LRU cache for rendered values. */
+class ExactRenderCache<Key, Value> {
+	private readonly entries = new Map<Key, Value>();
+	private readonly maxEntries: number;
+
+	constructor(options: ExactRenderCacheOptions = {}) {
+		this.maxEntries = positiveInteger(options.maxEntries, 8);
+	}
+
+	/** Return an exact cached value, producing it once on a miss. */
+	get(key: Key, produce: () => Value): Value {
+		const cached = this.entries.get(key);
+		if (cached !== undefined || this.entries.has(key)) {
+			this.entries.delete(key);
+			this.entries.set(key, cached as Value);
+			return cached as Value;
+		}
+		const value = produce();
+		if (this.entries.size >= this.maxEntries) {
+			const oldest = this.entries.keys().next();
+			if (!oldest.done) this.entries.delete(oldest.value);
+		}
+		this.entries.set(key, value);
+		return value;
+	}
+
+	/** Remove all retained values. */
+	clear(): void {
+		this.entries.clear();
+	}
+
+	/** Current retained entry count. */
+	get size(): number {
+		return this.entries.size;
+	}
+}
+/** Bounded cache keyed exactly by terminal width and a caller-owned content key. */
+export class RenderedLinesCache {
+	private readonly widths: ExactRenderCache<number, ExactRenderCache<string, string[]>>;
+	private readonly maxContentKeys: number;
+	private epoch = getTuiRenderEpoch();
+
+	constructor(options: { maxWidths?: number; maxContentKeysPerWidth?: number } = {}) {
+		this.widths = new ExactRenderCache({ maxEntries: positiveInteger(options.maxWidths, 4) });
+		this.maxContentKeys = positiveInteger(options.maxContentKeysPerWidth, 2);
+	}
+
+	/** Return the original rendered line array for an exact width and content key. */
+	get(width: number, contentKey: string, produce: () => string[]): string[] {
+		const epoch = getTuiRenderEpoch();
+		if (epoch !== this.epoch) {
+			this.epoch = epoch;
+			this.clear();
+		}
+		const byContent = this.widths.get(width, () => new ExactRenderCache({ maxEntries: this.maxContentKeys }));
+		return byContent.get(contentKey, produce);
+	}
+
+	/** Drop every cached width and content key. */
+	clear(): void {
+		this.widths.clear();
+	}
+
+	/** Number of retained terminal widths. */
+	get widthCount(): number {
+		return this.widths.size;
+	}
+}