pi-extension-utils 0.4.1 → 0.5.0

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

@@ -10,13 +10,30 @@ export interface PaneOverlayContext<T = unknown, Row = unknown> {
         mode: "cursor" | "scroll";
         cursor: number;
         scrollOffset: number;
+        width: number;
     };
     detail: {
         scrollOffset: number;
+        width: number;
     };
     close(result?: T): void;
     requestRender(): void;
 }
+export interface PaneOverlaySeparatorRow {
+    kind: "separator";
+    label?: string;
+}
+export type PaneOverlayPrimaryRow<Row = unknown> = Row | PaneOverlaySeparatorRow;
+export interface PaneOverlayTitle {
+    label: string;
+    tail?: string;
+    tailRendered?: string;
+    tailPlain?: string;
+    labelColor?: string;
+    tailColor?: string;
+    labelBold?: boolean;
+}
+type PaneOverlayTitleValue<Row> = string | PaneOverlayTitle | ((ctx: PaneOverlayContext<unknown, Row>) => string | PaneOverlayTitle);
 export interface PaneOverlayCustomAction<T = unknown, Row = unknown> {
     keys: string | readonly string[];
     label: string;
@@ -26,16 +43,20 @@ export interface PaneOverlayCustomAction<T = unknown, Row = unknown> {
 }
 export interface PrimaryPaneOptions<Row = unknown> {
     mode?: "cursor" | "scroll";
-    rows: Row[] | ((ctx: PaneOverlayContext<unknown, Row>) => Row[]);
-    renderRow?(row: Row, ctx: PaneOverlayContext<unknown, Row>): string;
+    rows: PaneOverlayPrimaryRow<Row>[] | ((ctx: PaneOverlayContext<unknown, Row>) => PaneOverlayPrimaryRow<Row>[]);
+    renderRow?(row: Row, ctx: PaneOverlayContext<unknown, Row>, width: number): string;
     selectionKey?(row: Row, index: number): string;
+    initialSelectionKey?: string;
+    initialIndex?: number;
     onSelectionChange?(row: Row | undefined, index: number, key: string, ctx: PaneOverlayContext<unknown, Row>): void;
-    title?: string | ((ctx: PaneOverlayContext<unknown, Row>) => string);
+    title?: PaneOverlayTitleValue<Row>;
+    info?: string[] | ((ctx: PaneOverlayContext<unknown, Row>) => string[]);
+    infoTitle?: 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);
+    title?: PaneOverlayTitleValue<Row>;
     footer?: string | ((ctx: PaneOverlayContext<unknown, Row>) => string);
 }
 export interface PaneOverlaySplitOptions {
@@ -66,6 +87,7 @@ export interface PaneOverlayOptions<T = unknown, Row = unknown> {
     collapse?: PaneCollapseOptions;
     perSelectionScroll?: boolean;
     stickyBottom?: boolean;
+    onRender?(ctx: PaneOverlayContext<T, Row>): void;
 }
 export interface PaneOverlayComponent {
     render(width: number): string[];
@@ -73,3 +95,4 @@ export interface PaneOverlayComponent {
     dispose(): void;
 }
 export declare function paneOverlay<T = undefined, Row = unknown>(options: PaneOverlayOptions<T, Row>): FullscreenComponentFactory<T>;
+export {};

package/dist/src/pane/overlay.js

@@ -1,5 +1,5 @@
 import { dispatchNavKeys } from "./key-dispatch.js";
-import { computeFixedSidebarLayout, computeSplitPaneLayout, endCursor, endScrollOffset, ensureCursorVisible, homeCursor, homeScrollOffset, moveCursor, moveScrollOffset, pageCursor, pageScrollOffset, resizeSplitPane, } from "./state.js";
+import { computeFixedSidebarLayout, computeSplitPaneLayout, endScrollOffset, ensureCursorVisible, homeScrollOffset, moveScrollOffset, pageScrollOffset, resizeSplitPane, } from "./state.js";
 import { boxRow, clipStyled, flatRule, formatScrollInfo, padRight, renderKeyRow, titledBottomSegment, titledTopSegment, } from "./chrome.js";
 import { matchesKey } from "@earendil-works/pi-tui";
 const DEFAULT_CLOSE_KEYS = ["escape", "ctrl+c", "q"];
@@ -28,6 +28,51 @@ function defaultRenderRow(row) {
 function decorateRow(text, theme) {
     return theme.bold ? theme.bold(theme.fg("accent", text)) : theme.fg("accent", text);
 }
+function isSeparatorRow(row) {
+    return typeof row === "object" && row !== null && row.kind === "separator";
+}
+function selectableIndexes(rows) {
+    const indexes = [];
+    for (let index = 0; index < rows.length; index++) {
+        if (!isSeparatorRow(rows[index]))
+            indexes.push(index);
+    }
+    return indexes;
+}
+function nearestSelectableIndex(rows, start) {
+    if (rows.length === 0)
+        return 0;
+    const clamped = Math.max(0, Math.min(start, rows.length - 1));
+    if (!isSeparatorRow(rows[clamped]))
+        return clamped;
+    for (let offset = 1; offset < rows.length; offset++) {
+        const after = clamped + offset;
+        if (after < rows.length && !isSeparatorRow(rows[after]))
+            return after;
+        const before = clamped - offset;
+        if (before >= 0 && !isSeparatorRow(rows[before]))
+            return before;
+    }
+    return 0;
+}
+function titleOptions(title, focused) {
+    if (typeof title === "object" && title !== null) {
+        return {
+            label: title.label,
+            tail: title.tail,
+            tailRendered: title.tailRendered,
+            tailPlain: title.tailPlain,
+            labelColor: title.labelColor ?? (focused ? "accent" : "text"),
+            tailColor: title.tailColor,
+            labelBold: title.labelBold ?? focused,
+        };
+    }
+    return {
+        label: title ?? "",
+        labelColor: focused ? "accent" : "text",
+        labelBold: focused,
+    };
+}
 export function paneOverlay(options) {
     const split = options.split ?? {};
     const closeKeys = options.closeKeys ?? DEFAULT_CLOSE_KEYS;
@@ -47,6 +92,7 @@ export function paneOverlay(options) {
         let leftFraction = split.initialFraction ?? 0.5;
         let lastRenderWidth = 80;
         let lastSelectedKey;
+        let initialSelectionApplied = false;
         const primaryState = { cursor: 0, scrollOffset: 0 };
         const detailState = { scrollOffset: 0, sticky: stickyBottom };
         const perSelectionOffsets = new Map();
@@ -59,7 +105,7 @@ export function paneOverlay(options) {
             finished = true;
             done(result);
         };
-        const makeContext = (selectedIndex, selectedRow, selectedKey, primaryRows, detailRows) => ({
+        const makeContext = (selectedIndex, selectedRow, selectedKey, primaryWidth = 0, detailWidth = 0) => ({
             tui,
             primaryFocus: focus === "primary",
             detailFocus: focus === "detail",
@@ -70,8 +116,9 @@ export function paneOverlay(options) {
                 mode: options.primary.mode ?? "scroll",
                 cursor: primaryState.cursor,
                 scrollOffset: primaryState.scrollOffset,
+                width: primaryWidth,
             },
-            detail: { scrollOffset: detailState.scrollOffset },
+            detail: { scrollOffset: detailState.scrollOffset, width: detailWidth },
             close: (result) => finish(result),
             requestRender,
         });
@@ -97,6 +144,60 @@ export function paneOverlay(options) {
                 fractionBasis: split.fractionBasis,
             });
         };
+        const currentWidths = () => {
+            const layout = getLayout(lastRenderWidth);
+            return { primaryWidth: layout.leftWidth, detailWidth: layout.rightWidth };
+        };
+        const getPrimaryRows = (ctx) => {
+            return resolveValue(options.primary.rows, ctx) ?? [];
+        };
+        const selectionKeyFor = (row, index) => {
+            return (options.primary.selectionKey ?? ((_row, rowIndex) => String(rowIndex)))(row, index);
+        };
+        const applyInitialSelection = (rows) => {
+            if (initialSelectionApplied || rows.length === 0)
+                return;
+            let targetIndex = -1;
+            if (options.primary.initialSelectionKey !== undefined) {
+                targetIndex = rows.findIndex((row, index) => !isSeparatorRow(row) && selectionKeyFor(row, index) === options.primary.initialSelectionKey);
+            }
+            if (targetIndex < 0 && options.primary.initialIndex !== undefined) {
+                targetIndex = options.primary.initialIndex;
+            }
+            if (targetIndex < 0)
+                return;
+            initialSelectionApplied = true;
+            const selectableIndex = nearestSelectableIndex(rows, targetIndex);
+            primaryState.cursor = selectableIndex;
+            primaryState.scrollOffset = selectableIndex;
+        };
+        const computeSelectionFromRows = (primaryRows, bodyHeight) => {
+            applyInitialSelection(primaryRows);
+            const primaryMode = options.primary.mode ?? "scroll";
+            let selectedIndex = 0;
+            if (primaryMode === "cursor") {
+                const viewport = ensureCursorVisible({
+                    cursor: nearestSelectableIndex(primaryRows, primaryState.cursor),
+                    scroll: primaryState.scrollOffset,
+                    itemCount: primaryRows.length,
+                    viewportHeight: Math.max(1, bodyHeight),
+                });
+                primaryState.cursor = nearestSelectableIndex(primaryRows, viewport.cursor);
+                primaryState.scrollOffset = viewport.scroll;
+                selectedIndex = primaryState.cursor;
+            }
+            else {
+                primaryState.scrollOffset = Math.min(primaryState.scrollOffset, Math.max(0, primaryRows.length - 1));
+                selectedIndex = nearestSelectableIndex(primaryRows, primaryState.scrollOffset);
+                primaryState.scrollOffset = selectedIndex;
+            }
+            if (primaryRows.length === 0 || selectableIndexes(primaryRows).length === 0)
+                selectedIndex = 0;
+            const selectedCandidate = primaryRows[selectedIndex];
+            const selectedRow = !isSeparatorRow(selectedCandidate) ? selectedCandidate : undefined;
+            const selectedKey = selectedRow !== undefined ? selectionKeyFor(selectedRow, selectedIndex) : String(selectedIndex);
+            return { primaryRows, selectedIndex, selectedRow, selectedKey };
+        };
         const resize = (direction) => {
             if (collapsed)
                 return;
@@ -129,16 +230,27 @@ export function paneOverlay(options) {
             }
             return state;
         };
-        const listViewport = (bodyHeight, legendLineCount) => {
-            const primaryHeight = legendPlacement === "primary"
-                ? Math.max(0, bodyHeight - legendLineCount - 1)
-                : bodyHeight;
-            return { primaryHeight, detailHeight: bodyHeight };
+        const primarySections = (bodyHeight, legendLineCount, infoLineCount) => {
+            const legendBlockHeight = legendPlacement === "primary" && legendLineCount > 0 ? legendLineCount + 1 : 0;
+            const availableBeforeLegend = Math.max(0, bodyHeight - legendBlockHeight);
+            const infoVisibleCount = infoLineCount > 0
+                ? Math.min(infoLineCount, Math.max(0, availableBeforeLegend - 2))
+                : 0;
+            const infoBlockHeight = infoVisibleCount > 0 ? infoVisibleCount + 1 : 0;
+            return {
+                primaryHeight: Math.max(0, availableBeforeLegend - infoBlockHeight),
+                detailHeight: bodyHeight,
+                infoVisibleCount,
+            };
         };
         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;
+            const { primaryWidth, detailWidth } = currentWidths();
+            const primaryRows = getPrimaryRows(makeContext(0, undefined, "", primaryWidth, detailWidth));
+            const selection = computeSelectionFromRows(primaryRows, bodyHeight);
+            const ctx = makeContext(selection.selectedIndex, selection.selectedRow, selection.selectedKey, primaryWidth, detailWidth);
+            const infoLines = resolveValue(options.primary.info, ctx) ?? [];
+            const viewportHeight = primarySections(bodyHeight, legendLineCount, infoLines.length).primaryHeight;
             return { primaryRows, viewportHeight: Math.max(1, viewportHeight) };
         };
         const applyPrimaryNav = (bodyHeight, legendLineCount, mutator) => {
@@ -148,8 +260,13 @@ export function paneOverlay(options) {
         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;
+                    const indexes = selectableIndexes(rows);
+                    if (indexes.length === 0)
+                        return;
+                    const currentIndex = nearestSelectableIndex(rows, state.cursor);
+                    const currentOrdinal = Math.max(0, indexes.indexOf(currentIndex));
+                    state.cursor = indexes[Math.max(0, Math.min(indexes.length - 1, currentOrdinal + delta))] ?? currentIndex;
+                    const next = ensureCursorVisible({ cursor: state.cursor, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight });
                     state.scrollOffset = next.scroll;
                 }
                 else {
@@ -161,8 +278,13 @@ export function paneOverlay(options) {
             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;
+                    const indexes = selectableIndexes(rows);
+                    if (indexes.length === 0)
+                        return;
+                    const currentIndex = nearestSelectableIndex(rows, state.cursor);
+                    const currentOrdinal = Math.max(0, indexes.indexOf(currentIndex));
+                    state.cursor = indexes[Math.max(0, Math.min(indexes.length - 1, currentOrdinal + delta * pageSize))] ?? currentIndex;
+                    const next = ensureCursorVisible({ cursor: state.cursor, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight });
                     state.scrollOffset = next.scroll;
                 }
                 else {
@@ -173,7 +295,10 @@ export function paneOverlay(options) {
         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 });
+                    const indexes = selectableIndexes(rows);
+                    if (indexes.length === 0)
+                        return;
+                    const next = ensureCursorVisible({ cursor: indexes[0] ?? 0, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight });
                     state.cursor = next.cursor;
                     state.scrollOffset = next.scroll;
                 }
@@ -185,7 +310,10 @@ export function paneOverlay(options) {
         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 });
+                    const indexes = selectableIndexes(rows);
+                    if (indexes.length === 0)
+                        return;
+                    const next = ensureCursorVisible({ cursor: indexes[indexes.length - 1] ?? 0, scroll: state.scrollOffset, itemCount: rows.length, viewportHeight });
                     state.cursor = next.cursor;
                     state.scrollOffset = next.scroll;
                 }
@@ -229,29 +357,6 @@ export function paneOverlay(options) {
             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
@@ -263,9 +368,11 @@ export function paneOverlay(options) {
                 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);
+                const primaryRows = getPrimaryRows(makeContext(0, undefined, "", primaryWidth, detailWidth));
+                const { selectedIndex, selectedRow, selectedKey } = computeSelectionFromRows(primaryRows, bodyHeight);
+                const ctx = makeContext(selectedIndex, selectedRow, selectedKey, primaryWidth, detailWidth);
+                options.onRender?.(ctx);
+                const detailRows = options.detail.rows(ctx) ?? [];
                 if (selectedKey !== lastSelectedKey) {
                     lastSelectedKey = selectedKey;
                     if (options.primary.onSelectionChange) {
@@ -283,7 +390,9 @@ export function paneOverlay(options) {
                 ensureFocusDetailWhenCollapsed();
                 const entries = legendEntries(ctx);
                 const legendLines = renderLegendLines(entries, totalWidth);
-                const { primaryHeight, detailHeight } = listViewport(bodyHeight, legendLines.length);
+                const infoLines = resolveValue(options.primary.info, ctx) ?? [];
+                const infoTitle = resolveValue(options.primary.infoTitle, ctx) ?? "info";
+                const { primaryHeight, detailHeight, infoVisibleCount } = primarySections(bodyHeight, legendLines.length, infoLines.length);
                 // Align primary viewport.
                 if ((options.primary.mode ?? "scroll") === "cursor") {
                     const viewport = ensureCursorVisible({
@@ -315,15 +424,11 @@ export function paneOverlay(options) {
                 const detailTitle = resolveValue(options.detail.title, ctx);
                 const topPrimary = titledTopSegment(chromeTheme, {
                     width: primaryWidth,
-                    label: primaryTitle ?? "",
-                    labelColor: focus === "primary" ? "accent" : "text",
-                    labelBold: focus === "primary",
+                    ...titleOptions(primaryTitle, focus === "primary"),
                 });
                 const topDetail = titledTopSegment(chromeTheme, {
                     width: detailWidth,
-                    label: detailTitle ?? "",
-                    labelColor: focus === "detail" ? "accent" : "text",
-                    labelBold: focus === "detail",
+                    ...titleOptions(detailTitle, focus === "detail"),
                 });
                 const corner = (glyph) => chromeTheme.fg("dim", glyph);
                 const topBorder = primaryWidth === 0
@@ -334,14 +439,17 @@ export function paneOverlay(options) {
                     .slice(primaryState.scrollOffset, primaryState.scrollOffset + primaryHeight)
                     .map((row, index) => {
                     const absoluteIndex = primaryState.scrollOffset + index;
-                    const text = renderFn(row, ctx);
+                    if (isSeparatorRow(row))
+                        return flatRule(chromeTheme, row.label ?? "", primaryWidth);
+                    const text = renderFn(row, ctx, primaryWidth);
                     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 selectable = selectableIndexes(primaryRows);
                 const primaryFooterText = resolveValue(options.primary.footer, ctx)
-                    ?? ((options.primary.mode ?? "scroll") === "cursor" && primaryRows.length > 0
-                        ? `${primaryState.cursor + 1}/${primaryRows.length}`
+                    ?? ((options.primary.mode ?? "scroll") === "cursor" && selectable.length > 0
+                        ? `${Math.max(0, selectable.indexOf(primaryState.cursor)) + 1}/${selectable.length}`
                         : primaryRows.length > primaryHeight
                             ? formatScrollInfo(primaryState.scrollOffset, Math.max(0, primaryRows.length - primaryHeight), { style: "position" })
                             : "");
@@ -355,13 +463,21 @@ export function paneOverlay(options) {
                     ? corner("╰") + bottomDetail + corner("╯")
                     : corner("╰") + bottomPrimary + corner("┴") + bottomDetail + corner("╯");
                 const bodyLines = [];
+                const infoStart = primaryHeight;
+                const legendStart = primaryHeight + (infoVisibleCount > 0 ? infoVisibleCount + 1 : 0);
                 for (let row = 0; row < bodyHeight; row++) {
                     let primaryCell = primaryVisible[row] ?? "";
-                    if (legendPlacement === "primary" && row === primaryHeight && legendLines.length > 0) {
+                    if (infoVisibleCount > 0 && row === infoStart) {
+                        primaryCell = flatRule(chromeTheme, infoTitle, primaryWidth);
+                    }
+                    else if (infoVisibleCount > 0 && row > infoStart && row < legendStart) {
+                        primaryCell = infoLines[row - infoStart - 1] ?? "";
+                    }
+                    else if (legendPlacement === "primary" && row === legendStart && legendLines.length > 0) {
                         primaryCell = flatRule(chromeTheme, collapse?.label ?? "actions", primaryWidth);
                     }
-                    if (legendPlacement === "primary" && row > primaryHeight) {
-                        const legendIndex = row - primaryHeight - 1;
+                    if (legendPlacement === "primary" && row > legendStart) {
+                        const legendIndex = row - legendStart - 1;
                         primaryCell = legendIndex < legendLines.length ? padRight(legendLines[legendIndex], primaryWidth) : "";
                     }
                     const detailCell = detailVisible[row] ?? "";
@@ -387,9 +503,11 @@ export function paneOverlay(options) {
                     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);
+                const { primaryWidth, detailWidth } = currentWidths();
+                const primaryRows = getPrimaryRows(makeContext(0, undefined, "", primaryWidth, detailWidth));
+                const { selectedIndex, selectedRow, selectedKey } = computeSelectionFromRows(primaryRows, bodyHeight);
+                const ctx = makeContext(selectedIndex, selectedRow, selectedKey, primaryWidth, detailWidth);
+                const detailRows = options.detail.rows(ctx) ?? [];
                 for (const action of customActions) {
                     if (action.when && !action.when(ctx))
                         continue;

package/docs/pane-overlay.md

@@ -19,12 +19,16 @@ await client.ui.fullscreen(
       mode: "cursor",
       rows: () => runs,
       selectionKey: (run) => run.id,
-      renderRow: (run) => run.label,
+      initialSelectionKey: currentRunId,
+      renderRow: (run, ctx, width) => width > 40 ? `${run.label} ${run.status}` : run.label,
+      infoTitle: "selected",
+      info: (ctx) => ctx.selectedRow ? [`status: ${ctx.selectedRow.status}`] : [],
     },
     detail: {
-      title: (ctx) => ctx.selectedRow?.label ?? "Details",
+      title: (ctx) => ({ label: ctx.selectedRow?.label ?? "Details", tail: "VAL" }),
       rows: (ctx) => renderDetails(ctx.selectedRow),
     },
+    onRender: (ctx) => tickFlashMessage(),
     customActions: [
       {
         keys: ["enter", "o"],
@@ -62,6 +66,29 @@ await client.ui.fullscreen(
 | `collapse` | Optional primary/sidebar collapse key |
 | `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 |
+
+## Primary pane extras
+
+The primary pane can render more than a flat selectable list:
+
+- `renderRow(row, ctx, width)` receives the current primary pane width. The same value is also exposed as `ctx.primary.width`; `ctx.detail.width` exposes the detail pane width.
+- `primary.info` renders a selected-row-derived block below the list and above a primary-placed legend. Use `primary.infoTitle` to label its divider.
+- `rows` may include `{ kind: "separator", label: "done" }`. Separator rows render as inline rules and are skipped by cursor movement and selection keys.
+- `initialSelectionKey` or `initialIndex` controls the first selected row when the overlay opens. `initialSelectionKey` applies on the first frame where that key is present, including async-arriving rows.
+
+Pane titles may be strings or structured objects forwarded to `titledTopSegment`:
+
+```ts
+detail: {
+  title: (ctx) => ({
+    label: ctx.selectedRow?.name ?? "Details",
+    tailRendered: renderStatusTail(ctx.selectedRow),
+    tailPlain: plainStatusTail(ctx.selectedRow),
+  }),
+  rows: renderDetailRows,
+}
+```
 
 ## Custom actions
 

package/examples/pane-overlay.ts

@@ -4,12 +4,13 @@ import { connect, paneOverlay } from "pi-extension-utils";
 interface RunRow {
   id: string;
   label: string;
+  status: string;
   lines: string[];
 }
 
 const runs: RunRow[] = [
-  { id: "a", label: "explorer", lines: ["status: running", "task: inspect files"] },
-  { id: "b", label: "qa", lines: ["status: done", "tests: passed"] },
+  { id: "a", label: "explorer", status: "running", lines: ["status: running", "task: inspect files"] },
+  { id: "b", label: "qa", status: "done", lines: ["status: done", "tests: passed"] },
 ];
 
 export default function (pi: ExtensionAPI) {
@@ -25,10 +26,13 @@ export default function (pi: ExtensionAPI) {
             mode: "cursor",
             rows: runs,
             selectionKey: (run) => run.id,
-            renderRow: (run) => run.label,
+            initialSelectionKey: "b",
+            renderRow: (run, _overlay, width) => width > 28 ? `${run.label} ${run.status}` : run.label,
+            infoTitle: "selected",
+            info: (overlay) => overlay.selectedRow ? [`status: ${overlay.selectedRow.status}`] : [],
           },
           detail: {
-            title: (overlay) => overlay.selectedRow?.label ?? "Details",
+            title: (overlay) => ({ label: overlay.selectedRow?.label ?? "Details", tail: overlay.selectedRow?.status }),
             rows: (overlay) => overlay.selectedRow?.lines ?? ["No selection"],
           },
           split: { initialFraction: 0.35, minPrimaryWidth: 20, minDetailWidth: 30 },

package/package.json

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