# Input Action Binding Guide

The action binding layer sits above `InputManager` and `ActionMap`. It keeps
physical input handling in the existing core package while adding game-facing
contracts for action registration, contexts, profile persistence, menu render
models, combo detection, input buffering, platform prompts, touch gestures,
multi-device state, haptics, testing recordings, and debug overlays.

## Runtime flow

1. Register contexts such as `gameplay`, `vehicle`, `menu`, or `photo_mode`.
2. Register named actions with labels, categories, types, default bindings, and
   the contexts that can use them.
3. Feed raw device state into `system.getInputManager()`.
4. Call `system.update(frame)` once per simulation tick.
5. Read action states from the debug model or from the underlying `ActionMap`
   when a subsystem needs lower-level access.

Exclusive contexts are intended for menus and modal modes. When an exclusive
context is active, lower-priority additive contexts are suppressed so gameplay
actions cannot leak through a pause or rebinding screen.

## Binding UI

`createBindingMenuModel()` returns a pure render descriptor. UI shells can
render the rows without coupling this package to DOM, React, or a specific game
engine. Each row includes:

- action name, label, category, type, and context IDs
- platform-specific prompt labels and icon keys
- conflict count
- whether the action can currently be rebound
- capture-session status for listening, captured, canceled, or conflict states

Use `beginRebind(actionName, bindingIndex)` and `captureRebindInput(rawEvent)`
to drive rebinding. The capture path rejects bindings already used by another
action and returns the conflict text for the UI.

## Profiles

Profiles are serializable `InputBindingProfile` objects. `exportProfile()` and
`importProfile()` are synchronous for local saves. `saveProfile()` and
`loadProfile()` accept an `InputBindingProfileStore`, making cloud saves,
platform storage, or test-memory stores interchangeable.

## Gameplay helpers

- `registerCombo()` detects ordered action starts inside a time window.
- `setInputBufferRule()` stores short-lived action starts for animation cancel
  windows, combat queues, and frame-perfect moves.
- `setAxisProcessing()` applies dead zones, response curves, sensitivity, and
  inversion per action.
- `registerTouchGestureBinding()` maps gesture recognizer output into action
  pulses.
- `registerHapticBinding()` maps action transitions to vibration effects.
- `createTestingRecording()` captures raw events, processed action states,
  active contexts, and active devices for deterministic input fixtures.
- `createInputDebugOverlayModel()` produces rows for an in-game debug overlay.

## Prompt icons

`createBindingPrompt()` returns `label`, `iconKey`, and `ariaLabel`. The icon
key is stable and platform-scoped, for example `xbox.button.0`,
`playstation.button.0`, `keyboard.Space`, or `mouse.button.0`.
