@aragon-agent/cli 0.6.2 → 0.6.4

package/dist/ui/paste-frames.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Reading paste frames back out of an Ink `input` string
+ * (tui-paste-handling section 5.4) -- pure.
+ *
+ * The stdin filter writes `PASTE_OPEN + payload + PASTE_CLOSE` inline, in stream
+ * order (I-5). This module is the only place that takes those markers apart.
+ */
+export interface FrameTextSegment {
+    readonly kind: 'text';
+    readonly text: string;
+}
+export interface FramePasteSegment {
+    readonly kind: 'paste';
+    readonly text: string;
+}
+/**
+ * A run of one `input` string.
+ *
+ * NO `id` HERE. The paste id is allocated by `PromptInput` while it builds the
+ * reducer's action, never by this function and never by the reducer (P1-5), so
+ * the split stays a pure function of its argument and `paste-frames.test.ts` can
+ * assert on its output.
+ */
+export type FrameSegment = FrameTextSegment | FramePasteSegment;
+/**
+ * Remove every C0 byte, DEL and C1 byte from text that arrived OUTSIDE a frame
+ * (I-14). NO CR -> LF conversion, and that omission is the point.
+ *
+ * WHY THIS IS NOT OPTIONAL. Ink drains its whole buffer in one size-less
+ * `read()` (`App.js:135`), so the `input` string carrying a frame can also carry
+ * the keystroke bytes that arrived beside it -- most often the `\r` of a user who
+ * pastes and immediately presses Enter, since Ink's 32 ms render throttle and a
+ * large transcript's Yoga pass both outlast the filter's 15 ms burst window.
+ * Splicing that run in verbatim puts a raw CR back into the draft and re-opens
+ * the corruption this whole feature exists to remove.
+ *
+ * Note what it does NOT do. It does not turn a coalesced `\r` into a newline and
+ * it does not submit: a keystroke that merged with a frame has already lost its
+ * identity as a key (`parseKeypress` saw the concatenation, not the key), so the
+ * only two honest options are "insert something wrong" and "drop it". Dropping is
+ * recoverable and benign -- the user presses Enter again -- while inserting a
+ * control byte is not. Printable characters survive untouched.
+ */
+export declare function sanitiseTyped(text: string): string;
+/**
+ * Split an `input` string into ordered text runs and paste runs.
+ *
+ * Text runs are returned already through `sanitiseTyped` (I-14); paste runs are
+ * returned through `sanitisePaste`, which keeps TAB and `\n` because they are
+ * content inside a payload.
+ *
+ * RE-SANITISING THE PAYLOAD IS DEFENCE IN DEPTH, NOT A SECOND OPINION. The
+ * filter already ran `sanitisePaste` and it is idempotent, so the normal path is
+ * byte-identical. What it buys is that G2 ("no pasted byte is ever executed as a
+ * terminal control") becomes a property of the COMPOSER rather than a property
+ * of whoever produced the frame -- which matters for the branch below, where an
+ * unmatched `PASTE_OPEN` turns arbitrary trailing bytes into a paste segment.
+ *
+ * An unmatched `PASTE_OPEN` -- impossible from our own filter, but cheap to
+ * survive -- yields its remainder as a paste segment rather than leaking NULs.
+ */
+export declare function splitPasteFrames(input: string): FrameSegment[];
+/** True when this `input` carries at least one frame -- the branch guard. */
+export declare function hasPasteFrame(input: string): boolean;
+/**
+ * Turn a possibly-framed `input` into plain text for a consumer that has no
+ * paste model of its own: unwrap the frames, keep the payload, drop the markers,
+ * and run BOTH halves through `sanitiseTyped`.
+ *
+ * ANY `useInput` CONSUMER THAT APPENDS `input` TO A STRING MUST CALL THIS (I-12),
+ * and the list is pinned by a source scan rather than by review discipline
+ * because the failure is invisible: NUL renders as nothing.
+ *
+ * `useInput` is a BROADCAST -- `use-input.js` re-emits every chunk to every
+ * mounted handler -- so `SettingsScreen` and `QuestionOverlay` see the frame the
+ * composer was sent. An API key is ~100 characters with no line break, which trips
+ * Tier 2's burst rule and gets framed; nothing downstream removes the NULs
+ * (`String.prototype.trim()` does not treat U+0000 as whitespace), the field is
+ * rendered through `maskDot` so the damage is invisible, and the value is handed
+ * to `registerSecret()` and `controller.setApiKey()`. The user is told the
+ * settings were saved and every request afterwards fails to authenticate with
+ * nothing on screen to explain it.
+ *
+ * This is strictly better than v0.6.3 for both consumers: a pasted key carrying a
+ * stray CR or an ANSI sequence is now cleaned rather than stored raw.
+ */
+export declare function stripPasteFrames(input: string): string;

package/dist/ui/paste-frames.js

@@ -0,0 +1,112 @@
+/**
+ * Reading paste frames back out of an Ink `input` string
+ * (tui-paste-handling section 5.4) -- pure.
+ *
+ * The stdin filter writes `PASTE_OPEN + payload + PASTE_CLOSE` inline, in stream
+ * order (I-5). This module is the only place that takes those markers apart.
+ */
+import { PASTE_CLOSE, PASTE_OPEN } from '../input/limits.js';
+import { sanitisePaste } from '../input/paste-parse.js';
+/**
+ * Remove every C0 byte, DEL and C1 byte from text that arrived OUTSIDE a frame
+ * (I-14). NO CR -> LF conversion, and that omission is the point.
+ *
+ * WHY THIS IS NOT OPTIONAL. Ink drains its whole buffer in one size-less
+ * `read()` (`App.js:135`), so the `input` string carrying a frame can also carry
+ * the keystroke bytes that arrived beside it -- most often the `\r` of a user who
+ * pastes and immediately presses Enter, since Ink's 32 ms render throttle and a
+ * large transcript's Yoga pass both outlast the filter's 15 ms burst window.
+ * Splicing that run in verbatim puts a raw CR back into the draft and re-opens
+ * the corruption this whole feature exists to remove.
+ *
+ * Note what it does NOT do. It does not turn a coalesced `\r` into a newline and
+ * it does not submit: a keystroke that merged with a frame has already lost its
+ * identity as a key (`parseKeypress` saw the concatenation, not the key), so the
+ * only two honest options are "insert something wrong" and "drop it". Dropping is
+ * recoverable and benign -- the user presses Enter again -- while inserting a
+ * control byte is not. Printable characters survive untouched.
+ */
+export function sanitiseTyped(text) {
+    return text.replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
+}
+/**
+ * Split an `input` string into ordered text runs and paste runs.
+ *
+ * Text runs are returned already through `sanitiseTyped` (I-14); paste runs are
+ * returned through `sanitisePaste`, which keeps TAB and `\n` because they are
+ * content inside a payload.
+ *
+ * RE-SANITISING THE PAYLOAD IS DEFENCE IN DEPTH, NOT A SECOND OPINION. The
+ * filter already ran `sanitisePaste` and it is idempotent, so the normal path is
+ * byte-identical. What it buys is that G2 ("no pasted byte is ever executed as a
+ * terminal control") becomes a property of the COMPOSER rather than a property
+ * of whoever produced the frame -- which matters for the branch below, where an
+ * unmatched `PASTE_OPEN` turns arbitrary trailing bytes into a paste segment.
+ *
+ * An unmatched `PASTE_OPEN` -- impossible from our own filter, but cheap to
+ * survive -- yields its remainder as a paste segment rather than leaking NULs.
+ */
+export function splitPasteFrames(input) {
+    const segments = [];
+    const pushText = (raw) => {
+        const text = sanitiseTyped(raw);
+        if (text.length > 0)
+            segments.push({ kind: 'text', text });
+    };
+    const pushPaste = (raw) => {
+        const text = sanitisePaste(raw);
+        if (text.length > 0)
+            segments.push({ kind: 'paste', text });
+    };
+    let i = 0;
+    while (i < input.length) {
+        const open = input.indexOf(PASTE_OPEN, i);
+        if (open === -1) {
+            pushText(input.slice(i));
+            break;
+        }
+        pushText(input.slice(i, open));
+        const bodyStart = open + PASTE_OPEN.length;
+        const close = input.indexOf(PASTE_CLOSE, bodyStart);
+        if (close === -1) {
+            pushPaste(input.slice(bodyStart));
+            break;
+        }
+        pushPaste(input.slice(bodyStart, close));
+        i = close + PASTE_CLOSE.length;
+    }
+    return segments;
+}
+/** True when this `input` carries at least one frame -- the branch guard. */
+export function hasPasteFrame(input) {
+    return input.includes(PASTE_OPEN);
+}
+/**
+ * Turn a possibly-framed `input` into plain text for a consumer that has no
+ * paste model of its own: unwrap the frames, keep the payload, drop the markers,
+ * and run BOTH halves through `sanitiseTyped`.
+ *
+ * ANY `useInput` CONSUMER THAT APPENDS `input` TO A STRING MUST CALL THIS (I-12),
+ * and the list is pinned by a source scan rather than by review discipline
+ * because the failure is invisible: NUL renders as nothing.
+ *
+ * `useInput` is a BROADCAST -- `use-input.js` re-emits every chunk to every
+ * mounted handler -- so `SettingsScreen` and `QuestionOverlay` see the frame the
+ * composer was sent. An API key is ~100 characters with no line break, which trips
+ * Tier 2's burst rule and gets framed; nothing downstream removes the NULs
+ * (`String.prototype.trim()` does not treat U+0000 as whitespace), the field is
+ * rendered through `maskDot` so the damage is invisible, and the value is handed
+ * to `registerSecret()` and `controller.setApiKey()`. The user is told the
+ * settings were saved and every request afterwards fails to authenticate with
+ * nothing on screen to explain it.
+ *
+ * This is strictly better than v0.6.3 for both consumers: a pasted key carrying a
+ * stray CR or an ANSI sequence is now cleaned rather than stored raw.
+ */
+export function stripPasteFrames(input) {
+    if (!hasPasteFrame(input))
+        return sanitiseTyped(input);
+    return splitPasteFrames(input)
+        .map((segment) => (segment.kind === 'paste' ? sanitiseTyped(segment.text) : segment.text))
+        .join('');
+}

package/dist/ui/paste-tokens.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The paste token vocabulary (tui-paste-handling section 5.3) -- pure. No Ink,
+ * no React, no I/O.
+ *
+ * A large paste is replaced IN THE BUFFER by a display token,
+ * `[Pasted text #1 +15 lines]`, and its payload is held beside the buffer in the
+ * editor's `pastes` map until the message is sent (D-7). An inline token rather
+ * than an out-of-band attachment is what lets the user place a paste relative to
+ * their own words -- "explain this: [Pasted text #1 +218 lines] -- why does it
+ * retry?" -- which is also the shape the requirement's example asks for.
+ *
+ * The token is ATOMIC FOR EDITING and NOT for cursor movement (D-8). Delete and
+ * kill ranges snap outward to cover a whole token and the caret snaps out before
+ * an insert, which removes every realistic way to corrupt one; arrows still step
+ * by character, because re-deriving `moveVertical`, `home`/`end` and word jumps
+ * around a synthetic unit buys a correctness the user cannot notice.
+ */
+export interface PasteRecord {
+    readonly id: number;
+    /** The sanitised payload, byte-for-byte what `expandPastes` sends. */
+    readonly text: string;
+    readonly lines: number;
+    readonly chars: number;
+}
+/**
+ * A FACTORY, NOT A SHARED CONSTANT (P2-2).
+ *
+ * A module-level `/g` RegExp carries `lastIndex` between calls, so `re.test(x)`
+ * returns false on every second call with the same input -- a bug that presents
+ * as "token detection works, then randomly does not". Callers must use
+ * `matchAll` or `replace` (both safe) on a FRESH instance; nothing in this module
+ * may call `.test()` or `.exec()` on a `/g` regex it did not just create.
+ *
+ * Strict, anchored to its own literal shape, ASCII-only. Group 1 is the id.
+ */
+export declare function pasteTokenRe(): RegExp;
+export declare function allocatePasteId(): number;
+/** Test-only reset. Never called from application code. */
+export declare function resetPasteIdsForTest(): void;
+export declare function makePasteRecord(id: number, text: string): PasteRecord;
+/**
+ * `[Pasted text #3 +218 lines]`, or `[Pasted text #4 +1204 chars]` for a paste
+ * that is one very long line.
+ *
+ * "+1 lines" is not a sentence, and for a one-liner the number the user cares
+ * about is its length rather than its line count.
+ */
+export declare function formatPasteToken(record: PasteRecord): string;
+/** Above EITHER inline bound the paste is collapsed into a token (G3 / G4). */
+export declare function shouldCollapse(text: string): boolean;
+interface TokenSpan {
+    readonly start: number;
+    readonly end: number;
+    readonly id: number;
+}
+/** Every token in the buffer, in order. */
+export declare function tokenSpans(buffer: string): TokenSpan[];
+/** The token containing or touching `index`, or `null`. */
+export declare function tokenAt(buffer: string, index: number): TokenSpan | null;
+/**
+ * Move a caret that landed STRICTLY INSIDE a token to its nearer edge (D-8).
+ *
+ * An index at either edge, or outside every token, is returned unchanged -- so
+ * this is a no-op on a buffer with no tokens, which is every buffer today.
+ */
+export declare function snapOutOfToken(buffer: string, cursor: number): number;
+/**
+ * Grow `[from, to)` so it covers every token it partially overlaps (G5).
+ *
+ * This is what makes `Backspace` immediately after `...lines]` remove the whole
+ * token in ONE keystroke, and what stops `Ctrl+W` / `Ctrl+U` / `Ctrl+K` leaving
+ * half a token -- and therefore an unparseable label -- behind.
+ */
+export declare function expandRangeOverTokens(buffer: string, from: number, to: number): {
+    from: number;
+    to: number;
+};
+/**
+ * Replace every token whose id is present in `pastes`; leave the rest verbatim.
+ *
+ * A user who literally TYPES `[Pasted text #3 +9 lines]` while paste #3 exists in
+ * the same draft will have it expanded. That is bounded (ids are per process, the
+ * map is per draft) and harmless (they get text that is already in their own
+ * draft), and the alternative -- an unguessable nonce in the label -- would trade
+ * a case nobody hits for a label nobody can read.
+ */
+export declare function expandPastes(buffer: string, pastes: ReadonlyMap<number, PasteRecord>): string;
+/** Ids still referenced by the buffer -- the input to I-7's prune. */
+export declare function referencedIds(buffer: string): Set<number>;
+export {};

package/dist/ui/paste-tokens.js

@@ -0,0 +1,147 @@
+/**
+ * The paste token vocabulary (tui-paste-handling section 5.3) -- pure. No Ink,
+ * no React, no I/O.
+ *
+ * A large paste is replaced IN THE BUFFER by a display token,
+ * `[Pasted text #1 +15 lines]`, and its payload is held beside the buffer in the
+ * editor's `pastes` map until the message is sent (D-7). An inline token rather
+ * than an out-of-band attachment is what lets the user place a paste relative to
+ * their own words -- "explain this: [Pasted text #1 +218 lines] -- why does it
+ * retry?" -- which is also the shape the requirement's example asks for.
+ *
+ * The token is ATOMIC FOR EDITING and NOT for cursor movement (D-8). Delete and
+ * kill ranges snap outward to cover a whole token and the caret snaps out before
+ * an insert, which removes every realistic way to corrupt one; arrows still step
+ * by character, because re-deriving `moveVertical`, `home`/`end` and word jumps
+ * around a synthetic unit buys a correctness the user cannot notice.
+ */
+import { PASTE_INLINE_MAX_CHARS, PASTE_INLINE_MAX_LINES } from './composer-limits.js';
+/**
+ * A FACTORY, NOT A SHARED CONSTANT (P2-2).
+ *
+ * A module-level `/g` RegExp carries `lastIndex` between calls, so `re.test(x)`
+ * returns false on every second call with the same input -- a bug that presents
+ * as "token detection works, then randomly does not". Callers must use
+ * `matchAll` or `replace` (both safe) on a FRESH instance; nothing in this module
+ * may call `.test()` or `.exec()` on a `/g` regex it did not just create.
+ *
+ * Strict, anchored to its own literal shape, ASCII-only. Group 1 is the id.
+ */
+export function pasteTokenRe() {
+    return /\[Pasted text #(\d+) \+\d+ (?:lines|chars)\]/g;
+}
+/**
+ * The process-monotonic id counter (D-14).
+ *
+ * CALLED FROM THE COMPONENT, NEVER FROM THE REDUCER (P1-5). React is explicitly
+ * allowed to run a reducer more than once for one action -- eager evaluation in
+ * `dispatchSetState`, base-queue replay after a bailout, StrictMode double
+ * invocation -- and a counter mutated inside one would skip ids and produce two
+ * states that differ in the token TEXT, not merely in identity. Allocating in the
+ * handler also makes the rendered token deterministic for a unit test.
+ *
+ * Monotonic for the PROCESS rather than per draft, so two drafts never show `#1`
+ * for different content in one session.
+ */
+let nextPasteId = 1;
+export function allocatePasteId() {
+    const id = nextPasteId;
+    nextPasteId += 1;
+    return id;
+}
+/** Test-only reset. Never called from application code. */
+export function resetPasteIdsForTest() {
+    nextPasteId = 1;
+}
+export function makePasteRecord(id, text) {
+    return { id, text, lines: text.split('\n').length, chars: [...text].length };
+}
+/**
+ * `[Pasted text #3 +218 lines]`, or `[Pasted text #4 +1204 chars]` for a paste
+ * that is one very long line.
+ *
+ * "+1 lines" is not a sentence, and for a one-liner the number the user cares
+ * about is its length rather than its line count.
+ */
+export function formatPasteToken(record) {
+    return record.lines > 1
+        ? `[Pasted text #${record.id} +${record.lines} lines]`
+        : `[Pasted text #${record.id} +${record.chars} chars]`;
+}
+/** Above EITHER inline bound the paste is collapsed into a token (G3 / G4). */
+export function shouldCollapse(text) {
+    return text.split('\n').length > PASTE_INLINE_MAX_LINES || [...text].length > PASTE_INLINE_MAX_CHARS;
+}
+/** Every token in the buffer, in order. */
+export function tokenSpans(buffer) {
+    const spans = [];
+    for (const m of buffer.matchAll(pasteTokenRe())) {
+        const start = m.index ?? 0;
+        spans.push({ start, end: start + m[0].length, id: Number(m[1]) });
+    }
+    return spans;
+}
+/** The token containing or touching `index`, or `null`. */
+export function tokenAt(buffer, index) {
+    for (const span of tokenSpans(buffer)) {
+        if (index >= span.start && index <= span.end)
+            return span;
+    }
+    return null;
+}
+/**
+ * Move a caret that landed STRICTLY INSIDE a token to its nearer edge (D-8).
+ *
+ * An index at either edge, or outside every token, is returned unchanged -- so
+ * this is a no-op on a buffer with no tokens, which is every buffer today.
+ */
+export function snapOutOfToken(buffer, cursor) {
+    for (const span of tokenSpans(buffer)) {
+        if (cursor <= span.start || cursor >= span.end)
+            continue;
+        return cursor - span.start <= span.end - cursor ? span.start : span.end;
+    }
+    return cursor;
+}
+/**
+ * Grow `[from, to)` so it covers every token it partially overlaps (G5).
+ *
+ * This is what makes `Backspace` immediately after `...lines]` remove the whole
+ * token in ONE keystroke, and what stops `Ctrl+W` / `Ctrl+U` / `Ctrl+K` leaving
+ * half a token -- and therefore an unparseable label -- behind.
+ */
+export function expandRangeOverTokens(buffer, from, to) {
+    let lo = Math.min(from, to);
+    let hi = Math.max(from, to);
+    for (const span of tokenSpans(buffer)) {
+        if (span.start < hi && lo < span.end) {
+            lo = Math.min(lo, span.start);
+            hi = Math.max(hi, span.end);
+        }
+    }
+    return { from: lo, to: hi };
+}
+/**
+ * Replace every token whose id is present in `pastes`; leave the rest verbatim.
+ *
+ * A user who literally TYPES `[Pasted text #3 +9 lines]` while paste #3 exists in
+ * the same draft will have it expanded. That is bounded (ids are per process, the
+ * map is per draft) and harmless (they get text that is already in their own
+ * draft), and the alternative -- an unguessable nonce in the label -- would trade
+ * a case nobody hits for a label nobody can read.
+ */
+export function expandPastes(buffer, pastes) {
+    if (pastes.size === 0)
+        return buffer;
+    return buffer.replace(pasteTokenRe(), (match, idText) => {
+        const record = pastes.get(Number(idText));
+        return record ? record.text : match;
+    });
+}
+/** Ids still referenced by the buffer -- the input to I-7's prune. */
+export function referencedIds(buffer) {
+    const ids = new Set();
+    for (const m of buffer.matchAll(pasteTokenRe()))
+        ids.add(Number(m[1]));
+    return ids;
+}

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,34 @@ 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;
+    /**
+     * TRUE MEANS "A FILTER THAT CONSUMES `\x1b[200~` IS ALREADY INSTALLED", NOT
+     * "the user wants paste support" — the same discipline `mouse` carries (I-1 /
+     * I-8).
+     *
+     * Enabling DEC 2004 without a filter in front of Ink does not degrade the
+     * feature: it types `[200~` and `[201~` into the user's message on EVERY paste,
+     * which is strictly worse than the bug being fixed. `cli.tsx` passes
+     * `pasteOn && mode === 'fullscreen'`, and NOT `filter !== null && config.paste`
+     * — after the gate widened, the handle no longer answers any question except
+     * "is a stream wrapped?" (D-17 / I-11).
+     *
+     * Optional, defaulting to `false`, so every pre-existing caller and every
+     * pre-existing assertion emits exactly the bytes it emitted before.
+     */
+    readonly bracketedPaste?: 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,33 @@ 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() { } };
+/**
+ * Bracketed paste (DEC private mode 2004) — the terminal wraps a paste in
+ * `\x1b[200~` / `\x1b[201~`, which makes Tier 1 detection EXACT rather than a
+ * heuristic on chunk shape (tui-paste-handling D-6 / L2).
+ *
+ * WHY THIS IS FORCED OFF ON EXIT RATHER THAN SAVED AND RESTORED (P1-8). DEC 1007
+ * above is the same class of state — global, not ours — and gets the OPPOSITE
+ * treatment, so the asymmetry has to be written down or the next reader will
+ * "fix" the inconsistency:
+ *
+ *  - `\x1b[?2004r` on a terminal that does not implement XTSAVE is a NO-OP, which
+ *    leaves 2004 ON. A shell that does not itself speak bracketed paste then
+ *    shows a literal `[200~` on every paste until the user runs `reset` — the
+ *    exact I-1 failure, arriving from the restore path.
+ *  - Forcing `?2004l` has no such failure mode. Every shell that DOES use
+ *    bracketed paste (bash >= 4.4 readline, zsh ZLE, fish, PSReadLine) re-arms it
+ *    when it draws its next prompt, so the state the user sees after `aragon`
+ *    exits is the state they had. Every shell that does not use it was already
+ *    off.
+ *
+ * So: 1007 is saved because getting it wrong silently changes a preference; 2004
+ * is forced because getting it wrong visibly breaks pasting, and the forced value
+ * is the one every consumer re-establishes for itself.
+ */
+const ENABLE_BRACKETED_PASTE = '\x1b[?2004h';
+const DISABLE_BRACKETED_PASTE = '\x1b[?2004l';
+const NOOP_HANDLE = { restore() { }, setMouseCapture() { } };
 function safeWrite(stdout, data) {
     try {
         stdout.write(data);
@@ -60,7 +98,61 @@ 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;
+    const bracketedPaste = options.bracketedPaste === true;
+    safeWrite(stdout, ENTER_ALT +
+        CLEAR_VISIBLE +
+        CURSOR_HOME +
+        (mouse ? enableMouse(motion) : SAVE_ALT_SCROLL_OFF) +
+        (bracketedPaste ? ENABLE_BRACKETED_PASTE : ''));
+    /**
+     * 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) => {
+        // IT MUST NOT TOUCH DEC 2004 (I-16 / P2-7). `/mouse off` releases the
+        // pointer; it says nothing about pasting, and a user who turns the mouse off
+        // mid-session to select text with their terminal must not silently lose Tier
+        // 1 detection as well. The two modes are written by different call sites and
+        // unwound by different flags in `restore()`.
+        //
+        // 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 +166,21 @@ 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.
+            //
+            // DEC 2004 IS UNWOUND FROM THE STARTUP FLAG, not from a runtime one, and
+            // that is deliberate: `setMouseCapture` never touches it (I-16), so this
+            // session either enabled it at entry or never did.
+            const tail = (captured ? disableMouse(motion) : '') +
+                (bracketedPaste ? DISABLE_BRACKETED_PASTE : '') +
+                (savedAltScroll ? RESTORE_ALT_SCROLL : '');
+            safeWrite(stdout, tail + SHOW_CURSOR + LEAVE_ALT);
         },
+        setMouseCapture,
     };
 }
 /**