vue-tui/docs/superpowers/specs/2026-05-27-kitty-keyboard-design.md

Kitty Keyboard Protocol Support

Summary

Add full kitty keyboard protocol support to vue-tui, matching Ink's implementation. This covers three layers: protocol lifecycle (enable/disable/auto-detect), useInput Key interface extension, and comprehensive test backfill.

The kitty keyboard protocol is an opt-in terminal enhancement that provides disambiguated key events, additional modifiers (super, hyper, capsLock, numLock), event types (press/repeat/release), and text-as-codepoints fields. vue-tui already has the parsing layer (parse-keypress.ts) but lacks the terminal handshake and useInput integration.

Reference: https://sw.kovidgoyal.net/kitty/keyboard-protocol/

Current State

Layer	Status	Details
Parsing (parse-keypress.ts)	Complete	Decodes CSI u sequences, kitty modifiers, event types, text-as-codepoints
useInput Key interface	Partial	Exposes ctrl/shift/meta but not super/hyper/capsLock/numLock/eventType
Protocol lifecycle	Missing	No enable/disable sequences, no auto-detect, no MountOptions field
Tests	1 of ~85	Only Ctrl+C via kitty codepoint-3 form exists

Architecture

New file: packages/runtime/src/io/kitty-keyboard.ts

Self-contained module with types, constants, query/response matching, and lifecycle controller.

Types & Constants

export const kittyFlags = {
  disambiguateEscapeCodes: 1,
  reportEventTypes: 2,
  reportAlternateKeys: 4,
  reportAllKeysAsEscapeCodes: 8,
  reportAssociatedText: 16,
} as const;

export type KittyFlagName = keyof typeof kittyFlags;

export type KittyKeyboardOptions = {
  mode?: 'auto' | 'enabled' | 'disabled';
  flags?: KittyFlagName[];
};

export function resolveFlags(flags: KittyFlagName[]): number;

Query/Response Matching

Functions for detecting terminal responses to the \x1b[?u capability query:

• matchKittyQueryResponse(buffer, startIndex) — detects \x1b[?<digits>u pattern in a byte buffer. Returns {state: 'complete', endIndex} or {state: 'partial'} or undefined.
• hasCompleteKittyQueryResponse(buffer) — scans entire buffer for any complete response.
• stripKittyQueryResponsesAndTrailingPartial(buffer) — removes complete responses and trailing partial sequences, returns remaining bytes to re-emit to the input pipeline.

These operate on number[] byte buffers because terminal responses can arrive as raw bytes (Uint8Array) and may be interleaved with user input.

Lifecycle Controller

export function createKittyKeyboardController(
  stdin: NodeJS.ReadStream,
  stdout: NodeJS.WriteStream,
): KittyKeyboardController;

interface KittyKeyboardController {
  init(options: KittyKeyboardOptions | undefined, interactive: boolean): void;
  dispose(): void;
  readonly isEnabled: boolean;
}

init(options, interactive):

1. If options not provided or mode === 'disabled' — no-op.
2. Resolve flags (default: ['disambiguateEscapeCodes']).
3. mode === 'enabled' — force-enable if both stdin and stdout are TTYs. Write \x1b[>${resolvedFlags}u.
4. mode === 'auto' (default) — require interactive === true + both TTYs, then call confirmKittySupport().

confirmKittySupport():

1. Create responseBuffer: number[].
2. Attach data listener to stdin (before writing query, to catch sync responses).
3. Write \x1b[?u to stdout.
4. Set 200ms timeout.
5. On data: push bytes to buffer. If hasCompleteKittyQueryResponse(buffer) → cleanup + enable.
6. On timeout: cleanup only (no enable).
7. Cleanup: remove listener, clear timeout, strip query responses from buffer, re-emit remaining bytes via stdin.unshift(Uint8Array.from(remaining)).
8. Guard: don't enable if already disposed (handles unmount-during-detection race).

dispose():

1. Cancel in-progress detection (call stored cleanup function).
2. If protocol was enabled, write \x1b[<u to stdout (disable sequence).
3. Set enabled = false.

Modified: packages/runtime/src/render.ts

MountOptions — add field:

kittyKeyboard?: KittyKeyboardOptions;

mount() — after createStdinController():

const kittyController = createKittyKeyboardController(stdin, stdout);
kittyController.init(options.kittyKeyboard, interactive);
mountedKittyController = kittyController;

teardown() — before existing cleanup:

mountedKittyController?.dispose();

Order matters: disable kitty protocol before restoring cursor and unmounting Vue, matching Ink's teardown sequence.

Modified: packages/runtime/src/composables/useInput.ts

Key interface — add 5 fields:

export interface Key {
  // ... existing fields unchanged ...
  super: boolean;
  hyper: boolean;
  capsLock: boolean;
  numLock: boolean;
  eventType?: 'press' | 'repeat' | 'release';
}

listener() function — after building the Key object, add kitty modifier mapping:

const key: Key = {
  // ... existing fields ...
  super: keypress.super ?? false,
  hyper: keypress.hyper ?? false,
  capsLock: keypress.capsLock ?? false,
  numLock: keypress.numLock ?? false,
  eventType: keypress.eventType,
};

Input string logic — replace the current logic with kitty-aware branching (matching Ink):

let input: string;
if (keypress.isKittyProtocol) {
  if (keypress.isPrintable) {
    input = keypress.text ?? keypress.name;
  } else if (keypress.ctrl && keypress.name.length === 1) {
    input = keypress.name;
  } else {
    input = '';
  }
} else if (keypress.ctrl) {
  input = keypress.name ?? '';
} else {
  input = keypress.sequence;
}

if (!keypress.isKittyProtocol && nonAlphanumericKeys.includes(keypress.name)) {
  input = '';
}

The key change: when kitty protocol is active, non-printable keys (capslock, media keys, F13+, modifier-only keys) produce empty input instead of leaking raw escape sequences. The nonAlphanumericKeys filter only applies to legacy sequences.

Exports

Re-export from package entry point:

• KittyKeyboardOptions type
• KittyFlagName type

Escape Sequences Reference

Purpose	Sequence	Example
Query terminal support	\x1b[?u	Sent to stdout during auto-detect
Terminal response	\x1b[?<flags>u	\x1b[?1u — terminal supports disambiguate
Enable protocol	\x1b[><flags>u	\x1b[>1u — enable disambiguateEscapeCodes
Disable protocol	\x1b[<u	Sent on unmount/dispose

Test Suite

File 1: packages/runtime/tests/io/parse-keypress-kitty.test.ts (~55 unit tests)

Tests kitty parsing in isolation — no rendering, no Vue. Each test calls parseKeypress() directly with a CSI u sequence and asserts the returned keypress object.

Helper function kittyKey(codepoint, modifiers?, eventType?, textCodepoints?) constructs CSI u sequences for testing.

Basic character + modifier parsing (11 tests):

• Simple character 'a' (\x1b[97u)
• Uppercase with shift (\x1b[65;2u)
• Ctrl modifier (\x1b[97;5u)
• Alt/option modifier (\x1b[97;3u)
• Super modifier (\x1b[97;9u)
• Hyper modifier (\x1b[97;17u)
• Meta modifier (\x1b[97;33u)
• Caps lock flag (\x1b[97;65u)
• Num lock flag (\x1b[97;129u)
• Combined: ctrl+shift (\x1b[97;6u)
• Combined: super+ctrl (\x1b[97;13u)

Special keys (7 tests):

• Escape (codepoint 27)
• Return/enter (codepoint 13)
• Tab (codepoint 9)
• Backspace (codepoint 8)
• Backspace (codepoint 127)
• Legacy meta+backspace (0x1b 0x7f)
• Space (codepoint 32)

Event types (3 tests):

• Press (eventType 1)
• Repeat (eventType 2)
• Release (eventType 3)

Text & unicode (8 tests):

• Number keys
• Special character (@)
• Ctrl+letter via codepoint 1-26
• Sequence and raw preservation
• Text-as-codepoints: single, multiple, supplementary unicode
• Text defaults to character from codepoint

Arrow & function keys (5 tests):

• Arrow keys with event type (CSI enhanced special key format)
• Arrow keys with modifiers
• Home and end keys
• Tilde-terminated special keys (delete, insert, pageup, f5)
• Tilde keys with modifiers

Error handling (4 tests):

• Invalid codepoint above U+10FFFF → safe empty keypress
• Surrogate codepoint → safe empty keypress
• Invalid text codepoint → replaced with '?'
• Malformed modifier 0 → does not set all flags

Legacy fallback (2 tests):

• Non-kitty sequences fall back to legacy parsing
• Ctrl+c legacy fallback

isPrintable field (11 tests):

• True for: regular chars, digits, symbols, emoji, return, space
• False for: escape, tab, backspace, ctrl+letter, special keys (arrows)

Non-printable key suppression (10 tests):

• Capslock (57358), printscreen (57361), f13 (57376)
• Media key (57428 mediaplay)
• Modifier-only keys (57441 leftshift, 57442 leftcontrol)
• Keypad keys (57399 kp0)
• Scrolllock (57359), numlock (57360), pause (57362)
• Volume keys (lower, raise, mute)

File 2: packages/runtime-tests/integration/pty/input-kitty.test.ts (~17 integration tests)

Tests useInput with kitty protocol sequences through the full PTY pipeline. Uses the same PTY test helper infrastructure as existing input.test.ts.

Kitty modifiers through useInput (5 tests):

• Super modifier → input='s', key.super=true
• Hyper modifier → input='h', key.hyper=true
• CapsLock → key.capsLock=true
• NumLock → key.numLock=true
• Super+ctrl → input='s', key.super=true, key.ctrl=true

Event types through useInput (3 tests):

• Press → key.eventType='press'
• Repeat → key.eventType='repeat'
• Release → key.eventType='release'

Special keys through useInput (3 tests):

• Escape key → key.escape=true, empty input
• Backspace (codepoint 127) → key.backspace=true, empty input
• Delete → key.delete=true, empty input

Non-printable keys produce empty input (3 tests):

• Capslock (57358) → input=''
• F13 (57376) → input=''
• Printscreen (57361) → input=''

Text input (3 tests):

• Space → input=' '
• Return → input='\r'
• Ctrl+letter via codepoint 1-26 → input='a', key.ctrl=true

File 3: packages/runtime-tests/integration/kitty-lifecycle.test.ts (~13 integration tests)

Tests the protocol enable/disable/auto-detect flow. Uses fake stdin/stdout streams to verify escape sequences written.

Init/cleanup (3 tests):

• Writes enable sequence (\x1b[>1u) when mode: 'enabled' and both streams are TTY
• Writes disable sequence (\x1b[<u) on unmount
• Not enabled when stdin or stdout is not a TTY

Auto-detection happy path (3 tests):

• Auto detection enables protocol when terminal responds with \x1b[?1u
• Auto detection handles synchronous (immediate) query response
• Auto detection handles Uint8Array response

Auto-detection edge cases (5 tests):

• Does not enable protocol after unmount (race condition guard)
• Preserves split UTF-8 input bytes during detection (re-emitted via unshift)
• Timeout does not leak partial query response (\x1b[?1 without terminator)
• Timeout preserves query prefix without digits (\x1b[? alone)
• Ignores response without digits (\x1b[?u — missing flags)

Invalid response handling (2 tests):

• Preserves invalid query-like escape sequence (wrong terminator)
• Non-query bytes interleaved with response are re-emitted

Implementation Notes

• The kitty-keyboard.ts kittyModifiers constant already exists in parse-keypress.ts. The new module only needs the flag constants and lifecycle logic; it imports nothing from parse-keypress.ts.
• The isKittyProtocol, isPrintable, text, super, hyper, capsLock, numLock, eventType fields are already set by parseKittyKeypress() in parse-keypress.ts. No changes needed to the parser.
• Auto-detect's stdin data listener is temporary (removed after detection completes or times out). It runs during the brief init window and is cleaned up before the main input pipeline processes events, so there's no conflict.
• The stdin.unshift() call to re-emit non-query bytes pushes them back to the front of the readable stream. This works because the kitty controller's listener is removed during cleanup, and the re-emitted bytes are picked up by the normal input pipeline (createStdinController's handleData) on the next read.

Files Changed

File	Change
packages/runtime/src/io/kitty-keyboard.ts	New — types, constants, query matchers, lifecycle controller
packages/runtime/src/render.ts	Add kittyKeyboard to MountOptions, wire controller in mount/teardown
packages/runtime/src/composables/useInput.ts	Extend Key interface, add kitty-aware input logic
packages/runtime/src/index.ts	Re-export KittyKeyboardOptions, KittyFlagName
packages/runtime/tests/io/parse-keypress-kitty.test.ts	New — 55 unit tests
packages/runtime-tests/integration/pty/input-kitty.test.ts	New — 17 integration tests
packages/runtime-tests/integration/kitty-lifecycle.test.ts	New — 13 integration tests