pi-extension-utils 0.7.7 → 0.7.9

package/dist/src/pane/overlay.js

@@ -223,8 +223,19 @@ export function paneOverlay(options) {
             primaryState.cursor = selectableIndex;
             primaryState.scrollOffset = selectableIndex;
         };
+        let previousPrimaryKeys = [];
         const computeSelectionFromRows = (primaryRows, bodyHeight) => {
             applyInitialSelection(primaryRows);
+            // The cursor indexes the previous snapshot. Resolve its stable identity
+            // before interpreting that index against refreshed or reordered rows.
+            if (options.primary.mode === "cursor" && options.primary.selectionKey) {
+                const keys = primaryRows.map((row, index) => isSeparatorRow(row) ? undefined : selectionKeyFor(row, index));
+                const previousKey = previousPrimaryKeys[primaryState.cursor];
+                const nextIndex = previousKey === undefined ? -1 : keys.indexOf(previousKey);
+                if (nextIndex >= 0)
+                    primaryState.cursor = nextIndex;
+                previousPrimaryKeys = keys;
+            }
             const primaryMode = options.primary.mode ?? "scroll";
             let selectedIndex = 0;
             if (primaryMode === "cursor") {

package/dist/src/reminders/host.js

@@ -256,17 +256,33 @@ function padToWidth(line, width) {
 }
 const SYSTEM_REMINDER_MIN_BODY_WIDTH = 76;
 const SYSTEM_REMINDER_BODY_WIDTH_RATIO = 0.9;
+/**
+ * Bordered transcript box for one reminder message.
+ *
+ * Content and details are fixed for the component's lifetime, so the laid-out lines depend only on
+ * width and theme colors. Lines are cached for the last width because the TUI renders every
+ * transcript component on each frame and large reminders are expensive to re-wrap. `invalidate()`
+ * drops the cache so theme changes take effect on the next render.
+ */
 class SystemReminderComponent {
     content;
     details;
     theme;
+    cache;
     constructor(content, details, theme) {
         this.content = content;
         this.details = details;
         this.theme = theme;
     }
-    invalidate() { }
+    invalidate() {
+        this.cache = undefined;
+    }
     render(width) {
+        if (this.cache?.width !== width)
+            this.cache = { width, lines: this.layout(width) };
+        return this.cache.lines;
+    }
+    layout(width) {
         if (width < 3)
             return [truncateToWidth("System Reminder", width)];
         const availableBodyWidth = width - 2;

package/dist/src/widgets/client.js

@@ -70,11 +70,14 @@ export function connectWidgetCoordinator(pi, opts) {
         mount.disposed = false;
         mount.tui?.requestRender?.();
     }
+    function fallbackKey(record) {
+        return `pi-extension-utils-fallback:${JSON.stringify([clientId, record.placement, record.key])}`;
+    }
     function clearFallback(record) {
-        opts.ctx.ui.setWidget(record.key, undefined, { placement: record.placement });
+        opts.ctx.ui.setWidget(fallbackKey(record), undefined, { placement: record.placement });
     }
     function restoreFallback(record) {
-        opts.ctx.ui.setWidget(record.key, record.fallbackFactory, { placement: record.placement });
+        opts.ctx.ui.setWidget(fallbackKey(record), record.fallbackFactory, { placement: record.placement });
     }
     function attach() {
         if (disposed || coordinated)

package/dist/src/widgets/host.js

@@ -114,7 +114,7 @@ function createHostComponent(tui, theme, records, hidden) {
     // 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 = [];
+    let healthy = [];
     if (!hidden) {
         for (const record of records) {
             try {
@@ -128,19 +128,26 @@ function createHostComponent(tui, theme, records, hidden) {
     return {
         render(width) {
             const lines = [];
+            const failed = new Set();
             for (const component of [...healthy]) {
+                if (failed.has(component))
+                    continue;
                 try {
                     lines.push(...component.render(width));
                 }
                 catch (error) {
-                    const failedIndex = healthy.indexOf(component);
-                    if (failedIndex >= 0)
-                        healthy.splice(failedIndex, 1);
+                    failed.add(component);
+                    healthy = healthy.filter((child) => child !== component);
+                    disposeChild(component);
                     console.warn(`pi-extension-utils: widget render threw, dropping it until re-registration`, error instanceof Error ? error.message : error);
                 }
             }
             return lines;
         },
+        dispose() {
+            for (const component of new Set(healthy.splice(0)))
+                disposeChild(component);
+        },
         invalidate() {
             for (const component of healthy) {
                 try {
@@ -153,6 +160,14 @@ function createHostComponent(tui, theme, records, hidden) {
         },
     };
 }
+function disposeChild(component) {
+    try {
+        component.dispose?.();
+    }
+    catch (error) {
+        console.warn("pi-extension-utils: widget dispose threw", error instanceof Error ? error.message : error);
+    }
+}
 function hostKey(placement) {
     return `${HOST_WIDGET_PREFIX}-${placement}`;
 }

package/docs/widgets.md

@@ -48,9 +48,15 @@ When any client holds a fullscreen lease, coordinated widgets are hidden and res
 await client.ui.fullscreen((tui, theme, keybindings, done) => new MyComponent(tui, theme, done));
 ```
 
+## Component ownership
+
+A widget factory transfers ownership of its returned component to the mount. Pi disposes the old mount before calling a replacement factory. Return a fresh component on each mount; do not reuse a disposed component or share one across placements or independent mounts.
+
+The host remounts a placement when its registrations or fullscreen visibility change. It disposes each owned child once on replacement, removal, hiding, or Pi UI teardown. A child whose render throws is detached and disposed immediately; a throwing disposer does not prevent sibling cleanup. If a factory throws before returning a component, it must clean up any resources it already created.
+
 ## Fallback
 
-If the host is not ready yet, each logical widget registers one stable proxy through the extension's own `ctx.ui.setWidget`. Later `widgets.set` calls replace the proxy's delegated component and request a redraw without re-registering the raw widget, preserving cross-extension insertion order on Pi versions that delete before setting. Set and fullscreen-acquire activity also retry the hello handshake without a polling timer. When the host announces readiness, the client clears the fallback widget and re-registers through the coordinator.
+If the host is not ready yet, each logical widget registers one stable proxy through the extension's own `ctx.ui.setWidget`. Its internal raw key includes the client ID, placement, and logical key, so separate clients and placements can use the same logical key. Later `widgets.set` calls replace the proxy's delegated component and request a redraw without re-registering the raw widget, preserving cross-extension insertion order on Pi versions that delete before setting. Set and fullscreen-acquire activity also retry the hello handshake without a polling timer. When the host announces readiness, the client clears the fallback widget and re-registers through the coordinator.
 
 ## Example
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-extension-utils",
-	"version": "0.7.7",
+	"version": "0.7.9",
 	"description": "Shared Pi extension utilities for coordinated widgets, fullscreen leases, and logging.",
 	"type": "module",
 	"main": "./dist/src/index.js",
@@ -43,10 +43,10 @@
 		"@earendil-works/pi-tui": "*"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-agent-core": "^0.75.4",
-		"@earendil-works/pi-ai": "^0.75.4",
-		"@earendil-works/pi-coding-agent": "^0.75.4",
-		"@earendil-works/pi-tui": "^0.79.3",
+		"@earendil-works/pi-agent-core": "0.87.1",
+		"@earendil-works/pi-ai": "0.87.1",
+		"@earendil-works/pi-coding-agent": "0.87.1",
+		"@earendil-works/pi-tui": "0.87.1",
 		"@types/node": "^24.0.0",
 		"typescript": "^6.0.3"
 	},