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}