pi-extension-utils 0.2.1 → 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

@@ -1,4 +1,8 @@
 export { connect, type FullscreenLease, type RemindersClient, type UtilsClient, type UtilsClientOptions, type WidgetSetOptions } from "./client.ts";
 export { createLogger, type Logger, type LoggerOptions } from "./logger.ts";
+export * from "./key-dispatch.ts";
+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

@@ -1,4 +1,8 @@
 export { connect } from "./client.js";
 export { createLogger } from "./logger.js";
+export * from "./key-dispatch.js";
+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/key-dispatch.d.ts

@@ -0,0 +1,21 @@
+export type KeyBinding = string | readonly string[];
+export interface ExtraKeyBinding {
+    keys: KeyBinding;
+    handler: () => void;
+}
+export interface NavKeyHandlers {
+    close?: () => void;
+    focusToggle?: () => void;
+    move?: (delta: 1 | -1) => void;
+    page?: (delta: 1 | -1) => void;
+    home?: () => void;
+    end?: () => void;
+    /** Defaults to escape + ctrl+c. Add "q" for dashboard-style close. */
+    closeKeys?: readonly string[];
+    /** Keys consumed without invoking a handler. */
+    bannedKeys?: readonly string[];
+    /** Consumer-specific bindings checked after close keys and before banned/common nav keys. */
+    extraBindings?: readonly ExtraKeyBinding[];
+}
+/** Dispatch common fullscreen navigation keys using pi-tui `matchesKey` semantics. */
+export declare function dispatchNavKeys(data: string, handlers: NavKeyHandlers): boolean;

package/dist/src/key-dispatch.js

@@ -0,0 +1,50 @@
+import { matchesKey } from "@earendil-works/pi-tui";
+const DEFAULT_CLOSE_KEYS = ["escape", "ctrl+c"];
+/** Dispatch common fullscreen navigation keys using pi-tui `matchesKey` semantics. */
+export function dispatchNavKeys(data, handlers) {
+    if (matchesAny(data, handlers.closeKeys ?? DEFAULT_CLOSE_KEYS)) {
+        handlers.close?.();
+        return true;
+    }
+    for (const binding of handlers.extraBindings ?? []) {
+        if (matchesAny(data, binding.keys)) {
+            binding.handler();
+            return true;
+        }
+    }
+    if (matchesAny(data, handlers.bannedKeys ?? []))
+        return true;
+    if (matchesAny(data, ["tab"])) {
+        handlers.focusToggle?.();
+        return true;
+    }
+    if (matchesAny(data, ["j", "down"])) {
+        handlers.move?.(1);
+        return true;
+    }
+    if (matchesAny(data, ["k", "up"])) {
+        handlers.move?.(-1);
+        return true;
+    }
+    if (matchesAny(data, ["pageDown"])) {
+        handlers.page?.(1);
+        return true;
+    }
+    if (matchesAny(data, ["pageUp"])) {
+        handlers.page?.(-1);
+        return true;
+    }
+    if (matchesAny(data, ["home", "g"])) {
+        handlers.home?.();
+        return true;
+    }
+    if (matchesAny(data, ["end", "shift+g"])) {
+        handlers.end?.();
+        return true;
+    }
+    return false;
+}
+function matchesAny(data, binding) {
+    const keys = typeof binding === "string" ? [binding] : binding;
+    return keys.some((key) => data === key || matchesKey(data, key));
+}

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/pane-state.d.ts

@@ -0,0 +1,71 @@
+export type PaneFocus = "left" | "right";
+export type PaneDirection = -1 | 1;
+export interface SplitPaneLayoutOptions {
+    totalWidth: number;
+    leftFraction: number;
+    minLeftWidth: number;
+    minRightWidth: number;
+    leftMaxWidth?: number;
+    separatorWidth?: number;
+    minFraction?: number;
+    maxFraction?: number;
+    /** Use "total" for the subagents dashboard math, "interior" for picker-style split math. */
+    fractionBasis?: "total" | "interior";
+}
+export interface SplitPaneLayout {
+    leftWidth: number;
+    rightWidth: number;
+    interiorWidth: number;
+    leftFraction: number;
+}
+export interface ResizeSplitPaneOptions extends SplitPaneLayoutOptions {
+    direction: PaneDirection;
+    stepCols: number;
+}
+export interface FixedSidebarLayoutOptions {
+    totalWidth: number;
+    collapsed: boolean;
+    leftWidth: number;
+    collapsedLeftWidth?: number;
+    minLeftWidth?: number;
+    minRightWidth?: number;
+    separatorWidth?: number;
+    collapsedChromeWidth?: number;
+}
+export interface FixedSidebarLayout {
+    collapsed: boolean;
+    leftWidth: number;
+    rightWidth: number;
+    interiorWidth: number;
+}
+export interface SidebarState {
+    collapsed: boolean;
+    focus: PaneFocus;
+}
+export interface ScrollViewportState {
+    offset: number;
+    contentLength: number;
+    viewportHeight: number;
+}
+export interface CursorViewportState {
+    cursor: number;
+    scroll: number;
+    itemCount: number;
+    viewportHeight: number;
+}
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function togglePaneFocus(focus: PaneFocus): PaneFocus;
+export declare function computeSplitPaneLayout(opts: SplitPaneLayoutOptions): SplitPaneLayout;
+export declare function resizeSplitPane(opts: ResizeSplitPaneOptions): SplitPaneLayout;
+export declare function computeFixedSidebarLayout(opts: FixedSidebarLayoutOptions): FixedSidebarLayout;
+export declare function toggleSidebar(state: SidebarState): SidebarState;
+export declare function clampScrollOffset(offset: number, contentLength: number, viewportHeight: number): number;
+export declare function moveScrollOffset(state: ScrollViewportState, delta: number): number;
+export declare function pageScrollOffset(state: ScrollViewportState, direction: PaneDirection, pageSize?: number): number;
+export declare function homeScrollOffset(): number;
+export declare function endScrollOffset(contentLength: number, viewportHeight: number): number;
+export declare function ensureCursorVisible(state: CursorViewportState): CursorViewportState;
+export declare function moveCursor(state: CursorViewportState, delta: number): CursorViewportState;
+export declare function pageCursor(state: CursorViewportState, direction: PaneDirection, pageSize?: number): CursorViewportState;
+export declare function homeCursor(state: CursorViewportState): CursorViewportState;
+export declare function endCursor(state: CursorViewportState): CursorViewportState;

package/dist/src/pane-state.js

@@ -0,0 +1,106 @@
+export function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+export function togglePaneFocus(focus) {
+    return focus === "left" ? "right" : "left";
+}
+export function computeSplitPaneLayout(opts) {
+    const separatorWidth = opts.separatorWidth ?? 3;
+    const interiorWidth = Math.max(0, opts.totalWidth - separatorWidth);
+    const basis = opts.fractionBasis === "interior" ? interiorWidth : opts.totalWidth;
+    const rawLeft = Math.round(Math.max(0, basis) * opts.leftFraction);
+    const capped = Math.min(opts.leftMaxWidth ?? Number.POSITIVE_INFINITY, Math.max(0, interiorWidth - opts.minRightWidth));
+    const maxLeft = capped > 0 ? capped : interiorWidth;
+    const minLeft = Math.min(opts.minLeftWidth, maxLeft);
+    const leftWidth = clamp(rawLeft, minLeft, maxLeft);
+    return {
+        leftWidth,
+        rightWidth: Math.max(0, interiorWidth - leftWidth),
+        interiorWidth,
+        leftFraction: opts.leftFraction,
+    };
+}
+export function resizeSplitPane(opts) {
+    const separatorWidth = opts.separatorWidth ?? 3;
+    const interiorWidth = Math.max(1, opts.totalWidth - separatorWidth);
+    const current = computeSplitPaneLayout(opts);
+    const basis = opts.fractionBasis === "interior" ? interiorWidth : Math.max(1, opts.totalWidth);
+    const nextFraction = opts.fractionBasis === "interior"
+        ? (current.leftWidth + opts.direction * opts.stepCols) / basis
+        : opts.leftFraction + (opts.direction * opts.stepCols) / basis;
+    const next = computeSplitPaneLayout({
+        ...opts,
+        leftFraction: clamp(nextFraction, opts.minFraction ?? 0.2, opts.maxFraction ?? 0.7),
+    });
+    return next.leftWidth === current.leftWidth ? current : next;
+}
+export function computeFixedSidebarLayout(opts) {
+    const separatorWidth = opts.separatorWidth ?? 3;
+    if (opts.collapsed) {
+        const leftWidth = Math.max(0, opts.collapsedLeftWidth ?? 0);
+        const chromeWidth = opts.collapsedChromeWidth ?? (leftWidth > 0 ? separatorWidth : 2);
+        return {
+            collapsed: true,
+            leftWidth,
+            rightWidth: Math.max(0, opts.totalWidth - chromeWidth - leftWidth),
+            interiorWidth: Math.max(0, opts.totalWidth - chromeWidth),
+        };
+    }
+    const interiorWidth = Math.max(0, opts.totalWidth - separatorWidth);
+    const minRight = opts.minRightWidth ?? 0;
+    const maxLeft = Math.max(0, interiorWidth - minRight);
+    const minLeft = Math.min(opts.minLeftWidth ?? 0, maxLeft);
+    const leftWidth = clamp(opts.leftWidth, minLeft, maxLeft || interiorWidth);
+    return {
+        collapsed: false,
+        leftWidth,
+        rightWidth: Math.max(0, interiorWidth - leftWidth),
+        interiorWidth,
+    };
+}
+export function toggleSidebar(state) {
+    const collapsed = !state.collapsed;
+    return { collapsed, focus: collapsed ? "right" : state.focus };
+}
+export function clampScrollOffset(offset, contentLength, viewportHeight) {
+    const maxOffset = Math.max(0, contentLength - Math.max(0, viewportHeight));
+    return clamp(offset, 0, maxOffset);
+}
+export function moveScrollOffset(state, delta) {
+    return clampScrollOffset(state.offset + delta, state.contentLength, state.viewportHeight);
+}
+export function pageScrollOffset(state, direction, pageSize = state.viewportHeight) {
+    return moveScrollOffset(state, direction * Math.max(1, pageSize));
+}
+export function homeScrollOffset() {
+    return 0;
+}
+export function endScrollOffset(contentLength, viewportHeight) {
+    return clampScrollOffset(Number.POSITIVE_INFINITY, contentLength, viewportHeight);
+}
+export function ensureCursorVisible(state) {
+    const itemCount = Math.max(0, state.itemCount);
+    const viewportHeight = Math.max(1, state.viewportHeight);
+    const cursor = itemCount === 0 ? 0 : clamp(state.cursor, 0, itemCount - 1);
+    let scroll = clampScrollOffset(state.scroll, itemCount, viewportHeight);
+    if (itemCount === 0)
+        return { cursor, scroll: 0, itemCount, viewportHeight };
+    if (cursor < scroll)
+        scroll = cursor;
+    else if (cursor >= scroll + viewportHeight)
+        scroll = cursor - viewportHeight + 1;
+    scroll = clampScrollOffset(scroll, itemCount, viewportHeight);
+    return { cursor, scroll, itemCount, viewportHeight };
+}
+export function moveCursor(state, delta) {
+    return ensureCursorVisible({ ...state, cursor: state.cursor + delta });
+}
+export function pageCursor(state, direction, pageSize = state.viewportHeight) {
+    return moveCursor(state, direction * Math.max(1, pageSize));
+}
+export function homeCursor(state) {
+    return ensureCursorVisible({ ...state, cursor: 0 });
+}
+export function endCursor(state) {
+    return ensureCursorVisible({ ...state, cursor: Math.max(0, state.itemCount - 1) });
+}

package/dist/src/tui-chrome.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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
+ * any pi-tui-compatible theme.
+ */
+export interface ChromeTheme {
+    fg(color: string, text: string): string;
+    bold?(text: string): string;
+}
+export declare function fuzzyFilter<T extends {
+    name: string;
+    description: string;
+    model?: string;
+}>(items: T[], query: string): T[];
+export declare function pad(s: string, len: number): string;
+export declare function row(content: string, width: number, theme: ChromeTheme): string;
+export declare function renderHeader(text: string, width: number, theme: ChromeTheme): string;
+export declare function formatPath(filePath: string): string;
+export declare function formatScrollInfo(above: number, below: number, opts?: {
+    style?: "more" | "position";
+}): string;
+export declare function renderFooter(text: string, width: number, theme: ChromeTheme): string;
+export interface TitledTopSegmentOptions {
+    width: number;
+    label: 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. */
+    tailRendered?: string;
+    /** Plain visible-width companion for `tailRendered` so dash math stays correct. */
+    tailPlain?: string;
+    labelColor?: string;
+    tailColor?: string;
+    labelBold?: boolean;
+    style?: "default" | "legacy";
+}
+/**
+ * Build one half of a top border with an embedded title and optional right-aligned tail.
+ * Layout: `─ <label> ───…─── <tail> ─` with single dashes for spacing.
+ * Returns a fragment WITHOUT corner glyphs; caller composes corners + `┬` divider.
+ */
+export declare function titledTopSegment(theme: ChromeTheme, opts: TitledTopSegmentOptions): string;
+/**
+ * Build one half of a bottom border with an embedded hint string.
+ * Layout: `─ <hint> ───…─` (no tail). Empty hint renders as a solid dash run.
+ */
+export declare function titledBottomSegment(theme: ChromeTheme, width: number, hint: string, focused: boolean): string;
+/** Pad-right to a visible width using `visibleWidth` (ANSI-aware). */
+export declare function padRight(text: string, width: number): string;
+/** Slice text by visible width and preserve ANSI color resets when present. */
+export declare function clipStyled(text: string, width: number): string;
+/** Slice text by character count (NOT visible width). For label text after `clipText` we then re-measure with visibleWidth. */
+export declare function clipText(text: string, width: number): string;
+/**
+ * Inline horizontal rule with an embedded title, NO corner/tee glyphs.
+ * Used inside a pane to subdivide sections (e.g. list / legend) without
+ * faking a second box border. Layout: `─ <title> ──…──`.
+ */
+export declare function flatRule(theme: ChromeTheme, title: string, width: number, opts?: {
+    leadingDashes?: number;
+}): string;
+/** Body row for a two-pane box. Caller supplies the left and right interior widths. */
+export declare function boxRow(theme: ChromeTheme, left: string, right: string, leftWidth: number, rightWidth: number): string;
+/** Aligned key legend row, dimmed by the caller when desired. */
+export declare function renderKeyRow(key: string, desc: string, width: number, keyWidth: number): string;

package/dist/src/tui-chrome.js

@@ -0,0 +1,227 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+function fuzzyScore(query, text) {
+    const lq = query.toLowerCase();
+    const lt = text.toLowerCase();
+    if (lt.includes(lq))
+        return 100 + (lq.length / lt.length) * 50;
+    let score = 0;
+    let qi = 0;
+    let consecutive = 0;
+    for (let i = 0; i < lt.length && qi < lq.length; i++) {
+        if (lt[i] === lq[qi]) {
+            score += 10 + consecutive;
+            consecutive += 5;
+            qi++;
+        }
+        else {
+            consecutive = 0;
+        }
+    }
+    return qi === lq.length ? score : 0;
+}
+export function fuzzyFilter(items, query) {
+    const q = query.trim();
+    if (!q)
+        return items;
+    return items
+        .map((item) => ({ item, score: Math.max(fuzzyScore(q, item.name), fuzzyScore(q, item.description) * 0.8, fuzzyScore(q, item.model ?? "") * 0.6) }))
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .map((x) => x.item);
+}
+export function pad(s, len) {
+    const vis = visibleWidth(s);
+    return s + " ".repeat(Math.max(0, len - vis));
+}
+function normalizeRenderableText(text) {
+    return text
+        .replaceAll("\t", "    ")
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001A\u001C-\u001F\u007F]/g, "");
+}
+export function row(content, width, theme) {
+    const innerW = Math.max(0, width - 2);
+    const safeContent = truncateToWidth(normalizeRenderableText(content), innerW);
+    return theme.fg("border", "│") + pad(safeContent, innerW) + theme.fg("border", "│");
+}
+export function renderHeader(text, width, theme) {
+    const innerW = Math.max(0, width - 2);
+    const safeText = truncateToWidth(normalizeRenderableText(text), innerW);
+    const padLen = Math.max(0, innerW - visibleWidth(safeText));
+    const padLeft = Math.floor(padLen / 2);
+    const padRight = padLen - padLeft;
+    return (theme.fg("border", "╭" + "─".repeat(padLeft)) +
+        theme.fg("accent", safeText) +
+        theme.fg("border", "─".repeat(padRight) + "╮"));
+}
+export function formatPath(filePath) {
+    const home = process.env.HOME;
+    if (home && filePath.startsWith(home))
+        return `~${filePath.slice(home.length)}`;
+    return filePath;
+}
+export function formatScrollInfo(above, below, opts) {
+    if (opts?.style === "position")
+        return `${above}/${below}`;
+    let info = "";
+    if (above > 0)
+        info += `↑ ${above} more`;
+    if (below > 0)
+        info += `${info ? "  " : ""}↓ ${below} more`;
+    return info;
+}
+export function renderFooter(text, width, theme) {
+    const innerW = Math.max(0, width - 2);
+    const safeText = truncateToWidth(normalizeRenderableText(text), innerW);
+    const padLen = Math.max(0, innerW - visibleWidth(safeText));
+    const padLeft = Math.floor(padLen / 2);
+    const padRight = padLen - padLeft;
+    return (theme.fg("border", "╰" + "─".repeat(padLeft)) +
+        theme.fg("dim", safeText) +
+        theme.fg("border", "─".repeat(padRight) + "╯"));
+}
+/**
+ * Build one half of a top border with an embedded title and optional right-aligned tail.
+ * Layout: `─ <label> ───…─── <tail> ─` with single dashes for spacing.
+ * Returns a fragment WITHOUT corner glyphs; caller composes corners + `┬` divider.
+ */
+export function titledTopSegment(theme, opts) {
+    const dash = (n) => theme.fg("dim", "─".repeat(Math.max(0, n)));
+    if (opts.style === "legacy") {
+        const width = Math.max(0, opts.width);
+        if (width <= 0)
+            return "";
+        if (width <= 2)
+            return dash(width);
+        const labelColor = opts.labelColor ?? "text";
+        const tailColor = opts.tailColor ?? "dim";
+        const tailPlain = opts.tailPlain ?? opts.tail ?? "";
+        const tailRendered = opts.tailRendered ?? (opts.tail !== undefined ? theme.fg(tailColor, opts.tail) : "");
+        const tailLen = visibleWidth(tailPlain);
+        const canShowTail = tailLen > 0 && width - tailLen >= 14;
+        const labelBudget = Math.max(0, width - (canShowTail ? tailLen + 6 : 4));
+        const labelText = clipText(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))
+            : theme.fg(labelColor, labelText);
+        if (canShowTail) {
+            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, 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";
+    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 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 labelLen = visibleWidth(labelText);
+    // 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(0, width - (labelLen + 3));
+    return clipStyled(`${dash(1)} ${labelStyled} ${dash(fillDashes)}`, width);
+}
+/**
+ * Build one half of a bottom border with an embedded hint string.
+ * Layout: `─ <hint> ───…─` (no tail). Empty hint renders as a solid dash run.
+ */
+export function titledBottomSegment(theme, width, hint, focused) {
+    const dash = (n) => theme.fg("dim", "─".repeat(Math.max(0, n)));
+    if (width <= 0)
+        return "";
+    if (!hint)
+        return dash(width);
+    // Reserve at minimum `─ ` + hint + ` `; truncate hint to fit when narrow so we never overflow.
+    const hintBudget = Math.max(0, width - 3);
+    const clipped = truncateToWidth(hint, hintBudget);
+    const clippedLen = visibleWidth(clipped);
+    if (clippedLen === 0)
+        return dash(width);
+    const hintStyled = focused && theme.bold
+        ? theme.bold(theme.fg("accent", clipped))
+        : theme.fg("dim", clipped);
+    const fillDashes = Math.max(0, width - (clippedLen + 3));
+    return `${dash(1)} ${hintStyled} ${dash(fillDashes)}`;
+}
+/** Pad-right to a visible width using `visibleWidth` (ANSI-aware). */
+export function padRight(text, width) {
+    const clipped = visibleWidth(text) > width ? clipStyled(text, width) : text;
+    const pad = Math.max(0, width - visibleWidth(clipped));
+    return clipped + " ".repeat(pad);
+}
+/** Slice text by visible width and preserve ANSI color resets when present. */
+export function clipStyled(text, width) {
+    if (width <= 0)
+        return "";
+    if (!text.includes("\u001b["))
+        return clipText(text, width);
+    return truncateToWidth(text, width, "");
+}
+/** Slice text by character count (NOT visible width). For label text after `clipText` we then re-measure with visibleWidth. */
+export function clipText(text, width) {
+    if (width <= 0)
+        return "";
+    return Array.from(text).slice(0, width).join("");
+}
+/**
+ * Inline horizontal rule with an embedded title, NO corner/tee glyphs.
+ * Used inside a pane to subdivide sections (e.g. list / legend) without
+ * faking a second box border. Layout: `─ <title> ──…──`.
+ */
+export function flatRule(theme, title, width, opts) {
+    if (width <= 0)
+        return "";
+    const dash = (n) => theme.fg("dim", "─".repeat(Math.max(0, n)));
+    if (!title)
+        return dash(width);
+    if (opts?.leadingDashes !== undefined) {
+        const label = ` ${title} `;
+        const labelW = visibleWidth(label);
+        if (labelW + 4 >= width)
+            return dash(width);
+        const leading = Math.max(0, opts.leadingDashes);
+        const trailing = Math.max(0, width - labelW - leading);
+        return `${dash(leading)}${theme.fg("dim", label)}${dash(trailing)}`;
+    }
+    const clipped = truncateToWidth(title, Math.max(0, width - 4));
+    const clippedLen = visibleWidth(clipped);
+    const styled = theme.fg("dim", clipped);
+    const trailing = Math.max(0, width - (clippedLen + 3));
+    return `${dash(1)} ${styled} ${dash(trailing)}`;
+}
+/** Body row for a two-pane box. Caller supplies the left and right interior widths. */
+export function boxRow(theme, left, right, leftWidth, rightWidth) {
+    const border = theme.fg("dim", "│");
+    const leftCell = padRight(truncateToWidth(left, leftWidth), leftWidth);
+    const rightCell = padRight(truncateToWidth(right, rightWidth), rightWidth);
+    return border + leftCell + border + rightCell + border;
+}
+/** Aligned key legend row, dimmed by the caller when desired. */
+export function renderKeyRow(key, desc, width, keyWidth) {
+    const keyCell = padRight(key, keyWidth);
+    return clipStyled(`${keyCell}  ${desc}`, width);
+}

package/package.json

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