@vgai/engine 0.2.0 → 0.3.0

package/dist/input/input-manager.d.ts

@@ -0,0 +1,596 @@
+import type { ActionValueOf, ActionValueSource, ActionValueType, BindingConflict, BindingPrompt, InputBinding, InputMapFile, PromptDevice, Vector2 } from './input-types';
+/**
+ * Maps raw keyboard/mouse/gamepad events → named actions.
+ *
+ * Usage:
+ *   const input = new InputManager();
+ *   await input.loadMap('inputmaps/default.inputmap.json');
+ *   // In game loop:
+ *   input.poll();  // call at start of frame
+ *   if (input.isPressed('jump')) { ... }
+ *   if (input.isJustPressed('attack')) { ... }
+ *   input.endFrame();  // call at end of frame
+ *
+ * F1 (spec §12 "Define Typed Action Values") — typed action values:
+ *
+ * Every action DECLARES a value shape (`InputAction.valueType`, defaulted to
+ * `'digital'` — see `input-types.ts`'s `ActionValueType`). Each shape has its
+ * own typed getter, none of which return `any`:
+ *
+ *   - `'digital'`         — `isPressed`/`isJustPressed`/`isJustReleased` -> `boolean`
+ *   - `'scalar'`           — `getScalar` -> `number`
+ *   - `'vector2'`          — `getVector2` -> `Vector2` ({x,y})
+ *   - `'pointerDelta'`     — `getPointerDelta` -> `Vector2`
+ *   - `'pointerPosition'`  — `getPointerPosition` -> `Vector2`
+ *
+ * Reading an action through the WRONG getter (e.g. `getScalar` on a
+ * `'digital'` action) throws — that's the type-safety enforcement point,
+ * since actions are declared in data (JSON), not TS types, so there's no
+ * compiler backstop otherwise. `readAction(name, expectedType)` is a generic
+ * entry point over the same getters, typed via `ActionValueOf<T>`.
+ *
+ * Each typed getter has a `*Source` sibling (e.g. `getScalarSource`) that
+ * returns `ActionValueSource | null` — which binding (and, for gamepad
+ * bindings, which connected gamepad, or for injected test bindings, which
+ * named source) produced the current value. That's the "device/source
+ * metadata" AC.
+ *
+ * Deadzone + normalization:
+ *   - scalar: below `deadzone` magnitude -> 0; at/above it, rescaled from 0
+ *     (at the deadzone edge) to ±1 (at |raw| = 1), sign preserved
+ *     (`rescaleScalar`).
+ *   - vector2: below `deadzone` magnitude -> {0,0}; at/above it, direction is
+ *     preserved and magnitude is rescaled the same way, then the result is
+ *     clamped to the unit circle — magnitude never exceeds 1 even for a raw
+ *     diagonal input like {1,1} (`rescaleVector2`).
+ *
+ * Simultaneous-binding combine rules (documented here, spec §12 F1
+ * "simultaneous bindings combine predictably"):
+ *   - digital: OR — any one satisfied binding makes the action pressed
+ *     (pre-existing behavior, unchanged).
+ *   - scalar: max-magnitude across contributing bindings' (deadzone-applied)
+ *     values, sign preserved; ties keep the first-listed binding
+ *     (deterministic given binding array order).
+ *   - vector2: sum contributing (deadzone-applied) {x,y} values component-
+ *     wise, then clamp the sum to the unit circle (never renormalized UP —
+ *     only ever scaled down if the sum exceeds magnitude 1).
+ *   - pointerDelta: sum contributing deltas (matches the existing
+ *     mouseDeltaX/Y + lookStick accumulation precedent below).
+ *   - pointerPosition: last-write-wins — the contributing source most
+ *     recently updated (by injection call order) wins; position isn't
+ *     additive so summing would be meaningless.
+ *
+ * Synthetic input injection (test hook, also the shape of F2's "injected
+ * test input" backend): `injectAxis`/`injectVector2`/`injectPointerDelta`/
+ * `injectPointerPosition` push a raw value into a named source, read back by
+ * binding an action to `{ type: 'test_axis' | 'test_vector2' |
+ * 'test_pointer_delta' | 'test_pointer_position', sourceId }` — the exact
+ * same aggregation path (deadzone/normalize/combine) real device bindings
+ * use.
+ *
+ * F2 (spec §12 "Complete Device Backends") completes the real-device side of
+ * that same typed-value path:
+ *
+ *   - `mouse_move` — un-rejected (schema.ts). Feeds `getPointerDelta` (raw
+ *     accumulated `mouseDeltaX/Y`, no deadzone) and `getVector2` (the same
+ *     delta, deadzone-rescaled + unit-circle-clamped).
+ *   - `gamepad_axis_pair` — un-rejected (schema.ts). Feeds `getVector2` with
+ *     the coupled `(xAxis, yAxis)` reading, deadzone-rescaled like a real
+ *     stick (default deadzone 0.15, matching `gamepad_axis`).
+ *   - `touch_button`/`touch_stick` — new binding kinds for touch/virtual
+ *     controls. `setTouchButton(sourceId, pressed)` feeds a digital action
+ *     (edge-tracked like `mouse_button`); `setTouchStick(sourceId, value)`
+ *     feeds a vector2 action (deadzone-rescaled like a gamepad stick). These
+ *     are the injectable entry points a real on-screen touch UI's own
+ *     touchstart/touchmove/touchend handlers would call — that DOM wiring is
+ *     a thin adapter at the edge (browser-verified separately, e.g. F4/e2e);
+ *     the mapping logic here is unit-tested headlessly with no DOM.
+ *   - Focus gating — `blur`/`focus` on `window` (guarded, real DOM only) now
+ *     drop input the same way `setEnabled(false)` does (flushing held
+ *     key/mouse/touch-button state) without touching the `enabled` flag the
+ *     editor drives — see `focused`/`inputActive` below. This is what stops
+ *     a stuck key/button when the user alt-tabs away mid-press.
+ *   - Pointer lock — `pointerlockchange` on `document` (guarded) tracks
+ *     `isPointerLocked()`; losing lock flushes mouse-button state (a click
+ *     held at the moment lock exits must not stick).
+ *   - Gamepad device identity — `getGamepadInfo(index)` exposes `{index, id,
+ *     mapping, connected}`; `ActionValueSource.gamepadId` (in addition to the
+ *     pre-existing `gamepadIndex`) is populated for every
+ *     gamepad_button/gamepad_axis/gamepad_axis_pair source.
+ *   - Disconnection/reconnection needs no new tracking: `poll()` already
+ *     re-reads `navigator.getGamepads()` every frame and every read (digital
+ *     edges, scalar/vector2 contributions) already skips a `null` gamepad
+ *     entry, so a disconnected gamepad's bound actions go neutral (and a
+ *     previously-held button correctly fires `isJustReleased`) with no
+ *     special-cased code — see the state-transition tests.
+ *
+ * F3 (spec §12 "Add Rebinding and Prompts") completes the input system with
+ * rebinding, structural conflict detection, and device-prompt resolution:
+ *
+ *   - Listing/mutating: `getBindings`/`setBindings`/`addBinding`/
+ *     `removeBinding`/`replaceBinding` — the same `this.actions` map F1/F2
+ *     already read, now with a public read + mutation surface (there was
+ *     previously none — every existing call site either loaded a map once or
+ *     read through the typed getters).
+ *   - Reset-to-defaults: `registerAction`/`loadMap`/`loadMapObject` snapshot
+ *     each action's bindings into `defaultBindings` (a deep clone) at
+ *     registration/load time; `resetBindings`/`resetAllBindings` restore from
+ *     that snapshot. Later rebinding calls do NOT touch the snapshot, so
+ *     "reset" always means "back to what was authored/loaded", not "back to
+ *     the last reset".
+ *   - Persist: `toInputMapFile()` serializes the live action set back into
+ *     the exact `.inputmap.json` shape (`InputMapFile`) `loadMap` reads;
+ *     `loadMapObject(data)` is `loadMap`'s synchronous, no-`fetch` sibling —
+ *     both funnel through the same `InputMapFileSchema`-validated
+ *     `applyParsedMap`. This is the round-trip seam: serialize, write/hand to
+ *     something else, reload, and rebound actions survive. It complements —
+ *     doesn't replace — the SDK's `project.inputMap.read/validate/update`
+ *     operations (B2, `packages/vgai-sdk/src/project/input-map-operations.ts`):
+ *     those are FILE-level (a CLI/agent editing the `.inputmap.json` on disk,
+ *     no running game involved); this is RUNTIME-level (a live game rebinding
+ *     while playing). Both validate through the identical
+ *     `InputMapFileSchema`, so a file B2 wrote loads here unchanged, and a
+ *     map this class serializes is a valid document for B2 to read back.
+ *   - Conflicts: `findConflicts(proposed, excludeActionName?)` scans every
+ *     OTHER registered action's bindings for one that's structurally
+ *     equivalent to `proposed` (see the private `bindingsCollide` — same
+ *     physical input identity: same key code, same mouse button, the same
+ *     gamepad button/axis/axis-pair, the same touch `sourceId`, etc.) and
+ *     returns the (possibly empty) list as plain `BindingConflict` data —
+ *     never throws. A rebinding UI calls this BEFORE calling
+ *     `addBinding`/`replaceBinding`/`setBindings` and decides what to do with
+ *     a non-empty result (block, warn, let the user steal the binding by
+ *     removing it from the other action first).
+ *   - Prompts: `getPrompt(actionName, device?, gamepadIndex?)` resolves a
+ *     `BindingPrompt` (display label + icon name) for whichever of the
+ *     action's bindings belongs to the requested `PromptDevice` family
+ *     (keyboard/mouse/gamepad/touch — `bindingDeviceFamily` in
+ *     `prompt-labels.ts`), using `getGamepadInfo` to prefer the standard
+ *     mapping's canonical glyph names (`'A'`, `'LB'`, ...) for gamepad
+ *     buttons and falling back to a raw index label (or a "disconnected"
+ *     label) when the pad isn't in standard mapping or isn't connected.
+ *     `device` is optional (F4 below) — omit it to resolve against
+ *     `getLastActiveDevice()` instead.
+ *
+ * F4 (spec §12 "Schema and Examples") closes F3's one open gap — a
+ * current-ACTIVE-device tracker, so a prompt UI can switch its displayed
+ * label as the player switches controllers instead of the caller having to
+ * track that itself:
+ *
+ *   - `getLastActiveDevice()` returns the `PromptDevice` family of whichever
+ *     input arrived most recently — keyboard on `keydown`, mouse on
+ *     `mousedown`/a real `mousemove`, gamepad on a button press or a stick
+ *     pushed meaningfully off-center (checked in `poll()`), touch on
+ *     `setTouchButton(_, true)` or `setTouchStick` pushed meaningfully
+ *     off-center. `null` before any input has arrived.
+ *   - `getPrompt(actionName)` (device omitted) resolves against it directly,
+ *     falling back to `'keyboard'` before any input has arrived — a HUD can
+ *     call it every frame with no extra bookkeeping and the label switches on
+ *     its own.
+ */
+export declare class InputManager {
+    private actions;
+    private actionValueTypes;
+    private defaultBindings;
+    private loadedMapVersion;
+    private keysDown;
+    private keysJustDown;
+    private keysJustUp;
+    private mouseButtons;
+    private mouseButtonsJustDown;
+    private mouseButtonsJustUp;
+    private mouseDeltaX;
+    private mouseDeltaY;
+    private gamepads;
+    private gamepadButtonsDown;
+    private gamepadButtonsPrev;
+    private gamepadButtonsJustDown;
+    private gamepadButtonsJustUp;
+    private gamepadAxesCurrent;
+    private gamepadAxesPrev;
+    private lookStickX;
+    private lookStickY;
+    private testAxisValues;
+    private testVector2Values;
+    private testPointerDeltaAccum;
+    private testPointerPositionValues;
+    private pointerPositionSeq;
+    private touchButtonsDown;
+    private touchButtonsJustDown;
+    private touchButtonsJustUp;
+    private touchStickValues;
+    private lastActiveDevice;
+    /** Coarse "is this stick meaningfully off-center" check shared by the
+     *  gamepad and touch-stick active-device heuristics above — deliberately a
+     *  higher bar than a binding's own (often much smaller) configured
+     *  deadzone, since this is "did the player just grab this control", not
+     *  "does this binding's value count as non-zero". */
+    private static isStickActive;
+    private disposed;
+    /**
+     * When false, all raw input is ignored and held/transient state is cleared.
+     * The editor host drives this (T6.3, `packages/editor/src/play-mode.ts`) so
+     * the running game only receives input while its viewport is the active,
+     * focused surface — keystrokes typed into the editor (Scene tab, inspector
+     * fields) must not leak into the game. A standalone game leaves this true
+     * for its whole lifetime.
+     */
+    private enabled;
+    /**
+     * F2 — real window focus, distinct from `enabled` (which is the editor's
+     * explicit play-mode gate). `false` while the tab/window is blurred (real
+     * `blur`/`focus` events — see the constructor). Held keyboard/mouse/touch
+     * state is flushed on blur so a key/button held at alt-tab time doesn't
+     * stick (the browser stops delivering keyup/mouseup while blurred).
+     */
+    private focused;
+    /** Both gates a standalone game must pass for input to be live (spec §12
+     *  F2 "focus gating"): the editor's explicit `enabled` flag AND real
+     *  window focus. Used everywhere `enabled` alone used to be checked. */
+    private get inputActive();
+    /** F2 — real pointer-lock state (`document.pointerLockElement`), tracked via
+     *  `pointerlockchange` (see the constructor). */
+    private pointerLocked;
+    /** Element currently wired for click-to-pointer-lock, and its listener. */
+    private pointerLockElement;
+    private onPointerLockClick;
+    private onPointerLockChange;
+    private onKeyDown;
+    private onKeyUp;
+    private onMouseDown;
+    private onMouseUp;
+    private onMouseMove;
+    /** F2 — real window blur: drop focus and flush held state, mirroring
+     *  `setEnabled(false)`'s flush (see `flushHeldState`), without touching the
+     *  editor-driven `enabled` flag. */
+    private onWindowBlur;
+    /** F2 — real window focus regain. No flush needed (there's nothing held to
+     *  flush — a fresh keydown/mousedown is required to register pressed
+     *  again, exactly like re-enabling via `setEnabled(true)`). */
+    private onWindowFocus;
+    /** Clear all held/transient keyboard/mouse/touch-button state — shared by
+     *  `setEnabled(false)` and real blur (`onWindowBlur`), so a key/button
+     *  physically held when input is suspended doesn't linger. Level values
+     *  (gamepad axes, touch sticks, injected test axes) are deliberately NOT
+     *  flushed here — they are gated at READ time instead (see `inputActive`
+     *  checks in `poll()`/the `collect*Contributions` methods), matching the
+     *  pre-existing gamepad-axis convention. */
+    private flushHeldState;
+    constructor();
+    /**
+     * Load action map from a .inputmap.json file. Validated via
+     * `InputMapFileSchema` (T4.6) — a malformed input map throws a
+     * `SceneParseError` naming the file, not a deep TypeError once the bad
+     * data reaches `isPressed`/`isJustPressed`/`isJustReleased`.
+     */
+    loadMap(url: string): Promise<void>;
+    /**
+     * F3 — `loadMap`'s synchronous, no-`fetch` sibling: apply an already-in-
+     * memory (or freshly-deserialized) input-map DOCUMENT, validated through
+     * the identical `InputMapFileSchema` (throws `SceneParseError` naming no
+     * file, matching `loadMap`'s error shape minus the URL). This is the other
+     * half of the F3 persist round-trip: `toInputMapFile()` serializes,
+     * `loadMapObject` re-applies — no network/file I/O required, so it's also
+     * how a headless test proves a rebind survives a save/reload cycle.
+     */
+    loadMapObject(data: unknown): InputMapFile;
+    /** Shared apply step for `loadMap`/`loadMapObject`: copy each action's
+     *  bindings + declared valueType into the live maps, and snapshot the
+     *  bindings as that action's F3 reset-to-defaults baseline. */
+    private applyParsedMap;
+    /** Register an action programmatically. `valueType` declares the action's
+     *  value shape (F1) — defaults to `'digital'`, matching every call site
+     *  written before F1. F3 — also snapshots `bindings` as this action's
+     *  reset-to-defaults baseline (see `resetBindings`). */
+    registerAction(name: string, bindings: InputBinding[], valueType?: ActionValueType): void;
+    /** The declared value type for a registered/loaded action (F1) — `'digital'`
+     *  for an action that never specified one (including an unregistered/typo'd
+     *  name — harmless, since every typed getter already treats an unknown
+     *  action as inert). */
+    getActionValueType(actionName: string): ActionValueType;
+    /** Enforces the F1 type-safety AC: reading an action through a typed getter
+     *  whose value type doesn't match the action's DECLARED `valueType` throws,
+     *  naming both. Unknown actions (never registered/loaded) are exempt — they
+     *  already read as inert/zeroed by every getter, matching pre-F1 behavior
+     *  for a typo'd action name. */
+    private assertValueType;
+    /** The names of all registered actions (for the InputAdapter to enumerate). */
+    actionNames(): string[];
+    /** Poll gamepads and virtual look stick (call at start of frame) */
+    poll(): void;
+    /** Has a `gamepad_axis` binding's raw value crossed its direction+deadzone
+     *  threshold (positive: `value > deadzone`; negative: `value < -deadzone`)? */
+    private static axisThresholdMet;
+    /** Is an action currently held down? */
+    isPressed(actionName: string): boolean;
+    /** Was an action pressed this frame (not held from previous)? */
+    isJustPressed(actionName: string): boolean;
+    /** Was an action released this frame (held last frame, up now)? */
+    isJustReleased(actionName: string): boolean;
+    /** Device/source metadata (F1 AC) for a digital action: which binding is
+     *  CURRENTLY satisfying `isPressed`, or `null` if none is (including an
+     *  unknown action). First-satisfied-binding-wins, mirroring isPressed's own
+     *  iteration order. */
+    getDigitalSource(actionName: string): ActionValueSource | null;
+    /** 1D deadzone rescale: magnitudes below `deadzone` become 0; magnitudes
+     *  at/above it rescale from 0 (at the deadzone edge) to ±1 (at |raw| = 1),
+     *  sign preserved. `raw` is clamped to [-1, 1] first so an out-of-range
+     *  input can't overshoot past ±1 the other end. */
+    private static rescaleScalar;
+    /** Radial deadzone + unit-circle normalization for a Vector2: magnitude
+     *  below `deadzone` snaps to {0,0}; at/above it, direction is preserved and
+     *  magnitude is rescaled the same way `rescaleScalar` rescales a 1D
+     *  magnitude (never renormalized UP past 1 — only ever scaled down). */
+    private static rescaleVector2;
+    /** Clamp a Vector2's magnitude to at most 1 (unit circle), preserving
+     *  direction — the second half of the vector2 "sum-then-clamp" combine
+     *  rule (a diagonal sum like {0.8, 0.8} has magnitude > 1). */
+    private static clampVector2;
+    /** Every `scalar`-relevant binding's (deadzone-applied) contribution for
+     *  `actionName`, one entry per binding that can produce a scalar value —
+     *  `gamepad_axis` (real device, already implemented pre-F1 for digital
+     *  thresholding — F1 additionally reads its raw signed value for scalar
+     *  actions, ignoring the binding's `direction` field, which is a digital-
+     *  only hint) and `test_axis` (F1's injected-test-input source). `mouse_move`
+     *  deliberately does NOT feed scalar (spec §12 F2 — no natural single-axis
+     *  selector field is defined for it; it feeds pointerDelta/vector2 only —
+     *  see `collectPointerDeltaContributions`/`collectVector2Contributions`). */
+    private collectScalarContributions;
+    private computeScalar;
+    /** Read a `'scalar'`-valueType action's current value: max-magnitude across
+     *  contributing (deadzone-applied) bindings, sign preserved (combine rule —
+     *  see the class doc comment). Throws if the action is declared a
+     *  different valueType. */
+    getScalar(actionName: string): number;
+    /** Device/source metadata for {@link getScalar} — which binding is
+     *  currently driving the combined value, or `null` if every contribution is
+     *  zero (including an unknown action). */
+    getScalarSource(actionName: string): ActionValueSource | null;
+    /** `gamepad_axis_pair` contribution(s) for {@link collectVector2Contributions} — one entry
+     *  per connected gamepad, deadzone-rescaled (default 0.15, matching `gamepad_axis`). Broken
+     *  out to a helper so the per-gamepad loop doesn't add to the main dispatcher's complexity. */
+    private contributeGamepadAxisPair;
+    /** Every `vector2`-relevant binding's (deadzone-applied) contribution:
+     *  `test_vector2` (F1's injected-test-input source), plus F2's real-device
+     *  cases — `gamepad_axis_pair` (see {@link contributeGamepadAxisPair}), `mouse_move` (the
+     *  accumulated mouse delta, deadzone default 0 — raw pixel deltas have no natural "at rest"
+     *  jitter floor the way an analog stick does), and `touch_stick` (a virtual on-screen stick,
+     *  deadzone default 0). */
+    private collectVector2Contributions;
+    private computeVector2;
+    /** Read a `'vector2'`-valueType action's current value: sum contributing
+     *  (deadzone-applied) {x,y} values component-wise, then clamp to the unit
+     *  circle (combine rule — see the class doc comment). Throws if the action
+     *  is declared a different valueType. */
+    getVector2(actionName: string): Vector2;
+    /** Device/source metadata for {@link getVector2} — the contributing binding
+     *  with the largest (pre-combine) magnitude, or `null` if the combined
+     *  value is {0,0} (including an unknown action). */
+    getVector2Source(actionName: string): ActionValueSource | null;
+    /** Every `pointerDelta`-relevant binding's contribution: `test_pointer_delta`
+     *  (F1's injected-test-input source) and — F2 — `mouse_move`, reading the
+     *  real accumulated `mouseDeltaX/Y` (the same accumulator `onMouseMove`
+     *  fills and `getMouseDelta()` reads). No deadzone for either (deltas are
+     *  not deadzoned). */
+    private collectPointerDeltaContributions;
+    private computePointerDelta;
+    /** Read a `'pointerDelta'`-valueType action's this-frame movement: sum of
+     *  contributing bindings' deltas (combine rule — see the class doc
+     *  comment). Throws if the action is declared a different valueType. */
+    getPointerDelta(actionName: string): Vector2;
+    /** Device/source metadata for {@link getPointerDelta}. */
+    getPointerDeltaSource(actionName: string): ActionValueSource | null;
+    /** Every `pointerPosition`-relevant binding's contribution, each tagged
+     *  with the injection-order sequence number used to break ties (last-
+     *  write-wins) — today only `test_pointer_position` (F1's injected-test-
+     *  input source). */
+    private collectPointerPositionContributions;
+    private computePointerPosition;
+    /** Read a `'pointerPosition'`-valueType action's current absolute position:
+     *  last-write-wins across contributing bindings (combine rule — see the
+     *  class doc comment; position isn't additive, so it is never summed).
+     *  Throws if the action is declared a different valueType. */
+    getPointerPosition(actionName: string): Vector2;
+    /** Device/source metadata for {@link getPointerPosition} — the most
+     *  recently-written contributing source. */
+    getPointerPositionSource(actionName: string): ActionValueSource | null;
+    /** Generic typed read (F1): dispatches to the matching typed getter based
+     *  on `expectedType`, returning `ActionValueOf<T>` — a caller with a
+     *  statically-known action-value-type map gets a fully-inferred, non-`any`
+     *  return type. Throws the same mismatch error as the dedicated getters if
+     *  the action's declared valueType disagrees with `expectedType`. */
+    readAction<T extends ActionValueType>(actionName: string, expectedType: T): ActionValueOf<T>;
+    /** Inject a synthetic scalar value for a named test source (F1's injected-
+     *  test-input hook — also the shape of F2's "injected test input" backend).
+     *  Bind an action to `{ type: 'test_axis', sourceId }` (`valueType:
+     *  'scalar'`) to read it back via {@link getScalar}. The value PERSISTS
+     *  across frames (like a real analog stick held in position) until changed
+     *  or cleared via {@link clearAxis}. */
+    injectAxis(sourceId: string, value: number): void;
+    /** Clear an injected scalar source (e.g. simulating an at-rest/disconnected
+     *  device). */
+    clearAxis(sourceId: string): void;
+    /** Inject a synthetic {x,y} value for a named test source. Bind an action
+     *  to `{ type: 'test_vector2', sourceId }` (`valueType: 'vector2'`) to read
+     *  it back via {@link getVector2}. Persists across frames until changed or
+     *  cleared via {@link clearVector2}. */
+    injectVector2(sourceId: string, value: Vector2): void;
+    /** Clear an injected Vector2 source. */
+    clearVector2(sourceId: string): void;
+    /** Accumulate a synthetic pointer delta for a named test source — mirrors
+     *  real mouse-move delta accumulation (`onMouseMove` above): multiple calls
+     *  within the same frame sum, and the accumulator is cleared in
+     *  {@link endFrame}. Bind an action to `{ type: 'test_pointer_delta',
+     *  sourceId }` (`valueType: 'pointerDelta'`) to read it back via
+     *  {@link getPointerDelta}. */
+    injectPointerDelta(sourceId: string, delta: Vector2): void;
+    /** Set a synthetic absolute pointer position for a named test source.
+     *  Persists (last-write-wins across contributing sources on read — see the
+     *  pointerPosition combine rule) until changed. Bind an action to `{ type:
+     *  'test_pointer_position', sourceId }` (`valueType: 'pointerPosition'`) to
+     *  read it back via {@link getPointerPosition}. */
+    injectPointerPosition(sourceId: string, value: Vector2): void;
+    /** Whether input capture is currently enabled (see {@link setEnabled}). */
+    isEnabled(): boolean;
+    /**
+     * Enable/disable input capture. The editor host disables the running game's
+     * input while its viewport isn't focused so keystrokes don't leak in from
+     * the editor. Disabling clears all held/transient keyboard/mouse/touch-button
+     * state (via {@link flushHeldState}) so nothing sticks (e.g. a held movement
+     * key when you switch back to the Scene tab mid-flight) — gamepad state
+     * doesn't need clearing here since `poll()` itself stops reading it while
+     * disabled (see poll()'s doc comment).
+     */
+    setEnabled(enabled: boolean): void;
+    /** Whether the window/tab is currently focused (F2, spec §12 "focus
+     *  gating") — `false` while blurred (real `blur`/`focus` events; see the
+     *  constructor). Distinct from {@link isEnabled}, which is the editor's
+     *  explicit play-mode gate. */
+    isFocused(): boolean;
+    /** Whether the pointer is currently locked to {@link requestPointerLock}'s
+     *  element (F2, spec §12 "pointer lock") — tracked via the real
+     *  `pointerlockchange` event. */
+    isPointerLocked(): boolean;
+    /** Device identity for a connected gamepad slot (F2, spec §12 "expose
+     *  device identity" + "prefer the standard mapping"), or `null` if nothing
+     *  is connected at `index` (including while input is disabled/unfocused,
+     *  since `poll()` empties `this.gamepads` then). `mapping` is the Gamepad
+     *  API's own `'standard'`/`''` value — bindings author button/axis indices
+     *  assuming the W3C Standard Gamepad layout, so a non-`'standard'` mapping
+     *  means those indices may not correspond as documented. */
+    getGamepadInfo(index: number): {
+        index: number;
+        id: string;
+        mapping: string;
+        connected: boolean;
+    } | null;
+    /** Get mouse movement delta this frame */
+    getMouseDelta(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * F4 (spec §12 "Schema and Examples" — the F3 prompt-switching gap): which
+     * device family most recently produced real input, or `null` before any
+     * input has arrived. A prompt UI polls this (or lets {@link getPrompt}
+     * consult it automatically by omitting `device`) to switch its displayed
+     * label as the player switches controllers — e.g. showing `'Space'` while
+     * they're on keyboard, then `'A'` the moment they touch a gamepad.
+     */
+    getLastActiveDevice(): PromptDevice | null;
+    /** The current bindings for `actionName` (F3 AC "listed") — a defensive
+     *  deep clone, so mutating the returned array/objects never affects the
+     *  live binding list. `[]` for an unknown/never-registered action. */
+    getBindings(actionName: string): InputBinding[];
+    /** Wholesale-replace `actionName`'s bindings array (F3 AC "replaced"). Does
+     *  NOT touch the reset-to-defaults snapshot — see `resetBindings`. A no-op
+     *  target for an action that was never registered is allowed (it simply
+     *  registers one with `valueType: 'digital'`, matching `registerAction`'s
+     *  own default) since a rebinding UI operates on actions it already knows
+     *  about, but shouldn't have to special-case "brand new action" separately. */
+    setBindings(actionName: string, bindings: InputBinding[]): void;
+    /** Append one binding to `actionName` (F3 AC "added"). */
+    addBinding(actionName: string, binding: InputBinding): void;
+    /** Remove the binding at `index` from `actionName` (F3 AC "removed"). A
+     *  no-op if the action is unknown or `index` is out of range (rather than
+     *  throwing) — mirrors every other getter's "unknown action is inert"
+     *  convention, so a UI doesn't need a separate existence check first. */
+    removeBinding(actionName: string, index: number): void;
+    /** Replace a single binding slot at `index` on `actionName` — the shape a
+     *  rebinding UI actually wants ("rebind THIS control"), built on
+     *  `getBindings`/`setBindings`. A no-op if the action is unknown or `index`
+     *  is out of range. */
+    replaceBinding(actionName: string, index: number, binding: InputBinding): void;
+    /** Restore `actionName`'s bindings to the snapshot taken at
+     *  `registerAction`/`loadMap`/`loadMapObject` time (F3 AC "reset"). A no-op
+     *  for an action with no snapshot (never registered/loaded — there is no
+     *  "default" to reset to). */
+    resetBindings(actionName: string): void;
+    /** Reset every action that has a snapshot back to its registered/loaded
+     *  defaults. Convenience batch form of `resetBindings`. */
+    resetAllBindings(): void;
+    /**
+     * Whether `a` and `b` are the SAME physical input (F3's structural-conflict
+     * identity check — see `findConflicts`). Deliberately narrower than deep
+     * equality: `deadzone` never participates (two bindings on the same key
+     * with different deadzones are still the same physical control), and a
+     * `gamepad_axis`'s `direction` DOES participate — opposite directions of one
+     * physical axis (e.g. "accelerate" on positive, "brake" on negative) are a
+     * legitimate, non-conflicting pair, not a collision.
+     */
+    private static bindingsCollide;
+    /**
+     * Every EXISTING binding, on every OTHER registered action, that is
+     * structurally the same physical input as `proposed` (F3 AC "conflicts are
+     * detected and returned structurally") — never throws, always a plain
+     * (possibly empty) array a rebinding UI inspects before committing a
+     * rebind. `excludeActionName` is normally the action being rebound itself
+     * (so an action isn't reported as conflicting with its own current
+     * binding when re-proposing an unchanged value).
+     */
+    findConflicts(proposed: InputBinding, excludeActionName?: string): BindingConflict[];
+    /**
+     * Serialize every registered/loaded action back into the `.inputmap.json`
+     * document shape (F3 AC "persisted") — the exact `InputMapFile` shape
+     * `loadMap`/`loadMapObject` read, so `manager.loadMapObject(manager.toInputMapFile())`
+     * on a fresh instance reproduces the same live bindings. `version` is
+     * carried forward from the last loaded map when known, else `1` (a
+     * manager built purely via `registerAction` calls, never `loadMap`, has no
+     * file-format version to preserve).
+     */
+    toInputMapFile(): InputMapFile;
+    /**
+     * Resolve a display prompt (F3 AC: labels/icons like `'Space'`, `'A'`, or a
+     * touch control's name) for whichever of `actionName`'s bindings belongs to
+     * the requested `device` family. `null` when the action has no binding for
+     * that device (including an unknown action). `gamepadIndex` (default 0)
+     * selects which connected pad's `mapping`/connected state to consult for a
+     * `gamepad_*` binding — see `getGamepadInfo`.
+     *
+     * F4 — `device` is now OPTIONAL: omit it (or pass `undefined`) to resolve
+     * against {@link getLastActiveDevice} instead (falling back to `'keyboard'`
+     * before any input has arrived), so a prompt UI that wants "show whatever
+     * the player is actually holding right now" doesn't have to track the
+     * active device itself — it can just call `getPrompt(actionName)` every
+     * frame and the label switches on its own as the player changes controllers.
+     * Passing an explicit `device` (as every pre-F4 caller does) is unaffected.
+     */
+    getPrompt(actionName: string, device?: PromptDevice, gamepadIndex?: number): BindingPrompt | null;
+    /** Call at end of frame to clear per-frame state */
+    endFrame(): void;
+    /** Inject synthetic key state from touch controls */
+    setVirtualKey(code: string, pressed: boolean): void;
+    /** Set virtual look stick position (-1..1). Injected as mouse delta during poll(). */
+    setLookStick(x: number, y: number): void;
+    /** Inject synthetic mouse delta (e.g. from touch controls) */
+    addMouseDelta(dx: number, dy: number): void;
+    /**
+     * F2 (spec §12 "Complete Device Backends") — the touch/virtual-control
+     * digital backend. Set a named virtual button's (`sourceId` — a zone/knob
+     * id the touch UI chooses) pressed state; edge-tracked exactly like a real
+     * mouse button (`onMouseDown`/`onMouseUp` above) so `isJustPressed`/
+     * `isJustReleased` work for `{ type: 'touch_button', sourceId }` bindings.
+     * This is the injectable entry point a real on-screen button's own
+     * touchstart/touchend handler would call — that DOM wiring is a thin
+     * adapter at the edge (browser-verified separately); this method is the
+     * MAPPING logic, unit-tested headlessly with no DOM.
+     */
+    setTouchButton(sourceId: string, pressed: boolean): void;
+    /**
+     * F2 — the touch/virtual-control analog backend. Set a named virtual
+     * stick's (`sourceId`) raw `{x,y}` position (e.g. -1..1 per axis, like a
+     * gamepad stick); read back via `getVector2` on a `{ type: 'touch_stick',
+     * sourceId }` binding, deadzone-rescaled the same way a gamepad stick is.
+     * Persists across frames (a level value, like a real analog stick held in
+     * position) until changed or cleared via {@link clearTouchStick}.
+     */
+    setTouchStick(sourceId: string, value: Vector2): void;
+    /** Clear a virtual stick's value (e.g. simulating the touch point lifting —
+     *  the knob returns to center). */
+    clearTouchStick(sourceId: string): void;
+    /** Request pointer lock for FPS-style mouse control */
+    requestPointerLock(element: HTMLElement): void;
+    /** Clean up event listeners */
+    dispose(): void;
+}
+//# sourceMappingURL=input-manager.d.ts.map

package/dist/input/input-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-manager.d.ts","sourceRoot":"","sources":["../../src/input/input-manager.ts"],"names":[],"mappings":"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"}