@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/input/mouse-events.js

@@ -0,0 +1,212 @@
+/**
+ * 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).
+ *
+ * Every mouse report is CONSUMED here whatever it turns out to be; what changed
+ * with tui-selection-and-scroll-follow is that press / drag / release are now
+ * EMITTED as well as consumed, so `SelectionController` can build a selection
+ * out of them (§4.4.2). They were previously recognized and thrown away.
+ */
+/**
+ * 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);
+}
+function modifiers(b) {
+    return { shift: (b & 4) !== 0, alt: (b & 8) !== 0, ctrl: (b & 16) !== 0 };
+}
+/**
+ * Decode one report, or `null` when it is a report we consume without acting 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; and `b & 32` (motion) has
+ * to precede the `final` test, because a drag is reported with `M` exactly as a
+ * press is.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * I-11 — BUTTON EVENTS COME FROM THE SGR PATH ONLY. X10 stays wheel-only, which
+ * is exactly the contract it has today.
+ *
+ * `matchX10` reconstructs a legacy report and hard-codes `final = 'M'`, because
+ * X10 HAS NO SEPARATE RELEASE FORM AT ALL — it encodes a release as button 3 of
+ * a press. Fed through the table below, an X10 release would become a `press`
+ * that is never followed by a `release`, whose `button` is 3 while the type says
+ * `0 | 1 | 2`, and whose consequence is a `hold` that is set and never cleared:
+ * content anchoring never lets go, the resume timer's third condition never
+ * passes, and the transcript is frozen for the rest of the session with nothing
+ * raised anywhere.
+ *
+ * This costs nothing real (D-16): we never REQUEST X10 — `?1006h` is over a
+ * decade old and every terminal that implements `?1000` implements it — and a
+ * terminal that ignored the SGR request also has no usable drag coordinates past
+ * column 223 (R-2). X10 exists in this parser only so a stray report cannot
+ * reach the user's draft.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+function decodeReport(b, x, y, final, encoding) {
+    // 1. Wheel. Buttons 64-67 in both encodings.
+    if ((b & 64) !== 0) {
+        // Horizontal wheel (66 = left, 67 = right). Consumed and dropped (non-goal).
+        if ((b & 3) >= 2)
+            return null;
+        // 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, ...modifiers(b) };
+    }
+    if (encoding !== 'sgr')
+        return null; // I-11
+    // 2. Motion while a button is held (`?1002h`). `3` is "no button", which
+    //    `?1002` should never send and `?1003` sends constantly — dropping it is
+    //    what keeps an any-event terminal from painting a selection with no button
+    //    down at all.
+    if ((b & 32) !== 0) {
+        const button = b & 3;
+        if (button === 3)
+            return null;
+        return { kind: 'drag', button: button, x, y, ...modifiers(b) };
+    }
+    // 3. Release. In SGR the final byte carries the transition, so this is
+    //    unambiguous — unlike X10, which is why step 1's guard exists.
+    //
+    //    A release whose button field reads `3` is a terminal saying "some button
+    //    came up" without naming it. It is mapped to button 0 rather than dropped:
+    //    the ONE thing a release must always do is let go of `hold`, and dropping
+    //    it would leave the viewport frozen — the exact failure I-11 is about. A
+    //    spurious button-0 release is harmless, because a selection can only exist
+    //    if button 0 was pressed in the first place.
+    if (final === 'm') {
+        const button = b & 3;
+        return { kind: 'release', button: (button === 3 ? 0 : button), x, y, ...modifiers(b) };
+    }
+    // 4. Press.
+    const button = b & 3;
+    if (button === 3)
+        return null;
+    return { kind: 'press', button: button, x, y, ...modifiers(b) };
+}
+/**
+ * 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,
+        // `'x10'` is what makes I-11 a property of the code rather than of somebody's
+        // memory: this encoding yields wheel events or nothing, ever.
+        event: decodeReport(b - 32, x - 32, y - 32, 'M', 'x10'),
+    };
+}
+/** 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: decodeReport(b, x, y, m[4], 'sgr') };
+        }
+        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 mouse 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).
+ *
+ * ONE CHANNEL, NOT TWO (§4.4.2). Widening this list to carry buttons alongside
+ * wheel notches is what keeps ARRIVAL ORDER intact between them; a second
+ * channel would let a press overtake the notch that preceded it, and the
+ * selection would then be anchored against rows that had already scrolled.
+ */
+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/paste-parse.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Paste recognition primitives (tui-paste-handling section 5.1) -- pure,
+ * stream-free, no timers.
+ *
+ * WHY THIS LIVES BELOW INK. `ink/build/components/App.js:131-138` reads stdin on
+ * `'readable'` and emits each chunk as one `'input'` event;
+ * `parse-keypress.js:145-148` maps the exact string `'\r'` to `name: 'return'`,
+ * which `PromptInput` reads as "send the message". A 15-line paste on a Windows
+ * console routinely arrives as a dozen chunks that are exactly `"\r"`, and each
+ * one SUBMITS THE DRAFT AS IT STOOD. No component-level heuristic can undo a
+ * `key.return` that has already fired, so recognition has to happen on the byte
+ * stream, in front of Ink -- the same lesson `mouse-events.ts` records.
+ *
+ * Two tiers feed one framing (D-4). Tier 1 is bracketed paste and is exact;
+ * Tier 2 is a heuristic on chunk SHAPE for the terminals that ignore
+ * `DECSET 2004`. Both are about what a keyboard can physically emit.
+ */
+/** `DECSET 2004` wraps a paste in these two markers. */
+export declare const PASTE_BEGIN_MARK = "\u001B[200~";
+export declare const PASTE_END_MARK = "\u001B[201~";
+/** The longest tail worth holding back while a marker might still complete. */
+export declare const PASTE_MARK_LENGTH: number;
+/**
+ * True when `s` is a PROPER prefix of either paste marker (never a whole one).
+ *
+ * Both markers are held, in every mode, whether or not THIS process enabled DEC
+ * 2004 (I-16): the user's shell, `tmux` or a wrapper script may have left it on,
+ * and an unconsumed marker is a literal `[200~` typed into the draft -- the
+ * exact failure the feature exists to prevent.
+ */
+export declare function isPastePrefix(s: string): boolean;
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a paste
+ * marker, or 0. Shortest match wins, so only the bytes that could still become a
+ * marker are held back.
+ */
+export declare function trailingPastePrefixLength(text: string): number;
+/**
+ * Tier 2: is this chunk a paste, or keystrokes?
+ *
+ * The PRIMARY rule -- "longer than one character AND contains a line break" --
+ * is exactly the shape defect A needs, so the two coincide: any chunk that could
+ * submit the draft by accident is classified as a paste. A lone `\r` is the
+ * Enter key and stays `'keys'`.
+ *
+ * The SECONDARY rule needs `PASTE_MIN_BURST_CHARS` printable characters in one
+ * chunk. It excludes chunks carrying any C0 byte but TAB, which is what keeps an
+ * arrow-key burst (`\x1b[B\x1b[B...`, and every wheel notch translated by
+ * alternate scroll) out of the paste path.
+ */
+export declare function classifyChunk(text: string, minBurstChars?: number): 'paste' | 'keys';
+/**
+ * Make a payload safe to put in a buffer and draw through `<Text>` (G2).
+ *
+ * 1. CRLF and lone CR both become exactly ONE `\n` -- terminals send CR for a
+ *    newline in pasted text, and a lone LF is dropped by Ink's key parser
+ *    entirely, so both have to be normalised here or a pasted line break either
+ *    submits the message or silently vanishes.
+ * 2. Every escape SEQUENCE is removed AS A SEQUENCE (`stripControlSequences`).
+ *    Deleting only the introducer byte is what produced the reported defect:
+ *    `ESC [ 3 8 ; 2 ; 1 8 ; 5 2 ; 8 6 m` minus its ESC is `[38;2;18;52;86m`,
+ *    a run of digits Ink then writes to the terminal as ordinary text -- and it
+ *    reached the model, the prompt history and the session file too, because
+ *    this function is the only cleaning the payload ever gets.
+ * 3. Every remaining C0 byte except `\n` and `\t` is removed. Ink writes
+ *    `<Text>` children to the terminal without escaping anything, so a
+ *    surviving `\r` overwrites the row it is drawn on and a surviving `ESC`
+ *    repaints the frame colours. Sequences are gone by this point, so what is
+ *    left for this step is a stray byte, never half of one.
+ * 4. DEL and every C1 byte (U+0080..U+009F) go too, and that is NOT padding:
+ *    U+009B is the single-byte CSI and U+0085 is NEL, and a terminal that
+ *    decodes them acts on them exactly as it acts on `ESC [`. A file pasted out
+ *    of a non-UTF-8 editor walks straight through a "strip C0" rule.
+ * 5. TAB is KEPT. Indentation is content, and it is what the model receives.
+ *    Expanding it is the RENDERERS' job (`ui/display-tab.ts`), so the model
+ *    keeps the original indentation while the screen, the composer and the
+ *    terminal all agree on what column a TAB lands on.
+ *
+ * Applied to PAYLOAD ONLY, never to keystrokes, so `Ctrl+A` and Escape keep
+ * working. Non-ASCII text (CJK, emoji) is untouched. Idempotent, so the
+ * second pass in `ui/paste-frames.ts` stays a byte-identical no-op.
+ */
+export declare function sanitisePaste(raw: string): string;

package/dist/input/paste-parse.js

@@ -0,0 +1,107 @@
+/**
+ * Paste recognition primitives (tui-paste-handling section 5.1) -- pure,
+ * stream-free, no timers.
+ *
+ * WHY THIS LIVES BELOW INK. `ink/build/components/App.js:131-138` reads stdin on
+ * `'readable'` and emits each chunk as one `'input'` event;
+ * `parse-keypress.js:145-148` maps the exact string `'\r'` to `name: 'return'`,
+ * which `PromptInput` reads as "send the message". A 15-line paste on a Windows
+ * console routinely arrives as a dozen chunks that are exactly `"\r"`, and each
+ * one SUBMITS THE DRAFT AS IT STOOD. No component-level heuristic can undo a
+ * `key.return` that has already fired, so recognition has to happen on the byte
+ * stream, in front of Ink -- the same lesson `mouse-events.ts` records.
+ *
+ * Two tiers feed one framing (D-4). Tier 1 is bracketed paste and is exact;
+ * Tier 2 is a heuristic on chunk SHAPE for the terminals that ignore
+ * `DECSET 2004`. Both are about what a keyboard can physically emit.
+ */
+import { PASTE_MIN_BURST_CHARS } from './limits.js';
+import { stripControlSequences } from './control-sequences.js';
+/** `DECSET 2004` wraps a paste in these two markers. */
+export const PASTE_BEGIN_MARK = '\x1b[200~';
+export const PASTE_END_MARK = '\x1b[201~';
+/** The longest tail worth holding back while a marker might still complete. */
+export const PASTE_MARK_LENGTH = PASTE_BEGIN_MARK.length;
+/**
+ * True when `s` is a PROPER prefix of either paste marker (never a whole one).
+ *
+ * Both markers are held, in every mode, whether or not THIS process enabled DEC
+ * 2004 (I-16): the user's shell, `tmux` or a wrapper script may have left it on,
+ * and an unconsumed marker is a literal `[200~` typed into the draft -- the
+ * exact failure the feature exists to prevent.
+ */
+export function isPastePrefix(s) {
+    if (s.length === 0 || s.length >= PASTE_MARK_LENGTH)
+        return false;
+    return PASTE_BEGIN_MARK.startsWith(s) || PASTE_END_MARK.startsWith(s);
+}
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a paste
+ * marker, or 0. Shortest match wins, so only the bytes that could still become a
+ * marker are held back.
+ */
+export function trailingPastePrefixLength(text) {
+    const max = Math.min(text.length, PASTE_MARK_LENGTH - 1);
+    for (let k = 1; k <= max; k += 1) {
+        if (isPastePrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}
+/** Any C0 control byte other than TAB -- ESC, BEL, NUL, CR, LF included. */
+const HAS_CONTROL_EXCEPT_TAB = /[\u0000-\u0008\u000A-\u001F]/;
+/**
+ * Tier 2: is this chunk a paste, or keystrokes?
+ *
+ * The PRIMARY rule -- "longer than one character AND contains a line break" --
+ * is exactly the shape defect A needs, so the two coincide: any chunk that could
+ * submit the draft by accident is classified as a paste. A lone `\r` is the
+ * Enter key and stays `'keys'`.
+ *
+ * The SECONDARY rule needs `PASTE_MIN_BURST_CHARS` printable characters in one
+ * chunk. It excludes chunks carrying any C0 byte but TAB, which is what keeps an
+ * arrow-key burst (`\x1b[B\x1b[B...`, and every wheel notch translated by
+ * alternate scroll) out of the paste path.
+ */
+export function classifyChunk(text, minBurstChars = PASTE_MIN_BURST_CHARS) {
+    if (text.length > 1 && /[\r\n]/.test(text))
+        return 'paste';
+    if (text.length >= minBurstChars && !HAS_CONTROL_EXCEPT_TAB.test(text))
+        return 'paste';
+    return 'keys';
+}
+/**
+ * Make a payload safe to put in a buffer and draw through `<Text>` (G2).
+ *
+ * 1. CRLF and lone CR both become exactly ONE `\n` -- terminals send CR for a
+ *    newline in pasted text, and a lone LF is dropped by Ink's key parser
+ *    entirely, so both have to be normalised here or a pasted line break either
+ *    submits the message or silently vanishes.
+ * 2. Every escape SEQUENCE is removed AS A SEQUENCE (`stripControlSequences`).
+ *    Deleting only the introducer byte is what produced the reported defect:
+ *    `ESC [ 3 8 ; 2 ; 1 8 ; 5 2 ; 8 6 m` minus its ESC is `[38;2;18;52;86m`,
+ *    a run of digits Ink then writes to the terminal as ordinary text -- and it
+ *    reached the model, the prompt history and the session file too, because
+ *    this function is the only cleaning the payload ever gets.
+ * 3. Every remaining C0 byte except `\n` and `\t` is removed. Ink writes
+ *    `<Text>` children to the terminal without escaping anything, so a
+ *    surviving `\r` overwrites the row it is drawn on and a surviving `ESC`
+ *    repaints the frame colours. Sequences are gone by this point, so what is
+ *    left for this step is a stray byte, never half of one.
+ * 4. DEL and every C1 byte (U+0080..U+009F) go too, and that is NOT padding:
+ *    U+009B is the single-byte CSI and U+0085 is NEL, and a terminal that
+ *    decodes them acts on them exactly as it acts on `ESC [`. A file pasted out
+ *    of a non-UTF-8 editor walks straight through a "strip C0" rule.
+ * 5. TAB is KEPT. Indentation is content, and it is what the model receives.
+ *    Expanding it is the RENDERERS' job (`ui/display-tab.ts`), so the model
+ *    keeps the original indentation while the screen, the composer and the
+ *    terminal all agree on what column a TAB lands on.
+ *
+ * Applied to PAYLOAD ONLY, never to keystrokes, so `Ctrl+A` and Escape keep
+ * working. Non-ASCII text (CJK, emoji) is untouched. Idempotent, so the
+ * second pass in `ui/paste-frames.ts` stays a byte-identical no-op.
+ */
+export function sanitisePaste(raw) {
+    return stripControlSequences(raw.replace(/\r\n?/g, '\n'))
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '');
+}

package/dist/input/pointer-router.d.ts

@@ -0,0 +1,11 @@
+import type { MouseEvent } from './mouse-events.js';
+import type { MouseSource } from './stdin-filter.js';
+export interface PointerRouter {
+    selectionSource: MouseSource;
+    dispose(): void;
+}
+/** Deliver each button gesture to the scrollbar before the selection source. */
+export declare function createPointerRouter(options: {
+    source: MouseSource;
+    handle(event: MouseEvent): boolean;
+}): PointerRouter;

package/dist/input/pointer-router.js

@@ -0,0 +1,14 @@
+/** Deliver each button gesture to the scrollbar before the selection source. */
+export function createPointerRouter(options) {
+    const listeners = new Set();
+    const unsubscribe = options.source.subscribe((event) => {
+        if (event.kind !== 'wheel' && options.handle(event))
+            return;
+        for (const listener of listeners)
+            listener(event);
+    });
+    return { selectionSource: { subscribe: (listener) => {
+                listeners.add(listener);
+                return () => { listeners.delete(listener); };
+            } }, dispose: () => { unsubscribe(); listeners.clear(); } };
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Stdin filter (mouse-wheel-region-routing section 4.2 / 5.2, extended by
+ * tui-paste-handling section 5.1).
+ *
+ * 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, frames every paste, and writes the
+ * remainder into a `PassThrough` that carries the surface Ink requires.
+ *
+ * ONE CHANNEL, NOT TWO, AND THAT NOW COVERS PASTES AS WELL (D-2 / D-3). A second
+ * chained filter would need a second `PassThrough` and would reopen the ordering
+ * hazard this note closes; a side-channel paste emit would apply the payload
+ * BEFORE text that preceded it in the same chunk, because `wrapper.write` is
+ * asynchronous and a synchronous emit is not. The paste therefore travels
+ * INLINE, wrapped in `PASTE_OPEN` / `PASTE_CLOSE` (I-5).
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h` or `\x1b[?2004h`. Reporting or
+ * bracketed paste enabled while Ink still holds the raw stream does not degrade
+ * the feature -- it types `[<0;12;5M` or `[200~` into the user's message, which
+ * is strictly worse than the bug being fixed.
+ *
+ * THE HANDLE ANSWERS EXACTLY ONE QUESTION: "is a stream wrapped?" (I-11 / D-17).
+ * It stopped being the answer to "is the mouse on?" the moment paste could build
+ * a filter on its own -- `paste` defaults to `true`, so `aragon --no-mouse`
+ * builds one. `cli.tsx` reads its own `mouseOn` / `pasteOn` booleans; this module
+ * is told which features it is running and never derives them.
+ */
+import { type MouseEvent } from './mouse-events.js';
+import { type PasteBridge } from './limits.js';
+export interface MouseSource {
+    /**
+     * Returns an unsubscribe function. Multiple subscribers are allowed -- the
+     * wheel router and (since tui-selection-and-scroll-follow) the selection
+     * controller both take this one channel, and each ignores the kinds it does
+     * not own.
+     *
+     * With `features.mouse` false the channel exists and stays SILENT forever, so
+     * a subscriber written against it does not have to know which features are on.
+     */
+    subscribe(listener: (event: MouseEvent) => void): () => void;
+}
+/**
+ * Which stream-level features this filter is running.
+ *
+ * TOLD, NEVER DERIVED (D-17 / P0-1). With `{ mouse: false, paste: true }` no
+ * `MouseEvent` is ever emitted and `splitMouseEvents` is not called at all: a
+ * `--no-mouse` session never wrote `?1000h`, so no real report can arrive, and
+ * running the parser anyway could only ever EAT pasted bytes that happen to look
+ * like one. With `{ mouse: true, paste: false }` this is byte-for-byte the
+ * v0.6.3 mouse filter.
+ */
+export interface StdinFilterFeatures {
+    /** Parse and strip SGR / X10 mouse reports, and emit `MouseEvent`s. */
+    readonly mouse: boolean;
+    /** Recognise pastes and deliver them framed. */
+    readonly paste: boolean;
+    /**
+     * Translate keyboard-enhancement encodings (win32-input-mode records on
+     * Windows, CSI-u sequences from kitty/modifyOtherKeys elsewhere) back to
+     * legacy bytes BEFORE Ink parses them. TOLD, never derived: `cli.tsx`
+     * resolves config, TTY state and `vtInputSupported`, and passes the same
+     * boolean to `enableKeyboardEnhancement`, so the filter only ever
+     * translates for a session whose mode push actually happened.
+     */
+    readonly enhancedKeys?: boolean;
+    /**
+     * Strip the Cursor Position Report a terminal sends back for `ESC[6n`
+     * (tui-bottom-anchored-live-region §4.5).
+     *
+     * TOLD, never derived, like the three above: `cli.tsx` passes
+     * `plan.differ === 'scrollback'`, so an `app`-mode session stays byte-identical to
+     * the build without this feature (I-A8). The report MUST NOT reach Ink -- `[` is
+     * 0x5B, so `PromptInput`'s control-sequence guard passes it and the reply gets
+     * typed into the draft -- and a report split across two reads is worse than a
+     * whole one, because `parse-keypress` has no branch for a half sequence.
+     */
+    readonly cursorReport?: boolean;
+}
+export interface StdinFilter {
+    /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */
+    readonly stdin: NodeJS.ReadStream;
+    readonly source: MouseSource;
+    /**
+     * The probe is waiting for an answer: hold a possible report prefix until it
+     * settles instead of flushing it after `PENDING_FLUSH_MS`.
+     *
+     * ConPTY can split `ESC[12;1R` across two reads further apart than 12 ms, and a
+     * half report that reaches Ink lands on an undefined branch of its key parser.
+     * Turning this off flushes whatever is still held as ordinary text -- the
+     * correct degradation for a terminal that answered with something else (R3).
+     */
+    setExpectingCursorReport(on: boolean): void;
+    /** Idempotent. Detaches from the real stdin and clears every timer (I-7). */
+    dispose(): void;
+}
+export declare function createStdinFilter(real: NodeJS.ReadStream, features: StdinFilterFeatures, bridge?: PasteBridge, onWarn?: (reason: string) => void): StdinFilter;
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): a construction failure must
+ * degrade to "the wheel is inert and pastes are keystrokes" -- a supported,
+ * tested rung of the fail-safe ladder -- rather than leaving `?1000h` or `?2004h`
+ * on with no filter in front of Ink. `cli.tsx` derives BOTH `mouseOn` and
+ * `pasteOn` from the returned handle for exactly that reason.
+ */
+export declare function tryCreateStdinFilter(real: NodeJS.ReadStream, features: StdinFilterFeatures, onError?: (reason: string) => void, bridge?: PasteBridge): StdinFilter | null;