@aragon-agent/cli 0.6.2 → 0.6.3

package/dist/ui/overlays/SettingsScreen.d.ts

@@ -9,7 +9,7 @@
  */
 import React from 'react';
 import { type ThinkingLevel } from '@aragon-agent/core';
-import { type FastConfig } from '../../config/schema.js';
+import { type CompactionConfig, type FastConfig } from '../../config/schema.js';
 import { type LogLevelName } from '../../logging/levels.js';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
@@ -57,6 +57,33 @@ export interface SettingsValues {
     fastReview: string;
     /** The session review budget. `fastReview` is the PACE, this is the TOTAL. */
     fastReviewBudget: string;
+    /**
+     * Context compaction (context-auto-compaction §4.5).
+     *
+     * THREE ROWS, NOT SIX. `onFailure` and `useFastTier` are file- and
+     * `/compact`-only on purpose: this screen is for the settings a user CHANGES,
+     * not for every setting that exists, and "what should it do if the summarizer
+     * 500s" is not a question a user reaches for with arrow keys.
+     *
+     * `string` rather than their config types because this screen edits TEXT, and
+     * a typo must change NOTHING rather than resolve to a default — the discipline
+     * `maxTokens` and `fastReview` already follow here.
+     */
+    compactionEnabled: 'on' | 'off';
+    /** A percentage the user types, e.g. `90`. Parsed on save; a typo is ignored. */
+    compactionThreshold: string;
+    compactionKeepTurns: string;
+    /**
+     * The two hardening toggles (context-auto-compaction-hardening §4.6).
+     *
+     * FIVE ROWS NOW, NOT THREE, and these two earn their place where `onFailure`
+     * did not: each one names a THING THE SESSION WILL DO - spend money inside a
+     * fan-out, and write conversation content to disk - rather than a policy for a
+     * failure the user has never seen. Both are questions a user reaches for
+     * deliberately.
+     */
+    compactionSubagents: 'on' | 'off';
+    compactionArchive: 'on' | 'off';
 }
 interface SettingsScreenProps {
     initial: SettingsValues;
@@ -121,6 +148,25 @@ export declare function readFastSettings(values: Pick<SettingsValues, 'fastEnabl
  * save writes the clamp's default over whatever the user had.
  */
 export declare function fastSettingsFrom(fast: FastConfig): Pick<SettingsValues, 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview' | 'fastReviewBudget'>;
+/**
+ * Read the three compaction rows back into a config patch.
+ *
+ * A TYPO CHANGES NOTHING — the discipline `readFastSettings` states one function
+ * up, and the reason is the same: a threshold that silently resolved to the
+ * default on a mistyped keystroke would be a setting the user believes they
+ * changed and did not. `parseThresholdInput` returns `null` for anything that is
+ * not a ratio or a percentage, and the key is then simply absent from the patch.
+ */
+export declare function readCompactionSettings(values: Pick<SettingsValues, 'compactionEnabled' | 'compactionThreshold' | 'compactionKeepTurns' | 'compactionSubagents' | 'compactionArchive'>): Partial<CompactionConfig>;
+/**
+ * The inverse: seed the three rows from a resolved config.
+ *
+ * OMITTING A KEY HERE IS THE SILENT HALF OF ADDING A ROW, exactly as it is for
+ * the fast rows above: the row renders empty, `readCompactionSettings` sees an
+ * unparseable value, and an untouched save writes the clamp's default over
+ * whatever the user had.
+ */
+export declare function compactionSettingsFrom(compaction: CompactionConfig): Pick<SettingsValues, 'compactionEnabled' | 'compactionThreshold' | 'compactionKeepTurns' | 'compactionSubagents' | 'compactionArchive'>;
 /**
  * The cap this setting will ACTUALLY produce against the selected model.
  *

package/dist/ui/overlays/SettingsScreen.js

@@ -11,13 +11,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { Text, useInput } from 'ink';
 import { DEFAULT_MAX_OUTPUT_TOKENS, resolveOutputTokens, } from '@aragon-agent/core';
-import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret, parseMaxTokensInput, } from '../../config/schema.js';
+import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret, parseMaxTokensInput, parseThresholdInput, } from '../../config/schema.js';
 import { LOG_LEVEL_NAMES } from '../../logging/levels.js';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
 const SHOW_THINKING_OPTIONS = ['off', 'on'];
 const LIVE_OUTPUT_OPTIONS = ['off', 'on'];
 const FAST_ENABLED_OPTIONS = ['off', 'on'];
+const COMPACTION_ENABLED_OPTIONS = ['off', 'on'];
 /**
  * `(inherit)` IS THE EMPTY STRING, rendered as a word.
  *
@@ -107,6 +108,48 @@ export function fastSettingsFrom(fast) {
         fastReviewBudget: String(fast.reviewMaxPerSession),
     };
 }
+/**
+ * Read the three compaction rows back into a config patch.
+ *
+ * A TYPO CHANGES NOTHING — the discipline `readFastSettings` states one function
+ * up, and the reason is the same: a threshold that silently resolved to the
+ * default on a mistyped keystroke would be a setting the user believes they
+ * changed and did not. `parseThresholdInput` returns `null` for anything that is
+ * not a ratio or a percentage, and the key is then simply absent from the patch.
+ */
+export function readCompactionSettings(values) {
+    const threshold = parseThresholdInput(values.compactionThreshold);
+    const keep = values.compactionKeepTurns.trim();
+    const parsedKeep = /^\d+$/.test(keep) ? Number.parseInt(keep, 10) : Number.NaN;
+    return {
+        enabled: values.compactionEnabled === 'on',
+        ...(threshold !== null ? { threshold } : {}),
+        ...(Number.isFinite(parsedKeep) && parsedKeep > 0 ? { keepRecentTurns: parsedKeep } : {}),
+        // AN ENUM ROW CANNOT BE MISTYPED, so unlike the two text rows above these are
+        // written unconditionally.
+        subagents: values.compactionSubagents === 'on',
+        archive: values.compactionArchive === 'on',
+    };
+}
+/**
+ * The inverse: seed the three rows from a resolved config.
+ *
+ * OMITTING A KEY HERE IS THE SILENT HALF OF ADDING A ROW, exactly as it is for
+ * the fast rows above: the row renders empty, `readCompactionSettings` sees an
+ * unparseable value, and an untouched save writes the clamp's default over
+ * whatever the user had.
+ */
+export function compactionSettingsFrom(compaction) {
+    return {
+        compactionEnabled: compaction.enabled ? 'on' : 'off',
+        // A PERCENTAGE, because that is the unit the status bar shows and the unit a
+        // user thinks in. `parseThresholdInput` accepts it back.
+        compactionThreshold: String(Math.round(compaction.threshold * 100)),
+        compactionKeepTurns: String(compaction.keepRecentTurns),
+        compactionSubagents: compaction.subagents ? 'on' : 'off',
+        compactionArchive: compaction.archive ? 'on' : 'off',
+    };
+}
 const FIELDS = [
     { key: 'provider', label: 'Provider', kind: 'enum', options: ADAPTER_PROVIDERS },
     { key: 'model', label: 'Model', kind: 'text' },
@@ -146,6 +189,22 @@ const FIELDS = [
     { key: 'fastProvider', label: 'Fast provider', kind: 'enum', options: FAST_PROVIDER_OPTIONS },
     { key: 'fastReview', label: 'Fast review', kind: 'text' },
     { key: 'fastReviewBudget', label: 'Fast budget', kind: 'text' },
+    // Context compaction sits after the fast rows and still BEFORE `API key`, for
+    // the reason recorded above that row: the key is the one a user scrolls to
+    // deliberately, and burying it further would be worse than the ordering is
+    // better. Three rows, and every label is inside the 18-column budget
+    // `.padEnd(18)` enforces below.
+    //
+    // `Compact at` is a PERCENTAGE and carries no `(50-95)` hint, for the reason
+    // `Fast budget` records: no other bounded row carries its range either,
+    // `clampCompactionConfig` is the enforcement, and `/compact threshold` states
+    // the range in the one place a user meets it — when it refuses a bad one.
+    { key: 'compactionEnabled', label: 'Auto-compaction', kind: 'enum', options: COMPACTION_ENABLED_OPTIONS },
+    { key: 'compactionThreshold', label: 'Compact at %', kind: 'text' },
+    { key: 'compactionKeepTurns', label: 'Keep turns', kind: 'text' },
+    // Both labels are inside the 18-column budget `.padEnd(18)` enforces below.
+    { key: 'compactionSubagents', label: 'Compact children', kind: 'enum', options: COMPACTION_ENABLED_OPTIONS },
+    { key: 'compactionArchive', label: 'Archive dropped', kind: 'enum', options: COMPACTION_ENABLED_OPTIONS },
     { key: 'apiKey', label: 'API key', kind: 'secret' },
     { key: 'logLevel', label: 'Log level', kind: 'enum', options: LOG_LEVEL_NAMES },
 ];

package/dist/ui/palettes.d.ts

@@ -32,6 +32,22 @@ export interface Palette {
     idleBorder: string;
     hintFg: string;
     logoShadow: string;
+    /**
+     * Drag-selection highlight (tui-selection-and-scroll-follow §4.4.4).
+     *
+     * A PAIR, not a background alone: the selected run has its inner SGR stripped
+     * before it is repainted, so whatever foreground the row had is gone by the
+     * time the highlight is applied and a background on its own would leave the
+     * text at the terminal's default colour over an arbitrary hue. The two are
+     * contrast-pinned against EACH OTHER in `palettes.test.ts` — the surface a
+     * selected glyph sits on is `selectionBg`, not `DARK_SURFACE`.
+     *
+     * Below ansi-256 these never reach the terminal at all: `highlight.ts` emits
+     * plain reverse video there, because `getTheme` has degraded them to chalk
+     * colour NAMES by then and a name is not an escape sequence.
+     */
+    selectionBg: string;
+    selectionFg: string;
     gradient: [string, string, string];
     gauge: {
         track: string;

package/dist/ui/palettes.js

@@ -39,6 +39,8 @@ export const WARM = {
     idleBorder: '#4a423b',
     hintFg: '#9c9086',
     logoShadow: '#4a423b',
+    selectionBg: '#e0b088',
+    selectionFg: '#1c1917',
     gradient: ['#d08c60', '#c9a227', '#b0916a'],
     gauge: { track: '#4a423b', low: '#7fb08a', mid: '#c9a227', high: '#cf6b5c' },
     diff: { add: '#7fb08a', remove: '#cf6b5c', meta: '#d08c60', context: '#a2968a' },
@@ -66,6 +68,8 @@ export const COOL = {
     idleBorder: '#3b4261',
     hintFg: '#565f89',
     logoShadow: '#3b4261',
+    selectionBg: '#7aa2f7',
+    selectionFg: '#1a1b26',
     gradient: ['#7aa2f7', '#bb9af7', '#7dcfff'],
     gauge: { track: '#3b4261', low: '#9ece6a', mid: '#e0af68', high: '#f7768e' },
     diff: { add: '#9ece6a', remove: '#f7768e', meta: '#7aa2f7', context: '#7a86b8' },
@@ -92,6 +96,8 @@ export const LIGHT = {
     idleBorder: '#c8cdd6',
     hintFg: '#6b7280',
     logoShadow: '#c8cdd6',
+    selectionBg: '#2959aa',
+    selectionFg: '#ffffff',
     gradient: ['#2959aa', '#8c4bc9', '#0f7490'],
     gauge: { track: '#c8cdd6', low: '#2e7d32', mid: '#b5730f', high: '#c62828' },
     diff: { add: '#2e7d32', remove: '#c62828', meta: '#2959aa', context: '#6b7280' },

package/dist/ui/screen.d.ts

@@ -14,6 +14,16 @@
 export interface ScreenHandle {
     /** Leave the alternate screen. Idempotent — safe from every exit path. */
     restore(): void;
+    /**
+     * Hand the mouse back to the terminal for this session, or take it again
+     * (tui-selection-and-scroll-follow §4.4.6 / G3). A no-op when this session
+     * never had a filter, and idempotent in both directions.
+     *
+     * This is the honest answer to "a user who wants their terminal's own
+     * selection", and it is reversible in one command instead of a restart plus a
+     * config edit (D-9).
+     */
+    setMouseCapture(on: boolean): void;
 }
 export interface AltScreenOptions {
     /**
@@ -27,6 +37,18 @@ export interface AltScreenOptions {
      * only caller is `cli.tsx::runInteractive`, and it passes `filter !== null`.
      */
     readonly mouse: boolean;
+    /**
+     * Whether to request motion reporting (`?1002h`) alongside the two modes
+     * above — i.e. whether drag-select is on for this session.
+     *
+     * SAME "ALREADY DECIDED ELSEWHERE" DISCIPLINE AS `mouse`: this module must
+     * never derive it from config. `cli.tsx` passes
+     * `mouseFilter !== null && cfg.mouseSelect`.
+     *
+     * Optional, defaulting to `false`, so every pre-existing caller and every
+     * pre-existing test emits exactly the bytes it emitted before (AC-8 / T-34).
+     */
+    readonly motion?: boolean;
 }
 /**
  * Enter the alternate screen. A non-TTY stdout is a hard no-op (tests, pipes,

package/dist/ui/screen.js

@@ -20,12 +20,24 @@ const SHOW_CURSOR = '\x1b[?25h';
 /**
  * `?1000` is NORMAL TRACKING (press / release), the minimum mode that reports
  * wheel buttons; `?1006` selects SGR encoding so coordinates arrive as decimal
- * text rather than raw bytes above 0x7F that `setEncoding('utf8')` would
- * mangle. Motion tracking (`?1002` / `?1003`) is deliberately NOT enabled: it
- * floods stdin on every pointer move and buys nothing this feature uses.
+ * text rather than raw bytes above 0x7F that `setEncoding('utf8')` would mangle.
+ *
+ * `?1002` is BUTTON-EVENT TRACKING: motion is reported ONLY WHILE A BUTTON IS
+ * HELD, which is what drag-select needs and costs exactly zero reports while the
+ * pointer is idle. This comment used to lump it together with `?1003` and
+ * dismiss both as "floods stdin on every pointer move" — true of `?1003`
+ * (any-event), false of `?1002`, and the sentence had to go in the same commit
+ * that started asking for it or it would stand as a documented reason not to
+ * (AC-11 / D-10).
+ *
+ * IT IS GATED ON `motion`, i.e. on the resolved `mouseSelect` capability, and
+ * that is what makes "S3 is revertible" a byte-level fact rather than a claim:
+ * with drag-select off the sequences below are byte-identical to the constants
+ * they replaced (AC-8 / D-15). `disableMouse` is the exact reverse of
+ * `enableMouse` for both values (I-1 / AC-7).
  */
-const ENABLE_MOUSE = '\x1b[?1000h\x1b[?1006h';
-const DISABLE_MOUSE = '\x1b[?1006l\x1b[?1000l';
+const enableMouse = (motion) => `\x1b[?1000h${motion ? '\x1b[?1002h' : ''}\x1b[?1006h`;
+const disableMouse = (motion) => `\x1b[?1006l${motion ? '\x1b[?1002l' : ''}\x1b[?1000l`;
 /**
  * Alternate scroll (DEC private mode 1007) is what turns a wheel notch into a
  * burst of arrow keys, which `PromptInput` reads as prompt-history recall. With
@@ -43,7 +55,7 @@ const DISABLE_MOUSE = '\x1b[?1006l\x1b[?1000l';
  */
 const SAVE_ALT_SCROLL_OFF = '\x1b[?1007s\x1b[?1007l';
 const RESTORE_ALT_SCROLL = '\x1b[?1007r';
-const NOOP_HANDLE = { restore() { } };
+const NOOP_HANDLE = { restore() { }, setMouseCapture() { } };
 function safeWrite(stdout, data) {
     try {
         stdout.write(data);
@@ -60,7 +72,50 @@ export function enterAltScreen(stdout, options = { mouse: false }) {
     if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
         return NOOP_HANDLE;
     const mouse = options.mouse === true;
-    safeWrite(stdout, ENTER_ALT + CLEAR_VISIBLE + CURSOR_HOME + (mouse ? ENABLE_MOUSE : SAVE_ALT_SCROLL_OFF));
+    const motion = options.motion === true;
+    safeWrite(stdout, ENTER_ALT + CLEAR_VISIBLE + CURSOR_HOME + (mouse ? enableMouse(motion) : SAVE_ALT_SCROLL_OFF));
+    /**
+     * THE CURRENT capture state, not the one the session started in (I-10).
+     *
+     * `restore()` used to close over the immutable `mouse` boolean. After
+     * `/mouse` exists that boolean is no longer the truth, and the exit path is
+     * the one place where being wrong leaves the user's shell broken until they
+     * run `reset`.
+     */
+    let captured = mouse;
+    /**
+     * Whether OUR `XTSAVE` of DEC 1007 is outstanding.
+     *
+     * `XTSAVE` HAS ONE SLOT PER MODE, so the save and the restore must stay
+     * STRICTLY PAIRED: an `off` that saved while our own disable was already in
+     * effect would save OUR value, and the following restore would hand the user
+     * back a preference that was never theirs — permanently.
+     */
+    let savedAltScroll = mouse ? false : true;
+    const setMouseCapture = (on) => {
+        // A session that never installed a filter has nothing to release, and
+        // enabling reporting without one types `[<0;12;5M` into the user's message
+        // on every click (I-8). It stays a no-op in both directions.
+        if (!mouse || on === captured)
+            return;
+        captured = on;
+        if (on) {
+            // Alternate scroll goes back to the user's own preference BEFORE reporting
+            // resumes, so the two never overlap in the "both disabled" state.
+            safeWrite(stdout, (savedAltScroll ? RESTORE_ALT_SCROLL : '') + enableMouse(motion));
+            savedAltScroll = false;
+            return;
+        }
+        // DEC 1007 IS THE HALF THAT MUST NOT BE DROPPED (P1-1). With reporting off,
+        // alternate scroll turns every wheel notch back into a burst of arrow keys,
+        // which `PromptInput` reads as prompt-history recall — replacing the user's
+        // draft with an old prompt. A `/mouse off` that wrote only the mouse
+        // sequences would hand that defect back on request, in the one command whose
+        // entire purpose is to make things better. Saved rather than force-set, so a
+        // user who deliberately disabled alternate scroll keeps their choice.
+        safeWrite(stdout, disableMouse(motion) + SAVE_ALT_SCROLL_OFF);
+        savedAltScroll = true;
+    };
     let restored = false;
     return {
         restore() {
@@ -74,8 +129,15 @@ export function enterAltScreen(stdout, options = { mouse: false }) {
             // here and not in `App.tsx`, a component that is on none of them.
             // Leaving reporting on prints `[<0;12;5M` in the user's shell on every
             // click, forever, until they run `reset`.
-            safeWrite(stdout, (mouse ? DISABLE_MOUSE : RESTORE_ALT_SCROLL) + SHOW_CURSOR + LEAVE_ALT);
+            //
+            // IT UNWINDS THE CURRENT STATE (I-10): `captured` and `savedAltScroll` are
+            // read here rather than the startup `mouse` flag, so a session that ran
+            // `/mouse off` exits with exactly one outstanding save restored and
+            // nothing left reporting.
+            const tail = (captured ? disableMouse(motion) : '') + (savedAltScroll ? RESTORE_ALT_SCROLL : '');
+            safeWrite(stdout, tail + SHOW_CURSOR + LEAVE_ALT);
         },
+        setMouseCapture,
     };
 }
 /**

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-mouse-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;