pi-extension-utils 0.2.1 → 0.3.0

package/dist/src/index.d.ts

@@ -1,4 +1,7 @@
 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";

package/dist/src/index.js

@@ -1,4 +1,7 @@
 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";

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-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,218 @@
+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 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;
+    // 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 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)}`;
+    }
+    const fillDashes = Math.max(1, opts.width - (labelLen + 3));
+    return `${dash(1)} ${labelStyled} ${dash(fillDashes)}`;
+}
+/**
+ * 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.0",
 	"description": "Shared Pi extension utilities for coordinated widgets, fullscreen leases, and logging.",
 	"type": "module",
 	"main": "./dist/src/index.js",