@aragon-agent/cli 0.6.47 → 0.6.48

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

@@ -1,104 +0,0 @@
-/**
- * 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 released-selection state Ctrl+C consumes, and it reaches the React tree
- * only through the 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 { CopyResult } from '../clipboard.js';
-import type { Theme } from '../theme.js';
-import type { TermCapabilities } from '../capabilities.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;
-    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[];
-    /**
-     * Whether a RELEASED, non-empty selection is waiting for Ctrl+C
-     * (tui-shift-enter-copy-queue 4.2). Dragging does not count: the gesture
-     * is not finished, and a copy key pressed mid-drag must fall through to
-     * whatever it meant before this feature.
-     */
-    hasPendingSelection(): boolean;
-    /**
-     * Take the pending selection: returns its text and line count, and clears
-     * the highlight, the settled state and the hold. `null` when nothing is
-     * pending. The caller owns the copy itself (`copyText` is the single
-     * clipboard path) and MUST take BEFORE copying: OSC 52 writes through
-     * `writeForeign`, the differ invalidates, and its `onInvalidate` clears
-     * this controller -- taking first makes that clear a no-op (4.3 / R7).
-     */
-    takeSelection(): {
-        text: string;
-        lines: number;
-    } | null;
-    /** 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: ((result: CopyResult, lines: number, chars: number) => void) | null;
-    requestRedraw: (() => void) | null;
-}
-export declare function createSelectionController(options: SelectionControllerOptions): SelectionController;

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

@@ -1,372 +0,0 @@
-/**
- * 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 released-selection state Ctrl+C consumes, and it reaches the React tree
- * only through the 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 stripAnsi from 'strip-ansi';
-import { createScreenMirror } from './screen-mirror.js';
-import { paintRow, selectionOpen } from './highlight.js';
-import { isEmpty, normalize, rowSpan, selectedText, sliceColumns, } 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;
-    /** A released, non-empty selection is waiting for Ctrl+C (4.2.1). */
-    let settled = false;
-    /** Mirror of the last `hold` emitted, so exits can be conditional. */
-    let holdActive = 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;
-    let notifiedHold = false;
-    let holdNotificationPending = false;
-    const notifyHold = () => {
-        if (disposed || notifiedHold === holdActive)
-            return;
-        notifiedHold = holdActive;
-        for (const listener of [...holdListeners])
-            listener(holdActive);
-    };
-    const emitHold = (hold) => {
-        holdActive = hold;
-        if (!painting) {
-            notifyHold();
-            return;
-        }
-        if (holdNotificationPending)
-            return;
-        holdNotificationPending = true;
-        queueMicrotask(() => {
-            holdNotificationPending = false;
-            notifyHold();
-        });
-    };
-    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;
-            clear();
-        }, 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 clearState = () => {
-        // 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 && !settled)
-            return;
-        sel = null;
-        dragging = false;
-        settled = false;
-        pendingFocus = null;
-        clearFlushTimer();
-        clearWatchdog();
-        // `holdActive`, not `wasDragging`: since tui-shift-enter-copy-queue a
-        // RELEASED selection also holds the viewport (4.2.3), so this is the
-        // exit for two states, not one.
-        if (holdActive)
-            emitHold(false);
-    };
-    const clear = () => {
-        const hadSelection = sel !== null || holdActive;
-        clearState();
-        if (hadSelection)
-            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) {
-            emitHold(false);
-            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;
-            settled = false;
-            emitHold(false);
-            paint(false);
-            return;
-        }
-        if (selectedText(mirror.plain, normal).length === 0) {
-            // Geometry without content (blank cells): nothing honest to promise a
-            // later Ctrl+C, so this is the same no-op a click is.
-            sel = null;
-            settled = false;
-            emitHold(false);
-            paint(false);
-            return;
-        }
-        // RELEASED AND NON-EMPTY: the highlight STAYS and so does the hold
-        // (4.2.1 / 4.2.3). The highlight is the promise of what Ctrl+C will
-        // copy -- not a receipt for a copy that already happened -- and the
-        // hold keeps the rows under it frozen until that promise resolves,
-        // which is what lets "what you see is what you get" survive a
-        // streaming run. The watchdog is NOT re-armed: the release already
-        // happened, and the frozen state has explicit exits (Ctrl+C, any other
-        // key, resize, overlay, /mouse off).
-        settled = true;
-        paint(true);
-        options.requestRedraw();
-    };
-    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.
-            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);
-            settled = false;
-            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;
-        // `finishSelection` decides the hold: a non-empty release KEEPS it
-        // (4.2.3) so the pending selection cannot be pushed off screen; every
-        // empty path releases it there.
-        finishSelection();
-    };
-    const unsubscribe = options.source.subscribe(onMouse);
-    const selectedCellsChanged = (lines) => {
-        if (!settled || !sel)
-            return false;
-        const normal = normalize(sel);
-        for (let row = normal.start.row; row <= normal.end.row; row += 1) {
-            const span = rowSpan(normal, row);
-            if (!span)
-                continue;
-            const before = sliceColumns(stripAnsi(mirror.raw[row] ?? ''), span.from, span.to);
-            const after = sliceColumns(stripAnsi(lines[row] ?? ''), span.from, span.to);
-            if (before !== after)
-                return true;
-        }
-        return false;
-    };
-    return {
-        decorate(lines) {
-            if (painting || disposed)
-                return lines;
-            painting = true;
-            try {
-                if (selectedCellsChanged(lines))
-                    clearState();
-                mirror.set(lines);
-                if (sel === null)
-                    return lines;
-                const normal = normalize(sel);
-                if (isEmpty(normal))
-                    return lines;
-                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);
-        },
-        hasPendingSelection() {
-            return settled && sel !== null;
-        },
-        takeSelection() {
-            if (!settled || sel === null)
-                return null;
-            const normal = normalize(sel);
-            const text = selectedText(mirror.plain, normal);
-            // CONSUMED BEFORE THE CALLER COPIES (4.3 / R7). The copy writes OSC
-            // 52 through `writeForeign`; the differ treats that as a foreign
-            // write and invalidates, and `onInvalidate` clears this controller on
-            // the next macrotask. Clearing first makes that callback a no-op;
-            // copying first would let it erase the held viewport state a tick
-            // after the copy -- the "copy flashes the screen" regression.
-            sel = null;
-            settled = false;
-            pendingFocus = null;
-            clearFlushTimer();
-            clearWatchdog();
-            if (holdActive)
-                emitHold(false);
-            paint(false);
-            if (text.length === 0)
-                return null;
-            return { text, lines: text.split('\n').length };
-        },
-        clear,
-        setEnabled(next) {
-            if (enabled === next)
-                return;
-            enabled = next;
-            if (!next)
-                clear();
-        },
-        dispose() {
-            if (disposed)
-                return;
-            // 4.2.3: a pending selection holds the viewport; teardown must let go
-            // of it explicitly, exactly like `clear()` does.
-            if (holdActive)
-                emitHold(false);
-            disposed = true;
-            unsubscribe();
-            clearFlushTimer();
-            clearWatchdog();
-            holdListeners.clear();
-            sel = null;
-            dragging = false;
-            pendingFocus = null;
-        },
-    };
-}

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

@@ -1,90 +0,0 @@
-/**
- * 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;