xonecas.io
70160
Ce

cel-tui / files

cel-tui / packages / core / src / test-helpers.ts

4.4 KB
1/**
2 * Test-only utilities for generating Kitty keyboard protocol byte sequences.
3 * NOT exported from the package — excluded via package.json `files` field.
4 */
5
6import { type Cel, cel as publicCel } from "./cel.js";
7import type { CellBuffer } from "./cell-buffer.js";
8
9/** Test-only view of runtime synchronization and buffer inspection hooks. */
10export const testCel = publicCel as Cel & {
11  _getBuffer(): CellBuffer | null;
12  _flush(): Promise<void>;
13};
14
15/**
16 * Encode a human-readable key string into the byte sequence a Kitty-protocol
17 * terminal would send with baseline escape-code disambiguation enabled.
18 *
19 * With baseline disambiguation only:
20 * - Unmodified printable chars → raw byte
21 * - Special/ambiguous keys (Escape, Enter, Tab, Backspace) → CSI u format
22 * - Modified keys → CSI u (printable/special) or CSI with modifier param (arrows/tilde)
23 * - Arrows/Home/End → legacy CSI letter format (modifier param added when modified)
24 * - Delete/PageUp/PageDown/F-keys → legacy CSI tilde format (modifier param when modified)
25 *
26 * Kitty modifier bitmask: shift=1, alt=2, ctrl=4. Wire value = bitmask + 1.
27 *
28 * @example
29 * kittyEncode("a")           // "a"           (raw byte)
30 * kittyEncode("ctrl+s")      // "\x1b[115;5u" (CSI u, codepoint 115, modifier 5)
31 * kittyEncode("escape")      // "\x1b[27u"    (CSI u, codepoint 27)
32 * kittyEncode("ctrl+up")     // "\x1b[1;5A"   (CSI letter with modifier)
33 * kittyEncode("shift+delete") // "\x1b[3;2~"  (CSI tilde with modifier)
34 */
35export function kittyEncode(key: string): string {
36  const parts = key.toLowerCase().split("+");
37  const base = parts.at(-1);
38  if (!base) {
39    throw new Error("kittyEncode: empty key");
40  }
41  const mods = parts.slice(0, -1);
42
43  let modBits = 0;
44  if (mods.includes("shift")) modBits |= 1;
45  if (mods.includes("alt")) modBits |= 2;
46  if (mods.includes("ctrl")) modBits |= 4;
47  const modParam = modBits > 0 ? modBits + 1 : 0;
48
49  // Named special keys → CSI u format (ambiguous in legacy encoding)
50  const csiUKeys: Record<string, number> = {
51    escape: 27,
52    enter: 13,
53    tab: 9,
54    backspace: 127,
55  };
56
57  if (base in csiUKeys) {
58    const cp = csiUKeys[base];
59    if (cp === undefined) {
60      throw new Error(`kittyEncode: missing CSI-u mapping for ${base}`);
61    }
62    if (modParam > 0) return `\x1b[${cp};${modParam}u`;
63    return `\x1b[${cp}u`;
64  }
65
66  // Arrow keys and Home/End → CSI letter format
67  const letterKeys: Record<string, string> = {
68    up: "A",
69    down: "B",
70    right: "C",
71    left: "D",
72    home: "H",
73    end: "F",
74  };
75
76  if (base in letterKeys) {
77    const letter = letterKeys[base];
78    if (letter === undefined) {
79      throw new Error(`kittyEncode: missing CSI-letter mapping for ${base}`);
80    }
81    if (modParam > 0) return `\x1b[1;${modParam}${letter}`;
82    return `\x1b[${letter}`;
83  }
84
85  // Tilde keys (unambiguous legacy format)
86  const tildeKeys: Record<string, number> = {
87    delete: 3,
88    pageup: 5,
89    pagedown: 6,
90  };
91
92  if (base in tildeKeys) {
93    const num = tildeKeys[base];
94    if (num === undefined) {
95      throw new Error(`kittyEncode: missing CSI-tilde mapping for ${base}`);
96    }
97    if (modParam > 0) return `\x1b[${num};${modParam}~`;
98    return `\x1b[${num}~`;
99  }
100
101  // Function keys (tilde format)
102  const fnKeys: Record<string, number> = {
103    f1: 11,
104    f2: 12,
105    f3: 13,
106    f4: 14,
107    f5: 15,
108    f6: 17,
109    f7: 18,
110    f8: 19,
111    f9: 20,
112    f10: 21,
113    f11: 23,
114    f12: 24,
115  };
116
117  if (base in fnKeys) {
118    const num = fnKeys[base];
119    if (num === undefined) {
120      throw new Error(`kittyEncode: missing function-key mapping for ${base}`);
121    }
122    if (modParam > 0) return `\x1b[${num};${modParam}~`;
123    return `\x1b[${num}~`;
124  }
125
126  // Named keys that map to printable codepoints
127  const namedPrintable: Record<string, [number, string]> = {
128    space: [32, " "],
129    plus: [43, "+"],
130  };
131
132  if (base in namedPrintable) {
133    const named = namedPrintable[base];
134    if (named === undefined) {
135      throw new Error(`kittyEncode: missing printable mapping for ${base}`);
136    }
137    const [cp, raw] = named;
138    if (modParam > 0) return `\x1b[${cp};${modParam}u`;
139    return raw; // Unmodified → raw byte (not ambiguous)
140  }
141
142  // Single printable character
143  if (base.length === 1) {
144    const cp = base.charCodeAt(0);
145    if (modParam > 0) return `\x1b[${cp};${modParam}u`;
146    return base; // Raw byte for unmodified
147  }
148
149  throw new Error(`kittyEncode: unknown key "${key}"`);
150}