@aragon-agent/cli 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -7,6 +7,33 @@ were written.
 
 ## Unreleased
 
+### Added
+
+- **The mouse wheel scrolls what is under the pointer.** In full-screen mode the
+  wheel now scrolls the transcript three rows per notch (a page with `Shift`),
+  scrolls an open overlay when the pointer is over one, and steps prompt history
+  one entry per notch when the pointer is over the input box — the same code
+  path `↑` / `↓` use, so it inherits the rule that an in-progress draft is never
+  overwritten. A slim rail on the viewport's right edge shows where you are in
+  the conversation.
+
+  **This fixes a destructive bug.** Previously the wheel recalled prompt history
+  no matter where the pointer was, because the alternate screen makes terminals
+  translate each notch into arrow keys. Wheeling while composing a message
+  silently replaced the draft with an old prompt, and nothing scrolled.
+
+  **Selecting text with the mouse now requires `Shift`+drag** in most terminals.
+  That is the standard convention for "an application is tracking the mouse" and
+  it applies to everyone, including people who never scroll with the wheel — so
+  the first session says so once, in the transcript, and never again. Turn the
+  whole feature off with `--no-mouse`, `ARAGON_MOUSE=0`, or
+  `aragon config set mouse false`; the wheel then does nothing rather than
+  reverting to the old behaviour. Inline mode (`--no-fullscreen`) is untouched:
+  your terminal's own scrollback already does the right thing there.
+
+  Under `tmux` with `mouse on`, tmux keeps the wheel for itself and the app
+  never sees it. `set -g mouse off` hands it back.
+
 ### Changed
 
 - **Your files moved to `~/.aragon-agent/`.** Config, sessions, installed skills

package/README.md

@@ -123,6 +123,8 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Ctrl+O` | Expand / collapse the most recent tool card |
 | `PgUp` / `PgDn` | Scroll the transcript a page (full-screen mode) |
 | `Shift+↑` / `Shift+↓` | Scroll the transcript a line (full-screen mode) |
+| Mouse wheel | Scroll the transcript (over the input box: prompt history) |
+| `Shift`+wheel | Scroll the transcript a page |
 | `Home` / `End`, `Ctrl+A` / `Ctrl+E` | Cursor to line start / end |
 | `Alt/Ctrl+←` / `→` | Word-wise cursor jump |
 | `Ctrl+W`, `Alt+Backspace` | Delete the previous word |
@@ -132,10 +134,31 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 
 In **full-screen mode** the transcript is scrolled by the app itself: `PgUp` /
 `PgDn` and `Shift+↑` / `Shift+↓`. While pinned to the bottom the viewport follows
-new output automatically; once you scroll away the status bar shows `↑N` and a
-hint counts the lines below you. Submitting a message always re-pins to the
-newest output. In **inline mode** (`--no-fullscreen`) history lives in your
-terminal's native scrollback, printed once via Ink `<Static>`.
+new output automatically; once you scroll away the status bar shows `↑N`, a slim
+rail on the right edge shows where you are, and a hint counts the lines below
+you. Submitting a message always re-pins to the newest output. In **inline mode**
+(`--no-fullscreen`) history lives in your terminal's native scrollback, printed
+once via Ink `<Static>`.
+
+**The mouse wheel scrolls whatever is under the pointer.** Over the transcript
+it scrolls the transcript three rows per notch (a page with `Shift`); over an
+open overlay it scrolls that overlay; over the input box at the bottom it steps
+prompt history one entry per notch, exactly as `↑` / `↓` do — including the rule
+that an in-progress draft is never overwritten.
+
+Two things follow from the app owning the mouse, and they are worth knowing
+before you meet them:
+
+- **Selecting text now needs `Shift`+drag** in most terminals. That is the
+  terminal's convention for "an application is tracking the mouse", not
+  something this CLI can opt out of while still reading wheel events.
+- **`tmux` with `mouse on` keeps the wheel for itself**, so the app never sees
+  it. `set -g mouse off` hands it back.
+
+Turn the whole thing off with `--no-mouse`, `ARAGON_MOUSE=0`, or
+`aragon config set mouse false`. With mouse support off the wheel simply does
+nothing in full-screen mode — it does not fall back to editing your draft, which
+is what it used to do. Inline mode is unaffected either way.
 
 ## Themes
 

package/dist/cli.js

@@ -32,6 +32,7 @@ import { runSkillsCommand } from './skills/cli-commands.js';
 import { runHeadless } from './agent/headless.js';
 import { App } from './ui/App.js';
 import { decideRenderMode } from './ui/layout/frame.js';
+import { tryCreateMouseFilter } from './input/stdin-mouse-filter.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
 import { readExitSnapshot } from './ui/exit-snapshot.js';
 import { renderTranscriptText } from './ui/transcript-text.js';
@@ -70,6 +71,9 @@ function toFlags(opts) {
         exitTranscript: opts.exitTranscript,
         compact: opts.compact,
         hints: opts.hints,
+        // Without this line the flag never reaches `CliFlags` and `--no-mouse` is
+        // inert — a failure with no compile error and no runtime error (P1-2).
+        mouse: opts.mouse,
         skills: opts.skills,
         skill: opts.skill,
         skillsYes: opts.skillsYes,
@@ -164,6 +168,31 @@ function runInteractive(flags, extras = {}) {
     attachAgentEvents(logger, controller);
     let screen = null;
     let replayed = false;
+    // --- Mouse wheel region routing (mouse-wheel-region-routing §4.2). -------
+    //
+    // BUILD THE FILTER FIRST, THEN ENABLE REPORTING. The order is invariant I-8
+    // and it is not negotiable: `\x1b[?1000h` tells the terminal to send SGR
+    // reports, and Ink 5.2.1 has no mouse branch at all, so any report that
+    // reaches its key parser is INSERTED INTO THE USER'S MESSAGE (`[` is 0x5B, so
+    // `PromptInput`'s `isControlSeq` guard passes it). A window in which
+    // reporting is on and Ink holds the raw stream is not a degraded feature — it
+    // is every click typing `[<0;12;5M` into the composer, strictly worse than
+    // the bug being fixed.
+    //
+    // `tryCreateMouseFilter` returns `null` rather than throwing, so a
+    // construction failure degrades to "the wheel is inert" (rung 3 of the
+    // fail-safe ladder), never to "reporting on, no filter".
+    // BOTH streams have to be terminals. `stdout.isTTY` is what decides whether
+    // `enterAltScreen` writes anything at all, but the reports come back on
+    // STDIN, so a TTY stdout with a piped stdin (`aragon config < file`, which
+    // reaches `runInteractive` without the stdin check the default action makes)
+    // would wrap a stream no report can ever arrive on and ask the terminal to
+    // start reporting anyway. §4.2's "non-TTY ⇒ no filter" covers both ends.
+    const wantMouse = mode === 'fullscreen' && config.mouse && !!process.stdout.isTTY && !!process.stdin.isTTY;
+    const mouseFilter = wantMouse
+        ? tryCreateMouseFilter(process.stdin, (reason) => logger.warn('cli', 'mouse_filter_failed', { reason }))
+        : null;
+    const disposeMouse = () => mouseFilter?.dispose();
     const replayTranscript = () => {
         if (replayed || mode !== 'fullscreen' || !config.exitTranscript)
             return;
@@ -181,7 +210,10 @@ function runInteractive(flags, extras = {}) {
         }));
     };
     if (mode === 'fullscreen') {
-        screen = enterAltScreen(process.stdout);
+        // `mouse` here means "a filter is installed", NOT "the user wants mouse
+        // support" — see `AltScreenOptions`. `screen.ts` must never derive it for
+        // itself, or a later refactor re-opens the gap I-8 closes.
+        screen = enterAltScreen(process.stdout, { mouse: mouseFilter !== null });
         const restore = () => screen?.restore();
         // Four idempotent restore paths (§4.4). The signal hook is NOT redundant:
         //   - `waitUntilExit().then()` is a microtask and may never be reached when
@@ -205,20 +237,38 @@ function runInteractive(flags, extras = {}) {
             process.exit(128 + signo);
         });
     }
-    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay }), 
+    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source }), 
     // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
     // straight to stdout and permanently shifts the fixed frame's accounting.
-    { exitOnCtrlC: false, patchConsole: mode === 'inline' });
+    {
+        exitOnCtrlC: false,
+        patchConsole: mode === 'inline',
+        // I-5: with mouse support off the REAL stdin is handed over unwrapped, so
+        // every existing path is provably unchanged.
+        stdin: mouseFilter?.stdin ?? process.stdin,
+    });
     // The return value MUST be captured — `waitUntilExit()` is the normal-exit
-    // restore path and it cannot be registered otherwise.
+    // restore path and it cannot be registered otherwise. `dispose()` runs on
+    // BOTH branches (I-7): a live `'data'` listener on stdin keeps the event loop
+    // alive and `aragon` would never return to the shell. The signal path does
+    // not need it — it calls `process.exit()`.
+    //
+    // RESTORE BEFORE DISPOSE. `restore()` writes `?1000l`, so the terminal stops
+    // reporting first and anything already in flight is still consumed by a live
+    // filter. Disposing first leaves a window — narrow, but real — in which the
+    // terminal is still reporting and nothing is draining stdin, so a notch taken
+    // in that instant survives in the OS buffer and is handed to the shell as
+    // `[<64;12;5M` on exit. That is the I-2 failure mode, just smaller.
     void instance
         .waitUntilExit()
         .then(() => {
         screen?.restore();
+        disposeMouse();
         replayTranscript();
     })
         .catch(() => {
         screen?.restore();
+        disposeMouse();
     });
 }
 async function runOneShot(flags, prompt, quiet) {
@@ -299,6 +349,11 @@ const CONFIG_SET_KEYS = new Set([
     // flags and never persist -- inconsistent with every other config field.
     'density',
     'hints',
+    // MEMBERSHIP HERE ONLY DECIDES THAT THE KEY IS NOT REJECTED. The `switch`
+    // below is what builds the patch, and a key present here but absent there
+    // falls through every case, writes nothing, and still prints
+    // `Set mouse = false` (P1-2) -- exactly what happened to `density`/`hints`.
+    'mouse',
     'planModeDefault',
     'planModeMaxAskRounds',
     'planModeHumanTimeoutMs',
@@ -371,6 +426,9 @@ function runConfigSet(key, value) {
         case 'hints':
             patch.hints = value === 'true' || value === '1';
             break;
+        case 'mouse':
+            patch.mouse = value === 'true' || value === '1';
+            break;
         // Clamped rather than rejected, for the same reason as `theme` and
         // `skills.integrity`: hardening only the READ path leaves a bad value on
         // disk that reverts to the default on every launch, which presents as
@@ -452,6 +510,9 @@ function buildProgram() {
         .option('--no-compact', 'Comfortable transcript density')
         .option('--hints', 'Always show the composer hint row')
         .option('--no-hints', 'Hide the composer hint row')
+        // Positive form first, same tri-state reason as `--fullscreen` above.
+        .option('--mouse', 'Wheel scrolls the region under the pointer (full-screen mode)')
+        .option('--no-mouse', 'Leave the mouse to the terminal (the wheel does nothing)')
         // Declaring `--fullscreen` BEFORE `--no-fullscreen` keeps the default
         // `undefined` instead of `true`, which is what makes the tri-state work:
         // "no opinion" must stay distinguishable from "force it".

package/dist/config/env.d.ts

@@ -5,8 +5,8 @@
  *   - Provider secrets: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY /
  *     GEMINI_API_KEY.
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
- *     ARAGON_MAX_TOKENS, ARAGON_THEME, ARAGON_PLAN, ARAGON_LOG_LEVEL,
- *     ARAGON_LOG_FILE, ARAGON_LOG_DIR.
+ *     ARAGON_MAX_TOKENS, ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN,
+ *     ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never

package/dist/config/env.js

@@ -5,8 +5,8 @@
  *   - Provider secrets: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY /
  *     GEMINI_API_KEY.
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
- *     ARAGON_MAX_TOKENS, ARAGON_THEME, ARAGON_PLAN, ARAGON_LOG_LEVEL,
- *     ARAGON_LOG_FILE, ARAGON_LOG_DIR.
+ *     ARAGON_MAX_TOKENS, ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN,
+ *     ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never
@@ -71,6 +71,14 @@ export function readEnvConfig() {
     if (fullscreen !== undefined && fullscreen.length > 0) {
         partial.fullscreen = fullscreen === '1' || fullscreen === 'true' || fullscreen === 'on' || fullscreen === 'yes';
     }
+    // ARAGON_MOUSE=0 turns off wheel region routing. Parsed by the POSITIVE list
+    // above, exactly as ARAGON_FULLSCREEN is — NOT by `envBool` below, which uses
+    // a negative list. The two disagree on `ARAGON_MOUSE=disable`, and `mouse` is
+    // modelled on `--fullscreen`, so it uses the reader `--fullscreen` uses.
+    const mouse = process.env.ARAGON_MOUSE?.trim().toLowerCase();
+    if (mouse !== undefined && mouse.length > 0) {
+        partial.mouse = mouse === '1' || mouse === 'true' || mouse === 'on' || mouse === 'yes';
+    }
     // ARAGON_PLAN=1 starts the session in PLAN mode — the same channel story as
     // ARAGON_FULLSCREEN, for terminals reached through a wrapper that owns argv.
     const plan = process.env.ARAGON_PLAN?.trim().toLowerCase();

package/dist/config/load.d.ts

@@ -27,6 +27,8 @@ export interface CliFlags {
     compact?: boolean;
     /** `--hints` ⇒ true, `--no-hints` ⇒ false, absent ⇒ undefined. */
     hints?: boolean;
+    /** `--mouse` ⇒ true, `--no-mouse` ⇒ false, absent ⇒ undefined. */
+    mouse?: boolean;
     /** `--no-skills` ⇒ false. Turns the whole skill subsystem off (§7.5). */
     skills?: boolean;
     /** `--skill <name>` ×N — force Level 2 injection for this run. */

package/dist/config/load.js

@@ -33,6 +33,28 @@ function resolveFullscreen(flags, env, file) {
         return false;
     return undefined;
 }
+/**
+ * Resolve wheel region routing: flag › env › file › default `true`.
+ *
+ * THIS NEEDS ITS OWN RESOLVER; it does not "match every other boolean" in this
+ * file. `hints` is `flags.hints !== undefined ? … : file.hints ?? DEFAULT` and
+ * reads NO ENV AT ALL — copying that line would ship `ARAGON_MOUSE` as
+ * documented-but-dead (P1-9). Only `fullscreen` has an env layer, and only
+ * because `resolveFullscreen` above was written to give it one.
+ *
+ * Unlike `fullscreen` this is a plain boolean rather than a tri-state: there
+ * are no heuristics for an explicit `true` to override, so a persisted `true`
+ * is just a value and not an opinion that has to be told apart from silence.
+ */
+function resolveMouse(flags, env, file) {
+    if (flags.mouse !== undefined)
+        return flags.mouse;
+    if (env.mouse !== undefined)
+        return env.mouse;
+    if (file.mouse !== undefined)
+        return file.mouse;
+    return DEFAULT_CONFIG.mouse;
+}
 /**
  * Resolve whether logs reach a file: flag › env › an explicit `false` in the
  * file › default `true`.
@@ -177,6 +199,7 @@ export function loadConfig(flags = {}) {
         promptHistory: file.promptHistory ?? [],
         density,
         hints,
+        mouse: resolveMouse(flags, env.partial, file),
         submitCount: coercePositiveInt(file.submitCount, 0),
         startInPlanMode,
         planModeMaxAskRounds,

package/dist/config/schema.d.ts

@@ -217,6 +217,21 @@ export interface PersistedConfig {
     density: DensityMode;
     /** Show the composer hint row at all. */
     hints: boolean;
+    /**
+     * Enable SGR mouse reporting in full-screen mode so the wheel scrolls the
+     * region under the pointer (mouse-wheel-region-routing §5.7).
+     *
+     * A PLAIN BOOLEAN, not a `fullscreen`-style tri-state: there are no
+     * heuristics for an explicit `true` to override (D-10).
+     */
+    mouse: boolean;
+    /**
+     * Whether the one-time "hold Shift to select text" notice has been shown
+     * (§6.1). Bookkeeping for a one-shot notice, NOT a preference — hence no
+     * flag, no env var and no `config set` key. Giving it a user-facing channel
+     * would invite it to be treated as one.
+     */
+    mouseNoticeSeen: boolean;
     /** Lifetime submit count driving the progressive-disclosure fade (§4.6). */
     submitCount: number;
     /** Start every session in PLAN mode (plan-mode §4.4). */
@@ -263,6 +278,11 @@ export interface CliConfig {
     promptHistory: string[];
     density: DensityMode;
     hints: boolean;
+    /**
+     * Whether this session may enable SGR mouse reporting (full-screen + TTY
+     * only). Resolved by `resolveMouse` in `load.ts`.
+     */
+    mouse: boolean;
     submitCount: number;
     /**
      * Whether this session opens in PLAN mode.

package/dist/config/schema.js

@@ -280,6 +280,8 @@ export const DEFAULT_CONFIG = {
     promptHistory: [],
     density: 'comfortable',
     hints: true,
+    mouse: true,
+    mouseNoticeSeen: false,
     submitCount: 0,
     planModeDefault: false,
     planModeMaxAskRounds: DEFAULT_PLAN_MAX_ASK_ROUNDS,

package/dist/input/mouse-events.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Mouse-report parser (mouse-wheel-region-routing §5.1) — pure, stream-free.
+ *
+ * The alternate screen has no native scrollback, so every modern terminal turns
+ * on DEC private mode 1007 (*alternate scroll*) and translates each wheel notch
+ * into a burst of arrow keys. Arrow keys carry NO POINTER POSITION, which is
+ * why region routing is impossible from that channel and why the CLI asks for
+ * real SGR mouse reporting instead (`\x1b[?1000h\x1b[?1006h`).
+ *
+ * Asking for it is only half the job. Ink 5.2.1 has no mouse branch at all:
+ * `parse-keypress.js` fails to match `\x1b[<64;40;12M`, `use-input.js` strips
+ * the leading ESC, and `PromptInput`'s `isControlSeq` guard passes the
+ * remainder (`[` is 0x5B, >= 0x20) straight into `insert()`. So an unfiltered
+ * mouse report is not ignored — it is TYPED INTO THE USER'S MESSAGE. This
+ * module exists so `stdin-mouse-filter.ts` can remove every byte of every
+ * report before Ink ever sees the chunk (invariant I-1).
+ *
+ * Non-wheel reports (press / release / drag) are recognized and DISCARDED
+ * rather than passed through, for the same reason.
+ */
+export interface WheelEvent {
+    readonly kind: 'wheel';
+    readonly dir: 'up' | 'down';
+    /** 1-based terminal column, as reported. */
+    readonly x: number;
+    /** 1-based terminal row, as reported. */
+    readonly y: number;
+    readonly shift: boolean;
+    readonly alt: boolean;
+    readonly ctrl: boolean;
+}
+export interface MouseSplit {
+    /** Wheel events, in arrival order. Non-wheel reports are dropped, not returned. */
+    readonly events: WheelEvent[];
+    /** Everything that was not a mouse report — forward this to Ink verbatim. */
+    readonly text: string;
+    /** Trailing strict prefix of a possible report; feed it back in with the next chunk. */
+    readonly pending: string;
+}
+/**
+ * Ceiling on the held-back tail. A malformed sequence that looks like a prefix
+ * forever must never be able to wedge input: past this length the tail is
+ * flushed as ordinary text and parsing resumes from the next byte.
+ */
+export declare const MAX_PENDING_MOUSE_CHARS = 32;
+/**
+ * True when `s` is a PROPER prefix of a possible mouse report (never a full
+ * one). Nothing a keyboard produces matches beyond `\x1b` and `\x1b[`, which is
+ * why the filter's flush timer is a rare path rather than a latency tax on
+ * typing: ordinary text and pasted blocks contain no `\x1b[<`.
+ */
+export declare function isMousePrefix(s: string): boolean;
+/**
+ * Split a decoded stdin chunk into wheel events, passthrough text, and a
+ * trailing prefix to carry into the next chunk.
+ *
+ * The caller is expected to feed `pending + nextChunk` back in; ConPTY does
+ * split writes mid-sequence, and a report torn across two chunks would
+ * otherwise leak its tail into the composer (R-6).
+ */
+export declare function splitMouseEvents(buffer: string): MouseSplit;

package/dist/input/mouse-events.js

@@ -0,0 +1,153 @@
+/**
+ * Mouse-report parser (mouse-wheel-region-routing §5.1) — pure, stream-free.
+ *
+ * The alternate screen has no native scrollback, so every modern terminal turns
+ * on DEC private mode 1007 (*alternate scroll*) and translates each wheel notch
+ * into a burst of arrow keys. Arrow keys carry NO POINTER POSITION, which is
+ * why region routing is impossible from that channel and why the CLI asks for
+ * real SGR mouse reporting instead (`\x1b[?1000h\x1b[?1006h`).
+ *
+ * Asking for it is only half the job. Ink 5.2.1 has no mouse branch at all:
+ * `parse-keypress.js` fails to match `\x1b[<64;40;12M`, `use-input.js` strips
+ * the leading ESC, and `PromptInput`'s `isControlSeq` guard passes the
+ * remainder (`[` is 0x5B, >= 0x20) straight into `insert()`. So an unfiltered
+ * mouse report is not ignored — it is TYPED INTO THE USER'S MESSAGE. This
+ * module exists so `stdin-mouse-filter.ts` can remove every byte of every
+ * report before Ink ever sees the chunk (invariant I-1).
+ *
+ * Non-wheel reports (press / release / drag) are recognized and DISCARDED
+ * rather than passed through, for the same reason.
+ */
+/**
+ * Ceiling on the held-back tail. A malformed sequence that looks like a prefix
+ * forever must never be able to wedge input: past this length the tail is
+ * flushed as ordinary text and parsing resumes from the next byte.
+ */
+export const MAX_PENDING_MOUSE_CHARS = 32;
+const ESC = '\x1b';
+/** `\x1b[<b;x;yM` (press) or `…m` (release) — the only form we request. */
+const SGR_REPORT = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/;
+/** A strict prefix of an SGR report: `\x1b[<` plus digits and semicolons. */
+const SGR_PREFIX = /^\x1b\[<[\d;]*$/;
+/**
+ * True when `s` is a PROPER prefix of a possible mouse report (never a full
+ * one). Nothing a keyboard produces matches beyond `\x1b` and `\x1b[`, which is
+ * why the filter's flush timer is a rare path rather than a latency tax on
+ * typing: ordinary text and pasted blocks contain no `\x1b[<`.
+ */
+export function isMousePrefix(s) {
+    return /^\x1B(\[(<[\d;]*|M[\s\S]{0,2})?)?$/.test(s);
+}
+/**
+ * Decode an SGR button byte into a wheel event, or `null` when the report is
+ * not a wheel notch we act on.
+ *
+ * THE ORDER OF THESE TESTS IS THE SPECIFICATION, not a presentation choice.
+ * Button 66 (wheel-left) has `b & 1 === 0` and would decode as `'up'`, so the
+ * horizontal test has to precede the direction decode.
+ */
+function decodeWheel(b, x, y, final) {
+    // 1. Not a wheel report at all (press / release / drag) — consume, emit nothing.
+    if ((b & 64) === 0)
+        return null;
+    // 2. Horizontal wheel (66 = left, 67 = right). Consumed and dropped (non-goal).
+    if ((b & 3) >= 2)
+        return null;
+    // 3. Wheel buttons are press-only; a terminal that ever sent a release for one
+    //    must not produce a second step for the same physical notch.
+    if (final !== 'M')
+        return null;
+    return {
+        kind: 'wheel',
+        dir: (b & 1) === 1 ? 'down' : 'up',
+        x,
+        y,
+        shift: (b & 4) !== 0,
+        alt: (b & 8) !== 0,
+        ctrl: (b & 16) !== 0,
+    };
+}
+/**
+ * X10 legacy reports (`\x1b[M` + three chars, each `code - 32`).
+ *
+ * We never request this encoding — `?1006h` is over a decade old and every
+ * terminal that implements `?1000` implements it — but a terminal that ignored
+ * the SGR request would fall back to it, and a leaked `\x1b[M` + garbage is
+ * exactly the draft corruption I-1 exists to prevent. So it is consumed
+ * unconditionally; the coordinates are only trusted when all three bytes are
+ * plausible, because `setEncoding('utf8')` mangles raw bytes above 0x7F.
+ */
+function matchX10(s) {
+    if (s.length < 6)
+        return { kind: 'partial' };
+    const codes = [s.charCodeAt(3), s.charCodeAt(4), s.charCodeAt(5)];
+    if (codes.some((c) => c < 32 || c > 255))
+        return { kind: 'complete', length: 6, event: null };
+    const [b, x, y] = codes;
+    return { kind: 'complete', length: 6, event: decodeWheel(b - 32, x - 32, y - 32, 'M') };
+}
+/** Classify the escape sequence starting at `s[0] === ESC`. */
+function matchReport(s) {
+    if (s.length === 1)
+        return { kind: 'partial' }; // lone ESC so far
+    if (s[1] !== '[')
+        return { kind: 'none' };
+    if (s.length === 2)
+        return { kind: 'partial' }; // `\x1b[`
+    if (s[2] === '<') {
+        const m = SGR_REPORT.exec(s);
+        if (m) {
+            const b = Number(m[1]);
+            const x = Number(m[2]);
+            const y = Number(m[3]);
+            return { kind: 'complete', length: m[0].length, event: decodeWheel(b, x, y, m[4]) };
+        }
+        return SGR_PREFIX.test(s) ? { kind: 'partial' } : { kind: 'none' };
+    }
+    if (s[2] === 'M')
+        return matchX10(s);
+    return { kind: 'none' };
+}
+/**
+ * Split a decoded stdin chunk into wheel events, passthrough text, and a
+ * trailing prefix to carry into the next chunk.
+ *
+ * The caller is expected to feed `pending + nextChunk` back in; ConPTY does
+ * split writes mid-sequence, and a report torn across two chunks would
+ * otherwise leak its tail into the composer (R-6).
+ */
+export function splitMouseEvents(buffer) {
+    const events = [];
+    let text = '';
+    let i = 0;
+    while (i < buffer.length) {
+        const esc = buffer.indexOf(ESC, i);
+        if (esc === -1) {
+            text += buffer.slice(i);
+            return { events, text, pending: '' };
+        }
+        text += buffer.slice(i, esc);
+        const rest = buffer.slice(esc);
+        const m = matchReport(rest);
+        if (m.kind === 'complete') {
+            if (m.event)
+                events.push(m.event);
+            i = esc + m.length;
+            continue;
+        }
+        if (m.kind === 'partial') {
+            // A tail that never resolves must not hold input hostage: past the
+            // ceiling it is ordinary text, and parsing continues after the ESC.
+            if (rest.length > MAX_PENDING_MOUSE_CHARS) {
+                text += rest;
+                return { events, text, pending: '' };
+            }
+            return { events, text, pending: rest };
+        }
+        // Not a mouse report — an arrow key, a paste, anything. Emit the ESC and
+        // resume scanning after it so the rest of the sequence reaches Ink intact.
+        text += ESC;
+        i = esc + 1;
+    }
+    return { events, text, pending: '' };
+}

package/dist/input/stdin-mouse-filter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Stdin mouse filter (mouse-wheel-region-routing §4.2 / §5.2).
+ *
+ * WHY A WRAPPER AND NOT A SECOND LISTENER. Ink 5.2.1 owns stdin in a way that
+ * forbids a second reader: `components/App.js` calls `setEncoding('utf8')`,
+ * `ref()`, `setRawMode(true)`, subscribes to `'readable'` and drains with
+ * `read()`. Attaching our own `'data'` listener to the same `process.stdin`
+ * would switch the stream into flowing mode and RACE Ink's `read()` for chunks
+ * — some keystrokes would reach Ink, some would not, non-deterministically
+ * (D-3). So the filter REPLACES the stream Ink is given: it reads the real
+ * stdin, strips every mouse report, and writes the remainder into a
+ * `PassThrough` that carries the surface Ink requires.
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h`. Reporting enabled while Ink
+ * still holds the raw stream does not degrade the feature — it types
+ * `[<0;12;5M` into the user's message on every click, which is strictly worse
+ * than the bug this feature fixes. `cli.tsx::runInteractive` is the only caller
+ * and passes `filter !== null` to `enterAltScreen`.
+ */
+import { type WheelEvent } from './mouse-events.js';
+export interface MouseSource {
+    /** Returns an unsubscribe function. Multiple subscribers are allowed. */
+    subscribe(listener: (event: WheelEvent) => void): () => void;
+}
+export interface MouseFilter {
+    /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */
+    readonly stdin: NodeJS.ReadStream;
+    readonly source: MouseSource;
+    /** Idempotent. Detaches from the real stdin and clears the flush timer (I-7). */
+    dispose(): void;
+}
+export declare function createMouseFilter(real: NodeJS.ReadStream): MouseFilter;
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): `enterAltScreen` derives whether
+ * to enable mouse reporting from `filter !== null`, so a construction failure
+ * degrades to "the wheel is inert" — a supported, tested rung of the fail-safe
+ * ladder — rather than leaving reporting on with no filter in front of Ink.
+ */
+export declare function tryCreateMouseFilter(real: NodeJS.ReadStream, onError?: (reason: string) => void): MouseFilter | null;