@@ -2,12 +2,14 @@
22 * Key parsing for the Kitty keyboard protocol (level 1 — disambiguate).
33 *
44 * At level 1, the terminal sends:
5- * - **CSI u** (`ESC [ codepoint ; modifiers u`) for keys that were ambiguous
6- * in legacy encoding (Escape, Enter, Tab, Backspace, Ctrl+letter, Alt+letter, etc.)
5+ * - **CSI u** (`ESC [ codepoint ; modifiers u`) for modified special keys
6+ * and modifier combos (Ctrl+letter, Alt+letter, Shift+Tab, Ctrl+Enter, etc.)
77 * - **CSI letter** (`ESC [ A/B/C/D/H/F` or `ESC [ 1 ; modifiers letter`) for
88 * arrow keys and Home/End
99 * - **CSI tilde** (`ESC [ number ~` or `ESC [ number ; modifiers ~`) for
1010 * Delete, PageUp, PageDown, and function keys
11+ * - **Legacy bytes** for unmodified special keys (Tab=0x09, Enter=0x0D,
12+ * Escape=0x1B, Backspace=0x7F) — these retain their traditional encoding
1113 * - **Raw bytes** for unmodified printable characters
1214 *
1315 * Modifier bitmask (wire value = bitmask + 1):
@@ -57,6 +59,21 @@ const TILDE_NAMES: Record<number, string> = {
5759 24: "f12",
5860 };
5961
62+/**
63+ * Legacy byte → named key mapping for unmodified special keys.
64+ *
65+ * At Kitty level 1, unmodified special keys that have well-known legacy
66+ * encodings retain those encodings. Only modified variants (e.g., Shift+Tab,
67+ * Ctrl+Enter) get the CSI u treatment. These mappings handle the legacy
68+ * bytes that arrive for the unmodified case.
69+ */
70+const LEGACY_BYTE_NAMES: Record<number, string> = {
71+ 9: "tab", // \t — also Ctrl+I in legacy, but at level 1 Ctrl+I → CSI u
72+ 13: "enter", // \r — also Ctrl+M in legacy, but at level 1 Ctrl+M → CSI u
73+ 27: "escape", // \x1b — bare ESC byte
74+ 127: "backspace", // \x7f — DEL byte
75+};
76+
6077 /** Raw printable characters that map to named keys. */
6178 const CHAR_NAMES: Record<string, string> = {
6279 " ": "space",
@@ -101,6 +118,9 @@ const CSI_LETTER_RE = /^(?:1;(\d+))?([A-H])$/;
101118 const CSI_TILDE_RE = /^(\d+)(?:;(\d+))?~$/;
102119
103120 function parseCsiSequence(seq: string): string {
121+ // Legacy Shift+Tab (CSI Z) — sent by tmux and some terminals
122+ if (seq === "Z") return "shift+tab";
123+
104124 // CSI u format: codepoint [; modifiers] u
105125 let match = CSI_U_RE.exec(seq);
106126 if (match) {
@@ -157,10 +177,19 @@ export function parseKey(data: string): string {
157177 return parseCsiSequence(data.slice(2));
158178 }
159179
160- // Single-character input: raw printable characters at level 1
180+ // Single-character input
161181 if (data.length === 1) {
182+ const code = data.charCodeAt(0);
183+
184+ // Legacy bytes for unmodified special keys (Kitty level 1 retains these)
185+ const legacy = LEGACY_BYTE_NAMES[code];
186+ if (legacy) return legacy;
187+
188+ // Named printable characters
162189 const named = CHAR_NAMES[data];
163190 if (named) return named;
191+
192+ // Printable characters — return lowercase
164193 return data.toLowerCase();
165194 }
166195