@timurproko/a1 0.1.8-dev.ece8cef → 0.2.0

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-block.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A grouped list: group headers, selectable elements, notes, and spacers. While
+ * the top visible row belongs to a group, that group's header stays pinned as
+ * the first rendered row, so the reader always knows which group is on screen.
+ */
+export type ListRow<T> = {
+    readonly kind: "group";
+    readonly group: string;
+    readonly title: string;
+} | {
+    readonly kind: "element";
+    readonly group: string;
+    readonly key: string;
+    readonly selectable: boolean;
+    readonly value: T;
+} | {
+    readonly kind: "note";
+    readonly group: string;
+    readonly text: string;
+} | {
+    readonly kind: "spacer";
+};
+export interface ListRowSpan {
+    readonly from: number;
+    readonly to: number;
+}
+export declare function rowKey<T>(row: ListRow<T> | undefined): string | undefined;
+export declare function selectableIndexes<T>(rows: readonly ListRow<T>[]): readonly number[];
+export declare function indexOfKey<T>(rows: readonly ListRow<T>[], key: string | undefined): number;
+/** Clamped movement between selectable rows. No wrap-around. */
+export declare function moveSelection<T>(rows: readonly ListRow<T>[], current: number, delta: number): number;
+/**
+ * Forward lands on the first element of the next group. Backward lands on the
+ * first element of the current group, or the previous group's when already
+ * there. Groups with no selectable element are skipped; edges stay put.
+ */
+export declare function blockJumpTarget<T>(rows: readonly ListRow<T>[], current: number, delta: number): number | undefined;
+/** The block containing `index`: its header through the row before the next header. */
+export declare function blockRowSpan<T>(rows: readonly ListRow<T>[], index: number): ListRowSpan;
+/** The header pinned above the body while its content or outgoing spacer is at the top. */
+export declare function stickyHeaderFor<T>(rows: readonly ListRow<T>[], scroll: number): string | undefined;
+export interface ListLayoutOptions {
+    /** Settings keeps one opening row; embedded documents can start with their own prelude. */
+    readonly topPadding?: boolean;
+}
+/** One blank row above the first group while the list is scrolled to the top. */
+export declare function topPaddingRows(scroll: number, enabled?: boolean): number;
+/** Rows of content visible after the padding and any pinned header. */
+export declare function visibleRowCount<T>(rows: readonly ListRow<T>[], bodyHeight: number, scroll: number, options?: ListLayoutOptions): number;
+export declare function maxScrollFor<T>(rows: readonly ListRow<T>[], bodyHeight: number, options?: ListLayoutOptions): number;
+export declare function clampScroll<T>(rows: readonly ListRow<T>[], bodyHeight: number, scroll: number, options?: ListLayoutOptions): {
+    readonly scroll: number;
+    readonly visible: number;
+};
+/**
+ * Scroll that brings the selection into view, moving the least it can. A reveal
+ * span asks for a whole block; a block taller than the viewport is shown from
+ * its header instead.
+ */
+export declare function scrollForSelection<T>(rows: readonly ListRow<T>[], bodyHeight: number, scroll: number, selected: number, reveal?: ListRowSpan): number;
+export interface ListLayout {
+    readonly scroll: number;
+    readonly visible: number;
+    readonly stickyHeader: string | undefined;
+    readonly topPadding: number;
+    /** Row indexes rendered in the body, in order. */
+    readonly rowIndexes: readonly number[];
+}
+/** Everything a renderer needs for one frame, derived rather than remembered. */
+export declare function layoutList<T>(rows: readonly ListRow<T>[], bodyHeight: number, scroll: number, options?: ListLayoutOptions): ListLayout;

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

@@ -0,0 +1,189 @@
+/**
+ * A grouped list: group headers, selectable elements, notes, and spacers. While
+ * the top visible row belongs to a group, that group's header stays pinned as
+ * the first rendered row, so the reader always knows which group is on screen.
+ */
+export function rowKey(row) {
+    return row !== undefined && row.kind === "element" && row.selectable ? row.key : undefined;
+}
+export function selectableIndexes(rows) {
+    const indexes = [];
+    rows.forEach((row, index) => {
+        if (rowKey(row) !== undefined)
+            indexes.push(index);
+    });
+    return indexes;
+}
+export function indexOfKey(rows, key) {
+    if (key !== undefined) {
+        const found = rows.findIndex(row => rowKey(row) === key);
+        if (found >= 0)
+            return found;
+    }
+    return selectableIndexes(rows)[0] ?? -1;
+}
+/** Clamped movement between selectable rows. No wrap-around. */
+export function moveSelection(rows, current, delta) {
+    const selectable = selectableIndexes(rows);
+    if (selectable.length === 0)
+        return -1;
+    const position = selectable.indexOf(current);
+    if (position < 0)
+        return selectable[0] ?? -1;
+    const next = Math.min(Math.max(position + delta, 0), selectable.length - 1);
+    return selectable[next] ?? current;
+}
+function firstElementOfBlock(rows, headerIndex) {
+    for (let index = headerIndex + 1; index < rows.length && rows[index]?.kind !== "group"; index++) {
+        if (rowKey(rows[index]) !== undefined)
+            return index;
+    }
+    return undefined;
+}
+function headerAbove(rows, index) {
+    for (let cursor = Math.min(index, rows.length - 1); cursor >= 0; cursor--) {
+        if (rows[cursor]?.kind === "group")
+            return cursor;
+    }
+    return -1;
+}
+/**
+ * Forward lands on the first element of the next group. Backward lands on the
+ * first element of the current group, or the previous group's when already
+ * there. Groups with no selectable element are skipped; edges stay put.
+ */
+export function blockJumpTarget(rows, current, delta) {
+    if (current < 0 || rows.length === 0)
+        return undefined;
+    const header = headerAbove(rows, current);
+    if (header < 0)
+        return undefined;
+    const blocks = [];
+    for (let index = 0; index < rows.length; index++) {
+        if (rows[index]?.kind === "group" && firstElementOfBlock(rows, index) !== undefined)
+            blocks.push(index);
+    }
+    const position = blocks.indexOf(header);
+    if (position < 0)
+        return undefined;
+    if (delta > 0) {
+        if (position >= blocks.length - 1)
+            return undefined;
+        const next = blocks[position + 1];
+        return next === undefined ? undefined : firstElementOfBlock(rows, next);
+    }
+    const own = firstElementOfBlock(rows, header);
+    if (own !== undefined && own < current)
+        return own;
+    if (position <= 0)
+        return undefined;
+    const previous = blocks[position - 1];
+    return previous === undefined ? undefined : firstElementOfBlock(rows, previous);
+}
+/** The block containing `index`: its header through the row before the next header. */
+export function blockRowSpan(rows, index) {
+    if (rows.length === 0)
+        return { from: 0, to: 0 };
+    const start = Math.min(Math.max(index, 0), rows.length - 1);
+    const from = Math.max(headerAbove(rows, start), 0);
+    let to = rows.length - 1;
+    for (let cursor = start + 1; cursor < rows.length; cursor++) {
+        if (rows[cursor]?.kind === "group") {
+            to = cursor - 1;
+            break;
+        }
+    }
+    return { from, to };
+}
+/** The header pinned above the body while its content or outgoing spacer is at the top. */
+export function stickyHeaderFor(rows, scroll) {
+    const row = rows[scroll];
+    if (row === undefined || row.kind === "group")
+        return undefined;
+    const header = headerAbove(rows, scroll);
+    const headerRow = header < 0 ? undefined : rows[header];
+    return headerRow !== undefined && headerRow.kind === "group" ? headerRow.title : undefined;
+}
+/** One blank row above the first group while the list is scrolled to the top. */
+export function topPaddingRows(scroll, enabled = true) {
+    return enabled && scroll <= 0 ? 1 : 0;
+}
+/** Rows of content visible after the padding and any pinned header. */
+export function visibleRowCount(rows, bodyHeight, scroll, options = {}) {
+    const reserved = topPaddingRows(scroll, options.topPadding !== false) + (stickyHeaderFor(rows, scroll) === undefined ? 0 : 1);
+    return Math.max(1, bodyHeight - reserved);
+}
+export function maxScrollFor(rows, bodyHeight, options = {}) {
+    let scroll = Math.max(0, rows.length - 1);
+    for (let pass = 0; pass < 8; pass++) {
+        const next = Math.max(0, rows.length - visibleRowCount(rows, bodyHeight, scroll, options));
+        if (next === scroll)
+            break;
+        scroll = next;
+    }
+    return scroll;
+}
+export function clampScroll(rows, bodyHeight, scroll, options = {}) {
+    const bounded = Math.min(Math.max(scroll, 0), maxScrollFor(rows, bodyHeight, options));
+    return { scroll: bounded, visible: visibleRowCount(rows, bodyHeight, bounded, options) };
+}
+/**
+ * Scroll that brings the selection into view, moving the least it can. A reveal
+ * span asks for a whole block; a block taller than the viewport is shown from
+ * its header instead.
+ */
+export function scrollForSelection(rows, bodyHeight, scroll, selected, reveal) {
+    let next = scroll;
+    for (let pass = 0; pass < 2; pass++) {
+        const visible = visibleRowCount(rows, bodyHeight, next);
+        if (selected >= 0) {
+            if (reveal && reveal.to - reveal.from < visible) {
+                if (reveal.from < next)
+                    next = reveal.from;
+                if (reveal.to >= next + visible)
+                    next = reveal.to - visible + 1;
+            }
+            else if (reveal) {
+                next = reveal.from;
+            }
+            else {
+                if (selected < next)
+                    next = selected;
+                if (selected >= next + visible)
+                    next = selected - visible + 1;
+            }
+        }
+        next = clampScroll(rows, bodyHeight, next).scroll;
+    }
+    return next;
+}
+/** Everything a renderer needs for one frame, derived rather than remembered. */
+export function layoutList(rows, bodyHeight, scroll, options = {}) {
+    const clamped = clampScroll(rows, bodyHeight, scroll, options);
+    const sticky = stickyHeaderFor(rows, clamped.scroll);
+    const padding = topPaddingRows(clamped.scroll, options.topPadding !== false);
+    const indexes = [];
+    // Invariant: a spacer at the scroll boundary belongs to the outgoing pinned section.
+    // The pin represents that transition, so the spacer spends no body row and the final
+    // setting remains reachable at the bottom.
+    const firstOffset = rows[clamped.scroll]?.kind === "spacer" && sticky !== undefined ? 1 : 0;
+    for (let offset = firstOffset; indexes.length < clamped.visible && clamped.scroll + offset < rows.length; offset++) {
+        indexes.push(clamped.scroll + offset);
+    }
+    // Invariant: a bottom clamp can land on the outgoing spacer with too few rows after it to fill the
+    // viewport. The pinned heading already represents that boundary, so fill the freed capacity
+    // from the same section rather than exposing a synthetic blank row at the bottom.
+    if (firstOffset > 0 && indexes.length < clamped.visible) {
+        const header = headerAbove(rows, clamped.scroll);
+        for (let index = clamped.scroll - 1; index > header && indexes.length < clamped.visible; index--) {
+            indexes.unshift(index);
+        }
+    }
+    return {
+        scroll: clamped.scroll,
+        visible: clamped.visible,
+        stickyHeader: sticky,
+        topPadding: padding,
+        rowIndexes: Object.freeze(indexes),
+    };
+}

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 with the shared one-cell section inset used by owned screens. */
+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,84 @@
+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 with the shared one-cell section inset used by owned screens. */
+export function renderGroupHeader(title, width, theme) {
+    if (width <= 0)
+        return "";
+    return ` ${truncateToWidth(theme.fg("mdHeading", theme.bold(title)), width - 1)}`;
+}
+/**
+ * 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\u001B[?1004h";
+export declare const MOUSE_TRACKING_OFF = "\u001B[?1004l\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;