xonecas.io
70160
Ce

cel-tui / commit 16aaec1

fix(core): handle legacy bytes for unmodified special keys at Kitty level 1

At Kitty protocol level 1, unmodified special keys that have well-known
legacy encodings retain those single-byte encodings. Only modified
variants (Shift+Tab, Ctrl+Enter, etc.) use the CSI u format.

This was causing Tab, Enter, Escape, and Backspace to be unrecognized
when sent without modifiers by Ghostty, Alacritty, and tmux.

Add legacy byte mapping in parseKey for:
- Tab (0x09), Enter (0x0D), Escape (0x1B), Backspace (0x7F)
- Shift+Tab via legacy CSI Z sequence

These are not a legacy fallback — they are the actual bytes that
Kitty-supporting terminals send at level 1 for unmodified keys.

xonecas2026-04-04 16aaec1d37c145d38c5d9a81d34e7f84557737a5 parent 251df02

3 files changed

packages/core/src/keys.test.ts+28−1
@@ -95,7 +95,29 @@ describe("parseKey", () => {
9595 });
9696 });
9797
98- // --- CSI u: special keys without modifiers ---
98+ // --- Legacy bytes for unmodified special keys ---
99+ // At Kitty level 1, unmodified special keys retain their traditional
100+ // encoding. Only modified variants get the CSI u treatment.
101+
102+ describe("legacy bytes for unmodified special keys", () => {
103+ test("tab", () => {
104+ expect(parseKey("\t")).toBe("tab");
105+ });
106+
107+ test("enter", () => {
108+ expect(parseKey("\r")).toBe("enter");
109+ });
110+
111+ test("escape", () => {
112+ expect(parseKey("\x1b")).toBe("escape");
113+ });
114+
115+ test("backspace", () => {
116+ expect(parseKey("\x7f")).toBe("backspace");
117+ });
118+ });
119+
120+ // --- CSI u: special keys (also valid, sent by some terminals) ---
99121
100122 describe("CSI u special keys", () => {
101123 test("escape", () => {
@@ -122,6 +144,11 @@ describe("parseKey", () => {
122144 expect(parseKey("\x1b[43u")).toBe("plus");
123145 });
124146
147+ test("legacy shift+tab (CSI Z)", () => {
148+ // tmux and some terminals send this instead of CSI 9;2 u
149+ expect(parseKey("\x1b[Z")).toBe("shift+tab");
150+ });
151+
125152 test("explicit modifier=1 means no modifiers", () => {
126153 expect(parseKey("\x1b[27;1u")).toBe("escape");
127154 expect(parseKey("\x1b[13;1u")).toBe("enter");
packages/core/src/keys.ts+32−3
@@ -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
spec.md+2−0
@@ -327,6 +327,8 @@ cel-tui **requires** the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kit
327327 2. All key input is parsed from the Kitty `CSI unicode-codepoint ; modifiers u` format, with fallback CSI parsing for functional keys (`CSI 1 ; modifiers <A-H>` arrows, `CSI number ; modifiers ~` function keys, etc.)
328328 3. `cel.stop()` pops the keyboard mode (`CSI < u`), restoring the terminal's previous state
329329
330+**Level 1 encoding details:** At level 1, unmodified special keys that have well-known legacy encodings (Tab, Enter, Escape, Backspace) retain those single-byte encodings. Only modified variants (e.g., Shift+Tab, Ctrl+Enter) use the CSI u format. The parser handles both paths.
331+
330332 **Supported terminals:** Kitty, WezTerm, Ghostty, foot, Alacritty, Windows Terminal, and others. macOS Terminal.app and older xterm versions do not support this protocol.
331333
332334 > **Future enhancement:** Higher protocol levels enable key-release events (`level 2`), associated text reporting (`level 3`), and full key event types (`level 4`). These would enable held-key detection for game-like UIs, distinguishing physical key layout from logical input, and other advanced input patterns. The framework may adopt higher levels in the future.