@aragon-agent/cli 0.6.37 → 0.6.39

package/dist/ui/overlays/ShortcutPanel.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The keyboard drawer (tui-shortcut-drawer-and-task-summary §4.5).
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * IT OWNS NO CHROME AND NO ARITHMETIC. `OverlayFrame` draws the frame, the
+ * window and the position indicator; `shortcut-panel-layout.ts` decides the
+ * columns, the rows and which window contains the cursor. This component adds two
+ * things and nothing else: its own key handling and the text-run colours. v1
+ * planned 260 lines that re-implemented the frame's windowing and clamping - a
+ * second source of truth for the one thing overlays have already been rewritten
+ * once to unify.
+ *
+ * IT DOES NOT REGISTER `Esc` AND DOES NOT TOUCH ANY `ctrl`/`meta` COMBINATION:
+ * `Esc` belongs to `App` (it closes every overlay and cancels the pending
+ * question/plan), and `Ctrl+G` is handled there too. Two listeners both acting on
+ * one byte is how a panel closes twice.
+ */
+import { useMemo, useState } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame, overlayBodyRows, overlayPageSize } from '../layout/OverlayFrame.js';
+import { buildShortcutRows, shortcutPanelWidth, } from '../layout/shortcut-panel-layout.js';
+import { filterShortcuts, isAvailable, SHORTCUTS } from '../shortcuts.js';
+/** Colour per tone. `dim` is `muted` plus the dim attribute, never a second colour. */
+function toneOf(row, theme) {
+    if (row.tone === 'accent')
+        return { color: theme.accent };
+    if (row.tone === 'primary')
+        return { color: theme.primary };
+    if (row.tone === 'dim')
+        return { color: theme.muted, dimColor: true };
+    return { color: theme.muted };
+}
+export function ShortcutPanel(props) {
+    const { cols, maxRows, theme, caps, isActive, native, running } = props;
+    const glyphs = pickGlyphs(caps);
+    const [cursor, setCursor] = useState(0);
+    const entries = useMemo(() => filterShortcuts(SHORTCUTS, props.query ?? ''), [props.query]);
+    const bodyRows = overlayBodyRows(maxRows, cols);
+    const page = overlayPageSize(maxRows, cols);
+    const result = useMemo(() => buildShortcutRows({
+        cols,
+        rows: bodyRows,
+        cursor,
+        entries,
+        task: props.task,
+        entryAvailable: (entry) => isAvailable(entry, { native, running }),
+        unavailableReason: native ? 'this mode leaves it to the terminal' : 'a run is in flight',
+        glyphs: {
+            ellipsis: glyphs.ellipsis,
+            cursor: glyphs.cursor,
+            hrule: glyphs.hrule,
+            midDot: glyphs.midDot,
+        },
+    }), [cols, bodyRows, cursor, entries, props.task, native, running,
+        glyphs.ellipsis, glyphs.cursor, glyphs.hrule, glyphs.midDot]);
+    const last = Math.max(0, entries.length - 1);
+    useInput((input, key) => {
+        // `ctrl`/`meta` ARE NOT OURS: `Ctrl+G` closes this panel and `Ctrl+C` owns the
+        // exit ladder, both in `App`. Consuming them here would double-handle a byte.
+        if (key.ctrl || key.meta)
+            return;
+        if (key.upArrow || input === 'k') {
+            setCursor((value) => Math.max(0, value - 1));
+            return;
+        }
+        if (key.downArrow || input === 'j') {
+            setCursor((value) => Math.min(last, value + 1));
+            return;
+        }
+        // PAGING MOVES THE CURSOR, one page minus one row of overlap - the same rule
+        // `overlayPageSize` uses for every other overlay, so a page turn keeps a row of
+        // context. An independent offset would let the selected row - and the detail
+        // line that explains it - slide off screen (P1-7).
+        if (key.pageUp) {
+            setCursor((value) => Math.max(0, value - Math.max(1, page - 1)));
+            return;
+        }
+        if (key.pageDown) {
+            setCursor((value) => Math.min(last, value + Math.max(1, page - 1)));
+            return;
+        }
+        if (input === 'd') {
+            props.onToggleDetails();
+            return;
+        }
+        if (input === 'r') {
+            props.onRefresh();
+        }
+    }, { isActive });
+    const rows = result.rows.map((row, index) => (_jsx(Text, { wrap: "truncate", ...toneOf(row, theme), children: row.text }, `${row.kind}-${row.entryId ?? 'x'}-${index}`)));
+    // THE `d` MARKER LIVES ON THE FRAME'S OWN TITLE LINE (D-6), which is chrome that is
+    // already paid for. It is spelled `d:on` / `d:off` rather than `details on|off`
+    // because the title row also carries the frame's position indicator (`v 1-13/37`,
+    // 13 cells) and the drawer's content is only 26 cells wide at 80 columns: the long
+    // form is truncated to `details...`, which is a marker that says nothing. The
+    // footer's `d details` clause names the key, so the pair reads as one sentence.
+    const title = `Keys  d:${props.detailsExpanded ? 'on' : 'off'}`;
+    return (_jsx(OverlayFrame, { title: title, hint: result.hint, maxRows: maxRows, cols: cols, width: shortcutPanelWidth(cols), align: "right", rows: rows, 
+        // THE WINDOW IS DERIVED FROM THE CURSOR, so the offset handed to the frame is
+        // a conclusion rather than state. `onScrollClamp` is deliberately not passed:
+        // there is nothing here that could drift out of step with it.
+        scrollOffset: result.window.start, theme: theme, caps: caps }));
+}

package/dist/ui/scrollback/canvas.d.ts

@@ -78,8 +78,9 @@ export declare function screenCapacity(rows: number | undefined): number;
 export declare function clampSpaceBelow(spaceBelow: number, rows: number | undefined): number;
 /**
  * A terminal that grew adds rows BELOW the cursor, so the capacity grows by the
- * exact difference (D6). Shrinking is NOT handled here: it re-measures instead of
- * guessing (D5), so a smaller value would only hide a lost measurement.
+ * exact difference (D6). Shrinking is NOT handled here either: the writer keeps the
+ * rows the screen still has and re-pins them (I-B17) instead of guessing a smaller
+ * value, which would only hide a lost measurement (D5).
  */
 export declare function applyResizeGrowth(capacity: number, rowsPrev: number, rowsNow: number): number;
 /**

package/dist/ui/scrollback/canvas.js

@@ -48,8 +48,9 @@ export function clampSpaceBelow(spaceBelow, rows) {
 }
 /**
  * A terminal that grew adds rows BELOW the cursor, so the capacity grows by the
- * exact difference (D6). Shrinking is NOT handled here: it re-measures instead of
- * guessing (D5), so a smaller value would only hide a lost measurement.
+ * exact difference (D6). Shrinking is NOT handled here either: the writer keeps the
+ * rows the screen still has and re-pins them (I-B17) instead of guessing a smaller
+ * value, which would only hide a lost measurement (D5).
  */
 export function applyResizeGrowth(capacity, rowsPrev, rowsNow) {
     // No capacity to grow: a broken number must not become a canvas by arithmetic.

package/dist/ui/scrollback/scrollback-writer.d.ts

@@ -54,6 +54,16 @@
  *  - I-B15 · every batch starts by reconciling `top + capacity` with the live
  *    `rows - 1` (a resize event can arrive one frame late), and a column change
  *    resets before it writes.
+ *  - I-B17 · a SHRINK re-pins the canvas, it never drops it. The canvas keeps
+ *    `min(canvasRows, screenCapacity(rows))` rows — the screen keeps the rows nearest
+ *    the parked cursor, so the survivors are its SUFFIX — and its top moves down to
+ *    `capacity - kept`, which preserves LB-3. Dropping the cache instead made the next
+ *    batch a SEED, and a seed assumes nothing is below the cursor
+ *    (`writer-shapes.ts:60-64`); after a shrink that is false, so the batch overflowed
+ *    the screen and the previous frame — status row included — went into the
+ *    scrollback: the same row in two places. For the same reason a frame TALLER than
+ *    the screen gives way at its TOP instead of being swallowed whole: the composer
+ *    and the status line are the two rows a human is interacting with.
  *  - I-A9 · the writer never writes a probe byte; it only asks the host, which owns
  *    deferral, coalescing and the death switch.
  */
@@ -102,6 +112,8 @@ export interface ScrollbackWriterStats {
     guardHits: number;
     /** The subset NOT explained by a recent resize: the real defect signal. */
     guardHitsOutsideResize: number;
+    /** Frames taller than the screen, drawn after giving way at their TOP (I-B17). */
+    tallFramesTrimmed: number;
     clippedRows: number;
     elidedEntries: number;
     resizes: number;
@@ -116,7 +128,7 @@ export interface ScrollbackWriterStats {
     anchorGapRows: number;
     /** Rows this session pushed into the scrollback (the "is it scrolling" signal). */
     anchorScrollRows: number;
-    /** Times the geometry was dropped on purpose (column change, shrink, gap lost). */
+    /** Times the geometry was dropped on purpose (column change, nothing left to pin). */
     anchorResets: number;
     /** Measurements accepted AFTER the first one — the re-probe count (not resize events). */
     anchorReprobes: number;

package/dist/ui/scrollback/scrollback-writer.js

@@ -54,6 +54,16 @@
  *  - I-B15 · every batch starts by reconciling `top + capacity` with the live
  *    `rows - 1` (a resize event can arrive one frame late), and a column change
  *    resets before it writes.
+ *  - I-B17 · a SHRINK re-pins the canvas, it never drops it. The canvas keeps
+ *    `min(canvasRows, screenCapacity(rows))` rows — the screen keeps the rows nearest
+ *    the parked cursor, so the survivors are its SUFFIX — and its top moves down to
+ *    `capacity - kept`, which preserves LB-3. Dropping the cache instead made the next
+ *    batch a SEED, and a seed assumes nothing is below the cursor
+ *    (`writer-shapes.ts:60-64`); after a shrink that is false, so the batch overflowed
+ *    the screen and the previous frame — status row included — went into the
+ *    scrollback: the same row in two places. For the same reason a frame TALLER than
+ *    the screen gives way at its TOP instead of being swallowed whole: the composer
+ *    and the status line are the two rows a human is interacting with.
  *  - I-A9 · the writer never writes a probe byte; it only asks the host, which owns
  *    deferral, coalescing and the death switch.
  */
@@ -110,6 +120,7 @@ export function createScrollbackWriter(o) {
         fallbacks: 0, guardHits: 0, guardHitsOutsideResize: 0, clippedRows: 0, elidedEntries: 0,
         resizes: 0, repaints: 0, anchorSource: 'none', anchorCanvasRows: 0, anchorHeldRows: 0,
         anchorGapRows: 0, anchorScrollRows: 0, anchorResets: 0, anchorReprobes: 0,
+        tallFramesTrimmed: 0,
     };
     const liveCols = () => {
         const cols = o.cols();
@@ -205,6 +216,68 @@ export function createScrollbackWriter(o) {
         stats.bytesWritten += bytes.length;
         return bytes;
     };
+    /**
+     * Drop from the canvas cache the rows a shorter screen no longer has (I-B17).
+     *
+     * A shrink deletes rows ABOVE the parked cursor, so what survives is the canvas's
+     * SUFFIX: the gap goes first, then the oldest content rows. Trimming the cache is
+     * what lets the next batch be a DIFF against what is really on screen. Dropping the
+     * cache (`reset()`) made it a SEED instead, and a seed assumes nothing is below the
+     * cursor (`writer-shapes.ts:60-64`) — after a shrink that is false, so the batch
+     * overflowed and the previous frame, status row included, was pushed into the
+     * scrollback instead of being erased.
+     */
+    const trimCanvasCache = (capacity) => {
+        const lost = canvasRows - capacity;
+        if (lost <= 0)
+            return;
+        const lostFromGap = Math.min(lost, gapRows);
+        gapRows -= lostFromGap;
+        held = held.slice(Math.min(lost - lostFromGap, held.length));
+        prev = prev === null ? null : prev.slice(lost);
+        canvasRows = capacity;
+        // A drastic shrink can eat into the region itself (E2). `frameRows` is the height
+        // the next diff is aligned against, so it may never claim rows that are gone.
+        frameRows = Math.min(frameRows, Math.max(0, capacity - gapRows - held.length));
+    };
+    /**
+     * Re-pin a canvas the terminal just got SHORTER, instead of dropping it (I-B17).
+     *
+     * `top` moves DOWN (`capacity - kept`) because the rows the screen lost were the ones
+     * above the cursor: the parked row is still `rows - 1`, so LB-3 holds for the same
+     * reason it always did.
+     *
+     * `capacity < 1` keeps the old answer (E3): a terminal with no row above the parked one
+     * has no canvas left to address, and re-measuring is then the only honest move. Columns
+     * are deliberately NOT handled here: a width change re-flows the rows themselves, so
+     * the cache describes nothing and still resets (D5 / E4).
+     */
+    const repinShrunk = (rows) => {
+        const room = screenCapacity(rows);
+        // Only a MEASURED canvas may be re-pinned. `unknown` means nothing ever established
+        // that the cursor sits on the last row, and the arithmetic below starts from exactly
+        // that assumption; the append path erases nothing, so it stays the honest answer and
+        // keeps its bytes exactly as they were (I-B7).
+        const capacity = anchor.kind === 'pinned' ? Math.min(canvasRows, room) : 0;
+        if (capacity < 1) {
+            reset();
+            return;
+        }
+        trimCanvasCache(capacity);
+        anchor = { kind: 'pinned', top: room - capacity, capacity };
+        seedDownToTop = 0;
+        lastRows = rows;
+        // The re-draw this answers is the host's, deferred and coalesced (P0-2 / P0-3):
+        // `anchorDirty` is what lets a `repaint()` land while the feed is idle.
+        anchorDirty = true;
+        publishAnchorStats();
+        // Re-measure anyway (I-B14). Keeping the canvas is a bet that the parked row is still
+        // `rows - 1`, and only a measurement can confirm the terminal agrees; dropping the
+        // probe here would leave a wrong geometry with nothing left to correct it. A drag
+        // that fires dozens of resize events still costs one probe: the host coalesces them
+        // (P1-3 / E6), and `anchorReprobes` counts measurements, never requests.
+        requestProbe();
+    };
     /**
      * Bring `top + capacity` back in line with the live `rows - 1` BEFORE the batch
      * reads either of them (§6.11, [P0-2]).
@@ -235,7 +308,10 @@ export function createScrollbackWriter(o) {
             lastRows = rows;
             return;
         }
-        reset();
+        // The `resize` event can arrive a whole frame late, and on a terminal that never
+        // answers CPR it never arrives at all: this batch is then the last chance to keep
+        // the canvas instead of dropping it (I-B17, W6).
+        repinShrunk(rows);
     };
     const afterCanvasBatch = (layout, heldNext, frame, raw, cols, rows) => {
         prev = [...new Array(layout.gap).fill(''), ...heldNext, ...frame];
@@ -402,6 +478,23 @@ export function createScrollbackWriter(o) {
         canvasRows = lines.length;
         gapRows = 0;
     };
+    /**
+     * Give way at the TOP of a frame taller than the screen (I-B17 / W4).
+     *
+     * Such a frame cannot be addressed as ONE block, and swallowing it left the PREVIOUS
+     * frame on screen — which is how the status row came to be printed twice. The region's
+     * last rows are the composer and the status line, the two rows a human is interacting
+     * with, so the oldest rows go first and the next (shorter) frame restores the rest.
+     *
+     * BOTH entry points that draw a frame need this: `repaint()` replays the frame it kept,
+     * and that frame can predate a shrink that has since made the screen shorter.
+     */
+    const giveWayAtTop = (lines, rows) => {
+        if (lines.length + 1 <= rows)
+            return lines;
+        stats.tallFramesTrimmed += 1;
+        return lines.slice(lines.length - (rows - 1));
+    };
     const transform = (chunk) => {
         if (finalized)
             return '';
@@ -419,12 +512,7 @@ export function createScrollbackWriter(o) {
         }
         if (lines === null)
             return countFallback(!firstChunk);
-        if (lines.length + 1 > rows) {
-            // Unreachable by construction (I-S1); never erase on a guess.
-            reset();
-            return '';
-        }
-        return assemble(lines, rows, liveCols(), 'frame');
+        return assemble(giveWayAtTop(lines, rows), rows, liveCols(), 'frame');
     };
     const repaint = () => {
         repaintQueued = false;
@@ -437,7 +525,10 @@ export function createScrollbackWriter(o) {
         const rows = liveRows();
         if (rows === undefined || rows < 2)
             return '';
-        return assemble(prevRawFrame, rows, liveCols(), 'repaint');
+        // The kept frame may predate a shrink, so a replay gets the same top give-way as a
+        // live frame (W4): drawing it whole would overflow the new screen and push this
+        // session's own rows into the scrollback through the repaint door.
+        return assemble(giveWayAtTop(prevRawFrame, rows), rows, liveCols(), 'repaint');
     };
     const finalize = (summary) => {
         if (finalized)
@@ -478,8 +569,10 @@ export function createScrollbackWriter(o) {
             }
             if (rowsNow !== undefined && lastRows !== undefined) {
                 if (rowsNow < lastRows) {
-                    // The terminal deleted rows; they are gone and must not be redrawn.
-                    reset();
+                    // I-B17: the screen kept the rows nearest the cursor, so re-pin the canvas onto
+                    // them instead of dropping it. A reset made the next batch a seed over a screen
+                    // that is not empty, which is what left the old status row in the scrollback.
+                    repinShrunk(rowsNow);
                     return;
                 }
                 if (anchor.kind === 'pinned') {
@@ -503,6 +596,12 @@ export function createScrollbackWriter(o) {
                 return;
             const rows = liveRows();
             const capacity = screenCapacity(rows);
+            // I-B17: a measurement can arrive after the terminal got shorter without ever
+            // announcing it (`rows` is read live, the `resize` event is optional). The cache
+            // must then stop describing rows the screen has already dropped, or the reach
+            // below would hand the next batch an erase distance longer than the canvas left.
+            if (rows !== undefined)
+                trimCanvasCache(capacity);
             // I-B14: the report is "rows BELOW the cursor", and the canvas also still owns
             // `canvasRows` rows ABOVE it, so the reachable height is their sum. Keeping only
             // the first term collapses the canvas onto the parked row, and the next batch

package/dist/ui/shortcuts.d.ts

@@ -0,0 +1,81 @@
+/**
+ * THE shortcut table (tui-shortcut-drawer-and-task-summary §4.6 / appendix B).
+ *
+ * ASCII ONLY, AND THAT IS A HARD CONSTRAINT RATHER THAN A STYLE CHOICE: this file
+ * is inside `glyphs.test.ts::inScope` (`ui/` prefix), whose `A-1` case fails on a
+ * single non-ASCII byte. Every `keyword` and `detail` below is English on
+ * purpose; translating them would turn the scanner red, and the only escape
+ * hatch - adding this file to the exemptions - is the thing that helper's own
+ * comment argues against.
+ *
+ * THIS IS THE ONLY TRUTH ABOUT SHORTCUTS. The drawer, `/keys` and the tests all
+ * derive from it, and `shortcut-table.test.ts` holds it in a BIDIRECTIONAL set
+ * relation with `HelpOverlay`'s key column (D-8). The reverse direction is the
+ * one that matters: without it `Alt+K`, `Esc twice` and `Esc again` could sit in
+ * `/help` forever and never appear in the panel whose entire requirement is
+ * "list ALL of them".
+ *
+ * `keyword` IS CAPPED AT 10 CELLS (`SHORTCUT_PANEL_LIMITS.keywordMaxCells`). A
+ * longer one is a spec error, not a width problem: at 80 columns the keyword
+ * column is 11 cells wide, and the only remaining remedy would be truncating it -
+ * which is the exact defect (a column of `promp...`) this table exists to avoid.
+ */
+export type ShortcutGroupId = 'compose' | 'run' | 'panels' | 'session' | 'view';
+/**
+ * When a row can actually be used. Unavailable rows are STILL LISTED - the user
+ * needs to know the key exists - but they render dim and explain themselves in
+ * the detail line when selected.
+ */
+export type ShortcutAvailability = 'always' | 'idle' | 'running' | 'app' | 'native';
+export interface ShortcutEntry {
+    /** Stable id used by tests and by `/keys <query>`. */
+    id: string;
+    /** The primary binding, spelled in full the way `HelpOverlay` spells it. */
+    keys: string;
+    /** One to two words, ASCII only, at most 10 columns. The requirement's second column. */
+    keyword: string;
+    /** One ASCII sentence, shown when the row is selected. */
+    detail: string;
+    group: ShortcutGroupId;
+    availability: ShortcutAvailability;
+    /** Extra spellings that must also resolve in `/keys <query>`. */
+    aliases?: readonly string[];
+}
+export declare const SHORTCUT_GROUPS: readonly {
+    id: ShortcutGroupId;
+    title: string;
+}[];
+/**
+ * The 31 rows, in reading order. Group order is fixed by `SHORTCUT_GROUPS`, and
+ * within a group the order is "how often a user reaches for it", not alphabetical:
+ * a reference panel is scanned from the top.
+ */
+export declare const SHORTCUTS: readonly ShortcutEntry[];
+/**
+ * The longest `keys` string in cells - the input the column derivation needs.
+ *
+ * DERIVED, NEVER HARD-CODED: v1 fixed the key column at 21 cells, which left six
+ * for the keyword at 80 columns and turned `prompt library` into `promp...`. A
+ * derived value cannot go stale the day someone adds a longer binding.
+ */
+export declare function widestKeysCells(entries: readonly ShortcutEntry[]): number;
+/**
+ * Filter for `/keys <query>`: case-insensitive substring over id, keys, keyword
+ * and aliases.
+ *
+ * NO KEYBOARD SEARCH IN THE PANEL ITSELF (§11 F-2): typing would fight `Esc` for
+ * "clear the filter or close the panel", and `Esc` is App-owned. The command is
+ * the zero-conflict way to reach the same filter.
+ */
+export declare function filterShortcuts(entries: readonly ShortcutEntry[], query: string): ShortcutEntry[];
+/**
+ * Whether a row can be used right now.
+ *
+ * `running` MEANS "ONLY WHILE RUNNING", not "unavailable while running" - the two
+ * halves of the table would otherwise need two different predicates, which is the
+ * kind of asymmetry a later reader gets backwards.
+ */
+export declare function isAvailable(entry: ShortcutEntry, context: {
+    native: boolean;
+    running: boolean;
+}): boolean;

package/dist/ui/shortcuts.js

@@ -0,0 +1,221 @@
+/**
+ * THE shortcut table (tui-shortcut-drawer-and-task-summary §4.6 / appendix B).
+ *
+ * ASCII ONLY, AND THAT IS A HARD CONSTRAINT RATHER THAN A STYLE CHOICE: this file
+ * is inside `glyphs.test.ts::inScope` (`ui/` prefix), whose `A-1` case fails on a
+ * single non-ASCII byte. Every `keyword` and `detail` below is English on
+ * purpose; translating them would turn the scanner red, and the only escape
+ * hatch - adding this file to the exemptions - is the thing that helper's own
+ * comment argues against.
+ *
+ * THIS IS THE ONLY TRUTH ABOUT SHORTCUTS. The drawer, `/keys` and the tests all
+ * derive from it, and `shortcut-table.test.ts` holds it in a BIDIRECTIONAL set
+ * relation with `HelpOverlay`'s key column (D-8). The reverse direction is the
+ * one that matters: without it `Alt+K`, `Esc twice` and `Esc again` could sit in
+ * `/help` forever and never appear in the panel whose entire requirement is
+ * "list ALL of them".
+ *
+ * `keyword` IS CAPPED AT 10 CELLS (`SHORTCUT_PANEL_LIMITS.keywordMaxCells`). A
+ * longer one is a spec error, not a width problem: at 80 columns the keyword
+ * column is 11 cells wide, and the only remaining remedy would be truncating it -
+ * which is the exact defect (a column of `promp...`) this table exists to avoid.
+ */
+import { cellWidth } from './layout/cells.js';
+export const SHORTCUT_GROUPS = [
+    { id: 'compose', title: 'COMPOSE' },
+    { id: 'run', title: 'RUN' },
+    { id: 'panels', title: 'PANELS' },
+    { id: 'session', title: 'SESSION' },
+    { id: 'view', title: 'VIEW' },
+];
+/**
+ * The 31 rows, in reading order. Group order is fixed by `SHORTCUT_GROUPS`, and
+ * within a group the order is "how often a user reaches for it", not alphabetical:
+ * a reference panel is scanned from the top.
+ */
+export const SHORTCUTS = [
+    // --- COMPOSE ---------------------------------------------------------------
+    {
+        id: 'enter', keys: 'Enter', keyword: 'send', group: 'compose', availability: 'always',
+        detail: 'Submits when idle; queues as steering while running;'
+            + ' re-pins the view to the newest output.',
+    },
+    {
+        id: 'alt-enter', keys: 'Alt+Enter', keyword: 'newline', group: 'compose',
+        availability: 'always',
+        detail: 'Multiline input; the host may intercept this combination.',
+    },
+    {
+        id: 'shift-enter', keys: 'Shift+Enter', keyword: 'newline', group: 'compose',
+        availability: 'always',
+        detail: 'Needs keyboard enhancement; /terminal-setup explains how to bind it.',
+    },
+    {
+        id: 'ctrl-j', keys: 'Ctrl+J', keyword: 'newline', group: 'compose', availability: 'always',
+        detail: 'Newline fallback that does not depend on keyboard enhancement.',
+    },
+    {
+        id: 'history', keys: 'Up / Down', keyword: 'history', group: 'compose', availability: 'always',
+        detail: 'Recalls earlier prompts when the input box is empty.',
+    },
+    {
+        id: 'paste', keys: 'Paste', keyword: 'paste', group: 'compose', availability: 'always',
+        detail: 'Up to 6 lines inserted as-is; larger becomes [Pasted text #N]; --no-paste disables.',
+    },
+    {
+        id: 'ctrl-o', keys: 'Ctrl+O', keyword: 'expand', group: 'compose', availability: 'always',
+        detail: 'Expands the newest tool output; in native mode it reprints it as a new block.',
+    },
+    {
+        id: 'ctrl-c', keys: 'Ctrl+C', keyword: 'copy/exit', group: 'compose', availability: 'always',
+        aliases: ['Ctrl+C (with a selection)'],
+        detail: 'Copies a pending selection; with a draft x2 clears and x3 exits;'
+            + ' empty input x2 exits.',
+    },
+    // --- RUN -------------------------------------------------------------------
+    {
+        id: 'esc', keys: 'Esc', keyword: 'close', group: 'run', availability: 'always',
+        detail: 'Closes the open overlay or menu; with nothing open it arms the interrupt ladder.',
+    },
+    {
+        id: 'esc-twice', keys: 'Esc twice', keyword: 'interrupt', group: 'run', availability: 'running',
+        aliases: ['Esc again'],
+        detail: 'Requests an interrupt within 1.5s; the next press forces the stop.',
+    },
+    {
+        id: 'shift-tab', keys: 'Shift+Tab', keyword: 'plan mode', group: 'run', availability: 'always',
+        detail: 'Toggles BUILD and PLAN; writes are refused and the agent only investigates.',
+    },
+    {
+        id: 'ctrl-n', keys: 'Ctrl+N', keyword: 'plan mode', group: 'run', availability: 'always',
+        detail: 'The same toggle, for Windows consoles that cannot deliver Shift+Tab.',
+    },
+    {
+        id: 'ctrl-t', keys: 'Ctrl+T', keyword: 'thinking', group: 'run', availability: 'always',
+        detail: "Shows or hides the model's thinking (off by default).",
+    },
+    {
+        id: 'ctrl-r', keys: 'Ctrl+R', keyword: 'redraw', group: 'run', availability: 'always',
+        detail: 'Repaints the whole frame; use it when the terminal is garbled.',
+    },
+    // --- PANELS ----------------------------------------------------------------
+    {
+        id: 'ctrl-g', keys: 'Ctrl+G', keyword: 'all keys', group: 'panels', availability: 'always',
+        detail: 'Opens this panel; a second Ctrl+G closes it. Every shortcut is listed here.',
+    },
+    {
+        id: 'ctrl-b', keys: 'Ctrl+B', keyword: 'agents', group: 'panels', availability: 'always',
+        detail: 'Read-only subagent board: every child, its facts and its timeline.',
+    },
+    {
+        id: 'ctrl-p', keys: 'Ctrl+P', keyword: 'prompts', group: 'panels', availability: 'always',
+        detail: 'Quick prompt library: pick, edit, reorder.',
+    },
+    {
+        id: 'ctrl-k', keys: 'Ctrl+K', keyword: 'kits', group: 'panels', availability: 'always',
+        detail: 'Switch the main / fast / subagent model kit for this session.',
+    },
+    {
+        id: 'ctrl-i', keys: 'Ctrl+I', keyword: 'index', group: 'panels', availability: 'idle',
+        detail: 'Unavailable while running; asks first, then runs the project-indexer skill.',
+    },
+    {
+        id: 'alt-k', keys: 'Alt+K', keyword: 'kill line', group: 'panels', availability: 'always',
+        detail: 'Deletes from the cursor to the end of the line'
+            + ' (this was Ctrl+K before the kit picker).',
+    },
+    {
+        id: 'help', keys: '/help', keyword: 'reference', group: 'panels', availability: 'always',
+        detail: 'Full reference: keys, slash commands, plan mode, team, skills.',
+    },
+    // --- SESSION ---------------------------------------------------------------
+    {
+        id: 'ctrl-l', keys: 'Ctrl+L', keyword: 'branch', group: 'session', availability: 'always',
+        detail: 'Opens this session in a new terminal window with its own session id.',
+    },
+    {
+        id: 'clear', keys: '/clear', keyword: 'new task', group: 'session', availability: 'always',
+        detail: 'Archives the old conversation, clears the context;'
+            + ' the task summary is cleared with it.',
+    },
+    {
+        id: 'resume', keys: '/resume', keyword: 'switch', group: 'session', availability: 'always',
+        detail: 'Loads a saved session; the current session moves to a new id.',
+    },
+    {
+        id: 'session', keys: '/session', keyword: 'identity', group: 'session', availability: 'always',
+        detail: 'Shows the session id and file, copies the resume command, pins the id.',
+    },
+    // --- VIEW ------------------------------------------------------------------
+    {
+        id: 'page', keys: 'PgUp / PgDn', keyword: 'page', group: 'view', availability: 'always',
+        detail: 'Pages the transcript, or the overlay that currently owns the keyboard.',
+    },
+    {
+        id: 'wheel', keys: 'Wheel', keyword: 'scroll', group: 'view', availability: 'app',
+        detail: 'Scrolls the transcript in app mode; in native mode the terminal owns this.',
+    },
+    {
+        id: 'shift-wheel', keys: 'Shift+Wheel', keyword: 'page', group: 'view', availability: 'app',
+        detail: 'Scrolls a whole page.',
+    },
+    {
+        id: 'shift-arrows', keys: 'Shift+Up / Shift+Down', keyword: 'line', group: 'view',
+        availability: 'app',
+        detail: 'Scrolls one line; native mode leaves this to the terminal.',
+    },
+    {
+        id: 'drag-edge', keys: 'Drag right edge', keyword: 'scrollbar', group: 'view',
+        availability: 'app',
+        detail: 'Drags the right-edge scrollbar; the input stays fixed.',
+    },
+    {
+        id: 'drag-text', keys: 'Drag text (left button)', keyword: 'select', group: 'view',
+        availability: 'app',
+        detail: 'Drags to select on-screen text; the highlight waits for a copy.',
+    },
+];
+/**
+ * The longest `keys` string in cells - the input the column derivation needs.
+ *
+ * DERIVED, NEVER HARD-CODED: v1 fixed the key column at 21 cells, which left six
+ * for the keyword at 80 columns and turned `prompt library` into `promp...`. A
+ * derived value cannot go stale the day someone adds a longer binding.
+ */
+export function widestKeysCells(entries) {
+    return entries.reduce((widest, entry) => Math.max(widest, cellWidth(entry.keys)), 0);
+}
+/**
+ * Filter for `/keys <query>`: case-insensitive substring over id, keys, keyword
+ * and aliases.
+ *
+ * NO KEYBOARD SEARCH IN THE PANEL ITSELF (§11 F-2): typing would fight `Esc` for
+ * "clear the filter or close the panel", and `Esc` is App-owned. The command is
+ * the zero-conflict way to reach the same filter.
+ */
+export function filterShortcuts(entries, query) {
+    const needle = query.trim().toLowerCase();
+    if (needle.length === 0)
+        return [...entries];
+    return entries.filter((entry) => {
+        const haystack = [entry.id, entry.keys, entry.keyword, ...(entry.aliases ?? [])];
+        return haystack.some((field) => field.toLowerCase().includes(needle));
+    });
+}
+/**
+ * Whether a row can be used right now.
+ *
+ * `running` MEANS "ONLY WHILE RUNNING", not "unavailable while running" - the two
+ * halves of the table would otherwise need two different predicates, which is the
+ * kind of asymmetry a later reader gets backwards.
+ */
+export function isAvailable(entry, context) {
+    switch (entry.availability) {
+        case 'always': return true;
+        case 'idle': return !context.running;
+        case 'running': return context.running;
+        case 'app': return !context.native;
+        case 'native': return context.native;
+        default: return true;
+    }
+}