@dungle-scrubs/tallow 0.9.4 → 0.9.7

package/node_modules/@mariozechner/pi-tui/src/keys.ts

@@ -71,6 +71,8 @@ type Letter =
 	| "y"
 	| "z";
 
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+
 type SymbolKey =
 	| "`"
 	| "-"
@@ -136,29 +138,20 @@ type SpecialKey =
 	| "f11"
 	| "f12";
 
-type BaseKey = Letter | SymbolKey | SpecialKey;
+type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
+type ModifierName = "ctrl" | "shift" | "alt" | "super";
+
+type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName = ModifierName> = {
+	[M in RemainingModifiers]:
+		| `${M}+${Key}`
+		| `${M}+${ModifiedKeyId<Key, Exclude<RemainingModifiers, M>>}`;
+}[RemainingModifiers];
 
 /**
  * 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}`;
+export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
 
 /**
  * Helper object for creating typed key identifiers with autocomplete.
@@ -166,8 +159,8 @@ export type KeyId =
  * 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
+ * - Key.ctrl("c"), Key.alt("x"), Key.super("k") for single modifiers
+ * - Key.ctrlShift("p"), Key.ctrlAlt("x"), Key.ctrlSuper("k") for combined modifiers
  */
 export const Key = {
 	// Special keys
@@ -239,6 +232,7 @@ export const Key = {
 	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}`,
+	super: <K extends BaseKey>(key: K): `super+${K}` => `super+${key}`,
 
 	// Combined modifiers
 	ctrlShift: <K extends BaseKey>(key: K): `ctrl+shift+${K}` => `ctrl+shift+${key}`,
@@ -247,9 +241,16 @@ export const 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}`,
+	ctrlSuper: <K extends BaseKey>(key: K): `ctrl+super+${K}` => `ctrl+super+${key}`,
+	superCtrl: <K extends BaseKey>(key: K): `super+ctrl+${K}` => `super+ctrl+${key}`,
+	shiftSuper: <K extends BaseKey>(key: K): `shift+super+${K}` => `shift+super+${key}`,
+	superShift: <K extends BaseKey>(key: K): `super+shift+${K}` => `super+shift+${key}`,
+	altSuper: <K extends BaseKey>(key: K): `alt+super+${K}` => `alt+super+${key}`,
+	superAlt: <K extends BaseKey>(key: K): `super+alt+${K}` => `super+alt+${key}`,
 
 	// Triple modifiers
 	ctrlShiftAlt: <K extends BaseKey>(key: K): `ctrl+shift+alt+${K}` => `ctrl+shift+alt+${key}`,
+	ctrlShiftSuper: <K extends BaseKey>(key: K): `ctrl+shift+super+${K}` => `ctrl+shift+super+${key}`,
 } as const;
 
 // =============================================================================
@@ -294,6 +295,7 @@ const MODIFIERS = {
 	shift: 1,
 	alt: 2,
 	ctrl: 4,
+	super: 8,
 } as const;
 
 const LOCK_MASK = 64 + 128; // Caps Lock + Num Lock
@@ -323,6 +325,40 @@ const FUNCTIONAL_CODEPOINTS = {
 	end: -15,
 } as const;
 
+const KITTY_FUNCTIONAL_KEY_EQUIVALENTS = new Map<number, number>([
+	[57399, 48], // KP_0 -> 0
+	[57400, 49], // KP_1 -> 1
+	[57401, 50], // KP_2 -> 2
+	[57402, 51], // KP_3 -> 3
+	[57403, 52], // KP_4 -> 4
+	[57404, 53], // KP_5 -> 5
+	[57405, 54], // KP_6 -> 6
+	[57406, 55], // KP_7 -> 7
+	[57407, 56], // KP_8 -> 8
+	[57408, 57], // KP_9 -> 9
+	[57409, 46], // KP_DECIMAL -> .
+	[57410, 47], // KP_DIVIDE -> /
+	[57411, 42], // KP_MULTIPLY -> *
+	[57412, 45], // KP_SUBTRACT -> -
+	[57413, 43], // KP_ADD -> +
+	[57415, 61], // KP_EQUAL -> =
+	[57416, 44], // KP_SEPARATOR -> ,
+	[57417, ARROW_CODEPOINTS.left],
+	[57418, ARROW_CODEPOINTS.right],
+	[57419, ARROW_CODEPOINTS.up],
+	[57420, ARROW_CODEPOINTS.down],
+	[57421, FUNCTIONAL_CODEPOINTS.pageUp],
+	[57422, FUNCTIONAL_CODEPOINTS.pageDown],
+	[57423, FUNCTIONAL_CODEPOINTS.home],
+	[57424, FUNCTIONAL_CODEPOINTS.end],
+	[57425, FUNCTIONAL_CODEPOINTS.insert],
+	[57426, FUNCTIONAL_CODEPOINTS.delete],
+]);
+
+function normalizeKittyFunctionalCodepoint(codepoint: number): number {
+	return KITTY_FUNCTIONAL_KEY_EQUIVALENTS.get(codepoint) ?? codepoint;
+}
+
 const LEGACY_KEY_SEQUENCES = {
 	up: ["\x1b[A", "\x1bOA"],
 	down: ["\x1b[B", "\x1bOB"],
@@ -475,16 +511,17 @@ interface ParsedKittySequence {
 	eventType: KeyEventType;
 }
 
-// Tracks the event type from the most recent parseKey() call.
+interface ParsedModifyOtherKeysSequence {
+	codepoint: number;
+	modifier: number;
+}
+
+// Store the last parsed event type for isKeyRelease() to query
 let _lastEventType: KeyEventType = "press";
 
 /**
- * Check if the given input data represents a key release event.
- * Performs fast pattern matching on raw terminal escape sequences.
+ * Check if the last parsed key event was a key release.
  * Only meaningful when Kitty keyboard protocol with flag 2 is active.
- *
- * @param data - Raw terminal input string
- * @returns true if the data contains a key release escape sequence
  */
 export function isKeyRelease(data: string): boolean {
 	// Don't treat bracketed paste content as key release, even if it contains
@@ -513,12 +550,8 @@ export function isKeyRelease(data: string): boolean {
 }
 
 /**
- * Check if the given input data represents a key repeat event.
- * Performs fast pattern matching on raw terminal escape sequences.
+ * Check if the last parsed key event was a key repeat.
  * Only meaningful when Kitty keyboard protocol with flag 2 is active.
- *
- * @param data - Raw terminal input string
- * @returns true if the data contains a key repeat escape sequence
  */
 export function isKeyRepeat(data: string): boolean {
 	// Don't treat bracketed paste content as key repeat, even if it contains
@@ -631,8 +664,11 @@ function matchesKittySequence(
 	// Check if modifiers match
 	if (actualMod !== expectedMod) return false;
 
-	// Primary match: codepoint matches directly
-	if (parsed.codepoint === expectedCodepoint) return true;
+	const normalizedCodepoint = normalizeKittyFunctionalCodepoint(parsed.codepoint);
+	const normalizedExpectedCodepoint = normalizeKittyFunctionalCodepoint(expectedCodepoint);
+
+	// Primary match: codepoint matches directly after normalizing functional keys
+	if (normalizedCodepoint === normalizedExpectedCodepoint) return true;
 
 	// Alternate match: use base layout key for non-Latin keyboard layouts.
 	// This allows Ctrl+С (Cyrillic) to match Ctrl+c (Latin) when terminal reports
@@ -647,7 +683,7 @@ function matchesKittySequence(
 	// (letter remapping) and Ctrl+/ could falsely match Ctrl+[ (symbol remapping)
 	// if the base layout key were always considered.
 	if (parsed.baseLayoutKey !== undefined && parsed.baseLayoutKey === expectedCodepoint) {
-		const cp = parsed.codepoint;
+		const cp = normalizedCodepoint;
 		const isLatinLetter = cp >= 97 && cp <= 122; // a-z
 		const isKnownSymbol = SYMBOL_KEYS.has(String.fromCharCode(cp));
 		if (!isLatinLetter && !isKnownSymbol) return true;
@@ -656,6 +692,14 @@ function matchesKittySequence(
 	return false;
 }
 
+function parseModifyOtherKeysSequence(data: string): ParsedModifyOtherKeysSequence | null {
+	const match = data.match(/^\x1b\[27;(\d+);(\d+)~$/);
+	if (!match) return null;
+	const modValue = parseInt(match[1]!, 10);
+	const codepoint = parseInt(match[2]!, 10);
+	return { codepoint, modifier: modValue - 1 };
+}
+
 /**
  * Match xterm modifyOtherKeys format: CSI 27 ; modifiers ; keycode ~
  * This is used by terminals when Kitty protocol is not enabled.
@@ -666,21 +710,11 @@ function matchesModifyOtherKeys(
 	expectedKeycode: number,
 	expectedModifier: number
 ): boolean {
-	const match = data.match(/^\x1b\[27;(\d+);(\d+)~$/);
-	if (!match) return false;
-	const modValue = parseInt(match[1]!, 10);
-	const keycode = parseInt(match[2]!, 10);
-	// Convert from 1-indexed xterm format to our 0-indexed format
-	const actualMod = modValue - 1;
-	return keycode === expectedKeycode && actualMod === expectedModifier;
+	const parsed = parseModifyOtherKeysSequence(data);
+	if (!parsed) return false;
+	return parsed.codepoint === expectedKeycode && parsed.modifier === expectedModifier;
 }
 
-/**
- * Detect Windows Terminal by session environment variable.
- * Excludes SSH sessions where WT_SESSION may leak from the host.
- *
- * @returns true when running directly inside Windows Terminal
- */
 function isWindowsTerminalSession(): boolean {
 	return (
 		Boolean(process.env.WT_SESSION) &&
@@ -698,10 +732,6 @@ function isWindowsTerminalSession(): boolean {
  *
  * Prefer explicit Kitty / CSI-u / modifyOtherKeys sequences whenever they are
  * available. Fall back to a Windows Terminal heuristic only for raw BS bytes.
- *
- * @param data - Raw terminal input byte
- * @param expectedModifier - Modifier bitmask to match against
- * @returns true if the data matches backspace with the given modifier
  */
 function matchesRawBackspace(data: string, expectedModifier: number): boolean {
 	if (data === "\x7f") return expectedModifier === 0;
@@ -741,9 +771,34 @@ function rawCtrlChar(key: string): string | null {
 	return null;
 }
 
+function isDigitKey(key: string): boolean {
+	return key >= "0" && key <= "9";
+}
+
+function matchesPrintableModifyOtherKeys(
+	data: string,
+	expectedKeycode: number,
+	expectedModifier: number
+): boolean {
+	if (expectedModifier === 0) return false;
+	return matchesModifyOtherKeys(data, expectedKeycode, expectedModifier);
+}
+
+function formatKeyNameWithModifiers(keyName: string, modifier: number): string | undefined {
+	const mods: string[] = [];
+	const effectiveMod = modifier & ~LOCK_MASK;
+	const supportedModifierMask = MODIFIERS.shift | MODIFIERS.ctrl | MODIFIERS.alt | MODIFIERS.super;
+	if ((effectiveMod & ~supportedModifierMask) !== 0) return undefined;
+	if (effectiveMod & MODIFIERS.shift) mods.push("shift");
+	if (effectiveMod & MODIFIERS.ctrl) mods.push("ctrl");
+	if (effectiveMod & MODIFIERS.alt) mods.push("alt");
+	if (effectiveMod & MODIFIERS.super) mods.push("super");
+	return mods.length > 0 ? `${mods.join("+")}+${keyName}` : keyName;
+}
+
 function parseKeyId(
 	keyId: string
-): { key: string; ctrl: boolean; shift: boolean; alt: boolean } | null {
+): { key: string; ctrl: boolean; shift: boolean; alt: boolean; super: boolean } | null {
 	const parts = keyId.toLowerCase().split("+");
 	const key = parts[parts.length - 1];
 	if (!key) return null;
@@ -752,6 +807,7 @@ function parseKeyId(
 		ctrl: parts.includes("ctrl"),
 		shift: parts.includes("shift"),
 		alt: parts.includes("alt"),
+		super: parts.includes("super"),
 	};
 }
 
@@ -764,9 +820,10 @@ function parseKeyId(
  * - 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"
+ * - Super combinations: "super+k", "super+enter"
+ * - Combined modifiers: "shift+ctrl+p", "ctrl+alt+x", "ctrl+super+k"
  *
- * Use the Key helper for autocomplete: Key.ctrl("c"), Key.escape, Key.ctrlShift("p")
+ * Use the Key helper for autocomplete: Key.ctrl("c"), Key.escape, Key.ctrlShift("p"), Key.super("k")
  *
  * @param data - Raw input data from terminal
  * @param keyId - Key identifier (e.g., "ctrl+c", "escape", Key.ctrl("c"))
@@ -775,11 +832,12 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 	const parsed = parseKeyId(keyId);
 	if (!parsed) return false;
 
-	const { key, ctrl, shift, alt } = parsed;
+	const { key, ctrl, shift, alt, super: superModifier } = parsed;
 	let modifier = 0;
 	if (shift) modifier |= MODIFIERS.shift;
 	if (alt) modifier |= MODIFIERS.alt;
 	if (ctrl) modifier |= MODIFIERS.ctrl;
+	if (superModifier) modifier |= MODIFIERS.super;
 
 	switch (key) {
 		case "escape":
@@ -793,10 +851,10 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 
 		case "space":
 			if (!_kittyProtocolActive) {
-				if (ctrl && !alt && !shift && data === "\x00") {
+				if (modifier === MODIFIERS.ctrl && data === "\x00") {
 					return true;
 				}
-				if (alt && !ctrl && !shift && data === "\x1b ") {
+				if (modifier === MODIFIERS.alt && data === "\x1b ") {
 					return true;
 				}
 			}
@@ -813,8 +871,12 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			);
 
 		case "tab":
-			if (shift && !ctrl && !alt) {
-				return data === "\x1b[Z" || matchesKittySequence(data, CODEPOINTS.tab, MODIFIERS.shift);
+			if (modifier === MODIFIERS.shift) {
+				return (
+					data === "\x1b[Z" ||
+					matchesKittySequence(data, CODEPOINTS.tab, MODIFIERS.shift) ||
+					matchesModifyOtherKeys(data, CODEPOINTS.tab, MODIFIERS.shift)
+				);
 			}
 			if (modifier === 0) {
 				return data === "\t" || matchesKittySequence(data, CODEPOINTS.tab, 0);
@@ -826,7 +888,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 
 		case "enter":
 		case "return":
-			if (shift && !ctrl && !alt) {
+			if (modifier === MODIFIERS.shift) {
 				// CSI u sequences (standard Kitty protocol)
 				if (
 					matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift) ||
@@ -846,7 +908,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 				}
 				return false;
 			}
-			if (alt && !ctrl && !shift) {
+			if (modifier === MODIFIERS.alt) {
 				// CSI u sequences (standard Kitty protocol)
 				if (
 					matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.alt) ||
@@ -881,7 +943,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			);
 
 		case "backspace":
-			if (alt && !ctrl && !shift) {
+			if (modifier === MODIFIERS.alt) {
 				if (data === "\x1b\x7f" || data === "\x1b\b") {
 					return true;
 				}
@@ -890,7 +952,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 					matchesModifyOtherKeys(data, CODEPOINTS.backspace, MODIFIERS.alt)
 				);
 			}
-			if (ctrl && !alt && !shift) {
+			if (modifier === MODIFIERS.ctrl) {
 				// Legacy raw 0x08 is ambiguous: it can be Ctrl+Backspace on Windows
 				// Terminal or plain Backspace on other terminals, while also
 				// overlapping with Ctrl+H.
@@ -991,7 +1053,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			return matchesKittySequence(data, FUNCTIONAL_CODEPOINTS.pageDown, modifier);
 
 		case "up":
-			if (alt && !ctrl && !shift) {
+			if (modifier === MODIFIERS.alt) {
 				return data === "\x1bp" || matchesKittySequence(data, ARROW_CODEPOINTS.up, MODIFIERS.alt);
 			}
 			if (modifier === 0) {
@@ -1006,7 +1068,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			return matchesKittySequence(data, ARROW_CODEPOINTS.up, modifier);
 
 		case "down":
-			if (alt && !ctrl && !shift) {
+			if (modifier === MODIFIERS.alt) {
 				return data === "\x1bn" || matchesKittySequence(data, ARROW_CODEPOINTS.down, MODIFIERS.alt);
 			}
 			if (modifier === 0) {
@@ -1021,7 +1083,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			return matchesKittySequence(data, ARROW_CODEPOINTS.down, modifier);
 
 		case "left":
-			if (alt && !ctrl && !shift) {
+			if (modifier === MODIFIERS.alt) {
 				return (
 					data === "\x1b[1;3D" ||
 					(!_kittyProtocolActive && data === "\x1bB") ||
@@ -1029,7 +1091,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 					matchesKittySequence(data, ARROW_CODEPOINTS.left, MODIFIERS.alt)
 				);
 			}
-			if (ctrl && !alt && !shift) {
+			if (modifier === MODIFIERS.ctrl) {
 				return (
 					data === "\x1b[1;5D" ||
 					matchesLegacyModifierSequence(data, "left", MODIFIERS.ctrl) ||
@@ -1048,7 +1110,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 			return matchesKittySequence(data, ARROW_CODEPOINTS.left, modifier);
 
 		case "right":
-			if (alt && !ctrl && !shift) {
+			if (modifier === MODIFIERS.alt) {
 				return (
 					data === "\x1b[1;3C" ||
 					(!_kittyProtocolActive && data === "\x1bF") ||
@@ -1056,7 +1118,7 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 					matchesKittySequence(data, ARROW_CODEPOINTS.right, MODIFIERS.alt)
 				);
 			}
-			if (ctrl && !alt && !shift) {
+			if (modifier === MODIFIERS.ctrl) {
 				return (
 					data === "\x1b[1;5C" ||
 					matchesLegacyModifierSequence(data, "right", MODIFIERS.ctrl) ||
@@ -1094,50 +1156,54 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
 		}
 	}
 
-	// Handle single letter keys (a-z) and some symbols
-	if (key.length === 1 && ((key >= "a" && key <= "z") || SYMBOL_KEYS.has(key))) {
+	// Handle single letter/digit keys and symbols
+	if (key.length === 1 && ((key >= "a" && key <= "z") || isDigitKey(key) || SYMBOL_KEYS.has(key))) {
 		const codepoint = key.charCodeAt(0);
 		const rawCtrl = rawCtrlChar(key);
-
-		if (ctrl && alt && !shift && !_kittyProtocolActive && rawCtrl) {
-			// Legacy: ctrl+alt+key is ESC followed by the control character
-			return data === `\x1b${rawCtrl}`;
+		const isLetter = key >= "a" && key <= "z";
+		const isDigit = isDigitKey(key);
+
+		if (modifier === MODIFIERS.ctrl + MODIFIERS.alt && !_kittyProtocolActive && rawCtrl) {
+			// Legacy: ctrl+alt+key is ESC followed by the control character.
+			// If that legacy form does not match, continue so CSI-u and
+			// modifyOtherKeys sequences from tmux can still be recognized.
+			if (data === `\x1b${rawCtrl}`) return true;
 		}
 
-		if (alt && !ctrl && !shift && !_kittyProtocolActive && key >= "a" && key <= "z") {
-			// Legacy: alt+letter is ESC followed by the letter
+		if (modifier === MODIFIERS.alt && !_kittyProtocolActive && (isLetter || isDigit)) {
+			// Legacy: alt+letter/digit is ESC followed by the key
 			if (data === `\x1b${key}`) return true;
 		}
 
-		if (ctrl && !shift && !alt) {
+		if (modifier === MODIFIERS.ctrl) {
 			// Legacy: ctrl+key sends the control character
 			if (rawCtrl && data === rawCtrl) return true;
 			return (
 				matchesKittySequence(data, codepoint, MODIFIERS.ctrl) ||
-				matchesModifyOtherKeys(data, codepoint, MODIFIERS.ctrl)
+				matchesPrintableModifyOtherKeys(data, codepoint, MODIFIERS.ctrl)
 			);
 		}
 
-		if (ctrl && shift && !alt) {
+		if (modifier === MODIFIERS.shift + MODIFIERS.ctrl) {
 			return (
 				matchesKittySequence(data, codepoint, MODIFIERS.shift + MODIFIERS.ctrl) ||
-				matchesModifyOtherKeys(data, codepoint, MODIFIERS.shift + MODIFIERS.ctrl)
+				matchesPrintableModifyOtherKeys(data, codepoint, MODIFIERS.shift + MODIFIERS.ctrl)
 			);
 		}
 
-		if (shift && !ctrl && !alt) {
+		if (modifier === MODIFIERS.shift) {
 			// Legacy: shift+letter produces uppercase
-			if (data === key.toUpperCase()) return true;
+			if (isLetter && data === key.toUpperCase()) return true;
 			return (
 				matchesKittySequence(data, codepoint, MODIFIERS.shift) ||
-				matchesModifyOtherKeys(data, codepoint, MODIFIERS.shift)
+				matchesPrintableModifyOtherKeys(data, codepoint, MODIFIERS.shift)
 			);
 		}
 
 		if (modifier !== 0) {
 			return (
 				matchesKittySequence(data, codepoint, modifier) ||
-				matchesModifyOtherKeys(data, codepoint, modifier)
+				matchesPrintableModifyOtherKeys(data, codepoint, modifier)
 			);
 		}
 
@@ -1154,51 +1220,63 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
  * @param data - Raw input data from terminal
  * @returns Key identifier string (e.g., "ctrl+c") or undefined
  */
+function formatParsedKey(
+	codepoint: number,
+	modifier: number,
+	baseLayoutKey?: number
+): string | undefined {
+	const normalizedCodepoint = normalizeKittyFunctionalCodepoint(codepoint);
+
+	// Use base layout key only when codepoint is not a recognized Latin
+	// letter (a-z), digit (0-9), or symbol (/, -, [, ;, etc.). For those,
+	// the codepoint is authoritative regardless of physical key position.
+	// This prevents remapped layouts (Dvorak, Colemak, xremap, etc.) from
+	// reporting the wrong key name based on the QWERTY physical position.
+	const isLatinLetter = normalizedCodepoint >= 97 && normalizedCodepoint <= 122; // a-z
+	const isDigit = normalizedCodepoint >= 48 && normalizedCodepoint <= 57; // 0-9
+	const isKnownSymbol = SYMBOL_KEYS.has(String.fromCharCode(normalizedCodepoint));
+	const effectiveCodepoint =
+		isLatinLetter || isDigit || isKnownSymbol
+			? normalizedCodepoint
+			: (baseLayoutKey ?? normalizedCodepoint);
+
+	let keyName: string | undefined;
+	if (effectiveCodepoint === CODEPOINTS.escape) keyName = "escape";
+	else if (effectiveCodepoint === CODEPOINTS.tab) keyName = "tab";
+	else if (effectiveCodepoint === CODEPOINTS.enter || effectiveCodepoint === CODEPOINTS.kpEnter)
+		keyName = "enter";
+	else if (effectiveCodepoint === CODEPOINTS.space) keyName = "space";
+	else if (effectiveCodepoint === CODEPOINTS.backspace) keyName = "backspace";
+	else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.delete) keyName = "delete";
+	else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.insert) keyName = "insert";
+	else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.home) keyName = "home";
+	else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.end) keyName = "end";
+	else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.pageUp) keyName = "pageUp";
+	else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.pageDown) keyName = "pageDown";
+	else if (effectiveCodepoint === ARROW_CODEPOINTS.up) keyName = "up";
+	else if (effectiveCodepoint === ARROW_CODEPOINTS.down) keyName = "down";
+	else if (effectiveCodepoint === ARROW_CODEPOINTS.left) keyName = "left";
+	else if (effectiveCodepoint === ARROW_CODEPOINTS.right) keyName = "right";
+	else if (effectiveCodepoint >= 48 && effectiveCodepoint <= 57)
+		keyName = String.fromCharCode(effectiveCodepoint);
+	else if (effectiveCodepoint >= 97 && effectiveCodepoint <= 122)
+		keyName = String.fromCharCode(effectiveCodepoint);
+	else if (SYMBOL_KEYS.has(String.fromCharCode(effectiveCodepoint)))
+		keyName = String.fromCharCode(effectiveCodepoint);
+
+	if (!keyName) return undefined;
+	return formatKeyNameWithModifiers(keyName, modifier);
+}
+
 export function parseKey(data: string): string | undefined {
 	const kitty = parseKittySequence(data);
 	if (kitty) {
-		const { codepoint, baseLayoutKey, 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");
-
-		// Use base layout key only when codepoint is not a recognized Latin
-		// letter (a-z) or symbol (/, -, [, ;, etc.). For those, the codepoint
-		// is authoritative regardless of physical key position. This prevents
-		// remapped layouts (Dvorak, Colemak, xremap, etc.) from reporting the
-		// wrong key name based on the QWERTY physical position.
-		const isLatinLetter = codepoint >= 97 && codepoint <= 122; // a-z
-		const isKnownSymbol = SYMBOL_KEYS.has(String.fromCharCode(codepoint));
-		const effectiveCodepoint =
-			isLatinLetter || isKnownSymbol ? codepoint : (baseLayoutKey ?? codepoint);
-
-		let keyName: string | undefined;
-		if (effectiveCodepoint === CODEPOINTS.escape) keyName = "escape";
-		else if (effectiveCodepoint === CODEPOINTS.tab) keyName = "tab";
-		else if (effectiveCodepoint === CODEPOINTS.enter || effectiveCodepoint === CODEPOINTS.kpEnter)
-			keyName = "enter";
-		else if (effectiveCodepoint === CODEPOINTS.space) keyName = "space";
-		else if (effectiveCodepoint === CODEPOINTS.backspace) keyName = "backspace";
-		else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.delete) keyName = "delete";
-		else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.insert) keyName = "insert";
-		else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.home) keyName = "home";
-		else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.end) keyName = "end";
-		else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.pageUp) keyName = "pageUp";
-		else if (effectiveCodepoint === FUNCTIONAL_CODEPOINTS.pageDown) keyName = "pageDown";
-		else if (effectiveCodepoint === ARROW_CODEPOINTS.up) keyName = "up";
-		else if (effectiveCodepoint === ARROW_CODEPOINTS.down) keyName = "down";
-		else if (effectiveCodepoint === ARROW_CODEPOINTS.left) keyName = "left";
-		else if (effectiveCodepoint === ARROW_CODEPOINTS.right) keyName = "right";
-		else if (effectiveCodepoint >= 97 && effectiveCodepoint <= 122)
-			keyName = String.fromCharCode(effectiveCodepoint);
-		else if (SYMBOL_KEYS.has(String.fromCharCode(effectiveCodepoint)))
-			keyName = String.fromCharCode(effectiveCodepoint);
-
-		if (keyName) {
-			return mods.length > 0 ? `${mods.join("+")}+${keyName}` : keyName;
-		}
+		return formatParsedKey(kitty.codepoint, kitty.modifier, kitty.baseLayoutKey);
+	}
+
+	const modifyOtherKeys = parseModifyOtherKeysSequence(data);
+	if (modifyOtherKeys) {
+		return formatParsedKey(modifyOtherKeys.codepoint, modifyOtherKeys.modifier);
 	}
 
 	// Mode-aware legacy sequences
@@ -1239,8 +1317,8 @@ export function parseKey(data: string): string | undefined {
 		if (code >= 1 && code <= 26) {
 			return `ctrl+alt+${String.fromCharCode(code + 96)}`;
 		}
-		// Legacy alt+letter (ESC followed by letter a-z)
-		if (code >= 97 && code <= 122) {
+		// Legacy alt+letter/digit (ESC followed by the key)
+		if ((code >= 97 && code <= 122) || (code >= 48 && code <= 57)) {
 			return `alt+${String.fromCharCode(code)}`;
 		}
 	}
@@ -1269,63 +1347,57 @@ export function parseKey(data: string): string | undefined {
 }
 
 // =============================================================================
-// Mouse Event Parsing
+// Kitty CSI-u Printable Decoding
 // =============================================================================
 
-/**
- * Parsed mouse event from SGR extended format.
- * SGR format: \x1b[<button;column;row[Mm]
- * M = press, m = release
- */
-export interface MouseEvent {
-	/** Event type */
-	type: "scroll-up" | "scroll-down" | "press" | "release" | "drag";
-	/** 0=left, 1=middle, 2=right */
-	button: number;
-	/** 1-indexed column */
-	x: number;
-	/** 1-indexed row */
-	y: number;
-}
-
-/** SGR extended mouse format: \x1b[<button;x;y[Mm] */
-const SGR_MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/;
+const KITTY_CSI_U_REGEX = /^\x1b\[(\d+)(?::(\d*))?(?::(\d+))?(?:;(\d+))?(?::(\d+))?u$/;
+const KITTY_PRINTABLE_ALLOWED_MODIFIERS = MODIFIERS.shift | LOCK_MASK;
 
 /**
- * Parse an SGR mouse event from raw terminal input.
+ * Decode a Kitty CSI-u sequence into a printable character, if applicable.
  *
- * @param data - Raw terminal input
- * @returns Parsed mouse event, or null if not a mouse sequence
- */
-export function parseMouseEvent(data: string): MouseEvent | null {
-	const match = data.match(SGR_MOUSE_RE);
-	if (!match) return null;
-
-	const code = parseInt(match[1]!, 10);
-	const x = parseInt(match[2]!, 10);
-	const y = parseInt(match[3]!, 10);
-	const isRelease = match[4] === "m";
-
-	// Scroll wheel: codes 64 (up) and 65 (down)
-	if (code === 64) return { type: "scroll-up", button: 0, x, y };
-	if (code === 65) return { type: "scroll-down", button: 0, x, y };
-
-	// Button number is in the low 2 bits
-	const button = code & 0x03;
-
-	// Bit 5 (32) = motion/drag
-	if (code & 32) return { type: "drag", button, x, y };
-
-	return { type: isRelease ? "release" : "press", button, x, y };
-}
-
-/**
- * Fast check: is this data an SGR mouse event?
- * Avoids regex for non-mouse input.
+ * When Kitty keyboard protocol flag 1 (disambiguate) is active, terminals send
+ * CSI-u sequences for all keys, including plain printable characters. This
+ * function extracts the printable character from such sequences.
+ *
+ * Only accepts plain or Shift-modified keys. Rejects Ctrl, Alt, and unsupported
+ * modifier combinations (those are handled by keybinding matching instead).
+ * Prefers the shifted keycode when Shift is held and a shifted key is reported.
  *
- * @param data - Raw terminal input
- * @returns true if the input is an SGR mouse sequence
+ * @param data - Raw input data from terminal
+ * @returns The printable character, or undefined if not a printable CSI-u sequence
  */
-export function isMouseEvent(data: string): boolean {
-	return data.length >= 9 && data.startsWith("\x1b[<");
+export function decodeKittyPrintable(data: string): string | undefined {
+	const match = data.match(KITTY_CSI_U_REGEX);
+	if (!match) return undefined;
+
+	// CSI-u groups: <codepoint>[:<shifted>[:<base>]];<mod>[:<event>]u
+	const codepoint = Number.parseInt(match[1] ?? "", 10);
+	if (!Number.isFinite(codepoint)) return undefined;
+
+	const shiftedKey = match[2] && match[2].length > 0 ? Number.parseInt(match[2], 10) : undefined;
+	const modValue = match[4] ? Number.parseInt(match[4], 10) : 1;
+	// Modifiers are 1-indexed in CSI-u; normalize to our bitmask.
+	const modifier = Number.isFinite(modValue) ? modValue - 1 : 0;
+
+	// Only accept printable CSI-u input for plain or Shift-modified text keys.
+	// Reject unsupported modifier bits (e.g. Super/Meta) to avoid inserting
+	// characters from modifier-only terminal events.
+	if ((modifier & ~KITTY_PRINTABLE_ALLOWED_MODIFIERS) !== 0) return undefined;
+	if (modifier & (MODIFIERS.alt | MODIFIERS.ctrl)) return undefined;
+
+	// Prefer the shifted keycode when Shift is held.
+	let effectiveCodepoint = codepoint;
+	if (modifier & MODIFIERS.shift && typeof shiftedKey === "number") {
+		effectiveCodepoint = shiftedKey;
+	}
+	effectiveCodepoint = normalizeKittyFunctionalCodepoint(effectiveCodepoint);
+	// Drop control characters or invalid codepoints.
+	if (!Number.isFinite(effectiveCodepoint) || effectiveCodepoint < 32) return undefined;
+
+	try {
+		return String.fromCodePoint(effectiveCodepoint);
+	} catch {
+		return undefined;
+	}
 }