@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/input/csiu-keys.js

@@ -0,0 +1,181 @@
+/**
+ * CSI-u key translation (posix keyboard-enhancement section of the Shift+Enter
+ * newline fix).
+ *
+ * WHY THIS EXISTS. On macOS/Linux the only lever that makes Shift+Enter
+ * distinguishable from Enter is asking the terminal to report modified keys in
+ * the CSI-u encoding: kitty's disambiguate mode (`CSI > 1 u`, pushed and popped
+ * with `CSI < u`) and xterm's `modifyOtherKeys=2` (`CSI > 4 ; 2 m`, reset with
+ * `CSI > 4 m`). iTerm2, kitty, ghostty, WezTerm, foot and Alacritty implement
+ * at least one of the two; a terminal implementing neither ignores both bytes,
+ * which the conhost probe confirmed is a harmless no-op.
+ *
+ * WHAT CHANGES IN THE STREAM -- AND WHAT NEVER DOES. Both modes re-encode only
+ * keys whose legacy encoding is ambiguous: Ctrl/Ctrl+Shift/Ctrl+Alt+letters and
+ * digits, the Enter family, the Escape key (kitty), and Backspace with
+ * modifiers. `modifyOtherKeys` is named for the OTHER keys: arrows, Home/End,
+ * PgUp/PgDn and F-keys keep their standard `\x1b[1;mA` / `\x1b[m~` encodings,
+ * and Shift+printable still types text. So the translator below only ever sees
+ * codepoints below 128 plus a few named control codes; anything else (a kitty
+ * functional-key code from a mode this app never pushes) passes through
+ * untouched, which is exactly the pre-enhancement behaviour.
+ *
+ * THE CONTRACT mirrors `win32-input-mode.ts`: split, translate back to the
+ * legacy bytes, with the modified-Enter family becoming `ENTER_NEWLINE_FRAME`.
+ * Pure: no node/React imports.
+ */
+import { ENTER_NEWLINE_FRAME, INDEX_KEY_FRAME } from './limits.js';
+/** Enable / disable the two CSI-u report modes (posix side). */
+export const CSI_U_ENABLE = '\x1b[>1u\x1b[>4;2m';
+export const CSI_U_DISABLE = '\x1b[<u\x1b[>4m';
+const isParamChar = (c) => (c >= '0' && c <= '9') || c === ';' || c === ':';
+/**
+ * Split a chunk into text spans and CSI-u sequences.
+ *
+ * Grammar accepted: `ESC [ <params> u` where params are digits, `;` and `:`
+ * only, and at least one field exists. `\x1b[13;2u` is INCLUDED: with
+ * enhancement on, this module owns every `u`-terminated sequence and applies
+ * the same Enter semantics `enter-sequences.ts` defines.
+ */
+export function splitCsiUKeys(text) {
+    const segments = [];
+    let start = 0;
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] !== '\x1b' || text[index + 1] !== '[') {
+            index += 1;
+            continue;
+        }
+        let end = index + 2;
+        while (end < text.length && isParamChar(text[end]))
+            end += 1;
+        if (end >= text.length || text[end] !== 'u') {
+            index += 1;
+            continue;
+        }
+        const key = parseKey(text.slice(index + 2, end), text.slice(index, end + 1));
+        if (!key) {
+            index += 1;
+            continue;
+        }
+        if (index > start)
+            segments.push({ kind: 'text', text: text.slice(start, index) });
+        segments.push({ kind: 'key', key });
+        index = end + 1;
+        start = index;
+    }
+    if (start < text.length)
+        segments.push({ kind: 'text', text: text.slice(start) });
+    return segments;
+}
+/** Parse the parameter body of a CSI-u sequence, or null when malformed. */
+function parseKey(body, seq) {
+    if (body.length === 0)
+        return null;
+    const fields = body.split(';');
+    const keyParts = fields[0]?.split(':').map(Number) ?? [];
+    if (keyParts.some((n) => !Number.isInteger(n) || n < 0 || n > 0x10ffff))
+        return null;
+    const code = keyParts[0];
+    if (code === undefined)
+        return null;
+    let mods = 0;
+    if (fields.length > 1) {
+        const modParts = fields[1]?.split(':').map(Number) ?? [];
+        if (modParts.some((n) => !Number.isInteger(n) || n < 0 || n > 64))
+            return null;
+        const m = modParts[0] ?? 0;
+        mods = Math.max(0, m - 1);
+    }
+    return { seq, code, alternates: keyParts.slice(1), mods };
+}
+/** Control code for Ctrl+letter (a-z -> 1-26), or the char itself. */
+function ctrlByte(char) {
+    if (char >= 97 && char <= 122)
+        return char - 96;
+    if (char >= 65 && char <= 90)
+        return char - 64;
+    return char;
+}
+/**
+ * Translate one CSI-u sequence to the legacy bytes the same keypress would
+ * have produced without the report modes (Enter family excepted: a modified
+ * Enter becomes the newline frame). Unknown keys pass through unchanged.
+ */
+export function translateCsiUKey(key) {
+    const m = key.mods;
+    const ctrl = (m & 4) !== 0;
+    const alt = (m & 2) !== 0;
+    const shift = (m & 1) !== 0;
+    if (key.code === 13)
+        return m === 0 ? '\r' : ENTER_NEWLINE_FRAME;
+    if (key.code === 27)
+        return alt ? '\x1b\x1b' : '\x1b';
+    if (key.code === 9) {
+        // A modified Tab codepoint (modifyOtherKeys shape) mirrors the VK_TAB
+        // decision in win32-input-mode.ts: ctrl (without shift/alt) is the
+        // project-indexer trigger frame, shift stays Shift+Tab.
+        if (ctrl && !shift && !alt)
+            return INDEX_KEY_FRAME;
+        return shift ? '\x1b[Z' : '\t';
+    }
+    // Ctrl+I under kitty disambiguate arrives as codepoint 105 with the ctrl
+    // modifier; the generic printable branch below would fold it back onto the
+    // legacy Tab byte, which is exactly the ambiguity the frame exists to break.
+    if (key.code === 105 && ctrl && !shift && !alt)
+        return INDEX_KEY_FRAME;
+    if (key.code === 127) {
+        // POST-normalisation bytes, same rationale as VK_BACK in win32-input-mode.
+        if (alt)
+            return '\x1b\x08';
+        return '\x08';
+    }
+    if (key.code === 32) {
+        // Ctrl+Space is 0x00 in legacy xterm; plain/alt space is the character.
+        if (ctrl)
+            return alt ? '\x1b\x00' : '\x00';
+        return alt ? '\x1b ' : ' ';
+    }
+    if (key.code >= 32 && key.code <= 126) {
+        const char = String.fromCharCode(key.code);
+        if (ctrl) {
+            const code = ctrlByte(key.code);
+            const text = code === key.code ? char : String.fromCharCode(code);
+            return alt ? `\x1b${text}` : text;
+        }
+        if (alt)
+            return `\x1b${char}`;
+        if (shift && key.alternates.length > 0) {
+            const shifted = key.alternates[0];
+            if (shifted !== undefined && shifted > 0)
+                return String.fromCodePoint(shifted);
+        }
+        return char;
+    }
+    // Functional-key codes only appear under modes this app never pushes
+    // (kitty flags 2+); pass them through so behaviour matches the un-enhanced
+    // stream instead of inventing a translation.
+    return key.seq;
+}
+/** True when `s` is a PROPER prefix of some CSI-u sequence. */
+function isCsiUPrefix(s) {
+    if (s.length < 3 || s[0] !== '\x1b' || s[1] !== '[')
+        return false;
+    for (let i = 2; i < s.length; i += 1) {
+        if (!isParamChar(s[i]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Length of the trailing run of `text` that could still complete into a
+ * CSI-u sequence, or 0. Longest match, mirroring the other families.
+ */
+export function trailingCsiUPrefixLength(text) {
+    const max = Math.min(text.length, 32);
+    for (let k = max; k >= 1; k -= 1) {
+        if (isCsiUPrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}

package/dist/input/cursor-report.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Cursor Position Report parsing (tui-bottom-anchored-live-region §4.5).
+ *
+ * The bottom anchor needs one number the writer cannot compute: how many rows are
+ * left below the cursor. `ESC[6n` is the only way to ask, and the terminal answers
+ * with `ESC[<row>;<col>R` (DECXCPR adds a `?`: `ESC[?<row>;<col>R`) on STDIN —
+ * the same stream the user types on. Two things follow, and both live here:
+ *
+ *  1. THE ANSWER MUST BE STRIPPED BEFORE INK SEES IT. A report that reaches Ink
+ *     travels the keystroke path: `[` is 0x5B, so `PromptInput`'s control-sequence
+ *     guard passes it through and the user's draft gets `[12;1R` typed into it (the
+ *     same class of accident the mouse filter exists to prevent).
+ *  2. THE ANSWER CAN ARRIVE IN TWO CHUNKS. ConPTY, tmux and a loaded SSH session
+ *     all split reads at arbitrary points, and a half report (`ESC[12`) is worse
+ *     than a whole one: `parse-keypress` has no branch for it.
+ *
+ * Pure functions only, mirroring `mouse-events.ts`: the filter owns the buffering
+ * and the timers, this module owns the shapes.
+ */
+/** The query for a Cursor Position Report (DSR 6). ASCII by construction. */
+export declare const CURSOR_REPORT_QUERY = "\u001B[6n";
+/** One parsed report. `row`/`col` are 1-based, exactly as the terminal sent them. */
+export interface CursorReport {
+    row: number;
+    col: number;
+}
+export interface CursorReportSplit {
+    /** Text that survives stripping — everything that is not a report. */
+    text: string;
+    /** Reports found in this chunk, in order. */
+    reports: CursorReport[];
+    /** Trailing bytes that could still become a report; hand them to the next chunk. */
+    pending: string;
+}
+/** True when `s` is a non-empty proper prefix of a possible report. */
+export declare function isCursorReportPrefix(s: string): boolean;
+/**
+ * Split the reports out of one chunk.
+ *
+ * `pending` carries the tail that might still complete into a report. It is only
+ * ever the LAST fragment: the scan is left to right, so anything before a complete
+ * report is settled text.
+ */
+export declare function splitCursorReports(text: string): CursorReportSplit;
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a report, or 0.
+ *
+ * LONGEST MATCH WINS, unlike the mouse family's shortest-wins rule. The families are
+ * combined with `max()`, so only the longest answer ever survives, and a longer hold
+ * is never wrong here: `ESC[1` can still become `ESC[12;1R`, while the shorter
+ * answer `ESC` could not describe it. The bound is the longest report the terminals
+ * we target emit (DECXCPR with a `?` and three-digit coordinates).
+ */
+export declare function trailingCprPrefixLength(text: string): number;
+/** The query bytes, as a function so call sites read as an action rather than a literal. */
+export declare function formatCursorReportQuery(): string;
+/**
+ * Rows left below a reported cursor row on a terminal of `rows` rows.
+ * `0` means the cursor is already on the last row; `null` when the height is unknown.
+ */
+export declare function spaceBelowFromReport(report: CursorReport, rows: number | undefined): number | null;

package/dist/input/cursor-report.js

@@ -0,0 +1,97 @@
+/**
+ * Cursor Position Report parsing (tui-bottom-anchored-live-region §4.5).
+ *
+ * The bottom anchor needs one number the writer cannot compute: how many rows are
+ * left below the cursor. `ESC[6n` is the only way to ask, and the terminal answers
+ * with `ESC[<row>;<col>R` (DECXCPR adds a `?`: `ESC[?<row>;<col>R`) on STDIN —
+ * the same stream the user types on. Two things follow, and both live here:
+ *
+ *  1. THE ANSWER MUST BE STRIPPED BEFORE INK SEES IT. A report that reaches Ink
+ *     travels the keystroke path: `[` is 0x5B, so `PromptInput`'s control-sequence
+ *     guard passes it through and the user's draft gets `[12;1R` typed into it (the
+ *     same class of accident the mouse filter exists to prevent).
+ *  2. THE ANSWER CAN ARRIVE IN TWO CHUNKS. ConPTY, tmux and a loaded SSH session
+ *     all split reads at arbitrary points, and a half report (`ESC[12`) is worse
+ *     than a whole one: `parse-keypress` has no branch for it.
+ *
+ * Pure functions only, mirroring `mouse-events.ts`: the filter owns the buffering
+ * and the timers, this module owns the shapes.
+ */
+/** The query for a Cursor Position Report (DSR 6). ASCII by construction. */
+export const CURSOR_REPORT_QUERY = '\x1b[6n';
+/**
+ * `ESC[<row>;<col>R`, with the DECXCPR `?` accepted. Anchored on `ESC[` plus digits
+ * and one `;`, which is what keeps it from matching a private-mode write such as
+ * `ESC[?25l` (that one ends in a letter this pattern cannot accept).
+ *
+ * Built per call rather than shared: a module-level `/g` regex carries `lastIndex`
+ * between calls, which turns a pure function into a stateful one.
+ */
+const reportPattern = () => /\x1b\[\??(\d+);(\d+)R/g;
+/**
+ * A PROPER prefix of a report: `ESC`, `ESC[`, then an optional `?`, then digits, at
+ * most one `;`, then more digits. Nothing a keyboard produces matches past `ESC[`
+ * (arrow keys end in a letter), so the filter's 12 ms hold stays a rare path.
+ */
+const PREFIX = /^\x1b(\[(\?(\d*(;\d*)?)?|\d*(;\d*)?)?)?$/;
+/** True when `s` is a non-empty proper prefix of a possible report. */
+export function isCursorReportPrefix(s) {
+    return s.length > 0 && s.length < 24 && PREFIX.test(s);
+}
+/**
+ * Split the reports out of one chunk.
+ *
+ * `pending` carries the tail that might still complete into a report. It is only
+ * ever the LAST fragment: the scan is left to right, so anything before a complete
+ * report is settled text.
+ */
+export function splitCursorReports(text) {
+    const reports = [];
+    const pattern = reportPattern();
+    let out = '';
+    let index = 0;
+    for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+        out += text.slice(index, match.index);
+        reports.push({ row: Number(match[1]), col: Number(match[2]) });
+        index = match.index + match[0].length;
+    }
+    out += text.slice(index);
+    const pendingLength = trailingCprPrefixLength(out);
+    if (pendingLength === 0)
+        return { text: out, reports, pending: '' };
+    return {
+        text: out.slice(0, out.length - pendingLength),
+        reports,
+        pending: out.slice(out.length - pendingLength),
+    };
+}
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a report, or 0.
+ *
+ * LONGEST MATCH WINS, unlike the mouse family's shortest-wins rule. The families are
+ * combined with `max()`, so only the longest answer ever survives, and a longer hold
+ * is never wrong here: `ESC[1` can still become `ESC[12;1R`, while the shorter
+ * answer `ESC` could not describe it. The bound is the longest report the terminals
+ * we target emit (DECXCPR with a `?` and three-digit coordinates).
+ */
+export function trailingCprPrefixLength(text) {
+    const max = Math.min(text.length, 24);
+    for (let k = max; k >= 1; k -= 1) {
+        if (isCursorReportPrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}
+/** The query bytes, as a function so call sites read as an action rather than a literal. */
+export function formatCursorReportQuery() {
+    return CURSOR_REPORT_QUERY;
+}
+/**
+ * Rows left below a reported cursor row on a terminal of `rows` rows.
+ * `0` means the cursor is already on the last row; `null` when the height is unknown.
+ */
+export function spaceBelowFromReport(report, rows) {
+    if (rows === undefined || !Number.isFinite(rows) || rows < 1)
+        return null;
+    return Math.max(0, Math.floor(rows) - 1 - (report.row - 1));
+}

package/dist/input/enter-sequences.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Enter-family sequence recognition (tui-shift-enter-copy-queue §3.3) -- pure,
+ * stream-free, no node/React imports, callable from any test environment.
+ *
+ * WHY THIS LIVES BELOW INK. Ink 5's `parse-keypress.js` calls `parseKeypress`
+ * ONCE per stdin chunk and hard-codes `shift: false` for the exact string
+ * `'\r'`, so a component can never see `key.return && key.shift` -- the
+ * `PromptInput` branch for it is dead code. Worse, terminals that DO encode a
+ * distinct Shift+Enter send CSI-u (`\x1b[13;2u`), which Ink's `fnKeyRe` does
+ * not match: the ESC is stripped by `use-input.js` and `'[13;2u'` falls through
+ * to the PRINTABLE branch, typing garbage into the draft. The only layer that
+ * sees the bytes before Ink mangles them is the stdin filter, which is where
+ * the mouse-report and paste-marker dialects are already translated.
+ *
+ * THE CONTRACT: rewrite every recognized sequence to ONE normalized token --
+ * `ENTER_NEWLINE_FRAME` for "this was a modified Enter, the user wants a
+ * newline" and `'\r'` for the unmodified CSI-u Enter some other program left
+ * behind. No state, no partial-output: `rewriteEnterSequences` is idempotent
+ * because its output contains none of its inputs.
+ */
+/** What one recognized sequence means, for tests and `/terminal-setup` copy. */
+export interface EnterSequenceSpec {
+    /** The exact byte sequence a terminal sends for this key. */
+    readonly seq: string;
+    /** The chord it names, e.g. `'shift+enter'`, `'ctrl+alt+enter'`, `'enter'`. */
+    readonly meaning: string;
+    /** What `rewriteEnterSequences` replaces it with. */
+    readonly to: string;
+}
+/**
+ * The recognition table (§3.3). CSI-u modifiers 2-8 cover Shift(2), Alt(3),
+ * Shift+Alt(4), Ctrl(5), Ctrl+Shift(6), Ctrl+Alt(7), Ctrl+Alt+Shift(8) as
+ * emitted by kitty/WezTerm keyboard-enhancement mode and by
+ * `modifyOtherKeys=2`; every one of them means "Enter with a modifier", and a
+ * modified Enter must NEVER submit the draft. `\x1b\r` / `\x1b\n` are the
+ * classic Alt+Enter encodings. `\x1b[13u` (no modifier field) is what a
+ * leftover kitty mode sends for a PLAIN Enter: it must submit, so it maps to
+ * `'\r'` rather than to a newline.
+ */
+export declare const ENTER_SEQUENCES: readonly EnterSequenceSpec[];
+export type EnterSequenceSegment = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'newline';
+} | {
+    kind: 'submit';
+};
+/** Split explicit keys using the recognition table; bare CR/LF remain text. */
+export declare function splitEnterSequences(text: string): EnterSequenceSegment[];
+/** Normalize explicit Enter keys without changing unknown sequences. */
+export declare function rewriteEnterSequences(text: string): string;
+/**
+ * Length of the trailing run of `text` that is a proper prefix of an
+ * Enter-family sequence, or 0.
+ *
+ * LONGEST MATCH, not shortest: unlike the mouse and paste families, a torn
+ * CSI-u sequence diverges from its siblings only at the LAST byte
+ * (`\x1b[13;` + `2u`), so every byte before the divergence point must be held
+ * back for the next chunk or the sequence is destroyed a byte early. Feeding
+ * the result into the filter's `keep = max(...)` alongside the other two
+ * families keeps every family's hold intact.
+ */
+export declare function trailingEnterPrefixLength(text: string): number;

package/dist/input/enter-sequences.js

@@ -0,0 +1,153 @@
+/**
+ * Enter-family sequence recognition (tui-shift-enter-copy-queue §3.3) -- pure,
+ * stream-free, no node/React imports, callable from any test environment.
+ *
+ * WHY THIS LIVES BELOW INK. Ink 5's `parse-keypress.js` calls `parseKeypress`
+ * ONCE per stdin chunk and hard-codes `shift: false` for the exact string
+ * `'\r'`, so a component can never see `key.return && key.shift` -- the
+ * `PromptInput` branch for it is dead code. Worse, terminals that DO encode a
+ * distinct Shift+Enter send CSI-u (`\x1b[13;2u`), which Ink's `fnKeyRe` does
+ * not match: the ESC is stripped by `use-input.js` and `'[13;2u'` falls through
+ * to the PRINTABLE branch, typing garbage into the draft. The only layer that
+ * sees the bytes before Ink mangles them is the stdin filter, which is where
+ * the mouse-report and paste-marker dialects are already translated.
+ *
+ * THE CONTRACT: rewrite every recognized sequence to ONE normalized token --
+ * `ENTER_NEWLINE_FRAME` for "this was a modified Enter, the user wants a
+ * newline" and `'\r'` for the unmodified CSI-u Enter some other program left
+ * behind. No state, no partial-output: `rewriteEnterSequences` is idempotent
+ * because its output contains none of its inputs.
+ */
+import { ENTER_NEWLINE_FRAME } from './limits.js';
+/**
+ * The recognition table (§3.3). CSI-u modifiers 2-8 cover Shift(2), Alt(3),
+ * Shift+Alt(4), Ctrl(5), Ctrl+Shift(6), Ctrl+Alt(7), Ctrl+Alt+Shift(8) as
+ * emitted by kitty/WezTerm keyboard-enhancement mode and by
+ * `modifyOtherKeys=2`; every one of them means "Enter with a modifier", and a
+ * modified Enter must NEVER submit the draft. `\x1b\r` / `\x1b\n` are the
+ * classic Alt+Enter encodings. `\x1b[13u` (no modifier field) is what a
+ * leftover kitty mode sends for a PLAIN Enter: it must submit, so it maps to
+ * `'\r'` rather than to a newline.
+ */
+export const ENTER_SEQUENCES = [
+    { seq: '\x1b[13;1u', meaning: 'enter', to: '\r' },
+    {
+        seq: '\x1b[13;2u',
+        meaning: 'shift+enter',
+        to: ENTER_NEWLINE_FRAME,
+    },
+    {
+        seq: '\x1b[13;3u',
+        meaning: 'alt+enter',
+        to: ENTER_NEWLINE_FRAME,
+    },
+    {
+        seq: '\x1b[13;4u',
+        meaning: 'shift+alt+enter',
+        to: ENTER_NEWLINE_FRAME,
+    },
+    {
+        seq: '\x1b[13;5u',
+        meaning: 'ctrl+enter',
+        to: ENTER_NEWLINE_FRAME,
+    },
+    {
+        seq: '\x1b[13;6u',
+        meaning: 'ctrl+shift+enter',
+        to: ENTER_NEWLINE_FRAME,
+    },
+    {
+        seq: '\x1b[13;7u',
+        meaning: 'ctrl+alt+enter',
+        to: ENTER_NEWLINE_FRAME,
+    },
+    {
+        seq: '\x1b[13;8u',
+        meaning: 'ctrl+alt+shift+enter',
+        to: ENTER_NEWLINE_FRAME,
+    },
+    {
+        seq: '\x1b\r',
+        meaning: 'alt+enter',
+        to: ENTER_NEWLINE_FRAME,
+    },
+    {
+        seq: '\x1b\n',
+        meaning: 'alt+enter',
+        to: ENTER_NEWLINE_FRAME,
+    },
+    {
+        seq: '\x1b[13u',
+        meaning: 'enter',
+        to: '\r',
+    },
+];
+/**
+ * Longest strict prefix any recognized sequence can have. Derived from the
+ * table rather than hard-coded so adding a sequence can never leave the hold
+ * ceiling behind: the longest sequence is 7 bytes, so a torn sequence can hold
+ * up to 6 of them.
+ */
+const MAX_ENTER_PREFIX = Math.max(...ENTER_SEQUENCES.map((s) => s.seq.length)) - 1;
+/** Split explicit keys using the recognition table; bare CR/LF remain text. */
+export function splitEnterSequences(text) {
+    const segments = [];
+    let start = 0;
+    let index = 0;
+    while (index < text.length) {
+        const match = text[index] === '\x1b'
+            ? ENTER_SEQUENCES.find((spec) => text.startsWith(spec.seq, index)) : undefined;
+        if (!match) {
+            index += 1;
+            continue;
+        }
+        if (index > start)
+            segments.push({ kind: 'text', text: text.slice(start, index) });
+        segments.push({ kind: match.to === '\r' ? 'submit' : 'newline' });
+        index += match.seq.length;
+        start = index;
+    }
+    if (start < text.length)
+        segments.push({ kind: 'text', text: text.slice(start) });
+    return segments;
+}
+/** Normalize explicit Enter keys without changing unknown sequences. */
+export function rewriteEnterSequences(text) {
+    return splitEnterSequences(text).map((segment) => {
+        if (segment.kind === 'text')
+            return segment.text;
+        return segment.kind === 'submit' ? '\r' : ENTER_NEWLINE_FRAME;
+    }).join('');
+}
+/** True when `s` is a PROPER prefix of some recognized sequence (never whole). */
+function isEnterPrefix(s) {
+    if (s.length === 0 || s.length > MAX_ENTER_PREFIX)
+        return false;
+    for (const spec of ENTER_SEQUENCES) {
+        // `length >`, not `startsWith` alone: `startsWith` accepts the WHOLE
+        // sequence too, and holding a complete sequence back would add 12 ms
+        // of latency to a key that is ready to be rewritten right now.
+        if (spec.seq.length > s.length && spec.seq.startsWith(s))
+            return true;
+    }
+    return false;
+}
+/**
+ * Length of the trailing run of `text` that is a proper prefix of an
+ * Enter-family sequence, or 0.
+ *
+ * LONGEST MATCH, not shortest: unlike the mouse and paste families, a torn
+ * CSI-u sequence diverges from its siblings only at the LAST byte
+ * (`\x1b[13;` + `2u`), so every byte before the divergence point must be held
+ * back for the next chunk or the sequence is destroyed a byte early. Feeding
+ * the result into the filter's `keep = max(...)` alongside the other two
+ * families keeps every family's hold intact.
+ */
+export function trailingEnterPrefixLength(text) {
+    const max = Math.min(text.length, MAX_ENTER_PREFIX);
+    for (let k = max; k >= 1; k -= 1) {
+        if (isEnterPrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}

package/dist/input/interrupt-gesture.d.ts

@@ -0,0 +1,18 @@
+/** Confirmation window for two independent decoded Escape events. */
+export declare const INTERRUPT_CONFIRM_MS = 1500;
+export type InterruptGestureState = {
+    phase: 'ready';
+} | {
+    phase: 'armed';
+    armedAt: number;
+} | {
+    phase: 'stopping';
+};
+export interface InterruptGestureResult {
+    state: InterruptGestureState;
+    action: 'hint' | 'abort' | 'force-stop';
+}
+/** Advance using a monotonic clock; the caller owns the current run's lifetime. */
+export declare function advanceInterruptGesture(state: InterruptGestureState, now: number): InterruptGestureResult;
+/** Other input cancels confirmation, but cannot undo an already requested stop. */
+export declare function cancelInterruptConfirmation(state: InterruptGestureState): InterruptGestureState;

package/dist/input/interrupt-gesture.js

@@ -0,0 +1,19 @@
+/** Confirmation window for two independent decoded Escape events. */
+export const INTERRUPT_CONFIRM_MS = 1500;
+/** Advance using a monotonic clock; the caller owns the current run's lifetime. */
+export function advanceInterruptGesture(state, now) {
+    if (state.phase === 'stopping') {
+        return { state: { phase: 'ready' }, action: 'force-stop' };
+    }
+    if (state.phase === 'armed') {
+        const elapsed = now - state.armedAt;
+        if (elapsed >= 0 && elapsed <= INTERRUPT_CONFIRM_MS) {
+            return { state: { phase: 'stopping' }, action: 'abort' };
+        }
+    }
+    return { state: { phase: 'armed', armedAt: now }, action: 'hint' };
+}
+/** Other input cancels confirmation, but cannot undo an already requested stop. */
+export function cancelInterruptConfirmation(state) {
+    return state.phase === 'armed' ? { phase: 'ready' } : state;
+}

package/dist/input/keyboard-enhancement.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Keyboard-enhancement lifecycle (the Shift+Enter newline fix).
+ *
+ * WHY A LIFECYCLE MODULE AND NOT ANOTHER `screen.ts` MODE. The alternate
+ * screen is bound to fullscreen rendering; keyboard enhancement must run in
+ * every interactive session, inline included, because the composer is always
+ * there. It still follows the screen module's discipline: bytes are written
+ * ONLY for a TTY stdout, restore is idempotent, and the caller owns every
+ * decision -- this module is told the resolved capability and never derives
+ * one from config or environment.
+ *
+ * PLATFORM SPLIT, DECIDED BY BYTE-LEVEL PROBES (see
+ * docs/diagnoses/shift-enter-newline-dead-by-default):
+ *
+ * - win32: `?9001h` (win32-input-mode). It works through ConPTY on both
+ *   conhost and Windows Terminal; kitty `CSI > 1 u` is swallowed there (a
+ *   `CSI ? u` query never answers) and modifyOtherKeys is a no-op. Gated on
+ *   the SAME `vtInputSupported` measurement the mouse feature uses: on Node
+ *   < 22.17 / < 24.2 libuv never turns on `ENABLE_VIRTUAL_TERMINAL_INPUT`,
+ *   so the records cannot reach the process and the mode would be a lie.
+ * - everything else: kitty disambiguate (`CSI > 1 u`) plus
+ *   `modifyOtherKeys=2`. iTerm2 / kitty / ghostty / WezTerm / foot implement
+ *   at least one; terminals that implement neither ignore both bytes.
+ */
+export interface KeyboardEnhancementHandle {
+    /** Idempotent; writes the disable bytes exactly once. */
+    restore(): void;
+}
+/** The handle a gated-out session reads: nothing was pushed, nothing unwinds. */
+export declare const NOOP_KEYBOARD_ENHANCEMENT: KeyboardEnhancementHandle;
+/**
+ * Ask the terminal to report modified keys distinctly. The returned handle's
+ * `restore()` hands the keyboard back; wire it into the same convergence
+ * point the screen restore uses so every exit path unwinds both.
+ *
+ * `vtInputSupported` is the measurement `cli.tsx` already resolves for the
+ * mouse gate; on win32 it decides between `?9001h` and nothing at all.
+ */
+export declare function enableKeyboardEnhancement(stdout: NodeJS.WriteStream | undefined, opts: {
+    readonly platform: string;
+    readonly vtInputSupported: boolean;
+}): KeyboardEnhancementHandle;