pi-extension-utils 0.7.4 → 0.7.5

package/README.md

@@ -1,6 +1,6 @@
 # pi-extension-utils
 
-Shared utilities for Pi extensions that need coordinated UI, fullscreen overlays, reminders, and logging.
+Shared utilities for Pi extensions that need coordinated UI, fullscreen custom UIs, reminders, and logging.
 
 Two faces:
 

package/dist/src/ui/client.js

@@ -14,6 +14,39 @@ export function createTuiModeCapture() {
         },
     };
 }
+function getLayoutRootTui(tui) {
+    if ((typeof tui !== "object" && typeof tui !== "function") || tui === null)
+        return undefined;
+    if (!("layoutRoot" in tui) || typeof tui.setLayoutRoot !== "function")
+        return undefined;
+    return tui;
+}
+// Pi 0.84 exposes setLayoutRoot() but no getter. Its TypeScript-private
+// layoutRoot remains a runtime property; keep that compatibility bridge here.
+function getLayoutRoot(tui) {
+    return tui.layoutRoot;
+}
+function createOverlayInputProxy(component) {
+    const target = component;
+    const proxy = {
+        render: () => [],
+        invalidate: () => target.invalidate?.(),
+        handleInput: (data) => target.handleInput?.(data),
+        get wantsKeyRelease() {
+            return target.wantsKeyRelease;
+        },
+        dispose: () => target.dispose?.(),
+    };
+    if (((typeof target === "object" && target !== null) || typeof target === "function") && "focused" in target) {
+        Object.defineProperty(proxy, "focused", {
+            get: () => target.focused,
+            set: (focused) => {
+                target.focused = focused;
+            },
+        });
+    }
+    return proxy;
+}
 export function createUiClient(fullscreen, ctx, capture = createTuiModeCapture()) {
     return {
         async fullscreen(factory) {
@@ -22,20 +55,52 @@ export function createUiClient(fullscreen, ctx, capture = createTuiModeCapture()
                 throw new Error("pi-extension-utils: ui.fullscreen requires an interactive UI (ctx.ui.custom is unavailable)");
             }
             const lease = fullscreen.acquire();
+            let restoreLayoutRoot;
+            let closed = false;
+            const close = () => {
+                closed = true;
+                restoreLayoutRoot?.();
+            };
             try {
                 const wrapped = (tui, theme, keybindings, done) => {
                     capture.noteTui(tui);
-                    return factory(tui, theme, keybindings, done);
+                    const mount = (component) => {
+                        const layoutTui = capture.isFullscreenTui() ? getLayoutRootTui(tui) : undefined;
+                        if (!layoutTui)
+                            return component;
+                        if (closed)
+                            return createOverlayInputProxy(component);
+                        const priorRoot = getLayoutRoot(layoutTui);
+                        let restored = false;
+                        restoreLayoutRoot = () => {
+                            if (restored)
+                                return;
+                            restored = true;
+                            layoutTui.setLayoutRoot(priorRoot);
+                            layoutTui.requestRender?.(true);
+                        };
+                        layoutTui.setLayoutRoot(component);
+                        layoutTui.requestRender?.(true);
+                        return createOverlayInputProxy(component);
+                    };
+                    const component = factory(tui, theme, keybindings, (result) => {
+                        close();
+                        done(result);
+                    });
+                    if (component && typeof component.then === "function") {
+                        return Promise.resolve(component).then(mount);
+                    }
+                    return mount(component);
                 };
                 // 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.
+                // bottom dock. Use the overlay path for focus/lifecycle, then let the
+                // wrapped factory replace a capable viewport TUI's layout root. The
+                // returned empty input proxy keeps the host overlay from rendering the
+                // same dashboard a second time.
                 // Before any wrapped factory has rendered, the mode is unknown. Default
                 // that cold-start case to an overlay: it is the only mount that remains
-                // fullscreen and receives focus in the alt-screen TUI. Preserve the
-                // legacy editor-slot mount only when regular mode was positively seen.
+                // safe in the alt-screen TUI. Preserve the legacy editor-slot mount only
+                // when regular mode was positively seen.
                 const options = capture.isRegularTui()
                     ? undefined
                     : {
@@ -45,7 +110,12 @@ export function createUiClient(fullscreen, ctx, capture = createTuiModeCapture()
                 return await ui.custom(wrapped, options);
             }
             finally {
-                lease.release();
+                try {
+                    close();
+                }
+                finally {
+                    lease.release();
+                }
             }
         },
     };

package/docs/client.md

@@ -44,9 +44,13 @@ await client.ui.fullscreen((tui, theme, keybindings, done) => new MyComponent(tu
 
 - acquires a fullscreen lease
 - blanks coordinated widgets
-- calls `ctx.ui.custom()`
+- preserves the regular-TUI editor-slot mount
+- temporarily replaces a capable fullscreen viewport TUI's layout root with the dashboard and forces redraws on install and restoration
+- uses the overlay path as the safe cold-start/fallback mount without rendering the real dashboard twice
 - releases the lease in `finally`
 
+Pi 0.84.x exposes the layout-root setter but no public getter, so exact restoration uses its runtime `layoutRoot` property through an isolated structural bridge. If a fullscreen TUI does not expose that setter/property shape, `ui.fullscreen()` safely falls back to the full-size overlay; that fallback cannot guarantee that terminal image placements from the transcript are cleared.
+
 Use `client.fullscreen.acquire()` only when you need manual lease control.
 
 ## Pane overlay

package/package.json

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