@gjsify/gamepad 0.1.9

package/lib/esm/axis-mapping.js

@@ -0,0 +1,35 @@
+const ManetteAxis = {
+  LEFT_X: 0,
+  // SDL leftx
+  LEFT_Y: 1,
+  // SDL lefty
+  RIGHT_X: 2,
+  // SDL rightx
+  RIGHT_Y: 3,
+  // SDL righty
+  LEFT_TRIGGER: 4,
+  // SDL lefttrigger
+  RIGHT_TRIGGER: 5
+  // SDL righttrigger
+};
+const W3CAxis = {
+  LEFT_STICK_X: 0,
+  LEFT_STICK_Y: 1,
+  RIGHT_STICK_X: 2,
+  RIGHT_STICK_Y: 3
+};
+const W3C_AXIS_COUNT = 4;
+const MANETTE_TO_W3C_AXIS = /* @__PURE__ */ new Map([
+  [ManetteAxis.LEFT_X, W3CAxis.LEFT_STICK_X],
+  [ManetteAxis.LEFT_Y, W3CAxis.LEFT_STICK_Y],
+  [ManetteAxis.RIGHT_X, W3CAxis.RIGHT_STICK_X],
+  [ManetteAxis.RIGHT_Y, W3CAxis.RIGHT_STICK_Y]
+]);
+const TRIGGER_PRESS_THRESHOLD = 0.5;
+export {
+  MANETTE_TO_W3C_AXIS,
+  ManetteAxis,
+  TRIGGER_PRESS_THRESHOLD,
+  W3CAxis,
+  W3C_AXIS_COUNT
+};

package/lib/esm/button-mapping.js

@@ -0,0 +1,92 @@
+const LinuxButton = {
+  BTN_SOUTH: 304,
+  // 0x130 — A (Xbox), B (Nintendo), Cross (PlayStation)
+  BTN_EAST: 305,
+  // 0x131 — B (Xbox), A (Nintendo), Circle (PlayStation)
+  BTN_C: 306,
+  // 0x132
+  BTN_NORTH: 307,
+  // 0x133 — Y (Xbox), X (Nintendo), Triangle (PlayStation)
+  BTN_WEST: 308,
+  // 0x134 — X (Xbox), Y (Nintendo), Square (PlayStation)
+  BTN_Z: 309,
+  // 0x135
+  BTN_TL: 310,
+  // 0x136 — Left shoulder (L, LB)
+  BTN_TR: 311,
+  // 0x137 — Right shoulder (R, RB)
+  BTN_TL2: 312,
+  // 0x138 — Left trigger (LT, L2)
+  BTN_TR2: 313,
+  // 0x139 — Right trigger (RT, R2)
+  BTN_SELECT: 314,
+  // 0x13a — Select / Back / Share
+  BTN_START: 315,
+  // 0x13b — Start / Menu / Options
+  BTN_MODE: 316,
+  // 0x13c — Home / Guide / PS
+  BTN_THUMBL: 317,
+  // 0x13d — Left stick click (L3)
+  BTN_THUMBR: 318,
+  // 0x13e — Right stick click (R3)
+  BTN_DPAD_UP: 544,
+  // 0x220
+  BTN_DPAD_DOWN: 545,
+  // 0x221
+  BTN_DPAD_LEFT: 546,
+  // 0x222
+  BTN_DPAD_RIGHT: 547
+  // 0x223
+};
+const W3CButton = {
+  FACE_1: 0,
+  // A (Xbox), B (Nintendo), Cross (PlayStation)
+  FACE_2: 1,
+  // B (Xbox), A (Nintendo), Circle (PlayStation)
+  FACE_3: 2,
+  // X (Xbox), Y (Nintendo), Square (PlayStation)
+  FACE_4: 3,
+  // Y (Xbox), X (Nintendo), Triangle (PlayStation)
+  LEFT_BUMPER: 4,
+  RIGHT_BUMPER: 5,
+  LEFT_TRIGGER: 6,
+  // Analog trigger — also populated from axis events
+  RIGHT_TRIGGER: 7,
+  // Analog trigger — also populated from axis events
+  SELECT: 8,
+  START: 9,
+  LEFT_STICK: 10,
+  RIGHT_STICK: 11,
+  DPAD_UP: 12,
+  DPAD_DOWN: 13,
+  DPAD_LEFT: 14,
+  DPAD_RIGHT: 15,
+  HOME: 16
+};
+const W3C_BUTTON_COUNT = 17;
+const MANETTE_TO_W3C_BUTTON = /* @__PURE__ */ new Map([
+  [LinuxButton.BTN_SOUTH, W3CButton.FACE_1],
+  [LinuxButton.BTN_EAST, W3CButton.FACE_2],
+  [LinuxButton.BTN_WEST, W3CButton.FACE_3],
+  [LinuxButton.BTN_NORTH, W3CButton.FACE_4],
+  [LinuxButton.BTN_TL, W3CButton.LEFT_BUMPER],
+  [LinuxButton.BTN_TR, W3CButton.RIGHT_BUMPER],
+  [LinuxButton.BTN_TL2, W3CButton.LEFT_TRIGGER],
+  [LinuxButton.BTN_TR2, W3CButton.RIGHT_TRIGGER],
+  [LinuxButton.BTN_SELECT, W3CButton.SELECT],
+  [LinuxButton.BTN_START, W3CButton.START],
+  [LinuxButton.BTN_THUMBL, W3CButton.LEFT_STICK],
+  [LinuxButton.BTN_THUMBR, W3CButton.RIGHT_STICK],
+  [LinuxButton.BTN_DPAD_UP, W3CButton.DPAD_UP],
+  [LinuxButton.BTN_DPAD_DOWN, W3CButton.DPAD_DOWN],
+  [LinuxButton.BTN_DPAD_LEFT, W3CButton.DPAD_LEFT],
+  [LinuxButton.BTN_DPAD_RIGHT, W3CButton.DPAD_RIGHT],
+  [LinuxButton.BTN_MODE, W3CButton.HOME]
+]);
+export {
+  LinuxButton,
+  MANETTE_TO_W3C_BUTTON,
+  LinuxButton as ManetteButton,
+  W3CButton,
+  W3C_BUTTON_COUNT
+};

package/lib/esm/gamepad-button.js

@@ -0,0 +1,16 @@
+class GamepadButton {
+  pressed;
+  touched;
+  value;
+  constructor(pressed = false, touched = false, value = 0) {
+    this.pressed = pressed;
+    this.touched = touched;
+    this.value = value;
+  }
+  get [Symbol.toStringTag]() {
+    return "GamepadButton";
+  }
+}
+export {
+  GamepadButton
+};

package/lib/esm/gamepad-event.js

@@ -0,0 +1,14 @@
+import { Event } from "@gjsify/dom-events";
+class GamepadEvent extends Event {
+  gamepad;
+  constructor(type, eventInitDict) {
+    super(type, eventInitDict);
+    this.gamepad = eventInitDict.gamepad;
+  }
+  get [Symbol.toStringTag]() {
+    return "GamepadEvent";
+  }
+}
+export {
+  GamepadEvent
+};

package/lib/esm/gamepad-manager.js

@@ -0,0 +1,223 @@
+import { GamepadButton } from "./gamepad-button.js";
+import { Gamepad } from "./gamepad.js";
+import { GamepadEvent } from "./gamepad-event.js";
+import { ManetteHapticActuator } from "./haptic-actuator.js";
+import { MANETTE_TO_W3C_BUTTON, W3C_BUTTON_COUNT } from "./button-mapping.js";
+import { MANETTE_TO_W3C_AXIS, ManetteAxis, W3C_AXIS_COUNT, TRIGGER_PRESS_THRESHOLD } from "./axis-mapping.js";
+import { W3CButton } from "./button-mapping.js";
+const MAX_GAMEPADS = 4;
+class GamepadManager {
+  _monitor = null;
+  _slots = new Array(MAX_GAMEPADS).fill(null);
+  _monitorSignalIds = [];
+  _ManetteModule = null;
+  _initPromise = null;
+  _initialized = false;
+  /**
+   * Lazily initialize the Manette.Monitor.
+   * Called on first `getGamepads()` invocation.
+   */
+  _ensureInit() {
+    if (this._initialized) return;
+    if (this._initPromise) return;
+    this._initPromise = this._init();
+  }
+  async _init() {
+    try {
+      const mod = await import("gi://Manette");
+      this._ManetteModule = mod.default;
+    } catch {
+      this._initialized = true;
+      return;
+    }
+    const monitor = new this._ManetteModule.Monitor();
+    this._monitor = monitor;
+    const iter = monitor.iterate();
+    let result = iter.next();
+    while (result[0]) {
+      const device = result[1];
+      if (device) {
+        this._onDeviceConnected(device);
+      }
+      result = iter.next();
+    }
+    this._monitorSignalIds.push(
+      monitor.connect("device-connected", (_monitor, device) => {
+        this._onDeviceConnected(device);
+      }),
+      monitor.connect("device-disconnected", (_monitor, device) => {
+        this._onDeviceDisconnected(device);
+      })
+    );
+    this._initialized = true;
+  }
+  _onDeviceConnected(device) {
+    let slotIndex = -1;
+    for (let i = 0; i < MAX_GAMEPADS; i++) {
+      if (this._slots[i] === null) {
+        slotIndex = i;
+        break;
+      }
+    }
+    if (slotIndex === -1) return;
+    const state = {
+      device,
+      index: slotIndex,
+      connected: true,
+      timestamp: performance.now(),
+      buttons: new Float64Array(W3C_BUTTON_COUNT),
+      buttonsPressed: new Array(W3C_BUTTON_COUNT).fill(false),
+      axes: new Float64Array(W3C_AXIS_COUNT),
+      hapticActuator: new ManetteHapticActuator(device),
+      signalIds: []
+    };
+    state.signalIds.push(
+      device.connect("button-press-event", (_device, event) => {
+        this._onButtonPress(state, event);
+      }),
+      device.connect("button-release-event", (_device, event) => {
+        this._onButtonRelease(state, event);
+      }),
+      device.connect("absolute-axis-event", (_device, event) => {
+        this._onAxisChange(state, event);
+      }),
+      device.connect("hat-axis-event", (_device, event) => {
+        this._onHatChange(state, event);
+      }),
+      device.connect("disconnected", () => {
+        this._onDeviceDisconnected(device);
+      })
+    );
+    this._slots[slotIndex] = state;
+    const snapshot = this._createSnapshot(state);
+    if (snapshot) {
+      globalThis.dispatchEvent?.(new GamepadEvent("gamepadconnected", { gamepad: snapshot }));
+    }
+  }
+  _onDeviceDisconnected(device) {
+    const state = this._findStateByDevice(device);
+    if (!state) return;
+    for (const id of state.signalIds) {
+      device.disconnect(id);
+    }
+    state.connected = false;
+    const snapshot = this._createSnapshot(state);
+    this._slots[state.index] = null;
+    if (snapshot) {
+      globalThis.dispatchEvent?.(new GamepadEvent("gamepaddisconnected", { gamepad: snapshot }));
+    }
+  }
+  _onButtonPress(state, event) {
+    const [ok, button] = event.get_button();
+    if (!ok) return;
+    const w3cIdx = MANETTE_TO_W3C_BUTTON.get(button);
+    if (w3cIdx === void 0) return;
+    state.buttons[w3cIdx] = 1;
+    state.buttonsPressed[w3cIdx] = true;
+    state.timestamp = performance.now();
+  }
+  _onButtonRelease(state, event) {
+    const [ok, button] = event.get_button();
+    if (!ok) return;
+    const w3cIdx = MANETTE_TO_W3C_BUTTON.get(button);
+    if (w3cIdx === void 0) return;
+    state.buttons[w3cIdx] = 0;
+    state.buttonsPressed[w3cIdx] = false;
+    state.timestamp = performance.now();
+  }
+  _onAxisChange(state, event) {
+    const [ok, axis, value] = event.get_absolute();
+    if (!ok) return;
+    const w3cAxisIdx = MANETTE_TO_W3C_AXIS.get(axis);
+    if (w3cAxisIdx !== void 0) {
+      state.axes[w3cAxisIdx] = value;
+    } else if (axis === ManetteAxis.LEFT_TRIGGER) {
+      const normalized = (value + 1) / 2;
+      state.buttons[W3CButton.LEFT_TRIGGER] = normalized;
+      state.buttonsPressed[W3CButton.LEFT_TRIGGER] = normalized > TRIGGER_PRESS_THRESHOLD;
+    } else if (axis === ManetteAxis.RIGHT_TRIGGER) {
+      const normalized = (value + 1) / 2;
+      state.buttons[W3CButton.RIGHT_TRIGGER] = normalized;
+      state.buttonsPressed[W3CButton.RIGHT_TRIGGER] = normalized > TRIGGER_PRESS_THRESHOLD;
+    }
+    state.timestamp = performance.now();
+  }
+  _onHatChange(state, event) {
+    const [ok, hatAxis, hatValue] = event.get_hat();
+    if (!ok) return;
+    if (hatAxis === 0) {
+      state.buttonsPressed[W3CButton.DPAD_LEFT] = hatValue < 0;
+      state.buttons[W3CButton.DPAD_LEFT] = hatValue < 0 ? 1 : 0;
+      state.buttonsPressed[W3CButton.DPAD_RIGHT] = hatValue > 0;
+      state.buttons[W3CButton.DPAD_RIGHT] = hatValue > 0 ? 1 : 0;
+    } else if (hatAxis === 1) {
+      state.buttonsPressed[W3CButton.DPAD_UP] = hatValue < 0;
+      state.buttons[W3CButton.DPAD_UP] = hatValue < 0 ? 1 : 0;
+      state.buttonsPressed[W3CButton.DPAD_DOWN] = hatValue > 0;
+      state.buttons[W3CButton.DPAD_DOWN] = hatValue > 0 ? 1 : 0;
+    }
+    state.timestamp = performance.now();
+  }
+  _findStateByDevice(device) {
+    for (const state of this._slots) {
+      if (state && state.device === device) return state;
+    }
+    return null;
+  }
+  _createSnapshot(state) {
+    const buttons = [];
+    for (let i = 0; i < W3C_BUTTON_COUNT; i++) {
+      buttons.push(new GamepadButton(
+        state.buttonsPressed[i],
+        state.buttonsPressed[i] || state.buttons[i] > 0,
+        state.buttons[i]
+      ));
+    }
+    return new Gamepad({
+      id: state.device.get_name() ?? `Gamepad (${state.device.get_guid()})`,
+      index: state.index,
+      connected: state.connected,
+      timestamp: state.timestamp,
+      mapping: "standard",
+      axes: Array.from(state.axes),
+      buttons,
+      vibrationActuator: state.hapticActuator
+    });
+  }
+  /**
+   * Returns a snapshot array matching the W3C `navigator.getGamepads()` contract.
+   * Each non-null entry is a frozen Gamepad object with current state.
+   */
+  getGamepads() {
+    this._ensureInit();
+    const result = [];
+    for (let i = 0; i < MAX_GAMEPADS; i++) {
+      const state = this._slots[i];
+      result.push(state ? this._createSnapshot(state) : null);
+    }
+    return result;
+  }
+  /** Cleanup — disconnect all signal handlers. */
+  dispose() {
+    for (const state of this._slots) {
+      if (state) {
+        for (const id of state.signalIds) {
+          state.device.disconnect(id);
+        }
+      }
+    }
+    this._slots.fill(null);
+    if (this._monitor) {
+      for (const id of this._monitorSignalIds) {
+        this._monitor.disconnect(id);
+      }
+      this._monitorSignalIds = [];
+      this._monitor = null;
+    }
+    this._initialized = false;
+    this._initPromise = null;
+  }
+}
+export {
+  GamepadManager
+};

package/lib/esm/gamepad.js

@@ -0,0 +1,26 @@
+class Gamepad {
+  id;
+  index;
+  connected;
+  timestamp;
+  mapping;
+  axes;
+  buttons;
+  vibrationActuator;
+  constructor(init) {
+    this.id = init.id;
+    this.index = init.index;
+    this.connected = init.connected;
+    this.timestamp = init.timestamp;
+    this.mapping = init.mapping;
+    this.axes = Object.freeze([...init.axes]);
+    this.buttons = Object.freeze(init.buttons);
+    this.vibrationActuator = init.vibrationActuator ?? null;
+  }
+  get [Symbol.toStringTag]() {
+    return "Gamepad";
+  }
+}
+export {
+  Gamepad
+};

package/lib/esm/haptic-actuator.js

@@ -0,0 +1,27 @@
+class ManetteHapticActuator {
+  effects;
+  _device;
+  constructor(device) {
+    this._device = device;
+    this.effects = device.has_rumble() ? ["dual-rumble"] : [];
+  }
+  playEffect(type, params) {
+    if (type !== "dual-rumble" || !this._device.has_rumble()) {
+      return Promise.resolve("complete");
+    }
+    const duration = params?.duration ?? 200;
+    const strong = Math.round((params?.strongMagnitude ?? 1) * 65535);
+    const weak = Math.round((params?.weakMagnitude ?? 1) * 65535);
+    this._device.rumble(strong, weak, Math.min(duration, 32767));
+    return Promise.resolve("complete");
+  }
+  reset() {
+    if (this._device.has_rumble()) {
+      this._device.rumble(0, 0, 0);
+    }
+    return Promise.resolve("complete");
+  }
+}
+export {
+  ManetteHapticActuator
+};

package/lib/esm/index.js

@@ -0,0 +1,23 @@
+import { GamepadButton } from "./gamepad-button.js";
+import { Gamepad } from "./gamepad.js";
+import { GamepadEvent } from "./gamepad-event.js";
+import { GamepadManager } from "./gamepad-manager.js";
+import { ManetteHapticActuator } from "./haptic-actuator.js";
+import { MANETTE_TO_W3C_BUTTON, ManetteButton, W3CButton, W3C_BUTTON_COUNT } from "./button-mapping.js";
+import { MANETTE_TO_W3C_AXIS, ManetteAxis, W3CAxis, W3C_AXIS_COUNT, TRIGGER_PRESS_THRESHOLD } from "./axis-mapping.js";
+export {
+  Gamepad,
+  GamepadButton,
+  GamepadEvent,
+  GamepadManager,
+  MANETTE_TO_W3C_AXIS,
+  MANETTE_TO_W3C_BUTTON,
+  ManetteAxis,
+  ManetteButton,
+  ManetteHapticActuator,
+  TRIGGER_PRESS_THRESHOLD,
+  W3CAxis,
+  W3CButton,
+  W3C_AXIS_COUNT,
+  W3C_BUTTON_COUNT
+};

package/lib/esm/register.js

@@ -0,0 +1,10 @@
+import { GamepadEvent } from "./gamepad-event.js";
+import { GamepadManager } from "./gamepad-manager.js";
+const manager = new GamepadManager();
+if (typeof globalThis.navigator === "undefined") {
+  globalThis.navigator = {};
+}
+globalThis.navigator.getGamepads = () => manager.getGamepads();
+if (typeof globalThis.GamepadEvent === "undefined") {
+  globalThis.GamepadEvent = GamepadEvent;
+}

package/lib/types/axis-mapping.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SDL logical axis indices as reported by Manette.Event.get_absolute().
+ * These are the SDL gamepad mapping indices, NOT Linux ABS_* hardware codes.
+ */
+export declare const ManetteAxis: {
+    readonly LEFT_X: 0;
+    readonly LEFT_Y: 1;
+    readonly RIGHT_X: 2;
+    readonly RIGHT_Y: 3;
+    readonly LEFT_TRIGGER: 4;
+    readonly RIGHT_TRIGGER: 5;
+};
+/**
+ * W3C standard gamepad axis indices.
+ * https://w3c.github.io/gamepad/#remapping
+ */
+export declare const W3CAxis: {
+    readonly LEFT_STICK_X: 0;
+    readonly LEFT_STICK_Y: 1;
+    readonly RIGHT_STICK_X: 2;
+    readonly RIGHT_STICK_Y: 3;
+};
+/** Total number of axes in the W3C standard mapping. */
+export declare const W3C_AXIS_COUNT = 4;
+/**
+ * Maps SDL logical axis → W3C axis index.
+ * Stick axes (0–3) map 1:1. Trigger axes (4–5) are NOT in this map —
+ * they are handled separately in gamepad-manager as buttons[6]/buttons[7].
+ */
+export declare const MANETTE_TO_W3C_AXIS: ReadonlyMap<number, number>;
+/** Threshold above which an analog trigger is considered "pressed". */
+export declare const TRIGGER_PRESS_THRESHOLD = 0.5;

package/lib/types/button-mapping.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Linux BTN_* input event codes as reported by Manette.Event.get_button().
+ * These are the actual values libmanette 0.2 passes in button-press/release signals.
+ */
+export declare const LinuxButton: {
+    readonly BTN_SOUTH: 304;
+    readonly BTN_EAST: 305;
+    readonly BTN_C: 306;
+    readonly BTN_NORTH: 307;
+    readonly BTN_WEST: 308;
+    readonly BTN_Z: 309;
+    readonly BTN_TL: 310;
+    readonly BTN_TR: 311;
+    readonly BTN_TL2: 312;
+    readonly BTN_TR2: 313;
+    readonly BTN_SELECT: 314;
+    readonly BTN_START: 315;
+    readonly BTN_MODE: 316;
+    readonly BTN_THUMBL: 317;
+    readonly BTN_THUMBR: 318;
+    readonly BTN_DPAD_UP: 544;
+    readonly BTN_DPAD_DOWN: 545;
+    readonly BTN_DPAD_LEFT: 546;
+    readonly BTN_DPAD_RIGHT: 547;
+};
+/**
+ * W3C standard gamepad button indices.
+ * https://w3c.github.io/gamepad/#remapping
+ */
+export declare const W3CButton: {
+    readonly FACE_1: 0;
+    readonly FACE_2: 1;
+    readonly FACE_3: 2;
+    readonly FACE_4: 3;
+    readonly LEFT_BUMPER: 4;
+    readonly RIGHT_BUMPER: 5;
+    readonly LEFT_TRIGGER: 6;
+    readonly RIGHT_TRIGGER: 7;
+    readonly SELECT: 8;
+    readonly START: 9;
+    readonly LEFT_STICK: 10;
+    readonly RIGHT_STICK: 11;
+    readonly DPAD_UP: 12;
+    readonly DPAD_DOWN: 13;
+    readonly DPAD_LEFT: 14;
+    readonly DPAD_RIGHT: 15;
+    readonly HOME: 16;
+};
+/** Total number of buttons in the W3C standard mapping. */
+export declare const W3C_BUTTON_COUNT = 17;
+/**
+ * Maps Linux BTN_* code → W3C standard button index.
+ */
+export declare const MANETTE_TO_W3C_BUTTON: ReadonlyMap<number, number>;
+export { LinuxButton as ManetteButton };

package/lib/types/gamepad-button.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Represents the state of a single button on a gamepad.
+ * https://w3c.github.io/gamepad/#dom-gamepadbutton
+ */
+export declare class GamepadButton {
+    pressed: boolean;
+    touched: boolean;
+    value: number;
+    constructor(pressed?: boolean, touched?: boolean, value?: number);
+    get [Symbol.toStringTag](): string;
+}

package/lib/types/gamepad-event.d.ts

@@ -0,0 +1,17 @@
+import { Event } from '@gjsify/dom-events';
+import type { Gamepad } from './gamepad.js';
+export interface GamepadEventInit {
+    gamepad: Gamepad;
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+}
+/**
+ * Fired on the Window when a gamepad is connected or disconnected.
+ * https://w3c.github.io/gamepad/#dom-gamepadevent
+ */
+export declare class GamepadEvent extends Event {
+    readonly gamepad: Gamepad;
+    constructor(type: string, eventInitDict: GamepadEventInit);
+    get [Symbol.toStringTag](): string;
+}

package/lib/types/gamepad-manager.d.ts

@@ -0,0 +1,37 @@
+import { Gamepad } from './gamepad.js';
+/**
+ * Singleton manager that wraps Manette.Monitor and maintains gamepad state.
+ *
+ * libmanette fires GObject signals on button/axis changes. This manager
+ * caches the latest state so that `getGamepads()` can return a snapshot
+ * matching the W3C Gamepad API's polling model.
+ */
+export declare class GamepadManager {
+    private _monitor;
+    private _slots;
+    private _monitorSignalIds;
+    private _ManetteModule;
+    private _initPromise;
+    private _initialized;
+    /**
+     * Lazily initialize the Manette.Monitor.
+     * Called on first `getGamepads()` invocation.
+     */
+    private _ensureInit;
+    private _init;
+    private _onDeviceConnected;
+    private _onDeviceDisconnected;
+    private _onButtonPress;
+    private _onButtonRelease;
+    private _onAxisChange;
+    private _onHatChange;
+    private _findStateByDevice;
+    private _createSnapshot;
+    /**
+     * Returns a snapshot array matching the W3C `navigator.getGamepads()` contract.
+     * Each non-null entry is a frozen Gamepad object with current state.
+     */
+    getGamepads(): (Gamepad | null)[];
+    /** Cleanup — disconnect all signal handlers. */
+    dispose(): void;
+}

package/lib/types/gamepad.d.ts

@@ -0,0 +1,45 @@
+import { GamepadButton } from './gamepad-button.js';
+/**
+ * Represents a single gamepad device.
+ * Instances are snapshots — they are not live-updating.
+ * https://w3c.github.io/gamepad/#dom-gamepad
+ */
+export declare class Gamepad {
+    readonly id: string;
+    readonly index: number;
+    readonly connected: boolean;
+    readonly timestamp: number;
+    readonly mapping: GamepadMappingType;
+    readonly axes: readonly number[];
+    readonly buttons: readonly GamepadButton[];
+    readonly vibrationActuator: GamepadHapticActuator | null;
+    constructor(init: {
+        id: string;
+        index: number;
+        connected: boolean;
+        timestamp: number;
+        mapping: GamepadMappingType;
+        axes: number[];
+        buttons: GamepadButton[];
+        vibrationActuator?: GamepadHapticActuator | null;
+    });
+    get [Symbol.toStringTag](): string;
+}
+export type GamepadMappingType = '' | 'standard' | 'xr-standard';
+/**
+ * Provides access to haptic feedback (rumble) on the gamepad.
+ * https://w3c.github.io/gamepad/#dom-gamepadhapticactuator
+ */
+export interface GamepadHapticActuator {
+    readonly effects: readonly GamepadHapticEffectType[];
+    playEffect(type: GamepadHapticEffectType, params?: GamepadEffectParameters): Promise<GamepadHapticsResult>;
+    reset(): Promise<GamepadHapticsResult>;
+}
+export type GamepadHapticEffectType = 'dual-rumble' | 'trigger-rumble';
+export type GamepadHapticsResult = 'complete' | 'preempted';
+export interface GamepadEffectParameters {
+    duration?: number;
+    startDelay?: number;
+    strongMagnitude?: number;
+    weakMagnitude?: number;
+}

package/lib/types/gamepad.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;