@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.510

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

@@ -0,0 +1,224 @@
+import { displayWidth, faint, truncateToWidth } from "./text.js";
+import { PromptInput } from "./prompt-input.js";
+const MAX_VALUE_LENGTH = 4_096;
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/** Character class for a word boundary: 0 space, 1 word, 2 anything else. */
+function charClass(character) {
+    if (/\s/.test(character))
+        return 0;
+    if (/[\p{L}\p{N}_]/u.test(character))
+        return 1;
+    return 2;
+}
+/**
+ * Where a word jump to the left lands: past any whitespace, then past the run of
+ * characters of one class, so a word and a run of punctuation each count as one.
+ */
+export function wordLeft(text, from) {
+    const graphemes = [...GRAPHEMES.segment(text.slice(0, from))].map(entry => entry.segment);
+    let at = from;
+    let index = graphemes.length - 1;
+    while (index >= 0 && charClass(graphemes[index] ?? "") === 0)
+        at -= (graphemes[index--] ?? "").length;
+    if (index >= 0) {
+        const cls = charClass(graphemes[index] ?? "");
+        while (index >= 0 && charClass(graphemes[index] ?? "") === cls)
+            at -= (graphemes[index--] ?? "").length;
+    }
+    return at;
+}
+/** Where a word jump to the right lands, by the same rules mirrored. */
+export function wordRight(text, from) {
+    const graphemes = [...GRAPHEMES.segment(text.slice(from))].map(entry => entry.segment);
+    let at = from;
+    let index = 0;
+    while (index < graphemes.length && charClass(graphemes[index] ?? "") === 0)
+        at += (graphemes[index++] ?? "").length;
+    if (index < graphemes.length) {
+        const cls = charClass(graphemes[index] ?? "");
+        while (index < graphemes.length && charClass(graphemes[index] ?? "") === cls)
+            at += (graphemes[index++] ?? "").length;
+    }
+    return at;
+}
+/**
+ * A single-line editable value with a caret and horizontal scrolling. Accept and
+ * cancel are reported distinctly so a caller can commit or discard; cancelling
+ * never changes the caller's value.
+ */
+export class LineInput {
+    #value;
+    #caret;
+    #offset = 0;
+    constructor(value = "") {
+        this.#value = value.slice(0, MAX_VALUE_LENGTH);
+        this.#caret = this.#value.length;
+    }
+    get value() {
+        return this.#value;
+    }
+    get caret() {
+        return this.#caret;
+    }
+    setValue(value) {
+        this.#value = value.slice(0, MAX_VALUE_LENGTH);
+        this.#caret = Math.min(this.#caret, this.#value.length);
+        this.#offset = 0;
+    }
+    insert(text) {
+        const printable = [...text].filter(character => {
+            const code = character.codePointAt(0) ?? 0;
+            return code >= 0x20 && code !== 0x7f;
+        }).join("");
+        if (printable.length === 0)
+            return;
+        const next = this.#value.slice(0, this.#caret) + printable + this.#value.slice(this.#caret);
+        if (next.length > MAX_VALUE_LENGTH)
+            return;
+        this.#value = next;
+        this.#caret += printable.length;
+    }
+    backspace() {
+        if (this.#caret === 0)
+            return;
+        this.#value = this.#value.slice(0, this.#caret - 1) + this.#value.slice(this.#caret);
+        this.#caret -= 1;
+    }
+    deleteForward() {
+        if (this.#caret >= this.#value.length)
+            return;
+        this.#value = this.#value.slice(0, this.#caret) + this.#value.slice(this.#caret + 1);
+    }
+    moveCaret(delta) {
+        this.#caret = Math.min(Math.max(this.#caret + delta, 0), this.#value.length);
+    }
+    /** Moves the caret one word, in whichever direction the sign says. */
+    moveCaretByWord(direction) {
+        this.#caret = direction < 0 ? wordLeft(this.#value, this.#caret) : wordRight(this.#value, this.#caret);
+    }
+    /** Removes the word before the caret, leaving the caret where it began. */
+    deleteWordBefore() {
+        const to = wordLeft(this.#value, this.#caret);
+        if (to >= this.#caret)
+            return;
+        this.#value = this.#value.slice(0, to) + this.#value.slice(this.#caret);
+        this.#caret = to;
+    }
+    /** Removes the word after the caret, leaving the caret where it is. */
+    deleteWordAfter() {
+        const to = wordRight(this.#value, this.#caret);
+        if (to <= this.#caret)
+            return;
+        this.#value = this.#value.slice(0, this.#caret) + this.#value.slice(to);
+    }
+    moveCaretToStart() {
+        this.#caret = 0;
+    }
+    moveCaretToEnd() {
+        this.#caret = this.#value.length;
+    }
+    /** Visible slice for a width, scrolled so the caret stays on screen. */
+    view(width) {
+        if (width <= 0)
+            return { text: "", caretColumn: 0 };
+        const before = this.#value.slice(0, this.#caret);
+        const caretWidth = displayWidth(before);
+        if (caretWidth < this.#offset)
+            this.#offset = caretWidth;
+        if (caretWidth >= this.#offset + width)
+            this.#offset = caretWidth - width + 1;
+        if (this.#offset < 0)
+            this.#offset = 0;
+        let start = 0;
+        let consumed = 0;
+        for (const character of this.#value) {
+            if (consumed >= this.#offset)
+                break;
+            consumed += displayWidth(character);
+            start += character.length;
+        }
+        return {
+            text: truncateToWidth(this.#value.slice(start), width),
+            caretColumn: Math.max(0, Math.min(width, caretWidth - this.#offset)),
+        };
+    }
+}
+/** Applies one key to the input and reports whether the caller should commit. */
+export function handleLineInputKey(input, data) {
+    if (data === "\r" || data === "\n")
+        return { kind: "accepted", value: input.value };
+    if (data === "\u001b" || data === "\u0003")
+        return { kind: "cancelled" };
+    // 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();
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[3;5~" || data === "\u001b[3;3~" || data === "\u001bd") {
+        input.deleteWordAfter();
+        return { kind: "editing" };
+    }
+    if (data === "\u007f") {
+        input.backspace();
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[3~") {
+        input.deleteForward();
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[1;5D" || data === "\u001b[1;3D" || data === "\u001bb") {
+        input.moveCaretByWord(-1);
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[1;5C" || data === "\u001b[1;3C" || data === "\u001bf") {
+        input.moveCaretByWord(1);
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[D") {
+        input.moveCaret(-1);
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[C") {
+        input.moveCaret(1);
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[H" || data === "\u0001") {
+        input.moveCaretToStart();
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[F" || data === "\u0005") {
+        input.moveCaretToEnd();
+        return { kind: "editing" };
+    }
+    // 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"))
+        return { kind: "editing" };
+    input.insert(data);
+    return { kind: "editing" };
+}
+/**
+ * The caret the reference draws: the cell under it is reversed rather than given
+ * a colour of its own, so it reads as a block in whatever theme is in use.
+ */
+export function caretCell(text) {
+    return `\u001b[7m${text}\u001b[27m`;
+}
+/** The input row as the reference draws one, padded to exactly the width. */
+export function renderInputRow(input, width, options = {}) {
+    const presentation = new PromptInput(options.theme);
+    const view = input.view(Math.max(0, width - presentation.geometry(width).prefixWidth));
+    const placeholder = options.placeholder ?? "";
+    const empty = view.text.length === 0 && placeholder.length > 0;
+    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);
+    // 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))}`
+        : `${before}${caretCell(under)}${after}`;
+    return { lines: presentation.render(width, () => ({ rows: [body] }), options.ruled) };
+}

package/dist/ui/components/list-view.d.ts

@@ -0,0 +1,60 @@
+import type { UiTheme } from "./theme.js";
+/** 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. */
+export declare const STEPPER_RESERVE = 2;
+export interface ListViewRow {
+    /** Identity of the row, as the screen knows it. */
+    readonly key: string;
+    readonly label: string;
+    /** The value as it should read. Formatting belongs to the screen. */
+    readonly value: string;
+    /** Trailing note, such as where a value came from. */
+    readonly suffix?: string;
+    /**
+     * Present when the value is stepped. Each end says whether it can still act;
+     * an end that cannot is drawn as unavailable rather than explaining itself.
+     */
+    readonly stepper?: {
+        readonly lower: boolean;
+        readonly raise: boolean;
+    };
+}
+export interface ListRowState {
+    /** The keyboard's row. */
+    readonly selected: boolean;
+    /** The pointer's row, and where on it the pointer is. */
+    readonly hovered: boolean;
+    readonly region: ListRegion;
+}
+/** Where a row was drawn, so a later pointer report can be read against it. */
+export interface ListRowPlacement {
+    readonly key: string;
+    readonly screenRow: number;
+    readonly valueColumn: number;
+    readonly valueWidth: number;
+    readonly stepper: boolean;
+}
+/**
+ * The column every value begins at: past the widest label, with room to breathe,
+ * 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 declare function valueColumnFor(rows: readonly ListViewRow[], indent?: number, gap?: number): number;
+/** A group's name, above the rows that belong to it. */
+export declare function renderGroupHeader(title: string, width: number, theme: UiTheme): string;
+/**
+ * One row, painted. The label carries the selection, the value carries the
+ * pointer, and the stepper appears only when the pointer is on the value it
+ * belongs to — an affordance, not decoration.
+ */
+export declare function renderListRow(row: ListViewRow, state: ListRowState, valueColumn: number, width: number, theme: UiTheme): string;
+/** A line that stands in for rows: why a group has none, or what it is waiting on. */
+export declare function renderNote(text: string, width: number, theme: UiTheme): string;
+/** Where the value of a row starts and ends, for reading a pointer against it. */
+export declare function placementFor(row: ListViewRow, screenRow: number, valueColumn: number, hovered: boolean): ListRowPlacement;
+/**
+ * The part of a row a column falls on. The stepper's controls sit in the columns
+ * reserved before and after the value, so they are only reachable while drawn.
+ */
+export declare function regionAt(placement: ListRowPlacement, column: number): ListRegion;

package/dist/ui/components/list-view.js

@@ -0,0 +1,82 @@
+import { displayWidth, truncateToWidth } from "./text.js";
+/** Columns a stepper's controls occupy on either side of the value. */
+export const STEPPER_RESERVE = 2;
+/**
+ * The column every value begins at: past the widest label, with room to breathe,
+ * 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 = 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;
+}
+/** A group's name, above the rows that belong to it. */
+export function renderGroupHeader(title, width, theme) {
+    return truncateToWidth(theme.fg("accent", theme.bold(title)), width);
+}
+/**
+ * One row, painted. The label carries the selection, the value carries the
+ * pointer, and the stepper appears only when the pointer is on the value it
+ * belongs to — an affordance, not decoration.
+ */
+export function renderListRow(row, state, valueColumn, width, theme) {
+    const cursor = state.selected ? "→ " : "  ";
+    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));
+    // Rationale: a declared difference from pinned SettingsList, which paints the selected
+    // value in the accent too. Here only the cursor and label carry the selection; the
+    // value reads the same on every row, and pointer hover brightens it without moving
+    // 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 minus = stepper
+        ? row.stepper?.lower === true
+            ? state.region === "minus" ? theme.plain("- ") : theme.fg("dim", "- ")
+            : theme.disabled("- ")
+        : "";
+    const plus = stepper
+        ? row.stepper?.raise === true
+            ? state.region === "plus" ? theme.plain(" +") : theme.fg("dim", " +")
+            : theme.disabled(" +")
+        : "";
+    const indent = Math.max(2, stepper ? gap - STEPPER_RESERVE : gap);
+    const suffix = row.suffix === undefined ? "" : theme.fg("dim", `  ${row.suffix}`);
+    return truncateToWidth(`${left}${" ".repeat(indent)}${minus}${value}${plus}${suffix}`, width);
+}
+/** A line that stands in for rows: why a group has none, or what it is waiting on. */
+export function renderNote(text, width, theme) {
+    return truncateToWidth(theme.fg("muted", `    ${text}`), width);
+}
+/** Where the value of a row starts and ends, for reading a pointer against it. */
+export function placementFor(row, screenRow, valueColumn, hovered) {
+    const stepper = row.stepper !== undefined && hovered;
+    return {
+        key: row.key,
+        screenRow,
+        valueColumn: stepper ? valueColumn - STEPPER_RESERVE : valueColumn,
+        valueWidth: displayWidth(row.value),
+        stepper,
+    };
+}
+/**
+ * The part of a row a column falls on. The stepper's controls sit in the columns
+ * reserved before and after the value, so they are only reachable while drawn.
+ */
+export function regionAt(placement, column) {
+    const start = placement.valueColumn + 1;
+    const end = start + placement.valueWidth;
+    if (column >= start && column <= end)
+        return "value";
+    if (placement.stepper && column >= start - STEPPER_RESERVE && column < start)
+        return "minus";
+    if (placement.stepper && column > end && column <= end + STEPPER_RESERVE)
+        return "plus";
+    return "label";
+}

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

@@ -0,0 +1,25 @@
+import type { PaneMouseEvent } from "./pane.js";
+/**
+ * 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 declare const MOUSE_TRACKING_ON = "\u001B[?1006h\u001B[?1000h\u001B[?1003h";
+export declare const MOUSE_TRACKING_OFF = "\u001B[?1003l\u001B[?1000l\u001B[?1006l";
+export interface ParsedMouseInput {
+    readonly events: readonly PaneMouseEvent[];
+    /** Input with every mouse report removed, for ordinary key handling. */
+    readonly rest: string;
+}
+/** 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, report: string) => boolean): RoutedMouseInput;

package/dist/ui/components/mouse.js

@@ -0,0 +1,70 @@
+/**
+ * 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";
+export const MOUSE_TRACKING_OFF = "\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.parseInt(match[1] ?? "", 10), Number.parseInt(match[2] ?? "", 10), Number.parseInt(match[3] ?? "", 10), 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 & 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,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-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 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;
+/** 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;
+}