@luan.sh/pi-libtui 0.3.8

package/src/host/cursor-bridge.ts

@@ -0,0 +1,210 @@
+import { type TUI, TuiAltScreen, TuiMainScreen } from "@earendil-works/pi-tui";
+import type { TuiCursorStyle } from "../appearance.ts";
+import { cursorStyle, findCursorPresentation, isNativeCursorStyle, stripCursorRoleMarkers } from "../cursor.ts";
+
+const INSTALLATION_KEY = Symbol.for("pi-libtui/cursor-bridge/v1");
+const PROTOCOL = "pi-libtui/cursor-bridge/v1" as const;
+const RESET_CURSOR_SHAPE = "\x1b[0 q";
+
+type CursorPosition = { row: number; col: number } | null;
+type ExtractCursorPosition = (lines: string[], height: number) => CursorPosition;
+type SetShowHardwareCursor = (enabled: boolean) => void;
+
+interface CursorState {
+	baselineVisible: boolean;
+	forcingVisible: boolean;
+	internalVisibilityWrite: boolean;
+	shape?: TuiCursorStyle;
+}
+
+interface CursorBridgeInstallation {
+	readonly protocol: typeof PROTOCOL;
+	refs: number;
+	readonly extract: ExtractCursorPosition;
+	readonly setVisible: SetShowHardwareCursor;
+	readonly states: Map<object, CursorState>;
+	readonly originalExtract: ExtractCursorPosition;
+	readonly originalSetVisible: SetShowHardwareCursor;
+	dispose(): void;
+}
+
+// type-boundary: Pi 0.84.2 owns renderer prototypes; these checks narrow the
+// cursor extraction and visibility methods before the compatibility patch.
+type PiPrivateValue = unknown;
+
+function installation(value: PiPrivateValue): CursorBridgeInstallation | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const candidate = value as Partial<CursorBridgeInstallation>;
+	return candidate.protocol === PROTOCOL &&
+		typeof candidate.extract === "function" &&
+		typeof candidate.setVisible === "function" &&
+		candidate.states instanceof Map
+		? (candidate as CursorBridgeInstallation)
+		: undefined;
+}
+
+function methodOwner(value: object, property: string): object | undefined {
+	let candidate: object | null = value;
+	while (candidate) {
+		if (Reflect.getOwnPropertyDescriptor(candidate, property)) return candidate;
+		candidate = Reflect.getPrototypeOf(candidate) as object | null;
+	}
+	return undefined;
+}
+
+function getHardwareCursor(renderer: object): boolean {
+	const read = Reflect.get(renderer, "getShowHardwareCursor") as PiPrivateValue;
+	return typeof read === "function" && Reflect.apply(read, renderer, []) === true;
+}
+
+function writeTerminal(renderer: object, data: string): void {
+	const terminal = Reflect.get(renderer, "terminal") as PiPrivateValue;
+	if (!terminal || typeof terminal !== "object") return;
+	const write = Reflect.get(terminal, "write") as PiPrivateValue;
+	if (typeof write === "function") Reflect.apply(write, terminal, [data]);
+}
+
+function cursorShapeSequence(style: TuiCursorStyle): string {
+	const parameter =
+		style === "terminal-default"
+			? 0
+			: style === "blinking-block"
+				? 1
+				: style === "steady-block"
+					? 2
+					: style === "blinking-underline"
+						? 3
+						: style === "steady-underline"
+							? 4
+							: style === "blinking-bar"
+								? 5
+								: 6;
+	return `\x1b[${parameter} q`;
+}
+
+function stateFor(bridge: CursorBridgeInstallation, renderer: object): CursorState {
+	let state = bridge.states.get(renderer);
+	if (state) return state;
+	let previous: CursorState | undefined;
+	for (const candidate of bridge.states.values()) {
+		if (candidate.forcingVisible) previous = candidate;
+	}
+	if (previous) previous.forcingVisible = false;
+	state = {
+		// Pi copies effective visibility into a replacement renderer during a mode
+		// switch. Carry the original preference alongside that temporary force.
+		baselineVisible: previous?.baselineVisible ?? getHardwareCursor(renderer),
+		forcingVisible: previous !== undefined,
+		internalVisibilityWrite: false,
+	};
+	bridge.states.set(renderer, state);
+	return state;
+}
+
+function setVisible(bridge: CursorBridgeInstallation, renderer: object, state: CursorState, enabled: boolean): void {
+	state.internalVisibilityWrite = true;
+	try {
+		Reflect.apply(bridge.originalSetVisible, renderer, [enabled]);
+	} finally {
+		state.internalVisibilityWrite = false;
+	}
+}
+
+function applyCursorPresentation(
+	bridge: CursorBridgeInstallation,
+	renderer: object,
+	presentation: ReturnType<typeof findCursorPresentation>,
+): void {
+	const state = stateFor(bridge, renderer);
+	const style = presentation
+		? "style" in presentation
+			? presentation.style
+			: cursorStyle(presentation.role)
+		: "virtual";
+	if (isNativeCursorStyle(style)) {
+		state.forcingVisible = true;
+		setVisible(bridge, renderer, state, true);
+		if (state.shape !== style) {
+			writeTerminal(renderer, cursorShapeSequence(style));
+			state.shape = style;
+		}
+		return;
+	}
+
+	if (state.forcingVisible) setVisible(bridge, renderer, state, state.baselineVisible);
+	state.forcingVisible = false;
+	if (state.shape !== undefined) {
+		writeTerminal(renderer, RESET_CURSOR_SHAPE);
+		state.shape = undefined;
+	}
+}
+
+function installPrototype(prototype: object): () => void {
+	const existing = installation(Reflect.get(prototype, INSTALLATION_KEY) as PiPrivateValue);
+	if (existing) {
+		existing.refs += 1;
+		return () => existing.dispose();
+	}
+
+	const originalExtractValue = Reflect.get(prototype, "extractCursorPosition") as PiPrivateValue;
+	const originalSetValue = Reflect.get(prototype, "setShowHardwareCursor") as PiPrivateValue;
+	if (typeof originalExtractValue !== "function" || typeof originalSetValue !== "function") return () => {};
+	const originalExtract = originalExtractValue as ExtractCursorPosition;
+	const originalSetVisible = originalSetValue as SetShowHardwareCursor;
+	let bridge: CursorBridgeInstallation;
+
+	const extract: ExtractCursorPosition = function (this: object, lines, height) {
+		const presentation = findCursorPresentation(lines, height);
+		for (let index = 0; index < lines.length; index += 1) lines[index] = stripCursorRoleMarkers(lines[index] ?? "");
+		applyCursorPresentation(bridge, this, presentation);
+		return Reflect.apply(originalExtract, this, [lines, height]) as CursorPosition;
+	};
+	const setHardwareCursor: SetShowHardwareCursor = function (this: object, enabled) {
+		const state = stateFor(bridge, this);
+		if (!state.internalVisibilityWrite) state.baselineVisible = enabled;
+		Reflect.apply(originalSetVisible, this, [state.forcingVisible ? true : enabled]);
+	};
+
+	bridge = {
+		protocol: PROTOCOL,
+		refs: 1,
+		extract,
+		setVisible: setHardwareCursor,
+		states: new Map(),
+		originalExtract,
+		originalSetVisible,
+		dispose() {
+			this.refs -= 1;
+			if (this.refs > 0) return;
+			for (const [renderer, state] of this.states) {
+				if (state.shape !== undefined) writeTerminal(renderer, RESET_CURSOR_SHAPE);
+				setVisible(this, renderer, state, state.baselineVisible);
+			}
+			this.states.clear();
+			if (Reflect.get(prototype, "extractCursorPosition") === this.extract) {
+				Reflect.set(prototype, "extractCursorPosition", this.originalExtract);
+			}
+			if (Reflect.get(prototype, "setShowHardwareCursor") === this.setVisible) {
+				Reflect.set(prototype, "setShowHardwareCursor", this.originalSetVisible);
+			}
+			Reflect.set(prototype, INSTALLATION_KEY, undefined);
+		},
+	};
+	Reflect.set(prototype, "extractCursorPosition", extract);
+	Reflect.set(prototype, "setShowHardwareCursor", setHardwareCursor);
+	Reflect.set(prototype, INSTALLATION_KEY, bridge);
+	return () => bridge.dispose();
+}
+
+/** Install libtui's semantic cursor bridge across Pi's renderer modes. */
+export function installCursorBridge(tui: TUI): () => void {
+	const prototypes = new Set<object>();
+	for (const candidate of [tui as object, TuiMainScreen.prototype, TuiAltScreen.prototype]) {
+		const owner = methodOwner(candidate, "extractCursorPosition");
+		if (owner) prototypes.add(owner);
+	}
+	const disposers = [...prototypes].map(installPrototype);
+	return () => {
+		for (const dispose of disposers) dispose();
+	};
+}

package/src/host/editor-bridge.ts

@@ -0,0 +1,148 @@
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import { dispatchEditorPaste, dispatchEditorRender, type EditorRegistry } from "../editor.ts";
+
+const BRIDGE_KEY = Symbol.for("pi-libtui/editor/custom-editor-bridge/v1");
+const BRIDGE_PROTOCOL = "pi-libtui/editor/custom-editor-bridge/v1" as const;
+const BRACKETED_PASTE = /^\x1b\[200~([\s\S]*)\x1b\[201~$/;
+
+type EditorPrototype = CustomEditor["constructor"]["prototype"];
+type HandleInput = EditorPrototype["handleInput"];
+type InsertTextAtCursor = EditorPrototype["insertTextAtCursor"];
+type Render = EditorPrototype["render"];
+
+interface OriginalMethod<T> {
+	readonly descriptor: PropertyDescriptor | undefined;
+	readonly method: T;
+}
+
+interface EditorBridgeState {
+	readonly protocol: typeof BRIDGE_PROTOCOL;
+	leases: number;
+	readonly handleInput: OriginalMethod<HandleInput>;
+	readonly insertTextAtCursor: OriginalMethod<InsertTextAtCursor>;
+	readonly render: OriginalMethod<Render>;
+	readonly wrappedHandleInput: HandleInput;
+	readonly wrappedInsertTextAtCursor: InsertTextAtCursor;
+	readonly wrappedRender: Render;
+}
+
+// type-boundary: Symbol.for bridge state can come from another installed pi-libtui copy; this validator narrows its lifecycle fields.
+type UntrustedBridgeState = unknown;
+
+function bridgeState(value: UntrustedBridgeState): EditorBridgeState | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const candidate = value as Partial<EditorBridgeState>;
+	if (
+		candidate.protocol !== BRIDGE_PROTOCOL ||
+		typeof candidate.leases !== "number" ||
+		typeof candidate.wrappedHandleInput !== "function" ||
+		typeof candidate.wrappedInsertTextAtCursor !== "function" ||
+		typeof candidate.wrappedRender !== "function"
+	) {
+		return undefined;
+	}
+	return candidate as EditorBridgeState;
+}
+
+function originalMethod<K extends "handleInput" | "insertTextAtCursor" | "render">(
+	prototype: EditorPrototype,
+	key: K,
+): OriginalMethod<EditorPrototype[K]> {
+	return {
+		descriptor: Object.getOwnPropertyDescriptor(prototype, key),
+		method: prototype[key],
+	};
+}
+
+function installMethod<K extends "handleInput" | "insertTextAtCursor" | "render">(
+	prototype: EditorPrototype,
+	key: K,
+	method: EditorPrototype[K],
+): void {
+	Object.defineProperty(prototype, key, {
+		configurable: true,
+		enumerable: false,
+		writable: true,
+		value: method,
+	});
+}
+
+function restoreMethod<K extends "handleInput" | "insertTextAtCursor" | "render">(
+	prototype: EditorPrototype,
+	key: K,
+	original: OriginalMethod<EditorPrototype[K]>,
+	wrapper: EditorPrototype[K],
+): void {
+	if (prototype[key] !== wrapper) return;
+	if (original.descriptor) {
+		Object.defineProperty(prototype, key, original.descriptor);
+	} else {
+		Reflect.deleteProperty(prototype, key);
+	}
+}
+
+/** Install the extension-owned CustomEditor adapter for one active Pi session. */
+export function installEditorBridge(registry: EditorRegistry): () => void {
+	const prototype = CustomEditor.prototype;
+	const active = bridgeState(Reflect.get(prototype, BRIDGE_KEY));
+	if (active) {
+		active.leases += 1;
+		return releaseBridge(prototype, active);
+	}
+
+	const handleInput = originalMethod(prototype, "handleInput");
+	const insertTextAtCursor = originalMethod(prototype, "insertTextAtCursor");
+	const render = originalMethod(prototype, "render");
+
+	const wrappedHandleInput: HandleInput = function libtuiHandleInput(this: CustomEditor, data: string): void {
+		const pasted = data.match(BRACKETED_PASTE)?.[1];
+		if (pasted !== undefined) {
+			const replacement = dispatchEditorPaste(registry, pasted);
+			if (replacement !== undefined) {
+				insertTextAtCursor.method.call(this, replacement);
+				return;
+			}
+		}
+		handleInput.method.call(this, data);
+	};
+	const wrappedInsertTextAtCursor: InsertTextAtCursor = function libtuiInsertTextAtCursor(
+		this: CustomEditor,
+		text: string,
+	): void {
+		insertTextAtCursor.method.call(this, dispatchEditorPaste(registry, text) ?? text);
+	};
+	const wrappedRender: Render = function libtuiRender(this: CustomEditor, width: number): string[] {
+		return dispatchEditorRender(registry, render.method.call(this, width), width);
+	};
+
+	const state: EditorBridgeState = {
+		protocol: BRIDGE_PROTOCOL,
+		leases: 1,
+		handleInput,
+		insertTextAtCursor,
+		render,
+		wrappedHandleInput,
+		wrappedInsertTextAtCursor,
+		wrappedRender,
+	};
+	Object.defineProperty(prototype, BRIDGE_KEY, { configurable: true, value: state });
+	installMethod(prototype, "handleInput", wrappedHandleInput);
+	installMethod(prototype, "insertTextAtCursor", wrappedInsertTextAtCursor);
+	installMethod(prototype, "render", wrappedRender);
+	return releaseBridge(prototype, state);
+}
+
+function releaseBridge(prototype: EditorPrototype, state: EditorBridgeState): () => void {
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		state.leases -= 1;
+		if (state.leases > 0) return;
+
+		restoreMethod(prototype, "handleInput", state.handleInput, state.wrappedHandleInput);
+		restoreMethod(prototype, "insertTextAtCursor", state.insertTextAtCursor, state.wrappedInsertTextAtCursor);
+		restoreMethod(prototype, "render", state.render, state.wrappedRender);
+		if (bridgeState(Reflect.get(prototype, BRIDGE_KEY)) === state) Reflect.deleteProperty(prototype, BRIDGE_KEY);
+	};
+}

package/src/host/extension-host.ts

@@ -0,0 +1,231 @@
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { subscribeTuiAppearance } from "../appearance.ts";
+import { renderEditorPasteMarkerPills } from "../decoration/editor-pills.ts";
+import { ensureEditorRegistry } from "../editor.ts";
+import { ensureMouseRegistry } from "../mouse.ts";
+import { sharedMotionScheduler } from "../motion.ts";
+import { ensureSplitPaneRegistry } from "../split-pane.ts";
+import { measureTerminalColors, terminalColorsRegistry } from "../terminal-colors.ts";
+import { shutdownPtyHost } from "../terminal/pty-host.ts";
+import { installCursorBridge } from "./cursor-bridge.ts";
+import { installEditorBridge } from "./editor-bridge.ts";
+import { installMouseBridge } from "./mouse-bridge.ts";
+import { installSplitPaneBridge } from "./split-pane-bridge.ts";
+
+const WIDGET_KEY = "pi-libtui.mouse-bridge";
+const HOST_CAPABILITY_KEY = Symbol.for("pi-libtui/extension-host/v1");
+const HOST_PROTOCOL = "pi-libtui/extension-host/v1" as const;
+
+class LibtuiHostWidget implements Component {
+	private mode: TUI["mode"];
+	private removeMouseBridge: () => void;
+	private removeCursorBridge: () => void;
+	private removeSplitPaneBridge: () => void;
+	private readonly removeAppearanceSubscription: () => void;
+	private readonly removeColorSubscription: () => void;
+	private readonly removeFocusSubscription: () => void;
+	private terminalColorsReady = false;
+	private fallbackTheme: Theme | undefined;
+	private disposed = false;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly ui: ExtensionContext["ui"],
+	) {
+		this.mode = tui.mode;
+		this.removeMouseBridge = installMouseBridge(tui, ensureMouseRegistry());
+		this.removeCursorBridge = installCursorBridge(tui);
+		this.removeSplitPaneBridge = installSplitPaneBridge(
+			tui,
+			() => this.ui.theme,
+			ensureSplitPaneRegistry(),
+			ensureMouseRegistry(),
+		);
+		this.removeAppearanceSubscription = subscribeTuiAppearance(() => tui.requestRender());
+		this.removeColorSubscription = terminalColorsRegistry().subscribe(() => tui.requestRender());
+		this.removeFocusSubscription = tui.addInputListener((data) => {
+			const focused = data === "\x1b[I" ? true : data === "\x1b[O" ? false : undefined;
+			if (focused !== undefined) sharedMotionScheduler.setPaused(!focused);
+			return undefined;
+		});
+		void this.loadTerminalColors();
+	}
+
+	render(): string[] {
+		if (this.tui.mode !== this.mode) {
+			// Acquire the new renderer leases before releasing the old ones so a mode
+			// switch never briefly removes shared prototype bridges.
+			const removeMouseBridge = installMouseBridge(this.tui, ensureMouseRegistry());
+			const removeCursorBridge = installCursorBridge(this.tui);
+			const removeSplitPaneBridge = installSplitPaneBridge(
+				this.tui,
+				() => this.ui.theme,
+				ensureSplitPaneRegistry(),
+				ensureMouseRegistry(),
+			);
+			const previousMouseBridge = this.removeMouseBridge;
+			const previousCursorBridge = this.removeCursorBridge;
+			const previousSplitPaneBridge = this.removeSplitPaneBridge;
+			this.mode = this.tui.mode;
+			this.removeMouseBridge = removeMouseBridge;
+			this.removeCursorBridge = removeCursorBridge;
+			this.removeSplitPaneBridge = removeSplitPaneBridge;
+			previousSplitPaneBridge();
+			previousCursorBridge();
+			previousMouseBridge();
+		}
+		this.applyHarmoniousFallback();
+		return [];
+	}
+
+	invalidate(): void {}
+
+	dispose(): void {
+		this.disposed = true;
+		this.removeMouseBridge();
+		this.removeCursorBridge();
+		this.removeSplitPaneBridge();
+		this.removeAppearanceSubscription();
+		this.removeColorSubscription();
+		this.removeFocusSubscription();
+		sharedMotionScheduler.setPaused(false);
+	}
+
+	private async loadTerminalColors(): Promise<void> {
+		let profile: Awaited<ReturnType<typeof measureTerminalColors>>;
+		try {
+			profile = await measureTerminalColors(this.tui);
+		} catch {
+			profile = { scheme: "dark", indexedPalette: "unknown" };
+		}
+		if (this.disposed) return;
+		terminalColorsRegistry().publish(profile);
+		this.terminalColorsReady = true;
+		this.fallbackTheme = this.ui.getTheme(profile.scheme);
+		this.applyHarmoniousFallback();
+	}
+
+	private applyHarmoniousFallback(): void {
+		if (!this.terminalColorsReady || this.ui.theme.name !== "harmonious") return;
+		const terminal = terminalColorsRegistry().current();
+		if (terminal?.indexedPalette === "generated" || terminal?.ansiBase16) return;
+		if (this.fallbackTheme) this.ui.setTheme(this.fallbackTheme);
+	}
+}
+
+interface HostRegistration {
+	readonly protocol: typeof HOST_PROTOCOL;
+	start(ctx: ExtensionContext): void;
+	shutdown(ctx: ExtensionContext, preservePtys: boolean): Promise<void>;
+}
+
+interface HostCapability {
+	readonly protocol: typeof HOST_PROTOCOL;
+	readonly version: 1;
+	get(key: object): HostRegistration | undefined;
+	set(key: object, registration: HostRegistration): void;
+	delete(key: object): void;
+}
+
+// type-boundary: Symbol.for capabilities can be populated by another extension realm; this validator narrows the host registry methods.
+type UntrustedHostValue = unknown;
+
+function isHostCapability(value: UntrustedHostValue): value is HostCapability {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<HostCapability>;
+	return (
+		candidate.protocol === HOST_PROTOCOL &&
+		candidate.version === 1 &&
+		typeof candidate.get === "function" &&
+		typeof candidate.set === "function" &&
+		typeof candidate.delete === "function"
+	);
+}
+
+function ensureHostCapability(scope: typeof globalThis = globalThis): HostCapability {
+	const slots = scope as Record<PropertyKey, UntrustedHostValue>;
+	const existing = slots[HOST_CAPABILITY_KEY];
+	if (isHostCapability(existing)) return existing;
+
+	const hosts = new WeakMap<object, HostRegistration>();
+	const capability: HostCapability = {
+		protocol: HOST_PROTOCOL,
+		version: 1,
+		get: (key) => hosts.get(key),
+		set: (key, registration) => hosts.set(key, registration),
+		delete: (key) => hosts.delete(key),
+	};
+	slots[HOST_CAPABILITY_KEY] = capability;
+	return capability;
+}
+
+function hostIdentity(pi: ExtensionAPI): object {
+	const events = pi.events;
+	return events && typeof events === "object" ? events : (pi as object);
+}
+
+function createHostRegistration(): HostRegistration {
+	const editorRegistry = ensureEditorRegistry();
+	let activeSession:
+		| {
+				readonly sessionManager: ExtensionContext["sessionManager"];
+				readonly ui: ExtensionContext["ui"];
+				readonly removeEditorBridge: () => void;
+				readonly removeEditorDecorator: () => void;
+		  }
+		| undefined;
+
+	function clearSession(): void {
+		const session = activeSession;
+		if (!session) return;
+		activeSession = undefined;
+		session.removeEditorDecorator();
+		session.removeEditorBridge();
+		session.ui.setWidget(WIDGET_KEY, undefined);
+	}
+
+	return {
+		protocol: HOST_PROTOCOL,
+		start(ctx) {
+			if (ctx.mode !== "tui" || !ctx.hasUI) return;
+			clearSession();
+			const removeEditorBridge = installEditorBridge(editorRegistry);
+			const removeEditorDecorator = editorRegistry.registerRenderDecorator({
+				id: "pi-libtui.native-paste-markers",
+				decorate: (lines, width) => renderEditorPasteMarkerPills(lines, width, ctx.ui.theme).lines,
+			});
+			activeSession = { sessionManager: ctx.sessionManager, ui: ctx.ui, removeEditorBridge, removeEditorDecorator };
+			// A zero-height widget obtains Pi's stable TUI reference without changing the existing spacer row.
+			ctx.ui.setWidget(WIDGET_KEY, (tui) => new LibtuiHostWidget(tui, ctx.ui));
+		},
+		async shutdown(ctx, preservePtys) {
+			if (ctx.mode !== "tui" || !ctx.hasUI || activeSession?.sessionManager !== ctx.sessionManager) return;
+			clearSession();
+			if (!preservePtys) await shutdownPtyHost();
+		},
+	};
+}
+
+export interface LibtuiExtensionHost {
+	start(ctx: ExtensionContext): void;
+	shutdown(ctx: ExtensionContext, preservePtys: boolean): Promise<void>;
+	release(): void;
+}
+
+/** Claim the generic host once for all installed copies of pi-libtui. */
+export function claimLibtuiExtensionHost(pi: ExtensionAPI): LibtuiExtensionHost | undefined {
+	const capability = ensureHostCapability();
+	const key = hostIdentity(pi);
+	if (capability.get(key)) return undefined;
+
+	const registration = createHostRegistration();
+	capability.set(key, registration);
+	return {
+		start: (ctx) => registration.start(ctx),
+		shutdown: (ctx, preservePtys) => registration.shutdown(ctx, preservePtys),
+		release() {
+			if (capability.get(key) === registration) capability.delete(key);
+		},
+	};
+}