|
1 | 1 | import { test, expect } from "bun:test" |
2 | 2 | import { buildKittyKeyboardFlags } from "../renderer" |
3 | 3 |
|
| 4 | +// Kitty Keyboard Protocol progressive enhancement flags |
| 5 | +// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement |
| 6 | +const KITTY_FLAG_DISAMBIGUATE = 0b1 // Report disambiguated escape codes |
| 7 | +const KITTY_FLAG_EVENT_TYPES = 0b10 // Report event types (press/repeat/release) |
| 8 | +const KITTY_FLAG_ALTERNATE_KEYS = 0b100 // Report alternate keys (e.g., numpad vs regular) |
| 9 | +const KITTY_FLAG_ALL_KEYS_AS_ESCAPES = 0b1000 // Report all keys as escape codes |
| 10 | +const KITTY_FLAG_REPORT_TEXT = 0b10000 // Report text associated with key events |
| 11 | + |
4 | 12 | test("buildKittyKeyboardFlags - null/undefined returns 0", () => { |
5 | 13 | expect(buildKittyKeyboardFlags(null)).toBe(0) |
6 | 14 | expect(buildKittyKeyboardFlags(undefined)).toBe(0) |
7 | 15 | }) |
8 | 16 |
|
9 | | -test("buildKittyKeyboardFlags - empty object returns 0b0001", () => { |
10 | | - // Default behavior: alternate keys only |
11 | | - expect(buildKittyKeyboardFlags({})).toBe(0b0001) |
| 17 | +test("buildKittyKeyboardFlags - empty object returns DISAMBIGUATE | ALTERNATE_KEYS (0b101)", () => { |
| 18 | + // Default behavior: disambiguate + alternate keys |
| 19 | + // - Disambiguate fixes ESC timing issues, alt+key ambiguity, makes ctrl+c a key event |
| 20 | + // - Alternate keys enables shifted/base-layout keys for robust shortcut matching |
| 21 | + const expected = KITTY_FLAG_DISAMBIGUATE | KITTY_FLAG_ALTERNATE_KEYS |
| 22 | + expect(buildKittyKeyboardFlags({})).toBe(expected) |
| 23 | + expect(buildKittyKeyboardFlags({})).toBe(0b101) |
| 24 | + expect(buildKittyKeyboardFlags({})).toBe(5) |
| 25 | +}) |
| 26 | + |
| 27 | +test("buildKittyKeyboardFlags - events: false returns DISAMBIGUATE | ALTERNATE_KEYS (0b101)", () => { |
| 28 | + // Explicit no events: disambiguate + alternate keys |
| 29 | + const expected = KITTY_FLAG_DISAMBIGUATE | KITTY_FLAG_ALTERNATE_KEYS |
| 30 | + expect(buildKittyKeyboardFlags({ events: false })).toBe(expected) |
| 31 | + expect(buildKittyKeyboardFlags({ events: false })).toBe(0b101) |
| 32 | + expect(buildKittyKeyboardFlags({ events: false })).toBe(5) |
| 33 | +}) |
| 34 | + |
| 35 | +test("buildKittyKeyboardFlags - events: true returns DISAMBIGUATE | ALTERNATE_KEYS | EVENT_TYPES (0b111)", () => { |
| 36 | + // With event types: disambiguate + alternate keys + event types (press/repeat/release) |
| 37 | + const expected = KITTY_FLAG_DISAMBIGUATE | KITTY_FLAG_ALTERNATE_KEYS | KITTY_FLAG_EVENT_TYPES |
| 38 | + expect(buildKittyKeyboardFlags({ events: true })).toBe(expected) |
| 39 | + expect(buildKittyKeyboardFlags({ events: true })).toBe(0b111) |
| 40 | + expect(buildKittyKeyboardFlags({ events: true })).toBe(7) |
| 41 | +}) |
| 42 | + |
| 43 | +test("buildKittyKeyboardFlags - flag values match kitty spec constants", () => { |
| 44 | + // Default: disambiguate + alternate keys |
| 45 | + expect(buildKittyKeyboardFlags({})).toBe(KITTY_FLAG_DISAMBIGUATE | KITTY_FLAG_ALTERNATE_KEYS) |
| 46 | + |
| 47 | + // With events: disambiguate + alternate keys + event types |
| 48 | + expect(buildKittyKeyboardFlags({ events: true })).toBe( |
| 49 | + KITTY_FLAG_DISAMBIGUATE | KITTY_FLAG_ALTERNATE_KEYS | KITTY_FLAG_EVENT_TYPES, |
| 50 | + ) |
| 51 | +}) |
| 52 | + |
| 53 | +test("kitty flag constants match spec bit positions", () => { |
| 54 | + // Verify our constants match the kitty keyboard protocol spec |
| 55 | + // https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement |
| 56 | + expect(KITTY_FLAG_DISAMBIGUATE).toBe(1) |
| 57 | + expect(KITTY_FLAG_EVENT_TYPES).toBe(2) |
| 58 | + expect(KITTY_FLAG_ALTERNATE_KEYS).toBe(4) |
| 59 | + expect(KITTY_FLAG_ALL_KEYS_AS_ESCAPES).toBe(8) |
| 60 | + expect(KITTY_FLAG_REPORT_TEXT).toBe(16) |
12 | 61 | }) |
13 | 62 |
|
14 | | -test("buildKittyKeyboardFlags - events: false returns 0b0001", () => { |
15 | | - // Explicit no events: alternate keys only |
16 | | - expect(buildKittyKeyboardFlags({ events: false })).toBe(0b0001) |
| 63 | +test("flag bit positions are correct powers of 2", () => { |
| 64 | + // Each flag should be a distinct bit |
| 65 | + expect(KITTY_FLAG_DISAMBIGUATE).toBe(1 << 0) |
| 66 | + expect(KITTY_FLAG_EVENT_TYPES).toBe(1 << 1) |
| 67 | + expect(KITTY_FLAG_ALTERNATE_KEYS).toBe(1 << 2) |
| 68 | + expect(KITTY_FLAG_ALL_KEYS_AS_ESCAPES).toBe(1 << 3) |
| 69 | + expect(KITTY_FLAG_REPORT_TEXT).toBe(1 << 4) |
17 | 70 | }) |
18 | 71 |
|
19 | | -test("buildKittyKeyboardFlags - events: true returns 0b0011", () => { |
20 | | - // With event types: alternate keys + event types |
21 | | - expect(buildKittyKeyboardFlags({ events: true })).toBe(0b0011) |
| 72 | +test("flags can be combined with bitwise OR", () => { |
| 73 | + // Verify flags can be combined properly |
| 74 | + const combined = KITTY_FLAG_ALTERNATE_KEYS | KITTY_FLAG_EVENT_TYPES |
| 75 | + expect(combined).toBe(0b110) |
| 76 | + expect(combined).toBe(6) |
| 77 | + |
| 78 | + // Check individual bits are set |
| 79 | + expect(combined & KITTY_FLAG_ALTERNATE_KEYS).toBeTruthy() |
| 80 | + expect(combined & KITTY_FLAG_EVENT_TYPES).toBeTruthy() |
| 81 | + expect(combined & KITTY_FLAG_DISAMBIGUATE).toBeFalsy() |
| 82 | +}) |
| 83 | + |
| 84 | +test("escape sequences match kitty spec format", () => { |
| 85 | + // According to the spec, the push escape code is: CSI > flags u |
| 86 | + // Where CSI = 0x1b 0x5b = \x1b[ |
| 87 | + // So the format should be: \x1b[>5u for DISAMBIGUATE | ALTERNATE_KEYS |
| 88 | + // and \x1b[>7u for DISAMBIGUATE | ALTERNATE_KEYS | EVENT_TYPES |
| 89 | + |
| 90 | + const defaultFlags = buildKittyKeyboardFlags({}) |
| 91 | + expect(defaultFlags).toBe(5) |
| 92 | + // The escape sequence would be: \x1b[>5u |
| 93 | + |
| 94 | + const withEventsFlags = buildKittyKeyboardFlags({ events: true }) |
| 95 | + expect(withEventsFlags).toBe(7) |
| 96 | + // The escape sequence would be: \x1b[>7u |
| 97 | +}) |
| 98 | + |
| 99 | +test("default config enables disambiguate and alternate keys", () => { |
| 100 | + // Default enables two key enhancements: |
| 101 | + // 1. Disambiguate (0b1): Fixes ESC timing, alt+key ambiguity, ctrl+c becomes key event |
| 102 | + // 2. Alternate keys (0b100): Reports shifted/base-layout keys for cross-keyboard shortcuts |
| 103 | + const flags = buildKittyKeyboardFlags({}) |
| 104 | + |
| 105 | + // Should have disambiguate and alternate keys bits set |
| 106 | + expect(flags & KITTY_FLAG_DISAMBIGUATE).toBeTruthy() |
| 107 | + expect(flags & KITTY_FLAG_ALTERNATE_KEYS).toBeTruthy() |
| 108 | + |
| 109 | + // Should NOT have other enhancements by default |
| 110 | + expect(flags & KITTY_FLAG_EVENT_TYPES).toBeFalsy() |
| 111 | + expect(flags & KITTY_FLAG_ALL_KEYS_AS_ESCAPES).toBeFalsy() |
| 112 | + expect(flags & KITTY_FLAG_REPORT_TEXT).toBeFalsy() |
| 113 | +}) |
| 114 | + |
| 115 | +test("events config adds event type reporting", () => { |
| 116 | + // With events enabled, we should be able to detect press/repeat/release |
| 117 | + const flags = buildKittyKeyboardFlags({ events: true }) |
| 118 | + |
| 119 | + // Should have disambiguate, alternate keys, and event types |
| 120 | + expect(flags & KITTY_FLAG_DISAMBIGUATE).toBeTruthy() |
| 121 | + expect(flags & KITTY_FLAG_ALTERNATE_KEYS).toBeTruthy() |
| 122 | + expect(flags & KITTY_FLAG_EVENT_TYPES).toBeTruthy() |
| 123 | + |
| 124 | + // Should NOT have other enhancements |
| 125 | + expect(flags & KITTY_FLAG_ALL_KEYS_AS_ESCAPES).toBeFalsy() |
| 126 | + expect(flags & KITTY_FLAG_REPORT_TEXT).toBeFalsy() |
| 127 | +}) |
| 128 | + |
| 129 | +test("disambiguate flag solves key ambiguity issues", () => { |
| 130 | + // The disambiguate flag (0b1) fixes several critical problems: |
| 131 | + // 1. ESC key: Without it, sends raw 0x1b (ambiguous with escape sequence start) |
| 132 | + // With it: sends CSI 27;1u (unambiguous) |
| 133 | + // 2. Alt+[: Without it, sends 0x1b 0x5b (same as CSI!) |
| 134 | + // With it: sends CSI 91;3u (unambiguous) |
| 135 | + // 3. Ctrl+C: Without it, sends 0x03 (generates SIGINT, kills process) |
| 136 | + // With it: sends CSI 99;5u (delivered as key event to app) |
| 137 | + |
| 138 | + const flags = buildKittyKeyboardFlags({}) |
| 139 | + expect(flags & KITTY_FLAG_DISAMBIGUATE).toBeTruthy() |
| 140 | + |
| 141 | + // Per the spec: "This has the nice side effect of making it much easier |
| 142 | + // to integrate into the application event loop." |
| 143 | + // No more timing-based hacks to distinguish ESC from escape sequences! |
| 144 | +}) |
| 145 | + |
| 146 | +test("can explicitly disable disambiguate", () => { |
| 147 | + const flags = buildKittyKeyboardFlags({ disambiguate: false }) |
| 148 | + expect(flags & KITTY_FLAG_DISAMBIGUATE).toBeFalsy() |
| 149 | + expect(flags & KITTY_FLAG_ALTERNATE_KEYS).toBeTruthy() // still enabled by default |
| 150 | +}) |
| 151 | + |
| 152 | +test("can explicitly disable alternateKeys", () => { |
| 153 | + const flags = buildKittyKeyboardFlags({ alternateKeys: false }) |
| 154 | + expect(flags & KITTY_FLAG_ALTERNATE_KEYS).toBeFalsy() |
| 155 | + expect(flags & KITTY_FLAG_DISAMBIGUATE).toBeTruthy() // still enabled by default |
| 156 | +}) |
| 157 | + |
| 158 | +test("can disable both disambiguate and alternateKeys", () => { |
| 159 | + const flags = buildKittyKeyboardFlags({ disambiguate: false, alternateKeys: false }) |
| 160 | + expect(flags).toBe(0) |
| 161 | +}) |
| 162 | + |
| 163 | +test("can enable all flags", () => { |
| 164 | + const flags = buildKittyKeyboardFlags({ |
| 165 | + disambiguate: true, |
| 166 | + alternateKeys: true, |
| 167 | + events: true, |
| 168 | + allKeysAsEscapes: true, |
| 169 | + reportText: true, |
| 170 | + }) |
| 171 | + |
| 172 | + const expected = |
| 173 | + KITTY_FLAG_DISAMBIGUATE | |
| 174 | + KITTY_FLAG_ALTERNATE_KEYS | |
| 175 | + KITTY_FLAG_EVENT_TYPES | |
| 176 | + KITTY_FLAG_ALL_KEYS_AS_ESCAPES | |
| 177 | + KITTY_FLAG_REPORT_TEXT |
| 178 | + |
| 179 | + expect(flags).toBe(expected) |
| 180 | + expect(flags).toBe(0b11111) |
| 181 | + expect(flags).toBe(31) |
22 | 182 | }) |
23 | 183 |
|
24 | | -test("buildKittyKeyboardFlags - flag values match expected constants", () => { |
25 | | - const KITTY_FLAG_ALTERNATE_KEYS = 0b0001 |
26 | | - const KITTY_FLAG_EVENT_TYPES = 0b0010 |
| 184 | +test("optional flags default to false", () => { |
| 185 | + const flags = buildKittyKeyboardFlags({}) |
27 | 186 |
|
28 | | - // Just alternate keys |
29 | | - expect(buildKittyKeyboardFlags({})).toBe(KITTY_FLAG_ALTERNATE_KEYS) |
| 187 | + // These default to true |
| 188 | + expect(flags & KITTY_FLAG_DISAMBIGUATE).toBeTruthy() |
| 189 | + expect(flags & KITTY_FLAG_ALTERNATE_KEYS).toBeTruthy() |
30 | 190 |
|
31 | | - // Alternate keys + event types |
32 | | - expect(buildKittyKeyboardFlags({ events: true })).toBe(KITTY_FLAG_ALTERNATE_KEYS | KITTY_FLAG_EVENT_TYPES) |
| 191 | + // These default to false |
| 192 | + expect(flags & KITTY_FLAG_EVENT_TYPES).toBeFalsy() |
| 193 | + expect(flags & KITTY_FLAG_ALL_KEYS_AS_ESCAPES).toBeFalsy() |
| 194 | + expect(flags & KITTY_FLAG_REPORT_TEXT).toBeFalsy() |
33 | 195 | }) |
0 commit comments