# useSurfaceKeyboard

One window keydown listener per surface, declared as a binding map. Bindings are ignored while typing unless whileTyping; the list doubles as the source the ? key map renders from — help cannot drift from reality.

Install: `npx candlelight-ds add use-surface-keyboard`

Category: hook · Grammar: G2

## Use when

A surface answers to keys — arm/commit/rename/strike, ⌘K, undo, the number row.

## Don't use when

A focused widget should handle its own keys (Ink, Menu, InlineEdit) — those swallow events before this hook sees them.

## States


## Keyboard

- `↑↓ ⏎ Esc Space R ⌘K ⌘Z ? 1–9` — the grammar-reserved keys every surface declares here (§5)

## Traps (shipped once — do not re-learn)

- Bare window.addEventListener('keydown') outside this hook is lint-banned (@candlelight-ds/no-bare-keydown) — this file carries the one sanctioned disable.

## Acceptance tests

- Typing targets swallow surface keys unless the binding says whileTyping.
- Undeclared shift on a letter key is a different intent (R ≠ shift+R).
- The ? overlay renders from this binding list, never from hand-written help.

## Files

- hooks/useSurfaceKeyboard.ts

npm dependencies: none

Rendered twin: https://candlelight-docs.vercel.app/components/use-surface-keyboard · Full spec: https://candlelight-docs.vercel.app/spec.md