@yagejs/input 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -34,6 +34,42 @@ var import_api = require("@yagejs/debug/api");
 
 // src/InputManager.ts
 var import_core = require("@yagejs/core");
+var MOUSE_BUTTON_CODES = ["MouseLeft", "MouseMiddle", "MouseRight"];
+var STANDARD_BUTTON_CODES = [
+  "GamepadA",
+  "GamepadB",
+  "GamepadX",
+  "GamepadY",
+  "GamepadLB",
+  "GamepadRB",
+  "GamepadLT",
+  "GamepadRT",
+  "GamepadSelect",
+  "GamepadStart",
+  "GamepadLeftStick",
+  "GamepadRightStick",
+  "GamepadDPadUp",
+  "GamepadDPadDown",
+  "GamepadDPadLeft",
+  "GamepadDPadRight",
+  "GamepadHome"
+];
+var TRIGGER_LEFT_INDEX = 6;
+var TRIGGER_RIGHT_INDEX = 7;
+var STICK_AXIS_KEYS = {
+  left: { x: "leftX", y: "leftY" },
+  right: { x: "rightX", y: "rightY" }
+};
+var TRIGGER_AXIS_KEYS = {
+  left: "leftTrigger",
+  right: "rightTrigger"
+};
+var STANDARD_AXIS_KEYS = [
+  "leftX",
+  "leftY",
+  "rightX",
+  "rightY"
+];
 var InputManager = class {
   static {
     __name(this, "InputManager");
@@ -49,11 +85,64 @@ var InputManager = class {
   groups = /* @__PURE__ */ new Map();
   actionGroups = /* @__PURE__ */ new Map();
   disabledGroups = /* @__PURE__ */ new Set();
-  pointerScreenPos = import_core.Vec2.ZERO;
-  pointerDownState = false;
-  pressedMouseButtons = /* @__PURE__ */ new Set();
-  gamepadButtons = /* @__PURE__ */ new Map();
-  gamepadAxes = /* @__PURE__ */ new Map();
+  /** Tracked pointers keyed by `pointerId`. Mouse persists; touch/pen removed on up/cancel. */
+  pointers = /* @__PURE__ */ new Map();
+  /** Id of the pointer the browser last marked `isPrimary`, or `null` when none are tracked. */
+  primaryPointerId = null;
+  /**
+   * Aggregate "any pointer has this button held" cache. The action-map codes
+   * `MouseLeft`/`MouseMiddle`/`MouseRight` are driven from edges into/out of this
+   * set so two simultaneous taps holding button 0 do not double-fire.
+   * Consumed pointers are excluded from the aggregate so UI-claimed presses
+   * never propagate to gameplay actions.
+   */
+  mouseButtonAggregate = /* @__PURE__ */ new Set();
+  /**
+   * Pointers marked as "claimed" via {@link consumePointer} (or auto-claimed by
+   * the renderer's UI hit-test fallback). Lifetime is per-pointer-event-cycle:
+   * cleared when the pointer's last button releases (drained `pointerUp`) or on
+   * `pointercancel`.
+   */
+  consumedPointers = /* @__PURE__ */ new Set();
+  /** Wheel-edge gate flipped by {@link consumeWheel}. Cleared at end of frame. */
+  consumedWheelThisFrame = false;
+  /** Buffered DOM-originated events awaiting drain at `Phase.EarlyUpdate`. */
+  inputQueue = [];
+  /**
+   * Renderer reference for the optional `hitTestUI(x, y)` lookup. Stashed by
+   * {@link _setRenderer} during `InputPlugin.install` so the drain step can
+   * read it cheaply each frame.
+   */
+  renderer = null;
+  pointerDownListeners = [];
+  pointerUpListeners = [];
+  pointerMoveListeners = [];
+  keyDownListenersAny = [];
+  keyUpListenersAny = [];
+  keyDownListeners = /* @__PURE__ */ new Map();
+  keyUpListeners = /* @__PURE__ */ new Map();
+  actionListeners = /* @__PURE__ */ new Map();
+  actionReleasedListeners = /* @__PURE__ */ new Map();
+  wheelListeners = [];
+  /** Real-pad axis values keyed by `${padIndex}:${axisKey}`. */
+  gamepadAxisState = /* @__PURE__ */ new Map();
+  /** Synthetic axis values for fireGamepadAxis injection (test path). */
+  syntheticAxisState = /* @__PURE__ */ new Map();
+  /** "Any pad" aggregate of currently-pressed gamepad codes. */
+  lastButtonState = /* @__PURE__ */ new Map();
+  /** Per-pad "anything happening" flag, used to detect rising-edge activity for active-pad promotion. */
+  lastPadActivity = /* @__PURE__ */ new Map();
+  /** Pads currently known to the engine (populated via events or polling). */
+  connectedPads = /* @__PURE__ */ new Map();
+  /** Index of the pad whose analog input is read by default. `null` when no pad is connected. */
+  activePadIndex = null;
+  gamepadConnectListeners = [];
+  gamepadDisconnectListeners = [];
+  activePadListeners = [];
+  stickDeadzone = 0.15;
+  triggerDeadzone = 0.05;
+  triggerThreshold = 0.5;
+  pollingEnabled = true;
   camera = null;
   elapsedMs = 0;
   listenResolve = null;
@@ -118,24 +207,216 @@ var InputManager = class {
     return new import_core.Vec2(x, y);
   }
   // -- Pointer --
-  /** Pointer position in world coordinates (via Camera), or screen coords if no camera. */
+  /**
+   * Primary pointer's position in world coordinates (via Camera), or screen
+   * coords if no camera. Returns `Vec2.ZERO` when no pointer is tracked.
+   *
+   * For multi-pointer access (touch UIs etc.) iterate {@link getPointers} and
+   * convert each `screenPos` via the camera as needed.
+   */
   getPointerPosition() {
+    const primary = this.getPrimaryPointer();
+    if (!primary) return import_core.Vec2.ZERO;
     if (this.camera) {
-      const w = this.camera.screenToWorld(
-        this.pointerScreenPos.x,
-        this.pointerScreenPos.y
-      );
+      const w = this.camera.screenToWorld(primary.screenPos.x, primary.screenPos.y);
       return new import_core.Vec2(w.x, w.y);
     }
-    return this.pointerScreenPos;
+    return primary.screenPos;
   }
-  /** Raw pointer position in screen coordinates. */
+  /** Primary pointer's raw position in screen coordinates, or `Vec2.ZERO` when no pointer is tracked. */
   getPointerScreenPosition() {
-    return this.pointerScreenPos;
+    const primary = this.getPrimaryPointer();
+    return primary ? primary.screenPos : import_core.Vec2.ZERO;
   }
-  /** Whether any pointer button is currently held. */
+  /** Whether the primary pointer has any button held. */
   isPointerDown() {
-    return this.pointerDownState;
+    const primary = this.getPrimaryPointer();
+    return primary ? primary.isDown : false;
+  }
+  /** All currently-tracked pointers (one per active mouse, pen, or finger). */
+  getPointers() {
+    const out = [];
+    for (const p of this.pointers.values()) {
+      out.push(this.toPointerInfo(p));
+    }
+    return out;
+  }
+  /** Direct lookup by `pointerId`, or `undefined` if no pointer with that id is tracked. */
+  getPointer(id) {
+    const p = this.pointers.get(id);
+    return p ? this.toPointerInfo(p) : void 0;
+  }
+  /**
+   * Defensive snapshot of a tracked pointer. The runtime `MutablePointerInfo`
+   * holds a real `Set` for `buttons` — even though the `PointerInfo` type
+   * declares `ReadonlySet`, JS doesn't enforce that at runtime, so we copy the
+   * set on every public read. `Vec2` is convention-immutable across YAGE, so
+   * we share the same instance.
+   */
+  toPointerInfo(pointer) {
+    return {
+      id: pointer.id,
+      screenPos: pointer.screenPos,
+      type: pointer.type,
+      isPrimary: pointer.isPrimary,
+      buttons: new Set(pointer.buttons),
+      isDown: pointer.isDown
+    };
+  }
+  /**
+   * Subscribe to pointer-down events (button transitions from up → down on a
+   * tracked pointer). Returns a disposer that detaches the listener.
+   */
+  onPointerDown(fn) {
+    this.pointerDownListeners.push(fn);
+    return () => {
+      const idx = this.pointerDownListeners.indexOf(fn);
+      if (idx !== -1) this.pointerDownListeners.splice(idx, 1);
+    };
+  }
+  /**
+   * Subscribe to pointer-up events (button transitions from down → up, plus
+   * touch / pen lifecycle ends and `pointercancel`). Returns a disposer.
+   */
+  onPointerUp(fn) {
+    this.pointerUpListeners.push(fn);
+    return () => {
+      const idx = this.pointerUpListeners.indexOf(fn);
+      if (idx !== -1) this.pointerUpListeners.splice(idx, 1);
+    };
+  }
+  /** Subscribe to pointer-move events. Returns a disposer. */
+  onPointerMove(fn) {
+    this.pointerMoveListeners.push(fn);
+    return () => {
+      const idx = this.pointerMoveListeners.indexOf(fn);
+      if (idx !== -1) this.pointerMoveListeners.splice(idx, 1);
+    };
+  }
+  // -- Consume primitives --
+  /**
+   * Mark a pointer as claimed for the rest of its event cycle (down → up).
+   * Subsequent action-map edges for this pointer (e.g. the `MouseLeft` edge a
+   * `pointerdown` would normally fire) are suppressed; `onPointerDown/Up/Move`
+   * listeners still fire because they are explicit user opt-ins.
+   *
+   * The mark clears automatically when the pointer's last button releases or
+   * on `pointercancel`. Call from a Pixi `pointerdown` handler that wants to
+   * own the event: `manager.consumePointer(e.pointerId)`.
+   */
+  consumePointer(id) {
+    this.consumedPointers.add(id);
+  }
+  /** Whether the pointer is currently marked consumed. */
+  isPointerConsumed(id) {
+    return this.consumedPointers.has(id);
+  }
+  /**
+   * Suppress wheel action-map edges (`WheelUp/Down/Left/Right`) for the rest
+   * of the current frame. `onWheel` listeners still fire.
+   */
+  consumeWheel() {
+    this.consumedWheelThisFrame = true;
+  }
+  // -- Listener parity (keys, actions, wheel) --
+  /**
+   * Subscribe to key-down events. Pass a code (e.g. `"Space"`, `"GamepadA"`)
+   * to filter, or `"*"` for all keys. The listener fires on the same edge
+   * `isJustPressed` reports — for DOM-originated events that's the next
+   * `Phase.EarlyUpdate` after the browser dispatches; for synthetic injection
+   * (`fireKeyDown`) it's synchronous. Returns a disposer.
+   */
+  onKeyDown(code, fn) {
+    if (code === "*") {
+      this.keyDownListenersAny.push(fn);
+      return () => {
+        const idx = this.keyDownListenersAny.indexOf(fn);
+        if (idx !== -1) this.keyDownListenersAny.splice(idx, 1);
+      };
+    }
+    let arr = this.keyDownListeners.get(code);
+    if (!arr) {
+      arr = [];
+      this.keyDownListeners.set(code, arr);
+    }
+    arr.push(fn);
+    return () => {
+      const list = this.keyDownListeners.get(code);
+      if (!list) return;
+      const idx = list.indexOf(fn);
+      if (idx !== -1) list.splice(idx, 1);
+    };
+  }
+  /** Subscribe to key-up events. See {@link onKeyDown}. */
+  onKeyUp(code, fn) {
+    if (code === "*") {
+      this.keyUpListenersAny.push(fn);
+      return () => {
+        const idx = this.keyUpListenersAny.indexOf(fn);
+        if (idx !== -1) this.keyUpListenersAny.splice(idx, 1);
+      };
+    }
+    let arr = this.keyUpListeners.get(code);
+    if (!arr) {
+      arr = [];
+      this.keyUpListeners.set(code, arr);
+    }
+    arr.push(fn);
+    return () => {
+      const list = this.keyUpListeners.get(code);
+      if (!list) return;
+      const idx = list.indexOf(fn);
+      if (idx !== -1) list.splice(idx, 1);
+    };
+  }
+  /**
+   * Subscribe to action press edges (rising edge of any key bound to the
+   * action). Fires once per press. Returns a disposer.
+   */
+  onAction(name, fn) {
+    let arr = this.actionListeners.get(name);
+    if (!arr) {
+      arr = [];
+      this.actionListeners.set(name, arr);
+    }
+    arr.push(fn);
+    return () => {
+      const list = this.actionListeners.get(name);
+      if (!list) return;
+      const idx = list.indexOf(fn);
+      if (idx !== -1) list.splice(idx, 1);
+    };
+  }
+  /** Subscribe to action release edges. Returns a disposer. */
+  onActionReleased(name, fn) {
+    let arr = this.actionReleasedListeners.get(name);
+    if (!arr) {
+      arr = [];
+      this.actionReleasedListeners.set(name, arr);
+    }
+    arr.push(fn);
+    return () => {
+      const list = this.actionReleasedListeners.get(name);
+      if (!list) return;
+      const idx = list.indexOf(fn);
+      if (idx !== -1) list.splice(idx, 1);
+    };
+  }
+  /**
+   * Subscribe to scroll-wheel events. Receives raw `deltaX`/`deltaY` (already
+   * sign-flipped by `InputConfig.wheelInvertY` if set). Fires regardless of
+   * {@link consumeWheel} — it only gates action edges. Returns a disposer.
+   */
+  onWheel(fn) {
+    this.wheelListeners.push(fn);
+    return () => {
+      const idx = this.wheelListeners.indexOf(fn);
+      if (idx !== -1) this.wheelListeners.splice(idx, 1);
+    };
+  }
+  getPrimaryPointer() {
+    if (this.primaryPointerId === null) return null;
+    return this.pointers.get(this.primaryPointerId) ?? null;
   }
   // -- Runtime action map management --
   /** Replace the entire action map and store it as the default for {@link resetBindings}. */
@@ -331,44 +612,432 @@ var InputManager = class {
       resolve(null);
     }
   }
-  /** Public wrapper for synthetic key-down injection. */
+  /** Public wrapper for synthetic key-down injection. Applies sync. */
   fireKeyDown(code) {
-    this._onKeyDown(code);
+    this._applyKeyDown(code);
   }
-  /** Public wrapper for synthetic key-up injection. */
+  /** Public wrapper for synthetic key-up injection. Applies sync. */
   fireKeyUp(code) {
-    this._onKeyUp(code);
+    this._applyKeyUp(code);
   }
-  /** Public wrapper for synthetic pointer movement. */
-  firePointerMove(screenX, screenY) {
-    this._onPointerMove(screenX, screenY);
+  /**
+   * Public wrapper for synthetic pointer movement. Defaults to the primary
+   * mouse pointer (`id: 1`, `type: "mouse"`); pass `opts` to drive a specific
+   * touch / pen pointer.
+   */
+  firePointerMove(screenX, screenY, opts) {
+    this._applyPointerMove(this.makeSyntheticInfo(screenX, screenY, -1, opts));
   }
-  /** Public wrapper for synthetic pointer-button presses. */
-  firePointerDown(button = 0) {
-    this._onPointerDown();
-    this.pressedMouseButtons.add(button);
-    if (button === 0) this._onKeyDown("MouseLeft");
-    if (button === 1) this._onKeyDown("MouseMiddle");
-    if (button === 2) this._onKeyDown("MouseRight");
+  /**
+   * Public wrapper for synthetic pointer-button presses. Defaults to button 0
+   * on the primary mouse pointer. Pass `opts` for touch / pen / non-primary
+   * pointers (e.g. `{ id: 5, type: "touch", isPrimary: false }`).
+   */
+  firePointerDown(button = 0, opts) {
+    const id = opts?.id ?? 1;
+    const existing = this.pointers.get(id);
+    this._applyPointerDown(
+      this.makeSyntheticInfo(
+        existing?.screenPos.x ?? 0,
+        existing?.screenPos.y ?? 0,
+        button,
+        opts
+      )
+    );
   }
   /** Public wrapper for synthetic pointer-button releases. */
-  firePointerUp(button = 0) {
-    this.pressedMouseButtons.delete(button);
-    this.pointerDownState = this.pressedMouseButtons.size > 0;
-    if (!this.pointerDownState) {
-      this._onPointerUp();
+  firePointerUp(button = 0, opts) {
+    const id = opts?.id ?? 1;
+    const existing = this.pointers.get(id);
+    const info = {
+      id,
+      screenX: existing?.screenPos.x ?? 0,
+      screenY: existing?.screenPos.y ?? 0,
+      type: existing?.type ?? "mouse",
+      isPrimary: existing?.isPrimary ?? id === 1,
+      button
+    };
+    this._applyPointerUp(info);
+  }
+  /** Public wrapper for synthetic wheel input. Applies sync, including
+   * action edges and `onWheel` listener notification — matching the DOM path
+   * so tests and inspector probes drive the full surface. */
+  fireWheel(dx, dy) {
+    for (const fn of [...this.wheelListeners]) fn(dx, dy);
+    this.applyWheelEdges(dx, dy);
+  }
+  makeSyntheticInfo(screenX, screenY, button, opts) {
+    const id = opts?.id ?? 1;
+    return {
+      id,
+      screenX,
+      screenY,
+      type: opts?.type ?? "mouse",
+      isPrimary: opts?.isPrimary ?? id === 1,
+      button
+    };
+  }
+  /**
+   * Inject a synthetic gamepad button edge. Routes through the same internal
+   * path as real polling, so action queries (`isPressed`, `isJustPressed`),
+   * `listenForNextKey`, and rebinding all see the synthetic input.
+   *
+   * `code` should be a gamepad code string (e.g. `"GamepadA"`, `"GamepadLT"`).
+   * Used by inspector probes / deterministic tests in lieu of real polling.
+   */
+  fireGamepadButton(code, pressed) {
+    const wasPressed = this.lastButtonState.get(code) ?? false;
+    if (pressed && !wasPressed) {
+      this._applyKeyDown(code);
+      this.lastButtonState.set(code, true);
+    } else if (!pressed && wasPressed) {
+      this._applyKeyUp(code);
+      this.lastButtonState.delete(code);
+    }
+  }
+  /**
+   * Inject a synthetic gamepad axis value. Stored separately from real-pad
+   * axis state and consulted by `getStick` / `getTrigger` only when no real
+   * pad is active — matching how a test fixture would use the API.
+   *
+   * Trigger axes additionally emit `GamepadLT`/`GamepadRT` button edges when
+   * crossing `triggerThreshold`, mirroring real-pad polling so synthetic
+   * inspector probes drive `isPressed` the same way as physical hardware.
+   */
+  fireGamepadAxis(side, value) {
+    const safe = Number.isFinite(value) ? value : 0;
+    this.syntheticAxisState.set(side, safe);
+    if (side === "leftTrigger") {
+      this.fireGamepadButton("GamepadLT", safe >= this.triggerThreshold);
+    } else if (side === "rightTrigger") {
+      this.fireGamepadButton("GamepadRT", safe >= this.triggerThreshold);
+    }
+  }
+  // -- Gamepad analog API --
+  /**
+   * Returns the deadzoned, magnitude-clamped stick vector for the given side.
+   *
+   * By default reads from the active pad (the most recently used controller,
+   * or the first connected one if nothing has been used yet). Pass
+   * `{ pad: index }` to read from a specific pad — useful for couch-co-op
+   * where each player's controller is addressed explicitly.
+   *
+   * Falls back to synthetic injection (`fireGamepadAxis`) when no pad is
+   * active — that's the test/probe path.
+   */
+  getStick(side, opts) {
+    const { x: xKey, y: yKey } = STICK_AXIS_KEYS[side];
+    const padIdx = opts?.pad !== void 0 ? opts.pad : this.activePadIndex;
+    let x;
+    let y;
+    if (padIdx !== null) {
+      x = this.gamepadAxisState.get(`${padIdx}:${xKey}`) ?? 0;
+      y = this.gamepadAxisState.get(`${padIdx}:${yKey}`) ?? 0;
+    } else {
+      x = this.syntheticAxisState.get(xKey) ?? 0;
+      y = this.syntheticAxisState.get(yKey) ?? 0;
     }
-    if (button === 0) this._onKeyUp("MouseLeft");
-    if (button === 1) this._onKeyUp("MouseMiddle");
-    if (button === 2) this._onKeyUp("MouseRight");
+    const mag = Math.hypot(x, y);
+    if (mag < this.stickDeadzone) return import_core.Vec2.ZERO;
+    if (mag === 0) return import_core.Vec2.ZERO;
+    const adjustedMag = Math.min(
+      1,
+      (mag - this.stickDeadzone) / (1 - this.stickDeadzone)
+    );
+    return new import_core.Vec2(x / mag * adjustedMag, y / mag * adjustedMag);
   }
-  /** Store synthetic gamepad button state. */
-  fireGamepadButton(idx, pressed) {
-    this.gamepadButtons.set(idx, pressed);
+  /**
+   * Returns the deadzoned trigger value (0..1) for the given side.
+   * Reads from the active pad by default; use `{ pad: index }` for explicit
+   * per-pad reads. Falls back to synthetic state when no pad is active.
+   */
+  getTrigger(side, opts) {
+    const key = TRIGGER_AXIS_KEYS[side];
+    const padIdx = opts?.pad !== void 0 ? opts.pad : this.activePadIndex;
+    const v = padIdx !== null ? this.gamepadAxisState.get(`${padIdx}:${key}`) ?? 0 : this.syntheticAxisState.get(key) ?? 0;
+    if (v < this.triggerDeadzone) return 0;
+    return Math.min(1, (v - this.triggerDeadzone) / (1 - this.triggerDeadzone));
+  }
+  // -- Gamepad enumeration / events --
+  /**
+   * Synchronously poll `navigator.getGamepads()` for currently-connected pads.
+   * Use this rather than the cached event-driven list when you need ground
+   * truth — `gamepadconnected` doesn't fire until the user presses a button.
+   */
+  gamepads() {
+    if (typeof navigator === "undefined" || typeof navigator.getGamepads !== "function") {
+      return [];
+    }
+    const result = [];
+    for (const pad of navigator.getGamepads()) {
+      if (pad) result.push({ index: pad.index, id: pad.id });
+    }
+    return result;
+  }
+  /**
+   * Subscribe to gamepad-connected events. Replays currently-known pads
+   * synchronously so callers don't need a separate `gamepads()` call.
+   * Returns a disposer.
+   */
+  onGamepadConnected(fn) {
+    this.gamepadConnectListeners.push(fn);
+    for (const info of this.connectedPads.values()) fn(info);
+    return () => {
+      const idx = this.gamepadConnectListeners.indexOf(fn);
+      if (idx !== -1) this.gamepadConnectListeners.splice(idx, 1);
+    };
+  }
+  /** Subscribe to gamepad-disconnected events. Returns a disposer. */
+  onGamepadDisconnected(fn) {
+    this.gamepadDisconnectListeners.push(fn);
+    return () => {
+      const idx = this.gamepadDisconnectListeners.indexOf(fn);
+      if (idx !== -1) this.gamepadDisconnectListeners.splice(idx, 1);
+    };
+  }
+  // -- Active pad --
+  /**
+   * The pad whose analog input is read by default. Auto-promotes on input
+   * activity (button press or stick/trigger above deadzone) and on first
+   * connect. Returns `null` when no pad is connected.
+   */
+  getActivePad() {
+    if (this.activePadIndex === null) return null;
+    return this.connectedPads.get(this.activePadIndex) ?? null;
+  }
+  /**
+   * Manually set the active pad. Index must match a currently connected pad
+   * — pass an unknown index and the call is a no-op. Pass `null` to clear
+   * (analog reads will fall back to synthetic state if any).
+   */
+  setActivePad(index) {
+    if (index !== null && !this.connectedPads.has(index)) return;
+    this.setActivePadInternal(index);
+  }
+  /**
+   * Subscribe to active-pad changes. Replays the current active pad
+   * synchronously on subscribe so callers get the present state without a
+   * separate `getActivePad()` call. Returns a disposer.
+   */
+  onActivePadChanged(fn) {
+    this.activePadListeners.push(fn);
+    fn(this.getActivePad());
+    return () => {
+      const idx = this.activePadListeners.indexOf(fn);
+      if (idx !== -1) this.activePadListeners.splice(idx, 1);
+    };
+  }
+  setActivePadInternal(index) {
+    if (this.activePadIndex === index) return;
+    this.activePadIndex = index;
+    const info = this.getActivePad();
+    for (const fn of this.activePadListeners) fn(info);
+  }
+  // -- Gamepad runtime config --
+  /** Enable or disable real gamepad polling. Synthetic injection still works when disabled. */
+  setPollingEnabled(enabled) {
+    this.pollingEnabled = enabled;
+  }
+  /** Whether real gamepad polling is currently enabled. */
+  isPollingEnabled() {
+    return this.pollingEnabled;
+  }
+  /**
+   * Update analog deadzones at runtime. Either field may be omitted.
+   * Values are clamped to `[0, 0.999]` — capping below 1 keeps the rescaling
+   * denominator non-zero. Non-finite values are ignored.
+   */
+  setDeadzones(opts) {
+    if (opts.stick !== void 0 && Number.isFinite(opts.stick)) {
+      this.stickDeadzone = Math.max(0, Math.min(0.999, opts.stick));
+    }
+    if (opts.trigger !== void 0 && Number.isFinite(opts.trigger)) {
+      this.triggerDeadzone = Math.max(0, Math.min(0.999, opts.trigger));
+    }
+  }
+  /**
+   * Set the trigger button-edge threshold (default 0.5). Clamped to `[0, 1]`;
+   * non-finite values are ignored.
+   */
+  setTriggerThreshold(value) {
+    if (!Number.isFinite(value)) return;
+    this.triggerThreshold = Math.max(0, Math.min(1, value));
+  }
+  // -- Internal: polling and connect/disconnect plumbing --
+  /**
+   * @internal Force-release held gamepad buttons and clear real-pad analog
+   * snapshots. Used on tab-hide (where `navigator.getGamepads()` returns
+   * stale data) and on disconnect when polling is paused. Synthetic axes
+   * live in their own field, so they're untouched.
+   */
+  _releaseAllGamepadState() {
+    for (const code of [...this.lastButtonState.keys()]) {
+      this._applyKeyUp(code);
+    }
+    this.lastButtonState.clear();
+    this.gamepadAxisState.clear();
+    this.lastPadActivity.clear();
+  }
+  /** @internal Called by InputPlugin from `gamepadconnected` event or by
+   * polling when discovering a previously-unknown pad. Idempotent. */
+  _onGamepadConnected(info) {
+    if (this.connectedPads.has(info.index)) return;
+    this.connectedPads.set(info.index, info);
+    if (this.activePadIndex === null) {
+      this.setActivePadInternal(info.index);
+    }
+    for (const fn of this.gamepadConnectListeners) fn(info);
+  }
+  /** @internal Called by InputPlugin from `gamepaddisconnected` event or by
+   * polling when a pad vanishes silently. Idempotent. */
+  _onGamepadDisconnected(info) {
+    if (!this.connectedPads.has(info.index)) return;
+    this.connectedPads.delete(info.index);
+    for (const key of [...this.gamepadAxisState.keys()]) {
+      if (key.startsWith(`${info.index}:`)) this.gamepadAxisState.delete(key);
+    }
+    this.lastPadActivity.delete(info.index);
+    if (this.activePadIndex === info.index) {
+      const next = this.connectedPads.keys().next();
+      this.setActivePadInternal(next.done ? null : next.value);
+    }
+    if (this.pollingEnabled && typeof navigator !== "undefined" && typeof navigator.getGamepads === "function") {
+      this.reconcileButtonStateAcrossPads(navigator.getGamepads());
+    } else {
+      this._releaseAllGamepadState();
+    }
+    for (const fn of this.gamepadDisconnectListeners) fn(info);
+  }
+  /**
+   * @internal Poll real gamepads via `navigator.getGamepads()` and emit
+   * key-down/key-up edges for any aggregate state changes. Called by
+   * `InputPollSystem` once per frame.
+   */
+  _pollGamepads() {
+    if (typeof navigator === "undefined" || typeof navigator.getGamepads !== "function") {
+      return;
+    }
+    const pads = navigator.getGamepads();
+    const liveIndices = /* @__PURE__ */ new Set();
+    for (const pad of pads) {
+      if (!pad) continue;
+      liveIndices.add(pad.index);
+      if (!this.connectedPads.has(pad.index)) {
+        this._onGamepadConnected({ index: pad.index, id: pad.id });
+      }
+    }
+    for (const [, info] of [...this.connectedPads]) {
+      if (!liveIndices.has(info.index)) {
+        this._onGamepadDisconnected(info);
+      }
+    }
+    for (const key of [...this.gamepadAxisState.keys()]) {
+      const colon = key.indexOf(":");
+      if (colon === -1) continue;
+      const idx = Number.parseInt(key.slice(0, colon), 10);
+      if (!liveIndices.has(idx)) this.gamepadAxisState.delete(key);
+    }
+    const currentActivity = /* @__PURE__ */ new Map();
+    for (const pad of pads) {
+      if (!pad) continue;
+      const standard = pad.mapping === "standard";
+      if (standard) {
+        for (let axIdx = 0; axIdx < STANDARD_AXIS_KEYS.length; axIdx++) {
+          const axisKey = STANDARD_AXIS_KEYS[axIdx];
+          if (!axisKey) continue;
+          const raw = pad.axes[axIdx] ?? 0;
+          this.gamepadAxisState.set(
+            `${pad.index}:${axisKey}`,
+            Number.isFinite(raw) ? raw : 0
+          );
+        }
+        const lt = pad.buttons[TRIGGER_LEFT_INDEX]?.value ?? 0;
+        const rt = pad.buttons[TRIGGER_RIGHT_INDEX]?.value ?? 0;
+        this.gamepadAxisState.set(
+          `${pad.index}:leftTrigger`,
+          Number.isFinite(lt) ? lt : 0
+        );
+        this.gamepadAxisState.set(
+          `${pad.index}:rightTrigger`,
+          Number.isFinite(rt) ? rt : 0
+        );
+      }
+      currentActivity.set(pad.index, this.padHasActivity(pad));
+    }
+    const activeStillActive = this.activePadIndex !== null && (currentActivity.get(this.activePadIndex) ?? false);
+    if (!activeStillActive) {
+      for (const [padIdx, isActive] of currentActivity) {
+        const wasActive = this.lastPadActivity.get(padIdx) ?? false;
+        if (isActive && !wasActive && padIdx !== this.activePadIndex) {
+          this.setActivePadInternal(padIdx);
+          break;
+        }
+      }
+    }
+    for (const [padIdx, isActive] of currentActivity) {
+      this.lastPadActivity.set(padIdx, isActive);
+    }
+    this.reconcileButtonStateAcrossPads(pads);
+  }
+  /** Whether a pad has any input that should claim active-pad ownership. */
+  padHasActivity(pad) {
+    for (const btn of pad.buttons) {
+      if (btn?.pressed) return true;
+    }
+    if (pad.mapping === "standard") {
+      const lx = pad.axes[0] ?? 0;
+      const ly = pad.axes[1] ?? 0;
+      const rx = pad.axes[2] ?? 0;
+      const ry = pad.axes[3] ?? 0;
+      if (Math.hypot(lx, ly) > this.stickDeadzone) return true;
+      if (Math.hypot(rx, ry) > this.stickDeadzone) return true;
+      const lt = pad.buttons[TRIGGER_LEFT_INDEX]?.value ?? 0;
+      const rt = pad.buttons[TRIGGER_RIGHT_INDEX]?.value ?? 0;
+      if (lt > this.triggerDeadzone) return true;
+      if (rt > this.triggerDeadzone) return true;
+    }
+    return false;
   }
-  /** Store synthetic gamepad axis state. */
-  fireGamepadAxis(idx, value) {
-    this.gamepadAxes.set(idx, value);
+  /**
+   * Aggregate "any pad pressed" per code across the supplied pad list and
+   * emit `_applyKeyDown`/`_applyKeyUp` edges. `lastButtonState` is updated
+   * unconditionally so listen-mode interception doesn't cause held-button
+   * re-fires on subsequent frames.
+   */
+  reconcileButtonStateAcrossPads(pads) {
+    const codePressed = /* @__PURE__ */ new Map();
+    for (const pad of pads) {
+      if (!pad) continue;
+      const standard = pad.mapping === "standard";
+      const buttons = pad.buttons;
+      for (let btnIdx = 0; btnIdx < buttons.length; btnIdx++) {
+        const btn = buttons[btnIdx];
+        if (!btn) continue;
+        const standardCode = standard && btnIdx < STANDARD_BUTTON_CODES.length ? STANDARD_BUTTON_CODES[btnIdx] : void 0;
+        const code = standardCode ?? `GamepadButton${btnIdx}`;
+        const isTrigger = standard && (btnIdx === TRIGGER_LEFT_INDEX || btnIdx === TRIGGER_RIGHT_INDEX);
+        const isDown = isTrigger ? btn.value >= this.triggerThreshold : btn.pressed;
+        if (isDown) codePressed.set(code, true);
+      }
+    }
+    const allCodes = /* @__PURE__ */ new Set([
+      ...this.lastButtonState.keys(),
+      ...codePressed.keys()
+    ]);
+    for (const code of allCodes) {
+      const wasPressed = this.lastButtonState.get(code) ?? false;
+      const isPressed = codePressed.get(code) ?? false;
+      if (isPressed && !wasPressed) {
+        this._applyKeyDown(code);
+      } else if (!isPressed && wasPressed) {
+        this._applyKeyUp(code);
+      }
+      if (isPressed) {
+        this.lastButtonState.set(code, true);
+      } else {
+        this.lastButtonState.delete(code);
+      }
+    }
   }
   /** Inject a one-frame synthetic action pulse. */
   fireAction(name) {
@@ -377,58 +1046,268 @@ var InputManager = class {
     }
     this.syntheticPressedActions.add(name);
     this.syntheticActionStarts.set(name, this.elapsedMs);
+    this.notifyActionListeners(this.actionListeners, name);
   }
   /** Release all synthetic and physical input state. */
   clearAll() {
     for (const code of [...this.pressedKeys]) {
-      this._onKeyUp(code);
+      this._applyKeyUp(code);
     }
     this.justPressedKeys.clear();
     this.justReleasedKeys.clear();
     this.holdStart.clear();
     this.syntheticPressedActions.clear();
     this.syntheticActionStarts.clear();
-    this.pressedMouseButtons.clear();
-    this.pointerDownState = false;
-    this.gamepadButtons.clear();
-    this.gamepadAxes.clear();
+    this.pointers.clear();
+    this.primaryPointerId = null;
+    this.mouseButtonAggregate.clear();
+    this.consumedPointers.clear();
+    this.consumedWheelThisFrame = false;
+    this.inputQueue.length = 0;
+    this.lastButtonState.clear();
+    this.gamepadAxisState.clear();
+    this.syntheticAxisState.clear();
+    this.lastPadActivity.clear();
   }
-  /** Release any pressed pointer buttons without touching keyboard state. */
+  /**
+   * Drop all tracked pointers and release the aggregate `MouseLeft/Middle/Right`
+   * codes without touching keyboard or gamepad state. Useful for window-blur
+   * / page-hide handling.
+   */
   clearPointerButtons() {
-    for (const button of [...this.pressedMouseButtons]) {
-      if (button === 0) this._onKeyUp("MouseLeft");
-      if (button === 1) this._onKeyUp("MouseMiddle");
-      if (button === 2) this._onKeyUp("MouseRight");
+    for (const button of [...this.mouseButtonAggregate]) {
+      const code = MOUSE_BUTTON_CODES[button];
+      if (code) this._applyKeyUp(code);
     }
-    this.pressedMouseButtons.clear();
-    this.pointerDownState = false;
+    this.mouseButtonAggregate.clear();
+    this.pointers.clear();
+    this.primaryPointerId = null;
+    this.consumedPointers.clear();
+    this.inputQueue = this.inputQueue.filter(
+      (e) => e.kind !== "pointerDown" && e.kind !== "pointerUp" && e.kind !== "pointerCancel"
+    );
   }
   /** Snapshot of current held input state for inspector tooling. */
   snapshotState() {
     const cmp = /* @__PURE__ */ __name((a, b) => a < b ? -1 : a > b ? 1 : 0, "cmp");
     const keys = [...this.pressedKeys].sort(cmp);
+    const nonGamepadKeys = keys.filter((k) => !k.startsWith("Gamepad"));
+    const gamepadButtons = keys.filter((k) => k.startsWith("Gamepad"));
     const actions = this.getActionNames().filter((action) => this.isPressed(action)).sort(cmp);
-    const buttons = [...this.pressedMouseButtons].sort((a, b) => a - b);
-    const pressedButtons = [...this.gamepadButtons.entries()].filter(([, pressed]) => pressed).map(([idx]) => idx).sort((a, b) => a - b);
-    const axes = [...this.gamepadAxes.entries()].filter(([, value]) => value !== 0).sort(([a], [b]) => a - b).map(([index, value]) => ({ index, value }));
+    const aggregateButtons = [...this.mouseButtonAggregate].sort((a, b) => a - b);
+    const pointers = [...this.pointers.values()].sort((a, b) => a.id - b.id).map((p) => ({
+      id: p.id,
+      x: p.screenPos.x,
+      y: p.screenPos.y,
+      type: p.type,
+      isPrimary: p.isPrimary,
+      buttons: [...p.buttons].sort((a, b) => a - b),
+      down: p.isDown
+    }));
+    const primary = this.getPrimaryPointer();
+    const realAxes = [...this.gamepadAxisState.entries()].filter(([, value]) => Math.abs(value) > 1e-3).map(([key, value]) => ({ key, value }));
+    const syntheticAxes = [...this.syntheticAxisState.entries()].filter(([, value]) => Math.abs(value) > 1e-3).map(([key, value]) => ({ key: `synthetic:${key}`, value }));
+    const axes = [...realAxes, ...syntheticAxes].sort((a, b) => cmp(a.key, b.key));
     return {
-      keys,
+      keys: nonGamepadKeys,
       actions,
       mouse: {
-        x: this.pointerScreenPos.x,
-        y: this.pointerScreenPos.y,
-        buttons,
-        down: this.pointerDownState
+        x: primary?.screenPos.x ?? 0,
+        y: primary?.screenPos.y ?? 0,
+        buttons: aggregateButtons,
+        down: this.mouseButtonAggregate.size > 0
       },
+      pointers,
       gamepad: {
-        buttons: pressedButtons,
+        buttons: gamepadButtons,
         axes
       }
     };
   }
-  // -- Internal methods (called by InputPlugin / Systems) --
+  // -- Internal: DOM-handler enqueue path --
+  /**
+   * @internal Stash the renderer adapter so the drain step can call its
+   * optional `hitTestUI(x, y)` for the auto-consume fallback. Called by
+   * `InputPlugin.install`.
+   */
+  _setRenderer(renderer) {
+    this.renderer = renderer;
+  }
   /** @internal */
-  _onKeyDown(code) {
+  _enqueueKeyDown(code) {
+    this.inputQueue.push({ kind: "keyDown", code });
+  }
+  /** @internal */
+  _enqueueKeyUp(code) {
+    this.inputQueue.push({ kind: "keyUp", code });
+  }
+  /**
+   * @internal Sync portion: upsert the pointer entry (existence, screenPos,
+   * type, isPrimary, primaryPointerId) and notify pointerMoveListeners so
+   * pointer-tracking UIs see live cursor positions. Move events do not carry
+   * action-map edges, so they are not queued.
+   */
+  _enqueuePointerMove(info) {
+    const pointer = this.upsertPointer(info);
+    pointer.screenPos = new import_core.Vec2(info.screenX, info.screenY);
+    this.notifyPointerListeners(this.pointerMoveListeners, pointer);
+  }
+  /**
+   * @internal Sync portion: upsert pointer (existence, screenPos, type,
+   * isPrimary, primaryPointerId) and notify pointerDownListeners. Button
+   * mutation, action-map edges, and mouse-aggregate emit are deferred to the
+   * next drain at `Phase.EarlyUpdate` so {@link consumePointer} (or the
+   * renderer's UI hit-test) can suppress them, AND so a same-frame
+   * down+up that arrives before drain still produces the correct
+   * `MouseLeft` press/release edges (recomputing aggregate from live state
+   * after sync mutation would silently drop the transient transition).
+   *
+   * Listeners therefore observe `pointer.buttons` BEFORE this event's edge is
+   * applied. That's a documented tradeoff: the canonical event-button info
+   * is in the `FederatedPointerEvent` / `PointerEvent` the user's Pixi
+   * handler already receives, so the lossy `info.buttons` view rarely
+   * matters in practice.
+   */
+  _enqueuePointerDown(info) {
+    const pointer = this.upsertPointer(info);
+    pointer.screenPos = new import_core.Vec2(info.screenX, info.screenY);
+    this.notifyPointerListeners(this.pointerDownListeners, pointer);
+    this.inputQueue.push({ kind: "pointerDown", info });
+  }
+  /** @internal */
+  _enqueuePointerUp(info) {
+    const pointer = this.upsertPointer(info);
+    pointer.screenPos = new import_core.Vec2(info.screenX, info.screenY);
+    this.notifyPointerListeners(this.pointerUpListeners, pointer);
+    this.inputQueue.push({ kind: "pointerUp", info });
+  }
+  /** @internal */
+  _enqueuePointerCancel(id) {
+    const pointer = this.pointers.get(id);
+    if (pointer) {
+      this.notifyPointerListeners(this.pointerUpListeners, pointer);
+    }
+    this.inputQueue.push({ kind: "pointerCancel", id });
+  }
+  /** @internal */
+  _enqueueWheel(dx, dy) {
+    for (const fn of [...this.wheelListeners]) fn(dx, dy);
+    this.inputQueue.push({ kind: "wheel", dx, dy });
+  }
+  /**
+   * @internal Drain queued DOM events at `Phase.EarlyUpdate`. Each event
+   * applies its deferred state (button mutations, action-map edges,
+   * mouse-aggregate transitions). Consumed pointers are excluded from the
+   * mouse aggregate so UI-claimed presses do not propagate to gameplay
+   * actions. The renderer's optional `hitTestUI(x, y)` auto-claims a pointer
+   * whose `pointerdown` lands on a UI-marked container.
+   */
+  _drainInputQueue() {
+    if (this.inputQueue.length === 0) return;
+    const queue = this.inputQueue;
+    this.inputQueue = [];
+    for (const event of queue) {
+      switch (event.kind) {
+        case "keyDown":
+          this._applyKeyDown(event.code);
+          break;
+        case "keyUp":
+          this._applyKeyUp(event.code);
+          break;
+        case "pointerDown":
+          this.drainPointerDown(event.info);
+          break;
+        case "pointerUp":
+          this.drainPointerUp(event.info);
+          break;
+        case "pointerCancel":
+          this.drainPointerCancel(event.id);
+          break;
+        case "wheel":
+          this.applyWheelEdges(event.dx, event.dy);
+          break;
+      }
+    }
+  }
+  drainPointerDown(info) {
+    if (!this.consumedPointers.has(info.id) && this.renderer?.hitTestUI?.(info.screenX, info.screenY)) {
+      this.consumedPointers.add(info.id);
+    }
+    const pointer = this.pointers.get(info.id);
+    if (!pointer) return;
+    if (info.button >= 0 && info.button <= 2) {
+      pointer.buttons.add(info.button);
+      pointer.isDown = true;
+      this.recomputeMouseAggregate(info.button);
+    } else {
+      pointer.isDown = pointer.buttons.size > 0;
+    }
+  }
+  drainPointerUp(info) {
+    const pointer = this.pointers.get(info.id);
+    if (!pointer) return;
+    if (info.button >= 0 && info.button <= 2) {
+      pointer.buttons.delete(info.button);
+      this.recomputeMouseAggregate(info.button);
+    }
+    pointer.isDown = pointer.buttons.size > 0;
+    if (!pointer.isDown) {
+      this.consumedPointers.delete(info.id);
+      if (pointer.type !== "mouse") {
+        this.removePointer(pointer.id);
+      }
+    }
+  }
+  drainPointerCancel(id) {
+    const pointer = this.pointers.get(id);
+    if (!pointer) return;
+    const heldButtons = [...pointer.buttons];
+    pointer.buttons.clear();
+    pointer.isDown = false;
+    for (const button of heldButtons) {
+      this.recomputeMouseAggregate(button);
+    }
+    this.consumedPointers.delete(id);
+    if (pointer.type !== "mouse") {
+      this.removePointer(id);
+    }
+  }
+  applyWheelEdges(dx, dy) {
+    if (this.consumedWheelThisFrame) return;
+    if (Math.abs(dy) > 1e-3) {
+      const code = dy < 0 ? "WheelUp" : "WheelDown";
+      this.fireOneFrameEdge(code);
+    }
+    if (Math.abs(dx) > 1e-3) {
+      const code = dx < 0 ? "WheelLeft" : "WheelRight";
+      this.fireOneFrameEdge(code);
+    }
+  }
+  /**
+   * Add a code to `justPressedKeys` without entering `pressedKeys`. Used for
+   * discrete edges (wheel ticks) that are never "held". Listeners and
+   * `listenForNextKey` still fire as usual.
+   */
+  fireOneFrameEdge(code) {
+    if (this.listenResolve) {
+      const resolve = this.listenResolve;
+      this.listenResolve = null;
+      resolve(code);
+      return;
+    }
+    this.justPressedKeys.add(code);
+    this.notifyKeyListeners(this.keyDownListeners, this.keyDownListenersAny, code);
+    for (const action of this.actionsForCode(code)) {
+      this.notifyActionListeners(this.actionListeners, action);
+    }
+  }
+  // -- Internal: synthetic / sync apply path --
+  /**
+   * @internal Synthetic key-down. DOM-originated events must use
+   * {@link _enqueueKeyDown} so `consumePointer` and the UI hit-test fallback
+   * have a chance to run before action edges fire.
+   */
+  _applyKeyDown(code) {
     if (this.listenResolve) {
       const resolve = this.listenResolve;
       this.listenResolve = null;
@@ -439,27 +1318,190 @@ var InputManager = class {
       this.pressedKeys.add(code);
       this.justPressedKeys.add(code);
       this.holdStart.set(code, this.elapsedMs);
+      this.notifyKeyListeners(this.keyDownListeners, this.keyDownListenersAny, code);
+      for (const action of this.actionsForCode(code)) {
+        this.notifyActionListeners(this.actionListeners, action);
+      }
     }
   }
-  /** @internal */
-  _onKeyUp(code) {
+  /**
+   * @internal Synthetic key-up. DOM-originated events must use
+   * {@link _enqueueKeyUp}.
+   */
+  _applyKeyUp(code) {
     if (this.pressedKeys.has(code)) {
       this.pressedKeys.delete(code);
       this.justReleasedKeys.add(code);
       this.holdStart.delete(code);
+      this.notifyKeyListeners(this.keyUpListeners, this.keyUpListenersAny, code);
+      for (const action of this.actionsForCode(code)) {
+        this.notifyActionListeners(this.actionReleasedListeners, action);
+      }
     }
   }
-  /** @internal */
-  _onPointerMove(screenX, screenY) {
-    this.pointerScreenPos = new import_core.Vec2(screenX, screenY);
+  /**
+   * @internal Synthetic pointer move. DOM-originated events must use
+   * {@link _enqueuePointerMove}.
+   */
+  _applyPointerMove(info) {
+    const pointer = this.upsertPointer(info);
+    pointer.screenPos = new import_core.Vec2(info.screenX, info.screenY);
+    this.notifyPointerListeners(this.pointerMoveListeners, pointer);
   }
-  /** @internal */
-  _onPointerDown() {
-    this.pointerDownState = true;
+  /**
+   * @internal Synthetic pointer down. DOM-originated events must use
+   * {@link _enqueuePointerDown}. This applies all state (button mutation,
+   * mouse-aggregate emit, listener notify) synchronously.
+   */
+  _applyPointerDown(info) {
+    const pointer = this.upsertPointer(info);
+    pointer.screenPos = new import_core.Vec2(info.screenX, info.screenY);
+    if (info.button >= 0 && info.button <= 2) {
+      pointer.buttons.add(info.button);
+      pointer.isDown = true;
+      this.recomputeMouseAggregate(info.button);
+    } else {
+      pointer.isDown = pointer.buttons.size > 0;
+    }
+    this.notifyPointerListeners(this.pointerDownListeners, pointer);
   }
-  /** @internal */
-  _onPointerUp() {
-    this.pointerDownState = false;
+  /**
+   * @internal Synthetic pointer up. DOM-originated events must use
+   * {@link _enqueuePointerUp}.
+   */
+  _applyPointerUp(info) {
+    const pointer = this.upsertPointer(info);
+    pointer.screenPos = new import_core.Vec2(info.screenX, info.screenY);
+    if (info.button >= 0 && info.button <= 2) {
+      pointer.buttons.delete(info.button);
+      this.recomputeMouseAggregate(info.button);
+    }
+    pointer.isDown = pointer.buttons.size > 0;
+    this.notifyPointerListeners(this.pointerUpListeners, pointer);
+    if (!pointer.isDown) {
+      this.consumedPointers.delete(info.id);
+      if (pointer.type !== "mouse") {
+        this.removePointer(pointer.id);
+      }
+    }
+  }
+  /**
+   * @internal Synthetic pointer cancel. Clears all buttons on the pointer,
+   * fires up-listeners, and drops the entry (unless it's a mouse). Mirrors
+   * the drain-time {@link drainPointerCancel} logic.
+   */
+  _applyPointerCancel(id) {
+    const pointer = this.pointers.get(id);
+    if (!pointer) return;
+    const heldButtons = [...pointer.buttons];
+    pointer.buttons.clear();
+    pointer.isDown = false;
+    for (const button of heldButtons) {
+      this.recomputeMouseAggregate(button);
+    }
+    this.notifyPointerListeners(this.pointerUpListeners, pointer);
+    this.consumedPointers.delete(id);
+    if (pointer.type !== "mouse") {
+      this.removePointer(id);
+    }
+  }
+  upsertPointer(info) {
+    let pointer = this.pointers.get(info.id);
+    if (!pointer) {
+      pointer = {
+        id: info.id,
+        screenPos: new import_core.Vec2(info.screenX, info.screenY),
+        type: info.type,
+        isPrimary: info.isPrimary,
+        buttons: /* @__PURE__ */ new Set(),
+        isDown: false
+      };
+      this.pointers.set(info.id, pointer);
+    } else {
+      pointer.type = info.type;
+      pointer.isPrimary = info.isPrimary;
+    }
+    if (info.isPrimary) {
+      this.primaryPointerId = info.id;
+    } else if (this.primaryPointerId === null) {
+      this.primaryPointerId = info.id;
+    }
+    return pointer;
+  }
+  removePointer(id) {
+    this.pointers.delete(id);
+    if (this.primaryPointerId === id) {
+      let next = null;
+      for (const p of this.pointers.values()) {
+        if (p.isPrimary) {
+          next = p.id;
+          break;
+        }
+        if (next === null) next = p.id;
+      }
+      this.primaryPointerId = next;
+    }
+  }
+  /**
+   * Recompute the `MouseLeft/Middle/Right` aggregate edge for `button`.
+   * Consumed pointers are excluded so a UI-claimed press never propagates to
+   * gameplay actions, even if a second non-UI pointer simultaneously holds
+   * the same button.
+   */
+  recomputeMouseAggregate(button) {
+    const code = MOUSE_BUTTON_CODES[button];
+    if (!code) return;
+    let nowAny = false;
+    for (const p of this.pointers.values()) {
+      if (this.consumedPointers.has(p.id)) continue;
+      if (p.buttons.has(button)) {
+        nowAny = true;
+        break;
+      }
+    }
+    const wasAny = this.mouseButtonAggregate.has(button);
+    if (nowAny && !wasAny) {
+      this.mouseButtonAggregate.add(button);
+      this._applyKeyDown(code);
+    } else if (!nowAny && wasAny) {
+      this.mouseButtonAggregate.delete(button);
+      this._applyKeyUp(code);
+    }
+  }
+  notifyPointerListeners(listeners, pointer) {
+    if (listeners.length === 0) return;
+    const info = this.toPointerInfo(pointer);
+    for (const fn of [...listeners]) {
+      fn(info);
+    }
+  }
+  notifyKeyListeners(perCode, anyList, code) {
+    const list = perCode.get(code);
+    if (list) {
+      for (const fn of [...list]) fn(code);
+    }
+    if (anyList.length > 0) {
+      for (const fn of [...anyList]) fn(code);
+    }
+  }
+  notifyActionListeners(perAction, name) {
+    const list = perAction.get(name);
+    if (!list) return;
+    for (const fn of [...list]) fn(name);
+  }
+  /**
+   * Action names that include `code` in their bindings AND whose group is
+   * currently enabled. Used for `onAction` / `onActionReleased` listener
+   * fan-out so disabled-group suppression matches `isPressed` behavior.
+   */
+  actionsForCode(code) {
+    const result = [];
+    for (const [action, keys] of this.actionMap) {
+      if (keys.includes(code) && this.isActionEnabled(action)) {
+        result.push(action);
+      }
+    }
+    return result;
   }
   /** @internal Clear per-frame justPressed/justReleased flags. */
   _clearFrameState() {
@@ -467,6 +1509,7 @@ var InputManager = class {
     this.justReleasedKeys.clear();
     this.syntheticPressedActions.clear();
     this.syntheticActionStarts.clear();
+    this.consumedWheelThisFrame = false;
   }
   /** Set camera for pointer world-coord conversion. */
   setCamera(camera) {
@@ -484,6 +1527,31 @@ var InputManager = class {
   _advanceTime(dtMs) {
     this.elapsedMs += dtMs;
   }
+  // -- Internal: sync-path aliases (back-compat with pre-0.5.x test callers) --
+  /** @internal Sync alias — see {@link _applyKeyDown}. */
+  _onKeyDown(code) {
+    this._applyKeyDown(code);
+  }
+  /** @internal Sync alias — see {@link _applyKeyUp}. */
+  _onKeyUp(code) {
+    this._applyKeyUp(code);
+  }
+  /** @internal Sync alias — see {@link _applyPointerMove}. */
+  _onPointerMove(info) {
+    this._applyPointerMove(info);
+  }
+  /** @internal Sync alias — see {@link _applyPointerDown}. */
+  _onPointerDown(info) {
+    this._applyPointerDown(info);
+  }
+  /** @internal Sync alias — see {@link _applyPointerUp}. */
+  _onPointerUp(info) {
+    this._applyPointerUp(info);
+  }
+  /** @internal Sync alias — see {@link _applyPointerCancel}. */
+  _onPointerCancel(id) {
+    this._applyPointerCancel(id);
+  }
 };
 
 // src/types.ts
@@ -499,7 +1567,12 @@ var InputPollSystem = class extends import_core3.System {
   phase = import_core3.Phase.EarlyUpdate;
   priority = -100;
   update(dt) {
-    this.use(InputManagerKey)._advanceTime(dt);
+    const manager = this.use(InputManagerKey);
+    manager._drainInputQueue();
+    manager._advanceTime(dt);
+    if (manager.isPollingEnabled()) {
+      manager._pollGamepads();
+    }
   }
 };
 
@@ -554,11 +1627,6 @@ var InputDebugContributor = class {
 };
 
 // src/InputPlugin.ts
-var MOUSE_BUTTON_MAP = {
-  0: "MouseLeft",
-  1: "MouseMiddle",
-  2: "MouseRight"
-};
 var InputPlugin = class {
   static {
     __name(this, "InputPlugin");
@@ -581,9 +1649,19 @@ var InputPlugin = class {
     if (this.config.groups) {
       this.manager.setGroups(this.config.groups);
     }
+    if (this.config.deadzones) {
+      this.manager.setDeadzones(this.config.deadzones);
+    }
+    if (this.config.triggerThreshold !== void 0) {
+      this.manager.setTriggerThreshold(this.config.triggerThreshold);
+    }
+    if (this.config.pollGamepads === false) {
+      this.manager.setPollingEnabled(false);
+    }
     const rendererKey = this.config.rendererKey ?? import_core5.RendererAdapterKey;
     const renderer = context.tryResolve(rendererKey);
     const pointerTarget = this.config.target ?? renderer?.canvas ?? document;
+    this.manager._setRenderer(renderer ?? null);
     const coordinateElement = renderer?.canvas ?? this.config.target ?? null;
     const mapPointer = /* @__PURE__ */ __name((cssX, cssY) => renderer?.canvasToVirtual?.(cssX, cssY) ?? { x: cssX, y: cssY }, "mapPointer");
     const preventSet = new Set(this.config.preventDefaultKeys ?? []);
@@ -591,12 +1669,12 @@ var InputPlugin = class {
       const ke = e;
       if (ke.repeat) return;
       if (preventSet.has(ke.code)) ke.preventDefault();
-      this.manager._onKeyDown(ke.code);
+      this.manager._enqueueKeyDown(ke.code);
     }, "onKeyDown");
     const onKeyUp = /* @__PURE__ */ __name((e) => {
       const ke = e;
       if (preventSet.has(ke.code)) ke.preventDefault();
-      this.manager._onKeyUp(ke.code);
+      this.manager._enqueueKeyUp(ke.code);
     }, "onKeyUp");
     window.addEventListener("keydown", onKeyDown);
     window.addEventListener("keyup", onKeyUp);
@@ -604,8 +1682,7 @@ var InputPlugin = class {
       () => window.removeEventListener("keydown", onKeyDown),
       () => window.removeEventListener("keyup", onKeyUp)
     );
-    const onPointerMove = /* @__PURE__ */ __name((e) => {
-      const pe = e;
+    const buildInfo = /* @__PURE__ */ __name((pe) => {
       let cssX;
       let cssY;
       if (coordinateElement) {
@@ -617,39 +1694,96 @@ var InputPlugin = class {
         cssY = pe.clientY;
       }
       const mapped = mapPointer(cssX, cssY);
-      this.manager._onPointerMove(mapped.x, mapped.y);
+      const rawType = pe.pointerType;
+      const type = rawType === "touch" || rawType === "pen" ? rawType : "mouse";
+      return {
+        id: pe.pointerId,
+        screenX: mapped.x,
+        screenY: mapped.y,
+        type,
+        isPrimary: pe.isPrimary,
+        button: pe.button
+      };
+    }, "buildInfo");
+    const onPointerMove = /* @__PURE__ */ __name((e) => {
+      this.manager._enqueuePointerMove(buildInfo(e));
     }, "onPointerMove");
     const onPointerDown = /* @__PURE__ */ __name((e) => {
-      const pe = e;
-      const button = pe.button;
-      if (button in MOUSE_BUTTON_MAP) {
-        this.manager.firePointerDown(button);
-      } else {
-        this.manager._onPointerDown();
-      }
+      this.manager._enqueuePointerDown(buildInfo(e));
     }, "onPointerDown");
     const onPointerUp = /* @__PURE__ */ __name((e) => {
-      const pe = e;
-      const button = pe.button;
-      if (button in MOUSE_BUTTON_MAP) {
-        this.manager.firePointerUp(button);
-      } else {
-        this.manager._onPointerUp();
-      }
+      this.manager._enqueuePointerUp(buildInfo(e));
     }, "onPointerUp");
-    const onPointerCancel = /* @__PURE__ */ __name(() => {
-      this.manager.clearPointerButtons();
+    const onPointerCancel = /* @__PURE__ */ __name((e) => {
+      const pe = e;
+      this.manager._enqueuePointerCancel(pe.pointerId);
     }, "onPointerCancel");
+    const onPointerLeave = /* @__PURE__ */ __name((e) => {
+      const pe = e;
+      this.manager._enqueuePointerCancel(pe.pointerId);
+    }, "onPointerLeave");
     pointerTarget.addEventListener("pointerdown", onPointerDown);
     window.addEventListener("pointermove", onPointerMove);
     window.addEventListener("pointerup", onPointerUp);
     window.addEventListener("pointercancel", onPointerCancel);
+    pointerTarget.addEventListener("pointerleave", onPointerLeave);
     this.cleanupFns.push(
       () => pointerTarget.removeEventListener("pointerdown", onPointerDown),
       () => window.removeEventListener("pointermove", onPointerMove),
       () => window.removeEventListener("pointerup", onPointerUp),
-      () => window.removeEventListener("pointercancel", onPointerCancel)
+      () => window.removeEventListener("pointercancel", onPointerCancel),
+      () => pointerTarget.removeEventListener("pointerleave", onPointerLeave)
+    );
+    const wheelInvertY = this.config.wheelInvertY === true;
+    const preventDefaultWheel = this.config.preventDefaultWheel === true;
+    const onWheel = /* @__PURE__ */ __name((e) => {
+      const we = e;
+      if (preventDefaultWheel) we.preventDefault();
+      const dy = wheelInvertY ? -we.deltaY : we.deltaY;
+      this.manager._enqueueWheel(we.deltaX, dy);
+    }, "onWheel");
+    pointerTarget.addEventListener(
+      "wheel",
+      onWheel,
+      preventDefaultWheel ? { passive: false } : void 0
     );
+    this.cleanupFns.push(
+      () => pointerTarget.removeEventListener("wheel", onWheel)
+    );
+    const onGamepadConnected = /* @__PURE__ */ __name((e) => {
+      const ge = e;
+      if (!ge.gamepad) return;
+      this.manager._onGamepadConnected({
+        index: ge.gamepad.index,
+        id: ge.gamepad.id
+      });
+    }, "onGamepadConnected");
+    const onGamepadDisconnected = /* @__PURE__ */ __name((e) => {
+      const ge = e;
+      if (!ge.gamepad) return;
+      this.manager._onGamepadDisconnected({
+        index: ge.gamepad.index,
+        id: ge.gamepad.id
+      });
+    }, "onGamepadDisconnected");
+    window.addEventListener("gamepadconnected", onGamepadConnected);
+    window.addEventListener("gamepaddisconnected", onGamepadDisconnected);
+    this.cleanupFns.push(
+      () => window.removeEventListener("gamepadconnected", onGamepadConnected),
+      () => window.removeEventListener("gamepaddisconnected", onGamepadDisconnected)
+    );
+    if (typeof document !== "undefined") {
+      const onVisibilityChange = /* @__PURE__ */ __name(() => {
+        if (document.visibilityState === "hidden") {
+          this.manager._releaseAllGamepadState();
+          this.manager.clearPointerButtons();
+        }
+      }, "onVisibilityChange");
+      document.addEventListener("visibilitychange", onVisibilityChange);
+      this.cleanupFns.push(
+        () => document.removeEventListener("visibilitychange", onVisibilityChange)
+      );
+    }
     context.register(InputManagerKey, this.manager);
   }
   registerSystems(scheduler) {
@@ -785,10 +1919,33 @@ var KEY_DISPLAY_NAMES = {
   // Mouse buttons (synthetic codes from InputPlugin)
   MouseLeft: "Left Click",
   MouseMiddle: "Middle Click",
-  MouseRight: "Right Click"
+  MouseRight: "Right Click",
+  // Gamepad buttons (synthetic codes from InputPollSystem; standard mapping)
+  GamepadA: "A",
+  GamepadB: "B",
+  GamepadX: "X",
+  GamepadY: "Y",
+  GamepadLB: "LB",
+  GamepadRB: "RB",
+  GamepadLT: "LT",
+  GamepadRT: "RT",
+  GamepadSelect: "Select",
+  GamepadStart: "Start",
+  GamepadLeftStick: "Left Stick",
+  GamepadRightStick: "Right Stick",
+  GamepadDPadUp: "D-Pad Up",
+  GamepadDPadDown: "D-Pad Down",
+  GamepadDPadLeft: "D-Pad Left",
+  GamepadDPadRight: "D-Pad Right",
+  GamepadHome: "Home"
 };
+var GAMEPAD_BUTTON_FALLBACK = /^GamepadButton(\d+)$/;
 function getKeyDisplayName(code) {
-  return KEY_DISPLAY_NAMES[code] ?? code;
+  const direct = KEY_DISPLAY_NAMES[code];
+  if (direct !== void 0) return direct;
+  const fallback = GAMEPAD_BUTTON_FALLBACK.exec(code);
+  if (fallback) return `Gamepad Button ${fallback[1]}`;
+  return code;
 }
 __name(getKeyDisplayName, "getKeyDisplayName");
 // Annotate the CommonJS export names for ESM import in node: