@oh-my-pi/pi-tui 3.15.0 → 3.20.0

package/src/keys.ts

@@ -1,87 +1,263 @@
 /**
- * Kitty keyboard protocol key sequence helpers.
+ * Keyboard input handling for terminal applications.
  *
- * The Kitty keyboard protocol sends enhanced escape sequences in the format:
- *   \x1b[<codepoint>;<modifier>u
+ * Supports both legacy terminal sequences and Kitty keyboard protocol.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
  *
- * 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
+ * Symbol keys are also supported, however some ctrl+symbol combos
+ * overlap with ASCII codes, e.g. ctrl+[ = ESC.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/#legacy-ctrl-mapping-of-ascii-keys
+ * Those can still be * used for ctrl+shift combos
  *
- * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ * 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
+ */
+
+// =============================================================================
+// Type-Safe Key Identifiers
+// =============================================================================
+
+type Letter =
+	| "a"
+	| "b"
+	| "c"
+	| "d"
+	| "e"
+	| "f"
+	| "g"
+	| "h"
+	| "i"
+	| "j"
+	| "k"
+	| "l"
+	| "m"
+	| "n"
+	| "o"
+	| "p"
+	| "q"
+	| "r"
+	| "s"
+	| "t"
+	| "u"
+	| "v"
+	| "w"
+	| "x"
+	| "y"
+	| "z";
+
+type SymbolKey =
+	| "`"
+	| "-"
+	| "="
+	| "["
+	| "]"
+	| "\\"
+	| ";"
+	| "'"
+	| ","
+	| "."
+	| "/"
+	| "!"
+	| "@"
+	| "#"
+	| "$"
+	| "%"
+	| "^"
+	| "&"
+	| "*"
+	| "("
+	| ")"
+	| "_"
+	| "+"
+	| "|"
+	| "~"
+	| "{"
+	| "}"
+	| ":"
+	| "<"
+	| ">"
+	| "?";
+
+type SpecialKey =
+	| "escape"
+	| "esc"
+	| "enter"
+	| "return"
+	| "tab"
+	| "space"
+	| "backspace"
+	| "delete"
+	| "home"
+	| "end"
+	| "up"
+	| "down"
+	| "left"
+	| "right";
+
+type BaseKey = Letter | SymbolKey | SpecialKey;
+
+/**
+ * Union type of all valid key identifiers.
+ * Provides autocomplete and catches typos at compile time.
+ */
+export type KeyId =
+	| BaseKey
+	| `ctrl+${BaseKey}`
+	| `shift+${BaseKey}`
+	| `alt+${BaseKey}`
+	| `ctrl+shift+${BaseKey}`
+	| `shift+ctrl+${BaseKey}`
+	| `ctrl+alt+${BaseKey}`
+	| `alt+ctrl+${BaseKey}`
+	| `shift+alt+${BaseKey}`
+	| `alt+shift+${BaseKey}`
+	| `ctrl+shift+alt+${BaseKey}`
+	| `ctrl+alt+shift+${BaseKey}`
+	| `shift+ctrl+alt+${BaseKey}`
+	| `shift+alt+ctrl+${BaseKey}`
+	| `alt+ctrl+shift+${BaseKey}`
+	| `alt+shift+ctrl+${BaseKey}`;
+
+/**
+ * Helper object for creating typed key identifiers with autocomplete.
  *
- * 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.
+ * Usage:
+ * - Key.escape, Key.enter, Key.tab, etc. for special keys
+ * - Key.backtick, Key.comma, Key.period, etc. for symbol keys
+ * - Key.ctrl("c"), Key.alt("x") for single modifier
+ * - Key.ctrlShift("p"), Key.ctrlAlt("x") for combined modifiers
  */
-
-// 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,
-	v: 118,
-	w: 119,
-	z: 122,
-
+export const Key = {
 	// Special keys
-	escape: 27,
-	tab: 9,
-	enter: 13,
-	backspace: 127,
+	escape: "escape" as const,
+	esc: "esc" as const,
+	enter: "enter" as const,
+	return: "return" as const,
+	tab: "tab" as const,
+	space: "space" as const,
+	backspace: "backspace" as const,
+	delete: "delete" as const,
+	home: "home" as const,
+	end: "end" as const,
+	up: "up" as const,
+	down: "down" as const,
+	left: "left" as const,
+	right: "right" as const,
+
+	// Symbol keys
+	backtick: "`" as const,
+	hyphen: "-" as const,
+	equals: "=" as const,
+	leftbracket: "[" as const,
+	rightbracket: "]" as const,
+	backslash: "\\" as const,
+	semicolon: ";" as const,
+	quote: "'" as const,
+	comma: "," as const,
+	period: "." as const,
+	slash: "/" as const,
+	exclamation: "!" as const,
+	at: "@" as const,
+	hash: "#" as const,
+	dollar: "$" as const,
+	percent: "%" as const,
+	caret: "^" as const,
+	ampersand: "&" as const,
+	asterisk: "*" as const,
+	leftparen: "(" as const,
+	rightparen: ")" as const,
+	underscore: "_" as const,
+	plus: "+" as const,
+	pipe: "|" as const,
+	tilde: "~" as const,
+	leftbrace: "{" as const,
+	rightbrace: "}" as const,
+	colon: ":" as const,
+	lessthan: "<" as const,
+	greaterthan: ">" as const,
+	question: "?" as const,
+
+	// Single modifiers
+	ctrl: <K extends BaseKey>(key: K): `ctrl+${K}` => `ctrl+${key}`,
+	shift: <K extends BaseKey>(key: K): `shift+${K}` => `shift+${key}`,
+	alt: <K extends BaseKey>(key: K): `alt+${K}` => `alt+${key}`,
+
+	// Combined modifiers
+	ctrlShift: <K extends BaseKey>(key: K): `ctrl+shift+${K}` => `ctrl+shift+${key}`,
+	shiftCtrl: <K extends BaseKey>(key: K): `shift+ctrl+${K}` => `shift+ctrl+${key}`,
+	ctrlAlt: <K extends BaseKey>(key: K): `ctrl+alt+${K}` => `ctrl+alt+${key}`,
+	altCtrl: <K extends BaseKey>(key: K): `alt+ctrl+${K}` => `alt+ctrl+${key}`,
+	shiftAlt: <K extends BaseKey>(key: K): `shift+alt+${K}` => `shift+alt+${key}`,
+	altShift: <K extends BaseKey>(key: K): `alt+shift+${K}` => `alt+shift+${key}`,
+
+	// Triple modifiers
+	ctrlShiftAlt: <K extends BaseKey>(key: K): `ctrl+shift+alt+${K}` => `ctrl+shift+alt+${key}`,
 } as const;
 
-// Lock key bits to ignore when matching (Caps Lock + Num Lock)
-const LOCK_MASK = 64 + 128; // 192
+// =============================================================================
+// Constants
+// =============================================================================
+
+const SYMBOL_KEYS = new Set([
+	"`",
+	"-",
+	"=",
+	"[",
+	"]",
+	"\\",
+	";",
+	"'",
+	",",
+	".",
+	"/",
+	"!",
+	"@",
+	"#",
+	"$",
+	"%",
+	"^",
+	"&",
+	"*",
+	"(",
+	")",
+	"_",
+	"+",
+	"|",
+	"~",
+	"{",
+	"}",
+	":",
+	"<",
+	">",
+	"?",
+]);
 
-// Modifier bits (before adding 1)
 const MODIFIERS = {
 	shift: 1,
 	alt: 2,
 	ctrl: 4,
-	super: 8,
 } as const;
 
-/**
- * Build a Kitty keyboard protocol sequence for a key with modifier.
- */
-function kittySequence(codepoint: number, modifier: number): string {
-	return `\x1b[${codepoint};${modifier + 1}u`;
-}
+const LOCK_MASK = 64 + 128; // Caps Lock + Num Lock
 
-/**
- * Parsed Kitty keyboard protocol sequence.
- */
-interface ParsedKittySequence {
-	codepoint: number;
-	modifier: number; // Actual modifier bits (after subtracting 1)
-}
+const CODEPOINTS = {
+	escape: 27,
+	tab: 9,
+	enter: 13,
+	space: 32,
+	backspace: 127,
+	kpEnter: 57414, // Numpad Enter (Kitty protocol)
+} as const;
+
+const ARROW_CODEPOINTS = {
+	up: -1,
+	down: -2,
+	right: -3,
+	left: -4,
+} as const;
 
-/**
- * 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,
@@ -91,8 +267,17 @@ const FUNCTIONAL_CODEPOINTS = {
 	end: -15,
 } as const;
 
+// =============================================================================
+// Kitty Protocol Parsing
+// =============================================================================
+
+interface ParsedKittySequence {
+	codepoint: number;
+	modifier: number;
+}
+
 function parseKittySequence(data: string): ParsedKittySequence | null {
-	// 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);
@@ -100,30 +285,26 @@ function parseKittySequence(data: string): ParsedKittySequence | null {
 		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: Record<string, number> = { 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: Record<number, number> = {
 			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) {
@@ -131,7 +312,7 @@ function parseKittySequence(data: string): ParsedKittySequence | null {
 		}
 	}
 
-	// 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);
@@ -142,419 +323,462 @@ function parseKittySequence(data: string): ParsedKittySequence | null {
 	return null;
 }
 
-/**
- * Check if a Kitty sequence matches the expected codepoint and modifier,
- * ignoring lock key bits (Caps Lock, Num Lock).
- */
 function matchesKittySequence(data: string, expectedCodepoint: number, expectedModifier: number): boolean {
 	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_V: kittySequence(CODEPOINTS.v, 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),
-} as const;
+// =============================================================================
+// Generic Key Matching
+// =============================================================================
 
-/**
- * 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)
- */
-export function isKittyCtrl(data: string, key: string): boolean {
-	if (key.length !== 1) 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);
+function rawCtrlChar(letter: string): string {
+	const code = letter.toLowerCase().charCodeAt(0) - 96;
+	return String.fromCharCode(code);
 }
 
-/**
- * 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: string, codepoint: number, modifier: number): boolean {
-	// 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_V: "\x16",
-	CTRL_W: "\x17",
-	CTRL_Z: "\x1a",
-	ALT_BACKSPACE: "\x1b\x7f",
-	SHIFT_TAB: "\x1b[Z",
-} as const;
+function parseKeyId(keyId: string): { key: string; ctrl: boolean; shift: boolean; alt: boolean } | null {
+	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"),
+	};
+}
 
 /**
- * Check if input matches Ctrl+A (raw byte or Kitty protocol).
- * Ignores lock key bits.
+ * 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 isCtrlA(data: string): boolean {
-	return data === RAW.CTRL_A || data === Keys.CTRL_A || matchesKittySequence(data, CODEPOINTS.a, MODIFIERS.ctrl);
+export function matchesKey(data: string, keyId: KeyId): boolean {
+	const parsed = parseKeyId(keyId);
+	if (!parsed) return false;
+
+	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 (
+					data === "\x1b\r" || // Legacy: some terminals send ESC+CR for shift+enter
+					matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift) ||
+					matchesKittySequence(data, CODEPOINTS.kpEnter, MODIFIERS.shift)
+				);
+			}
+			if (alt && !ctrl && !shift) {
+				return (
+					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) and some symbols
+	if (key.length === 1 && ((key >= "a" && key <= "z") || SYMBOL_KEYS.has(key))) {
+		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 Ctrl+C (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlC(data: string): boolean {
-	return data === RAW.CTRL_C || data === Keys.CTRL_C || matchesKittySequence(data, CODEPOINTS.c, MODIFIERS.ctrl);
+ * 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: string): string | undefined {
+	const kitty = parseKittySequence(data);
+	if (kitty) {
+		const { codepoint, modifier } = kitty;
+		const mods: string[] = [];
+		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: string | undefined;
+		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);
+		else if (SYMBOL_KEYS.has(String.fromCharCode(codepoint))) 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 "shift+enter"; // Legacy: ESC+CR for shift+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;
 }
 
-/**
- * Check if input matches Ctrl+D (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlD(data: string): boolean {
-	return data === RAW.CTRL_D || data === Keys.CTRL_D || matchesKittySequence(data, CODEPOINTS.d, MODIFIERS.ctrl);
+// =============================================================================
+// Legacy helper wrappers (for compatibility)
+// =============================================================================
+
+export function isArrowUp(data: string): boolean {
+	return matchesKey(data, "up");
 }
 
-/**
- * Check if input matches Ctrl+E (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlE(data: string): boolean {
-	return data === RAW.CTRL_E || data === Keys.CTRL_E || matchesKittySequence(data, CODEPOINTS.e, MODIFIERS.ctrl);
+export function isArrowDown(data: string): boolean {
+	return matchesKey(data, "down");
 }
 
-/**
- * Check if input matches Ctrl+G (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlG(data: string): boolean {
-	return data === RAW.CTRL_G || data === Keys.CTRL_G || matchesKittySequence(data, CODEPOINTS.g, MODIFIERS.ctrl);
+export function isArrowLeft(data: string): boolean {
+	return matchesKey(data, "left");
 }
 
-/**
- * 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: string): boolean {
-	return (
-		data === RAW.CTRL_K ||
-		(data.length > 0 && data.charCodeAt(0) === 0x0b) ||
-		data === Keys.CTRL_K ||
-		matchesKittySequence(data, CODEPOINTS.k, MODIFIERS.ctrl)
-	);
+export function isArrowRight(data: string): boolean {
+	return matchesKey(data, "right");
 }
 
-/**
- * Check if input matches Ctrl+L (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlL(data: string): boolean {
-	return data === RAW.CTRL_L || data === Keys.CTRL_L || matchesKittySequence(data, CODEPOINTS.l, MODIFIERS.ctrl);
+export function isEscape(data: string): boolean {
+	return matchesKey(data, "escape") || matchesKey(data, "esc");
 }
 
-/**
- * Check if input matches Ctrl+O (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlO(data: string): boolean {
-	return data === RAW.CTRL_O || data === Keys.CTRL_O || matchesKittySequence(data, CODEPOINTS.o, MODIFIERS.ctrl);
+export function isEnter(data: string): boolean {
+	return matchesKey(data, "enter") || matchesKey(data, "return") || data === "\n";
 }
 
-/**
- * Check if input matches Shift+Ctrl+O (Kitty protocol only).
- * Ignores lock key bits.
- */
-export function isShiftCtrlO(data: string): boolean {
-	return matchesKittySequence(data, CODEPOINTS.o, MODIFIERS.shift + MODIFIERS.ctrl);
+export function isTab(data: string): boolean {
+	return matchesKey(data, "tab");
 }
 
-/**
- * Check if input matches Ctrl+P (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlP(data: string): boolean {
-	return data === RAW.CTRL_P || data === Keys.CTRL_P || matchesKittySequence(data, CODEPOINTS.p, MODIFIERS.ctrl);
+export function isShiftTab(data: string): boolean {
+	return matchesKey(data, "shift+tab");
 }
 
-/**
- * Check if input matches Shift+Ctrl+P (Kitty protocol only).
- * Ignores lock key bits.
- */
-export function isShiftCtrlP(data: string): boolean {
-	return matchesKittySequence(data, CODEPOINTS.p, MODIFIERS.shift + MODIFIERS.ctrl);
+export function isShiftEnter(data: string): boolean {
+	return matchesKey(data, "shift+enter");
 }
 
-/**
- * Check if input matches Shift+Ctrl+D (Kitty protocol only, for debug).
- * Ignores lock key bits.
- */
-export function isShiftCtrlD(data: string): boolean {
-	return matchesKittySequence(data, CODEPOINTS.d, MODIFIERS.shift + MODIFIERS.ctrl);
+export function isAltEnter(data: string): boolean {
+	return matchesKey(data, "alt+enter");
 }
 
-/**
- * Check if input matches Ctrl+T (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlT(data: string): boolean {
-	return data === RAW.CTRL_T || data === Keys.CTRL_T || matchesKittySequence(data, CODEPOINTS.t, MODIFIERS.ctrl);
+export function isAltBackspace(data: string): boolean {
+	return matchesKey(data, "alt+backspace");
 }
 
-/**
- * Check if input matches Ctrl+U (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlU(data: string): boolean {
-	return data === RAW.CTRL_U || data === Keys.CTRL_U || matchesKittySequence(data, CODEPOINTS.u, MODIFIERS.ctrl);
+export function isBackspace(data: string): boolean {
+	return matchesKey(data, "backspace");
 }
 
-/**
- * Check if input matches Ctrl+V (raw byte or Kitty protocol).
- * Ignores lock key bits.
- * Note: In most terminals, Ctrl+V triggers paste which sends bracketed paste markers,
- * but raw mode can intercept the key before the terminal processes it.
- */
-export function isCtrlV(data: string): boolean {
-	return data === RAW.CTRL_V || data === Keys.CTRL_V || matchesKittySequence(data, CODEPOINTS.v, MODIFIERS.ctrl);
+export function isDelete(data: string): boolean {
+	return matchesKey(data, "delete");
 }
 
-/**
- * Check if input matches Ctrl+W (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlW(data: string): boolean {
-	return data === RAW.CTRL_W || data === Keys.CTRL_W || matchesKittySequence(data, CODEPOINTS.w, MODIFIERS.ctrl);
+export function isHome(data: string): boolean {
+	return matchesKey(data, "home");
 }
 
-/**
- * Check if input matches Ctrl+Z (raw byte or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isCtrlZ(data: string): boolean {
-	return data === RAW.CTRL_Z || data === Keys.CTRL_Z || matchesKittySequence(data, CODEPOINTS.z, MODIFIERS.ctrl);
+export function isEnd(data: string): boolean {
+	return matchesKey(data, "end");
 }
 
-/**
- * Check if input matches Alt+Backspace (legacy or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isAltBackspace(data: string): boolean {
-	return (
-		data === RAW.ALT_BACKSPACE ||
-		data === Keys.ALT_BACKSPACE ||
-		matchesKittySequence(data, CODEPOINTS.backspace, MODIFIERS.alt)
-	);
+export function isCtrlA(data: string): boolean {
+	return matchesKey(data, "ctrl+a");
 }
 
-/**
- * Check if input matches Shift+Tab (legacy or Kitty protocol).
- * Ignores lock key bits.
- */
-export function isShiftTab(data: string): boolean {
-	return (
-		data === RAW.SHIFT_TAB || data === Keys.SHIFT_TAB || matchesKittySequence(data, CODEPOINTS.tab, MODIFIERS.shift)
-	);
+export function isCtrlC(data: string): boolean {
+	return matchesKey(data, "ctrl+c");
 }
 
-/**
- * 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: string): boolean {
-	return data === "\x1b" || data === `\x1b[${CODEPOINTS.escape}u` || matchesKittySequence(data, CODEPOINTS.escape, 0);
+export function isCtrlD(data: string): boolean {
+	return matchesKey(data, "ctrl+d");
 }
 
-// Arrow key virtual codepoints (negative to avoid conflicts with real codepoints)
-const ARROW_CODEPOINTS = {
-	up: -1,
-	down: -2,
-	right: -3,
-	left: -4,
-} as const;
+export function isCtrlE(data: string): boolean {
+	return matchesKey(data, "ctrl+e");
+}
 
-/**
- * Check if input matches Arrow Up key.
- * Handles both legacy (\x1b[A) and Kitty protocol with modifiers.
- */
-export function isArrowUp(data: string): boolean {
-	return data === "\x1b[A" || matchesKittySequence(data, ARROW_CODEPOINTS.up, 0);
+export function isCtrlG(data: string): boolean {
+	return matchesKey(data, "ctrl+g");
 }
 
-/**
- * Check if input matches Arrow Down key.
- * Handles both legacy (\x1b[B) and Kitty protocol with modifiers.
- */
-export function isArrowDown(data: string): boolean {
-	return data === "\x1b[B" || matchesKittySequence(data, ARROW_CODEPOINTS.down, 0);
+export function isCtrlK(data: string): boolean {
+	return matchesKey(data, "ctrl+k");
 }
 
-/**
- * Check if input matches Arrow Right key.
- * Handles both legacy (\x1b[C) and Kitty protocol with modifiers.
- */
-export function isArrowRight(data: string): boolean {
-	return data === "\x1b[C" || matchesKittySequence(data, ARROW_CODEPOINTS.right, 0);
+export function isCtrlL(data: string): boolean {
+	return matchesKey(data, "ctrl+l");
 }
 
-/**
- * Check if input matches Arrow Left key.
- * Handles both legacy (\x1b[D) and Kitty protocol with modifiers.
- */
-export function isArrowLeft(data: string): boolean {
-	return data === "\x1b[D" || matchesKittySequence(data, ARROW_CODEPOINTS.left, 0);
+export function isCtrlO(data: string): boolean {
+	return matchesKey(data, "ctrl+o");
 }
 
-/**
- * Check if input matches plain Tab key (no modifiers).
- * Handles both legacy (\t) and Kitty protocol.
- */
-export function isTab(data: string): boolean {
-	return data === "\t" || matchesKittySequence(data, CODEPOINTS.tab, 0);
+export function isCtrlP(data: string): boolean {
+	return matchesKey(data, "ctrl+p");
 }
 
-/**
- * Check if input matches plain Enter/Return key (no modifiers).
- * Handles both legacy (\r) and Kitty protocol.
- */
-export function isEnter(data: string): boolean {
-	return data === "\r" || matchesKittySequence(data, CODEPOINTS.enter, 0);
+export function isCtrlT(data: string): boolean {
+	return matchesKey(data, "ctrl+t");
 }
 
-/**
- * Check if input matches plain Backspace key (no modifiers).
- * Handles both legacy (\x7f, \x08) and Kitty protocol.
- */
-export function isBackspace(data: string): boolean {
-	return data === "\x7f" || data === "\x08" || matchesKittySequence(data, CODEPOINTS.backspace, 0);
+export function isCtrlU(data: string): boolean {
+	return matchesKey(data, "ctrl+u");
 }
 
-/**
- * Check if input matches Shift+Enter.
- * Ignores lock key bits.
- */
-export function isShiftEnter(data: string): boolean {
-	return data === Keys.SHIFT_ENTER || matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift);
+export function isCtrlV(data: string): boolean {
+	return matchesKey(data, "ctrl+v");
 }
 
-/**
- * Check if input matches Alt+Enter.
- * Ignores lock key bits.
- */
-export function isAltEnter(data: string): boolean {
-	return data === Keys.ALT_ENTER || data === "\x1b\r" || matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.alt);
+export function isCtrlW(data: string): boolean {
+	return matchesKey(data, "ctrl+w");
 }
 
-/**
- * Check if input matches Option/Alt+Left (word navigation).
- * Handles multiple formats including Kitty protocol.
- */
-export function isAltLeft(data: string): boolean {
-	return data === "\x1b[1;3D" || data === "\x1bb" || matchesKittySequence(data, ARROW_CODEPOINTS.left, MODIFIERS.alt);
+export function isCtrlY(data: string): boolean {
+	return matchesKey(data, "ctrl+y");
 }
 
-/**
- * Check if input matches Option/Alt+Right (word navigation).
- * Handles multiple formats including Kitty protocol.
- */
-export function isAltRight(data: string): boolean {
-	return data === "\x1b[1;3C" || data === "\x1bf" || matchesKittySequence(data, ARROW_CODEPOINTS.right, MODIFIERS.alt);
+export function isCtrlZ(data: string): boolean {
+	return matchesKey(data, "ctrl+z");
 }
 
-/**
- * Check if input matches Ctrl+Left (word navigation).
- * Handles multiple formats including Kitty protocol.
- */
 export function isCtrlLeft(data: string): boolean {
-	return data === "\x1b[1;5D" || matchesKittySequence(data, ARROW_CODEPOINTS.left, MODIFIERS.ctrl);
+	return matchesKey(data, "ctrl+left");
 }
 
-/**
- * Check if input matches Ctrl+Right (word navigation).
- * Handles multiple formats including Kitty protocol.
- */
 export function isCtrlRight(data: string): boolean {
-	return data === "\x1b[1;5C" || matchesKittySequence(data, ARROW_CODEPOINTS.right, MODIFIERS.ctrl);
+	return matchesKey(data, "ctrl+right");
 }
 
-/**
- * Check if input matches Home key.
- * Handles legacy formats and Kitty protocol with lock key modifiers.
- */
-export function isHome(data: string): boolean {
-	return (
-		data === "\x1b[H" ||
-		data === "\x1b[1~" ||
-		data === "\x1b[7~" ||
-		matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.home, 0)
-	);
+export function isAltLeft(data: string): boolean {
+	return matchesKey(data, "alt+left");
 }
 
-/**
- * Check if input matches End key.
- * Handles legacy formats and Kitty protocol with lock key modifiers.
- */
-export function isEnd(data: string): boolean {
-	return (
-		data === "\x1b[F" ||
-		data === "\x1b[4~" ||
-		data === "\x1b[8~" ||
-		matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.end, 0)
-	);
+export function isAltRight(data: string): boolean {
+	return matchesKey(data, "alt+right");
+}
+
+export function isShiftCtrlD(data: string): boolean {
+	return matchesKey(data, "shift+ctrl+d") || matchesKey(data, "ctrl+shift+d");
+}
+
+export function isShiftCtrlO(data: string): boolean {
+	return matchesKey(data, "shift+ctrl+o") || matchesKey(data, "ctrl+shift+o");
+}
+
+export function isShiftCtrlP(data: string): boolean {
+	return matchesKey(data, "shift+ctrl+p") || matchesKey(data, "ctrl+shift+p");
+}
+
+export function isShiftBackspace(data: string): boolean {
+	return matchesKey(data, "shift+backspace");
+}
+
+export function isShiftDelete(data: string): boolean {
+	return matchesKey(data, "shift+delete");
+}
+
+export function isShiftSpace(data: string): boolean {
+	return matchesKey(data, "shift+space");
 }
 
 /**
- * Check if input matches Delete key (forward delete).
- * Handles legacy format and Kitty protocol with lock key modifiers.
+ * Check if input indicates Caps Lock state change.
+ * Kitty protocol reports Caps Lock via modifier bit 64.
  */
-export function isDelete(data: string): boolean {
-	return data === "\x1b[3~" || matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.delete, 0);
+export function isCapsLock(data: string): boolean {
+	const parsed = parseKittySequence(data);
+	if (!parsed) return false;
+	// Caps Lock is modifier bit 64
+	return (parsed.modifier & 64) !== 0;
 }