@vgai/engine 0.2.0 → 0.3.0

package/src/input/input-manager.ts

@@ -1,6 +1,24 @@
 import { resolveUrl } from '../loader';
 import { SceneParseError } from '../scene/parse';
-import type { InputBinding, InputMapFile } from './input-types';
+import type {
+  ActionValueOf,
+  ActionValueSource,
+  ActionValueType,
+  BindingConflict,
+  BindingPrompt,
+  InputBinding,
+  InputMapFile,
+  PromptDevice,
+  Vector2,
+} from './input-types';
+import {
+  bindingDeviceFamily,
+  gamepadAxisLabel,
+  gamepadAxisPairLabel,
+  keyLabel,
+  mouseButtonLabel,
+  STANDARD_GAMEPAD_BUTTON_LABELS,
+} from './prompt-labels';
 import { InputMapFileSchema } from './schema';
 
 /**
@@ -31,9 +49,182 @@ function isTextEntryFocused(): boolean {
  *   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 class InputManager {
   private actions = new Map<string, InputBinding[]>();
+  // F1 — each registered/loaded action's declared value shape (defaults to
+  // 'digital' — see registerAction/loadMap). Kept as a sibling map rather than
+  // folded into `actions` so the pre-F1 `Map<string, InputBinding[]>` shape
+  // (and every existing direct read of it, e.g. in tests) stays unchanged.
+  private actionValueTypes = new Map<string, ActionValueType>();
+  // F3 — a deep-cloned snapshot of each action's bindings AT REGISTRATION/LOAD
+  // TIME (registerAction/loadMap/loadMapObject), restored by
+  // resetBindings/resetAllBindings. Later rebinding calls (setBindings/
+  // addBinding/removeBinding/replaceBinding) deliberately do not touch this —
+  // "reset" always means "back to the originally authored/loaded defaults".
+  private defaultBindings = new Map<string, InputBinding[]>();
+  // F3 — the `version` field of the last `loadMap`/`loadMapObject`-ed
+  // document, carried forward by `toInputMapFile()` so a round-trip
+  // (serialize -> reload) preserves it. Defaults to 1 for a manager built
+  // purely via `registerAction` (no file was ever loaded).
+  private loadedMapVersion = 1;
   private keysDown = new Set<string>();
   private keysJustDown = new Set<string>();
   private keysJustUp = new Set<string>();
@@ -61,6 +252,50 @@ export class InputManager {
   private gamepadAxesPrev = new Map<string, number>();
   private lookStickX = 0;
   private lookStickY = 0;
+  // F1 — injected-test-input raw value stores, keyed by caller-chosen
+  // `sourceId` (see the class doc comment's "Synthetic input injection"
+  // section). Axis/Vector2/pointer-position are LEVEL values (persist across
+  // frames until changed, mirroring a real analog stick/gamepad axis —
+  // there's no hardware poll to naturally refresh them each frame); pointer
+  // delta is a per-frame accumulator (cleared in endFrame(), mirroring
+  // mouseDeltaX/Y above).
+  private testAxisValues = new Map<string, number>();
+  private testVector2Values = new Map<string, Vector2>();
+  private testPointerDeltaAccum = new Map<string, Vector2>();
+  private testPointerPositionValues = new Map<string, { value: Vector2; seq: number }>();
+  // Monotonic counter stamped onto each injectPointerPosition call so the
+  // pointerPosition combine rule (last-write-wins) can tell which of several
+  // contributing sources was written most recently within/across frames.
+  private pointerPositionSeq = 0;
+  // F2 — touch/virtual-control state, keyed by caller-chosen `sourceId` (the
+  // touch UI's own zone/knob id — see setTouchButton/setTouchStick). Buttons
+  // mirror the mouse-button edge-tracking shape (Down/JustDown/JustUp sets);
+  // sticks are LEVEL values like a gamepad axis (persist until changed).
+  private touchButtonsDown = new Set<string>();
+  private touchButtonsJustDown = new Set<string>();
+  private touchButtonsJustUp = new Set<string>();
+  private touchStickValues = new Map<string, Vector2>();
+  // F4 (spec §12 "Schema and Examples" — the F3 prompt-switching gap) — which
+  // device family most recently produced REAL input, so a prompt UI can
+  // switch its displayed label ('Space' -> 'A' -> a touch control's name) as
+  // the player switches controllers, without the caller having to guess or
+  // track this itself. Updated at the same points raw input arrives: keydown
+  // (`'keyboard'`), mousedown/mousemove (`'mouse'`), a gamepad button press or
+  // a stick pushed meaningfully past rest (`'gamepad'`, both detected in
+  // `poll()` — a raw resting stick reports small non-zero noise on some
+  // pads, so this deliberately checks a coarse magnitude, not "any non-zero
+  // axis"), and a touch button press / stick pushed past rest
+  // (`'touch'` — `setTouchButton`/`setTouchStick`). `null` until the very
+  // first input of any kind arrives. See `getLastActiveDevice`/`getPrompt`.
+  private lastActiveDevice: PromptDevice | null = null;
+  /** 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(v: Vector2): boolean {
+    return Math.hypot(v.x, v.y) > 0.3;
+  }
   private disposed = false;
   /**
    * When false, all raw input is ignored and held/transient state is cleared.
@@ -71,16 +306,48 @@ export class InputManager {
    * for its whole lifetime.
    */
   private enabled = true;
+  /**
+   * 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 = true;
+  /** 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(): boolean {
+    return this.enabled && this.focused;
+  }
+  /** F2 — real pointer-lock state (`document.pointerLockElement`), tracked via
+   *  `pointerlockchange` (see the constructor). */
+  private pointerLocked = false;
   /** Element currently wired for click-to-pointer-lock, and its listener. */
   private pointerLockElement: HTMLElement | null = null;
   private onPointerLockClick = () => {
     this.pointerLockElement?.requestPointerLock();
   };
+  private onPointerLockChange = () => {
+    const doc = typeof document !== 'undefined' ? document : null;
+    const wasLocked = this.pointerLocked;
+    this.pointerLocked =
+      !!this.pointerLockElement && doc?.pointerLockElement === this.pointerLockElement;
+    // Losing lock mid-click must not leave a mouse button stuck down — the
+    // browser may not deliver a mouseup when lock exits (e.g. Escape).
+    if (wasLocked && !this.pointerLocked) {
+      this.mouseButtons.clear();
+      this.mouseButtonsJustDown.clear();
+      this.mouseButtonsJustUp.clear();
+    }
+  };
 
   private onKeyDown = (e: KeyboardEvent) => {
-    // Ignore game input while suspended or while the user is typing into a text
-    // field (e.g. renaming an entity / editing an inspector value in the editor).
-    if (!this.enabled || isTextEntryFocused()) return;
+    // Ignore game input while suspended, unfocused, or while the user is typing
+    // into a text field (e.g. renaming an entity / editing an inspector value
+    // in the editor).
+    if (!this.inputActive || isTextEntryFocused()) return;
+    this.lastActiveDevice = 'keyboard';
     if (!this.keysDown.has(e.code)) {
       this.keysJustDown.add(e.code);
     }
@@ -88,35 +355,81 @@ export class InputManager {
   };
 
   private onKeyUp = (e: KeyboardEvent) => {
-    if (!this.enabled) return;
+    if (!this.inputActive) return;
     this.keysDown.delete(e.code);
     this.keysJustUp.add(e.code);
   };
 
   private onMouseDown = (e: MouseEvent) => {
-    if (!this.enabled) return;
+    if (!this.inputActive) return;
+    this.lastActiveDevice = 'mouse';
     this.mouseButtons.add(e.button);
     this.mouseButtonsJustDown.add(e.button);
   };
 
   private onMouseUp = (e: MouseEvent) => {
-    if (!this.enabled) return;
+    if (!this.inputActive) return;
     this.mouseButtons.delete(e.button);
     this.mouseButtonsJustUp.add(e.button);
   };
 
   private onMouseMove = (e: MouseEvent) => {
-    if (!this.enabled) return;
+    if (!this.inputActive) return;
+    if (e.movementX !== 0 || e.movementY !== 0) this.lastActiveDevice = 'mouse';
     this.mouseDeltaX += e.movementX;
     this.mouseDeltaY += e.movementY;
   };
 
+  /** 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 = () => {
+    this.focused = false;
+    this.flushHeldState();
+  };
+
+  /** 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 = () => {
+    this.focused = true;
+  };
+
+  /** 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(): void {
+    this.keysDown.clear();
+    this.keysJustDown.clear();
+    this.keysJustUp.clear();
+    this.mouseButtons.clear();
+    this.mouseButtonsJustDown.clear();
+    this.mouseButtonsJustUp.clear();
+    this.mouseDeltaX = 0;
+    this.mouseDeltaY = 0;
+    this.touchButtonsDown.clear();
+    this.touchButtonsJustDown.clear();
+    this.touchButtonsJustUp.clear();
+  }
+
   constructor() {
     window.addEventListener('keydown', this.onKeyDown);
     window.addEventListener('keyup', this.onKeyUp);
     window.addEventListener('mousedown', this.onMouseDown);
     window.addEventListener('mouseup', this.onMouseUp);
     window.addEventListener('mousemove', this.onMouseMove);
+    window.addEventListener('blur', this.onWindowBlur);
+    window.addEventListener('focus', this.onWindowFocus);
+    // `document` isn't touched by any pre-F2 code path (the headless vitest
+    // env stubs `window` only) — guard the same way `isTextEntryFocused` does
+    // so tests that don't need pointer-lock coverage need no `document` stub.
+    if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+      document.addEventListener('pointerlockchange', this.onPointerLockChange);
+    }
   }
 
   /**
@@ -143,14 +456,72 @@ export class InputManager {
       console.error(message);
       throw err instanceof SceneParseError ? err : new Error(message);
     }
+    this.applyParsedMap(data);
+  }
+
+  /**
+   * 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 {
+    const result = InputMapFileSchema.safeParse(data);
+    if (!result.success) throw new SceneParseError(result.error.issues);
+    this.applyParsedMap(result.data);
+    return result.data;
+  }
+
+  /** 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(data: InputMapFile): void {
+    this.loadedMapVersion = data.version;
     for (const [name, action] of Object.entries(data.actions)) {
       this.actions.set(name, action.bindings);
+      // `InputActionSchema.valueType` has a Zod `.default('digital')`, so a
+      // successfully-parsed action always carries one even when the source
+      // JSON omitted it.
+      this.actionValueTypes.set(name, action.valueType ?? 'digital');
+      this.defaultBindings.set(name, structuredClone(action.bindings));
     }
   }
 
-  /** Register an action programmatically */
-  registerAction(name: string, bindings: InputBinding[]) {
+  /** 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 = 'digital') {
     this.actions.set(name, bindings);
+    this.actionValueTypes.set(name, valueType);
+    this.defaultBindings.set(name, structuredClone(bindings));
+  }
+
+  /** 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 {
+    return this.actionValueTypes.get(actionName) ?? 'digital';
+  }
+
+  /** 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(actionName: string, expected: ActionValueType, method: string): void {
+    const actual = this.actionValueTypes.get(actionName);
+    if (actual !== undefined && actual !== expected) {
+      throw new Error(
+        `InputManager.${method}: action "${actionName}" is declared valueType '${actual}', not ` +
+          `'${expected}'. Typed reads must match an action's declared valueType (F1, spec §12) — ` +
+          `use the getter for '${actual}' instead.`,
+      );
+    }
   }
 
   /** The names of all registered actions (for the InputAdapter to enumerate). */
@@ -160,13 +531,14 @@ export class InputManager {
 
   /** Poll gamepads and virtual look stick (call at start of frame) */
   poll() {
-    if (!this.enabled) {
-      // Input suspended (editor-gated play mode). Unlike keyboard/mouse,
-      // gamepad state isn't DOM-event-driven — `isPressed`/`isJustPressed`/
-      // `isJustReleased` read `this.gamepads` (and the edge-tracked sets)
-      // directly, not a live poll of `navigator`. So gate the READ here: leave
-      // `this.gamepads` empty so every gamepad-bound check sees no gamepads
-      // and reports false. Deliberately leave the edge-tracking sets
+    if (!this.inputActive) {
+      // Input suspended (editor-gated play mode, OR — F2 — real window blur).
+      // Unlike keyboard/mouse, gamepad state isn't DOM-event-driven —
+      // `isPressed`/`isJustPressed`/`isJustReleased` read `this.gamepads`
+      // (and the edge-tracked sets) directly, not a live poll of `navigator`.
+      // So gate the READ here: leave `this.gamepads` empty so every
+      // gamepad-bound check sees no gamepads and reports false. Deliberately
+      // leave the edge-tracking sets
       // (gamepadButtons{Prev,Down,JustDown,JustUp}, gamepadAxes{Current,Prev})
       // untouched — they freeze at their last real values while disabled and
       // resume diffing against genuinely-last-observed hardware state once
@@ -194,6 +566,8 @@ export class InputManager {
       if (!current.has(key)) this.gamepadButtonsJustUp.add(key);
     }
     this.gamepadButtonsDown = current;
+    // F4 — a button press is unambiguous real gamepad input.
+    if (current.size > 0) this.lastActiveDevice = 'gamepad';
 
     // Snapshot this frame's raw axis values per (gamepad, axis) — independent
     // of any binding's direction/deadzone, mirroring the button snapshot
@@ -204,7 +578,11 @@ export class InputManager {
       const gp = this.gamepads[i];
       if (!gp) continue;
       for (let a = 0; a < gp.axes.length; a++) {
-        currentAxes.set(`${i}:${a}`, gp.axes[a] ?? 0);
+        const value = gp.axes[a] ?? 0;
+        currentAxes.set(`${i}:${a}`, value);
+        // F4 — a stick pushed meaningfully off-center is also unambiguous
+        // real gamepad input (see `isStickActive`'s doc comment).
+        if (Math.abs(value) > 0.3) this.lastActiveDevice = 'gamepad';
       }
     }
     this.gamepadAxesCurrent = currentAxes;
@@ -229,6 +607,7 @@ export class InputManager {
 
   /** Is an action currently held down? */
   isPressed(actionName: string): boolean {
+    this.assertValueType(actionName, 'digital', 'isPressed');
     const bindings = this.actions.get(actionName);
     if (!bindings) return false;
 
@@ -254,6 +633,9 @@ export class InputManager {
           }
           break;
         }
+        case 'touch_button':
+          if (this.touchButtonsDown.has(binding.sourceId)) return true;
+          break;
       }
     }
     return false;
@@ -261,6 +643,7 @@ export class InputManager {
 
   /** Was an action pressed this frame (not held from previous)? */
   isJustPressed(actionName: string): boolean {
+    this.assertValueType(actionName, 'digital', 'isJustPressed');
     const bindings = this.actions.get(actionName);
     if (!bindings) return false;
 
@@ -294,6 +677,9 @@ export class InputManager {
           }
           break;
         }
+        case 'touch_button':
+          if (this.touchButtonsJustDown.has(binding.sourceId)) return true;
+          break;
       }
     }
     return false;
@@ -301,6 +687,7 @@ export class InputManager {
 
   /** Was an action released this frame (held last frame, up now)? */
   isJustReleased(actionName: string): boolean {
+    this.assertValueType(actionName, 'digital', 'isJustReleased');
     const bindings = this.actions.get(actionName);
     if (!bindings) return false;
 
@@ -331,11 +718,449 @@ export class InputManager {
           }
           break;
         }
+        case 'touch_button':
+          if (this.touchButtonsJustUp.has(binding.sourceId)) return true;
+          break;
       }
     }
     return false;
   }
 
+  /** 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 {
+    this.assertValueType(actionName, 'digital', 'getDigitalSource');
+    if (!this.inputActive) return null;
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return null;
+    for (const binding of bindings) {
+      switch (binding.type) {
+        case 'key':
+          if (this.keysDown.has(binding.code)) return { bindingType: 'key' };
+          break;
+        case 'mouse_button':
+          if (this.mouseButtons.has(binding.button)) return { bindingType: 'mouse_button' };
+          break;
+        case 'gamepad_button':
+          for (let i = 0; i < this.gamepads.length; i++) {
+            const gp = this.gamepads[i];
+            if (gp?.buttons[binding.button]?.pressed) {
+              return { bindingType: 'gamepad_button', gamepadIndex: i, gamepadId: gp.id };
+            }
+          }
+          break;
+        case 'gamepad_axis': {
+          const dz = binding.deadzone ?? 0.15;
+          for (let i = 0; i < this.gamepads.length; i++) {
+            const gp = this.gamepads[i];
+            if (!gp) continue;
+            const val = gp.axes[binding.axis] ?? 0;
+            if (InputManager.axisThresholdMet(val, binding.direction, dz)) {
+              return { bindingType: 'gamepad_axis', gamepadIndex: i, gamepadId: gp.id };
+            }
+          }
+          break;
+        }
+        case 'touch_button':
+          if (this.touchButtonsDown.has(binding.sourceId)) {
+            return { bindingType: 'touch_button', sourceId: binding.sourceId };
+          }
+          break;
+      }
+    }
+    return null;
+  }
+
+  // ==========================================================================
+  // F1 — typed scalar/vector2/pointer reads. See the class doc comment above
+  // for the deadzone/normalize/combine rules these implement.
+  // ==========================================================================
+
+  /** 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(raw: number, deadzone: number): number {
+    const clamped = Math.max(-1, Math.min(1, raw));
+    const mag = Math.abs(clamped);
+    if (mag < deadzone) return 0;
+    const rescaled = deadzone >= 1 ? 0 : (mag - deadzone) / (1 - deadzone);
+    return Math.sign(clamped) * Math.min(1, rescaled);
+  }
+
+  /** 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(raw: Vector2, deadzone: number): Vector2 {
+    const mag = Math.hypot(raw.x, raw.y);
+    if (mag === 0 || mag < deadzone) return { x: 0, y: 0 };
+    const rescaledMag = Math.min(1, deadzone >= 1 ? 0 : (mag - deadzone) / (1 - deadzone));
+    const scale = rescaledMag / mag;
+    return { x: raw.x * scale, y: raw.y * scale };
+  }
+
+  /** 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(v: Vector2): Vector2 {
+    const mag = Math.hypot(v.x, v.y);
+    if (mag <= 1 || mag === 0) return v;
+    return { x: v.x / mag, y: v.y / mag };
+  }
+
+  /** 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(
+    actionName: string,
+  ): { value: number; source: ActionValueSource }[] {
+    if (!this.inputActive) return [];
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return [];
+    const out: { value: number; source: ActionValueSource }[] = [];
+    for (const binding of bindings) {
+      if (binding.type === 'gamepad_axis') {
+        const dz = binding.deadzone ?? 0.15;
+        for (let i = 0; i < this.gamepads.length; i++) {
+          const gp = this.gamepads[i];
+          if (!gp) continue;
+          const raw = gp.axes[binding.axis] ?? 0;
+          out.push({
+            value: InputManager.rescaleScalar(raw, dz),
+            source: { bindingType: 'gamepad_axis', gamepadIndex: i, gamepadId: gp.id },
+          });
+        }
+      } else if (binding.type === 'test_axis') {
+        const raw = this.testAxisValues.get(binding.sourceId) ?? 0;
+        out.push({
+          value: InputManager.rescaleScalar(raw, binding.deadzone ?? 0),
+          source: { bindingType: 'test_axis', sourceId: binding.sourceId },
+        });
+      }
+    }
+    return out;
+  }
+
+  private computeScalar(actionName: string): { value: number; source: ActionValueSource | null } {
+    this.assertValueType(actionName, 'scalar', 'getScalar');
+    let best: { value: number; source: ActionValueSource } | null = null;
+    for (const c of this.collectScalarContributions(actionName)) {
+      if (!best || Math.abs(c.value) > Math.abs(best.value)) best = c;
+    }
+    if (!best || best.value === 0) return { value: 0, source: null };
+    return best;
+  }
+
+  /** 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 {
+    return this.computeScalar(actionName).value;
+  }
+
+  /** 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 {
+    return this.computeScalar(actionName).source;
+  }
+
+  /** `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(
+    binding: Extract<InputBinding, { type: 'gamepad_axis_pair' }>,
+  ): { value: Vector2; source: ActionValueSource }[] {
+    const dz = binding.deadzone ?? 0.15;
+    const out: { value: Vector2; source: ActionValueSource }[] = [];
+    for (let i = 0; i < this.gamepads.length; i++) {
+      const gp = this.gamepads[i];
+      if (!gp) continue;
+      const raw = { x: gp.axes[binding.xAxis] ?? 0, y: gp.axes[binding.yAxis] ?? 0 };
+      out.push({
+        value: InputManager.rescaleVector2(raw, dz),
+        source: { bindingType: 'gamepad_axis_pair', gamepadIndex: i, gamepadId: gp.id },
+      });
+    }
+    return out;
+  }
+
+  /** 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(
+    actionName: string,
+  ): { value: Vector2; source: ActionValueSource }[] {
+    if (!this.inputActive) return [];
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return [];
+    const out: { value: Vector2; source: ActionValueSource }[] = [];
+    for (const binding of bindings) {
+      switch (binding.type) {
+        case 'test_vector2': {
+          const raw = this.testVector2Values.get(binding.sourceId) ?? { x: 0, y: 0 };
+          out.push({
+            value: InputManager.rescaleVector2(raw, binding.deadzone ?? 0),
+            source: { bindingType: 'test_vector2', sourceId: binding.sourceId },
+          });
+          break;
+        }
+        case 'gamepad_axis_pair':
+          out.push(...this.contributeGamepadAxisPair(binding));
+          break;
+        case 'mouse_move': {
+          const raw = { x: this.mouseDeltaX, y: this.mouseDeltaY };
+          out.push({
+            value: InputManager.rescaleVector2(raw, binding.deadzone ?? 0),
+            source: { bindingType: 'mouse_move' },
+          });
+          break;
+        }
+        case 'touch_stick': {
+          const raw = this.touchStickValues.get(binding.sourceId) ?? { x: 0, y: 0 };
+          out.push({
+            value: InputManager.rescaleVector2(raw, binding.deadzone ?? 0),
+            source: { bindingType: 'touch_stick', sourceId: binding.sourceId },
+          });
+          break;
+        }
+      }
+    }
+    return out;
+  }
+
+  private computeVector2(actionName: string): { value: Vector2; source: ActionValueSource | null } {
+    this.assertValueType(actionName, 'vector2', 'getVector2');
+    let sum: Vector2 = { x: 0, y: 0 };
+    let bestSource: ActionValueSource | null = null;
+    let bestMag = 0;
+    for (const c of this.collectVector2Contributions(actionName)) {
+      sum = { x: sum.x + c.value.x, y: sum.y + c.value.y };
+      const mag = Math.hypot(c.value.x, c.value.y);
+      if (mag > bestMag) {
+        bestMag = mag;
+        bestSource = c.source;
+      }
+    }
+    const clamped = InputManager.clampVector2(sum);
+    if (clamped.x === 0 && clamped.y === 0) return { value: clamped, source: null };
+    return { value: clamped, source: bestSource };
+  }
+
+  /** 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 {
+    return this.computeVector2(actionName).value;
+  }
+
+  /** 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 {
+    return this.computeVector2(actionName).source;
+  }
+
+  /** 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(
+    actionName: string,
+  ): { value: Vector2; source: ActionValueSource }[] {
+    if (!this.inputActive) return [];
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return [];
+    const out: { value: Vector2; source: ActionValueSource }[] = [];
+    for (const binding of bindings) {
+      if (binding.type === 'test_pointer_delta') {
+        const value = this.testPointerDeltaAccum.get(binding.sourceId) ?? { x: 0, y: 0 };
+        out.push({
+          value,
+          source: { bindingType: 'test_pointer_delta', sourceId: binding.sourceId },
+        });
+      } else if (binding.type === 'mouse_move') {
+        out.push({
+          value: { x: this.mouseDeltaX, y: this.mouseDeltaY },
+          source: { bindingType: 'mouse_move' },
+        });
+      }
+    }
+    return out;
+  }
+
+  private computePointerDelta(actionName: string): {
+    value: Vector2;
+    source: ActionValueSource | null;
+  } {
+    this.assertValueType(actionName, 'pointerDelta', 'getPointerDelta');
+    let sum: Vector2 = { x: 0, y: 0 };
+    let bestSource: ActionValueSource | null = null;
+    let bestMag = 0;
+    for (const c of this.collectPointerDeltaContributions(actionName)) {
+      sum = { x: sum.x + c.value.x, y: sum.y + c.value.y };
+      const mag = Math.hypot(c.value.x, c.value.y);
+      if (mag > bestMag) {
+        bestMag = mag;
+        bestSource = c.source;
+      }
+    }
+    if (sum.x === 0 && sum.y === 0) return { value: sum, source: null };
+    return { value: sum, source: bestSource };
+  }
+
+  /** 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 {
+    return this.computePointerDelta(actionName).value;
+  }
+
+  /** Device/source metadata for {@link getPointerDelta}. */
+  getPointerDeltaSource(actionName: string): ActionValueSource | null {
+    return this.computePointerDelta(actionName).source;
+  }
+
+  /** 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(
+    actionName: string,
+  ): { value: Vector2; seq: number; source: ActionValueSource }[] {
+    if (!this.inputActive) return [];
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return [];
+    const out: { value: Vector2; seq: number; source: ActionValueSource }[] = [];
+    for (const binding of bindings) {
+      if (binding.type === 'test_pointer_position') {
+        const entry = this.testPointerPositionValues.get(binding.sourceId);
+        if (entry) {
+          out.push({
+            value: entry.value,
+            seq: entry.seq,
+            source: { bindingType: 'test_pointer_position', sourceId: binding.sourceId },
+          });
+        }
+      }
+    }
+    return out;
+  }
+
+  private computePointerPosition(actionName: string): {
+    value: Vector2;
+    source: ActionValueSource | null;
+  } {
+    this.assertValueType(actionName, 'pointerPosition', 'getPointerPosition');
+    const contributions = this.collectPointerPositionContributions(actionName);
+    if (contributions.length === 0) return { value: { x: 0, y: 0 }, source: null };
+    let best = contributions[0]!;
+    for (const c of contributions) {
+      if (c.seq > best.seq) best = c;
+    }
+    return { value: best.value, source: best.source };
+  }
+
+  /** 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 {
+    return this.computePointerPosition(actionName).value;
+  }
+
+  /** Device/source metadata for {@link getPointerPosition} — the most
+   *  recently-written contributing source. */
+  getPointerPositionSource(actionName: string): ActionValueSource | null {
+    return this.computePointerPosition(actionName).source;
+  }
+
+  /** 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> {
+    switch (expectedType) {
+      case 'digital':
+        return this.isPressed(actionName) as ActionValueOf<T>;
+      case 'scalar':
+        return this.getScalar(actionName) as ActionValueOf<T>;
+      case 'vector2':
+        return this.getVector2(actionName) as ActionValueOf<T>;
+      case 'pointerDelta':
+        return this.getPointerDelta(actionName) as ActionValueOf<T>;
+      case 'pointerPosition':
+        return this.getPointerPosition(actionName) as ActionValueOf<T>;
+      default:
+        throw new Error(`InputManager.readAction: unknown value type "${expectedType as string}"`);
+    }
+  }
+
+  /** 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 {
+    this.testAxisValues.set(sourceId, value);
+  }
+
+  /** Clear an injected scalar source (e.g. simulating an at-rest/disconnected
+   *  device). */
+  clearAxis(sourceId: string): void {
+    this.testAxisValues.delete(sourceId);
+  }
+
+  /** 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 {
+    this.testVector2Values.set(sourceId, value);
+  }
+
+  /** Clear an injected Vector2 source. */
+  clearVector2(sourceId: string): void {
+    this.testVector2Values.delete(sourceId);
+  }
+
+  /** 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 {
+    const prev = this.testPointerDeltaAccum.get(sourceId) ?? { x: 0, y: 0 };
+    this.testPointerDeltaAccum.set(sourceId, { x: prev.x + delta.x, y: prev.y + delta.y });
+  }
+
+  /** 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 {
+    this.testPointerPositionValues.set(sourceId, { value, seq: ++this.pointerPositionSeq });
+  }
+
   /** Whether input capture is currently enabled (see {@link setEnabled}). */
   isEnabled(): boolean {
     return this.enabled;
@@ -344,24 +1169,46 @@ export class InputManager {
   /**
    * 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 state 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).
+   * 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) {
     if (this.enabled === enabled) return;
     this.enabled = enabled;
-    if (!enabled) {
-      this.keysDown.clear();
-      this.keysJustDown.clear();
-      this.keysJustUp.clear();
-      this.mouseButtons.clear();
-      this.mouseButtonsJustDown.clear();
-      this.mouseButtonsJustUp.clear();
-      this.mouseDeltaX = 0;
-      this.mouseDeltaY = 0;
-    }
+    if (!enabled) this.flushHeldState();
+  }
+
+  /** 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 {
+    return this.focused;
+  }
+
+  /** Whether the pointer is currently locked to {@link requestPointerLock}'s
+   *  element (F2, spec §12 "pointer lock") — tracked via the real
+   *  `pointerlockchange` event. */
+  isPointerLocked(): boolean {
+    return this.pointerLocked;
+  }
+
+  /** 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 {
+    const gp = this.gamepads[index];
+    if (!gp) return null;
+    return { index, id: gp.id, mapping: gp.mapping, connected: gp.connected };
   }
 
   /** Get mouse movement delta this frame */
@@ -369,6 +1216,278 @@ export class InputManager {
     return { x: this.mouseDeltaX, y: this.mouseDeltaY };
   }
 
+  /**
+   * 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 {
+    return this.lastActiveDevice;
+  }
+
+  // ==========================================================================
+  // F3 — rebinding: list/replace/add/remove/reset/persist. See the class doc
+  // comment above for the full design note.
+  // ==========================================================================
+
+  /** 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[] {
+    const bindings = this.actions.get(actionName);
+    return bindings ? structuredClone(bindings) : [];
+  }
+
+  /** 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 {
+    if (!this.actionValueTypes.has(actionName)) this.actionValueTypes.set(actionName, 'digital');
+    this.actions.set(actionName, structuredClone(bindings));
+  }
+
+  /** Append one binding to `actionName` (F3 AC "added"). */
+  addBinding(actionName: string, binding: InputBinding): void {
+    const bindings = this.actions.get(actionName) ?? [];
+    this.actions.set(actionName, [...bindings, structuredClone(binding)]);
+    if (!this.actionValueTypes.has(actionName)) this.actionValueTypes.set(actionName, 'digital');
+  }
+
+  /** 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 {
+    const bindings = this.actions.get(actionName);
+    if (!bindings || index < 0 || index >= bindings.length) return;
+    this.actions.set(actionName, [...bindings.slice(0, index), ...bindings.slice(index + 1)]);
+  }
+
+  /** 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 {
+    const bindings = this.actions.get(actionName);
+    if (!bindings || index < 0 || index >= bindings.length) return;
+    const next = bindings.slice();
+    next[index] = structuredClone(binding);
+    this.actions.set(actionName, next);
+  }
+
+  /** 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 {
+    const defaults = this.defaultBindings.get(actionName);
+    if (!defaults) return;
+    this.actions.set(actionName, structuredClone(defaults));
+  }
+
+  /** Reset every action that has a snapshot back to its registered/loaded
+   *  defaults. Convenience batch form of `resetBindings`. */
+  resetAllBindings(): void {
+    for (const actionName of this.defaultBindings.keys()) this.resetBindings(actionName);
+  }
+
+  /**
+   * 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(a: InputBinding, b: InputBinding): boolean {
+    if (a.type !== b.type) return false;
+    switch (a.type) {
+      case 'key':
+        return a.code === (b as typeof a).code;
+      case 'mouse_button':
+        return a.button === (b as typeof a).button;
+      case 'mouse_move':
+        return true; // there is only one physical mouse-move source
+      case 'gamepad_button':
+        return a.button === (b as typeof a).button;
+      case 'gamepad_axis': {
+        const other = b as typeof a;
+        return a.axis === other.axis && a.direction === other.direction;
+      }
+      case 'gamepad_axis_pair': {
+        const other = b as typeof a;
+        return a.xAxis === other.xAxis && a.yAxis === other.yAxis;
+      }
+      case 'touch_button':
+      case 'touch_stick':
+      case 'test_axis':
+      case 'test_vector2':
+      case 'test_pointer_delta':
+      case 'test_pointer_position':
+        return a.sourceId === (b as typeof a).sourceId;
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * 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[] {
+    const conflicts: BindingConflict[] = [];
+    for (const [actionName, bindings] of this.actions) {
+      if (actionName === excludeActionName) continue;
+      bindings.forEach((binding, bindingIndex) => {
+        if (InputManager.bindingsCollide(proposed, binding)) {
+          conflicts.push({ actionName, bindingIndex, binding: structuredClone(binding) });
+        }
+      });
+    }
+    return conflicts;
+  }
+
+  /**
+   * 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 {
+    const actions: InputMapFile['actions'] = {};
+    for (const [name, bindings] of this.actions) {
+      actions[name] = {
+        valueType: this.actionValueTypes.get(name) ?? 'digital',
+        bindings: structuredClone(bindings),
+      };
+    }
+    return { version: this.loadedMapVersion, actions };
+  }
+
+  /**
+   * 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 = 0): BindingPrompt | null {
+    const resolvedDevice = device ?? this.lastActiveDevice ?? 'keyboard';
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return null;
+    const binding = bindings.find((b) => bindingDeviceFamily(b.type) === resolvedDevice);
+    if (!binding) return null;
+
+    switch (binding.type) {
+      case 'key':
+        return {
+          device: 'keyboard',
+          bindingType: 'key',
+          label: keyLabel(binding.code),
+          icon: keyLabel(binding.code),
+        };
+      case 'mouse_button':
+        return {
+          device: 'mouse',
+          bindingType: 'mouse_button',
+          label: mouseButtonLabel(binding.button),
+          icon: 'mouse',
+        };
+      case 'mouse_move':
+        return { device: 'mouse', bindingType: 'mouse_move', label: 'Mouse', icon: 'mouse' };
+      case 'gamepad_button': {
+        const info = this.getGamepadInfo(gamepadIndex);
+        if (!info?.connected) {
+          return {
+            device: 'gamepad',
+            bindingType: 'gamepad_button',
+            label: 'Gamepad Disconnected',
+            icon: 'gamepad-off',
+          };
+        }
+        const label =
+          info.mapping === 'standard'
+            ? (STANDARD_GAMEPAD_BUTTON_LABELS[binding.button] ?? `Button ${binding.button}`)
+            : `Button ${binding.button}`;
+        return { device: 'gamepad', bindingType: 'gamepad_button', label, icon: label };
+      }
+      case 'gamepad_axis': {
+        const info = this.getGamepadInfo(gamepadIndex);
+        if (!info?.connected) {
+          return {
+            device: 'gamepad',
+            bindingType: 'gamepad_axis',
+            label: 'Gamepad Disconnected',
+            icon: 'gamepad-off',
+          };
+        }
+        return {
+          device: 'gamepad',
+          bindingType: 'gamepad_axis',
+          label: gamepadAxisLabel(binding.axis),
+          icon: 'gamepad-stick',
+        };
+      }
+      case 'gamepad_axis_pair': {
+        const info = this.getGamepadInfo(gamepadIndex);
+        if (!info?.connected) {
+          return {
+            device: 'gamepad',
+            bindingType: 'gamepad_axis_pair',
+            label: 'Gamepad Disconnected',
+            icon: 'gamepad-off',
+          };
+        }
+        return {
+          device: 'gamepad',
+          bindingType: 'gamepad_axis_pair',
+          label: gamepadAxisPairLabel(binding.xAxis, binding.yAxis),
+          icon: 'gamepad-stick',
+        };
+      }
+      case 'touch_button':
+        return {
+          device: 'touch',
+          bindingType: 'touch_button',
+          label: binding.sourceId,
+          icon: 'touch',
+        };
+      case 'touch_stick':
+        return {
+          device: 'touch',
+          bindingType: 'touch_stick',
+          label: binding.sourceId,
+          icon: 'touch',
+        };
+      default:
+        return null;
+    }
+  }
+
   /** Call at end of frame to clear per-frame state */
   endFrame() {
     this.keysJustDown.clear();
@@ -385,6 +1504,13 @@ export class InputManager {
     this.gamepadAxesPrev = this.gamepadAxesCurrent;
     this.mouseDeltaX = 0;
     this.mouseDeltaY = 0;
+    // F1 — pointerDelta is a per-frame accumulator, same shape as
+    // mouseDeltaX/Y above; axis/vector2/pointerPosition are level values and
+    // deliberately NOT reset here (they persist until changed/cleared).
+    this.testPointerDeltaAccum.clear();
+    // F2 — touch-button edges, same shape as the mouse-button edges above.
+    this.touchButtonsJustDown.clear();
+    this.touchButtonsJustUp.clear();
   }
 
   /** Inject synthetic key state from touch controls */
@@ -410,6 +1536,49 @@ export class InputManager {
     this.mouseDeltaY += dy;
   }
 
+  /**
+   * 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 {
+    if (!this.inputActive) return;
+    if (pressed) {
+      if (!this.touchButtonsDown.has(sourceId)) this.touchButtonsJustDown.add(sourceId);
+      this.touchButtonsDown.add(sourceId);
+      this.lastActiveDevice = 'touch'; // F4
+    } else {
+      if (this.touchButtonsDown.has(sourceId)) this.touchButtonsJustUp.add(sourceId);
+      this.touchButtonsDown.delete(sourceId);
+    }
+  }
+
+  /**
+   * 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 {
+    this.touchStickValues.set(sourceId, value);
+    // F4 — mirrors the gamepad-axis heuristic in poll() (see `isStickActive`).
+    if (InputManager.isStickActive(value)) this.lastActiveDevice = 'touch';
+  }
+
+  /** Clear a virtual stick's value (e.g. simulating the touch point lifting —
+   *  the knob returns to center). */
+  clearTouchStick(sourceId: string): void {
+    this.touchStickValues.delete(sourceId);
+  }
+
   /** Request pointer lock for FPS-style mouse control */
   requestPointerLock(element: HTMLElement) {
     // Idempotent: never stack duplicate click listeners. Rewire if the element
@@ -431,6 +1600,11 @@ export class InputManager {
     window.removeEventListener('mousedown', this.onMouseDown);
     window.removeEventListener('mouseup', this.onMouseUp);
     window.removeEventListener('mousemove', this.onMouseMove);
+    window.removeEventListener('blur', this.onWindowBlur);
+    window.removeEventListener('focus', this.onWindowFocus);
+    if (typeof document !== 'undefined' && typeof document.removeEventListener === 'function') {
+      document.removeEventListener('pointerlockchange', this.onPointerLockChange);
+    }
     if (this.pointerLockElement) {
       this.pointerLockElement.removeEventListener('click', this.onPointerLockClick);
       this.pointerLockElement = null;