@vgai/engine 0.2.0

package/src/ecs/game-component.ts

@@ -0,0 +1,147 @@
+import type RAPIER2D from '@dimforge/rapier2d-compat';
+import type RAPIER3D from '@dimforge/rapier3d-compat';
+import type * as PIXI from 'pixi.js';
+import type * as THREE from 'three';
+import type { z } from 'zod';
+import type { SystemPhaseName } from '../core/types';
+import type { WorldInstance, WorldKind } from '../runtime/game';
+import type { GameContext } from '../runtime/types';
+
+/**
+ * Map a {@link WorldKind} to its native world node type (T7.2, D8 —
+ * `docs/GAME-COMPONENT-GENERALIZATION.md` §2). `react` maps to `never`: react
+ * entities host no GameComponents (they render from game state via the T7.4
+ * state bridge instead).
+ */
+export type NodeOf<K extends WorldKind> = K extends 'threejs'
+  ? THREE.Object3D
+  : K extends 'pixijs'
+    ? PIXI.Container
+    : never;
+
+/** Map a {@link WorldKind} to its native Rapier rigid-body type. */
+export type BodyOf<K extends WorldKind> = K extends 'threejs'
+  ? RAPIER3D.RigidBody
+  : K extends 'pixijs'
+    ? RAPIER2D.RigidBody
+    : never;
+
+/** Map a {@link WorldKind} to its native Rapier collider type. */
+export type ColliderOf<K extends WorldKind> = K extends 'threejs'
+  ? RAPIER3D.Collider
+  : K extends 'pixijs'
+    ? RAPIER2D.Collider
+    : never;
+
+/**
+ * Base class for game components attached to entities.
+ *
+ * Generalized (T7.2, D8 — `docs/GAME-COMPONENT-GENERALIZATION.md`) over the
+ * world kind `K` (default `'threejs'`, so every existing component — all of
+ * which extend the bare `GameComponent` — compiles and runs unchanged). The
+ * world's native node IS the entity — there is no separate entity id and no
+ * mirror/sync layer (Track A). Each component instance holds a direct
+ * reference to its node and (if any) its Rapier rigid body/collider. The
+ * ComponentManager wires these up in `attach()`.
+ *
+ * Similar to Unity's MonoBehaviour or Godot's Node scripts:
+ * - `init()` — called once after the entity is fully constructed
+ * - `update(dt, ctx)` — called every fixed timestep, in the component's phase
+ * - `dispose(ctx)` — called when the entity is destroyed
+ * - `onTriggerEnter/onTriggerExit` — called when a sensor collider overlap
+ *   starts/stops, with the other party's native node
+ *
+ * State lives on `this` (instance properties). On HMR, the engine swaps the
+ * prototype via Object.setPrototypeOf — instance state survives, method bodies
+ * update to the new code.
+ */
+export abstract class GameComponent<K extends WorldKind = 'threejs'> {
+  /** Which phase this component's update runs in. Override in subclasses. */
+  static phase: SystemPhaseName = 'gameLogic';
+
+  /**
+   * Runtime-checkable declaration of which {@link WorldKind} this component
+   * is written for (T7.2, D8 §3 — `docs/GAME-COMPONENT-GENERALIZATION.md`).
+   * TS's `K` type parameter is erased at runtime, so this static is what the
+   * ComponentManager checks at attach time: a node whose world's kind
+   * doesn't match `declaredKind` THROWS at attach (a `GameComponent<'pixijs'>`
+   * attached to a threejs entity, or vice versa). Kind-agnostic components —
+   * written only against `node`/`this.world`, never the typed `object3D`
+   * accessor or a kind-specific field — may declare `'any'` and attach in
+   * any world components are legal in (every world except `'react'`, which
+   * always throws regardless of `declaredKind` — see the ComponentManager).
+   */
+  static declaredKind: WorldKind | 'any' = 'threejs';
+
+  /**
+   * Optional Zod object schema for this component's authored fields. When set,
+   * scene data is validated + defaulted through `schema.parse(data)` before being
+   * assigned onto the instance. Also powers (later) the editor's schema-driven
+   * inspector and HMR defaults.
+   */
+  static schema?: z.ZodObject<z.ZodRawShape>;
+
+  /** The native world node. The node IS the entity. */
+  node!: NodeOf<K>;
+
+  /** The world instance this component's entity lives in (wired at attach). */
+  world!: WorldInstance;
+
+  /**
+   * Typed accessor, threejs worlds only — kept for compatibility. On a
+   * `GameComponent` (default `K`) this types as `THREE.Object3D`, so every
+   * existing component compiles unchanged. On a non-threejs instance it
+   * THROWS a descriptive error rather than ever returning a wrong-kind node —
+   * use `this.node` (or `this.world.kind` to check first) instead.
+   */
+  get object3D(): THREE.Object3D {
+    const kind = this.world?.kind;
+    if (kind !== undefined && kind !== 'threejs') {
+      throw new Error(
+        `${this.constructor.name}.object3D: this component's world (kind: "${kind}") is not a ` +
+          'threejs world — `object3D` only ever returns a THREE.Object3D; use `this.node` instead.',
+      );
+    }
+    // When the world isn't wired yet (silo-attached 2D components until
+    // T7.3; bare instances), fall back to the static declaration so a
+    // GameComponent<'pixijs'> can never silently hand out its Container
+    // typed as an Object3D.
+    if (kind === undefined) {
+      const declared = (this.constructor as typeof GameComponent).declaredKind;
+      if (declared !== 'threejs' && declared !== 'any') {
+        throw new Error(
+          `${this.constructor.name}.object3D: this component declares kind "${declared}" — ` +
+            '`object3D` only ever returns a THREE.Object3D; use `this.node` instead.',
+        );
+      }
+    }
+    return this.node as unknown as THREE.Object3D;
+  }
+
+  /** The entity's native rigid body, if it has physics. */
+  rigidBody: BodyOf<K> | null = null;
+
+  /** The entity's native collider, if it has physics. */
+  collider: ColliderOf<K> | null = null;
+
+  /** Called once after the entity is fully constructed (node, physics, etc.). */
+  init?(ctx: GameContext): void | Promise<void>;
+
+  /** Called every fixed timestep. */
+  abstract update(dt: number, ctx: GameContext): void;
+
+  /** Called when the entity is destroyed or the component is removed. */
+  dispose?(ctx: GameContext): void;
+
+  /** Called when a sensor overlap with `other` begins. */
+  onTriggerEnter?(other: NodeOf<K>, ctx: GameContext): void;
+
+  /** Called when a sensor overlap with `other` ends. */
+  onTriggerExit?(other: NodeOf<K>, ctx: GameContext): void;
+}
+
+/** Constructor type for GameComponent subclasses (carries static phase/schema). */
+export type GameComponentClass = (new () => GameComponent) & {
+  phase?: SystemPhaseName;
+  schema?: z.ZodObject<z.ZodRawShape>;
+};

package/src/ecs/hmr-swap-report.ts

@@ -0,0 +1,65 @@
+/**
+ * HMR swap-miss report — T5.4 (docs/BACKBONE-TASKS.md's Track 5 table:
+ * "Deterministic HMR: registry-keyed hotSwap (not `constructor.name`), schema
+ * re-parse on swap, loud swap-miss warnings"). `ComponentManager.hotSwap` keys
+ * live instances by the `componentRegistry` name recorded on them at attach
+ * (see `component-manager.ts`'s `attach`/`hotSwap`), NOT the live
+ * `constructor.name` — fragile under minification, class renames, or two
+ * classes sharing one name. This module is the structured, greppable
+ * `console.warn` a swap-miss warrants, mirrored on the established
+ * prefix + JSON-payload pattern (`packages/editor/src/achieved-tier.ts`'s
+ * `TIER_SHORTFALL_PREFIX`, `packages/editor/src/authoring/overlay-report.ts`'s
+ * `OVERLAY_REPORT_PREFIX`) — kept dependency-free (no `window`/editor-console
+ * import) so it stays importable from a headless engine/runtime context,
+ * same discipline as those two files.
+ *
+ * Two independent miss reasons, per the BACKBONE-TASKS detail note:
+ *   - `'no-live-instance'` — the incoming hot update's key (the
+ *     `componentRegistry` name the recompiled module was re-exported under)
+ *     matches no currently-attached instance's recorded registry key (nor,
+ *     for an instance attached WITHOUT a registry key — an ad-hoc,
+ *     code-attached component — its `constructor.name`). This is the
+ *     "renamed class → loud miss" case: a class rename changes the export
+ *     key a hot update arrives under, so no live instance is found under the
+ *     NEW key — the OLD prototype is simply left in place (never silently
+ *     dropped, never crashed).
+ *   - `'schema-reparse-failed'` — at least one matched instance's swap
+ *     succeeded (prototype replaced), but re-validating its authored props
+ *     against the NEW class's `static schema` threw; that instance's fields
+ *     are left exactly as they were (last-good props), never partially or
+ *     invalidly overwritten.
+ */
+
+/** Greppable prefix shared by every swap-miss log line this module produces. */
+export const HMR_SWAP_MISS_PREFIX = 'hmr-swap-miss';
+
+export type HmrSwapMissReport =
+  | { key: string; reason: 'no-live-instance' }
+  | { key: string; reason: 'schema-reparse-failed'; error: string };
+
+/**
+ * The one shared message shape — greppable on the prefix, JSON-parseable on
+ * the trailing payload (the LAST `{...}` in the string — the human-readable
+ * `detail` clause never itself contains a brace, even for the
+ * `'schema-reparse-failed'` reason, whose full Zod error text — itself a
+ * JSON-issues blob, braces included — is carried only in `report.error`
+ * inside that trailing payload, never inlined into `detail`).
+ */
+export function formatHmrSwapMissMessage(report: HmrSwapMissReport): string {
+  const detail =
+    report.reason === 'no-live-instance'
+      ? `no live instance's registry key (or, for an ad-hoc/unregistered instance, its class name) ` +
+        `matches "${report.key}" — the hot update had nothing to swap (old class, if any, left in place)`
+      : `schema re-parse failed for "${report.key}" after swap — keeping the instance's last-good ` +
+        `props (Zod error in the trailing payload's "error" field)`;
+  return (
+    `${HMR_SWAP_MISS_PREFIX} ${detail} (T5.4, docs/BACKBONE-TASKS.md). ` +
+    `${HMR_SWAP_MISS_PREFIX} ${JSON.stringify(report)}`
+  );
+}
+
+/** Emit the ONE structured `console.warn` a swap-miss warrants — never a silent no-op. */
+export function logHmrSwapMiss(report: HmrSwapMissReport): void {
+  // biome-ignore lint/suspicious/noConsole: structured, greppable swap-miss warning (T5.4) — mirrors achieved-tier.ts/overlay-report.ts's deliberate direct console.warn
+  console.warn(formatHmrSwapMissMessage(report));
+}

package/src/input/input-manager.ts

@@ -0,0 +1,439 @@
+import { resolveUrl } from '../loader';
+import { SceneParseError } from '../scene/parse';
+import type { InputBinding, InputMapFile } from './input-types';
+import { InputMapFileSchema } from './schema';
+
+/**
+ * True when a text-entry element is focused, so game input shouldn't also fire
+ * (e.g. typing into an editor inspector field / renaming an entity). Cheap guard
+ * that holds even when the game viewport is the active tab.
+ */
+function isTextEntryFocused(): boolean {
+  const el = typeof document !== 'undefined' ? document.activeElement : null;
+  if (!el) return false;
+  const tag = el.tagName;
+  return (
+    tag === 'INPUT' ||
+    tag === 'TEXTAREA' ||
+    tag === 'SELECT' ||
+    (el as HTMLElement).isContentEditable === true
+  );
+}
+
+/**
+ * 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
+ */
+export class InputManager {
+  private actions = new Map<string, InputBinding[]>();
+  private keysDown = new Set<string>();
+  private keysJustDown = new Set<string>();
+  private keysJustUp = new Set<string>();
+  private mouseButtons = new Set<number>();
+  private mouseButtonsJustDown = new Set<number>();
+  private mouseButtonsJustUp = new Set<number>();
+  private mouseDeltaX = 0;
+  private mouseDeltaY = 0;
+  private gamepads: (Gamepad | null)[] = [];
+  // Gamepad button edge tracking (P1.6c). Keys are `${gamepadIndex}:${buttonIndex}`.
+  // `Prev` is last frame's pressed set; `Down` is this frame's; the just-down/up
+  // sets are the per-frame diff computed in poll() and cleared in endFrame().
+  private gamepadButtonsDown = new Set<string>();
+  private gamepadButtonsPrev = new Set<string>();
+  private gamepadButtonsJustDown = new Set<string>();
+  private gamepadButtonsJustUp = new Set<string>();
+  // Gamepad axis edge tracking: raw per-(gamepad,axis) values, this frame vs
+  // last frame, so `gamepad_axis` bindings can compute a thresholded
+  // (direction + deadzone) boolean for THIS frame and compare it against the
+  // same threshold applied to last frame's raw value — giving real
+  // isJustPressed/isJustReleased edges for an otherwise-continuous input.
+  // Keys are `${gamepadIndex}:${axisIndex}`; `Prev` is carried forward in
+  // endFrame(), mirroring the button edge-tracking above.
+  private gamepadAxesCurrent = new Map<string, number>();
+  private gamepadAxesPrev = new Map<string, number>();
+  private lookStickX = 0;
+  private lookStickY = 0;
+  private disposed = false;
+  /**
+   * 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 = true;
+  /** Element currently wired for click-to-pointer-lock, and its listener. */
+  private pointerLockElement: HTMLElement | null = null;
+  private onPointerLockClick = () => {
+    this.pointerLockElement?.requestPointerLock();
+  };
+
+  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;
+    if (!this.keysDown.has(e.code)) {
+      this.keysJustDown.add(e.code);
+    }
+    this.keysDown.add(e.code);
+  };
+
+  private onKeyUp = (e: KeyboardEvent) => {
+    if (!this.enabled) return;
+    this.keysDown.delete(e.code);
+    this.keysJustUp.add(e.code);
+  };
+
+  private onMouseDown = (e: MouseEvent) => {
+    if (!this.enabled) return;
+    this.mouseButtons.add(e.button);
+    this.mouseButtonsJustDown.add(e.button);
+  };
+
+  private onMouseUp = (e: MouseEvent) => {
+    if (!this.enabled) return;
+    this.mouseButtons.delete(e.button);
+    this.mouseButtonsJustUp.add(e.button);
+  };
+
+  private onMouseMove = (e: MouseEvent) => {
+    if (!this.enabled) return;
+    this.mouseDeltaX += e.movementX;
+    this.mouseDeltaY += e.movementY;
+  };
+
+  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);
+  }
+
+  /**
+   * 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`.
+   */
+  async loadMap(url: string) {
+    let data: InputMapFile;
+    try {
+      const res = await fetch(resolveUrl(url));
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status} ${res.statusText}`);
+      }
+      const json = await res.json();
+      const result = InputMapFileSchema.safeParse(json);
+      if (!result.success) throw new SceneParseError(result.error.issues, url);
+      data = result.data;
+    } catch (err) {
+      const message = `InputManager.loadMap: failed to load input map "${url}": ${
+        err instanceof Error ? err.message : String(err)
+      }`;
+      console.error(message);
+      throw err instanceof SceneParseError ? err : new Error(message);
+    }
+    for (const [name, action] of Object.entries(data.actions)) {
+      this.actions.set(name, action.bindings);
+    }
+  }
+
+  /** Register an action programmatically */
+  registerAction(name: string, bindings: InputBinding[]) {
+    this.actions.set(name, bindings);
+  }
+
+  /** The names of all registered actions (for the InputAdapter to enumerate). */
+  actionNames(): string[] {
+    return [...this.actions.keys()];
+  }
+
+  /** 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
+      // (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
+      // re-enabled, so there's no phantom edge on re-enable (mirrors the
+      // "flush held state, don't corrupt history" intent of setEnabled below).
+      this.gamepads = [];
+      return;
+    }
+    this.gamepads = navigator.getGamepads ? [...navigator.getGamepads()] : [];
+
+    // Gamepad button edge detection: diff this frame's pressed set against the
+    // previous frame's so isJustPressed/isJustReleased work for gamepads too.
+    const current = new Set<string>();
+    for (let i = 0; i < this.gamepads.length; i++) {
+      const gp = this.gamepads[i];
+      if (!gp) continue;
+      for (let b = 0; b < gp.buttons.length; b++) {
+        if (gp.buttons[b]?.pressed) current.add(`${i}:${b}`);
+      }
+    }
+    for (const key of current) {
+      if (!this.gamepadButtonsPrev.has(key)) this.gamepadButtonsJustDown.add(key);
+    }
+    for (const key of this.gamepadButtonsPrev) {
+      if (!current.has(key)) this.gamepadButtonsJustUp.add(key);
+    }
+    this.gamepadButtonsDown = current;
+
+    // Snapshot this frame's raw axis values per (gamepad, axis) — independent
+    // of any binding's direction/deadzone, mirroring the button snapshot
+    // above. isPressed/isJustPressed/isJustReleased apply a binding's own
+    // threshold to these raw values (current vs. `gamepadAxesPrev`) on read.
+    const currentAxes = new Map<string, number>();
+    for (let i = 0; i < this.gamepads.length; i++) {
+      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);
+      }
+    }
+    this.gamepadAxesCurrent = currentAxes;
+
+    // Inject look stick as continuous mouse delta (position → rate-of-rotation)
+    if (this.lookStickX !== 0 || this.lookStickY !== 0) {
+      const scale = 8;
+      this.mouseDeltaX += this.lookStickX * scale;
+      this.mouseDeltaY += this.lookStickY * scale;
+    }
+  }
+
+  /** Has a `gamepad_axis` binding's raw value crossed its direction+deadzone
+   *  threshold (positive: `value > deadzone`; negative: `value < -deadzone`)? */
+  private static axisThresholdMet(
+    value: number,
+    direction: 'positive' | 'negative',
+    deadzone: number,
+  ): boolean {
+    return direction === 'positive' ? value > deadzone : value < -deadzone;
+  }
+
+  /** Is an action currently held down? */
+  isPressed(actionName: string): boolean {
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return false;
+
+    for (const binding of bindings) {
+      switch (binding.type) {
+        case 'key':
+          if (this.keysDown.has(binding.code)) return true;
+          break;
+        case 'mouse_button':
+          if (this.mouseButtons.has(binding.button)) return true;
+          break;
+        case 'gamepad_button':
+          for (const gp of this.gamepads) {
+            if (gp?.buttons[binding.button]?.pressed) return true;
+          }
+          break;
+        case 'gamepad_axis': {
+          const dz = binding.deadzone ?? 0.15;
+          for (const gp of this.gamepads) {
+            if (!gp) continue;
+            const val = gp.axes[binding.axis] ?? 0;
+            if (InputManager.axisThresholdMet(val, binding.direction, dz)) return true;
+          }
+          break;
+        }
+      }
+    }
+    return false;
+  }
+
+  /** Was an action pressed this frame (not held from previous)? */
+  isJustPressed(actionName: string): boolean {
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return false;
+
+    for (const binding of bindings) {
+      switch (binding.type) {
+        case 'key':
+          if (this.keysJustDown.has(binding.code)) return true;
+          break;
+        case 'mouse_button':
+          if (this.mouseButtonsJustDown.has(binding.button)) return true;
+          break;
+        case 'gamepad_button':
+          // Edge-tracked in poll(): true only on the first frame the button
+          // transitions from up→down (across any connected gamepad).
+          for (let i = 0; i < this.gamepads.length; i++) {
+            if (this.gamepadButtonsJustDown.has(`${i}:${binding.button}`)) return true;
+          }
+          break;
+        case 'gamepad_axis': {
+          // Edge-tracked via raw axis snapshots (poll()): true only on the
+          // first frame the thresholded (direction+deadzone) boolean flips
+          // from off→on (across any connected gamepad).
+          const dz = binding.deadzone ?? 0.15;
+          for (let i = 0; i < this.gamepads.length; i++) {
+            const key = `${i}:${binding.axis}`;
+            const now = this.gamepadAxesCurrent.get(key) ?? 0;
+            const prev = this.gamepadAxesPrev.get(key) ?? 0;
+            const nowOn = InputManager.axisThresholdMet(now, binding.direction, dz);
+            const prevOn = InputManager.axisThresholdMet(prev, binding.direction, dz);
+            if (nowOn && !prevOn) return true;
+          }
+          break;
+        }
+      }
+    }
+    return false;
+  }
+
+  /** Was an action released this frame (held last frame, up now)? */
+  isJustReleased(actionName: string): boolean {
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return false;
+
+    for (const binding of bindings) {
+      switch (binding.type) {
+        case 'key':
+          if (this.keysJustUp.has(binding.code)) return true;
+          break;
+        case 'mouse_button':
+          if (this.mouseButtonsJustUp.has(binding.button)) return true;
+          break;
+        case 'gamepad_button':
+          for (let i = 0; i < this.gamepads.length; i++) {
+            if (this.gamepadButtonsJustUp.has(`${i}:${binding.button}`)) return true;
+          }
+          break;
+        case 'gamepad_axis': {
+          // The mirror of isJustPressed: true only on the first frame the
+          // thresholded boolean flips from on→off.
+          const dz = binding.deadzone ?? 0.15;
+          for (let i = 0; i < this.gamepads.length; i++) {
+            const key = `${i}:${binding.axis}`;
+            const now = this.gamepadAxesCurrent.get(key) ?? 0;
+            const prev = this.gamepadAxesPrev.get(key) ?? 0;
+            const nowOn = InputManager.axisThresholdMet(now, binding.direction, dz);
+            const prevOn = InputManager.axisThresholdMet(prev, binding.direction, dz);
+            if (!nowOn && prevOn) return true;
+          }
+          break;
+        }
+      }
+    }
+    return false;
+  }
+
+  /** Whether input capture is currently enabled (see {@link setEnabled}). */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * 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).
+   */
+  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;
+    }
+  }
+
+  /** Get mouse movement delta this frame */
+  getMouseDelta(): { x: number; y: number } {
+    return { x: this.mouseDeltaX, y: this.mouseDeltaY };
+  }
+
+  /** Call at end of frame to clear per-frame state */
+  endFrame() {
+    this.keysJustDown.clear();
+    this.keysJustUp.clear();
+    this.mouseButtonsJustDown.clear();
+    this.mouseButtonsJustUp.clear();
+    // Carry this frame's gamepad pressed set forward as next frame's baseline,
+    // then clear the per-frame edge sets.
+    this.gamepadButtonsPrev = this.gamepadButtonsDown;
+    this.gamepadButtonsJustDown.clear();
+    this.gamepadButtonsJustUp.clear();
+    // Carry this frame's raw axis snapshot forward as next frame's baseline
+    // for gamepad_axis edge detection (isJustPressed/isJustReleased).
+    this.gamepadAxesPrev = this.gamepadAxesCurrent;
+    this.mouseDeltaX = 0;
+    this.mouseDeltaY = 0;
+  }
+
+  /** Inject synthetic key state from touch controls */
+  setVirtualKey(code: string, pressed: boolean) {
+    if (pressed) {
+      if (!this.keysDown.has(code)) this.keysJustDown.add(code);
+      this.keysDown.add(code);
+    } else {
+      if (this.keysDown.has(code)) this.keysJustUp.add(code);
+      this.keysDown.delete(code);
+    }
+  }
+
+  /** Set virtual look stick position (-1..1). Injected as mouse delta during poll(). */
+  setLookStick(x: number, y: number) {
+    this.lookStickX = x;
+    this.lookStickY = y;
+  }
+
+  /** Inject synthetic mouse delta (e.g. from touch controls) */
+  addMouseDelta(dx: number, dy: number) {
+    this.mouseDeltaX += dx;
+    this.mouseDeltaY += dy;
+  }
+
+  /** Request pointer lock for FPS-style mouse control */
+  requestPointerLock(element: HTMLElement) {
+    // Idempotent: never stack duplicate click listeners. Rewire if the element
+    // changed, and track it so dispose() can remove the listener.
+    if (this.pointerLockElement === element) return;
+    if (this.pointerLockElement) {
+      this.pointerLockElement.removeEventListener('click', this.onPointerLockClick);
+    }
+    this.pointerLockElement = element;
+    element.addEventListener('click', this.onPointerLockClick);
+  }
+
+  /** Clean up event listeners */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    window.removeEventListener('keydown', this.onKeyDown);
+    window.removeEventListener('keyup', this.onKeyUp);
+    window.removeEventListener('mousedown', this.onMouseDown);
+    window.removeEventListener('mouseup', this.onMouseUp);
+    window.removeEventListener('mousemove', this.onMouseMove);
+    if (this.pointerLockElement) {
+      this.pointerLockElement.removeEventListener('click', this.onPointerLockClick);
+      this.pointerLockElement = null;
+    }
+  }
+}

package/src/input/input-types.ts

@@ -0,0 +1,19 @@
+/** A single binding for an action */
+export type InputBinding =
+  | { type: 'key'; code: string }
+  | { type: 'mouse_button'; button: number }
+  | { type: 'mouse_move' }
+  | { type: 'gamepad_button'; button: number }
+  | { type: 'gamepad_axis'; axis: number; direction: 'positive' | 'negative'; deadzone?: number }
+  | { type: 'gamepad_axis_pair'; xAxis: number; yAxis: number; deadzone?: number };
+
+/** An action has a name and one or more bindings */
+export interface InputAction {
+  bindings: InputBinding[];
+}
+
+/** The .inputmap.json file format */
+export interface InputMapFile {
+  version: number;
+  actions: Record<string, InputAction>;
+}