@aragon-agent/tui 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `@aragon-agent/tui` are documented here.
+
+## 0.1.0
+
+### Added
+- **First release: the terminal runtime, split out of `@aragon-agent/cli`.** The Ink components,
+  terminal input protocols (keyboard, mouse, bracketed paste, stdin filtering), the scrollback
+  renderer and frame differ, every overlay, and the view model they draw from (`Entry`,
+  `ViewState`, the reducer, panel row models) now live in their own package, published in
+  lock-step with `@aragon-agent/core` and `@aragon-agent/cli`. Nothing a user can see or type
+  changed: the moved files are byte-identical apart from their import paths, which is checked by
+  a parity script before release.
+- **Subpath exports, no barrel.** Import modules by path, for example
+  `@aragon-agent/tui/ui/theme`. The package entry exports only `TUI_API_VERSION` and has no side
+  effects, because `ui/ink-runtime` must be evaluated before any other module that imports Ink.
+- **A logging port.** The package never reaches into the CLI's logger. Call
+  `setTuiLogger(...)` from `@aragon-agent/tui/model/logging/log-port`; until then logging is a no-op.
+- **`testing/` helpers** (`terminal-harness`, `mini-vt`, `vt-screen`, `render-at-width`,
+  `governance-fixtures`) shipped for the CLI's own tests. Test support, not a stable API.
+
+### Notes
+- `react` and `ink` are peer dependencies. Install them at the same range as the CLI so the
+  process has exactly one copy of each; two copies of React break hooks.
+- Subpaths are an internal contract between the three AragonAgent packages. Pin an exact version
+  if you depend on them directly.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AragonAgent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @aragon-agent/tui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The terminal runtime behind the `aragon` command: [Ink](https://github.com/vadimdemedes/ink)
+components, terminal input protocols, the scrollback renderer, and the view model they draw from.
+
+```
+@aragon-agent/core   engine: LLM adapters, streaming, tools, skills, sandbox
+        ▲
+@aragon-agent/tui    this package: terminal rendering, terminal input, view model
+        ▲
+@aragon-agent/cli    the `aragon` binary, the session container, config, commands, headless `exec`
+```
+
+Most people want [`@aragon-agent/cli`](../cli), which depends on this package. Install this one
+directly only to build your own terminal front end on the same components.
+
+## Using it
+
+There is deliberately **no barrel**. Import a module by its path:
+
+```ts
+import { renderTui } from '@aragon-agent/tui/ui/ink-runtime';
+import { viewReducer } from '@aragon-agent/tui/model/agent/reducer';
+```
+
+The package entry (`@aragon-agent/tui`) exports only `TUI_API_VERSION` and has no side effects.
+Ink caches its CI detection the first time it is imported, and `ui/ink-runtime` must be evaluated
+before any other module that imports Ink; a barrel would make that depend on import order.
+
+`react` and `ink` are **peer dependencies**. Install them yourself, at the same range this
+package declares, so your process holds exactly one copy of each.
+
+### Layout
+
+| Path | Contents |
+| --- | --- |
+| `ui/` | components, layout, scrollback, selection, frame differ, overlays, theme and glyphs |
+| `input/` | stdin filter and the keyboard / mouse / paste protocols |
+| `model/` | the view model and the pure domain helpers it needs (`agent/reducer`, `config/schema`, `todo/`, `team/`, `governance/`, `tools/patch`, `update/semver`, ...) |
+| `testing/` | terminal test harness and virtual-terminal helpers (test support, not a stable API) |
+
+`model/` holds more than view state: pure, I/O-free helpers such as the config schema, the patch
+parser and the semver comparison live there because the components need their values and types.
+Splitting them into a separate domain package is a possible later step.
+
+### Logging
+
+The package never imports the host's logger. Install one at startup:
+
+```ts
+import { setTuiLogger } from '@aragon-agent/tui/model/logging/log-port';
+
+setTuiLogger(myLogger); // { error, warn, info, debug, child }; default is a no-op
+```
+
+## Stability
+
+Subpaths are an **internal contract** between the three AragonAgent packages, released together
+and pinned exactly (`@aragon-agent/cli` depends on one exact `@aragon-agent/tui` version). Do not
+assume a subpath survives a minor release. The `testing/` helpers carry no stability promise.
+
+## Layering rules
+
+Enforced by the compiler and `npm run verify:layering`:
+
+1. This package never imports `@aragon-agent/cli`.
+2. `@aragon-agent/core` never imports this package or the CLI.
+3. The CLI reaches this package only through `@aragon-agent/tui/<subpath>`.
+4. Code here logs through the port, never through the CLI's logger.
+
+## Development
+
+```bash
+npm run build -w packages/tui        # tsc to dist/
+npm run dev   -w packages/tui        # tsc --watch (restart the CLI process to pick changes up)
+npm test      -w packages/tui
+npm run typecheck -w packages/tui
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@aragon-agent/tui` - the terminal runtime of AragonAgent.
+ *
+ * This entry deliberately exports ONE constant and has no side effects. It is NOT a barrel,
+ * and must not become one: Ink caches its CI detection the first time `ink` is imported,
+ * and `ui/ink-runtime` has to be evaluated before any other module that imports Ink. A
+ * barrel that re-exported the components would make that order depend on import sort order.
+ * Consumers import the module they need by its subpath instead, for example
+ * `@aragon-agent/tui/ui/ink-runtime` or `@aragon-agent/tui/ui/theme`.
+ */
+export declare const TUI_API_VERSION: 1;

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@aragon-agent/tui` - the terminal runtime of AragonAgent.
+ *
+ * This entry deliberately exports ONE constant and has no side effects. It is NOT a barrel,
+ * and must not become one: Ink caches its CI detection the first time `ink` is imported,
+ * and `ui/ink-runtime` has to be evaluated before any other module that imports Ink. A
+ * barrel that re-exported the components would make that order depend on import sort order.
+ * Consumers import the module they need by its subpath instead, for example
+ * `@aragon-agent/tui/ui/ink-runtime` or `@aragon-agent/tui/ui/theme`.
+ */
+export const TUI_API_VERSION = 1;

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

@@ -0,0 +1,71 @@
+/**
+ * Control-SEQUENCE removal for text that crosses a boundary where a terminal
+ * escape must never become content (paste-control-sequence-residue, fix A'-1).
+ *
+ * WHY A DELETE-THE-WHOLE-SEQUENCE RULE EXISTS. Deleting only the introducer
+ * byte turns an escape into visible text: `ESC [ 3 8 ; 2 m` loses its ESC and
+ * leaves `[38;2m`, which is a run of digits and semicolons somebody then reads
+ * on screen and sends to the model. The bytes were never content; the sequence
+ * has to go as a unit.
+ *
+ * WHY IT IS NOT `tools/terminal-output.ts`'s REGEXES MOVED HERE. Those four
+ * regexes answer "what does this look like" for a terminal row that is still
+ * being written, and they are fed text whose unfinished tail has ALREADY been
+ * cut off and parked in a carry by the caller (`sanitizeChunk`,
+ * `toDisplayRow`). Pasted text is one-shot: there is no next chunk, so a
+ * truncated sequence needs a rule of its own. Measured against the stream
+ * version of the same input, `ESC [ 3 8 ; 2 ; 1 8 ; 5 2 ; 8 6` followed by
+ * prose loses the first letter of the prose (`n`), and an unterminated OSC
+ * leaves its whole body behind.
+ *
+ * THE FOUR DECISIONS THIS MODULE ENCODES:
+ *
+ * 1. A sequence introduced by a real introducer byte (`0x1B`, `0x9B`, `0x9D`,
+ *    ...) is removed as a unit; bare text that merely LOOKS like the inside of
+ *    one (`[38;2;18;52;86m` typed or pasted without an ESC) is left exactly as
+ *    it is, character for character.
+ * 2. A string-type sequence (OSC / DCS / SOS / PM / APC) runs to BEL or ST, and
+ *    an unterminated one is removed UP TO THE END OF ITS LINE. It never crosses
+ *    `\n` and never guesses at a terminator: a truncated sequence is the most
+ *    common shape in a clipboard, and the only safe reading of it is "the rest
+ *    of this line was never text".
+ * 3. A truncated CSI loses its introducer and its parameter bytes and NOTHING
+ *    ELSE. `ESC [ 3 1 m` split mid-parameter is parameters, not prose, but the
+ *    byte after them is the user's own character and must survive.
+ * 4. A C1 CSI (`0x9B`) with no parameter byte at all is treated as the stray
+ *    control byte it is most likely to be rather than as a sequence, because a
+ *    lone `0x9B` followed by one letter is otherwise indistinguishable from a
+ *    non-UTF-8 file's stray byte followed by content -- and consuming that
+ *    letter would be the very data loss this module exists to prevent.
+ *
+ * Pure, ASCII-only, React-free, Ink-free, and TOTAL: it never throws and it
+ * never reorders or mangles the bytes it keeps. No new dependency.
+ */
+/**
+ * Remove every escape/control sequence, keeping all other bytes in order.
+ *
+ * KEEPS `\t`, `\n` AND `\r`: they are line structure, and `\t` inside pasted
+ * indentation is content the model is supposed to receive. Stray C0/C1 bytes
+ * (and DEL) are NOT this function's job -- they are removed by the caller that
+ * wants them gone, so one rule has one owner.
+ */
+export declare function stripControlSequences(text: string): string;
+/**
+ * True when `text` carries a sequence a KEYBOARD cannot physically produce.
+ *
+ * Used at the keystroke branch of the stdin filter: a single-line paste that
+ * carries ESC fails `classifyChunk`'s two rules (no line break, and
+ * `HAS_CONTROL_EXCEPT_TAB`) and would otherwise reach Ink as raw bytes --
+ * either typing `[38;2;18;52;86m` with a live ESC into the draft, or throwing
+ * an uncaught `TypeError` inside Ink's key parser.
+ *
+ * THREE THINGS MUST NOT MATCH, and the shapes below are why:
+ * - SGR mouse reports (`ESC [ < 0 ; 1 ; 2 m`) are stripped by `splitMouseEvents`
+ *   BEFORE this test, and `<` is not a parameter byte, so the SGR rule cannot
+ *   see them anyway.
+ * - Arrow / function / Home / End keys (`ESC [ A`, `ESC [ 1 ; 5 D`, `ESC [ 3 ~`,
+ *   `ESC [ Z`) never end in `m`.
+ * - `Alt`+letter (`ESC` followed by one character) has no introducer body, so
+ *   the string-type rule does not fire.
+ */
+export declare function hasPasteOnlySequence(text: string): boolean;

package/dist/input/control-sequences.js

@@ -0,0 +1,222 @@
+/**
+ * Control-SEQUENCE removal for text that crosses a boundary where a terminal
+ * escape must never become content (paste-control-sequence-residue, fix A'-1).
+ *
+ * WHY A DELETE-THE-WHOLE-SEQUENCE RULE EXISTS. Deleting only the introducer
+ * byte turns an escape into visible text: `ESC [ 3 8 ; 2 m` loses its ESC and
+ * leaves `[38;2m`, which is a run of digits and semicolons somebody then reads
+ * on screen and sends to the model. The bytes were never content; the sequence
+ * has to go as a unit.
+ *
+ * WHY IT IS NOT `tools/terminal-output.ts`'s REGEXES MOVED HERE. Those four
+ * regexes answer "what does this look like" for a terminal row that is still
+ * being written, and they are fed text whose unfinished tail has ALREADY been
+ * cut off and parked in a carry by the caller (`sanitizeChunk`,
+ * `toDisplayRow`). Pasted text is one-shot: there is no next chunk, so a
+ * truncated sequence needs a rule of its own. Measured against the stream
+ * version of the same input, `ESC [ 3 8 ; 2 ; 1 8 ; 5 2 ; 8 6` followed by
+ * prose loses the first letter of the prose (`n`), and an unterminated OSC
+ * leaves its whole body behind.
+ *
+ * THE FOUR DECISIONS THIS MODULE ENCODES:
+ *
+ * 1. A sequence introduced by a real introducer byte (`0x1B`, `0x9B`, `0x9D`,
+ *    ...) is removed as a unit; bare text that merely LOOKS like the inside of
+ *    one (`[38;2;18;52;86m` typed or pasted without an ESC) is left exactly as
+ *    it is, character for character.
+ * 2. A string-type sequence (OSC / DCS / SOS / PM / APC) runs to BEL or ST, and
+ *    an unterminated one is removed UP TO THE END OF ITS LINE. It never crosses
+ *    `\n` and never guesses at a terminator: a truncated sequence is the most
+ *    common shape in a clipboard, and the only safe reading of it is "the rest
+ *    of this line was never text".
+ * 3. A truncated CSI loses its introducer and its parameter bytes and NOTHING
+ *    ELSE. `ESC [ 3 1 m` split mid-parameter is parameters, not prose, but the
+ *    byte after them is the user's own character and must survive.
+ * 4. A C1 CSI (`0x9B`) with no parameter byte at all is treated as the stray
+ *    control byte it is most likely to be rather than as a sequence, because a
+ *    lone `0x9B` followed by one letter is otherwise indistinguishable from a
+ *    non-UTF-8 file's stray byte followed by content -- and consuming that
+ *    letter would be the very data loss this module exists to prevent.
+ *
+ * Pure, ASCII-only, React-free, Ink-free, and TOTAL: it never throws and it
+ * never reorders or mangles the bytes it keeps. No new dependency.
+ */
+/** ESC -- the introducer every terminal shares. */
+const ESC = 0x1b;
+/** LF. No rule in this module may consume it (decision 2). */
+const LF = 0x0a;
+/** BEL terminates an OSC. */
+const BEL = 0x07;
+/** `[` after ESC is CSI, and `\` after ESC is the two-byte ST. */
+const BRACKET = 0x5b;
+const BACKSLASH = 0x5c;
+/** The ASCII second byte of each string-type sequence (`ESC ]`, `ESC P`, ...). */
+const ESC_DCS = 0x50;
+const ESC_SOS = 0x58;
+const ESC_OSC = 0x5d;
+const ESC_PM = 0x5e;
+const ESC_APC = 0x5f;
+/** C1 introducers, as written by a source that is not UTF-8 clean. */
+const C1_CSI = 0x9b;
+const C1_ST = 0x9c;
+const C1_OSC = 0x9d;
+const C1_DCS = 0x90;
+const C1_SOS = 0x98;
+const C1_PM = 0x9e;
+const C1_APC = 0x9f;
+/** Every byte that can START a sequence this module removes. */
+const ANY_INTRODUCER = /[\u001b\u0090\u0098\u009b\u009d\u009e\u009f]/;
+/**
+ * `CSI ... m` (SGR), in both encodings: `ESC [ digits ; m` and the single-byte
+ * C1 form `0x9B digits ; m`. NO KEY PRESS PRODUCES ONE, which is what makes it
+ * usable as the discriminator for an unframed paste in `stdin-filter.ts`.
+ */
+const SGR_SEQUENCE = /\u001b\[[0-9;]*m|\u009b[0-9;]*m/;
+/**
+ * A string-type introducer followed by at least one body byte. An `Alt`+key
+ * press is exactly two bytes, so "introducer plus a body" is already outside
+ * what a keyboard can emit.
+ */
+const STRING_SEQUENCE = /(?:\u001b[\u0050\u0058\u005d\u005e\u005f]|[\u0090\u0098\u009d\u009e\u009f])[\s\S]/;
+/** CSI final byte: `@` through `~`. */
+function isFinalByte(code) {
+    return code >= 0x40 && code <= 0x7e;
+}
+/** CSI parameter byte: `0` through `?`. */
+function isParamByte(code) {
+    return code >= 0x30 && code <= 0x3f;
+}
+/**
+ * CSI intermediate byte: `!` through `/`.
+ *
+ * SPACE (`0x20`) IS DELIBERATELY EXCLUDED (decision 3). The standard allows it,
+ * but a pasted sequence cut mid-parameter is followed by ` ` and then prose,
+ * and the first letter of that prose is a legal final byte -- so honouring the
+ * space would silently eat it. `CSI Ps SP q` (cursor style) is the only shape
+ * that gets worse, and no child process writes that to its stdout.
+ */
+function isIntermediateByte(code) {
+    return code >= 0x21 && code <= 0x2f;
+}
+/** True for the C1 introducers that open a string, not a CSI. */
+function isC1StringIntroducer(code) {
+    return code === C1_OSC || code === C1_DCS || code === C1_SOS || code === C1_PM || code === C1_APC;
+}
+/**
+ * End of the string-type sequence whose body starts at `from`.
+ *
+ * Stops AT the line break rather than past it, and reports "consumed to here"
+ * for a body that never terminates (decision 2).
+ */
+function stringEnd(text, from) {
+    let i = from;
+    while (i < text.length) {
+        const code = text.charCodeAt(i);
+        if (code === BEL || code === C1_ST)
+            return i + 1;
+        if (code === LF)
+            return i;
+        if (code === ESC && text.charCodeAt(i + 1) === BACKSLASH)
+            return i + 2;
+        i += 1;
+    }
+    return i;
+}
+/**
+ * End of the CSI whose parameter run starts at `from`.
+ *
+ * `requireParams` implements decision 4: with no parameter byte at all, a C1
+ * CSI is only the introducer byte, and its "final byte" is content.
+ */
+function csiEnd(text, from, requireParams) {
+    let i = from;
+    let sawParams = false;
+    while (i < text.length && isParamByte(text.charCodeAt(i))) {
+        sawParams = true;
+        i += 1;
+    }
+    if (requireParams && !sawParams)
+        return from;
+    while (i < text.length && isIntermediateByte(text.charCodeAt(i)))
+        i += 1;
+    if (i < text.length && isFinalByte(text.charCodeAt(i)))
+        return i + 1;
+    return i;
+}
+/** End of the sequence starting with ESC at `index` (decision 1 / 3). */
+function escapeEnd(text, index) {
+    if (index + 1 >= text.length)
+        return index + 1;
+    const next = text.charCodeAt(index + 1);
+    if (next === BRACKET)
+        return csiEnd(text, index + 2, false);
+    if (next === ESC_OSC || next === ESC_DCS || next === ESC_SOS || next === ESC_PM
+        || next === ESC_APC) {
+        return stringEnd(text, index + 2);
+    }
+    if (next === LF)
+        return index + 1;
+    return index + 2;
+}
+/**
+ * End of the sequence starting at `index`, or `-1` when no sequence starts
+ * there.
+ */
+function sequenceEnd(text, index) {
+    const code = text.charCodeAt(index);
+    if (code === ESC)
+        return escapeEnd(text, index);
+    if (code === C1_CSI)
+        return csiEnd(text, index + 1, true);
+    if (isC1StringIntroducer(code)) {
+        return index + 1 >= text.length ? index + 1 : stringEnd(text, index + 1);
+    }
+    return -1;
+}
+/**
+ * Remove every escape/control sequence, keeping all other bytes in order.
+ *
+ * KEEPS `\t`, `\n` AND `\r`: they are line structure, and `\t` inside pasted
+ * indentation is content the model is supposed to receive. Stray C0/C1 bytes
+ * (and DEL) are NOT this function's job -- they are removed by the caller that
+ * wants them gone, so one rule has one owner.
+ */
+export function stripControlSequences(text) {
+    if (!ANY_INTRODUCER.test(text))
+        return text;
+    let out = '';
+    let kept = 0;
+    let i = 0;
+    while (i < text.length) {
+        const end = sequenceEnd(text, i);
+        if (end === -1) {
+            i += 1;
+            continue;
+        }
+        out += text.slice(kept, i);
+        i = end;
+        kept = end;
+    }
+    return kept === 0 ? text : out + text.slice(kept);
+}
+/**
+ * True when `text` carries a sequence a KEYBOARD cannot physically produce.
+ *
+ * Used at the keystroke branch of the stdin filter: a single-line paste that
+ * carries ESC fails `classifyChunk`'s two rules (no line break, and
+ * `HAS_CONTROL_EXCEPT_TAB`) and would otherwise reach Ink as raw bytes --
+ * either typing `[38;2;18;52;86m` with a live ESC into the draft, or throwing
+ * an uncaught `TypeError` inside Ink's key parser.
+ *
+ * THREE THINGS MUST NOT MATCH, and the shapes below are why:
+ * - SGR mouse reports (`ESC [ < 0 ; 1 ; 2 m`) are stripped by `splitMouseEvents`
+ *   BEFORE this test, and `<` is not a parameter byte, so the SGR rule cannot
+ *   see them anyway.
+ * - Arrow / function / Home / End keys (`ESC [ A`, `ESC [ 1 ; 5 D`, `ESC [ 3 ~`,
+ *   `ESC [ Z`) never end in `m`.
+ * - `Alt`+letter (`ESC` followed by one character) has no introducer body, so
+ *   the string-type rule does not fire.
+ */
+export function hasPasteOnlySequence(text) {
+    return SGR_SEQUENCE.test(text) || STRING_SEQUENCE.test(text);
+}

package/dist/input/csiu-keys.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+/** Enable / disable the two CSI-u report modes (posix side). */
+export declare const CSI_U_ENABLE = "\u001B[>1u\u001B[>4;2m";
+export declare const CSI_U_DISABLE = "\u001B[<u\u001B[>4m";
+export interface CsiUKey {
+    /** The full original sequence, for pass-through. */
+    readonly seq: string;
+    /** First parameter's primary number (the key's codepoint). */
+    readonly code: number;
+    /** Optional `:alternate` sub-parameters of the key field (kitty/mok). */
+    readonly alternates: readonly number[];
+    /** Modifier parameter minus one (bit 1 shift, 2 alt, 4 ctrl), or 0. */
+    readonly mods: number;
+}
+export type CsiUSegment = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'key';
+    key: CsiUKey;
+};
+/**
+ * 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 declare function splitCsiUKeys(text: string): CsiUSegment[];
+/**
+ * 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 declare function translateCsiUKey(key: CsiUKey): string;
+/**
+ * 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 declare function trailingCsiUPrefixLength(text: string): number;