@rosetears/aili-pi 0.1.0 → 0.1.3

package/extensions/zentui/fixed-editor/index.ts

@@ -0,0 +1,223 @@
+/**
+ * Probe widget and lifecycle for the fixed editor compositor.
+ *
+ * A "probe" widget is registered via `ctx.ui.setWidget` with
+ * `placement: "aboveEditor"`. On first render it provides the TUI instance,
+ * which the compositor needs to patch internal methods.
+ *
+ * @internal
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type Component, type TUI, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { PolishedTuiConfig } from "../config.js";
+import type { SessionLifecycle } from "../session-lifecycle.js";
+import { renderStyleForSourceOrFallback } from "../style.js";
+import { TerminalSplitCompositor } from "./compositor.js";
+import { inspectPiTui } from "./pi-compat.js";
+
+let compositor: TerminalSplitCompositor | null = null;
+let didWarnUnsupported = false;
+let copyNoticeTimer: ReturnType<typeof setTimeout> | null = null;
+let storedCtx: ExtensionContext | null = null;
+let cancelProbeInstall: (() => void) | null = null;
+const COPY_NOTICE_KEY = "zentui-copy-notice";
+const COPY_NOTICE_MS = 2500;
+
+function clearCopyNotice(ctx: ExtensionContext): void {
+	if (copyNoticeTimer) {
+		clearTimeout(copyNoticeTimer);
+		copyNoticeTimer = null;
+	}
+	if (!ctx.hasUI || typeof ctx.ui.setWidget !== "function") return;
+	ctx.ui.setWidget(COPY_NOTICE_KEY, undefined);
+}
+
+/** Centered bordered box showing the copy notice. */
+class CopyNoticeComponent implements Component {
+	private readonly text: string;
+	private readonly border: string;
+
+	constructor(text: string, border: string) {
+		this.text = text;
+		this.border = border;
+	}
+
+	render(width: number): string[] {
+		const inner = " ".repeat(2) + this.text + " ".repeat(2);
+		const innerWidth = visibleWidth(inner);
+		const leftPad = Math.max(0, Math.floor((width - innerWidth - 2) / 2));
+		const pad = " ".repeat(leftPad);
+		const bar = "─".repeat(innerWidth);
+		return [
+			`${pad}${this.border}┌${bar}┐`,
+			`${pad}${this.border}│${inner}│`,
+			`${pad}${this.border}└${bar}┘`,
+		];
+	}
+
+	invalidate(): void {}
+}
+
+function showCopyNotice(ctx: ExtensionContext, getConfig: () => PolishedTuiConfig): void {
+	if (!ctx.hasUI || typeof ctx.ui.setWidget !== "function") return;
+	const config = getConfig();
+	ctx.ui.setWidget(COPY_NOTICE_KEY, (_tui, theme) => {
+		const text = renderStyleForSourceOrFallback(
+			theme,
+			config.colorSources.editor,
+			undefined,
+			{ terminal: "yellow", theme: "warning" },
+			"Copied to clipboard",
+		);
+		const border = renderStyleForSourceOrFallback(
+			theme,
+			config.colorSources.editor,
+			config.colors.editorBorder,
+			{ terminal: "yellow", theme: "border" },
+			"",
+		);
+		return new CopyNoticeComponent(text, border);
+	});
+	if (copyNoticeTimer) clearTimeout(copyNoticeTimer);
+	copyNoticeTimer = setTimeout(() => {
+		copyNoticeTimer = null;
+		if (storedCtx !== ctx) return;
+		if (!ctx.hasUI || typeof ctx.ui.setWidget !== "function") return;
+		ctx.ui.setWidget(COPY_NOTICE_KEY, undefined);
+	}, COPY_NOTICE_MS);
+}
+
+/**
+ * Minimal component that triggers a callback on first render, then returns [].
+ */
+class ProbeComponent implements Component {
+	private readonly onInstall: () => void;
+	private hasQueuedInstall = false;
+
+	constructor(onInstall: () => void) {
+		this.onInstall = onInstall;
+	}
+
+	render(): string[] {
+		if (!this.hasQueuedInstall) {
+			this.hasQueuedInstall = true;
+			this.onInstall();
+		}
+		return [];
+	}
+
+	invalidate(): void {
+		this.hasQueuedInstall = false;
+	}
+}
+
+function warnUnsupported(ctx: ExtensionContext): void {
+	if (didWarnUnsupported || !ctx.hasUI) return;
+	didWarnUnsupported = true;
+	console.warn(
+		"[zentui] Fixed editor: unsupported Pi TUI layout — falling back to normal rendering.",
+	);
+}
+
+function installFromProbe(
+	ctx: ExtensionContext,
+	tui: TUI,
+	getConfig: () => PolishedTuiConfig,
+): void {
+	if (compositor) return;
+	try {
+		const config = getConfig();
+		if (!config.fixedEditor?.enabled) return;
+
+		const capabilities = inspectPiTui(tui);
+		if (!capabilities) {
+			warnUnsupported(ctx);
+			return;
+		}
+
+		const next = new TerminalSplitCompositor(
+			capabilities,
+			() => ({
+				enabled: getConfig().fixedEditor?.enabled ?? false,
+				mouseScroll: getConfig().fixedEditor?.mouseScroll ?? false,
+				copyNotice: getConfig().fixedEditor?.copyNotice ?? true,
+			}),
+			ctx.hasUI ? () => showCopyNotice(ctx, getConfig) : undefined,
+			ctx.hasUI ? () => clearCopyNotice(ctx) : undefined,
+		);
+
+		if (!next.install()) {
+			warnUnsupported(ctx);
+			return;
+		}
+
+		compositor = next;
+	} catch {
+		warnUnsupported(ctx);
+	}
+}
+
+const WIDGET_KEY = "zentui-fixed-editor-probe";
+
+/**
+ * Register the fixed-editor probe widget.
+ * Call from session_start after editor + footer install.
+ * Only activates when `fixedEditor.enabled` is true.
+ */
+export function installFixedEditorProbe(
+	ctx: ExtensionContext,
+	getConfig: () => PolishedTuiConfig,
+	lifecycle: SessionLifecycle,
+): void {
+	if (!lifecycle.isCurrent() || !ctx.hasUI) return;
+	if (typeof ctx.ui.setWidget !== "function") return;
+	didWarnUnsupported = false;
+	storedCtx = ctx;
+	cancelProbeInstall?.();
+	cancelProbeInstall = null;
+
+	ctx.ui.setWidget(
+		WIDGET_KEY,
+		(tui: TUI) =>
+			new ProbeComponent(() => {
+				cancelProbeInstall = lifecycle.queueMicrotask(() => {
+					cancelProbeInstall = lifecycle.queueMicrotask(() => {
+						cancelProbeInstall = null;
+						installFromProbe(ctx, tui, getConfig);
+					});
+				});
+			}),
+		{ placement: "aboveEditor" },
+	);
+}
+
+/**
+ * Dispose the compositor if active.
+ * Call from session_shutdown and cleanupUi.
+ */
+export function disposeFixedEditor(ctx?: ExtensionContext): void {
+	cancelProbeInstall?.();
+	cancelProbeInstall = null;
+	compositor?.dispose();
+	compositor = null;
+	if (copyNoticeTimer) {
+		clearTimeout(copyNoticeTimer);
+		copyNoticeTimer = null;
+	}
+	storedCtx = null;
+	if (ctx) clearCopyNotice(ctx);
+}
+
+/**
+ * Remove the probe widget without disposing an active compositor.
+ * Useful for full UI cleanup.
+ */
+export function removeFixedEditorProbe(ctx: ExtensionContext): void {
+	cancelProbeInstall?.();
+	cancelProbeInstall = null;
+	if (!ctx.hasUI) return;
+	if (typeof ctx.ui.setWidget !== "function") return;
+	ctx.ui.setWidget(WIDGET_KEY, undefined);
+}

package/extensions/zentui/fixed-editor/input.ts

@@ -0,0 +1,85 @@
+/**
+ * Pure functions for parsing terminal input into scroll commands.
+ *
+ * These are fully unit-testable with no I/O or side effects.
+ */
+
+import { isKeyRelease, matchesKey } from "@earendil-works/pi-tui";
+
+import type { KeyboardScrollInput, MouseEvent, MouseScrollInput } from "./types.js";
+
+/** Regex matching SGR mouse format `\x1b[<code;col;row M|m`. */
+const SGR_MOUSE_RE = /\u001b\[<(\d+);(\d+);(\d+)([Mm])/;
+
+/** Kitty protocol variants for PgUp/PgDn ( CSI 5;~u / CSI 6;~u etc). */
+const KITTY_PAGE_UP_RE = /^\u001b\[5;9(?::[12])?~$|^\u001b\[57421;9(?::[12])?u$|^\u001b\[1;6A$/;
+const KITTY_PAGE_DOWN_RE = /^\u001b\[6;9(?::[12])?~$|^\u001b\[57422;9(?::[12])?u$|^\u001b\[1;6B$/;
+
+/** Mouse wheel button codes (SGR). */
+const WHEEL_UP = 64;
+const WHEEL_DOWN = 65;
+const SCROLL_AMOUNT = 3;
+
+/**
+ * Parse an SGR mouse sequence for wheel scroll.
+ * Returns `undefined` if the data is not a wheel event.
+ */
+export function parseMouseScroll(data: string): MouseScrollInput | undefined {
+	const ev = parseMouseEvent(data);
+	if (!ev) return undefined;
+	if (ev.button === "wheel-up") return { direction: "up", amount: SCROLL_AMOUNT };
+	if (ev.button === "wheel-down") return { direction: "down", amount: SCROLL_AMOUNT };
+	return undefined;
+}
+
+/**
+ * Parse any SGR mouse event (press, drag, release, wheel).
+ * Returns `undefined` if the data is not a mouse sequence.
+ */
+export function parseMouseEvent(data: string): MouseEvent | undefined {
+	const match = SGR_MOUSE_RE.exec(data);
+	if (!match) return undefined;
+	const code = Number(match[1]);
+	const col = Number(match[2]);
+	const row = Number(match[3]);
+	const isRelease = match[4] === "m";
+	const isMotion = (code & 32) !== 0;
+	const baseButton = code & ~(4 | 8 | 16 | 32);
+
+	const button: MouseEvent["button"] =
+		baseButton === 0
+			? "left"
+			: baseButton === 1
+				? "middle"
+				: baseButton === 2
+					? "right"
+					: baseButton === WHEEL_UP
+						? "wheel-up"
+						: baseButton === WHEEL_DOWN
+							? "wheel-down"
+							: "other";
+
+	const action: MouseEvent["action"] = isRelease ? "release" : isMotion ? "drag" : "press";
+
+	return { button, action, col, row };
+}
+
+/**
+ * Parse keyboard input for scroll commands.
+ * Handles PgUp/PgDn, Ctrl+Shift+↑/↓, and Enter (jump-to-bottom).
+ * Returns `undefined` if the input is not a scroll command.
+ */
+export function parseKeyboardScroll(data: string): KeyboardScrollInput | undefined {
+	if (isKeyRelease(data)) return undefined;
+
+	if (matchesKey(data, "pageUp") || KITTY_PAGE_UP_RE.test(data)) return { action: "pageUp" };
+	if (matchesKey(data, "pageDown") || KITTY_PAGE_DOWN_RE.test(data)) return { action: "pageDown" };
+	if (matchesKey(data, "enter") || matchesKey(data, "return")) return { action: "jumpBottom" };
+
+	return undefined;
+}
+
+/** Clamp scroll offset to [0, maxOffset]. */
+export function clampScrollOffset(offset: number, maxOffset: number): number {
+	return Math.max(0, Math.min(offset, maxOffset));
+}

package/extensions/zentui/fixed-editor/pi-compat.ts

@@ -0,0 +1,296 @@
+/** Verified private Pi TUI capabilities required by the experimental fixed editor. @internal */
+export type PiMethodCapability = {
+	target: Record<PropertyKey, unknown>;
+	key: "render" | "doRender" | "write";
+	method: (...args: unknown[]) => unknown;
+	ownDescriptor: PropertyDescriptor | undefined;
+};
+
+export type PiRenderableCapability = {
+	target: Record<PropertyKey, unknown>;
+	render: (width: number) => string[];
+	ownDescriptor: PropertyDescriptor | undefined;
+};
+
+export type PiFixedCluster = {
+	status: PiRenderableCapability | null;
+	aboveWidget: PiRenderableCapability | null;
+	editor: PiRenderableCapability;
+	belowWidget: PiRenderableCapability | null;
+	footer: PiRenderableCapability | null;
+};
+
+export type PiFixedEditorCapabilities = {
+	tui: Record<PropertyKey, unknown>;
+	terminal: Record<PropertyKey, unknown>;
+	cluster: PiFixedCluster;
+	renderMethod: PiMethodCapability;
+	doRenderMethod: PiMethodCapability;
+	writeMethod: PiMethodCapability;
+	rowsOwnDescriptor: PropertyDescriptor | undefined;
+	readRawRows: () => number;
+	getColumns: () => number;
+	hasVisibleOverlay: () => boolean;
+	getCursorBookkeeping: () => { hardwareCursorRow: number; previousViewportTop: number };
+	addInputListener: (
+		listener: (data: string) => { consume?: boolean; data?: string } | undefined,
+	) => unknown;
+	removeInputListener: (
+		listener: (data: string) => { consume?: boolean; data?: string } | undefined,
+	) => void;
+	requestRender?: (force?: boolean) => void;
+};
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+	return (typeof value === "object" && value !== null) || typeof value === "function";
+}
+
+function ownDescriptor(target: object, key: PropertyKey): PropertyDescriptor | undefined {
+	return Object.getOwnPropertyDescriptor(target, key);
+}
+
+function descriptorInChain(target: object, key: PropertyKey): PropertyDescriptor | undefined {
+	let current: object | null = target;
+	while (current) {
+		const descriptor = Object.getOwnPropertyDescriptor(current, key);
+		if (descriptor) return descriptor;
+		current = Object.getPrototypeOf(current);
+	}
+	return undefined;
+}
+
+function writableMethod(
+	target: Record<PropertyKey, unknown>,
+	key: PiMethodCapability["key"],
+): PiMethodCapability | undefined {
+	const method = Reflect.get(target, key);
+	if (typeof method !== "function") return undefined;
+	const descriptor = ownDescriptor(target, key);
+	if (descriptor) {
+		if (!("value" in descriptor) || descriptor.writable !== true) return undefined;
+	} else if (!Object.isExtensible(target)) {
+		return undefined;
+	}
+	return {
+		target,
+		key,
+		method: method as (...args: unknown[]) => unknown,
+		ownDescriptor: descriptor,
+	};
+}
+
+function renderable(value: unknown): PiRenderableCapability | undefined {
+	if (!isRecord(value)) return undefined;
+	const method = writableMethod(value, "render");
+	if (!method) return undefined;
+	return {
+		target: value,
+		render: method.method as (width: number) => string[],
+		ownDescriptor: method.ownDescriptor,
+	};
+}
+
+function isEditorLike(value: unknown): boolean {
+	return (
+		isRecord(value) &&
+		typeof Reflect.get(value, "getText") === "function" &&
+		typeof Reflect.get(value, "setText") === "function" &&
+		typeof Reflect.get(value, "handleInput") === "function"
+	);
+}
+
+function containerChildren(value: unknown): unknown[] | undefined {
+	if (!isRecord(value)) return undefined;
+	const children = Reflect.get(value, "children");
+	return Array.isArray(children) ? children : undefined;
+}
+
+export function findEditorContainerIndex(
+	children: unknown[],
+	focusedComponent?: unknown,
+): number | undefined {
+	if (focusedComponent && isRecord(focusedComponent)) {
+		const focusedIndex = children.findIndex(
+			(child) => renderable(child) && containerChildren(child)?.includes(focusedComponent),
+		);
+		if (focusedIndex !== -1) return focusedIndex;
+	}
+	const index = children.findIndex(
+		(child) => renderable(child) && containerChildren(child)?.some(isEditorLike),
+	);
+	return index === -1 ? undefined : index;
+}
+
+function clusterCapability(children: unknown[], editorIndex: number): PiFixedCluster | undefined {
+	const editor = renderable(children[editorIndex]);
+	if (!editor) return undefined;
+	const optional = (index: number): PiRenderableCapability | null | undefined => {
+		if (index < 0 || index >= children.length) return null;
+		return renderable(children[index]);
+	};
+	const status = optional(editorIndex - 2);
+	const aboveWidget = optional(editorIndex - 1);
+	const belowWidget = optional(editorIndex + 1);
+	const footer = optional(editorIndex + 2);
+	if (
+		status === undefined ||
+		aboveWidget === undefined ||
+		belowWidget === undefined ||
+		footer === undefined
+	) {
+		return undefined;
+	}
+	return { status, aboveWidget, editor, belowWidget, footer };
+}
+
+function readRowsValue(
+	terminal: Record<PropertyKey, unknown>,
+	descriptor: PropertyDescriptor,
+): unknown {
+	return descriptor.get
+		? descriptor.get.call(terminal)
+		: "value" in descriptor
+			? descriptor.value
+			: Reflect.get(terminal, "rows");
+}
+
+function rowsReader(
+	terminal: Record<PropertyKey, unknown>,
+	descriptor: PropertyDescriptor,
+	fallback: number,
+): () => number {
+	return () => {
+		try {
+			const value = readRowsValue(terminal, descriptor);
+			return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+		} catch {
+			return fallback;
+		}
+	};
+}
+
+function inspectPiTuiUnsafe(value: unknown): PiFixedEditorCapabilities | undefined {
+	if (!isRecord(value)) return undefined;
+	const terminalValue = Reflect.get(value, "terminal");
+	if (!isRecord(terminalValue)) return undefined;
+
+	const renderMethod = writableMethod(value, "render");
+	const doRenderMethod = writableMethod(value, "doRender");
+	const writeMethod = writableMethod(terminalValue, "write");
+	if (!renderMethod || !doRenderMethod || !writeMethod) return undefined;
+
+	const addInputListenerValue = Reflect.get(value, "addInputListener");
+	const removeInputListenerValue = Reflect.get(value, "removeInputListener");
+	if (
+		typeof addInputListenerValue !== "function" ||
+		typeof removeInputListenerValue !== "function"
+	) {
+		return undefined;
+	}
+	const children = Reflect.get(value, "children");
+	if (!Array.isArray(children) || children.length < 3) return undefined;
+	const editorIndex = findEditorContainerIndex(children, Reflect.get(value, "focusedComponent"));
+	if (editorIndex === undefined) return undefined;
+	const cluster = clusterCapability(children, editorIndex);
+	if (!cluster) return undefined;
+
+	const rowsOwnDescriptor = ownDescriptor(terminalValue, "rows");
+	if (
+		rowsOwnDescriptor
+			? rowsOwnDescriptor.configurable !== true
+			: !Object.isExtensible(terminalValue)
+	) {
+		return undefined;
+	}
+	const rowsDescriptor = descriptorInChain(terminalValue, "rows");
+	if (!rowsDescriptor) return undefined;
+	const initialRows = readRowsValue(terminalValue, rowsDescriptor);
+	if (typeof initialRows !== "number" || !Number.isFinite(initialRows)) return undefined;
+	const columns = Reflect.get(terminalValue, "columns");
+	if (typeof columns !== "number" || !Number.isFinite(columns)) return undefined;
+
+	const hasOverlayValue = Reflect.get(value, "hasOverlay");
+	const overlayStackValue = Reflect.get(value, "overlayStack");
+	if (typeof hasOverlayValue !== "function" && !Array.isArray(overlayStackValue)) return undefined;
+	const hardwareCursorRow = Reflect.get(value, "hardwareCursorRow");
+	const previousViewportTop = Reflect.get(value, "previousViewportTop");
+	if (
+		typeof hardwareCursorRow !== "number" ||
+		!Number.isFinite(hardwareCursorRow) ||
+		typeof previousViewportTop !== "number" ||
+		!Number.isFinite(previousViewportTop)
+	) {
+		return undefined;
+	}
+
+	const requestRenderValue = Reflect.get(value, "requestRender");
+	return {
+		tui: value,
+		terminal: terminalValue,
+		cluster,
+		renderMethod,
+		doRenderMethod,
+		writeMethod,
+		rowsOwnDescriptor,
+		readRawRows: rowsReader(terminalValue, rowsDescriptor, initialRows),
+		getColumns: () => {
+			try {
+				const current = Reflect.get(terminalValue, "columns");
+				return typeof current === "number" && Number.isFinite(current) ? current : columns;
+			} catch {
+				return columns;
+			}
+		},
+		hasVisibleOverlay: () => {
+			try {
+				if (
+					typeof hasOverlayValue === "function" &&
+					Reflect.apply(hasOverlayValue, value, []) === true
+				) {
+					return true;
+				}
+				const stack = Reflect.get(value, "overlayStack");
+				return (
+					Array.isArray(stack) && stack.some((entry) => isRecord(entry) && entry.hidden !== true)
+				);
+			} catch {
+				return true;
+			}
+		},
+		getCursorBookkeeping: () => {
+			try {
+				const currentHardwareCursorRow = Reflect.get(value, "hardwareCursorRow");
+				const currentViewportTop = Reflect.get(value, "previousViewportTop");
+				return {
+					hardwareCursorRow:
+						typeof currentHardwareCursorRow === "number" &&
+						Number.isFinite(currentHardwareCursorRow)
+							? currentHardwareCursorRow
+							: hardwareCursorRow,
+					previousViewportTop:
+						typeof currentViewportTop === "number" && Number.isFinite(currentViewportTop)
+							? currentViewportTop
+							: previousViewportTop,
+				};
+			} catch {
+				return { hardwareCursorRow, previousViewportTop };
+			}
+		},
+		addInputListener: (listener) => Reflect.apply(addInputListenerValue, value, [listener]),
+		removeInputListener: (listener) => {
+			Reflect.apply(removeInputListenerValue, value, [listener]);
+		},
+		requestRender:
+			typeof requestRenderValue === "function"
+				? (force) => Reflect.apply(requestRenderValue, value, [force])
+				: undefined,
+	};
+}
+
+export function inspectPiTui(value: unknown): PiFixedEditorCapabilities | undefined {
+	try {
+		return inspectPiTuiUnsafe(value);
+	} catch {
+		return undefined;
+	}
+}