@tuidom/core 0.1.0

package/dist/input/keyInputParser.js

@@ -0,0 +1,249 @@
+import { convertTokenToKeyPressEvent } from "./convertToken.js";
+import { createKeyPressEvent } from "./keyEvent.js";
+import { parseCSI, parseOSC, tokenize } from "./tokenize.js";
+/**
+ * Index where an *incomplete* trailing escape sequence begins, or -1 if `data`
+ * ends on a clean token boundary.
+ *
+ * Over SSH/tmux (and any slow link) a single keypress can be split across two
+ * stdin reads — e.g. Ctrl+Shift+P (`\x1b[112;6u`) arriving as `\x1b[112;6` then
+ * `u`. Without this, the first chunk is mis-tokenized into a lone Escape plus
+ * literal characters and the keybinding silently fails; the user has to press
+ * again. We detect the dangling tail so KeyInputParser can hold it and prepend
+ * it to the next chunk.
+ *
+ * Only a sequence that starts at the *last* ESC and runs to the end can be
+ * incomplete — anything before it is already followed by more bytes.
+ */
+function incompleteTailStart(data) {
+    const esc = data.lastIndexOf("\x1b");
+    if (esc === -1)
+        return -1;
+    const next = data.charCodeAt(esc + 1);
+    // Lone trailing ESC: ambiguous (Escape key vs. start of a split sequence) — buffer it.
+    if (Number.isNaN(next))
+        return esc;
+    // CSI / OSC reuse the real parsers, so completeness exactly matches tokenize().
+    if (next === 0x5b)
+        return parseCSI(data, esc) === null ? esc : -1; // ESC [
+    if (next === 0x5d)
+        return parseOSC(data, esc) === null ? esc : -1; // ESC ]
+    if (next === 0x4f)
+        return esc + 2 >= data.length ? esc : -1; // ESC O (SS3) needs its final letter
+    // ESC + printable / control / special is complete once the second byte is present (it is).
+    return -1;
+}
+/**
+ * Bracketed paste markers (DEC mode ?2004). The terminal wraps clipboard pastes
+ * as `ESC[200~ <literal text> ESC[201~`, letting us insert the whole block as one
+ * text edit instead of replaying it byte-by-byte through key parsing (which would
+ * turn newlines into Enter keypresses and run special characters as shortcuts).
+ */
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+/**
+ * If `s` ends with a non-empty proper prefix of `marker` (a marker split across
+ * stdin reads), return the index where that partial tail begins; otherwise `s.length`.
+ * Used while accumulating paste content so a split `ESC[201~` end marker is held back
+ * rather than swallowed into the pasted text.
+ */
+function partialMarkerTailStart(s, marker) {
+    const max = Math.min(s.length, marker.length - 1);
+    for (let len = max; len > 0; len--) {
+        if (s.endsWith(marker.slice(0, len)))
+            return s.length - len;
+    }
+    return s.length;
+}
+/** Normalize pasted line endings: CRLF and lone CR both become LF. */
+function normalizeNewlines(text) {
+    return text.replace(/\r\n?/g, "\n");
+}
+/**
+ * Set of key values representing modifier keys.
+ * These follow the browser model: keydown/keyup only, no keypress synthesized.
+ */
+const modifierKeyValues = new Set([
+    "Shift",
+    "Control",
+    "Alt",
+    "Meta",
+    "Hyper",
+    "Super",
+    "AltGraph",
+    "ISO_Level5_Shift",
+    "CapsLock",
+    "NumLock",
+    "ScrollLock",
+]);
+function emptyStreams() {
+    return { keys: [], mouse: [], osc: [], deviceReports: [], paste: [] };
+}
+export class KeyInputParser {
+    pressedKeys = new Set();
+    /** Tail of the previous chunk that was cut mid-escape-sequence; "" when none. */
+    pending = "";
+    /** True while accumulating bracketed-paste content (between ESC[200~ and ESC[201~). */
+    pasting = false;
+    /** Pasted text accumulated so far, awaiting the ESC[201~ end marker. */
+    pasteBuffer = "";
+    /**
+     * Parse a chunk of raw terminal input into browser-like keyboard events.
+     */
+    parse(data) {
+        return this.ingest(data).keys;
+    }
+    /**
+     * Parse raw terminal input, returning both keyboard events and mouse tokens.
+     */
+    parseWithMouse(data) {
+        return this.ingest(data);
+    }
+    /** True when a partial escape sequence is buffered, awaiting the rest of its bytes. */
+    hasPending() {
+        return this.pending !== "";
+    }
+    /**
+     * Force-process any buffered partial sequence as-is (a lone ESC becomes the
+     * Escape key). Callers use a short timeout so a real Escape keypress isn't
+     * held hostage waiting for a continuation that never comes.
+     *
+     * While a paste is in flight (ESC[200~ seen, ESC[201~ not yet), this is a no-op:
+     * the held tail is a split end marker, not a stuck escape — keep accumulating so
+     * the paste isn't corrupted or truncated.
+     */
+    flush() {
+        const streams = emptyStreams();
+        if (this.pasting)
+            return streams;
+        const tail = this.pending;
+        this.pending = "";
+        if (tail !== "")
+            this.tokenizeInto(tail, streams);
+        return streams;
+    }
+    /**
+     * Reassemble the stream across reads, splitting out bracketed-paste blocks so
+     * their literal text bypasses key tokenization entirely. Normal segments keep the
+     * existing behavior: prepend any buffered tail, then hold back a fresh incomplete
+     * tail so an escape sequence cut across stdin reads is reassembled next chunk.
+     */
+    ingest(data) {
+        let combined = this.pending + data;
+        this.pending = "";
+        const streams = emptyStreams();
+        while (combined !== "") {
+            if (this.pasting) {
+                const endIdx = combined.indexOf(PASTE_END);
+                if (endIdx === -1) {
+                    // No end marker yet: accumulate, but hold back a possible split ESC[201~.
+                    const tailStart = partialMarkerTailStart(combined, PASTE_END);
+                    this.pasteBuffer += combined.slice(0, tailStart);
+                    this.pending = combined.slice(tailStart);
+                    return streams;
+                }
+                this.pasteBuffer += combined.slice(0, endIdx);
+                const text = normalizeNewlines(this.pasteBuffer);
+                if (text !== "")
+                    streams.paste.push(text);
+                this.pasteBuffer = "";
+                this.pasting = false;
+                combined = combined.slice(endIdx + PASTE_END.length);
+                continue;
+            }
+            const startIdx = combined.indexOf(PASTE_START);
+            if (startIdx === -1) {
+                // No paste start in view. A trailing partial ESC[200~ is an incomplete CSI,
+                // so incompleteTailStart already holds it back like any split sequence.
+                const cut = incompleteTailStart(combined);
+                if (cut === -1) {
+                    this.tokenizeInto(combined, streams);
+                }
+                else {
+                    this.tokenizeInto(combined.slice(0, cut), streams);
+                    this.pending = combined.slice(cut);
+                }
+                return streams;
+            }
+            // Bytes before the marker are complete (a full marker follows them).
+            this.tokenizeInto(combined.slice(0, startIdx), streams);
+            this.pasting = true;
+            combined = combined.slice(startIdx + PASTE_START.length);
+        }
+        return streams;
+    }
+    tokenizeInto(data, streams) {
+        if (data === "")
+            return;
+        const tokens = tokenize(data);
+        const keyEvents = [];
+        for (const token of tokens) {
+            if (token.kind === "mouse") {
+                streams.mouse.push(token);
+            }
+            else if (token.kind === "osc") {
+                streams.osc.push(token);
+            }
+            else if (token.kind === "device-report") {
+                streams.deviceReports.push(token);
+            }
+            else if (token.kind === "unknown-csi") {
+                // Complete but unrecognized CSI sequence — drop it (never type it as text).
+            }
+            else {
+                keyEvents.push(convertTokenToKeyPressEvent(token));
+            }
+        }
+        for (const event of this.processKeyEvents(keyEvents)) {
+            streams.keys.push(event);
+        }
+    }
+    processKeyEvents(rawEvents) {
+        const result = [];
+        for (const event of rawEvents) {
+            if (event.type === "keydown") {
+                this.pressedKeys.add(event.code);
+                result.push(event);
+                if (!modifierKeyValues.has(event.key)) {
+                    result.push(createKeyPressEvent(event.key, event.raw, {
+                        type: "keypress",
+                        code: event.code,
+                        ctrlKey: event.ctrlKey,
+                        shiftKey: event.shiftKey,
+                        altKey: event.altKey,
+                        metaKey: event.metaKey,
+                    }));
+                }
+                /* v8 ignore start -- unreachable: no token converter emits a synthetic "keypress" (processKeyEvents only ever sees keydown/keyup), so the keypress branch never runs and the keyup else-if's false path (the closed-union fall-through) is also dead */
+            }
+            else if (event.type === "keypress") {
+                this.pressedKeys.add(event.code);
+                result.push(event);
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            }
+            else if (event.type === "keyup") {
+                /* v8 ignore stop */
+                if (!modifierKeyValues.has(event.key) && !this.pressedKeys.has(event.code)) {
+                    const synth = {
+                        type: "keypress",
+                        code: event.code,
+                        ctrlKey: event.ctrlKey,
+                        shiftKey: event.shiftKey,
+                        altKey: event.altKey,
+                        metaKey: event.metaKey,
+                    };
+                    result.push(createKeyPressEvent(event.key, event.raw, { ...synth, type: "keydown" }));
+                    result.push(createKeyPressEvent(event.key, event.raw, synth));
+                }
+                this.pressedKeys.delete(event.code);
+                result.push(event);
+            }
+            else {
+                /* v8 ignore start -- unreachable: event.type is a closed union (keydown|keypress|keyup), all handled above */
+                result.push(event);
+                /* v8 ignore stop */
+            }
+        }
+        return result;
+    }
+}

package/dist/input/mouseTracking.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Mouse tracking escape sequences for xterm-compatible terminals.
+ *
+ * Modes:
+ * - 1000: Normal tracking — reports button press and release
+ * - 1002: Button-event tracking — also reports motion while a button is held (drag)
+ * - 1003: Any-event tracking — reports all motion events (even without button held)
+ * - 1006: SGR extended mode — uses CSI < Cb;Cx;Cy M/m format (no coordinate limits)
+ *
+ * SGR mode (1006) should always be enabled alongside a tracking mode,
+ * because the legacy X10 format limits coordinates to 223 and doesn't distinguish release buttons.
+ *
+ * Reference: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking
+ */
+/** Enable any-event tracking (press + release + all motion) with SGR extended coordinates */
+export declare const MOUSE_TRACKING_ALL_ENABLE = "\u001B[?1003h\u001B[?1006h";
+/** Disable all mouse tracking modes */
+export declare const MOUSE_TRACKING_DISABLE = "\u001B[?1000l\u001B[?1002l\u001B[?1003l\u001B[?1006l";

package/dist/input/mouseTracking.js

@@ -0,0 +1,18 @@
+/**
+ * Mouse tracking escape sequences for xterm-compatible terminals.
+ *
+ * Modes:
+ * - 1000: Normal tracking — reports button press and release
+ * - 1002: Button-event tracking — also reports motion while a button is held (drag)
+ * - 1003: Any-event tracking — reports all motion events (even without button held)
+ * - 1006: SGR extended mode — uses CSI < Cb;Cx;Cy M/m format (no coordinate limits)
+ *
+ * SGR mode (1006) should always be enabled alongside a tracking mode,
+ * because the legacy X10 format limits coordinates to 223 and doesn't distinguish release buttons.
+ *
+ * Reference: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking
+ */
+/** Enable any-event tracking (press + release + all motion) with SGR extended coordinates */
+export const MOUSE_TRACKING_ALL_ENABLE = "\x1b[?1003h\x1b[?1006h";
+/** Disable all mouse tracking modes */
+export const MOUSE_TRACKING_DISABLE = "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l";

package/dist/input/parseInput.d.ts

@@ -0,0 +1,13 @@
+import type { KeyPressEvent } from "./keyEvent.js";
+/**
+ * Parse raw terminal input into KeyPressEvent[].
+ *
+ * Composes tokenize() (protocol-specific token extraction) with
+ * convertTokenToKeyPressEvent() (unified KeyPressEvent mapping).
+ *
+ * Mouse tokens are filtered out — they are handled separately
+ * at the tokenize layer (see MouseToken in RawTerminalToken).
+ *
+ * Pure function, no side effects.
+ */
+export declare function parseInput(data: string): KeyPressEvent[];

package/dist/input/parseInput.js

@@ -0,0 +1,17 @@
+import { convertTokenToKeyPressEvent } from "./convertToken.js";
+import { tokenize } from "./tokenize.js";
+/**
+ * Parse raw terminal input into KeyPressEvent[].
+ *
+ * Composes tokenize() (protocol-specific token extraction) with
+ * convertTokenToKeyPressEvent() (unified KeyPressEvent mapping).
+ *
+ * Mouse tokens are filtered out — they are handled separately
+ * at the tokenize layer (see MouseToken in RawTerminalToken).
+ *
+ * Pure function, no side effects.
+ */
+export function parseInput(data) {
+    const keyTokens = tokenize(data).filter((t) => t.kind !== "mouse" && t.kind !== "osc" && t.kind !== "device-report" && t.kind !== "unknown-csi");
+    return keyTokens.map(convertTokenToKeyPressEvent);
+}

package/dist/input/rawTerminalToken.d.ts

@@ -0,0 +1,142 @@
+export interface CsiUToken {
+    readonly kind: "csi-u";
+    readonly codepoint: number;
+    readonly shiftedKey: number | undefined;
+    readonly baseLayoutKey: number | undefined;
+    readonly key: string;
+    readonly code: string;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly metaKey: boolean;
+    /** 0 = not specified, 1 = press, 2 = repeat, 3 = release */
+    readonly eventType: number;
+    readonly raw: string;
+}
+export interface PuaToken {
+    readonly kind: "pua";
+    readonly codepoint: number;
+    readonly key: string;
+    readonly code: string;
+    readonly raw: string;
+}
+export interface CsiLetterToken {
+    readonly kind: "csi-letter";
+    readonly finalByte: string;
+    readonly key: string;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly metaKey: boolean;
+    /** 0 = not specified (legacy), 1 = press, 2 = repeat, 3 = release */
+    readonly eventType: number;
+    readonly raw: string;
+}
+export interface CsiTildeToken {
+    readonly kind: "csi-tilde";
+    readonly number: number;
+    readonly key: string;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly metaKey: boolean;
+    /** 0 = not specified (legacy), 1 = press, 2 = repeat, 3 = release */
+    readonly eventType: number;
+    readonly raw: string;
+}
+export interface Ss3Token {
+    readonly kind: "ss3";
+    readonly finalByte: string;
+    readonly key: string;
+    readonly raw: string;
+}
+export interface EscCharToken {
+    readonly kind: "esc-char";
+    readonly char: string;
+    readonly charCode: number;
+    readonly raw: string;
+}
+export interface EscControlToken {
+    readonly kind: "esc-control";
+    readonly letter: string;
+    readonly raw: string;
+}
+export interface EscSpecialToken {
+    readonly kind: "esc-special";
+    readonly key: "Enter" | "Backspace";
+    readonly raw: string;
+}
+export interface StandaloneEscToken {
+    readonly kind: "standalone-esc";
+    readonly raw: string;
+}
+export interface CharToken {
+    readonly kind: "char";
+    readonly char: string;
+    readonly codepoint: number;
+    readonly raw: string;
+}
+export interface SpecialKeyToken {
+    readonly kind: "special-key";
+    readonly key: "Enter" | "Tab" | "Backspace";
+    readonly raw: string;
+}
+export interface CtrlCharToken {
+    readonly kind: "ctrl-char";
+    readonly letter: string;
+    readonly raw: string;
+}
+export interface UnknownByteToken {
+    readonly kind: "unknown-byte";
+    readonly byte: number;
+    readonly raw: string;
+}
+/**
+ * A *complete* but unrecognized CSI sequence (ESC `[` … final byte in 0x40–0x7e that
+ * matched no key/mouse/device-report handler). Carries the full raw bytes so the whole
+ * sequence is consumed and dropped rather than leaking its `[…u`-style bytes into the
+ * buffer as literal characters. Distinct from a `null` parse, which means *incomplete*
+ * (a sequence cut across stdin reads, which must be buffered until the rest arrives).
+ */
+export interface UnknownCsiToken {
+    readonly kind: "unknown-csi";
+    readonly raw: string;
+}
+export interface OscToken {
+    readonly kind: "osc";
+    /** OSC command number, e.g. 52 for clipboard */
+    readonly code: number;
+    /** Everything after the first semicolon, up to the terminator */
+    readonly data: string;
+    readonly raw: string;
+}
+/**
+ * A private-mode CSI response to one of our capability probes — NOT a key event.
+ *  - "kitty-flags": reply to the Kitty keyboard-protocol query `CSI ? u` → `CSI ? <flags> u`.
+ *  - "da1":         reply to Primary Device Attributes `CSI c` → `CSI ? <attrs> c`.
+ * These begin with the private marker `?`, which never appears in a real key event.
+ */
+export interface DeviceReportToken {
+    readonly kind: "device-report";
+    readonly report: "kitty-flags" | "da1";
+    /** Raw parameter bytes including the leading `?` (e.g. "?15" or "?62;1;6"). */
+    readonly params: string;
+    readonly raw: string;
+}
+export type MouseButton = "left" | "middle" | "right" | "none";
+export type MouseAction = "press" | "release" | "move" | "scroll-up" | "scroll-down" | "scroll-left" | "scroll-right";
+export interface MouseToken {
+    readonly kind: "mouse";
+    readonly button: MouseButton;
+    readonly action: MouseAction;
+    /** 1-based column */
+    readonly x: number;
+    /** 1-based row */
+    readonly y: number;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly raw: string;
+}
+export type RawTerminalToken = CsiUToken | PuaToken | CsiLetterToken | CsiTildeToken | Ss3Token | EscCharToken | EscControlToken | EscSpecialToken | StandaloneEscToken | CharToken | SpecialKeyToken | CtrlCharToken | UnknownByteToken | UnknownCsiToken | MouseToken | OscToken | DeviceReportToken;
+export type RawKeyToken = CsiUToken | PuaToken | CsiLetterToken | CsiTildeToken | Ss3Token | EscCharToken | EscControlToken | EscSpecialToken | StandaloneEscToken | CharToken | SpecialKeyToken | CtrlCharToken | UnknownByteToken;

package/dist/input/rawTerminalToken.js

@@ -0,0 +1,2 @@
+// ─── Kitty protocol tokens ───
+export {};

package/dist/input/serializeKey.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Convert a human-readable key name (DSL) to the raw terminal escape sequence.
+ * Inverse of parseInput — used in tests for the DSL:
+ *   serializeKey('a')              → 'a'
+ *   serializeKey('Ctrl+C')         → '\x03'
+ *   serializeKey('Enter')          → '\r'
+ *   serializeKey('ArrowUp')        → '\x1b[A'
+ *   serializeKey('Ctrl+ArrowUp')   → '\x1b[1;5A'
+ *   serializeKey('F5')             → '\x1b[15~'
+ *   serializeKey('Alt+a')          → '\x1ba'
+ *
+ * Supports modifier prefixes: Ctrl+, Shift+, Alt+, Meta+ (combinable).
+ */
+export declare function serializeKey(name: string): string;

package/dist/input/serializeKey.js

@@ -0,0 +1,179 @@
+/**
+ * Convert a human-readable key name (DSL) to the raw terminal escape sequence.
+ * Inverse of parseInput — used in tests for the DSL:
+ *   serializeKey('a')              → 'a'
+ *   serializeKey('Ctrl+C')         → '\x03'
+ *   serializeKey('Enter')          → '\r'
+ *   serializeKey('ArrowUp')        → '\x1b[A'
+ *   serializeKey('Ctrl+ArrowUp')   → '\x1b[1;5A'
+ *   serializeKey('F5')             → '\x1b[15~'
+ *   serializeKey('Alt+a')          → '\x1ba'
+ *
+ * Supports modifier prefixes: Ctrl+, Shift+, Alt+, Meta+ (combinable).
+ */
+/** Simple special keys (no modifiers, no CSI) */
+const simpleSpecialKeys = {
+    Enter: "\x0d",
+    Tab: "\x09",
+    Backspace: "\x7f",
+    Escape: "\x1b",
+    Space: " ",
+};
+/** Keys using CSI <letter> format (also used for Ctrl/Shift/Alt variants) */
+const csiLetterKeys = {
+    ArrowUp: "A",
+    ArrowDown: "B",
+    ArrowRight: "C",
+    ArrowLeft: "D",
+    Home: "H",
+    End: "F",
+    F1: "P",
+    F2: "Q",
+    F3: "R",
+    F4: "S",
+};
+/** Keys using SS3 format (no-modifier variant of F1–F4 and cursor keys in app mode) */
+const ss3Keys = {
+    F1: "P",
+    F2: "Q",
+    F3: "R",
+    F4: "S",
+};
+/** Keys using CSI <num>~ format */
+const csiTildeKeys = {
+    Insert: 2,
+    Delete: 3,
+    PageUp: 5,
+    PageDown: 6,
+    F5: 15,
+    F6: 17,
+    F7: 18,
+    F8: 19,
+    F9: 20,
+    F10: 21,
+    F11: 23,
+    F12: 24,
+};
+/** Клавиши, чей Ctrl-вариант терминал шлёт кодами 0x1c–0x1f (зеркало `tokenize`). */
+const ctrlSymbolCodes = {
+    "\\": 0x1c,
+    "]": 0x1d,
+    "6": 0x1e,
+    "/": 0x1f,
+};
+function encodeModifier(ctrl, shift, alt, meta) {
+    let mod = 1;
+    if (shift)
+        mod += 1;
+    if (alt)
+        mod += 2;
+    if (ctrl)
+        mod += 4;
+    if (meta)
+        mod += 8;
+    return mod;
+}
+export function serializeKey(name) {
+    // Parse modifier prefixes: "Ctrl+Shift+ArrowUp" → modifiers + "ArrowUp"
+    let ctrl = false;
+    let shift = false;
+    let alt = false;
+    let meta = false;
+    let remaining = name;
+    const modPattern = /^(Ctrl|Shift|Alt|Meta)\+/;
+    let match = modPattern.exec(remaining);
+    while (match) {
+        const mod = match[1];
+        if (mod === "Ctrl")
+            ctrl = true;
+        else if (mod === "Shift")
+            shift = true;
+        /* v8 ignore start -- the modifier regex only ever captures Ctrl|Shift|Alt|Meta, so the final "none matched" fall-through (no else clause) is unreachable; v8 attributes that phantom branch to these chained else-ifs */ else if (mod === "Alt")
+            alt = true;
+        else if (mod === "Meta")
+            meta = true;
+        /* v8 ignore stop */
+        remaining = remaining.slice(match[0].length);
+        match = modPattern.exec(remaining);
+    }
+    const hasModifiers = ctrl || shift || alt || meta;
+    // Simple special keys without modifiers
+    if (!hasModifiers && remaining in simpleSpecialKeys) {
+        return simpleSpecialKeys[remaining];
+    }
+    // Shift+Tab → CSI Z (reverse tab / backtab)
+    if (shift && !ctrl && !alt && !meta && remaining === "Tab") {
+        return "\x1b[Z";
+    }
+    // Tab with modifiers in Kitty CSI-u form: CSI 9;{mod}:1u
+    if (remaining === "Tab" && hasModifiers) {
+        const mod = encodeModifier(ctrl, shift, alt, meta);
+        return `\x1b[9;${mod.toString()}:1u`;
+    }
+    // Enter with modifiers in Kitty CSI-u form: CSI 13;{mod}u (Ctrl+Enter = commit).
+    if (remaining === "Enter" && hasModifiers) {
+        const mod = encodeModifier(ctrl, shift, alt, meta);
+        return `\x1b[13;${mod.toString()}u`;
+    }
+    // Ctrl+Space → NUL: именно так его шлёт терминал (см. tokenize.ts, 0x00).
+    if (ctrl && !shift && !alt && !meta && remaining === "Space") {
+        return "\x00";
+    }
+    // Backspace с модификаторами — CSI 127;{mod}u (форма kitty). Легаси-байт 0x08
+    // здесь не годится: он неотличим от Ctrl+H, и бинд `ctrl+backspace` по нему
+    // не сматчится — ровно поэтому Ctrl+Backspace и не работал.
+    if (remaining === "Backspace" && hasModifiers) {
+        const mod = encodeModifier(ctrl, shift, alt, meta);
+        return `\x1b[127;${mod.toString()}u`;
+    }
+    // Ctrl+letter → control character (0x01–0x1a)
+    if (ctrl && !shift && !alt && !meta && remaining.length === 1 && /[a-zA-Z]/.test(remaining)) {
+        const code = remaining.toUpperCase().charCodeAt(0) - 0x40;
+        return String.fromCharCode(code);
+    }
+    // Ctrl+\ ] 6 / → control-коды 0x1c–0x1f. Парно с разбором в `tokenize`:
+    // это единственные не-буквенные комбинации, которые терминал вообще умеет
+    // передать без расширенного протокола.
+    if (ctrl && !shift && !alt && !meta && remaining in ctrlSymbolCodes) {
+        return String.fromCharCode(ctrlSymbolCodes[remaining]);
+    }
+    // Alt+single character → ESC prefix
+    if (alt && !ctrl && !shift && !meta && remaining.length === 1) {
+        return `\x1b${remaining}`;
+    }
+    // CSI letter keys (cursor keys, F1–F4)
+    if (remaining in csiLetterKeys) {
+        const letter = csiLetterKeys[remaining];
+        if (!hasModifiers) {
+            // F1–F4 without modifiers use SS3 format
+            if (remaining in ss3Keys) {
+                return `\x1bO${ss3Keys[remaining]}`;
+            }
+            return `\x1b[${letter}`;
+        }
+        const mod = encodeModifier(ctrl, shift, alt, meta);
+        return `\x1b[1;${mod.toString()}${letter}`;
+    }
+    // Kitty functional keys without legacy escape form (CSI-u codepoint)
+    if (remaining === "ContextMenu") {
+        if (!hasModifiers) {
+            return "\x1b[57363u";
+        }
+        const mod = encodeModifier(ctrl, shift, alt, meta);
+        return `\x1b[57363;${mod.toString()}u`;
+    }
+    // CSI tilde keys (Insert, Delete, PageUp, PageDown, F5–F12)
+    if (remaining in csiTildeKeys) {
+        const num = csiTildeKeys[remaining];
+        if (!hasModifiers) {
+            return `\x1b[${num.toString()}~`;
+        }
+        const mod = encodeModifier(ctrl, shift, alt, meta);
+        return `\x1b[${num.toString()};${mod.toString()}~`;
+    }
+    // Single printable character (no modifiers)
+    if (!hasModifiers && remaining.length === 1) {
+        return remaining;
+    }
+    throw new Error(`serializeKey: unknown key name "${name}". Add it to the mapping.`);
+}