pi-extension-utils 0.7.7 → 0.7.8

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.8",
 	"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.84.4",
+		"@earendil-works/pi-ai": "^0.84.4",
+		"@earendil-works/pi-coding-agent": "^0.84.4",
+		"@earendil-works/pi-tui": "^0.84.4",
 		"@types/node": "^24.0.0",
 		"typescript": "^6.0.3"
 	},