Skip to content

Commit 4a84421

Browse files
authored
Fix wrong Kitty keyboard protocol flags (#426)
1 parent 3b1b36d commit 4a84421

3 files changed

Lines changed: 237 additions & 34 deletions

File tree

‎packages/core/src/renderer.ts‎

Lines changed: 49 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -87,9 +87,7 @@ export interface CliRendererConfig {
8787
useAlternateScreen?: boolean
8888
useConsole?: boolean
8989
experimental_splitHeight?: number
90-
useKittyKeyboard?: {
91-
events?: boolean // Enable event types (press/repeat/release)
92-
} | null
90+
useKittyKeyboard?: KittyKeyboardOptions | null
9391
backgroundColor?: ColorInput
9492
openConsoleOnError?: boolean
9593
prependInputHandlers?: ((sequence: string) => boolean)[]
@@ -103,28 +101,69 @@ export type PixelResolution = {
103101

104102
// Kitty keyboard protocol flags
105103
// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
106-
const KITTY_FLAG_ALTERNATE_KEYS = 0b0001 // Report alternate keys (e.g., numpad vs regular)
107-
const KITTY_FLAG_EVENT_TYPES = 0b0010 // Report event types (press/repeat/release)
108-
const KITTY_FLAG_REPORT_TEXT = 0b0100 // Report text associated with key events
104+
const KITTY_FLAG_DISAMBIGUATE = 0b1 // Report disambiguated escape codes
105+
const KITTY_FLAG_EVENT_TYPES = 0b10 // Report event types (press/repeat/release)
106+
const KITTY_FLAG_ALTERNATE_KEYS = 0b100 // Report alternate keys (e.g., numpad vs regular)
109107
const KITTY_FLAG_ALL_KEYS_AS_ESCAPES = 0b1000 // Report all keys as escape codes
108+
const KITTY_FLAG_REPORT_TEXT = 0b10000 // Report text associated with key events
109+
110+
/**
111+
* Kitty Keyboard Protocol configuration options
112+
* See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement
113+
*/
114+
export interface KittyKeyboardOptions {
115+
/** Disambiguate escape codes (fixes ESC timing, alt+key ambiguity, ctrl+c as event). Default: true */
116+
disambiguate?: boolean
117+
/** Report alternate keys (numpad, shifted, base layout) for cross-keyboard shortcuts. Default: true */
118+
alternateKeys?: boolean
119+
/** Report event types (press/repeat/release). Default: false */
120+
events?: boolean
121+
/** Report all keys as escape codes. Default: false */
122+
allKeysAsEscapes?: boolean
123+
/** Report text associated with key events. Default: false */
124+
reportText?: boolean
125+
}
110126

111127
/**
112128
* Build kitty keyboard protocol flags based on configuration
113129
* @param config Kitty keyboard configuration object (null/undefined = disabled)
114130
* @returns The combined flags value (0 = disabled, >0 = enabled)
115131
* @internal Exported for testing
116132
*/
117-
export function buildKittyKeyboardFlags(config: { events?: boolean } | null | undefined): number {
133+
export function buildKittyKeyboardFlags(config: KittyKeyboardOptions | null | undefined): number {
118134
if (!config) {
119135
return 0
120136
}
121137

122-
let flags = KITTY_FLAG_ALTERNATE_KEYS
138+
let flags = 0
139+
140+
// Default: disambiguate + alternate keys (both default to true)
141+
// - Disambiguate (0b1): Fixes ESC timing issues, alt+key ambiguity, makes ctrl+c a key event
142+
// - Alternate keys (0b100): Reports shifted/base-layout keys for cross-keyboard shortcuts
143+
144+
// disambiguate defaults to true unless explicitly set to false
145+
if (config.disambiguate !== false) {
146+
flags |= KITTY_FLAG_DISAMBIGUATE
147+
}
123148

124-
if (config.events) {
149+
// alternateKeys defaults to true unless explicitly set to false
150+
if (config.alternateKeys !== false) {
151+
flags |= KITTY_FLAG_ALTERNATE_KEYS
152+
}
153+
154+
// Optional flags (default to false, only enabled when explicitly true)
155+
if (config.events === true) {
125156
flags |= KITTY_FLAG_EVENT_TYPES
126157
}
127158

159+
if (config.allKeysAsEscapes === true) {
160+
flags |= KITTY_FLAG_ALL_KEYS_AS_ESCAPES
161+
}
162+
163+
if (config.reportText === true) {
164+
flags |= KITTY_FLAG_REPORT_TEXT
165+
}
166+
128167
return flags
129168
}
130169

@@ -761,7 +800,7 @@ export class CliRenderer extends EventEmitter implements RenderContext {
761800
}
762801

763802
public set useKittyKeyboard(use: boolean) {
764-
const flags = use ? KITTY_FLAG_ALTERNATE_KEYS : 0
803+
const flags = use ? KITTY_FLAG_DISAMBIGUATE | KITTY_FLAG_ALTERNATE_KEYS : 0
765804
this.lib.setKittyKeyboardFlags(this.rendererPtr, flags)
766805
}
767806

Lines changed: 178 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,195 @@
11
import { test, expect } from "bun:test"
22
import { buildKittyKeyboardFlags } from "../renderer"
33

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+
412
test("buildKittyKeyboardFlags - null/undefined returns 0", () => {
513
expect(buildKittyKeyboardFlags(null)).toBe(0)
614
expect(buildKittyKeyboardFlags(undefined)).toBe(0)
715
})
816

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)
1261
})
1362

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)
1770
})
1871

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)
22182
})
23183

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({})
27186

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()
30190

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()
33195
})

‎packages/core/src/zig/terminal.zig‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -42,14 +42,16 @@ pub const CursorStyle = enum {
4242
};
4343

4444
pub const Options = struct {
45-
// Kitty keyboard protocol flags:
46-
// Bit 0 (1): Report alternate keys (e.g., numpad vs regular keys)
47-
// Bit 1 (2): Report event types (press/repeat/release)
48-
// Bit 2 (4): Report text associated with key events
49-
// Bit 3 (8): Report all keys as escape codes
50-
// Default 0b00001 (1) = alternate keys only (no event types)
51-
// Use 0b00011 (3) to enable event types for key release detection
52-
kitty_keyboard_flags: u8 = 0b00001,
45+
// Kitty keyboard protocol flags (progressive enhancement):
46+
// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement
47+
// Bit 0 (0b1): Disambiguate escape codes (fixes ESC timing, alt+key ambiguity, ctrl+c as event)
48+
// Bit 1 (0b10): Report event types (press/repeat/release)
49+
// Bit 2 (0b100): Report alternate keys (e.g., numpad vs regular, shifted, base layout)
50+
// Bit 3 (0b1000): Report all keys as escape codes
51+
// Bit 4 (0b10000): Report text associated with key events
52+
// Default 0b00101 (5) = disambiguate + alternate keys
53+
// Use 0b00111 (7) to also enable event types for key release detection
54+
kitty_keyboard_flags: u8 = 0b00101,
5355
};
5456

5557
pub const TerminalInfo = struct {

0 commit comments

Comments
 (0)