@aragon-agent/cli 0.6.1 → 0.6.3

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;

package/dist/ui/selection/selection.js

@@ -0,0 +1,223 @@
+/**
+ * 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).
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+import stringWidth from 'string-width';
+export function normalize(sel) {
+    const { anchor, focus } = sel;
+    const anchorFirst = anchor.row < focus.row || (anchor.row === focus.row && anchor.col <= focus.col);
+    return anchorFirst ? { start: anchor, end: focus } : { start: focus, end: anchor };
+}
+export function isEmpty(sel) {
+    return sel.start.row === sel.end.row && sel.start.col === sel.end.col;
+}
+/**
+ * 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 function rowSpan(sel, row) {
+    const { start, end } = sel;
+    if (row < start.row || row > end.row)
+        return null;
+    if (start.row === end.row) {
+        return end.col > start.col ? { from: start.col, to: end.col } : null;
+    }
+    if (row === start.row)
+        return { from: start.col, to: Number.POSITIVE_INFINITY };
+    if (row === end.row)
+        return end.col > 0 ? { from: 0, to: end.col } : null;
+    return { from: 0, to: Number.POSITIVE_INFINITY };
+}
+/**
+ * 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 function selectedText(plainRows, sel) {
+    const out = [];
+    for (let row = sel.start.row; row <= sel.end.row; row += 1) {
+        const span = rowSpan(sel, row);
+        if (!span)
+            continue;
+        const line = plainRows[row] ?? '';
+        const to = Number.isFinite(span.to) ? span.to : undefined;
+        out.push(sliceColumns(line, span.from, to).trimEnd());
+    }
+    return out.join('\n');
+}
+// ---------------------------------------------------------------------------
+// sliceColumns — the one mapping (I-12)
+// ---------------------------------------------------------------------------
+/**
+ * CSI / OSC sequences. They occupy ZERO columns and are copied through so a
+ * slice keeps the styling of the text around it.
+ */
+const ANSI_RE = /\x1b(?:\[[0-9;:?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])/g;
+/** SGR "all attributes off" — everything carried before it is cancelled. */
+const SGR_RESET_RE = /^\x1b\[0?m$/;
+const segmenter = typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    : null;
+/**
+ * Width cache. `stringWidth` re-segments and re-classifies on every call, and a
+ * repaint slices every row of the selection; the key space is the set of
+ * grapheme clusters on screen, which is tiny and bounded by the frame.
+ */
+const widthCache = new Map();
+const WIDTH_CACHE_MAX = 4096;
+function clusterWidth(cluster) {
+    const hit = widthCache.get(cluster);
+    if (hit !== undefined)
+        return hit;
+    const w = stringWidth(cluster);
+    // A plain ceiling with a wholesale drop, like `virtual-window.ts`'s height
+    // cache: an LRU here would cost more bookkeeping than the values are worth.
+    if (widthCache.size >= WIDTH_CACHE_MAX)
+        widthCache.clear();
+    widthCache.set(cluster, w);
+    return w;
+}
+/** Split into ANSI sequences and grapheme clusters, in order. */
+function tokenize(text) {
+    const tokens = [];
+    ANSI_RE.lastIndex = 0;
+    let last = 0;
+    let m;
+    const pushPlain = (chunk) => {
+        if (chunk.length === 0)
+            return;
+        if (segmenter) {
+            for (const { segment } of segmenter.segment(chunk))
+                tokens.push({ text: segment, ansi: false });
+            return;
+        }
+        // No `Intl.Segmenter`: code points are a strictly worse but never wrong
+        // approximation — a combining mark becomes its own zero-width token, which
+        // the walk below already handles.
+        for (const cp of chunk)
+            tokens.push({ text: cp, ansi: false });
+    };
+    while ((m = ANSI_RE.exec(text)) !== null) {
+        pushPlain(text.slice(last, m.index));
+        tokens.push({ text: m[0], ansi: true });
+        last = m.index + m[0].length;
+    }
+    pushPlain(text.slice(last));
+    return tokens;
+}
+/**
+ * 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 function sliceColumns(text, from, to) {
+    const start = Math.max(0, Math.floor(from));
+    const end = to === undefined || !Number.isFinite(to) ? Number.POSITIVE_INFINITY : Math.floor(to);
+    if (end <= start)
+        return '';
+    let carried = '';
+    let out = '';
+    let col = 0;
+    let started = false;
+    const open = () => {
+        if (started)
+            return;
+        started = true;
+        out += carried;
+    };
+    for (const token of tokenize(text)) {
+        if (token.ansi) {
+            if (started)
+                out += token.text;
+            else {
+                if (SGR_RESET_RE.test(token.text))
+                    carried = '';
+                carried += token.text;
+            }
+            continue;
+        }
+        if (col >= end)
+            break;
+        const w = clusterWidth(token.text);
+        if (w === 0) {
+            // A zero-width cluster attaches to the cell before it, so it belongs to the
+            // slice only when that cell is already inside.
+            if (started)
+                out += token.text;
+            continue;
+        }
+        const cellEnd = col + w;
+        if (cellEnd <= start) {
+            col = cellEnd;
+            continue;
+        }
+        open();
+        if (col < start) {
+            // Straddles the LEFT boundary: only `cellEnd - start` columns are ours.
+            out += ' '.repeat(Math.min(cellEnd, end) - start);
+        }
+        else if (cellEnd > end) {
+            // Straddles the RIGHT boundary.
+            out += ' '.repeat(end - col);
+        }
+        else {
+            out += token.text;
+        }
+        col = cellEnd;
+    }
+    return out;
+}
+/** Display width in columns, using the same oracle `sliceColumns` charges with. */
+export function columnsOf(text) {
+    let total = 0;
+    for (const token of tokenize(text)) {
+        if (!token.ansi)
+            total += clusterWidth(token.text);
+    }
+    return total;
+}

package/dist/ui/stdout-frame-writer.d.ts

@@ -35,6 +35,39 @@ export interface FrameWriterHandle {
     stdout: NodeJS.WriteStream;
     /** Hand this to `setFrameStatsProvider`. */
     stats(): FrameWriterStats;
+    /**
+     * Re-paint the last frame through the differ's `decorate` hook — how a
+     * selection drag reaches the screen without a React commit.
+     *
+     * Returns whether anything was written. `false` means the differ had nothing
+     * safe to do (no cache, or a geometry stand-down), which is the caller's cue to
+     * fall back to `App`'s `redrawNonce`.
+     *
+     * I-3 / I-13 — IT WRITES TO THE REAL STREAM, NEVER THROUGH THE PROXY. Through
+     * the proxy the payload would be handed to `transform`, which would not
+     * recognise it and would `invalidate()`, turning every drag frame into a full
+     * repaint — the flicker `tui-input-flicker-fix` removed. It is also not a
+     * fallback and not a frame, so it touches neither counter.
+     */
+    repaint(): boolean;
+    /**
+     * Write bytes that are ours but are not a frame — today, the OSC 52 clipboard
+     * sequence (§4.4.5).
+     *
+     * The differ is invalidated first, because absolute addressing is only valid
+     * while nothing else writes to stdout, and one full repaint after a copy is the
+     * correct price.
+     *
+     * IT IS NOT A FALLBACK (P1-6 / I-13), and that is the whole reason this door
+     * exists rather than the caller reaching for `stdout.write`. `transform` cannot
+     * recognise an OSC 52 chunk, so through the proxy it would take
+     * `passThrough(true)` — which increments `fallbacks` and, on the first one,
+     * raises `onFirstFallback`, wired to `console.warn(FRAME_FALLBACK_NOTICE)`.
+     * The first copy of every session would print a diagnostic at a user who did
+     * nothing wrong, and `fallbacks` — documented to mean "something wrote to
+     * stdout behind Ink's back" — would stop being true for the rest of the run.
+     */
+    writeForeign(text: string): void;
     /** Removes the `'resize'` subscription of I-8. Idempotent. */
     dispose(): void;
 }

package/dist/ui/stdout-frame-writer.js

@@ -92,6 +92,21 @@ export function wrapStdoutForFrames(stdout, differ) {
     return {
         stdout: proxy,
         stats: () => differ.stats(),
+        repaint() {
+            if (disposed)
+                return false;
+            const payload = differ.repaint();
+            if (payload.length === 0)
+                return false;
+            writeReal(payload);
+            return true;
+        },
+        writeForeign(text) {
+            differ.invalidate();
+            if (disposed || text.length === 0)
+                return;
+            writeReal(text);
+        },
         dispose() {
             if (disposed)
                 return;

package/dist/ui/theme.d.ts

@@ -50,6 +50,17 @@ export interface Theme {
     hintFg: Color;
     /** Single-color wordmark fallback below ansi-256. */
     logoShadow: Color;
+    /**
+     * Drag-selection highlight (tui-selection-and-scroll-follow §4.4.4).
+     *
+     * Degraded like every other colour here, which means that below ansi-256 these
+     * are chalk colour NAMES rather than hex triples. `highlight.ts` tests for a
+     * hex shape and falls back to plain reverse video otherwise — the fallback a
+     * terminal that shallow would render anyway, and what the emulator's own
+     * selection looks like.
+     */
+    selectionBg: Color;
+    selectionFg: Color;
     gradient: string[];
     gauge: {
         track: Color;

package/dist/ui/theme.js

@@ -101,6 +101,8 @@ export function getTheme(name, caps) {
         idleBorder: d(palette.idleBorder),
         hintFg: d(palette.hintFg),
         logoShadow: d(palette.logoShadow),
+        selectionBg: d(palette.selectionBg),
+        selectionFg: d(palette.selectionFg),
         gradient: level >= 2 ? [...palette.gradient] : [],
         gauge: {
             track: d(palette.gauge.track),