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.

npx candlelight-ds add use-surface-keyboard

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–9the grammar-reserved keys every surface declares here (§5)

Traps

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

Acceptance

• 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.

Raw twin: /components/use-surface-keyboard.md·Registry item: /r/use-surface-keyboard.json