@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/ui/layout/scroll-indicator.js

@@ -0,0 +1,36 @@
+/**
+ * Scroll-thumb geometry (mouse-wheel-region-routing §4.8) — pure, React-free.
+ *
+ * Wheel scrolling without a position indicator is a half-finished affordance:
+ * the user learns THAT they moved but not HOW FAR or how much is left. The
+ * status bar's `↑N` answers neither.
+ *
+ * OFFSET COUNTS FROM THE BOTTOM, exactly as `scroll.ts` documents — `0` is
+ * pinned to the newest output and `overflow` is parked at the very top. The
+ * rows hidden ABOVE are therefore `overflow - offset`, and that inversion is
+ * precisely what gets done by accident, so it is computed here once and named.
+ */
+/**
+ * Where the thumb sits, or `null` when the content fits and there is nothing to
+ * indicate.
+ *
+ * `size` never rounds to zero: a 10-row window over a 5000-row transcript still
+ * gets a one-row thumb, because an indicator that vanishes at exactly the
+ * moment the transcript is longest is worse than no indicator at all.
+ */
+export function thumbRange(viewportRows, contentRows, offsetFromBottom, reserveTravel = false) {
+    const viewport = Math.floor(viewportRows);
+    const content = Math.floor(contentRows);
+    if (!Number.isFinite(viewport) || !Number.isFinite(content))
+        return null;
+    if (viewport <= 0 || content <= viewport)
+        return null;
+    const overflow = content - viewport;
+    const offset = Math.min(Math.max(Math.floor(offsetFromBottom) || 0, 0), overflow);
+    const maximum = reserveTravel && viewport >= 2 ? viewport - 1 : viewport;
+    const size = Math.min(maximum, Math.max(1, Math.round((viewport * viewport) / content)));
+    const travel = viewport - size;
+    const hiddenAbove = overflow - offset;
+    const start = travel <= 0 ? 0 : Math.round((hiddenAbove / overflow) * travel);
+    return { start: Math.min(Math.max(start, 0), travel), size };
+}

package/dist/ui/layout/scroll.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Scroll maths for the self-drawn viewport (spec §4.5). Pure, React-free.
+ *
+ * `offset` counts LINES FROM THE BOTTOM — equivalently, the number of rows
+ * currently hidden BELOW the viewport. `0` means pinned to the newest output;
+ * `overflowLines` means parked at the very top. Counting from the bottom is what
+ * makes auto-follow free: when new content arrives `overflowLines` grows while
+ * `offset` stays 0, so the viewport keeps showing the tail without anyone
+ * calling a "scroll to bottom" routine.
+ *
+ * The rows hidden ABOVE are therefore `overflowLines - offset`. Mixing the two
+ * up inverts both the bottom-snap test and the "N new lines" hint.
+ */
+export interface ScrollState {
+    offset: number;
+}
+export interface ViewportMetrics {
+    /** Visible height of the clipping box, in rows. */
+    viewport: number;
+    /** Natural (unclipped) height of the content, in rows. */
+    content: number;
+}
+export type ScrollIntent = 'lineUp' | 'lineDown' | 'pageUp' | 'pageDown' | 'toTop' | 'toBottom';
+export declare const BOTTOM_SNAP_TOLERANCE = 2;
+export declare function clampScroll(offset: number, overflowLines: number): number;
+export declare function pageSize(viewportHeight: number): number;
+export declare function isPinnedToBottom(state: ScrollState): boolean;
+export declare function applyScroll(state: ScrollState, intent: ScrollIntent, metrics: ViewportMetrics): ScrollState;
+/**
+ * Fold `applyScroll` `times` times — one `setState`, one render, however fast
+ * the wheel spins (mouse-wheel-region-routing §5.5).
+ *
+ * Folding rather than multiplying is deliberate: `applyScroll` owns the
+ * downward bottom-snap and the clamp, and reimplementing either here would give
+ * the wheel a different notion of "pinned to the bottom" than the keyboard has.
+ */
+export declare function applyScrollTimes(state: ScrollState, intent: ScrollIntent, metrics: ViewportMetrics, times: number): ScrollState;

package/dist/ui/layout/scroll.js

@@ -0,0 +1,99 @@
+/**
+ * Scroll maths for the self-drawn viewport (spec §4.5). Pure, React-free.
+ *
+ * `offset` counts LINES FROM THE BOTTOM — equivalently, the number of rows
+ * currently hidden BELOW the viewport. `0` means pinned to the newest output;
+ * `overflowLines` means parked at the very top. Counting from the bottom is what
+ * makes auto-follow free: when new content arrives `overflowLines` grows while
+ * `offset` stays 0, so the viewport keeps showing the tail without anyone
+ * calling a "scroll to bottom" routine.
+ *
+ * The rows hidden ABOVE are therefore `overflowLines - offset`. Mixing the two
+ * up inverts both the bottom-snap test and the "N new lines" hint.
+ */
+/**
+ * Rows of context kept across a page turn, and — not a coincidence — the
+ * bottom-snap tolerance. The tolerance must be >= whatever a page turn can
+ * leave behind, or PgDn parks the user in a fake off-bottom state that they
+ * cannot press their way out of.
+ */
+const PAGE_CONTEXT_LINES = 2;
+export const BOTTOM_SNAP_TOLERANCE = PAGE_CONTEXT_LINES;
+export function clampScroll(offset, overflowLines) {
+    const max = Math.max(0, overflowLines);
+    if (!Number.isFinite(offset) || offset < 0)
+        return 0;
+    return Math.min(Math.floor(offset), max);
+}
+export function pageSize(viewportHeight) {
+    return Math.max(1, Math.floor(viewportHeight) - PAGE_CONTEXT_LINES);
+}
+export function isPinnedToBottom(state) {
+    return state.offset === 0;
+}
+/** Intents that move toward the newest output; only these snap to the bottom. */
+function isDownward(intent) {
+    return intent === 'lineDown' || intent === 'pageDown' || intent === 'toBottom';
+}
+export function applyScroll(state, intent, metrics) {
+    const overflowLines = Math.max(0, metrics.content - metrics.viewport);
+    const page = pageSize(metrics.viewport);
+    let next;
+    switch (intent) {
+        case 'lineUp':
+            next = state.offset + 1;
+            break;
+        case 'lineDown':
+            next = state.offset - 1;
+            break;
+        case 'pageUp':
+            next = state.offset + page;
+            break;
+        case 'pageDown':
+            next = state.offset - page;
+            break;
+        case 'toTop':
+            next = overflowLines;
+            break;
+        case 'toBottom':
+            next = 0;
+            break;
+    }
+    const clamped = clampScroll(next, overflowLines);
+    // `offset` IS the number of rows hidden below the viewport, so proximity to
+    // the bottom is `offset <= tolerance` — not `overflowLines - offset`, which
+    // measures the distance to the TOP. Without the snap, a PgDn that lands one
+    // row short parks the user in a fake off-bottom state (a stuck `↑1` and a
+    // permanent "new lines" hint) that no further PgDn can clear, because the
+    // hint row itself shrinks the viewport and keeps re-introducing the residue.
+    //
+    // Downward intents only: with the correct comparison, snapping on the way up
+    // would turn `lineUp` from a pinned viewport into a no-op.
+    if (isDownward(intent) && clamped <= BOTTOM_SNAP_TOLERANCE) {
+        return { offset: 0 };
+    }
+    return { offset: clamped };
+}
+/**
+ * Upper bound on one folded burst. `repeat` arrives from the wheel router's
+ * coalescing window, and an unbounded fold is a free CPU-burn primitive for a
+ * high-resolution / free-spinning wheel (R-10).
+ */
+const MAX_SCROLL_REPEAT = 100;
+/**
+ * Fold `applyScroll` `times` times — one `setState`, one render, however fast
+ * the wheel spins (mouse-wheel-region-routing §5.5).
+ *
+ * Folding rather than multiplying is deliberate: `applyScroll` owns the
+ * downward bottom-snap and the clamp, and reimplementing either here would give
+ * the wheel a different notion of "pinned to the bottom" than the keyboard has.
+ */
+export function applyScrollTimes(state, intent, metrics, times) {
+    const n = Number.isFinite(times)
+        ? Math.min(MAX_SCROLL_REPEAT, Math.max(1, Math.floor(times)))
+        : 1;
+    let next = state;
+    for (let i = 0; i < n; i += 1)
+        next = applyScroll(next, intent, metrics);
+    return next;
+}

package/dist/ui/layout/scrollbar-geometry.d.ts

@@ -0,0 +1,17 @@
+import type { ThumbRange } from './scroll-indicator.js';
+export interface ScrollbarGeometry {
+    trackTop: number;
+    trackCol: number;
+    trackRows: number;
+    contentRows: number;
+    offset: number;
+    thumb: ThumbRange | null;
+    revision: number;
+}
+export interface ThumbOffsetInput {
+    geometry: ScrollbarGeometry;
+    pointerY: number;
+    grabRow: number;
+}
+/** Convert a captured pointer to a bottom-relative offset, with exact endpoints. */
+export declare function offsetForThumb({ geometry: g, pointerY, grabRow }: ThumbOffsetInput): number;

package/dist/ui/layout/scrollbar-geometry.js

@@ -0,0 +1,13 @@
+/** Convert a captured pointer to a bottom-relative offset, with exact endpoints. */
+export function offsetForThumb({ geometry: g, pointerY, grabRow }) {
+    const values = [g.trackTop, g.trackRows, g.contentRows, pointerY, grabRow];
+    if (!values.every(Number.isFinite) || !g.thumb)
+        return g.offset;
+    const overflow = Math.max(0, g.contentRows - g.trackRows);
+    const travel = g.trackRows - g.thumb.size;
+    if (travel <= 0 || overflow === 0)
+        return g.offset;
+    const grab = Math.min(Math.max(0, Math.floor(grabRow)), g.thumb.size - 1);
+    const top = Math.min(travel, Math.max(0, Math.floor(pointerY) - g.trackTop - grab));
+    return overflow - Math.round(top / travel * overflow);
+}

package/dist/ui/layout/session-chip.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The session-id chip: pure width planning, no JSX
+ * (tui-session-id-resume §3.9 / D-11 / D-12).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A PLANNER AND NOT A STYLED `<Text>`: the status bar is a cell-by-cell
+ * measured row with a six-rung degradation ladder (`status-layout.ts`), not a
+ * flex layout.
+ * Anything positioned "just to the right" pushes the left half over or covers
+ * `phase`, and `phase` is the field a user needs while a run is in flight. The
+ * chip therefore spends cells out of the SAME budget as every other field.
+ *
+ * THE ID IS NEVER TRUNCATED (D-12). A truncated id produces a `--resume` command
+ * that is guaranteed to fail, which is strictly worse than showing nothing: the
+ * rungs below are, in order, "drop the label" and only then "hide the whole
+ * chip", and `/session` reports the full id at any width.
+ */
+export declare const SESSION_CHIP_LIMITS: {
+    /** The same threshold `Header.tsx` uses for its `^I Index` hint. */
+    readonly labelMinCols: 72;
+    /** Blank cells between the last status field and the chip. */
+    readonly gapCells: 2;
+    /**
+     * The tightest rung's worst-case width for the fields on the LEFT, summed:
+     * phase glyph(1)+label(4)=5, sep 1 -> 6, deferred mode 'C>B' 3 -> 9,
+     * sep 1 -> 10, 'C'+'~999%' 6 -> 16, sep 1 -> 17, thinking code 1 -> 18,
+     * sep 1 -> 19, '>99M/s' 6 -> 25, sep 1 -> 26, '>999d' 5 -> 31.
+     *
+     * 34 IS A FLOOR ROUNDED UP, not a measurement: over-estimating hides the chip
+     * one column early, which is invisible; under-estimating lets the chip eat the
+     * phase field, which is not.
+     */
+    readonly minStatusCells: 34;
+};
+export interface SessionChipPlan {
+    visible: boolean;
+    text: string;
+    cells: number;
+    gap: number;
+}
+/**
+ * Plan the chip for `columns` and this session's id.
+ *
+ * Inputs are the same ones the status row already has, so the two plans cannot
+ * disagree about the terminal: `StatusBar` computes `chip` first and hands
+ * `chip.cells + chip.gap` to `planPrimaryStatusFields` as `reserveRight`.
+ */
+export declare function planSessionChip(input: {
+    columns: number;
+    sessionId?: string | null;
+}): SessionChipPlan;

package/dist/ui/layout/session-chip.js

@@ -0,0 +1,64 @@
+/**
+ * The session-id chip: pure width planning, no JSX
+ * (tui-session-id-resume §3.9 / D-11 / D-12).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A PLANNER AND NOT A STYLED `<Text>`: the status bar is a cell-by-cell
+ * measured row with a six-rung degradation ladder (`status-layout.ts`), not a
+ * flex layout.
+ * Anything positioned "just to the right" pushes the left half over or covers
+ * `phase`, and `phase` is the field a user needs while a run is in flight. The
+ * chip therefore spends cells out of the SAME budget as every other field.
+ *
+ * THE ID IS NEVER TRUNCATED (D-12). A truncated id produces a `--resume` command
+ * that is guaranteed to fail, which is strictly worse than showing nothing: the
+ * rungs below are, in order, "drop the label" and only then "hide the whole
+ * chip", and `/session` reports the full id at any width.
+ */
+import stringWidth from 'string-width';
+export const SESSION_CHIP_LIMITS = {
+    /** The same threshold `Header.tsx` uses for its `^I Index` hint. */
+    labelMinCols: 72,
+    /** Blank cells between the last status field and the chip. */
+    gapCells: 2,
+    /**
+     * The tightest rung's worst-case width for the fields on the LEFT, summed:
+     * phase glyph(1)+label(4)=5, sep 1 -> 6, deferred mode 'C>B' 3 -> 9,
+     * sep 1 -> 10, 'C'+'~999%' 6 -> 16, sep 1 -> 17, thinking code 1 -> 18,
+     * sep 1 -> 19, '>99M/s' 6 -> 25, sep 1 -> 26, '>999d' 5 -> 31.
+     *
+     * 34 IS A FLOOR ROUNDED UP, not a measurement: over-estimating hides the chip
+     * one column early, which is invisible; under-estimating lets the chip eat the
+     * phase field, which is not.
+     */
+    minStatusCells: 34,
+};
+/** `{visible:false}` - the shape every caller can cheaply branch on. */
+const HIDDEN = { visible: false, text: '', cells: 0, gap: 0 };
+/**
+ * Plan the chip for `columns` and this session's id.
+ *
+ * Inputs are the same ones the status row already has, so the two plans cannot
+ * disagree about the terminal: `StatusBar` computes `chip` first and hands
+ * `chip.cells + chip.gap` to `planPrimaryStatusFields` as `reserveRight`.
+ */
+export function planSessionChip(input) {
+    // No identity (the default build, a test, or a host with no session) is the
+    // `undefined` case, and it must cost nothing: reserveRight stays 0 and the
+    // status row's output is byte-identical to the pre-feature build (I-6).
+    if (!input.sessionId)
+        return HIDDEN;
+    const columns = Number.isFinite(input.columns) ? Math.floor(input.columns) : 80;
+    const id = input.sessionId;
+    const gap = SESSION_CHIP_LIMITS.gapCells;
+    const fits = (text) => columns - 1 - gap - stringWidth(text) >= SESSION_CHIP_LIMITS.minStatusCells;
+    // Widest form first, then drop the label, then hide: the order is the decision.
+    const labelled = `id ${id}`;
+    if (columns >= SESSION_CHIP_LIMITS.labelMinCols && fits(labelled)) {
+        return { visible: true, text: labelled, cells: stringWidth(labelled), gap };
+    }
+    if (fits(id))
+        return { visible: true, text: id, cells: stringWidth(id), gap };
+    return HIDDEN;
+}

package/dist/ui/layout/shortcut-panel-layout.d.ts

@@ -0,0 +1,191 @@
+/**
+ * The shortcut drawer's geometry and row layout
+ * (tui-shortcut-drawer-and-task-summary §4.5).
+ *
+ * ASCII ONLY: `src/ui/**` is inside the glyph scanner's scope, so every symbol
+ * this module emits arrives as a `glyphs` field and is never spelled here.
+ *
+ * PURE AND TOTAL. No Ink, no clock, no terminal: the drawer component renders
+ * what this returns, `OverlayFrame` slices the window this function DERIVED, and
+ * `shortcut-panel-layout.test.ts` pins the arithmetic directly. That split is the
+ * whole defence against P0-1, which was not a rendering bug: v1 hand-fixed the key
+ * column at 21 cells, which left six cells for the keyword at 80 columns, so every
+ * keyword was truncated to `promp...` while a "does not overflow" assertion stayed
+ * green. The column is therefore DERIVED from the table, and a keyword that does
+ * not fit makes its row STACK rather than be cut.
+ *
+ * THERE IS EXACTLY ONE WINDOW AUTHORITY: `cursor`. v1 took both `cursor` and
+ * `scrollOffset`, which meant paging could leave the selected row - and the detail
+ * line that belongs to it - off screen. Paging now moves the CURSOR by a page and
+ * the window is the smallest one containing it.
+ */
+import { type OverlayWindow } from './overlay-window.js';
+import { type ShortcutEntry } from '../shortcuts.js';
+export declare const SHORTCUT_PANEL_LIMITS: {
+    /** Below this the drawer is full width: a 30-cell bar on a 40-cell screen is noise. */
+    readonly minSplitCols: 64;
+    /** Fraction of the terminal the drawer takes when it IS a drawer. */
+    readonly widthFraction: 0.34;
+    readonly minWidth: 30;
+    readonly maxWidth: 46;
+    /** Rail (1 cell) + `paddingLeft` (1 cell) that `OverlayFrame` spends below 48 columns. */
+    readonly railCells: 2;
+    /** Border (2 cells) + `paddingX` (2 cells) that `OverlayFrame` spends at or above 48. */
+    readonly boxCells: 4;
+    /**
+     * The key column is DERIVED: `min(longestKeys, ceil(listCells * 0.55))`.
+     *
+     * A hard 21 is what turned `prompt library` into `promp...` at 80 columns. The
+     * share is a ceiling, not a target: a table of short keys gets a narrow key
+     * column and the leftover width goes to the keyword.
+     */
+    readonly keyColumnShare: 0.55;
+    /** The keyword column must be at least this wide, or the row stacks. */
+    readonly keywordMinCells: 8;
+    /** Hard ceiling for a keyword string; a longer one is a spec bug, not a width problem. */
+    readonly keywordMaxCells: 10;
+    /** Gap between the key column and the keyword column. */
+    readonly keyGapCells: 1;
+    /** Indent for the selected row's detail lines, and for a stacked keyword. */
+    readonly detailIndent: 2;
+    /** Title + footer rows are chrome and are spent out of the row budget. */
+    readonly chromeRows: 2;
+    /** The task section is capped so the key list always gets the majority of the panel. */
+    readonly taskMaxRows: 2;
+    /**
+     * ABOVE THIS BODY HEIGHT THE GROUP HEADERS GET THEIR OWN ROWS.
+     *
+     * Below it they are dropped entirely - not compressed into `---- GROUP ----`
+     * separators, which was v2's rule and left FOUR entry rows visible on an
+     * 80x24 terminal (title + task + rule + five separators = 9 of 13 body rows).
+     * See `spec.md`'s `## 实施过程发现的方案缺陷` note 1: the ordering still runs
+     * COMPOSE -> RUN -> PANELS -> SESSION -> VIEW, and the requirement ("list every
+     * shortcut from top to bottom") is met by the entries themselves.
+     */
+    readonly groupHeaderMinRows: 18;
+    /** The longest detail line the selected row may grow to. */
+    readonly detailMaxRows: 2;
+};
+/**
+ * The drawer's width in columns.
+ *
+ * `cols < 64` is FULL WIDTH on purpose: at 40 columns a right-aligned 30-cell bar
+ * spends 10 of the user's columns on empty space. The clamp mirrors
+ * `rail.ts::todoRailWidth` (same shape, same reason).
+ */
+export declare function shortcutPanelWidth(cols: number): number;
+/**
+ * Cells the drawer may draw on INSIDE its frame.
+ *
+ * THE FORM IS DECIDED BY THE TERMINAL, exactly as `OverlayFrame` decides it
+ * (`cols >= BORDERLESS_COLS`), so this function takes the same `cols` the frame
+ * receives. Passing the panel's own width instead would make a 46-cell drawer on
+ * a 200-column terminal fall back to the rail form for ever, because 46 < 48.
+ */
+export declare function shortcutPanelContentCells(cols: number): number;
+/** One rendered row. `text` already measures at most the panel's content width. */
+export interface ShortcutRow {
+    /** `entry` = key + keyword on one row; `stacked` = key alone, keyword below. */
+    kind: 'task' | 'rule' | 'group' | 'entry' | 'stacked' | 'keyword' | 'detail';
+    text: string;
+    /** Which entry a `detail` / `keyword` row belongs to; `null` for every other kind. */
+    entryId: string | null;
+    tone: 'accent' | 'primary' | 'muted' | 'dim';
+}
+/** The task section's inputs, already flattened by the caller. */
+export interface ShortcutTaskSection {
+    /** The label, or `null` when there is none yet. */
+    text: string | null;
+    /** `model` / `fallback`, so the row can be coloured by provenance. */
+    tone: 'model' | 'fallback' | null;
+    /** Why it is a fallback, or `null`. */
+    reason: string | null;
+    /** `provider:model`, or `''`. */
+    by: string;
+    /** Age in ms, or `null` when unknown. */
+    ageMs: number | null;
+    /** `false` when `taskSummary.enabled` is off. */
+    enabled: boolean;
+    /** A call is in flight. */
+    pending: boolean;
+}
+export interface BuildShortcutRowsInput {
+    cols: number;
+    /** Body rows available INSIDE the frame (`OverlayFrame` already subtracted its chrome). */
+    rows: number;
+    /** Index into the FILTERED entry list. The one authority for the window. */
+    cursor: number;
+    /**
+     * THE ENTRIES ARRIVE FILTERED AND WITH THEIR AVAILABILITY, so this module takes
+     * neither a `query` nor a `context` for them (review fix RF-2). It used to accept
+     * both - and `detailsExpanded` as well - and read none of them, which is the exact
+     * "second source of truth that silently does nothing" its own 0-3 rule forbids: a
+     * caller could pass `query: 'git'` and get the unfiltered list with nothing
+     * failing.
+     */
+    entries: readonly ShortcutEntry[];
+    task: ShortcutTaskSection;
+    /** Per-entry availability, so an unavailable row renders dim and explains itself. */
+    entryAvailable?: (entry: ShortcutEntry) => boolean;
+    /** The sentence appended to an unavailable row's detail line. */
+    unavailableReason?: string;
+    glyphs: {
+        ellipsis: string;
+        cursor: string;
+        hrule: string;
+        midDot: string;
+    };
+}
+export interface BuildShortcutRowsResult {
+    rows: ShortcutRow[];
+    window: OverlayWindow;
+    /** Row index of the selected entry; equal to `window.start + 0` at the top. */
+    cursorRow: number;
+    /** Total rows the panel holds, which is what the frame's position indicator counts. */
+    total: number;
+    /** The footer string; `OverlayFrame`'s `hint`, and chrome rather than a row. */
+    hint: string;
+}
+/** Column widths for one geometry. Exported so the tests can assert them directly. */
+export interface ShortcutColumns {
+    /** The panel's own width. */
+    width: number;
+    /** Content cells inside the frame. */
+    available: number;
+    /** Cells left for a list row after the cursor column is spent. */
+    listCells: number;
+    keyCells: number;
+    keywordCells: number;
+    /** True when no entry fits the two-column form and every row stacks. */
+    stacked: boolean;
+}
+/**
+ * Derive the two columns (P0-1).
+ *
+ * `stacked` is a GLOBAL flag only when the keyword column is too narrow for any
+ * keyword at all; otherwise stacking is decided per row, so one long binding
+ * (`Shift+Up / Shift+Down`, 20 cells) does not cost the other thirty rows a line.
+ */
+export declare function shortcutColumns(cols: number, entries: readonly ShortcutEntry[], glyphs: {
+    cursor: string;
+}): ShortcutColumns;
+/**
+ * The footer, built by DROPPING clauses from the right (never by re-wording).
+ *
+ * `Esc close` is never dropped: it is the one thing a user must be able to find on
+ * a terminal too narrow to explain anything else. The rest go in a fixed order so
+ * the footer is stable across resizes instead of shuffling.
+ */
+export declare function shortcutFooter(cols: number, glyphs: {
+    midDot: string;
+}, opts?: {
+    canRefresh: boolean;
+}): string;
+/**
+ * Build every row the drawer can show, and derive the window from the cursor.
+ *
+ * @param input.cols Terminal columns (the frame receives the same number).
+ * @param input.rows Body rows inside the frame - `overlayBodyRows(maxRows, cols)`.
+ * @param input.cursor Index into `input.entries`; clamped, never trusted.
+ */
+export declare function buildShortcutRows(input: BuildShortcutRowsInput): BuildShortcutRowsResult;