pi-extension-utils 0.5.2 → 0.7.0

package/dist/src/client/index.js

@@ -1,11 +1,12 @@
 import { createRemindersClient } from "../reminders/client.js";
-import { createUiClient } from "../ui/client.js";
+import { createTuiModeCapture, createUiClient } from "../ui/client.js";
 import { connectWidgetCoordinator } from "../widgets/client.js";
 let nextClientId = 1;
 export function connect(pi, opts) {
     const clientId = opts.clientId ?? `client-${process.pid}-${Date.now()}-${nextClientId++}`;
     let disposed = false;
-    const coordinator = connectWidgetCoordinator(pi, { ctx: opts.ctx, clientId });
+    const tuiCapture = createTuiModeCapture();
+    const coordinator = connectWidgetCoordinator(pi, { ctx: opts.ctx, clientId, tui: tuiCapture });
     return {
         clientId,
         get mode() {
@@ -13,7 +14,7 @@ export function connect(pi, opts) {
         },
         widgets: coordinator.widgets,
         fullscreen: coordinator.fullscreen,
-        ui: createUiClient(coordinator.fullscreen, opts.ctx),
+        ui: createUiClient(coordinator.fullscreen, opts.ctx, tuiCapture),
         reminders: createRemindersClient(pi, () => disposed),
         dispose() {
             if (disposed)

package/dist/src/pane/mouse.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SGR (1006) mouse sequence parsing for pane overlays.
+ *
+ * In fullscreen TUI mode a focused overlay receives raw mouse input: pi's
+ * alt-screen viewport handler defers wheel and SGR mouse sequences to the
+ * focused component (see TuiAltScreen#shouldDeferViewportInputToOverlay).
+ * These helpers turn those sequences into structured events. In regular TUI
+ * mode no mouse sequences arrive, so pane overlays degrade gracefully to
+ * keyboard-only input with zero changes at call sites.
+ */
+export interface SgrMouseEvent {
+    /** 0 = left, 1 = middle, 2 = right, 64 = wheel up, 65 = wheel down. */
+    button: number;
+    /** 1-based terminal column. */
+    x: number;
+    /** 1-based terminal row. */
+    y: number;
+    /** Button press (not motion, not release). */
+    press: boolean;
+    release: boolean;
+    /** Motion with a button held (drag). */
+    motion: boolean;
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+}
+/** Parse a full SGR mouse sequence. Returns undefined for any other input. */
+export declare function parseSgrMouseEvent(data: string): SgrMouseEvent | undefined;

package/dist/src/pane/mouse.js

@@ -0,0 +1,35 @@
+/**
+ * SGR (1006) mouse sequence parsing for pane overlays.
+ *
+ * In fullscreen TUI mode a focused overlay receives raw mouse input: pi's
+ * alt-screen viewport handler defers wheel and SGR mouse sequences to the
+ * focused component (see TuiAltScreen#shouldDeferViewportInputToOverlay).
+ * These helpers turn those sequences into structured events. In regular TUI
+ * mode no mouse sequences arrive, so pane overlays degrade gracefully to
+ * keyboard-only input with zero changes at call sites.
+ */
+const SGR_MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/;
+/** Parse a full SGR mouse sequence. Returns undefined for any other input. */
+export function parseSgrMouseEvent(data) {
+    const match = SGR_MOUSE_RE.exec(data);
+    if (!match)
+        return undefined;
+    const cb = Number(match[1]);
+    const x = Number(match[2]);
+    const y = Number(match[3]);
+    const isRelease = match[4] === "m";
+    const motion = (cb & 32) !== 0 && !isRelease;
+    const wheel = (cb & 64) !== 0;
+    const buttonBits = cb & 3;
+    return {
+        button: wheel ? 64 + buttonBits : buttonBits,
+        x,
+        y,
+        press: !isRelease && !motion,
+        release: isRelease,
+        motion,
+        shift: (cb & 4) !== 0,
+        alt: (cb & 8) !== 0,
+        ctrl: (cb & 16) !== 0,
+    };
+}

package/dist/src/pane/overlay.js

@@ -1,4 +1,5 @@
 import { dispatchNavKeys } from "./key-dispatch.js";
+import { parseSgrMouseEvent } from "./mouse.js";
 import { computeFixedSidebarLayout, computeSplitPaneLayout, endScrollOffset, ensureCursorVisible, homeScrollOffset, moveScrollOffset, pageScrollOffset, resizeSplitPane, } from "./state.js";
 import { boxRow, clipStyled, flatRule, formatScrollInfo, padRight, renderKeyRow, titledBottomSegment, titledTopSegment, } from "./chrome.js";
 import { matchesKey } from "@earendil-works/pi-tui";
@@ -94,6 +95,9 @@ export function paneOverlay(options) {
             return typeof label === "function" ? label(collapsed) : (label ?? fallback);
         };
         let leftFraction = split.initialFraction ?? 0.5;
+        let dividerDragActive = false;
+        let lastPrimaryClick;
+        let componentRef;
         let lastRenderWidth = 80;
         let lastSelectedKey;
         let initialSelectionApplied = false;
@@ -361,6 +365,133 @@ export function paneOverlay(options) {
             const keyWidth = Math.min(11, Math.max(3, Math.floor(totalWidth / 4)));
             return entries.map((entry) => chromeTheme.fg("dim", renderKeyRow(entry.key, entry.label, totalWidth, keyWidth)));
         };
+        /**
+         * Mouse support (fullscreen TUI only, where a focused overlay receives raw
+         * SGR sequences). Wheel scrolls the pane under the pointer; click selects
+         * rows and focuses panes; double-click activates (synthesizes Enter);
+         * dragging the divider resizes the split. All bounds are in overlay-local
+         * coordinates: the overlay mounts top-left at 100% width, so terminal
+         * columns/rows map 1:1 to rendered lines.
+         */
+        const handleMouseEvent = (event) => {
+            if (finished)
+                return;
+            const totalWidth = lastRenderWidth;
+            if (totalWidth <= 0)
+                return;
+            const bodyHeight = computeBodyHeight(tui, options.height);
+            const { primaryWidth, detailWidth } = currentWidths();
+            const { selectedIndex, selectedRow, selectedKey } = computeSelectionFromRows(getPrimaryRows(makeContext(0, undefined, "", primaryWidth, detailWidth)), bodyHeight);
+            const ctx = makeContext(selectedIndex, selectedRow, selectedKey, primaryWidth, detailWidth);
+            const detailRows = options.detail.rows(ctx) ?? [];
+            const legendLineCount = legendPlacement === "primary"
+                ? renderLegendLines(legendEntries(ctx), totalWidth).length
+                : 0;
+            const maxRow = 1 + bodyHeight + (legendPlacement === "footer"
+                ? renderLegendLines(legendEntries(ctx), totalWidth).length
+                : 0);
+            const inPrimaryColumn = primaryWidth > 0 && event.x >= 1 && event.x <= primaryWidth;
+            const onDivider = !collapsed && primaryWidth > 0 && event.x === primaryWidth + 1;
+            const inDetailColumn = event.x > primaryWidth + 1;
+            // Wheel: scroll the pane under the pointer (shift accelerates).
+            if (event.button === 64 || event.button === 65) {
+                if (event.y > maxRow)
+                    return;
+                const lines = (event.button === 64 ? -1 : 1) * (event.shift ? 5 : 3);
+                if (inPrimaryColumn || (primaryWidth > 0 && event.x <= primaryWidth + 1)) {
+                    focus = "primary";
+                    applyPrimaryNav(bodyHeight, legendLineCount, (state, rows, viewportHeight) => {
+                        if ((options.primary.mode ?? "scroll") === "cursor") {
+                            const indexes = selectableIndexes(rows);
+                            if (indexes.length === 0)
+                                return;
+                            const currentIndex = nearestSelectableIndex(rows, state.cursor);
+                            const currentOrdinal = Math.max(0, indexes.indexOf(currentIndex));
+                            const nextOrdinal = Math.max(0, Math.min(indexes.length - 1, currentOrdinal + lines));
+                            state.cursor = indexes[nextOrdinal] ?? currentIndex;
+                            const next = ensureCursorVisible({ cursor: state.cursor, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight });
+                            state.scrollOffset = next.scroll;
+                        }
+                        else {
+                            state.scrollOffset = moveScrollOffset({ offset: state.scrollOffset, contentLength: rows.length, viewportHeight }, lines);
+                        }
+                    });
+                }
+                else {
+                    focus = "detail";
+                    markDetailManual();
+                    detailState.scrollOffset = moveScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, lines);
+                }
+                requestRender();
+                return;
+            }
+            // Divider drag: press on the divider starts it, motion resizes, release ends.
+            if (onDivider && event.press && event.button === 0) {
+                dividerDragActive = true;
+                return;
+            }
+            if (event.motion && dividerDragActive) {
+                const usable = Math.max(1, totalWidth - 3);
+                const minFraction = Math.max(split.minFraction ?? 0, (split.minPrimaryWidth ?? 8) / usable);
+                const maxFraction = Math.min(split.maxFraction ?? 1, (usable - (split.minDetailWidth ?? 8)) / usable, split.maxPrimaryWidth !== undefined ? split.maxPrimaryWidth / usable : 1);
+                leftFraction = Math.max(Math.min(minFraction, maxFraction), Math.min(maxFraction, (event.x - 1) / usable));
+                requestRender();
+                return;
+            }
+            if (event.release && event.button === 0 && dividerDragActive) {
+                dividerDragActive = false;
+                return;
+            }
+            if (!event.press || event.button !== 0 || event.y > maxRow)
+                return;
+            // Title/border rows: click focuses the pane under the pointer.
+            if (event.y === 0 || event.y === bodyHeight + 1) {
+                if (primaryWidth > 0 && event.x <= primaryWidth + 1)
+                    focus = "primary";
+                else
+                    focus = "detail";
+                ensureFocusDetailWhenCollapsed();
+                requestRender();
+                return;
+            }
+            // Body rows.
+            if (event.y >= 1 && event.y <= bodyHeight) {
+                if (onDivider)
+                    return;
+                if (inPrimaryColumn && !collapsed) {
+                    focus = "primary";
+                    if ((options.primary.mode ?? "scroll") === "cursor") {
+                        const rowIndex = event.y - 1;
+                        const absoluteIndex = primaryState.scrollOffset + rowIndex;
+                        applyPrimaryNav(bodyHeight, legendLineCount, (state, rows, viewportHeight) => {
+                            if (absoluteIndex >= rows.length)
+                                return;
+                            state.cursor = nearestSelectableIndex(rows, absoluteIndex);
+                            const next = ensureCursorVisible({ cursor: state.cursor, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight });
+                            state.scrollOffset = next.scroll;
+                        });
+                        const now = Date.now();
+                        const isDoubleClick = lastPrimaryClick
+                            && lastPrimaryClick.row === event.y
+                            && lastPrimaryClick.col === event.x
+                            && now - lastPrimaryClick.at < 450;
+                        lastPrimaryClick = { row: event.y, col: event.x, at: now };
+                        requestRender();
+                        if (isDoubleClick)
+                            componentRef?.handleInput("\r");
+                        return;
+                    }
+                    requestRender();
+                    return;
+                }
+                if (inDetailColumn) {
+                    focus = "detail";
+                    ensureFocusDetailWhenCollapsed();
+                    requestRender();
+                    return;
+                }
+            }
+        };
         const component = {
             dispose() {
                 // no-op is acceptable
@@ -508,6 +639,11 @@ export function paneOverlay(options) {
             handleInput(data) {
                 if (finished)
                     return;
+                const mouseEvent = parseSgrMouseEvent(data);
+                if (mouseEvent) {
+                    handleMouseEvent(mouseEvent);
+                    return;
+                }
                 const bodyHeight = computeBodyHeight(tui, options.height);
                 if (matchesAny(data, closeKeys)) {
                     finish(options.closeResult);
@@ -615,6 +751,7 @@ export function paneOverlay(options) {
                 }
             },
         };
+        componentRef = component;
         return component;
     };
 }

package/dist/src/ui/client.d.ts

@@ -4,6 +4,17 @@ export interface FullscreenLeaseLike {
 export interface FullscreenController {
     acquire(): FullscreenLeaseLike;
 }
+/**
+ * Lazily-captured TUI reference used to detect the fullscreen TUI mode.
+ * Populated whenever pi invokes any wrapped UI factory (widget, footer,
+ * editor, custom component). Structural on purpose: the helper must not
+ * depend on pi-tui types directly.
+ */
+export interface TuiModeCapture {
+    noteTui(tui: unknown): void;
+    isFullscreenTui(): boolean;
+}
+export declare function createTuiModeCapture(): TuiModeCapture;
 /**
  * Factory signature accepted by `ctx.ui.custom`. Typed structurally so the
  * helper does not depend on pi-tui types directly.
@@ -19,4 +30,4 @@ export interface UiClient {
 }
 export declare function createUiClient(fullscreen: FullscreenController, ctx: {
     ui: unknown;
-}): UiClient;
+}, capture?: TuiModeCapture): UiClient;

package/dist/src/ui/client.js

@@ -1,4 +1,17 @@
-export function createUiClient(fullscreen, ctx) {
+export function createTuiModeCapture() {
+    let mode;
+    return {
+        noteTui(tui) {
+            const value = tui?.mode;
+            if (typeof value === "string")
+                mode = value;
+        },
+        isFullscreenTui() {
+            return mode === "fullscreen";
+        },
+    };
+}
+export function createUiClient(fullscreen, ctx, capture = createTuiModeCapture()) {
     return {
         async fullscreen(factory) {
             const ui = ctx.ui;
@@ -7,7 +20,22 @@ export function createUiClient(fullscreen, ctx) {
             }
             const lease = fullscreen.acquire();
             try {
-                return await ui.custom(factory);
+                const wrapped = (tui, theme, keybindings, done) => {
+                    capture.noteTui(tui);
+                    return factory(tui, theme, keybindings, done);
+                };
+                // In the fullscreen TUI a plain custom component mounts inside the
+                // bottom dock (the editor slot), where the dock layout shrinks and
+                // clips it while the transcript tail renders above it. Mount it as a
+                // full-screen overlay instead so the component owns the whole screen,
+                // matching the regular-TUI behavior it was designed for.
+                const options = capture.isFullscreenTui()
+                    ? {
+                        overlay: true,
+                        overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%" },
+                    }
+                    : undefined;
+                return await ui.custom(wrapped, options);
             }
             finally {
                 lease.release();

package/dist/src/widgets/client.d.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type TuiModeCapture } from "../ui/client.ts";
 import { type WidgetFactory, type WidgetPlacement } from "./protocol.ts";
 export interface WidgetSetOptions {
     order?: number;
@@ -22,6 +23,8 @@ export interface WidgetCoordinatorClient {
 interface WidgetCoordinatorClientOptions {
     ctx: ExtensionContext;
     clientId: string;
+    /** Optional shared TUI-mode capture fed by every widget factory invocation. */
+    tui?: TuiModeCapture;
 }
 export declare function connectWidgetCoordinator(pi: ExtensionAPI, opts: WidgetCoordinatorClientOptions): WidgetCoordinatorClient;
 export {};

package/dist/src/widgets/client.js

@@ -1,5 +1,11 @@
 import { basePayload, EVENTS, PROTOCOL_VERSION } from "./protocol.js";
 let nextLeaseId = 1;
+function withTuiCapture(factory, capture) {
+    return (tui, theme) => {
+        capture.noteTui(tui);
+        return factory(tui, theme);
+    };
+}
 export function connectWidgetCoordinator(pi, opts) {
     const { clientId } = opts;
     const widgets = new Map();
@@ -78,13 +84,18 @@ export function connectWidgetCoordinator(pi, opts) {
             set(placement, key, factory, setOpts = {}) {
                 if (disposed)
                     return;
-                const record = { placement, key, factory, order: setOpts.order ?? 0 };
+                const record = {
+                    placement,
+                    key,
+                    factory: opts.tui ? withTuiCapture(factory, opts.tui) : factory,
+                    order: setOpts.order ?? 0,
+                };
                 widgets.set(widgetId(placement, key), record);
                 if (coordinated) {
                     emitRegister(record);
                 }
                 else if (leases.size === 0) {
-                    opts.ctx.ui.setWidget(key, factory, { placement });
+                    opts.ctx.ui.setWidget(key, record.factory, { placement });
                 }
             },
             remove(placement, key) {

package/dist/src/widgets/host.js

@@ -109,14 +109,47 @@ export function registerWidgetHost(pi) {
     }
 }
 function createHostComponent(tui, theme, records, hidden) {
-    const components = hidden ? [] : records.map((record) => record.factory(tui, theme));
+    // A widget whose factory or render throws (e.g. an extension holding a
+    // ctx that went stale during session reload) must never take down the
+    // whole agent: render failures drop that widget until its client
+    // re-registers. Records are replaced wholesale on every re-registration
+    // and remount, so a dropped component cannot linger past the handshake.
+    const healthy = [];
+    if (!hidden) {
+        for (const record of records) {
+            try {
+                healthy.push(record.factory(tui, theme));
+            }
+            catch (error) {
+                console.warn(`pi-extension-utils: widget factory for ${record.clientId}/${record.key} threw, dropping it until re-registration`, error instanceof Error ? error.message : error);
+            }
+        }
+    }
     return {
         render(width) {
-            return components.flatMap((component) => component.render(width));
+            const lines = [];
+            for (const component of [...healthy]) {
+                try {
+                    lines.push(...component.render(width));
+                }
+                catch (error) {
+                    const failedIndex = healthy.indexOf(component);
+                    if (failedIndex >= 0)
+                        healthy.splice(failedIndex, 1);
+                    console.warn(`pi-extension-utils: widget render threw, dropping it until re-registration`, error instanceof Error ? error.message : error);
+                }
+            }
+            return lines;
         },
         invalidate() {
-            for (const component of components)
-                component.invalidate();
+            for (const component of healthy) {
+                try {
+                    component.invalidate();
+                }
+                catch {
+                    // invalidate is best-effort; ignore failures
+                }
+            }
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-extension-utils",
-	"version": "0.5.2",
+	"version": "0.7.0",
 	"description": "Shared Pi extension utilities for coordinated widgets, fullscreen leases, and logging.",
 	"type": "module",
 	"main": "./dist/src/index.js",