@aragon-agent/cli 0.6.2 → 0.6.4

package/dist/ui/selection/highlight.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The row painter (tui-selection-and-scroll-follow §4.4.4). PURE — strings in,
+ * strings out.
+ *
+ * It runs inside the frame differ's `decorate` hook rather than in React (D-6):
+ * a re-render per drag event goes through the render governor and the whole
+ * component tree, while this repaints one to three rows with no commit at all.
+ */
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+/**
+ * The SGR sequence that opens a highlighted run.
+ *
+ * TRUECOLOR OR REVERSE VIDEO, WITH NOTHING IN BETWEEN, and that is deliberate.
+ * `getTheme` degrades every palette colour to the terminal's depth, so below
+ * ansi-256 `theme.selectionBg` is a CHALK COLOUR NAME (`'blue'`) rather than a
+ * hex triple — and a name cannot be turned into an escape sequence here without
+ * duplicating chalk's own table. Reverse video is what a terminal that shallow
+ * would render anyway, it needs no colour support at all, and it is exactly what
+ * the emulator's own selection looks like. The `HEX` test is therefore both the
+ * colour-depth check and the type check.
+ */
+export declare function selectionOpen(theme: Theme, caps: TermCapabilities): string;
+/**
+ * Paint `[from, to)` of one frame line.
+ *
+ * `to` is already clamped to the terminal width by the caller, so `Infinity`
+ * never reaches here.
+ *
+ * STRIPPING SGR INSIDE THE SELECTION IS NOT LAZINESS. An inner `\x1b[0m` — which
+ * `Markdown` and `cli-highlight` emit constantly — would cancel the highlight
+ * attribute mid-run and leave holes in it. Terminals repaint selected text in
+ * the selection's own colours for exactly this reason.
+ *
+ * `pad` is what gives a multi-row selection a straight right edge over short
+ * lines, and it measures with `columnsOf` — the same oracle `sliceColumns`
+ * charges with — rather than reaching for a third width function (I-12).
+ */
+export declare function paintRow(line: string, from: number, to: number, open: string): string;

package/dist/ui/selection/highlight.js

@@ -0,0 +1,64 @@
+/**
+ * The row painter (tui-selection-and-scroll-follow §4.4.4). PURE — strings in,
+ * strings out.
+ *
+ * It runs inside the frame differ's `decorate` hook rather than in React (D-6):
+ * a re-render per drag event goes through the render governor and the whole
+ * component tree, while this repaints one to three rows with no commit at all.
+ */
+import stripAnsi from 'strip-ansi';
+import { columnsOf, sliceColumns } from './selection.js';
+const CSI = '\x1b[';
+const SGR_RESET = `${CSI}0m`;
+/** Reverse video — the universal fallback, and what a monochrome terminal gets. */
+const REVERSE = `${CSI}7m`;
+const HEX = /^#[0-9a-f]{6}$/i;
+function rgb(hex) {
+    const n = Number.parseInt(hex.slice(1), 16);
+    return `${(n >> 16) & 0xff};${(n >> 8) & 0xff};${n & 0xff}`;
+}
+/**
+ * The SGR sequence that opens a highlighted run.
+ *
+ * TRUECOLOR OR REVERSE VIDEO, WITH NOTHING IN BETWEEN, and that is deliberate.
+ * `getTheme` degrades every palette colour to the terminal's depth, so below
+ * ansi-256 `theme.selectionBg` is a CHALK COLOUR NAME (`'blue'`) rather than a
+ * hex triple — and a name cannot be turned into an escape sequence here without
+ * duplicating chalk's own table. Reverse video is what a terminal that shallow
+ * would render anyway, it needs no colour support at all, and it is exactly what
+ * the emulator's own selection looks like. The `HEX` test is therefore both the
+ * colour-depth check and the type check.
+ */
+export function selectionOpen(theme, caps) {
+    if (caps.colorLevel < 2)
+        return REVERSE;
+    const bg = theme.selectionBg;
+    const fg = theme.selectionFg;
+    if (!bg || !fg || !HEX.test(bg) || !HEX.test(fg))
+        return REVERSE;
+    return `${CSI}48;2;${rgb(bg)}m${CSI}38;2;${rgb(fg)}m`;
+}
+/**
+ * Paint `[from, to)` of one frame line.
+ *
+ * `to` is already clamped to the terminal width by the caller, so `Infinity`
+ * never reaches here.
+ *
+ * STRIPPING SGR INSIDE THE SELECTION IS NOT LAZINESS. An inner `\x1b[0m` — which
+ * `Markdown` and `cli-highlight` emit constantly — would cancel the highlight
+ * attribute mid-run and leave holes in it. Terminals repaint selected text in
+ * the selection's own colours for exactly this reason.
+ *
+ * `pad` is what gives a multi-row selection a straight right edge over short
+ * lines, and it measures with `columnsOf` — the same oracle `sliceColumns`
+ * charges with — rather than reaching for a third width function (I-12).
+ */
+export function paintRow(line, from, to, open) {
+    if (!(to > from))
+        return line;
+    const head = sliceColumns(line, 0, from);
+    const mid = stripAnsi(sliceColumns(line, from, to));
+    const pad = ' '.repeat(Math.max(0, to - from - columnsOf(mid)));
+    const tail = sliceColumns(line, to);
+    return `${head}${open}${mid}${pad}${SGR_RESET}${tail}`;
+}

package/dist/ui/selection/screen-mirror.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The screen mirror (tui-selection-and-scroll-follow §7) — the single source of
+ * truth for what text is on which row.
+ *
+ * I-4 RIDES ON THIS OBJECT. The highlight and the clipboard both read the rows
+ * stored here, written by the same `decorate` call, so whatever changes under a
+ * selection is simultaneously what is highlighted and what would be copied. What
+ * you see is what you get BY CONSTRUCTION, rather than by a staleness check that
+ * can be wrong.
+ *
+ * `plain` is computed LAZILY. `decorate` runs on every frame Ink produces —
+ * 15-30 times a second during a run — while a copy happens when a human releases
+ * a mouse button, so stripping every row eagerly would spend H regex passes per
+ * frame to serve an event that may never come. The cache is dropped by `set`, so
+ * the laziness is invisible to callers and cannot go stale.
+ */
+export interface ScreenMirror {
+    /** Last frame, ANSI intact — what `decorate` paints over. */
+    readonly raw: readonly string[];
+    /** The same rows, ANSI stripped — what `selectedText` reads. */
+    readonly plain: readonly string[];
+    set(lines: readonly string[]): void;
+}
+export declare function createScreenMirror(): ScreenMirror;

package/dist/ui/selection/screen-mirror.js

@@ -0,0 +1,35 @@
+/**
+ * The screen mirror (tui-selection-and-scroll-follow §7) — the single source of
+ * truth for what text is on which row.
+ *
+ * I-4 RIDES ON THIS OBJECT. The highlight and the clipboard both read the rows
+ * stored here, written by the same `decorate` call, so whatever changes under a
+ * selection is simultaneously what is highlighted and what would be copied. What
+ * you see is what you get BY CONSTRUCTION, rather than by a staleness check that
+ * can be wrong.
+ *
+ * `plain` is computed LAZILY. `decorate` runs on every frame Ink produces —
+ * 15-30 times a second during a run — while a copy happens when a human releases
+ * a mouse button, so stripping every row eagerly would spend H regex passes per
+ * frame to serve an event that may never come. The cache is dropped by `set`, so
+ * the laziness is invisible to callers and cannot go stale.
+ */
+import stripAnsi from 'strip-ansi';
+export function createScreenMirror() {
+    let raw = [];
+    let plain = null;
+    return {
+        get raw() {
+            return raw;
+        },
+        get plain() {
+            if (plain === null)
+                plain = raw.map((line) => stripAnsi(line));
+            return plain;
+        },
+        set(lines) {
+            raw = lines;
+            plain = null;
+        },
+    };
+}

package/dist/ui/selection/selection-controller.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The selection controller (tui-selection-and-scroll-follow §4.4). NON-REACT: it
+ * owns the mouse lifecycle, the 16 ms drag coalescer, the `decorate` hook and the
+ * copy-on-release, and it reaches the React tree only through the two callbacks
+ * `App` registers on mount.
+ *
+ * WHY IT IS NOT A COMPONENT (D-6). A React re-render per motion report goes
+ * through the render governor and the whole component tree; the frame pipeline
+ * repaints one to three rows with no commit at all. A fast drag across 40 columns
+ * therefore costs about three repaints of a few rows each, not forty full frames.
+ *
+ * THREE THINGS IN HERE FAIL SILENTLY AND PERMANENTLY IF DROPPED:
+ *
+ *  - **I-11 · `hold` must always have a way out.** A press with no matching
+ *    release freezes the viewport for the rest of the session: content anchoring
+ *    never lets go, the resume timer's third condition never passes, and nothing
+ *    is raised anywhere. Three ways to never get a release — the button comes up
+ *    while the terminal does not have focus, the emulator swallows it, or the
+ *    terminal fell back to X10, whose reports cannot express a release at all.
+ *    So `hold` is released by a `release` report, by `clear()`, OR by the
+ *    `holdMaxMs` watchdog, and the parser refuses to emit buttons from X10.
+ *  - **I-9 · a highlight that survives the rows moving is a lie about what would
+ *    be copied.** `App` clears on `shiftUp` change — the DERIVED form, which a
+ *    new way to move the viewport cannot forget to join — and additionally on
+ *    key, resize, overlay and `differ.invalidate()`.
+ *  - **I-4 · the highlight and the copy read the SAME mirror**, written by the
+ *    same `decorate` call. What you see is what you get by construction, rather
+ *    than by a staleness check that can be wrong.
+ */
+import type { MouseSource } from '../../input/stdin-filter.js';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { CopyVia } from '../clipboard.js';
+/**
+ * How long a nominally-held button may sit MOTIONLESS before the watchdog lets
+ * go of it (I-11). Reset by every motion report, so it only fires when the
+ * pointer has not moved for the whole window — which is indistinguishable from a
+ * lost release, and the failure it prevents is unrecoverable while the one it
+ * risks costs a re-drag (R-12).
+ */
+export declare const DEFAULT_HOLD_MAX_MS = 30000;
+export interface SelectionControllerOptions {
+    source: MouseSource;
+    /**
+     * Ask the frame writer to re-paint. Returns whether anything reached the
+     * screen; `false` means the differ had no cache to diff against, and the
+     * caller falls back to `requestRedraw`.
+     */
+    repaint: () => boolean;
+    /** `App`'s `redrawNonce`, for the invalidated case (§4.4.3). */
+    requestRedraw: () => void;
+    copy: (text: string) => CopyVia;
+    /** Toast sink, registered by `App` on mount (§6.3). */
+    onCopied: (via: CopyVia, lines: number, chars: number) => void;
+    theme: () => Theme;
+    caps: TermCapabilities;
+    /** Terminal width, for the right edge of a multi-row highlight. */
+    cols: () => number;
+    /** Static half of the gate: full-screen and `mouseSelect`. */
+    isSelectable?: () => boolean;
+    /** I-11. Default 30_000; `0` disables the watchdog (tests). */
+    holdMaxMs?: number;
+}
+export interface SelectionController {
+    /** Feed to `createFrameDiffer({ decorate })`. Mirrors, then paints. */
+    decorate(lines: string[]): string[];
+    /** Subscribe to `hold` transitions; `App` mirrors this into React state. */
+    onHoldChange(listener: (hold: boolean) => void): () => void;
+    /** Called by `App` for key / resize / overlay / clear, and by `onInvalidate`. */
+    clear(): void;
+    /** The dynamic half of the gate: `App` closes it while an overlay is open. */
+    setEnabled(enabled: boolean): void;
+    dispose(): void;
+}
+/**
+ * The seam between the non-React controller and the React tree.
+ *
+ * SAME SHAPE AS `UpdateBridge` (`cli.tsx`), and for the same reason: the
+ * controller is constructed before `render()` and must not hold React state,
+ * while the toast sink and the redraw nonce only exist once `App` has mounted.
+ * `App` assigns both fields in an effect and clears them on unmount.
+ */
+export interface SelectionBridge {
+    controller: SelectionController | null;
+    onCopied: ((via: CopyVia, lines: number, chars: number) => void) | null;
+    requestRedraw: (() => void) | null;
+}
+export declare function createSelectionController(options: SelectionControllerOptions): SelectionController;

package/dist/ui/selection/selection-controller.js

@@ -0,0 +1,282 @@
+/**
+ * The selection controller (tui-selection-and-scroll-follow §4.4). NON-REACT: it
+ * owns the mouse lifecycle, the 16 ms drag coalescer, the `decorate` hook and the
+ * copy-on-release, and it reaches the React tree only through the two callbacks
+ * `App` registers on mount.
+ *
+ * WHY IT IS NOT A COMPONENT (D-6). A React re-render per motion report goes
+ * through the render governor and the whole component tree; the frame pipeline
+ * repaints one to three rows with no commit at all. A fast drag across 40 columns
+ * therefore costs about three repaints of a few rows each, not forty full frames.
+ *
+ * THREE THINGS IN HERE FAIL SILENTLY AND PERMANENTLY IF DROPPED:
+ *
+ *  - **I-11 · `hold` must always have a way out.** A press with no matching
+ *    release freezes the viewport for the rest of the session: content anchoring
+ *    never lets go, the resume timer's third condition never passes, and nothing
+ *    is raised anywhere. Three ways to never get a release — the button comes up
+ *    while the terminal does not have focus, the emulator swallows it, or the
+ *    terminal fell back to X10, whose reports cannot express a release at all.
+ *    So `hold` is released by a `release` report, by `clear()`, OR by the
+ *    `holdMaxMs` watchdog, and the parser refuses to emit buttons from X10.
+ *  - **I-9 · a highlight that survives the rows moving is a lie about what would
+ *    be copied.** `App` clears on `shiftUp` change — the DERIVED form, which a
+ *    new way to move the viewport cannot forget to join — and additionally on
+ *    key, resize, overlay and `differ.invalidate()`.
+ *  - **I-4 · the highlight and the copy read the SAME mirror**, written by the
+ *    same `decorate` call. What you see is what you get by construction, rather
+ *    than by a staleness check that can be wrong.
+ */
+import { createScreenMirror } from './screen-mirror.js';
+import { paintRow, selectionOpen } from './highlight.js';
+import { isEmpty, normalize, rowSpan, selectedText, } from './selection.js';
+/**
+ * Motion coalescing window. The same 16 ms and the same reasoning as
+ * `use-wheel-routing.ts`: this one is in the direct path of a hand gesture, so
+ * it is deliberately tighter than the 33 ms streaming coalescer.
+ */
+const DRAG_COALESCE_MS = 16;
+/**
+ * How long a nominally-held button may sit MOTIONLESS before the watchdog lets
+ * go of it (I-11). Reset by every motion report, so it only fires when the
+ * pointer has not moved for the whole window — which is indistinguishable from a
+ * lost release, and the failure it prevents is unrecoverable while the one it
+ * risks costs a re-drag (R-12).
+ */
+export const DEFAULT_HOLD_MAX_MS = 30_000;
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+export function createSelectionController(options) {
+    const mirror = createScreenMirror();
+    const holdListeners = new Set();
+    const holdMaxMs = options.holdMaxMs ?? DEFAULT_HOLD_MAX_MS;
+    const isSelectable = options.isSelectable ?? (() => true);
+    let enabled = true;
+    let sel = null;
+    let dragging = false;
+    let pendingFocus = null;
+    let flushTimer = null;
+    let holdWatchdog = null;
+    let disposed = false;
+    /** Guards `decorate` against being re-entered from inside a repaint. */
+    let painting = false;
+    const emitHold = (hold) => {
+        for (const listener of [...holdListeners])
+            listener(hold);
+    };
+    const clearFlushTimer = () => {
+        if (!flushTimer)
+            return;
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    };
+    const clearWatchdog = () => {
+        if (!holdWatchdog)
+            return;
+        clearTimeout(holdWatchdog);
+        holdWatchdog = null;
+    };
+    /**
+     * `0` disables it, which is what the tests that are not about it use. Every
+     * motion report re-arms it, so the window measures STILLNESS rather than the
+     * duration of the drag (R-12).
+     */
+    const armWatchdog = () => {
+        clearWatchdog();
+        if (holdMaxMs <= 0)
+            return;
+        holdWatchdog = setTimeout(() => {
+            holdWatchdog = null;
+            if (!dragging)
+                return;
+            // Let go of `hold` and the drag; KEEP whatever was selected. The user may
+            // still want to copy it, and throwing it away would turn a terminal quirk
+            // into lost work.
+            dragging = false;
+            pendingFocus = null;
+            clearFlushTimer();
+            emitHold(false);
+        }, holdMaxMs);
+        holdWatchdog.unref?.();
+    };
+    /**
+     * Repaint, falling back to a React redraw when the differ has no cache.
+     *
+     * `wanted` says whether something must APPEAR on screen. Clearing a highlight
+     * after an `invalidate()` needs no fallback — the raw frame is already on the
+     * screen without it — and asking for one there would turn every resize and
+     * every foreign write into a redraw nonce bump.
+     */
+    const paint = (wanted) => {
+        if (disposed)
+            return;
+        const painted = options.repaint();
+        if (!painted && wanted)
+            options.requestRedraw();
+    };
+    const clear = () => {
+        // Nothing to undo: no timers, no repaint, no redraw. This is what keeps
+        // `onInvalidate` — which fires on every resize and every foreign write —
+        // free for a session that has never selected anything.
+        if (sel === null && !dragging && pendingFocus === null)
+            return;
+        const wasDragging = dragging;
+        sel = null;
+        dragging = false;
+        pendingFocus = null;
+        clearFlushTimer();
+        clearWatchdog();
+        if (wasDragging)
+            emitHold(false);
+        paint(false);
+    };
+    const cellOf = (event) => {
+        // SGR reports are 1-based, frame line `i` is terminal row `i + 1`. A report
+        // from a terminal that resized mid-drag must not index past the mirror.
+        const rows = Math.max(1, mirror.raw.length);
+        const cols = Math.max(1, options.cols());
+        return { row: clamp(event.y - 1, 0, rows - 1), col: clamp(event.x - 1, 0, cols - 1) };
+    };
+    const flushDrag = () => {
+        clearFlushTimer();
+        const focus = pendingFocus;
+        pendingFocus = null;
+        if (!focus || !sel)
+            return;
+        sel = { anchor: sel.anchor, focus };
+        paint(true);
+    };
+    const finishSelection = () => {
+        if (!sel)
+            return;
+        const normal = normalize(sel);
+        if (isEmpty(normal)) {
+            // A plain click. It must never leave a one-cell highlight behind, and it
+            // must never clobber the clipboard.
+            sel = null;
+            paint(false);
+            return;
+        }
+        const text = selectedText(mirror.plain, normal);
+        if (text.length === 0) {
+            sel = null;
+            paint(false);
+            return;
+        }
+        const via = options.copy(text);
+        options.onCopied(via, text.split('\n').length, text.length);
+        // The highlight STAYS after a release: it is the receipt for what was taken,
+        // and it goes away on the next thing that moves the rows (I-9).
+        paint(true);
+    };
+    const onMouse = (event) => {
+        if (disposed)
+            return;
+        if (event.kind === 'wheel') {
+            // A wheel notch during a drag is a user changing their mind, not extending
+            // a selection — N1 already declines auto-scroll-while-dragging. The notch
+            // then scrolls normally, because the wheel router is a separate subscriber
+            // on the same channel.
+            if (dragging)
+                clear();
+            return;
+        }
+        if (event.kind === 'press') {
+            if (event.button !== 0 || !enabled || !isSelectable()) {
+                // Any other button, or a closed gate: drop whatever was selected and do
+                // nothing else. A right-click that left a stale highlight behind would be
+                // the same false promise I-9 forbids.
+                clear();
+                return;
+            }
+            const cell = cellOf(event);
+            sel = { anchor: cell, focus: cell };
+            pendingFocus = null;
+            clearFlushTimer();
+            dragging = true;
+            emitHold(true); // freezes the transcript for the duration of the drag
+            armWatchdog();
+            paint(true);
+            return;
+        }
+        if (event.kind === 'drag') {
+            if (!dragging || event.button !== 0 || !sel)
+                return;
+            pendingFocus = cellOf(event);
+            armWatchdog();
+            if (!flushTimer) {
+                flushTimer = setTimeout(flushDrag, DRAG_COALESCE_MS);
+                flushTimer.unref?.();
+            }
+            return;
+        }
+        // release
+        if (!dragging)
+            return;
+        if (pendingFocus && sel)
+            sel = { anchor: sel.anchor, focus: pendingFocus };
+        pendingFocus = null;
+        clearFlushTimer();
+        clearWatchdog();
+        dragging = false;
+        emitHold(false);
+        finishSelection();
+    };
+    const unsubscribe = options.source.subscribe(onMouse);
+    return {
+        decorate(lines) {
+            mirror.set(lines);
+            if (painting || sel === null)
+                return lines;
+            const normal = normalize(sel);
+            if (isEmpty(normal))
+                return lines;
+            painting = true;
+            try {
+                const open = selectionOpen(options.theme(), options.caps);
+                const cols = Math.max(1, options.cols());
+                const out = lines.slice();
+                for (let row = normal.start.row; row <= normal.end.row; row += 1) {
+                    if (row < 0 || row >= out.length)
+                        continue;
+                    const span = rowSpan(normal, row);
+                    if (!span)
+                        continue;
+                    const to = Math.min(Number.isFinite(span.to) ? span.to : cols, cols);
+                    out[row] = paintRow(out[row], span.from, to, open);
+                }
+                return out;
+            }
+            finally {
+                painting = false;
+            }
+        },
+        onHoldChange(listener) {
+            holdListeners.add(listener);
+            return () => holdListeners.delete(listener);
+        },
+        clear,
+        setEnabled(next) {
+            if (enabled === next)
+                return;
+            enabled = next;
+            if (!next)
+                clear();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            unsubscribe();
+            clearFlushTimer();
+            clearWatchdog();
+            holdListeners.clear();
+            sel = null;
+            dragging = false;
+            pendingFocus = null;
+        },
+    };
+}

package/dist/ui/selection/selection.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The selection model (tui-selection-and-scroll-follow §4.4.4). PURE — no React,
+ * no I/O, no terminal.
+ *
+ * Coordinates are SCREEN CELLS, 0-based: frame line `i` is terminal row `i + 1`
+ * and column `x - 1`, so an SGR report at `(x, y)` becomes `{ row: y - 1, col: x
+ * - 1 }`. Screen coordinates are only sound while the rows hold still, and
+ * holding them still is Stage 2's job — `press` sets `hold`, which anchors the
+ * content and suspends the resume timer, so the transcript is frozen for the
+ * duration of a drag (D-7).
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * I-12 — `sliceColumns` IS THE ONE COLUMN→CHARACTER MAPPING IN THIS FEATURE,
+ * and `stringWidth` is its only width oracle.
+ *
+ * The painter and the extractor are handed the SAME half-open column range by
+ * `rowSpan`. If they turn that range into characters by different rules, the
+ * copied text is not the highlighted text — silently, which is the one failure
+ * mode I-4 exists to name. That is not hypothetical: `slice-ansi` advances its
+ * cursor by `isFullWidth ? 2 : character.length`, i.e. display columns for CJK
+ * but UTF-16 CODE UNITS for everything else, so a combining mark costs it a
+ * column that occupies none and an astral code point costs two; and the obvious
+ * `String.slice` for the extractor is code units throughout. Two mappings from
+ * one range agree on ASCII and diverge on exactly the rows a user is most likely
+ * to want to copy.
+ *
+ * So both call the function below, which walks GRAPHEME CLUSTERS and charges
+ * each one `stringWidth(cluster)` columns. What is hand-rolled here is only the
+ * column arithmetic — the width table is still `string-width`'s, and the escape
+ * bookkeeping is `slice-ansi`'s idea re-indexed (R-13).
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+export interface Cell {
+    /** 0-based frame line. */
+    row: number;
+    /** 0-based screen column. */
+    col: number;
+}
+export interface Selection {
+    anchor: Cell;
+    focus: Cell;
+}
+/** `start <= end` in reading order. */
+export interface NormalSelection {
+    start: Cell;
+    end: Cell;
+}
+/** A half-open column range on one row; `to` may be `Infinity` (to end of line). */
+export interface RowSpan {
+    from: number;
+    to: number;
+}
+export declare function normalize(sel: Selection): NormalSelection;
+export declare function isEmpty(sel: NormalSelection): boolean;
+/**
+ * The half-open column range to highlight on `row`, or `null` when the row is
+ * outside the selection.
+ *
+ * LINEAR, NOT RECTANGULAR — what every terminal does: the first row runs from
+ * `start.col` to end of line, whole middle rows are taken entirely, and the last
+ * row stops at `end.col`. `Infinity` means "to the end of the line"; the painter
+ * clamps it to the terminal width so a multi-row selection gets a straight right
+ * edge, and the extractor treats it as "no upper bound".
+ */
+export declare function rowSpan(sel: NormalSelection, row: number): RowSpan | null;
+/**
+ * The text a release would put on the clipboard.
+ *
+ * `plainRows` are the mirror's ANSI-STRIPPED rows — the same rows the highlight
+ * was painted over, which is what makes I-4 hold by construction rather than by
+ * a staleness check that can be wrong.
+ */
+export declare function selectedText(plainRows: readonly string[], sel: NormalSelection): string;
+/**
+ * Slice `text` by SCREEN COLUMNS, half-open `[from, to)`.
+ *
+ * Three properties are load-bearing:
+ *
+ *  - **Escape codes opened before `from` are carried into the result.** Without
+ *    it the painter's tail — `sliceColumns(line, to)` — would lose the colour
+ *    `Markdown` and `cli-highlight` gave it, on every row a selection touches.
+ *  - **A wide cluster straddling either boundary becomes spaces for the part
+ *    that is inside.** That keeps the arithmetic EXACT in columns, which is the
+ *    whole point of I-12: half a CJK glyph is not a character, and inventing one
+ *    would put the painter and the extractor back out of step.
+ *  - **`to` is optional and means "to the end of the line".**
+ */
+export declare function sliceColumns(text: string, from: number, to?: number): string;
+/** Display width in columns, using the same oracle `sliceColumns` charges with. */
+export declare function columnsOf(text: string): number;