pi-extension-utils 0.3.0 → 0.3.1

package/README.md

@@ -16,7 +16,7 @@ The host owns one real widget per placement and composes registered sub-widgets
 ## API sketch
 
 ```ts
-import { connect, createLogger } from "pi-extension-utils";
+import { connect, createLogger, paneOverlay } from "pi-extension-utils";
 
 const client = connect(pi, { ctx, clientId: "my-extension" });
 client.widgets.set("belowEditor", "status", (tui, theme) => component, { order: 10 });
@@ -28,6 +28,23 @@ const result = await client.ui.fullscreen<string | null>(
   (tui, theme, keybindings, done) => new MyOverlayComponent(tui, theme, done),
 );
 
+// Opinionated master/detail pane overlay helper with built-in key handling.
+const result = await client.ui.fullscreen(
+  paneOverlay<string, string>({
+    primary: {
+      mode: "cursor",
+      rows: ["one", "two", "three"],
+      renderRow: (row) => row,
+      onSelectionChange: (row) => console.log("selected", row),
+    },
+    detail: {
+      title: "Details",
+      rows: (ctx) => [`Selected: ${ctx.selectedRow}`],
+    },
+    legendPlacement: "footer",
+  }),
+);
+
 // Lower-level lease, for manual control over the blank/restore window.
 const lease = client.fullscreen.acquire();
 lease.release();

package/dist/src/index.d.ts

@@ -5,3 +5,4 @@ export * from "./pane-state.ts";
 export * from "./protocol.ts";
 export * from "./reminders/types.ts";
 export * from "./tui-chrome.ts";
+export * from "./pane-overlay.ts";

package/dist/src/index.js

@@ -5,3 +5,4 @@ export * from "./pane-state.js";
 export * from "./protocol.js";
 export * from "./reminders/types.js";
 export * from "./tui-chrome.js";
+export * from "./pane-overlay.js";

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

@@ -0,0 +1,75 @@
+import type { FullscreenComponentFactory } from "./client.ts";
+export interface PaneOverlayContext<T = unknown, Row = unknown> {
+    tui: unknown;
+    primaryFocus: boolean;
+    detailFocus: boolean;
+    selectedRow: Row | undefined;
+    selectedIndex: number;
+    selectedKey: string;
+    primary: {
+        mode: "cursor" | "scroll";
+        cursor: number;
+        scrollOffset: number;
+    };
+    detail: {
+        scrollOffset: number;
+    };
+    close(result?: T): void;
+    requestRender(): void;
+}
+export interface PaneOverlayCustomAction<T = unknown, Row = unknown> {
+    keys: string | readonly string[];
+    label: string;
+    run(ctx: PaneOverlayContext<T, Row>): void;
+    when?(ctx: PaneOverlayContext<T, Row>): boolean;
+    showInLegend?: boolean;
+}
+export interface PrimaryPaneOptions<Row = unknown> {
+    mode?: "cursor" | "scroll";
+    rows: Row[] | ((ctx: PaneOverlayContext<unknown, Row>) => Row[]);
+    renderRow?(row: Row, ctx: PaneOverlayContext<unknown, Row>): string;
+    selectionKey?(row: Row, index: number): string;
+    onSelectionChange?(row: Row | undefined, index: number, key: string, ctx: PaneOverlayContext<unknown, Row>): void;
+    title?: string | ((ctx: PaneOverlayContext<unknown, Row>) => string);
+    footer?: string | ((ctx: PaneOverlayContext<unknown, Row>) => string);
+}
+export interface DetailPaneOptions<Row = unknown> {
+    rows(ctx: PaneOverlayContext<unknown, Row>): string[];
+    title?: string | ((ctx: PaneOverlayContext<unknown, Row>) => string);
+    footer?: string | ((ctx: PaneOverlayContext<unknown, Row>) => string);
+}
+export interface PaneOverlaySplitOptions {
+    initialFraction?: number;
+    minPrimaryWidth?: number;
+    minDetailWidth?: number;
+    maxPrimaryWidth?: number;
+    stepCols?: number;
+    minFraction?: number;
+    maxFraction?: number;
+    fractionBasis?: "total" | "interior";
+}
+export interface PaneCollapseOptions {
+    key?: string;
+    collapsedWidth?: number;
+    label?: string;
+}
+export interface PaneOverlayOptions<T = unknown, Row = unknown> {
+    primary: PrimaryPaneOptions<Row>;
+    detail: DetailPaneOptions<Row>;
+    height?: number | ((tui: unknown) => number);
+    closeKeys?: readonly string[];
+    closeResult?: T;
+    customActions?: readonly PaneOverlayCustomAction<T, Row>[];
+    bannedKeys?: readonly string[];
+    split?: PaneOverlaySplitOptions;
+    legendPlacement?: "footer" | "primary";
+    collapse?: PaneCollapseOptions;
+    perSelectionScroll?: boolean;
+    stickyBottom?: boolean;
+}
+export interface PaneOverlayComponent {
+    render(width: number): string[];
+    handleInput(data: string): void;
+    dispose(): void;
+}
+export declare function paneOverlay<T = undefined, Row = unknown>(options: PaneOverlayOptions<T, Row>): FullscreenComponentFactory<T>;

package/dist/src/pane-overlay.js

@@ -0,0 +1,492 @@
+import { dispatchNavKeys } from "./key-dispatch.js";
+import { computeFixedSidebarLayout, computeSplitPaneLayout, endCursor, endScrollOffset, ensureCursorVisible, homeCursor, homeScrollOffset, moveCursor, moveScrollOffset, pageCursor, pageScrollOffset, resizeSplitPane, } from "./pane-state.js";
+import { boxRow, clipStyled, flatRule, formatScrollInfo, padRight, renderKeyRow, titledBottomSegment, titledTopSegment, } from "./tui-chrome.js";
+import { matchesKey } from "@earendil-works/pi-tui";
+const DEFAULT_CLOSE_KEYS = ["escape", "ctrl+c", "q"];
+function resolveValue(value, ctx) {
+    return typeof value === "function" ? value(ctx) : value;
+}
+function computeBodyHeight(tui, height) {
+    if (typeof height === "number")
+        return Math.max(1, height);
+    if (typeof height === "function")
+        return Math.max(1, height(tui));
+    const rows = tui?.terminal?.rows;
+    if (typeof rows === "number")
+        return Math.max(8, rows - 2);
+    return 16;
+}
+function matchesAny(data, binding) {
+    if (!binding)
+        return false;
+    const keys = typeof binding === "string" ? [binding] : binding;
+    return keys.some((key) => data === key || matchesKey(data, key));
+}
+function defaultRenderRow(row) {
+    return typeof row === "string" ? row : String(row);
+}
+function decorateRow(text, theme) {
+    return theme.bold ? theme.bold(theme.fg("accent", text)) : theme.fg("accent", text);
+}
+export function paneOverlay(options) {
+    const split = options.split ?? {};
+    const closeKeys = options.closeKeys ?? DEFAULT_CLOSE_KEYS;
+    const customActions = options.customActions ?? [];
+    const bannedKeys = options.bannedKeys ?? [];
+    const legendPlacement = options.legendPlacement ?? "footer";
+    const perSelectionScroll = options.perSelectionScroll ?? false;
+    const stickyBottom = options.stickyBottom ?? false;
+    const collapse = options.collapse;
+    const collapseKey = collapse?.key ?? "c";
+    const collapsedWidth = collapse?.collapsedWidth ?? 1;
+    return (tui, theme, _keybindings, done) => {
+        const chromeTheme = theme;
+        let finished = false;
+        let focus = "primary";
+        let collapsed = false;
+        let leftFraction = split.initialFraction ?? 0.5;
+        let lastRenderWidth = 80;
+        let lastSelectedKey;
+        const primaryState = { cursor: 0, scrollOffset: 0 };
+        const detailState = { scrollOffset: 0, sticky: stickyBottom };
+        const perSelectionOffsets = new Map();
+        const requestRender = () => {
+            tui?.requestRender?.();
+        };
+        const finish = (result) => {
+            if (finished)
+                return;
+            finished = true;
+            done(result);
+        };
+        const makeContext = (selectedIndex, selectedRow, selectedKey, primaryRows, detailRows) => ({
+            tui,
+            primaryFocus: focus === "primary",
+            detailFocus: focus === "detail",
+            selectedRow,
+            selectedIndex,
+            selectedKey,
+            primary: {
+                mode: options.primary.mode ?? "scroll",
+                cursor: primaryState.cursor,
+                scrollOffset: primaryState.scrollOffset,
+            },
+            detail: { scrollOffset: detailState.scrollOffset },
+            close: (result) => finish(result),
+            requestRender,
+        });
+        const getLayout = (totalWidth) => {
+            if (collapsed) {
+                return computeFixedSidebarLayout({
+                    totalWidth,
+                    collapsed: true,
+                    leftWidth: collapsedWidth,
+                    collapsedLeftWidth: collapsedWidth,
+                    minLeftWidth: split.minPrimaryWidth ?? 0,
+                    minRightWidth: split.minDetailWidth ?? 8,
+                });
+            }
+            return computeSplitPaneLayout({
+                totalWidth,
+                leftFraction,
+                minLeftWidth: split.minPrimaryWidth ?? 8,
+                minRightWidth: split.minDetailWidth ?? 8,
+                leftMaxWidth: split.maxPrimaryWidth,
+                minFraction: split.minFraction,
+                maxFraction: split.maxFraction,
+                fractionBasis: split.fractionBasis,
+            });
+        };
+        const resize = (direction) => {
+            if (collapsed)
+                return;
+            const next = resizeSplitPane({
+                totalWidth: lastRenderWidth,
+                leftFraction,
+                direction,
+                stepCols: split.stepCols ?? 4,
+                minLeftWidth: split.minPrimaryWidth ?? 8,
+                minRightWidth: split.minDetailWidth ?? 8,
+                leftMaxWidth: split.maxPrimaryWidth,
+                minFraction: split.minFraction,
+                maxFraction: split.maxFraction,
+                fractionBasis: split.fractionBasis,
+            });
+            leftFraction = next.leftFraction;
+        };
+        const toggleFocus = () => {
+            focus = focus === "primary" ? "detail" : "primary";
+        };
+        const ensureFocusDetailWhenCollapsed = () => {
+            if (collapsed)
+                focus = "detail";
+        };
+        const getDetailStateForKey = (key) => {
+            let state = perSelectionOffsets.get(key);
+            if (!state) {
+                state = { offset: 0, sticky: stickyBottom };
+                perSelectionOffsets.set(key, state);
+            }
+            return state;
+        };
+        const listViewport = (bodyHeight, legendLineCount) => {
+            const primaryHeight = legendPlacement === "primary"
+                ? Math.max(0, bodyHeight - legendLineCount - 1)
+                : bodyHeight;
+            return { primaryHeight, detailHeight: bodyHeight };
+        };
+        const pageSizeHalf = (height) => Math.max(1, Math.floor(height / 2));
+        const withPrimaryViewport = (bodyHeight, legendLineCount) => {
+            const primaryRows = resolveValue(options.primary.rows, makeContext(0, undefined, "", [], []));
+            const viewportHeight = listViewport(bodyHeight, legendLineCount).primaryHeight;
+            return { primaryRows, viewportHeight: Math.max(1, viewportHeight) };
+        };
+        const applyPrimaryNav = (bodyHeight, legendLineCount, mutator) => {
+            const { primaryRows, viewportHeight } = withPrimaryViewport(bodyHeight, legendLineCount);
+            mutator(primaryState, primaryRows, viewportHeight);
+        };
+        const movePrimary = (delta, bodyHeight, legendLineCount) => {
+            applyPrimaryNav(bodyHeight, legendLineCount, (state, rows, viewportHeight) => {
+                if ((options.primary.mode ?? "scroll") === "cursor") {
+                    const next = moveCursor({ cursor: state.cursor, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight }, delta);
+                    state.cursor = next.cursor;
+                    state.scrollOffset = next.scroll;
+                }
+                else {
+                    state.scrollOffset = moveScrollOffset({ offset: state.scrollOffset, contentLength: rows.length, viewportHeight }, delta);
+                }
+            });
+        };
+        const halfPagePrimary = (delta, bodyHeight, legendLineCount) => {
+            applyPrimaryNav(bodyHeight, legendLineCount, (state, rows, viewportHeight) => {
+                const pageSize = pageSizeHalf(viewportHeight);
+                if ((options.primary.mode ?? "scroll") === "cursor") {
+                    const next = pageCursor({ cursor: state.cursor, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight }, delta, pageSize);
+                    state.cursor = next.cursor;
+                    state.scrollOffset = next.scroll;
+                }
+                else {
+                    state.scrollOffset = pageScrollOffset({ offset: state.scrollOffset, contentLength: rows.length, viewportHeight }, delta, pageSize);
+                }
+            });
+        };
+        const homePrimary = (bodyHeight, legendLineCount) => {
+            applyPrimaryNav(bodyHeight, legendLineCount, (state, rows, viewportHeight) => {
+                if ((options.primary.mode ?? "scroll") === "cursor") {
+                    const next = homeCursor({ cursor: state.cursor, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight });
+                    state.cursor = next.cursor;
+                    state.scrollOffset = next.scroll;
+                }
+                else {
+                    state.scrollOffset = homeScrollOffset();
+                }
+            });
+        };
+        const endPrimary = (bodyHeight, legendLineCount) => {
+            applyPrimaryNav(bodyHeight, legendLineCount, (state, rows, viewportHeight) => {
+                if ((options.primary.mode ?? "scroll") === "cursor") {
+                    const next = endCursor({ cursor: state.cursor, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight });
+                    state.cursor = next.cursor;
+                    state.scrollOffset = next.scroll;
+                }
+                else {
+                    state.scrollOffset = endScrollOffset(rows.length, viewportHeight);
+                }
+            });
+        };
+        const markDetailManual = () => {
+            detailState.sticky = false;
+            if (perSelectionScroll && lastSelectedKey !== undefined) {
+                getDetailStateForKey(lastSelectedKey).sticky = false;
+            }
+        };
+        const legendEntries = (ctx) => {
+            const entries = [];
+            entries.push({ key: "tab/←/→", label: "focus" });
+            const primaryMode = options.primary.mode ?? "scroll";
+            const moveLabel = ctx.detailFocus || primaryMode === "scroll" ? "scroll" : "select";
+            entries.push({ key: "j/k", label: moveLabel });
+            entries.push({ key: "u/d", label: "half-page" });
+            entries.push({ key: "g/G", label: "top/bottom" });
+            if (!collapsed)
+                entries.push({ key: "[/]", label: "resize" });
+            if (collapse)
+                entries.push({ key: collapseKey, label: collapse.label ?? "collapse" });
+            for (const action of customActions) {
+                if (action.showInLegend === false)
+                    continue;
+                if (action.when && !action.when(ctx))
+                    continue;
+                entries.push({ key: typeof action.keys === "string" ? action.keys : action.keys.join("/"), label: action.label });
+            }
+            const qCloses = closeKeys.includes("q");
+            entries.push({ key: qCloses ? "q/esc" : "esc", label: "close" });
+            return entries;
+        };
+        const renderLegendLines = (entries, totalWidth) => {
+            if (entries.length === 0 || totalWidth <= 0)
+                return [];
+            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)));
+        };
+        const computeSelection = (bodyHeight) => {
+            const provisionalCtx = makeContext(0, undefined, "", [], []);
+            const primaryRows = resolveValue(options.primary.rows, provisionalCtx);
+            const primaryMode = options.primary.mode ?? "scroll";
+            let selectedIndex = 0;
+            if (primaryMode === "cursor") {
+                selectedIndex = ensureCursorVisible({
+                    cursor: primaryState.cursor,
+                    scroll: primaryState.scrollOffset,
+                    itemCount: primaryRows.length,
+                    viewportHeight: Math.max(1, bodyHeight),
+                }).cursor;
+            }
+            else {
+                selectedIndex = Math.min(primaryState.scrollOffset, Math.max(0, primaryRows.length - 1));
+            }
+            if (primaryRows.length === 0)
+                selectedIndex = 0;
+            const selectedRow = primaryRows[selectedIndex];
+            const selectionKeyFn = options.primary.selectionKey ?? ((_row, index) => String(index));
+            const selectedKey = selectedRow !== undefined ? selectionKeyFn(selectedRow, selectedIndex) : String(selectedIndex);
+            return { primaryRows, selectedIndex, selectedRow, selectedKey };
+        };
+        const component = {
+            dispose() {
+                // no-op is acceptable
+            },
+            render(width) {
+                const totalWidth = Math.max(10, Math.floor(width));
+                lastRenderWidth = totalWidth;
+                const bodyHeight = computeBodyHeight(tui, options.height);
+                const layout = getLayout(totalWidth);
+                const primaryWidth = layout.leftWidth;
+                const detailWidth = layout.rightWidth;
+                const { primaryRows, selectedIndex, selectedRow, selectedKey } = computeSelection(bodyHeight);
+                const detailRows = resolveValue(options.detail.rows, makeContext(selectedIndex, selectedRow, selectedKey, primaryRows, []));
+                const ctx = makeContext(selectedIndex, selectedRow, selectedKey, primaryRows, detailRows);
+                if (selectedKey !== lastSelectedKey) {
+                    lastSelectedKey = selectedKey;
+                    if (options.primary.onSelectionChange) {
+                        options.primary.onSelectionChange(selectedRow, selectedIndex, selectedKey, ctx);
+                    }
+                    if (perSelectionScroll) {
+                        const state = getDetailStateForKey(selectedKey);
+                        detailState.scrollOffset = state.offset;
+                        detailState.sticky = state.sticky;
+                    }
+                    else if (stickyBottom) {
+                        detailState.sticky = true;
+                    }
+                }
+                ensureFocusDetailWhenCollapsed();
+                const entries = legendEntries(ctx);
+                const legendLines = renderLegendLines(entries, totalWidth);
+                const { primaryHeight, detailHeight } = listViewport(bodyHeight, legendLines.length);
+                // Align primary viewport.
+                if ((options.primary.mode ?? "scroll") === "cursor") {
+                    const viewport = ensureCursorVisible({
+                        cursor: primaryState.cursor,
+                        scroll: primaryState.scrollOffset,
+                        itemCount: primaryRows.length,
+                        viewportHeight: Math.max(1, primaryHeight),
+                    });
+                    primaryState.cursor = viewport.cursor;
+                    primaryState.scrollOffset = viewport.scroll;
+                }
+                else {
+                    primaryState.scrollOffset = Math.max(0, Math.min(primaryState.scrollOffset, Math.max(0, primaryRows.length - primaryHeight)));
+                }
+                // Align detail viewport.
+                const detailMaxOffset = Math.max(0, detailRows.length - detailHeight);
+                if (stickyBottom && detailState.sticky) {
+                    detailState.scrollOffset = detailMaxOffset;
+                }
+                else {
+                    detailState.scrollOffset = Math.max(0, Math.min(detailState.scrollOffset, detailMaxOffset));
+                }
+                if (perSelectionScroll) {
+                    const state = getDetailStateForKey(selectedKey);
+                    state.offset = detailState.scrollOffset;
+                    state.sticky = detailState.sticky;
+                }
+                const primaryTitle = resolveValue(options.primary.title, ctx);
+                const detailTitle = resolveValue(options.detail.title, ctx);
+                const topPrimary = titledTopSegment(chromeTheme, {
+                    width: primaryWidth,
+                    label: primaryTitle ?? "",
+                    labelColor: focus === "primary" ? "accent" : "text",
+                    labelBold: focus === "primary",
+                });
+                const topDetail = titledTopSegment(chromeTheme, {
+                    width: detailWidth,
+                    label: detailTitle ?? "",
+                    labelColor: focus === "detail" ? "accent" : "text",
+                    labelBold: focus === "detail",
+                });
+                const corner = (glyph) => chromeTheme.fg("dim", glyph);
+                const topBorder = primaryWidth === 0
+                    ? corner("╭") + topDetail + corner("╮")
+                    : corner("╭") + topPrimary + corner("┬") + topDetail + corner("╮");
+                const renderFn = options.primary.renderRow ?? defaultRenderRow;
+                const primaryVisible = primaryRows
+                    .slice(primaryState.scrollOffset, primaryState.scrollOffset + primaryHeight)
+                    .map((row, index) => {
+                    const absoluteIndex = primaryState.scrollOffset + index;
+                    const text = renderFn(row, ctx);
+                    const selected = (options.primary.mode ?? "scroll") === "cursor" && absoluteIndex === primaryState.cursor && focus === "primary";
+                    return selected ? decorateRow(text, chromeTheme) : text;
+                });
+                const detailVisible = detailRows.slice(detailState.scrollOffset, detailState.scrollOffset + detailHeight);
+                const primaryFooterText = resolveValue(options.primary.footer, ctx)
+                    ?? ((options.primary.mode ?? "scroll") === "cursor" && primaryRows.length > 0
+                        ? `${primaryState.cursor + 1}/${primaryRows.length}`
+                        : primaryRows.length > primaryHeight
+                            ? formatScrollInfo(primaryState.scrollOffset, Math.max(0, primaryRows.length - primaryHeight), { style: "position" })
+                            : "");
+                const detailFooterText = resolveValue(options.detail.footer, ctx)
+                    ?? (detailRows.length > detailHeight
+                        ? formatScrollInfo(detailState.scrollOffset, Math.max(0, detailRows.length - detailHeight), { style: "position" })
+                        : "");
+                const bottomPrimary = titledBottomSegment(chromeTheme, primaryWidth, primaryFooterText, focus === "primary");
+                const bottomDetail = titledBottomSegment(chromeTheme, detailWidth, detailFooterText, focus === "detail");
+                const bottomBorder = primaryWidth === 0
+                    ? corner("╰") + bottomDetail + corner("╯")
+                    : corner("╰") + bottomPrimary + corner("┴") + bottomDetail + corner("╯");
+                const bodyLines = [];
+                for (let row = 0; row < bodyHeight; row++) {
+                    let primaryCell = primaryVisible[row] ?? "";
+                    if (legendPlacement === "primary" && row === primaryHeight && legendLines.length > 0) {
+                        primaryCell = flatRule(chromeTheme, collapse?.label ?? "actions", primaryWidth);
+                    }
+                    if (legendPlacement === "primary" && row > primaryHeight) {
+                        const legendIndex = row - primaryHeight - 1;
+                        primaryCell = legendIndex < legendLines.length ? padRight(legendLines[legendIndex], primaryWidth) : "";
+                    }
+                    const detailCell = detailVisible[row] ?? "";
+                    if (primaryWidth === 0) {
+                        const border = chromeTheme.fg("dim", "│");
+                        bodyLines.push(border + padRight(clipStyled(detailCell, detailWidth), detailWidth) + border);
+                    }
+                    else {
+                        bodyLines.push(boxRow(chromeTheme, primaryCell, detailCell, primaryWidth, detailWidth));
+                    }
+                }
+                const lines = [topBorder, ...bodyLines, bottomBorder];
+                if (legendPlacement === "footer") {
+                    lines.push(...legendLines);
+                }
+                return lines.map((line) => padRight(line, totalWidth));
+            },
+            handleInput(data) {
+                if (finished)
+                    return;
+                const bodyHeight = computeBodyHeight(tui, options.height);
+                if (matchesAny(data, closeKeys)) {
+                    finish(options.closeResult);
+                    return;
+                }
+                const { primaryRows, selectedIndex, selectedRow, selectedKey } = computeSelection(bodyHeight);
+                const detailRows = resolveValue(options.detail.rows, makeContext(selectedIndex, selectedRow, selectedKey, primaryRows, []));
+                const ctx = makeContext(selectedIndex, selectedRow, selectedKey, primaryRows, detailRows);
+                for (const action of customActions) {
+                    if (action.when && !action.when(ctx))
+                        continue;
+                    if (matchesAny(data, action.keys)) {
+                        action.run(ctx);
+                        requestRender();
+                        return;
+                    }
+                }
+                if (matchesAny(data, bannedKeys)) {
+                    requestRender();
+                    return;
+                }
+                if (matchesAny(data, ["left", "right", "tab"])) {
+                    toggleFocus();
+                    ensureFocusDetailWhenCollapsed();
+                    requestRender();
+                    return;
+                }
+                const legendLineCount = legendPlacement === "primary" ? renderLegendLines(legendEntries(ctx), lastRenderWidth).length : 0;
+                if (matchesAny(data, ["pageUp", "pageDown"]))
+                    return;
+                const commonConsumed = dispatchNavKeys(data, {
+                    close: () => undefined,
+                    closeKeys: [],
+                    move: (delta) => {
+                        if (focus === "primary") {
+                            movePrimary(delta, bodyHeight, legendLineCount);
+                        }
+                        else {
+                            markDetailManual();
+                            detailState.scrollOffset = moveScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, delta);
+                        }
+                    },
+                    home: () => {
+                        if (focus === "primary") {
+                            homePrimary(bodyHeight, legendLineCount);
+                        }
+                        else {
+                            markDetailManual();
+                            detailState.scrollOffset = homeScrollOffset();
+                        }
+                    },
+                    end: () => {
+                        if (focus === "primary") {
+                            endPrimary(bodyHeight, legendLineCount);
+                        }
+                        else {
+                            markDetailManual();
+                            detailState.scrollOffset = endScrollOffset(detailRows.length, Math.max(1, bodyHeight));
+                        }
+                    },
+                });
+                if (commonConsumed) {
+                    requestRender();
+                    return;
+                }
+                if (matchesAny(data, ["u", "U"])) {
+                    if (focus === "primary") {
+                        halfPagePrimary(-1, bodyHeight, legendLineCount);
+                    }
+                    else {
+                        markDetailManual();
+                        detailState.scrollOffset = pageScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, -1, pageSizeHalf(bodyHeight));
+                    }
+                    requestRender();
+                    return;
+                }
+                if (matchesAny(data, ["d", "D"])) {
+                    if (focus === "primary") {
+                        halfPagePrimary(1, bodyHeight, legendLineCount);
+                    }
+                    else {
+                        markDetailManual();
+                        detailState.scrollOffset = pageScrollOffset({ offset: detailState.scrollOffset, contentLength: detailRows.length, viewportHeight: Math.max(1, bodyHeight) }, 1, pageSizeHalf(bodyHeight));
+                    }
+                    requestRender();
+                    return;
+                }
+                if (collapse && matchesAny(data, [collapseKey])) {
+                    collapsed = !collapsed;
+                    ensureFocusDetailWhenCollapsed();
+                    requestRender();
+                    return;
+                }
+                if (!collapsed && matchesAny(data, ["["])) {
+                    resize(-1);
+                    requestRender();
+                    return;
+                }
+                if (!collapsed && matchesAny(data, ["]"])) {
+                    resize(1);
+                    requestRender();
+                    return;
+                }
+            },
+        };
+        return component;
+    };
+}

package/dist/src/tui-chrome.js

@@ -113,28 +113,37 @@ export function titledTopSegment(theme, opts) {
         const fillDashes = Math.max(1, width - labelLen - 3);
         return clipStyled(`${dash(1)} ${labelStyled} ${dash(fillDashes)}`, width);
     }
+    const width = Math.max(0, opts.width);
+    if (width <= 0)
+        return "";
     const labelColor = opts.labelColor ?? "text";
     const tailColor = opts.tailColor ?? "dim";
-    // Reserve at least `─ ` + label + ` ─` (4 chars) and 1 dash on each side of the tail when present.
-    const labelBudget = opts.width <= 4 ? 0 : opts.width - 4;
+    const tailPlain = opts.tailPlain ?? opts.tail ?? "";
+    const rawTailRendered = opts.tailRendered ?? (opts.tail !== undefined ? theme.fg(tailColor, opts.tail) : "");
+    const tailLen = visibleWidth(tailPlain);
+    // With a tail, the minimum chrome is:
+    // `─ ` + label + ` ` + `─` + ` ` + tail + ` ` + `─` = label + tail + 7.
+    // The previous math reserved only 6 columns, so long label+tail combinations
+    // could render one column too wide and crash Pi's TUI at terminal width.
+    const tailFits = tailLen > 0 && width >= tailLen + 7;
+    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 labelText = truncateToWidth(opts.label ?? "", labelBudget);
+    const rawLabel = 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 tailPlain = opts.tailPlain ?? opts.tail ?? "";
-    const tailRendered = opts.tailRendered ?? (opts.tail !== undefined ? theme.fg(tailColor, opts.tail) : "");
     const labelLen = visibleWidth(labelText);
-    const tailLen = visibleWidth(tailPlain);
-    // Layout with tail: `─ <label> ──…── <tail> ─` => fixed = 6 + labelLen + tailLen.
-    // Layout without tail: `─ <label> ──…────`     => fixed = 3 + labelLen (one space + label + space).
-    if (tailLen > 0) {
-        const fillDashes = Math.max(1, opts.width - (labelLen + tailLen + 6));
-        return `${dash(1)} ${labelStyled} ${dash(fillDashes)} ${tailRendered} ${dash(1)}`;
+    // Layout with tail: `─ <label> ──…── <tail> ─`.
+    // Layout without tail: `─ <label> ──…────`.
+    if (tailFits) {
+        const tailRendered = visibleWidth(rawTailRendered) > tailLen ? clipStyled(rawTailRendered, tailLen) : rawTailRendered;
+        const fillDashes = Math.max(1, width - (labelLen + tailLen + 6));
+        return clipStyled(`${dash(1)} ${labelStyled} ${dash(fillDashes)} ${tailRendered} ${dash(1)}`, width);
     }
-    const fillDashes = Math.max(1, opts.width - (labelLen + 3));
-    return `${dash(1)} ${labelStyled} ${dash(fillDashes)}`;
+    const fillDashes = Math.max(0, width - (labelLen + 3));
+    return clipStyled(`${dash(1)} ${labelStyled} ${dash(fillDashes)}`, width);
 }
 /**
  * Build one half of a bottom border with an embedded hint string.

package/package.json

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