@timurproko/a1 0.1.8-dev.ece8cef → 0.2.1-dev.590

package/dist/ui/components/mouse.js

@@ -0,0 +1,72 @@
+/**
+ * SGR mouse reporting. A screen that wants hover, click, and drag needs the
+ * terminal to send reports; nothing else in A1 turns this on, and the sequences
+ * are paired so the terminal is always left as it was found.
+ */
+export const MOUSE_TRACKING_ON = "\u001b[?1006h\u001b[?1000h\u001b[?1003h\u001b[?1004h";
+export const MOUSE_TRACKING_OFF = "\u001b[?1004l\u001b[?1003l\u001b[?1000l\u001b[?1006l";
+const SGR_PATTERN = /\u001b\[<(\d+);(\d+);(\d+)([Mm])/g;
+/** Extracts SGR mouse reports, leaving any keyboard input untouched. */
+export function parseMouseInput(data) {
+    if (!data.includes("\u001b[<"))
+        return { events: [], rest: data };
+    const events = [];
+    let rest = "";
+    let index = 0;
+    SGR_PATTERN.lastIndex = 0;
+    for (let match = SGR_PATTERN.exec(data); match !== null; match = SGR_PATTERN.exec(data)) {
+        rest += data.slice(index, match.index);
+        index = match.index + match[0].length;
+        const code = Number.parseInt(match[1] ?? "", 10);
+        const column = Number.parseInt(match[2] ?? "", 10);
+        const row = Number.parseInt(match[3] ?? "", 10);
+        const released = match[4] === "m";
+        if (!Number.isInteger(code) || !Number.isInteger(column) || !Number.isInteger(row))
+            continue;
+        const event = toEvent(code, column, row, released);
+        if (event !== null)
+            events.push(event);
+    }
+    rest += data.slice(index);
+    return { events: Object.freeze(events), rest };
+}
+/**
+ * Routes every SGR report independently, preserving keyboard bytes and mouse
+ * reports the caller does not claim even when they share one physical chunk.
+ */
+export function routeMouseInput(data, claim) {
+    if (!data.includes("\u001b[<"))
+        return { data, consumed: false };
+    let output = "";
+    let index = 0;
+    let consumed = false;
+    // Concurrency: reentrant routing may deliver a report to another component using this parser.
+    const pattern = new RegExp(SGR_PATTERN.source, "g");
+    for (let match = pattern.exec(data); match !== null; match = pattern.exec(data)) {
+        output += data.slice(index, match.index);
+        index = match.index + match[0].length;
+        const event = toEvent(Number(match[1]), Number(match[2]), Number(match[3]), match[4] === "m");
+        if (event === null || claim(event, match[0]))
+            consumed = true;
+        else
+            output += match[0];
+    }
+    output += data.slice(index);
+    return { data: output, consumed };
+}
+function toEvent(code, column, row, released) {
+    if ((code & 66) === 66)
+        return null;
+    if ((code & 64) !== 0) {
+        const kind = (code & 1) === 0 ? "wheel-up" : "wheel-down";
+        return { kind, button: 0, column, row };
+    }
+    const button = code & 3;
+    if ((code & 32) !== 0)
+        return { kind: "motion", button, column, row };
+    if (released)
+        return { kind: "release", button, column, row };
+    if (button === 3)
+        return { kind: "release", button: 0, column, row };
+    return { kind: "press", button, column, row };
+}

package/dist/ui/components/progress-status.d.ts

@@ -0,0 +1,9 @@
+export type ProgressStatusMarker = "…" | "...";
+export interface ProgressStatusFrameStyles {
+    readonly muted: (text: string) => string;
+    readonly accent: (text: string) => string;
+}
+/** Returns spinner-backed status text with the selected terminal progress marker. */
+export declare function progressStatusText(message: string, marker?: ProgressStatusMarker): string;
+/** Paints one width-stable, grapheme-safe frame of the quiet progress-label sweep. */
+export declare function progressStatusFrame(message: string, phase: number, styles: ProgressStatusFrameStyles): string;

package/dist/ui/components/progress-status.js

@@ -0,0 +1,25 @@
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const HIGHLIGHT_WIDTH = 2;
+const UPDATES_PER_STEP = 3;
+/** Returns spinner-backed status text with the selected terminal progress marker. */
+export function progressStatusText(message, marker = "…") {
+    return `${message.replace(/(?:…|\.+)$/u, "")}${marker}`;
+}
+/** Paints one width-stable, grapheme-safe frame of the quiet progress-label sweep. */
+export function progressStatusFrame(message, phase, styles) {
+    const marker = message.endsWith("…") ? "…" : "";
+    const label = marker === "" ? message : message.slice(0, -marker.length);
+    const graphemes = [...GRAPHEMES.segment(label)].map(segment => segment.segment);
+    if (graphemes.length === 0)
+        return paint(marker, styles.muted);
+    const step = Math.floor(Math.max(0, phase) / UPDATES_PER_STEP) % (graphemes.length * 2);
+    if (step >= graphemes.length)
+        return paint(`${label}${marker}`, styles.muted);
+    const before = graphemes.slice(0, step).join("");
+    const highlight = graphemes.slice(step, step + HIGHLIGHT_WIDTH).join("");
+    const after = `${graphemes.slice(step + HIGHLIGHT_WIDTH).join("")}${marker}`;
+    return `${paint(before, styles.muted)}${paint(highlight, styles.accent)}${paint(after, styles.muted)}`;
+}
+function paint(text, style) {
+    return text === "" ? "" : style(text);
+}

package/dist/ui/components/prompt-input.d.ts

@@ -0,0 +1,32 @@
+import { type UiTheme } from "./theme.js";
+export declare const PROMPT_GLYPH = "\u276F ";
+export declare const PROMPT_PREFIX_WIDTH = 2;
+export declare function promptRuleText(text: string): string;
+export declare function promptRule(width: number): string;
+export declare function promptArrow(text: string, theme: Pick<UiTheme, "fg">): string;
+export interface PromptInputBody {
+    readonly rows: readonly string[];
+    /** Semantic border fragments retain editor history and scroll annotations. */
+    readonly topRule?: string | undefined;
+    readonly bottomRule?: string | undefined;
+    readonly after?: readonly string[];
+}
+export interface PromptInputMetrics {
+    readonly measure: (text: string) => number;
+    readonly truncate: (text: string, width: number) => string;
+}
+/** Composes shared input chrome around controller-owned body rows without owning editing state. */
+export declare class PromptInput {
+    readonly theme: Pick<UiTheme, "fg">;
+    readonly metrics: PromptInputMetrics;
+    constructor(theme?: Pick<UiTheme, "fg">, metrics?: PromptInputMetrics);
+    styleRule(text: string): string;
+    geometry(width: number, padding?: number): {
+        prefixWidth: number;
+        innerWidth: number;
+        paddingX: number;
+        contentWidth: number;
+        layoutWidth: number;
+    };
+    render(width: number, renderBody: (innerWidth: number) => PromptInputBody, ruled?: boolean, padding?: number): string[];
+}

package/dist/ui/components/prompt-input.js

@@ -0,0 +1,51 @@
+import { displayWidth, truncateToWidth } from "./text.js";
+import { PLAIN_THEME } from "./theme.js";
+export const PROMPT_GLYPH = "❯ ";
+export const PROMPT_PREFIX_WIDTH = 2;
+export function promptRuleText(text) {
+    return `\u001b[38;2;154;160;166m${text}\u001b[39m`;
+}
+export function promptRule(width) {
+    return promptRuleText("─".repeat(Math.max(0, width)));
+}
+export function promptArrow(text, theme) {
+    return theme.fg("muted", text);
+}
+/** Composes shared input chrome around controller-owned body rows without owning editing state. */
+export class PromptInput {
+    theme;
+    metrics;
+    constructor(theme = PLAIN_THEME, metrics = { measure: displayWidth, truncate: truncateToWidth }) { this.theme = theme; this.metrics = metrics; }
+    styleRule(text) { return promptRuleText(text); }
+    geometry(width, padding = 0) {
+        const prefixWidth = Math.min(PROMPT_PREFIX_WIDTH, Math.max(0, width));
+        // Compatibility: editor wrapping needs room for a two-cell grapheme plus its cursor cell.
+        // Lay out against a safe virtual width, then clip only at the shared frame boundary.
+        const innerWidth = Math.max(3 + padding * 2, width - prefixWidth);
+        const paddingX = Math.min(padding, Math.max(0, Math.floor((innerWidth - 1) / 2)));
+        const contentWidth = Math.max(1, innerWidth - paddingX * 2);
+        return { prefixWidth, innerWidth, paddingX, contentWidth, layoutWidth: Math.max(1, contentWidth - (paddingX ? 0 : 1)) };
+    }
+    render(width, renderBody, ruled = true, padding = 0) {
+        if (width <= 0)
+            return [];
+        const { prefixWidth, innerWidth } = this.geometry(width, padding);
+        const body = renderBody(innerWidth);
+        const fit = (row) => {
+            const clipped = this.metrics.truncate(row, width);
+            return clipped + " ".repeat(Math.max(0, width - this.metrics.measure(clipped)));
+        };
+        const rows = body.rows.map((row, index) => fit(`${index === 0
+            ? promptArrow(PROMPT_GLYPH, this.theme)
+            : " ".repeat(prefixWidth)}${row}`));
+        const rule = (fragment) => fragment === undefined
+            ? promptRule(width)
+            : fit(fragment + promptRule(Math.max(0, width - this.metrics.measure(fragment))));
+        return [
+            ...(ruled ? [rule(body.topRule)] : []),
+            ...rows,
+            ...(ruled ? [rule(body.bottomRule)] : []),
+            ...(body.after ?? []).map(row => fit(`${" ".repeat(prefixWidth)}${row}`)),
+        ];
+    }
+}

package/dist/ui/components/scrollbar.d.ts

@@ -0,0 +1,88 @@
+/**
+ * One scrollbar for every scrollable surface. Hover and drag belong to a named
+ * rail rather than to a global, because two scrollable surfaces can be visible
+ * at once and a shared flag lights up the wrong one.
+ */
+export interface ScrollbarGeometry {
+    /** Rows in the track. */
+    readonly trackHeight: number;
+    /** Thumb height in rows, at least one. */
+    readonly thumbHeight: number;
+    /** Zero-based row of the thumb's top within the track. */
+    readonly thumbTop: number;
+    /** Highest scroll position the content allows. */
+    readonly maxScroll: number;
+}
+export interface ScrollbarInput {
+    readonly contentLength: number;
+    readonly viewportHeight: number;
+    readonly scroll: number;
+    readonly trackHeight: number;
+}
+export type ScrollbarAppearance = "auto" | "always" | "hidden";
+export type ScrollbarStyle = "thin" | "thick";
+export type ScrollbarSpeed = "normal" | "fast" | "high";
+/** Wheel distance: normal (3), fast (6), high as normal + fast (9). */
+export declare function scrollbarWheelRows(speed: ScrollbarSpeed): number;
+/** Selection edge distance per auto-scroll tick: normal (1), fast (2), high (3). */
+export declare function scrollbarSelectionRows(speed: ScrollbarSpeed): number;
+export interface ScrollbarPresentationInput {
+    readonly geometry: ScrollbarGeometry | null;
+    readonly appearance: ScrollbarAppearance;
+    readonly style: ScrollbarStyle;
+    readonly hovered: boolean;
+    readonly dragging: boolean;
+    readonly activeUntil: number;
+    readonly now: number;
+}
+export interface ScrollbarPresentation {
+    readonly visible: boolean;
+    readonly reservesSpace: boolean;
+    readonly trackGlyph: "│" | "┃";
+    readonly thumbGlyph: "│" | "┃";
+}
+/** Pure appearance decision; activity time is supplied so tests own the clock. */
+export declare function scrollbarPresentation(input: ScrollbarPresentationInput): ScrollbarPresentation;
+/** Null when the content fits: no scrollbar is drawn and no width is reserved. */
+export declare function scrollbarGeometry(input: ScrollbarInput): ScrollbarGeometry | null;
+export declare function scrollbarReservesSpace(geometry: ScrollbarGeometry | null): boolean;
+/** True when this track row is part of the thumb. */
+export declare function isThumbRow(geometry: ScrollbarGeometry | null, trackRow: number): boolean;
+/** Scroll position for a thumb dragged to a track row. */
+export declare function scrollForThumbRow(geometry: ScrollbarGeometry | null, trackRow: number): number;
+/** Scroll position after paging on the track above or below the thumb. */
+export declare function scrollForTrackPage(geometry: ScrollbarGeometry | null, trackRow: number, scroll: number, viewportHeight: number): number;
+export interface RailPosition {
+    /** Identity of this rail. Two surfaces never share one. */
+    readonly key: string;
+    /** Column the rail is drawn in, one-based. */
+    readonly column: number;
+    /** First row of the track within the surface, zero-based. */
+    readonly rowStart: number;
+    readonly trackHeight: number;
+}
+export interface RailPointer {
+    readonly column: number;
+    readonly row: number;
+}
+/**
+ * Hover and drag state for every rail on screen. State is keyed by rail, so a
+ * pointer over one rail cannot make another appear hot, and a drag started on
+ * one rail cannot be continued by a report addressed to another.
+ */
+export declare class ScrollbarRails {
+    #private;
+    noteActivity(key: string, now: number, lingerMs?: number): void;
+    isRecentlyActive(key: string, now: number): boolean;
+    isHovered(key: string): boolean;
+    isDragging(key: string): boolean;
+    get draggingKey(): string | null;
+    /** Records the pointer position. Returns the rail it is over, if any. */
+    notePointer(rails: readonly RailPosition[], pointer: RailPointer): string | null;
+    /** Starts a drag when the pointer is on that rail's thumb. */
+    beginDrag(rail: RailPosition, geometry: ScrollbarGeometry | null, pointer: RailPointer): boolean;
+    /** Scroll position for a drag in progress, or null when this rail is not being dragged. */
+    dragTo(rail: RailPosition, geometry: ScrollbarGeometry | null, pointer: RailPointer): number | null;
+    endDrag(): void;
+    clear(): void;
+}

package/dist/ui/components/scrollbar.js

@@ -0,0 +1,137 @@
+/**
+ * One scrollbar for every scrollable surface. Hover and drag belong to a named
+ * rail rather than to a global, because two scrollable surfaces can be visible
+ * at once and a shared flag lights up the wrong one.
+ */
+/** Wheel distance: normal (3), fast (6), high as normal + fast (9). */
+export function scrollbarWheelRows(speed) {
+    return speed === "high" ? 9 : speed === "fast" ? 6 : 3;
+}
+/** Selection edge distance per auto-scroll tick: normal (1), fast (2), high (3). */
+export function scrollbarSelectionRows(speed) {
+    return speed === "high" ? 3 : speed === "fast" ? 2 : 1;
+}
+/** Pure appearance decision; activity time is supplied so tests own the clock. */
+export function scrollbarPresentation(input) {
+    const overflowing = input.geometry !== null;
+    // Invariant: auto/always reserve the final rail cell even while content fits.
+    // The blank gutter prevents prompt timestamps from touching the terminal edge
+    // and keeps later scrollbar appearance from reflowing the transcript.
+    const reservesSpace = input.appearance !== "hidden";
+    const visible = overflowing && reservesSpace && (input.appearance === "always"
+        || input.hovered
+        || input.dragging
+        || (input.activeUntil > 0 && input.now <= input.activeUntil));
+    const thick = input.style === "thick";
+    return {
+        visible,
+        reservesSpace,
+        trackGlyph: thick ? "┃" : "│",
+        thumbGlyph: thick || input.hovered || input.dragging ? "┃" : "│",
+    };
+}
+/** Null when the content fits: no scrollbar is drawn and no width is reserved. */
+export function scrollbarGeometry(input) {
+    const { contentLength, viewportHeight, trackHeight } = input;
+    if (trackHeight <= 0 || viewportHeight <= 0)
+        return null;
+    if (contentLength <= viewportHeight)
+        return null;
+    const maxScroll = contentLength - viewportHeight;
+    const scroll = Math.min(Math.max(input.scroll, 0), maxScroll);
+    const thumbHeight = Math.max(1, Math.min(trackHeight, Math.round(trackHeight * viewportHeight / contentLength)));
+    const travel = trackHeight - thumbHeight;
+    const thumbTop = maxScroll === 0 ? 0 : Math.min(travel, Math.round(travel * scroll / maxScroll));
+    return { trackHeight, thumbHeight, thumbTop, maxScroll };
+}
+export function scrollbarReservesSpace(geometry) {
+    return geometry !== null;
+}
+/** True when this track row is part of the thumb. */
+export function isThumbRow(geometry, trackRow) {
+    if (geometry === null)
+        return false;
+    return trackRow >= geometry.thumbTop && trackRow < geometry.thumbTop + geometry.thumbHeight;
+}
+/** Scroll position for a thumb dragged to a track row. */
+export function scrollForThumbRow(geometry, trackRow) {
+    if (geometry === null)
+        return 0;
+    const travel = geometry.trackHeight - geometry.thumbHeight;
+    if (travel <= 0)
+        return 0;
+    const clamped = Math.min(Math.max(trackRow, 0), travel);
+    return Math.round(clamped * geometry.maxScroll / travel);
+}
+/** Scroll position after paging on the track above or below the thumb. */
+export function scrollForTrackPage(geometry, trackRow, scroll, viewportHeight) {
+    if (geometry === null)
+        return scroll;
+    const page = Math.max(1, viewportHeight);
+    const next = trackRow < geometry.thumbTop ? scroll - page : scroll + page;
+    return Math.min(Math.max(next, 0), geometry.maxScroll);
+}
+/**
+ * Hover and drag state for every rail on screen. State is keyed by rail, so a
+ * pointer over one rail cannot make another appear hot, and a drag started on
+ * one rail cannot be continued by a report addressed to another.
+ */
+export class ScrollbarRails {
+    #hovered = new Set();
+    #activeUntil = new Map();
+    #dragging;
+    noteActivity(key, now, lingerMs = 900) {
+        this.#activeUntil.set(key, Math.max(this.#activeUntil.get(key) ?? 0, now + Math.max(0, lingerMs)));
+    }
+    isRecentlyActive(key, now) {
+        return now <= (this.#activeUntil.get(key) ?? 0);
+    }
+    isHovered(key) {
+        return this.#hovered.has(key);
+    }
+    isDragging(key) {
+        return this.#dragging?.key === key;
+    }
+    get draggingKey() {
+        return this.#dragging?.key ?? null;
+    }
+    /** Records the pointer position. Returns the rail it is over, if any. */
+    notePointer(rails, pointer) {
+        this.#hovered.clear();
+        for (const rail of rails) {
+            if (pointer.column !== rail.column)
+                continue;
+            const trackRow = pointer.row - rail.rowStart;
+            if (trackRow < 0 || trackRow >= rail.trackHeight)
+                continue;
+            this.#hovered.add(rail.key);
+            return rail.key;
+        }
+        return null;
+    }
+    /** Starts a drag when the pointer is on that rail's thumb. */
+    beginDrag(rail, geometry, pointer) {
+        if (geometry === null || pointer.column !== rail.column)
+            return false;
+        const trackRow = pointer.row - rail.rowStart;
+        if (!isThumbRow(geometry, trackRow))
+            return false;
+        this.#dragging = { key: rail.key, grabOffset: trackRow - geometry.thumbTop };
+        return true;
+    }
+    /** Scroll position for a drag in progress, or null when this rail is not being dragged. */
+    dragTo(rail, geometry, pointer) {
+        const dragging = this.#dragging;
+        if (dragging === undefined || dragging.key !== rail.key || geometry === null)
+            return null;
+        return scrollForThumbRow(geometry, pointer.row - rail.rowStart - dragging.grabOffset);
+    }
+    endDrag() {
+        this.#dragging = undefined;
+    }
+    clear() {
+        this.#hovered.clear();
+        this.#activeUntil.clear();
+        this.#dragging = undefined;
+    }
+}

package/dist/ui/components/selection-copy.d.ts

@@ -0,0 +1,24 @@
+import { type OrderedTextSelection, type TextSelectionLineContent } from "./text-selection.js";
+/** Bound selected-source retention independently of history length and encoded payload size. */
+export declare const MAX_COPY_SOURCE_UNITS: number;
+export declare const MAX_COPY_ROWS = 65536;
+export type SelectionCopyPrompt = "first" | "continuation" | undefined;
+export interface SelectionCopyRow {
+    readonly text: string;
+    readonly prompt?: "first" | "continuation";
+}
+/** Immutable selected rows only; safe to transfer to an isolated text preparer. */
+export interface SelectionCopySnapshot {
+    readonly selection: OrderedTextSelection;
+    readonly revision: number;
+    /** Prompt copy/cut already supplies exact expanded text; do not apply transcript chrome stripping. */
+    readonly literal?: boolean;
+    readonly rows: readonly SelectionCopyRow[];
+    readonly sourceUnits: number;
+    readonly captureMs?: number;
+    readonly rejected?: "size";
+}
+/** Shares the viewport's semantic chrome exclusions with isolated copy preparation. */
+export declare function selectionCopyLineContent(text: string, prompt: SelectionCopyPrompt): TextSelectionLineContent;
+/** Extracts one snapshot row with the existing grapheme/newline policy; run expensive rows off-thread. */
+export declare function selectionCopyRowText(snapshot: Pick<SelectionCopySnapshot, "selection" | "literal">, row: SelectionCopyRow, index: number): string;

package/dist/ui/components/selection-copy.js

@@ -0,0 +1,39 @@
+import { textSelectionText, usefulTextLineContent } from "./text-selection.js";
+import { stripAnsi } from "./text.js";
+/** Bound selected-source retention independently of history length and encoded payload size. */
+export const MAX_COPY_SOURCE_UNITS = 32 * 1024 * 1024;
+export const MAX_COPY_ROWS = 65_536;
+/** Shares the viewport's semantic chrome exclusions with isolated copy preparation. */
+export function selectionCopyLineContent(text, prompt) {
+    const plain = stripAnsi(text);
+    if (prompt !== undefined) {
+        if (prompt === "first") {
+            const timestamp = /\s+\d{2}:\d{2}\s*$/.exec(plain);
+            if (timestamp !== null)
+                return usefulTextLineContent(plain.slice(0, timestamp.index), 3);
+        }
+        return usefulTextLineContent(plain, 3);
+    }
+    const from = plain.trim().length === 0 || (plain.startsWith(" ") && !plain.startsWith("  ")) ? 2 : 1;
+    if (plain.trim().length === 0)
+        return { from, to: from + 1 };
+    return usefulTextLineContent(plain, from);
+}
+/** Extracts one snapshot row with the existing grapheme/newline policy; run expensive rows off-thread. */
+export function selectionCopyRowText(snapshot, row, index) {
+    if (snapshot.literal)
+        return row.text;
+    let plain = stripAnsi(row.text);
+    if (row.prompt === "first") {
+        const timestamp = /\s+\d{2}:\d{2}\s*$/.exec(plain);
+        if (timestamp !== null)
+            plain = plain.slice(0, timestamp.index);
+    }
+    const from = row.prompt !== undefined ? 3 : plain.startsWith(" ") && !plain.startsWith("  ") ? 2 : 1;
+    // Performance: trailing chrome is excluded before extraction; full-row copy need not measure every grapheme.
+    plain = plain.trimEnd();
+    return textSelectionText({
+        start: { line: 0, column: index === snapshot.selection.start.line ? snapshot.selection.start.column : 0 },
+        end: { line: 0, column: index === snapshot.selection.end.line ? snapshot.selection.end.column : Number.MAX_SAFE_INTEGER },
+    }, [plain], () => ({ from }));
+}

package/dist/ui/components/shortcut-hints.d.ts

@@ -0,0 +1,7 @@
+import { type SemanticShortcutHint } from "../../contracts/presentation/index.js";
+import type { UiTheme } from "./theme.js";
+export type ShortcutHintEntry = SemanticShortcutHint;
+/** Returns an unstyled modal instruction row for width-aware clipping. */
+export declare function shortcutHintsText(entries: readonly ShortcutHintEntry[], indent?: number): string;
+/** Paints one modal instruction row without decorative separator glyphs. */
+export declare function renderShortcutHints(entries: readonly ShortcutHintEntry[], theme: Pick<UiTheme, "fg">, indent?: number): string;

package/dist/ui/components/shortcut-hints.js

@@ -0,0 +1,12 @@
+import { renderSemanticShortcutHints, } from "../../contracts/presentation/index.js";
+/** Returns an unstyled modal instruction row for width-aware clipping. */
+export function shortcutHintsText(entries, indent = 0) {
+    return renderSemanticShortcutHints(entries, { key: text => text, action: text => text }, indent);
+}
+/** Paints one modal instruction row without decorative separator glyphs. */
+export function renderShortcutHints(entries, theme, indent = 0) {
+    return renderSemanticShortcutHints(entries, {
+        key: text => theme.fg("dim", text),
+        action: text => theme.fg("muted", text),
+    }, indent);
+}

package/dist/ui/components/shortcuts.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shortcuts as declared data. Dispatch resolves a key through declarations
+ * rather than inline comparisons, conflicts are reported when the registry is
+ * assembled, and any listing is generated from the same declarations — so a
+ * listed shortcut is one dispatch would actually invoke.
+ */
+import type { ShortcutHintEntry } from "./shortcut-hints.js";
+export interface ShortcutDeclaration {
+    /** Key token, for example `up`, `shift+down`, `ctrl+c`, or a literal character. */
+    readonly key: string;
+    /** Screen this applies to, or `global` for every screen. */
+    readonly scope: string;
+    readonly description: string;
+    /** Grouping label for the listing. */
+    readonly section?: string;
+    /**
+     * How this key reads on a screen's hint line, when it belongs there. Keys that
+     * do one thing together — the two arrows, enter and space — declare the same
+     * pair and are shown once.
+     */
+    readonly hint?: {
+        readonly keys: string;
+        readonly does: string;
+    };
+}
+export declare const GLOBAL_SCOPE = "global";
+export interface ShortcutConflict {
+    readonly key: string;
+    readonly scopes: readonly [string, string];
+    readonly descriptions: readonly [string, string];
+    readonly kind: "duplicate" | "shadowed";
+}
+export interface ShortcutRegistryResult {
+    readonly declarations: readonly ShortcutDeclaration[];
+    readonly conflicts: readonly ShortcutConflict[];
+}
+/**
+ * Assembles declarations and reports every key claimed twice in overlapping
+ * scopes. A screen claiming a global key is reported as shadowed rather than
+ * silently resolved by declaration order.
+ */
+export declare function assembleShortcuts(declarations: readonly ShortcutDeclaration[]): ShortcutRegistryResult;
+export declare function assertNoShortcutConflicts(result: ShortcutRegistryResult): void;
+/** Keeps shortcut dispatch and reader-facing listings derived from one ordered declaration set. */
+export declare class ShortcutRegistry<Action extends string = string> {
+    #private;
+    declare(declaration: ShortcutDeclaration, action: Action): void;
+    /** The action this key invokes in this scope, preferring a screen over a global. */
+    resolve(key: string, scope: string): Action | null;
+    assemble(): ShortcutRegistryResult;
+    /**
+     * The hint line, in the order the screen declares its keys. It is rendered from
+     * the same declarations dispatch reads, so a key cannot be described here and
+     * bound to something else, or bound and never mentioned.
+     */
+    hintEntries(scope: string): readonly ShortcutHintEntry[];
+    hint(scope: string, separator?: string): string;
+    /** The listing, derived from the declarations dispatch reads. */
+    list(scope?: string): readonly ShortcutDeclaration[];
+}

package/dist/ui/components/shortcuts.js

@@ -0,0 +1,85 @@
+/**
+ * Shortcuts as declared data. Dispatch resolves a key through declarations
+ * rather than inline comparisons, conflicts are reported when the registry is
+ * assembled, and any listing is generated from the same declarations — so a
+ * listed shortcut is one dispatch would actually invoke.
+ */
+export const GLOBAL_SCOPE = "global";
+function overlaps(left, right) {
+    return left === right || left === GLOBAL_SCOPE || right === GLOBAL_SCOPE;
+}
+/**
+ * Assembles declarations and reports every key claimed twice in overlapping
+ * scopes. A screen claiming a global key is reported as shadowed rather than
+ * silently resolved by declaration order.
+ */
+export function assembleShortcuts(declarations) {
+    const conflicts = [];
+    for (let left = 0; left < declarations.length; left++) {
+        for (let right = left + 1; right < declarations.length; right++) {
+            const a = declarations[left];
+            const b = declarations[right];
+            if (a === undefined || b === undefined)
+                continue;
+            if (a.key !== b.key || !overlaps(a.scope, b.scope))
+                continue;
+            conflicts.push({
+                key: a.key,
+                scopes: [a.scope, b.scope],
+                descriptions: [a.description, b.description],
+                kind: a.scope === b.scope ? "duplicate" : "shadowed",
+            });
+        }
+    }
+    return { declarations: Object.freeze([...declarations]), conflicts: Object.freeze(conflicts) };
+}
+export function assertNoShortcutConflicts(result) {
+    const duplicate = result.conflicts.find(conflict => conflict.kind === "duplicate");
+    if (duplicate) {
+        throw new Error(`shortcut ${duplicate.key} is declared twice in scope ${duplicate.scopes[0]}: `
+            + `"${duplicate.descriptions[0]}" and "${duplicate.descriptions[1]}"`);
+    }
+}
+/** Keeps shortcut dispatch and reader-facing listings derived from one ordered declaration set. */
+export class ShortcutRegistry {
+    #declarations = [];
+    #actions = new Map();
+    declare(declaration, action) {
+        this.#declarations.push(declaration);
+        this.#actions.set(`${declaration.scope}\u0000${declaration.key}`, action);
+    }
+    /** The action this key invokes in this scope, preferring a screen over a global. */
+    resolve(key, scope) {
+        return this.#actions.get(`${scope}\u0000${key}`) ?? this.#actions.get(`${GLOBAL_SCOPE}\u0000${key}`) ?? null;
+    }
+    assemble() {
+        return assembleShortcuts(this.#declarations);
+    }
+    /**
+     * The hint line, in the order the screen declares its keys. It is rendered from
+     * the same declarations dispatch reads, so a key cannot be described here and
+     * bound to something else, or bound and never mentioned.
+     */
+    hintEntries(scope) {
+        const shown = new Map();
+        for (const declaration of this.#declarations) {
+            if (declaration.hint === undefined)
+                continue;
+            if (declaration.scope !== scope && declaration.scope !== GLOBAL_SCOPE)
+                continue;
+            if (!shown.has(declaration.hint.keys))
+                shown.set(declaration.hint.keys, declaration.hint.does);
+        }
+        return Object.freeze([...shown].map(([key, action]) => ({ key, action })));
+    }
+    hint(scope, separator = " · ") {
+        return this.hintEntries(scope).map(({ key, action }) => `${key} ${action}`).join(separator);
+    }
+    /** The listing, derived from the declarations dispatch reads. */
+    list(scope) {
+        const inScope = scope === undefined
+            ? this.#declarations
+            : this.#declarations.filter(declaration => declaration.scope === scope || declaration.scope === GLOBAL_SCOPE);
+        return Object.freeze([...inScope].sort((left, right) => (left.section ?? "").localeCompare(right.section ?? "") || left.key.localeCompare(right.key)));
+    }
+}