@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.226

package/dist/{src/foundation/ui-apps → ui/apps}/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { PaneInputResult, PaneMouseEvent, PaneRect, UiTheme } from "../ui-components/index.js";
+import type { PaneInputResult, PaneMouseEvent, PaneRect, RenderCacheContract, UiTheme } from "../components/index.js";
 export interface AppSize {
     readonly width: number;
     readonly height: number;
@@ -27,6 +27,8 @@ export interface AppHostServices {
 }
 export interface UiApp {
     readonly id: string;
+    /** Optional declared revisions used by the host's shared frame cache. */
+    readonly renderCache?: RenderCacheContract;
     render(rect: PaneRect, host: AppHostServices): readonly string[];
     onInput?(data: string, host: AppHostServices): PaneInputResult;
     onMouse?(event: PaneMouseEvent, host: AppHostServices): PaneInputResult;
@@ -39,4 +41,24 @@ export interface AppRegistration {
     readonly route: string;
     create(): UiApp;
 }
+/** A neutral owned-app surface mounted by a surrounding presentation runtime. */
+export interface UiRouteSurface {
+    readonly id: string;
+    /** Renders exactly `height` rows of at most `width` columns. */
+    render(width: number, height: number): readonly string[];
+    /** True when the key was consumed; false leaves it to the surrounding shell. */
+    handleInput(data: string): boolean;
+    /** Mouse report in surface-local coordinates. True when consumed. */
+    handleMouse(event: PaneMouseEvent): boolean;
+    isClosed(): boolean;
+    close(): void;
+    onRenderRequested(listener: () => void): void;
+    /** The surface asks to leave A1 entirely, not merely to close itself. */
+    onExitRequested(listener: () => void): void;
+}
+/** Route lookup seam shared by owned apps and any presentation runtime hosting them. */
+export interface UiRouteHost {
+    claims(route: string): boolean;
+    open(route: string): UiRouteSurface | null;
+}
 export declare function assertAppRegistration(registration: AppRegistration): void;

package/dist/{src/foundation/ui-apps → ui/apps}/host.d.ts

@@ -1,4 +1,4 @@
-import { type PaneInputResult, type PaneMouseEvent, type UiTheme } from "../ui-components/index.js";
+import { type PaneInputResult, type PaneMouseEvent, type UiTheme } from "../components/index.js";
 import type { AppSize, UiApp } from "./contracts.js";
 import type { UiAppRegistry } from "./registry.js";
 export interface AppHostSurface {

package/dist/{src/foundation/ui-apps → ui/apps}/host.js

@@ -1,5 +1,5 @@
-import { FrameCache, finalizeFrame, } from "../ui-components/index.js";
-// The interrupt byte, written as an escape: as a raw byte it is invisible to
+import { FrameCache, finalizeFrame, } from "../components/index.js";
+// Invariant: the interrupt byte is written as an escape: as a raw byte it is invisible to
 // every text tool, and this constant had already been emptied by one.
 const INTERRUPT = "";
 /** How long the first interrupt of the chord stays armed. */
@@ -14,8 +14,9 @@ export class UiAppHost {
     #surface;
     #closeOnInterrupt;
     #theme;
-    /** When the first interrupt of a chord was seen, or null when disarmed. */
+    // Invariant: the first interrupt timestamp is null whenever the chord is disarmed.
     #interruptArmedAt = null;
+    #renderedInterruptArmed;
     #cache = new FrameCache();
     #app = null;
     constructor(options) {
@@ -58,7 +59,11 @@ export class UiAppHost {
         }
         const size = this.#surface.size();
         const rect = { width: Math.max(0, size.width), height: Math.max(0, size.height) };
-        const lines = this.#guard(() => finalizeFrame(app.render(rect, this.#services()), rect, app.id));
+        const interruptArmed = this.interruptArmed;
+        if (this.#renderedInterruptArmed !== interruptArmed)
+            this.#cache.invalidate();
+        this.#renderedInterruptArmed = interruptArmed;
+        const lines = this.#guard(() => this.#cache.render(app, rect, () => finalizeFrame(app.render(rect, this.#services()), rect, app.id)));
         this.#surface.present(lines ?? null);
     }
     handleInput(data) {
@@ -86,11 +91,7 @@ export class UiAppHost {
             this.render();
         return result;
     }
-    /**
-     * Two interrupts leave A1, from any screen. One arms the chord and repaints so
-     * the screen can say so; a second within the window exits rather than merely
-     * closing the screen, which is what the chord means everywhere else.
-     */
+    // Protocol: two interrupts within the chord window leave A1 from every screen.
     #interrupt() {
         const now = Date.now();
         const armed = this.#interruptArmedAt;
@@ -101,6 +102,9 @@ export class UiAppHost {
             return { consumed: true, render: true };
         }
         this.#interruptArmedAt = now;
+        // Invariant: host-owned state participates in the app's next frame independently of
+        // the app's own revision contract.
+        this.#cache.invalidate();
         return { consumed: true, render: true };
     }
     get interruptArmed() {
@@ -135,7 +139,7 @@ export class UiAppHost {
             ...(this.#theme === undefined ? {} : { theme: this.#theme }),
         };
     }
-    /** Contains a failure: the app is closed and the surface restored, never left broken. */
+    // Security: an app failure closes its app and restores the surface.
     #guard(work) {
         try {
             return work();

package/dist/{src/foundation/ui-apps → ui/apps}/registry.d.ts

@@ -1,4 +1,5 @@
 import { type AppRegistration } from "./contracts.js";
+/** Registers owned applications under unique routes and unregisters only the matching definition. */
 export declare class UiAppRegistry {
     #private;
     /** Registering a known id replaces its definition rather than adding a second app. */

package/dist/{src/foundation/ui-apps → ui/apps}/registry.js

@@ -1,4 +1,5 @@
 import { assertAppRegistration } from "./contracts.js";
+/** Registers owned applications under unique routes and unregisters only the matching definition. */
 export class UiAppRegistry {
     #byId = new Map();
     /** Registering a known id replaces its definition rather than adding a second app. */

package/dist/{src/foundation/ui-components → ui/components}/dialog-panel.js

@@ -17,9 +17,11 @@ export function renderDialogPanel(state, width, theme) {
         const padded = `${row.label}${" ".repeat(Math.max(0, labelColumn - displayWidth(row.label)))}`;
         const cursor = selected ? "→ " : "  ";
         const raw = `${cursor}${padded}  ${row.value}`;
-        // An unselected label is left unpainted and its value quietened, both lifted
-        // to the accent on the row the cursor is on — as the engine paints its own.
-        const painted = `${theme.fg("accent", cursor)}${selected ? theme.fg("accent", padded) : padded}  ${theme.fg("muted", row.value)}`;
+        // Compatibility: match pinned SettingsList: selected cursor, label, and value all use the
+        // accent role; an unselected label is plain and its value is muted.
+        const painted = selected
+            ? `${theme.fg("accent", cursor)}${theme.fg("accent", padded)}  ${theme.fg("accent", row.value)}`
+            : `${cursor}${padded}  ${theme.fg("muted", row.value)}`;
         return pad(truncateToWidth(painted, width), width, raw);
     });
     const description = state.rows[state.index]?.description ?? "";

package/dist/{src/foundation/ui-components → ui/components}/frame.d.ts

@@ -2,6 +2,7 @@ export interface PaneRect {
     readonly width: number;
     readonly height: number;
 }
+/** Identifies the pane whose bounded frame geometry or rendered rows violated the contract. */
 export declare class FrameContractError extends Error {
     readonly pane: string;
     constructor(pane: string, message: string);

package/dist/{src/foundation/ui-components → ui/components}/frame.js

@@ -1,4 +1,5 @@
 import { displayWidth, truncateToWidth } from "./text.js";
+/** Identifies the pane whose bounded frame geometry or rendered rows violated the contract. */
 export class FrameContractError extends Error {
     pane;
     constructor(pane, message) {

package/dist/{src/foundation/ui-components → ui/components}/index.d.ts

@@ -6,13 +6,17 @@ export * from "./list-block.js";
 export * from "./list-view.js";
 export * from "./mouse.js";
 export * from "./pane.js";
+export * from "./progress-status.js";
 export * from "./revision.js";
 export * from "./scrollbar.js";
 export * from "./shortcuts.js";
 export * from "./spans.js";
 export * from "./status-line.js";
+export * from "./submitted-prompt.js";
 export * from "./stepper.js";
+export * from "./transcript-viewport.js";
 export * from "./surface.js";
 export * from "./text.js";
+export * from "./text-selection.js";
 export * from "./theme.js";
 export * from "./value-menu.js";

package/dist/{src/foundation/ui-components → ui/components}/index.js

@@ -6,13 +6,17 @@ export * from "./list-block.js";
 export * from "./list-view.js";
 export * from "./mouse.js";
 export * from "./pane.js";
+export * from "./progress-status.js";
 export * from "./revision.js";
 export * from "./scrollbar.js";
 export * from "./shortcuts.js";
 export * from "./spans.js";
 export * from "./status-line.js";
+export * from "./submitted-prompt.js";
 export * from "./stepper.js";
+export * from "./transcript-viewport.js";
 export * from "./surface.js";
 export * from "./text.js";
+export * from "./text-selection.js";
 export * from "./theme.js";
 export * from "./value-menu.js";

package/dist/{src/foundation/ui-components → ui/components}/line-input.d.ts

@@ -47,12 +47,7 @@ export declare class LineInput {
 }
 /** Applies one key to the input and reports whether the caller should commit. */
 export declare function handleLineInputKey(input: LineInput, data: string): LineInputOutcome;
-/**
- * The prompt the reference draws at the head of an input row, in the grey it
- * uses for one (#9AA0A6), painted foreground-only so anything drawn behind the
- * row survives.
- */
-/** A rule drawn in the prompt's own grey, as the reference rules an input row. */
+/** Draws the reference prompt rule foreground-only so underlying cells survive. */
 export declare function promptRule(width: number): string;
 export declare const PROMPT_GLYPH = "\u001B[38;2;154;160;166m\u276F\u001B[39m ";
 /**

package/dist/{src/foundation/ui-components → ui/components}/line-input.js

@@ -148,7 +148,7 @@ export function handleLineInputKey(input, data) {
         return { kind: "accepted", value: input.value };
     if (data === "\u001b" || data === "\u0003")
         return { kind: "cancelled" };
-    // A word delete is decided before a plain one: on Windows Terminal the raw
+    // Platform: a word delete is decided before a plain one: on Windows Terminal the raw
     // backspace byte IS ctrl+backspace, and the plain branch would swallow it.
     if (data === "\b" || data === "\u001b\u007f" || data === "\u0017") {
         input.deleteWordBefore();
@@ -190,7 +190,7 @@ export function handleLineInputKey(input, data) {
         input.moveCaretToEnd();
         return { kind: "editing" };
     }
-    // Any other escape sequence is a key this input has no answer for - a page
+    // Rationale: any other escape sequence is a key this input has no answer for - a page
     // key, a function key, a chord. It is swallowed rather than typed, because the
     // one thing it certainly is not is text the reader meant to enter.
     if (data.startsWith("\u001b"))
@@ -198,12 +198,7 @@ export function handleLineInputKey(input, data) {
     input.insert(data);
     return { kind: "editing" };
 }
-/**
- * The prompt the reference draws at the head of an input row, in the grey it
- * uses for one (#9AA0A6), painted foreground-only so anything drawn behind the
- * row survives.
- */
-/** A rule drawn in the prompt's own grey, as the reference rules an input row. */
+/** Draws the reference prompt rule foreground-only so underlying cells survive. */
 export function promptRule(width) {
     return `\u001b[38;2;154;160;166m${"─".repeat(Math.max(0, width))}\u001b[39m`;
 }
@@ -224,7 +219,7 @@ export function renderInputRow(input, width, options = {}) {
     const before = view.text.slice(0, view.caretColumn);
     const under = view.text.slice(view.caretColumn, view.caretColumn + 1) || " ";
     const after = view.text.slice(view.caretColumn + 1);
-    // Typed text is left unpainted, the caret reverses its cell, and the
+    // Rationale: typed text is left unpainted, the caret reverses its cell, and the
     // placeholder is quietened by weight rather than by a colour of its own.
     const body = empty
         ? `${caretCell(placeholder.slice(0, 1))}${faint(placeholder.slice(1))}`

package/dist/{src/foundation/ui-components → ui/components}/list-view.d.ts

@@ -1,10 +1,4 @@
 import type { UiTheme } from "./theme.js";
-/**
- * A list of things that each carry a label and a value. It owns where a value
- * starts, how a row reads when it is selected or pointed at, and which part of a
- * row the pointer is on — so a screen decides what a row means and this decides
- * how it looks and where it can be touched.
- */
 /** The part of a row the pointer is over. A label selects; a value acts. */
 export type ListRegion = "label" | "value" | "minus" | "plus";
 /** Columns a stepper's controls occupy on either side of the value. */

package/dist/{src/foundation/ui-components → ui/components}/list-view.js

@@ -6,8 +6,8 @@ export const STEPPER_RESERVE = 2;
  * and with the stepper's columns reserved for every row when any row has one, so
  * a number does not shift its own value out of the column it shares.
  */
-export function valueColumnFor(rows, indent = 4, gap = 2) {
-    const widest = Math.max(0, ...rows.map(row => displayWidth(row.label)));
+export function valueColumnFor(rows, indent = 2, gap = 2) {
+    const widest = Math.min(30, Math.max(0, ...rows.map(row => displayWidth(row.label))));
     const stepper = rows.some(row => row.stepper !== undefined) ? STEPPER_RESERVE : 0;
     return indent + widest + gap + stepper;
 }
@@ -22,14 +22,21 @@ export function renderGroupHeader(title, width, theme) {
  */
 export function renderListRow(row, state, valueColumn, width, theme) {
     const cursor = state.selected ? "→ " : "  ";
-    const leftRaw = `${cursor}  ${row.label}`;
-    const left = `${theme.fg("accent", cursor)}  ${state.selected ? theme.fg("accent", row.label) : theme.plain(row.label)}`;
+    const labelColumn = Math.max(displayWidth(row.label), valueColumn - 4 - (row.stepper === undefined ? 0 : STEPPER_RESERVE));
+    const labelPadded = `${row.label}${" ".repeat(Math.max(0, labelColumn - displayWidth(row.label)))}`;
+    const leftRaw = `${cursor}${labelPadded}`;
+    const left = state.selected
+        ? `${theme.fg("accent", cursor)}${theme.fg("accent", labelPadded)}`
+        : `${cursor}${theme.plain(labelPadded)}`;
     const gap = Math.max(2, valueColumn - displayWidth(leftRaw));
-    // Pointing anywhere on the row is pointing at the item; pointing at the value
-    // is what brightens it. The selection speaks through the label alone.
+    // Compatibility: pinned SettingsList gives the selected label and value the same accent
+    // role. Pointer hover may brighten an unselected value without changing the
+    // keyboard selection.
     const valueHovered = state.hovered && state.region !== "label";
     const stepper = row.stepper !== undefined && valueHovered;
-    const value = valueHovered ? theme.plain(row.value) : theme.fg("muted", row.value);
+    const value = state.selected
+        ? theme.fg("accent", row.value)
+        : valueHovered ? theme.plain(row.value) : theme.fg("muted", row.value);
     const minus = stepper
         ? row.stepper?.lower === true
             ? state.region === "minus" ? theme.plain("- ") : theme.fg("dim", "- ")

package/dist/{src/foundation/ui-components → ui/components}/mouse.d.ts

@@ -13,3 +13,13 @@ export interface ParsedMouseInput {
 }
 /** Extracts SGR mouse reports, leaving any keyboard input untouched. */
 export declare function parseMouseInput(data: string): ParsedMouseInput;
+export interface RoutedMouseInput {
+    /** Input left for the TUI after only claimed reports were removed. */
+    readonly data: string;
+    readonly consumed: boolean;
+}
+/**
+ * Routes every SGR report independently, preserving keyboard bytes and mouse
+ * reports the caller does not claim even when they share one physical chunk.
+ */
+export declare function routeMouseInput(data: string, claim: (event: PaneMouseEvent) => boolean): RoutedMouseInput;

package/dist/{src/foundation/ui-components → ui/components}/mouse.js

@@ -30,6 +30,29 @@ export function parseMouseInput(data) {
     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;
+    SGR_PATTERN.lastIndex = 0;
+    for (let match = SGR_PATTERN.exec(data); match !== null; match = SGR_PATTERN.exec(data)) {
+        output += data.slice(index, match.index);
+        index = match.index + match[0].length;
+        const event = toEvent(Number.parseInt(match[1] ?? "", 10), Number.parseInt(match[2] ?? "", 10), Number.parseInt(match[3] ?? "", 10), match[4] === "m");
+        if (event !== null && claim(event))
+            consumed = true;
+        else
+            output += match[0];
+    }
+    output += data.slice(index);
+    return { data: output, consumed };
+}
 function toEvent(code, column, row, released) {
     if ((code & 64) !== 0) {
         const kind = (code & 1) === 0 ? "wheel-up" : "wheel-down";

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

@@ -0,0 +1,2 @@
+/** Returns spinner-backed status text with A1's canonical three-period marker. */
+export declare function progressStatusText(message: string): string;

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

@@ -0,0 +1,4 @@
+/** Returns spinner-backed status text with A1's canonical three-period marker. */
+export function progressStatusText(message) {
+    return `${message.replace(/(?:…|\.+)$/u, "")}...`;
+}

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

@@ -0,0 +1,14 @@
+export interface TimestampedPromptRowsInput {
+    readonly width: number;
+    readonly sourceTimestamp: number | Date;
+    readonly render: (contentWidth: number) => readonly string[];
+    /** Styles the reserved suffix while keeping policy independent of a vendor theme. */
+    readonly decorateSuffix?: (text: string, firstRow: boolean) => string;
+    readonly minimumWidth?: number;
+}
+export declare function formatPromptTimestamp(source: number | Date): string | null;
+/**
+ * Reserves timestamp columns before wrapping, so the clock never overwrites
+ * prompt content. At narrow widths the same renderer is used without a clock.
+ */
+export declare function composeTimestampedPromptRows(input: TimestampedPromptRowsInput): readonly string[];

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

@@ -0,0 +1,20 @@
+import { overlaySpan } from "./spans.js";
+export function formatPromptTimestamp(source) {
+    const date = source instanceof Date ? source : new Date(source);
+    if (Number.isNaN(date.getTime()))
+        return null;
+    return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}
+/**
+ * Reserves timestamp columns before wrapping, so the clock never overwrites
+ * prompt content. At narrow widths the same renderer is used without a clock.
+ */
+export function composeTimestampedPromptRows(input) {
+    const timestamp = formatPromptTimestamp(input.sourceTimestamp);
+    if (timestamp === null || input.width < (input.minimumWidth ?? 20))
+        return input.render(input.width);
+    const suffixWidth = timestamp.length + 2;
+    const contentWidth = Math.max(1, input.width - suffixWidth);
+    const decorate = input.decorateSuffix ?? ((text) => text);
+    return input.render(contentWidth).map((row, index) => overlaySpan(row, contentWidth, input.width, decorate(index === 0 ? `  ${timestamp}` : " ".repeat(suffixWidth), index === 0)));
+}

package/dist/{src/foundation/ui-components → ui/components}/scrollbar.d.ts

@@ -19,6 +19,30 @@ export interface ScrollbarInput {
     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 uses the same configured rate as a wheel event. */
+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;
@@ -48,6 +72,8 @@ export interface RailPointer {
  */
 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;

package/dist/{src/foundation/ui-components → ui/components}/scrollbar.js

@@ -3,6 +3,33 @@
  * 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 uses the same configured rate as a wheel event. */
+export function scrollbarSelectionRows(speed) {
+    return scrollbarWheelRows(speed);
+}
+/** 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;
@@ -51,7 +78,14 @@ export function scrollForTrackPage(geometry, trackRow, scroll, viewportHeight) {
  */
 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);
     }
@@ -97,6 +131,7 @@ export class ScrollbarRails {
     }
     clear() {
         this.#hovered.clear();
+        this.#activeUntil.clear();
         this.#dragging = undefined;
     }
 }

package/dist/{src/foundation/ui-components → ui/components}/shortcuts.d.ts

@@ -40,6 +40,7 @@ export interface ShortcutRegistryResult {
  */
 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;

package/dist/{src/foundation/ui-components → ui/components}/shortcuts.js

@@ -40,6 +40,7 @@ export function assertNoShortcutConflicts(result) {
             + `"${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();

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

@@ -0,0 +1,25 @@
+/**
+ * Replaces the visible columns `[from, to)` of `line` with `span`, preserving
+ * the styling before it and re-asserting whatever was still open afterwards, so
+ * the tail keeps the colour it had. A wide character straddling either edge is
+ * replaced by spaces rather than split.
+ */
+export declare function overlaySpan(line: string, from: number, to: number, span: string): string;
+/** Wraps visible columns `[from,to)` in an explicit OSC 8 hyperlink. */
+export declare function hyperlinkSgrSpan(line: string, from: number, to: number, target: string, widthOf?: (text: string) => number): string;
+/** Returns the OSC 8 target painted at a zero-based visible terminal column. */
+export declare function hyperlinkTargetAtColumn(line: string, targetColumn: number, widthOf?: (text: string) => number): string | undefined;
+/**
+ * Gives existing and bare web links explicit, tightly bounded OSC 8 regions so
+ * the terminal owns dotted-idle/solid-hover decoration without leaking hover
+ * state into cells repainted during scrolling.
+ */
+export declare function nativeHyperlinkStyle(line: string, color?: (text: string, target: string) => string): string;
+/**
+ * Held-button paint for terminal-native links. OSC 8 is removed so the terminal
+ * cannot switch a selected link to its solid hover underline. A dotted SGR
+ * underline preserves the idle appearance, and VS15 transiently breaks native
+ * plain-text URL detection without changing visible width.
+ */
+export declare function heldNativeHyperlinkStyle(line: string): string;
+export declare function backgroundSgrSpan(line: string, from: number, to: number, on?: string, off?: string, widthOf?: (text: string) => number): string;