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

# Kitty Keyboard Protocol Support

## Summary

Add 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. Parser support covers the default `disambiguateEscapeCodes` and `reportEventTypes` flags; advanced flags are accepted but experimental.

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 for default flags | Decodes CSI u sequences, kitty modifiers, event types, text-as-codepoints. Advanced flag forms (alternate keys, associated text edge cases) not fully covered. |
| 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

```ts
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;
```

**Parser support note**: The current parse-keypress.ts parser fully supports `disambiguateEscapeCodes` (the default and most useful flag). The `reportEventTypes` flag is also supported (press/repeat/release). The `reportAlternateKeys`, `reportAllKeysAsEscapeCodes`, and `reportAssociatedText` flags are accepted in the options but the parser may not handle all edge forms they produce (e.g., colon-separated alternate key fields). These flags are exposed for forward compatibility but users should treat them as experimental until parser coverage is verified.

#### 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. A "partial" sequence is `\x1b[?` followed by at least one digit but no terminator (`\x1b[?1` without `u`). The prefix `\x1b[?` alone (no digits) is NOT considered partial — it's not a query response at all and is preserved in the output.

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

#### Lifecycle Controller

```ts
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).

**Raw mode ownership**: The controller does NOT acquire or release raw mode. It attaches a temporary `data` listener to stdin for detection, matching Ink's approach. Raw mode is managed exclusively by `createStdinController` / `useInput`. In practice, if useInput hasn't enabled raw mode yet, the terminal query response may be buffered by the kernel's line discipline and detection times out — this is acceptable because `mode: 'auto'` gracefully degrades to "no kitty support" on timeout. Forced mode (`mode: 'enabled'`) bypasses detection entirely.

**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:

```ts
kittyKeyboard?: KittyKeyboardOptions;
```

**mount()** — after `createStdinController()`:

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

**teardown()** — after Vue unmount, before terminal restoration:

```ts
// In teardown(), after originalUnmount() and before writer.done() / cursor restore:
mountedKittyController?.dispose();
```

Order matches Ink: final render → restore console → React/Vue unmount → cancel kitty detection → disable kitty protocol → exit alt screen → restore cursor → done.

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

**Key interface** — add 5 fields:

```ts
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:

```ts
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):

```ts
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
- `kittyFlags` constant (matching Ink's exports)

## 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/src/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` (~22 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)

**Opt-in behavior (2 tests):**
- No-op when `kittyKeyboard` is absent from mount options (no sequences written)
- No-op when `kittyKeyboard: { mode: 'disabled' }` (no sequences written)

**Custom flags (2 tests):**
- Enabled mode with custom flags writes correct bitmask (e.g., `flags: ['disambiguateEscapeCodes', 'reportEventTypes']` → `\x1b[>3u`)
- Auto mode with custom flags passes them through to enable sequence

**Invalid response handling (3 tests):**
- Preserves invalid query-like escape sequence (wrong terminator)
- Non-query bytes interleaved with response are re-emitted
- Response `\x1b[?0u` (zero flags) — still treated as valid support confirmation

**Split response (1 test):**
- Query response split across two stdin data chunks — bytes reassembled correctly

**Late response after timeout (1 test):**
- Terminal responds after 200ms timeout — protocol not enabled (late response bytes flow to normal input pipeline as an unknown escape sequence, which is harmless since `\x1b[?1u` does not match the kitty CSI u parser regex)

**End-to-end byte delivery (1 test):**
- User input during detection window is delivered to useInput exactly once after detection completes

## 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. See the race condition note below for the overlap scenario with useInput's listener.
- The `stdin.unshift()` call to re-emit non-query bytes pushes them back to the front of the readable stream. After the kitty detection listener is removed, the re-emitted bytes are picked up by the normal input pipeline (createStdinController's handleData) on the next read.
- **Known race condition (matches Ink)**: The detection `data` listener and useInput's `data` listener can briefly coexist if a component mounts and calls `acquireRawMode()` within the 200ms detection window. In this scenario: (a) query response bytes could leak to useInput (they'd be treated as unknown escape sequences), (b) user input bytes could be delivered twice (once by each listener, plus once more after unshift). This same race exists in Ink's implementation. In practice, most terminals respond to the query synchronously or within a few ms, so detection completes before useInput effects fire. The mitigation is ordering: `kittyController.init()` runs before `originalMount()`, so detection starts before Vue components mount. An end-to-end test must verify that user bytes sent during detection are delivered to useInput exactly once. If the race proves problematic in practice, the fix is to integrate detection into the stdin controller's input pipeline (filter query responses inline rather than using a separate listener).

## 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, kittyFlags |
| `packages/runtime/src/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** — 22 integration tests |