pi-extension-utils 0.7.3 → 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/pane/chrome.d.ts

@@ -1,10 +1,12 @@
 /**
- * Minimal theme shape for chrome helpers: only `fg(color, text)` is required.
- * Lets the same helpers work for both `@earendil-works/pi-coding-agent` Theme and
+ * Minimal theme shape for chrome helpers: only `fg(color, text)` is required;
+ * `bg` enables native-style scrollbar thumbs when the host exposes it. Lets the
+ * same helpers work for both `@earendil-works/pi-coding-agent` Theme and
  * any pi-tui-compatible theme.
  */
 export interface ChromeTheme {
     fg(color: string, text: string): string;
+    bg?(color: string, text: string): string;
     bold?(text: string): string;
 }
 export declare function fuzzyFilter<T extends {
@@ -23,6 +25,10 @@ export declare function renderFooter(text: string, width: number, theme: ChromeT
 export interface TitledTopSegmentOptions {
     width: number;
     label: string;
+    /** Pre-rendered label string when caller already applied ANSI; pair with `labelPlain` for length. */
+    labelRendered?: string;
+    /** Plain visible-width companion for `labelRendered` so truncation and dash math stay correct. */
+    labelPlain?: string;
     /** Plain-text tail; styled via `tailColor` (default "dim"). */
     tail?: string;
     /** Pre-rendered tail string when caller already applied ANSI; pair with `tailPlain` for length. */

package/dist/src/pane/chrome.js

@@ -103,13 +103,14 @@ export function titledTopSegment(theme, opts) {
         const tailLen = visibleWidth(tailPlain);
         const canShowTail = tailLen > 0 && width - tailLen >= 14;
         const labelBudget = Math.max(0, width - (canShowTail ? tailLen + 6 : 4));
-        const labelText = clipText(normalizeRenderableText(opts.label ?? ""), labelBudget);
+        const labelText = clipText(normalizeRenderableText(opts.labelPlain ?? opts.label ?? ""), labelBudget);
         const labelLen = visibleWidth(labelText);
         if (labelLen === 0)
             return dash(width);
-        const labelStyled = opts.labelBold && theme.bold
-            ? theme.bold(theme.fg(labelColor, labelText))
+        const renderedLabel = opts.labelRendered !== undefined
+            ? clipStyled(opts.labelRendered, labelLen)
             : theme.fg(labelColor, labelText);
+        const labelStyled = opts.labelBold && theme.bold ? theme.bold(renderedLabel) : renderedLabel;
         if (canShowTail) {
             const fillDashes = Math.max(1, width - labelLen - tailLen - 6);
             return clipStyled(`${dash(1)} ${labelStyled} ${dash(fillDashes)} ${tailRendered} ${dash(1)}`, width);
@@ -133,12 +134,13 @@ export function titledTopSegment(theme, opts) {
     const labelBudget = tailFits ? Math.max(0, width - tailLen - 7) : Math.max(0, width - 3);
     // Defensive: callers occasionally pass undefined labels for transient/legacy
     // runs that lack agent+mode+label; treat as empty rather than crashing pi.
-    const rawLabel = normalizeRenderableText(opts.label ?? "");
+    const rawLabel = normalizeRenderableText(opts.labelPlain ?? opts.label ?? "");
     const labelText = truncateToWidth(rawLabel, labelBudget, "").replace(/\u001b\[[0-9;]*m/g, "");
-    const labelStyled = opts.labelBold && theme.bold
-        ? theme.bold(theme.fg(labelColor, labelText))
-        : theme.fg(labelColor, labelText);
     const labelLen = visibleWidth(labelText);
+    const renderedLabel = opts.labelRendered !== undefined
+        ? clipStyled(opts.labelRendered, labelLen)
+        : theme.fg(labelColor, labelText);
+    const labelStyled = opts.labelBold && theme.bold ? theme.bold(renderedLabel) : renderedLabel;
     // Layout with tail: `─ <label> ──…── <tail> ─`.
     // Layout without tail: `─ <label> ──…────`.
     if (tailFits) {

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

@@ -1,19 +1,18 @@
 /**
  * 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.
+ * In fullscreen TUI mode Pi defers wheel input to a focused overlay. Pi 0.84
+ * still consumes non-wheel SGR mouse events before the overlay sees them, so
+ * click and drag paths require a host that forwards those events. These helpers
+ * turn forwarded sequences into structured events. Regular TUI mode remains
+ * keyboard-only 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. */
+    /** 0-based terminal column. */
     x: number;
-    /** 1-based terminal row. */
+    /** 0-based terminal row. */
     y: number;
     /** Button press (not motion, not release). */
     press: boolean;

package/dist/src/pane/mouse.js

@@ -1,12 +1,11 @@
 /**
  * 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.
+ * In fullscreen TUI mode Pi defers wheel input to a focused overlay. Pi 0.84
+ * still consumes non-wheel SGR mouse events before the overlay sees them, so
+ * click and drag paths require a host that forwards those events. These helpers
+ * turn forwarded sequences into structured events. Regular TUI mode remains
+ * keyboard-only 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. */
@@ -15,8 +14,8 @@ export function parseSgrMouseEvent(data) {
     if (!match)
         return undefined;
     const cb = Number(match[1]);
-    const x = Number(match[2]);
-    const y = Number(match[3]);
+    const x = Number(match[2]) - 1;
+    const y = Number(match[3]) - 1;
     const isRelease = match[4] === "m";
     const motion = (cb & 32) !== 0 && !isRelease;
     const wheel = (cb & 64) !== 0;

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

@@ -26,6 +26,8 @@ export interface PaneOverlaySeparatorRow {
 export type PaneOverlayPrimaryRow<Row = unknown> = Row | PaneOverlaySeparatorRow;
 export interface PaneOverlayTitle {
     label: string;
+    labelRendered?: string;
+    labelPlain?: string;
     tail?: string;
     tailRendered?: string;
     tailPlain?: string;
@@ -72,6 +74,10 @@ export interface PaneOverlaySplitOptions {
 export interface PaneCollapseOptions {
     key?: string;
     collapsedWidth?: number;
+    /** Use Left/Right to move the primary cursor while the collapsed detail pane stays focused. */
+    horizontalPrimaryNavigation?: boolean;
+    /** Collapsed-footer label for Left/Right navigation (default: "navigate"). */
+    horizontalPrimaryNavigationLabel?: string;
     /**
      * Legend/divider label for the collapse toggle. A function receives the
      * current collapsed state so the hint can read e.g. "hide sidebar" when open

package/dist/src/pane/overlay.js

@@ -60,6 +60,8 @@ function titleOptions(title, focused) {
     if (typeof title === "object" && title !== null) {
         return {
             label: title.label,
+            labelRendered: title.labelRendered,
+            labelPlain: title.labelPlain,
             tail: title.tail,
             tailRendered: title.tailRendered,
             tailPlain: title.tailPlain,
@@ -101,12 +103,54 @@ export function paneOverlay(options) {
         let lastRenderWidth = 80;
         let lastSelectedKey;
         let initialSelectionApplied = false;
+        const primaryScrollbar = { visible: false, timer: undefined };
+        const detailScrollbar = { visible: false, timer: undefined };
         const primaryState = { cursor: 0, scrollOffset: 0 };
         const detailState = { scrollOffset: 0, sticky: stickyBottom };
         const perSelectionOffsets = new Map();
         const requestRender = () => {
             tui?.requestRender?.();
         };
+        const markScrollbarActivity = (scrollbar) => {
+            scrollbar.visible = true;
+            if (scrollbar.timer)
+                clearTimeout(scrollbar.timer);
+            scrollbar.timer = setTimeout(() => {
+                scrollbar.timer = undefined;
+                scrollbar.visible = false;
+                requestRender();
+            }, 1_000);
+            scrollbar.timer.unref?.();
+        };
+        const paintScrollbarThumb = (text, width, row, viewportHeight, contentLength, offset, visible) => {
+            const cell = padRight(clipStyled(text, width), width);
+            if (!visible || width <= 0 || viewportHeight <= 0 || contentLength <= viewportHeight)
+                return cell;
+            const thumbHeight = Math.max(Math.min(2, viewportHeight), Math.min(viewportHeight, Math.round((viewportHeight * viewportHeight) / contentLength)));
+            const maxOffset = Math.max(0, contentLength - viewportHeight);
+            const maxThumbTop = viewportHeight - thumbHeight;
+            const thumbTop = maxOffset === 0 ? 0 : Math.round((offset / maxOffset) * maxThumbTop);
+            if (row < thumbTop || row >= thumbTop + thumbHeight)
+                return cell;
+            const prefix = padRight(clipStyled(cell, width - 1), width - 1);
+            let thumb;
+            try {
+                thumb = chromeTheme.bg?.("scrollbarThumb", " ");
+            }
+            catch {
+                // Older Pi themes expose selectedBg but not scrollbarThumb.
+            }
+            if (thumb === undefined) {
+                try {
+                    thumb = chromeTheme.bg?.("selectedBg", " ");
+                }
+                catch {
+                    // Minimal structural themes may not support background roles.
+                }
+            }
+            thumb ??= chromeTheme.fg("dim", "▐");
+            return prefix + thumb;
+        };
         const finish = (result) => {
             if (finished)
                 return;
@@ -263,7 +307,12 @@ export function paneOverlay(options) {
         };
         const applyPrimaryNav = (bodyHeight, legendLineCount, mutator) => {
             const { primaryRows, viewportHeight } = withPrimaryViewport(bodyHeight, legendLineCount);
+            const previousCursor = primaryState.cursor;
+            const previousOffset = primaryState.scrollOffset;
             mutator(primaryState, primaryRows, viewportHeight);
+            if (primaryState.cursor !== previousCursor || primaryState.scrollOffset !== previousOffset) {
+                markScrollbarActivity(primaryScrollbar);
+            }
         };
         const movePrimary = (delta, bodyHeight, legendLineCount) => {
             applyPrimaryNav(bodyHeight, legendLineCount, (state, rows, viewportHeight) => {
@@ -330,12 +379,26 @@ export function paneOverlay(options) {
                 }
             });
         };
-        const markDetailManual = () => {
-            detailState.sticky = false;
+        const setDetailOffset = (offset, contentLength, viewportHeight) => {
+            const height = Math.max(1, viewportHeight);
+            const maxOffset = endScrollOffset(contentLength, height);
+            const previousOffset = detailState.scrollOffset;
+            detailState.scrollOffset = Math.max(0, Math.min(offset, maxOffset));
+            detailState.sticky = stickyBottom && detailState.scrollOffset === maxOffset;
+            if (detailState.scrollOffset !== previousOffset)
+                markScrollbarActivity(detailScrollbar);
             if (perSelectionScroll && lastSelectedKey !== undefined) {
-                getDetailStateForKey(lastSelectedKey).sticky = false;
+                const state = getDetailStateForKey(lastSelectedKey);
+                state.offset = detailState.scrollOffset;
+                state.sticky = detailState.sticky;
             }
         };
+        const moveDetail = (delta, contentLength, viewportHeight) => {
+            const previousOffset = detailState.scrollOffset;
+            const nextOffset = moveScrollOffset({ offset: previousOffset, contentLength, viewportHeight: Math.max(1, viewportHeight) }, delta);
+            setDetailOffset(nextOffset, contentLength, viewportHeight);
+            return delta - (detailState.scrollOffset - previousOffset);
+        };
         const legendEntries = (ctx) => {
             const entries = [];
             entries.push({ key: "tab/←/→", label: "focus" });
@@ -366,8 +429,8 @@ export function paneOverlay(options) {
             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
+         * Mouse support for forwarded 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
@@ -392,37 +455,20 @@ export function paneOverlay(options) {
                 : 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).
+            const inDetailColumn = event.x > primaryWidth + 1 && event.x < totalWidth - 1;
+            const inBodyRow = event.y >= 1 && event.y <= bodyHeight;
+            // Wheel: move exactly one logical row per terminal report, like TuiAltScreen.
             if (event.button === 64 || event.button === 65) {
                 if (event.y > maxRow)
                     return;
                 const direction = event.button === 64 ? -1 : 1;
-                if (inPrimaryColumn || (primaryWidth > 0 && event.x <= primaryWidth + 1)) {
-                    const lines = direction * (event.shift ? 5 : 1);
+                if (!inDetailColumn || (!inBodyRow && !collapsed)) {
                     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);
-                        }
-                    });
+                    movePrimary(direction, bodyHeight, legendLineCount);
                 }
                 else {
-                    const lines = direction * (event.shift ? 5 : 3);
                     focus = "detail";
-                    markDetailManual();
-                    detailState.scrollOffset = moveScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, lines);
+                    moveDetail(direction, detailRows.length, bodyHeight);
                 }
                 requestRender();
                 return;
@@ -496,7 +542,10 @@ export function paneOverlay(options) {
         };
         const component = {
             dispose() {
-                // no-op is acceptable
+                if (primaryScrollbar.timer)
+                    clearTimeout(primaryScrollbar.timer);
+                if (detailScrollbar.timer)
+                    clearTimeout(detailScrollbar.timer);
             },
             render(width) {
                 const totalWidth = Math.max(10, Math.floor(width));
@@ -597,8 +646,13 @@ export function paneOverlay(options) {
                 // When the primary pane is collapsed its legend (and the collapse hint with
                 // it) disappears, so the user can't see how to reopen it. Surface the
                 // reopen hint in the always-visible detail footer instead.
+                const horizontalNavigationHint = collapsed && collapse?.horizontalPrimaryNavigation
+                    ? `←/→ ${collapse.horizontalPrimaryNavigationLabel ?? "navigate"}`
+                    : "";
                 const detailFooterText = collapsed && collapse
-                    ? [`${collapseKey} ${collapseLabel("expand")}`, detailFooterBase].filter(Boolean).join(" \u00b7 ")
+                    ? [horizontalNavigationHint, `${collapseKey} ${collapseLabel("expand")}`, detailFooterBase]
+                        .filter(Boolean)
+                        .join(" \u00b7 ")
                     : detailFooterBase;
                 const bottomPrimary = titledBottomSegment(chromeTheme, primaryWidth, primaryFooterText, focus === "primary");
                 const bottomDetail = titledBottomSegment(chromeTheme, detailWidth, detailFooterText, focus === "detail");
@@ -623,7 +677,8 @@ export function paneOverlay(options) {
                         const legendIndex = row - legendStart - 1;
                         primaryCell = legendIndex < legendLines.length ? padRight(legendLines[legendIndex], primaryWidth) : "";
                     }
-                    const detailCell = detailVisible[row] ?? "";
+                    primaryCell = paintScrollbarThumb(primaryCell, primaryWidth, row, primaryHeight, primaryRows.length, primaryState.scrollOffset, primaryScrollbar.visible && !collapsed);
+                    const detailCell = paintScrollbarThumb(detailVisible[row] ?? "", detailWidth, row, detailHeight, detailRows.length, detailState.scrollOffset, detailScrollbar.visible);
                     if (primaryWidth === 0) {
                         const border = chromeTheme.fg("dim", "│");
                         bodyLines.push(border + padRight(clipStyled(detailCell, detailWidth), detailWidth) + border);
@@ -669,6 +724,11 @@ export function paneOverlay(options) {
                     requestRender();
                     return;
                 }
+                if (collapsed && collapse?.horizontalPrimaryNavigation && matchesAny(data, ["left", "right"])) {
+                    movePrimary(matchesAny(data, ["right"]) ? 1 : -1, bodyHeight, 0);
+                    requestRender();
+                    return;
+                }
                 if (matchesAny(data, ["left", "right", "tab"])) {
                     toggleFocus();
                     ensureFocusDetailWhenCollapsed();
@@ -686,8 +746,7 @@ export function paneOverlay(options) {
                             movePrimary(delta, bodyHeight, legendLineCount);
                         }
                         else {
-                            markDetailManual();
-                            detailState.scrollOffset = moveScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, delta);
+                            moveDetail(delta, detailRows.length, bodyHeight);
                         }
                     },
                     home: () => {
@@ -695,8 +754,7 @@ export function paneOverlay(options) {
                             homePrimary(bodyHeight, legendLineCount);
                         }
                         else {
-                            markDetailManual();
-                            detailState.scrollOffset = homeScrollOffset();
+                            setDetailOffset(homeScrollOffset(), detailRows.length, bodyHeight);
                         }
                     },
                     end: () => {
@@ -704,8 +762,7 @@ export function paneOverlay(options) {
                             endPrimary(bodyHeight, legendLineCount);
                         }
                         else {
-                            markDetailManual();
-                            detailState.scrollOffset = endScrollOffset(detailRows.length, Math.max(1, bodyHeight));
+                            setDetailOffset(endScrollOffset(detailRows.length, Math.max(1, bodyHeight)), detailRows.length, bodyHeight);
                         }
                     },
                 });
@@ -718,8 +775,7 @@ export function paneOverlay(options) {
                         halfPagePrimary(-1, bodyHeight, legendLineCount);
                     }
                     else {
-                        markDetailManual();
-                        detailState.scrollOffset = pageScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, -1, pageSizeHalf(bodyHeight));
+                        setDetailOffset(pageScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, -1, pageSizeHalf(bodyHeight)), detailRows.length, bodyHeight);
                     }
                     requestRender();
                     return;
@@ -729,8 +785,7 @@ export function paneOverlay(options) {
                         halfPagePrimary(1, bodyHeight, legendLineCount);
                     }
                     else {
-                        markDetailManual();
-                        detailState.scrollOffset = pageScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, 1, pageSizeHalf(bodyHeight));
+                        setDetailOffset(pageScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, 1, pageSizeHalf(bodyHeight)), detailRows.length, bodyHeight);
                     }
                     requestRender();
                     return;

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/docs/pane-overlay.md

@@ -63,7 +63,7 @@ await client.ui.fullscreen(
 | `legendPlacement` | `footer` or `primary` |
 | `customActions` | Extra keys with labels and handlers |
 | `closeKeys` | Override close keys, e.g. omit `q` |
-| `collapse` | Optional primary/sidebar collapse key |
+| `collapse` | Optional primary/sidebar collapse key; collapsed horizontal navigation can provide its own footer label |
 | `perSelectionScroll` | Keep separate detail scroll per selected key |
 | `stickyBottom` | Detail starts/follows at bottom until user scrolls |
 | `onRender` | Per-frame hook for external transient UI state |

package/package.json

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