# Keyboard Integration as Shared Input, Not as Gesture

## Decision

Keyboard is not a `GestureType`.

v2 treats pointer gestures and keyboard events as parallel input streams that share:

- one context stack
- one resolver
- one action dispatcher
- one provider-owned keyboard listener per active canvas

## Runtime Shape

- Pointer stays gesture-native:
  - `tap`
  - `double-tap`
  - `triple-tap`
  - `long-press`
  - `drag`
  - `pinch`
  - `scroll`
- Keyboard uses a separate event shape:
  - `kind: 'key'`
  - `phase: 'down' | 'up'`
  - `key`
  - `code`
  - `repeat`
- Shared runtime event union:
  - `PointerGestureEvent`
  - `KeyInputEvent`
  - `InputEvent`
- Held keyboard state is explicit:
  - `heldKeys.byKey`
  - `heldKeys.byCode`
- Pointer events carry a held-key snapshot so bindings like `Space+drag` are modeled as pointer gestures with keyboard context.

## Resolver Rules

- Pointer patterns still match pointer gesture types.
- Keyboard patterns match `phase`, `key`, and/or `code`.
- `key` score: `+64`
- `code` score: `+64`
- held-key positive score: `+16`
- held-key negative score: `+8`
- If both `key` and `code` are present, both must match.

## Ownership

- `InputProvider` is the single keyboard owner for the active canvas.
- The last canvas root to receive pointer interaction or focus becomes keyboard-active.
- Keyboard routing is suppressed when:
  - target is `input`
  - target is `textarea`
  - target is `contentEditable`
  - IME composition is active
- Held keys clear on `blur` and `visibilitychange`.

## Default Behavior

- `/` opens command line
- `Cmd/Ctrl+F` opens search
- `Cmd/Ctrl+C/X/V/D` route through shared input actions
- `Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`, `Cmd/Ctrl+Y` route through shared input actions
- `Delete` / `Backspace` delete current selection
- `Escape` precedence:
  1. cancel active interaction
  2. exit keyboard manipulate mode
  3. clear search / selection / close palette
- `keyboardInteractionMode` is explicit:
  - `'navigate'`
  - `'manipulate'`
- Navigate mode:
  - arrows move focus
  - `Enter` selects and enters manipulate mode
  - `Space` activates focused node
  - `Tab` cycles focus
- Manipulate mode:
  - arrows nudge selection by `10`
  - `Shift+Arrow` nudges by `50`
  - `Escape` returns to navigate mode

## Cutoff

- Remove keyboard ownership from:
  - `packages/canvas/src/commands/keyboard.ts`
  - `packages/canvas/src/hooks/useCanvasHistory.ts`
  - `packages/canvas/src/hooks/useArrowKeyNavigation.ts`
- Keep those exports as compatibility shims only if needed for callers during the repo migration.

## Verification

- resolver tests for key/code/held-key matching
- runtime tests for `Space+drag`, `Escape`, copy/paste, undo/redo, and active-canvas ownership
- behavior tests for navigate vs manipulate mode