@mariozechner/pi-tui 0.32.3 → 0.34.0

package/dist/keys.js

@@ -1,73 +1,75 @@
 /**
- * Kitty keyboard protocol key sequence helpers.
- *
- * The Kitty keyboard protocol sends enhanced escape sequences in the format:
- *   \x1b[<codepoint>;<modifier>u
- *
- * Modifier bits (before adding 1 for transmission):
- *   - Shift: 1 (value 2)
- *   - Alt: 2 (value 3)
- *   - Ctrl: 4 (value 5)
- *   - Super: 8 (value 9)
- *   - Hyper: 16
- *   - Meta: 32
- *   - Caps_Lock: 64
- *   - Num_Lock: 128
+ * Keyboard input handling for terminal applications.
  *
+ * Supports both legacy terminal sequences and Kitty keyboard protocol.
  * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
  *
- * NOTE: Some terminals (e.g., Ghostty on Linux) include lock key states
- * (Caps Lock, Num Lock) in the modifier field. We mask these out when
- * checking for key combinations since they shouldn't affect behavior.
+ * API:
+ * - matchesKey(data, keyId) - Check if input matches a key identifier
+ * - parseKey(data) - Parse input and return the key identifier
+ * - Key - Helper object for creating typed key identifiers
  */
-// Common codepoints
-const CODEPOINTS = {
-    // Letters (lowercase ASCII)
-    a: 97,
-    c: 99,
-    d: 100,
-    e: 101,
-    g: 103,
-    k: 107,
-    l: 108,
-    o: 111,
-    p: 112,
-    t: 116,
-    u: 117,
-    w: 119,
-    z: 122,
+/**
+ * Helper object for creating typed key identifiers with autocomplete.
+ *
+ * Usage:
+ * - Key.escape, Key.enter, Key.tab, etc. for special keys
+ * - Key.ctrl("c"), Key.alt("x") for single modifier
+ * - Key.ctrlShift("p"), Key.ctrlAlt("x") for combined modifiers
+ */
+export const Key = {
     // Special keys
+    escape: "escape",
+    esc: "esc",
+    enter: "enter",
+    return: "return",
+    tab: "tab",
+    space: "space",
+    backspace: "backspace",
+    delete: "delete",
+    home: "home",
+    end: "end",
+    up: "up",
+    down: "down",
+    left: "left",
+    right: "right",
+    // Single modifiers
+    ctrl: (key) => `ctrl+${key}`,
+    shift: (key) => `shift+${key}`,
+    alt: (key) => `alt+${key}`,
+    // Combined modifiers
+    ctrlShift: (key) => `ctrl+shift+${key}`,
+    shiftCtrl: (key) => `shift+ctrl+${key}`,
+    ctrlAlt: (key) => `ctrl+alt+${key}`,
+    altCtrl: (key) => `alt+ctrl+${key}`,
+    shiftAlt: (key) => `shift+alt+${key}`,
+    altShift: (key) => `alt+shift+${key}`,
+    // Triple modifiers
+    ctrlShiftAlt: (key) => `ctrl+shift+alt+${key}`,
+};
+// =============================================================================
+// Constants
+// =============================================================================
+const MODIFIERS = {
+    shift: 1,
+    alt: 2,
+    ctrl: 4,
+};
+const LOCK_MASK = 64 + 128; // Caps Lock + Num Lock
+const CODEPOINTS = {
     escape: 27,
     tab: 9,
     enter: 13,
     space: 32,
     backspace: 127,
+    kpEnter: 57414, // Numpad Enter (Kitty protocol)
 };
-// Lock key bits to ignore when matching (Caps Lock + Num Lock)
-const LOCK_MASK = 64 + 128; // 192
-// Modifier bits (before adding 1)
-const MODIFIERS = {
-    shift: 1,
-    alt: 2,
-    ctrl: 4,
-    super: 8,
+const ARROW_CODEPOINTS = {
+    up: -1,
+    down: -2,
+    right: -3,
+    left: -4,
 };
-/**
- * Build a Kitty keyboard protocol sequence for a key with modifier.
- */
-function kittySequence(codepoint, modifier) {
-    return `\x1b[${codepoint};${modifier + 1}u`;
-}
-/**
- * Parse a Kitty keyboard protocol sequence.
- * Handles formats:
- *   - \x1b[<codepoint>u (no modifier)
- *   - \x1b[<codepoint>;<modifier>u (with modifier)
- *   - \x1b[1;<modifier>A/B/C/D (arrow keys with modifier)
- *
- * Returns null if not a valid Kitty sequence.
- */
-// Virtual codepoints for functional keys (negative to avoid conflicts)
 const FUNCTIONAL_CODEPOINTS = {
     delete: -10,
     insert: -11,
@@ -77,43 +79,39 @@ const FUNCTIONAL_CODEPOINTS = {
     end: -15,
 };
 function parseKittySequence(data) {
-    // Match CSI u format: \x1b[<num>u or \x1b[<num>;<mod>u
+    // CSI u format: \x1b[<num>u or \x1b[<num>;<mod>u
     const csiUMatch = data.match(/^\x1b\[(\d+)(?:;(\d+))?u$/);
     if (csiUMatch) {
         const codepoint = parseInt(csiUMatch[1], 10);
         const modValue = csiUMatch[2] ? parseInt(csiUMatch[2], 10) : 1;
         return { codepoint, modifier: modValue - 1 };
     }
-    // Match arrow keys with modifier: \x1b[1;<mod>A/B/C/D
+    // Arrow keys with modifier: \x1b[1;<mod>A/B/C/D
     const arrowMatch = data.match(/^\x1b\[1;(\d+)([ABCD])$/);
     if (arrowMatch) {
         const modValue = parseInt(arrowMatch[1], 10);
-        // Map arrow letters to virtual codepoints for easier matching
         const arrowCodes = { A: -1, B: -2, C: -3, D: -4 };
-        const codepoint = arrowCodes[arrowMatch[2]];
-        return { codepoint, modifier: modValue - 1 };
+        return { codepoint: arrowCodes[arrowMatch[2]], modifier: modValue - 1 };
     }
-    // Match functional keys with ~ terminator: \x1b[<num>~ or \x1b[<num>;<mod>~
-    // DELETE=3, INSERT=2, PAGEUP=5, PAGEDOWN=6, etc.
+    // Functional keys: \x1b[<num>~ or \x1b[<num>;<mod>~
     const funcMatch = data.match(/^\x1b\[(\d+)(?:;(\d+))?~$/);
     if (funcMatch) {
         const keyNum = parseInt(funcMatch[1], 10);
         const modValue = funcMatch[2] ? parseInt(funcMatch[2], 10) : 1;
-        // Map functional key numbers to virtual codepoints
         const funcCodes = {
             2: FUNCTIONAL_CODEPOINTS.insert,
             3: FUNCTIONAL_CODEPOINTS.delete,
             5: FUNCTIONAL_CODEPOINTS.pageUp,
             6: FUNCTIONAL_CODEPOINTS.pageDown,
-            7: FUNCTIONAL_CODEPOINTS.home, // Alternative home
-            8: FUNCTIONAL_CODEPOINTS.end, // Alternative end
+            7: FUNCTIONAL_CODEPOINTS.home,
+            8: FUNCTIONAL_CODEPOINTS.end,
         };
         const codepoint = funcCodes[keyNum];
         if (codepoint !== undefined) {
             return { codepoint, modifier: modValue - 1 };
         }
     }
-    // Match Home/End with modifier: \x1b[1;<mod>H/F
+    // Home/End with modifier: \x1b[1;<mod>H/F
     const homeEndMatch = data.match(/^\x1b\[1;(\d+)([HF])$/);
     if (homeEndMatch) {
         const modValue = parseInt(homeEndMatch[1], 10);
@@ -122,381 +120,282 @@ function parseKittySequence(data) {
     }
     return null;
 }
-/**
- * Check if a Kitty sequence matches the expected codepoint and modifier,
- * ignoring lock key bits (Caps Lock, Num Lock).
- */
 function matchesKittySequence(data, expectedCodepoint, expectedModifier) {
     const parsed = parseKittySequence(data);
     if (!parsed)
         return false;
-    // Mask out lock bits from both sides for comparison
     const actualMod = parsed.modifier & ~LOCK_MASK;
     const expectedMod = expectedModifier & ~LOCK_MASK;
     return parsed.codepoint === expectedCodepoint && actualMod === expectedMod;
 }
-// Pre-built sequences for common key combinations
-export const Keys = {
-    // Ctrl+<letter> combinations
-    CTRL_A: kittySequence(CODEPOINTS.a, MODIFIERS.ctrl),
-    CTRL_C: kittySequence(CODEPOINTS.c, MODIFIERS.ctrl),
-    CTRL_D: kittySequence(CODEPOINTS.d, MODIFIERS.ctrl),
-    CTRL_E: kittySequence(CODEPOINTS.e, MODIFIERS.ctrl),
-    CTRL_G: kittySequence(CODEPOINTS.g, MODIFIERS.ctrl),
-    CTRL_K: kittySequence(CODEPOINTS.k, MODIFIERS.ctrl),
-    CTRL_L: kittySequence(CODEPOINTS.l, MODIFIERS.ctrl),
-    CTRL_O: kittySequence(CODEPOINTS.o, MODIFIERS.ctrl),
-    CTRL_P: kittySequence(CODEPOINTS.p, MODIFIERS.ctrl),
-    CTRL_T: kittySequence(CODEPOINTS.t, MODIFIERS.ctrl),
-    CTRL_U: kittySequence(CODEPOINTS.u, MODIFIERS.ctrl),
-    CTRL_W: kittySequence(CODEPOINTS.w, MODIFIERS.ctrl),
-    CTRL_Z: kittySequence(CODEPOINTS.z, MODIFIERS.ctrl),
-    // Enter combinations
-    SHIFT_ENTER: kittySequence(CODEPOINTS.enter, MODIFIERS.shift),
-    ALT_ENTER: kittySequence(CODEPOINTS.enter, MODIFIERS.alt),
-    CTRL_ENTER: kittySequence(CODEPOINTS.enter, MODIFIERS.ctrl),
-    // Tab combinations
-    SHIFT_TAB: kittySequence(CODEPOINTS.tab, MODIFIERS.shift),
-    // Backspace combinations
-    ALT_BACKSPACE: kittySequence(CODEPOINTS.backspace, MODIFIERS.alt),
-};
-/**
- * Check if input matches a Kitty protocol Ctrl+<key> sequence.
- * Ignores lock key bits (Caps Lock, Num Lock).
- * @param data - The input data to check
- * @param key - Single lowercase letter (e.g., 'c' for Ctrl+C)
+// =============================================================================
+// Generic Key Matching
+// =============================================================================
+function rawCtrlChar(letter) {
+    const code = letter.toLowerCase().charCodeAt(0) - 96;
+    return String.fromCharCode(code);
+}
+function parseKeyId(keyId) {
+    const parts = keyId.toLowerCase().split("+");
+    const key = parts[parts.length - 1];
+    if (!key)
+        return null;
+    return {
+        key,
+        ctrl: parts.includes("ctrl"),
+        shift: parts.includes("shift"),
+        alt: parts.includes("alt"),
+    };
+}
+/**
+ * Match input data against a key identifier string.
+ *
+ * Supported key identifiers:
+ * - Single keys: "escape", "tab", "enter", "backspace", "delete", "home", "end", "space"
+ * - Arrow keys: "up", "down", "left", "right"
+ * - Ctrl combinations: "ctrl+c", "ctrl+z", etc.
+ * - Shift combinations: "shift+tab", "shift+enter"
+ * - Alt combinations: "alt+enter", "alt+backspace"
+ * - Combined modifiers: "shift+ctrl+p", "ctrl+alt+x"
+ *
+ * Use the Key helper for autocomplete: Key.ctrl("c"), Key.escape, Key.ctrlShift("p")
+ *
+ * @param data - Raw input data from terminal
+ * @param keyId - Key identifier (e.g., "ctrl+c", "escape", Key.ctrl("c"))
  */
-export function isKittyCtrl(data, key) {
-    if (key.length !== 1)
+export function matchesKey(data, keyId) {
+    const parsed = parseKeyId(keyId);
+    if (!parsed)
         return false;
-    const codepoint = key.charCodeAt(0);
-    // Check exact match first (fast path)
-    if (data === kittySequence(codepoint, MODIFIERS.ctrl))
-        return true;
-    // Check with lock bits masked out
-    return matchesKittySequence(data, codepoint, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches a Kitty protocol key sequence with specific modifier.
- * Ignores lock key bits (Caps Lock, Num Lock).
- * @param data - The input data to check
- * @param codepoint - ASCII codepoint of the key
- * @param modifier - Modifier value (use MODIFIERS constants)
- */
-export function isKittyKey(data, codepoint, modifier) {
-    // Check exact match first (fast path)
-    if (data === kittySequence(codepoint, modifier))
-        return true;
-    // Check with lock bits masked out
-    return matchesKittySequence(data, codepoint, modifier);
-}
-// Raw control character codes
-const RAW = {
-    CTRL_A: "\x01",
-    CTRL_C: "\x03",
-    CTRL_D: "\x04",
-    CTRL_E: "\x05",
-    CTRL_G: "\x07",
-    CTRL_K: "\x0b",
-    CTRL_L: "\x0c",
-    CTRL_O: "\x0f",
-    CTRL_P: "\x10",
-    CTRL_T: "\x14",
-    CTRL_U: "\x15",
-    CTRL_W: "\x17",
-    CTRL_Z: "\x1a",
-    ALT_BACKSPACE: "\x1b\x7f",
-    SHIFT_TAB: "\x1b[Z",
-};
-/**
- * Check if input matches Ctrl+A (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlA(data) {
-    return data === RAW.CTRL_A || data === Keys.CTRL_A || matchesKittySequence(data, CODEPOINTS.a, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+C (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlC(data) {
-    return data === RAW.CTRL_C || data === Keys.CTRL_C || matchesKittySequence(data, CODEPOINTS.c, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+D (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlD(data) {
-    return data === RAW.CTRL_D || data === Keys.CTRL_D || matchesKittySequence(data, CODEPOINTS.d, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+E (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlE(data) {
-    return data === RAW.CTRL_E || data === Keys.CTRL_E || matchesKittySequence(data, CODEPOINTS.e, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+G (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlG(data) {
-    return data === RAW.CTRL_G || data === Keys.CTRL_G || matchesKittySequence(data, CODEPOINTS.g, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+K (raw byte or Kitty protocol).
- * Ignores lock key bits.
- * Also checks if first byte is 0x0b for compatibility with terminals
- * that may send trailing bytes.
- */
-export function isCtrlK(data) {
-    return (data === RAW.CTRL_K ||
-        (data.length > 0 && data.charCodeAt(0) === 0x0b) ||
-        data === Keys.CTRL_K ||
-        matchesKittySequence(data, CODEPOINTS.k, MODIFIERS.ctrl));
-}
-/**
- * Check if input matches Ctrl+L (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlL(data) {
-    return data === RAW.CTRL_L || data === Keys.CTRL_L || matchesKittySequence(data, CODEPOINTS.l, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+O (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlO(data) {
-    return data === RAW.CTRL_O || data === Keys.CTRL_O || matchesKittySequence(data, CODEPOINTS.o, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Shift+Ctrl+O (Kitty protocol only).
- * Ignores lock key bits.
- */
-export function isShiftCtrlO(data) {
-    return matchesKittySequence(data, CODEPOINTS.o, MODIFIERS.shift + MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+P (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlP(data) {
-    return data === RAW.CTRL_P || data === Keys.CTRL_P || matchesKittySequence(data, CODEPOINTS.p, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Shift+Ctrl+P (Kitty protocol only).
- * Ignores lock key bits.
- */
-export function isShiftCtrlP(data) {
-    return matchesKittySequence(data, CODEPOINTS.p, MODIFIERS.shift + MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Shift+Ctrl+D (Kitty protocol only, for debug).
- * Ignores lock key bits.
- */
-export function isShiftCtrlD(data) {
-    return matchesKittySequence(data, CODEPOINTS.d, MODIFIERS.shift + MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+T (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlT(data) {
-    return data === RAW.CTRL_T || data === Keys.CTRL_T || matchesKittySequence(data, CODEPOINTS.t, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+U (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlU(data) {
-    return data === RAW.CTRL_U || data === Keys.CTRL_U || matchesKittySequence(data, CODEPOINTS.u, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+W (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlW(data) {
-    return data === RAW.CTRL_W || data === Keys.CTRL_W || matchesKittySequence(data, CODEPOINTS.w, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+Z (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlZ(data) {
-    return data === RAW.CTRL_Z || data === Keys.CTRL_Z || matchesKittySequence(data, CODEPOINTS.z, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Alt+Backspace (legacy or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isAltBackspace(data) {
-    return (data === RAW.ALT_BACKSPACE ||
-        data === Keys.ALT_BACKSPACE ||
-        matchesKittySequence(data, CODEPOINTS.backspace, MODIFIERS.alt));
-}
-/**
- * Check if input matches Shift+Tab (legacy or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isShiftTab(data) {
-    return (data === RAW.SHIFT_TAB || data === Keys.SHIFT_TAB || matchesKittySequence(data, CODEPOINTS.tab, MODIFIERS.shift));
-}
-/**
- * Check if input matches the Escape key (raw byte or Kitty protocol).
- * Raw: \x1b (single byte)
- * Kitty: \x1b[27u (codepoint 27 = escape)
- * Ignores lock key bits.
- */
-export function isEscape(data) {
-    return data === "\x1b" || data === `\x1b[${CODEPOINTS.escape}u` || matchesKittySequence(data, CODEPOINTS.escape, 0);
-}
-// Arrow key virtual codepoints (negative to avoid conflicts with real codepoints)
-const ARROW_CODEPOINTS = {
-    up: -1,
-    down: -2,
-    right: -3,
-    left: -4,
-};
-/**
- * Check if input matches Arrow Up key.
- * Handles both legacy (\x1b[A) and Kitty protocol with modifiers.
- */
-export function isArrowUp(data) {
-    return data === "\x1b[A" || matchesKittySequence(data, ARROW_CODEPOINTS.up, 0);
-}
-/**
- * Check if input matches Arrow Down key.
- * Handles both legacy (\x1b[B) and Kitty protocol with modifiers.
- */
-export function isArrowDown(data) {
-    return data === "\x1b[B" || matchesKittySequence(data, ARROW_CODEPOINTS.down, 0);
-}
-/**
- * Check if input matches Arrow Right key.
- * Handles both legacy (\x1b[C) and Kitty protocol with modifiers.
- */
-export function isArrowRight(data) {
-    return data === "\x1b[C" || matchesKittySequence(data, ARROW_CODEPOINTS.right, 0);
-}
-/**
- * Check if input matches Arrow Left key.
- * Handles both legacy (\x1b[D) and Kitty protocol with modifiers.
- */
-export function isArrowLeft(data) {
-    return data === "\x1b[D" || matchesKittySequence(data, ARROW_CODEPOINTS.left, 0);
-}
-/**
- * Check if input matches plain Tab key (no modifiers).
- * Handles both legacy (\t) and Kitty protocol.
- */
-export function isTab(data) {
-    return data === "\t" || matchesKittySequence(data, CODEPOINTS.tab, 0);
-}
-/**
- * Check if input matches plain Enter/Return key (no modifiers).
- * Handles both legacy (\r) and Kitty protocol.
- */
-export function isEnter(data) {
-    return data === "\r" || matchesKittySequence(data, CODEPOINTS.enter, 0);
-}
-/**
- * Check if input matches plain Backspace key (no modifiers).
- * Handles both legacy (\x7f, \x08) and Kitty protocol.
- */
-export function isBackspace(data) {
-    return data === "\x7f" || data === "\x08" || matchesKittySequence(data, CODEPOINTS.backspace, 0);
-}
-/**
- * Check if input matches Shift+Backspace (Kitty protocol).
- * Returns true so caller can treat it as regular backspace.
- * Ignores lock key bits.
- */
-export function isShiftBackspace(data) {
-    return matchesKittySequence(data, CODEPOINTS.backspace, MODIFIERS.shift);
-}
-/**
- * Check if input matches Shift+Enter.
- * Ignores lock key bits.
- */
-export function isShiftEnter(data) {
-    return data === Keys.SHIFT_ENTER || matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift);
-}
-/**
- * Check if input matches Alt+Enter.
- * Ignores lock key bits.
- */
-export function isAltEnter(data) {
-    return data === Keys.ALT_ENTER || data === "\x1b\r" || matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.alt);
-}
-/**
- * Check if input matches Shift+Space (Kitty protocol).
- * Returns true so caller can insert a regular space.
- * Ignores lock key bits.
- */
-export function isShiftSpace(data) {
-    return matchesKittySequence(data, CODEPOINTS.space, MODIFIERS.shift);
-}
-/**
- * Check if input matches Option/Alt+Left (word navigation).
- * Handles multiple formats including Kitty protocol.
- */
-export function isAltLeft(data) {
-    return data === "\x1b[1;3D" || data === "\x1bb" || matchesKittySequence(data, ARROW_CODEPOINTS.left, MODIFIERS.alt);
-}
-/**
- * Check if input matches Option/Alt+Right (word navigation).
- * Handles multiple formats including Kitty protocol.
- */
-export function isAltRight(data) {
-    return data === "\x1b[1;3C" || data === "\x1bf" || matchesKittySequence(data, ARROW_CODEPOINTS.right, MODIFIERS.alt);
-}
-/**
- * Check if input matches Ctrl+Left (word navigation).
- * Handles multiple formats including Kitty protocol.
- */
-export function isCtrlLeft(data) {
-    return data === "\x1b[1;5D" || matchesKittySequence(data, ARROW_CODEPOINTS.left, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Ctrl+Right (word navigation).
- * Handles multiple formats including Kitty protocol.
- */
-export function isCtrlRight(data) {
-    return data === "\x1b[1;5C" || matchesKittySequence(data, ARROW_CODEPOINTS.right, MODIFIERS.ctrl);
-}
-/**
- * Check if input matches Home key.
- * Handles legacy formats and Kitty protocol with lock key modifiers.
- */
-export function isHome(data) {
-    return (data === "\x1b[H" ||
-        data === "\x1b[1~" ||
-        data === "\x1b[7~" ||
-        matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.home, 0));
-}
-/**
- * Check if input matches End key.
- * Handles legacy formats and Kitty protocol with lock key modifiers.
- */
-export function isEnd(data) {
-    return (data === "\x1b[F" ||
-        data === "\x1b[4~" ||
-        data === "\x1b[8~" ||
-        matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.end, 0));
-}
-/**
- * Check if input matches Delete key (forward delete).
- * Handles legacy format and Kitty protocol with lock key modifiers.
- */
-export function isDelete(data) {
-    return data === "\x1b[3~" || matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.delete, 0);
+    const { key, ctrl, shift, alt } = parsed;
+    let modifier = 0;
+    if (shift)
+        modifier |= MODIFIERS.shift;
+    if (alt)
+        modifier |= MODIFIERS.alt;
+    if (ctrl)
+        modifier |= MODIFIERS.ctrl;
+    switch (key) {
+        case "escape":
+        case "esc":
+            if (modifier !== 0)
+                return false;
+            return data === "\x1b" || matchesKittySequence(data, CODEPOINTS.escape, 0);
+        case "space":
+            if (modifier === 0) {
+                return data === " " || matchesKittySequence(data, CODEPOINTS.space, 0);
+            }
+            return matchesKittySequence(data, CODEPOINTS.space, modifier);
+        case "tab":
+            if (shift && !ctrl && !alt) {
+                return data === "\x1b[Z" || matchesKittySequence(data, CODEPOINTS.tab, MODIFIERS.shift);
+            }
+            if (modifier === 0) {
+                return data === "\t" || matchesKittySequence(data, CODEPOINTS.tab, 0);
+            }
+            return matchesKittySequence(data, CODEPOINTS.tab, modifier);
+        case "enter":
+        case "return":
+            if (shift && !ctrl && !alt) {
+                return (matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift) ||
+                    matchesKittySequence(data, CODEPOINTS.kpEnter, MODIFIERS.shift));
+            }
+            if (alt && !ctrl && !shift) {
+                return (data === "\x1b\r" ||
+                    matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.alt) ||
+                    matchesKittySequence(data, CODEPOINTS.kpEnter, MODIFIERS.alt));
+            }
+            if (modifier === 0) {
+                return (data === "\r" ||
+                    data === "\x1bOM" || // SS3 M (numpad enter in some terminals)
+                    matchesKittySequence(data, CODEPOINTS.enter, 0) ||
+                    matchesKittySequence(data, CODEPOINTS.kpEnter, 0));
+            }
+            return (matchesKittySequence(data, CODEPOINTS.enter, modifier) ||
+                matchesKittySequence(data, CODEPOINTS.kpEnter, modifier));
+        case "backspace":
+            if (alt && !ctrl && !shift) {
+                return data === "\x1b\x7f" || matchesKittySequence(data, CODEPOINTS.backspace, MODIFIERS.alt);
+            }
+            if (modifier === 0) {
+                return data === "\x7f" || data === "\x08" || matchesKittySequence(data, CODEPOINTS.backspace, 0);
+            }
+            return matchesKittySequence(data, CODEPOINTS.backspace, modifier);
+        case "delete":
+            if (modifier === 0) {
+                return data === "\x1b[3~" || matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.delete, 0);
+            }
+            return matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.delete, modifier);
+        case "home":
+            if (modifier === 0) {
+                return (data === "\x1b[H" ||
+                    data === "\x1b[1~" ||
+                    data === "\x1b[7~" ||
+                    matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.home, 0));
+            }
+            return matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.home, modifier);
+        case "end":
+            if (modifier === 0) {
+                return (data === "\x1b[F" ||
+                    data === "\x1b[4~" ||
+                    data === "\x1b[8~" ||
+                    matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.end, 0));
+            }
+            return matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.end, modifier);
+        case "up":
+            if (modifier === 0) {
+                return data === "\x1b[A" || matchesKittySequence(data, ARROW_CODEPOINTS.up, 0);
+            }
+            return matchesKittySequence(data, ARROW_CODEPOINTS.up, modifier);
+        case "down":
+            if (modifier === 0) {
+                return data === "\x1b[B" || matchesKittySequence(data, ARROW_CODEPOINTS.down, 0);
+            }
+            return matchesKittySequence(data, ARROW_CODEPOINTS.down, modifier);
+        case "left":
+            if (alt && !ctrl && !shift) {
+                return (data === "\x1b[1;3D" ||
+                    data === "\x1bb" ||
+                    matchesKittySequence(data, ARROW_CODEPOINTS.left, MODIFIERS.alt));
+            }
+            if (ctrl && !alt && !shift) {
+                return data === "\x1b[1;5D" || matchesKittySequence(data, ARROW_CODEPOINTS.left, MODIFIERS.ctrl);
+            }
+            if (modifier === 0) {
+                return data === "\x1b[D" || matchesKittySequence(data, ARROW_CODEPOINTS.left, 0);
+            }
+            return matchesKittySequence(data, ARROW_CODEPOINTS.left, modifier);
+        case "right":
+            if (alt && !ctrl && !shift) {
+                return (data === "\x1b[1;3C" ||
+                    data === "\x1bf" ||
+                    matchesKittySequence(data, ARROW_CODEPOINTS.right, MODIFIERS.alt));
+            }
+            if (ctrl && !alt && !shift) {
+                return data === "\x1b[1;5C" || matchesKittySequence(data, ARROW_CODEPOINTS.right, MODIFIERS.ctrl);
+            }
+            if (modifier === 0) {
+                return data === "\x1b[C" || matchesKittySequence(data, ARROW_CODEPOINTS.right, 0);
+            }
+            return matchesKittySequence(data, ARROW_CODEPOINTS.right, modifier);
+    }
+    // Handle single letter keys (a-z)
+    if (key.length === 1 && key >= "a" && key <= "z") {
+        const codepoint = key.charCodeAt(0);
+        if (ctrl && !shift && !alt) {
+            const raw = rawCtrlChar(key);
+            if (data === raw)
+                return true;
+            if (data.length > 0 && data.charCodeAt(0) === raw.charCodeAt(0))
+                return true;
+            return matchesKittySequence(data, codepoint, MODIFIERS.ctrl);
+        }
+        if (ctrl && shift && !alt) {
+            return matchesKittySequence(data, codepoint, MODIFIERS.shift + MODIFIERS.ctrl);
+        }
+        if (shift && !ctrl && !alt) {
+            // Legacy: shift+letter produces uppercase
+            if (data === key.toUpperCase())
+                return true;
+            return matchesKittySequence(data, codepoint, MODIFIERS.shift);
+        }
+        if (modifier !== 0) {
+            return matchesKittySequence(data, codepoint, modifier);
+        }
+        return data === key;
+    }
+    return false;
 }
 /**
- * Check if input matches Shift+Delete (Kitty protocol).
- * Returns true so caller can treat it as regular delete.
- * Ignores lock key bits.
- */
-export function isShiftDelete(data) {
-    return matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.delete, MODIFIERS.shift);
+ * Parse input data and return the key identifier if recognized.
+ *
+ * @param data - Raw input data from terminal
+ * @returns Key identifier string (e.g., "ctrl+c") or undefined
+ */
+export function parseKey(data) {
+    const kitty = parseKittySequence(data);
+    if (kitty) {
+        const { codepoint, modifier } = kitty;
+        const mods = [];
+        const effectiveMod = modifier & ~LOCK_MASK;
+        if (effectiveMod & MODIFIERS.shift)
+            mods.push("shift");
+        if (effectiveMod & MODIFIERS.ctrl)
+            mods.push("ctrl");
+        if (effectiveMod & MODIFIERS.alt)
+            mods.push("alt");
+        let keyName;
+        if (codepoint === CODEPOINTS.escape)
+            keyName = "escape";
+        else if (codepoint === CODEPOINTS.tab)
+            keyName = "tab";
+        else if (codepoint === CODEPOINTS.enter || codepoint === CODEPOINTS.kpEnter)
+            keyName = "enter";
+        else if (codepoint === CODEPOINTS.space)
+            keyName = "space";
+        else if (codepoint === CODEPOINTS.backspace)
+            keyName = "backspace";
+        else if (codepoint === FUNCTIONAL_CODEPOINTS.delete)
+            keyName = "delete";
+        else if (codepoint === FUNCTIONAL_CODEPOINTS.home)
+            keyName = "home";
+        else if (codepoint === FUNCTIONAL_CODEPOINTS.end)
+            keyName = "end";
+        else if (codepoint === ARROW_CODEPOINTS.up)
+            keyName = "up";
+        else if (codepoint === ARROW_CODEPOINTS.down)
+            keyName = "down";
+        else if (codepoint === ARROW_CODEPOINTS.left)
+            keyName = "left";
+        else if (codepoint === ARROW_CODEPOINTS.right)
+            keyName = "right";
+        else if (codepoint >= 97 && codepoint <= 122)
+            keyName = String.fromCharCode(codepoint);
+        if (keyName) {
+            return mods.length > 0 ? `${mods.join("+")}+${keyName}` : keyName;
+        }
+    }
+    // Legacy sequences
+    if (data === "\x1b")
+        return "escape";
+    if (data === "\t")
+        return "tab";
+    if (data === "\r" || data === "\x1bOM")
+        return "enter";
+    if (data === " ")
+        return "space";
+    if (data === "\x7f" || data === "\x08")
+        return "backspace";
+    if (data === "\x1b[Z")
+        return "shift+tab";
+    if (data === "\x1b\r")
+        return "alt+enter";
+    if (data === "\x1b\x7f")
+        return "alt+backspace";
+    if (data === "\x1b[A")
+        return "up";
+    if (data === "\x1b[B")
+        return "down";
+    if (data === "\x1b[C")
+        return "right";
+    if (data === "\x1b[D")
+        return "left";
+    if (data === "\x1b[H")
+        return "home";
+    if (data === "\x1b[F")
+        return "end";
+    if (data === "\x1b[3~")
+        return "delete";
+    // Raw Ctrl+letter
+    if (data.length === 1) {
+        const code = data.charCodeAt(0);
+        if (code >= 1 && code <= 26) {
+            return `ctrl+${String.fromCharCode(code + 96)}`;
+        }
+        if (code >= 32 && code <= 126) {
+            return data;
+        }
+    }
+    return undefined;
 }
 //# sourceMappingURL=keys.js.map