three-gamepad-controls 0.24.0 → 0.24.2

package/README.md

@@ -25,8 +25,8 @@ npm i -D @types/three # optional: for TypeScript projects
 pnpm:
 
 ```bash
-pnpm add three three-gamepad-controls
-pnpm add -D @types/three # optional: for TypeScript projects
+pn add three three-gamepad-controls
+pn add -D @types/three # optional: for TypeScript projects
 ```
 
 Yarn:
@@ -58,13 +58,41 @@ bun add three three-gamepad-controls
 bun add -d @types/three # optional: for TypeScript projects
 ```
 
+## 🧪 Testing
+
+Tests use Vitest with Browser Mode and Playwright for browser-dependent behavior in Chromium. Browser-independent tests run directly in Node.js.
+
+After installing the project dependencies, install Chromium once:
+
+```bash
+pn exec playwright install chromium
+```
+
+Run the test suite once:
+
+```bash
+pn test
+```
+
+Start Vitest in watch mode while developing:
+
+```bash
+pn test:watch
+```
+
+Generate the coverage report:
+
+```bash
+pn test:coverage
+```
+
 ## 🔗 Compatibility
 
 | Three.js | Three.js Gamepad Controls |
 | --- | --- |
-| `~0.184.0` | `<=0.22.0` |
-| `~0.185.0` | `0.23.0` |
-| `~0.186.0` | `0.24.0` |
+| `0.184.x` | `<=0.22.x` |
+| `0.185.x` | `0.23.x` |
+| `0.186.x` | `0.24.x` |
 
 ## 📖 Documentation
 

package/dist/core.d.ts

@@ -4,19 +4,19 @@
  *
  * Gamepad slots cannot be negative.
  */
-declare const MIN_GAMEPAD_INDEX = 0;
+export declare const MIN_GAMEPAD_INDEX = 0;
 /**
  * Largest valid browser-assigned gamepad index.
  *
  * `Gamepad.index` is a Web IDL `long`, a signed 32-bit integer. Because
  * gamepad slots cannot be negative, the largest valid index is 2^31 - 1.
  */
-declare const MAX_GAMEPAD_INDEX = 2147483647;
+export declare const MAX_GAMEPAD_INDEX = 2147483647;
 /**
  * Button indices for the W3C Standard Gamepad mapping.
  * @see https://www.w3.org/TR/gamepad/#dfn-standard-gamepad
  */
-declare const GAMEPAD_BUTTON: {
+export declare const GAMEPAD_BUTTON: {
   readonly South: 0;
   readonly East: 1;
   readonly West: 2;
@@ -39,7 +39,7 @@ declare const GAMEPAD_BUTTON: {
  * Axis indices for the W3C Standard Gamepad mapping.
  * @see https://www.w3.org/TR/gamepad/#dfn-standard-gamepad
  */
-declare const GAMEPAD_AXIS: {
+export declare const GAMEPAD_AXIS: {
   readonly LeftX: 0;
   readonly LeftY: 1;
   readonly RightX: 2;
@@ -48,18 +48,17 @@ declare const GAMEPAD_AXIS: {
 /**
  * Union type of all valid {@link GAMEPAD_BUTTON} keys.
  */
-type GamepadButtonKey = keyof typeof GAMEPAD_BUTTON;
+export type GamepadButtonKey = keyof typeof GAMEPAD_BUTTON;
 /**
  * Union type of all valid {@link GAMEPAD_BUTTON} values.
  */
-type GamepadButtonValue = (typeof GAMEPAD_BUTTON)[keyof typeof GAMEPAD_BUTTON];
+export type GamepadButtonValue = (typeof GAMEPAD_BUTTON)[keyof typeof GAMEPAD_BUTTON];
 /**
  * Union type of all valid {@link GAMEPAD_AXIS} keys.
  */
-type GamepadAxisKey = keyof typeof GAMEPAD_AXIS;
+export type GamepadAxisKey = keyof typeof GAMEPAD_AXIS;
 /**
  * Union type of all valid {@link GAMEPAD_AXIS} values.
  */
-type GamepadAxisValue = (typeof GAMEPAD_AXIS)[keyof typeof GAMEPAD_AXIS];
-//#endregion
-export { GAMEPAD_AXIS, GAMEPAD_BUTTON, GamepadAxisKey, GamepadAxisValue, GamepadButtonKey, GamepadButtonValue, MAX_GAMEPAD_INDEX, MIN_GAMEPAD_INDEX };
+export type GamepadAxisValue = (typeof GAMEPAD_AXIS)[keyof typeof GAMEPAD_AXIS];
+//#endregion

package/dist/gamepad-arcball-controls.d.ts

@@ -7,7 +7,7 @@ import { ArcballControls } from "three/addons/controls/ArcballControls.js";
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadArcballControlsOptions = GamepadControlsOptions & {
+export type GamepadArcballControlsOptions = GamepadControlsOptions & {
   /**
    * Multiplier on `ArcballControls.rotateSpeed` for rotation.
    * @default 1.0
@@ -76,7 +76,7 @@ type GamepadArcballControlsOptions = GamepadControlsOptions & {
  * Arcball transformations. The wrapped `ArcballControls.update()` is only
  * needed after manual camera or target changes, matching Arcball's native API.
  */
-declare class GamepadArcballControls extends GamepadControls {
+export declare class GamepadArcballControls extends GamepadControls {
   #private;
   /**
    * @param controls - A Three.js `ArcballControls` instance.
@@ -91,6 +91,7 @@ declare class GamepadArcballControls extends GamepadControls {
    * @param deltaTime - Seconds since the last frame.
    */
   protected onUpdate(deltaTime: number): void;
+  dispose(): void;
+  protected onGamepadDisconnected(gamepad: Gamepad): void;
 }
-//#endregion
-export { GamepadArcballControls, GamepadArcballControlsOptions };
+//#endregion

package/dist/gamepad-arcball-controls.js

@@ -77,10 +77,7 @@ var GamepadArcballControls = class extends GamepadControls {
 		const { rotateSpeed, panSpeed, zoomSpeed, zRotateSpeed, rotateStick, panStick, buttonDeadzone, buttonZoomIn, buttonZoomOut, buttonZRotateLeft, buttonZRotateRight, buttonFocus } = this.#options;
 		const input = this.gamepadInput;
 		const focusPoint = this.#consumeFocusPoint(buttonFocus);
-		if (!controls.enabled) {
-			this.#endInteraction();
-			return;
-		}
+		if (!this.#canApplyInput()) return;
 		let rotateX = 0;
 		let rotateY = 0;
 		if (controls.enableRotate) {
@@ -102,20 +99,38 @@ var GamepadArcballControls = class extends GamepadControls {
 			this.#endInteraction();
 			return;
 		}
-		if (!this.#wasInteracting) controls.dispatchEvent({ type: "start" });
+		if (!this.#wasInteracting) {
+			this.#wasInteracting = true;
+			controls.dispatchEvent({ type: "start" });
+		}
+		if (!this.#canApplyInput()) return;
 		let changed = false;
-		changed = this.#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed) || changed;
-		changed = this.#applyPan(deltaTime, panX, panY, panSpeed) || changed;
-		changed = this.#applyZoom(deltaTime, zoom, zoomSpeed, buttonDeadzone) || changed;
-		changed = this.#applyZRotation(deltaTime, zRotation, zRotateSpeed, buttonDeadzone) || changed;
-		changed = this.#applyFocus(focusPoint) || changed;
+		if (controls.enableRotate) changed = this.#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed) || changed;
+		if (controls.enablePan) changed = this.#applyPan(deltaTime, panX, panY, panSpeed) || changed;
+		if (controls.enableZoom) changed = this.#applyZoom(deltaTime, zoom, zoomSpeed, buttonDeadzone) || changed;
+		if (controls.enableRotate) changed = this.#applyZRotation(deltaTime, zRotation, zRotateSpeed, buttonDeadzone) || changed;
+		if (controls.enablePan && controls.enableFocus) changed = this.#applyFocus(focusPoint) || changed;
 		if (changed) {
 			controls.update();
 			controls.updateMatrixState();
 			controls.dispatchEvent({ type: "change" });
 		}
-		this.#wasInteracting = activeInput;
-		if (!activeInput) this.#endInteraction();
+		if (!activeInput || !controls.enabled) this.#endInteraction();
+	}
+	dispose() {
+		super.dispose();
+		this.#endInteraction();
+	}
+	onGamepadDisconnected(gamepad) {
+		this.#endInteraction();
+		super.onGamepadDisconnected(gamepad);
+	}
+	#canApplyInput() {
+		if (!this.#controls.enabled) {
+			this.#endInteraction();
+			return false;
+		}
+		return this.enabled && this.gamepad !== null;
 	}
 	/**
 	* Applies gamepad stick rotation through Arcball's runtime rotation helper.
@@ -253,8 +268,8 @@ var GamepadArcballControls = class extends GamepadControls {
 	}
 	#endInteraction() {
 		if (!this.#wasInteracting) return;
-		this.#controls.dispatchEvent({ type: "end" });
 		this.#wasInteracting = false;
+		this.#controls.dispatchEvent({ type: "end" });
 	}
 };
 //#endregion

package/dist/gamepad-controls.d.ts

@@ -7,7 +7,7 @@ import { EventDispatcher } from "three";
  * Each key is an event name, and its value is the extra data included in the event object
  * alongside the standard `type` and `target` fields.
  */
-type GamepadControlsEventMap = {
+export type GamepadControlsEventMap = {
   /**
    * Fired when a gamepad is connected and set as the active gamepad.
    */
@@ -18,7 +18,8 @@ type GamepadControlsEventMap = {
     gamepad: Gamepad;
   };
   /**
-   * Fired when the active gamepad is disconnected or replaced in its slot.
+   * Fired on a matching browser disconnection event or when polling observes
+   * the active slot missing or disconnected, not on snapshot identity changes.
    */
   disconnected: {
     /**
@@ -30,22 +31,25 @@ type GamepadControlsEventMap = {
 /**
  * Shared configuration for Three.js gamepad control wrappers.
  */
-type GamepadControlsOptions = Pick<GamepadInputOptions, "gamepadIndex">;
+export type GamepadControlsOptions = Pick<GamepadInputOptions, "gamepadIndex">;
 /**
  * Abstract base class for Three.js gamepad controls.
  *
  * Delegates gamepad connection lifecycle and input polling to {@link GamepadInput}
  * so subclasses can focus on mapping input to the wrapped Three.js control.
  */
-declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEventMap> {
+export declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEventMap> {
   #private;
   /**
-   * When `false`, all input processing is paused.
+   * When `false`, `update()` pauses polling and subclass input application,
+   * retaining state. Browser connection/disconnection listeners remain active.
+   * Assignment alone does not cancel an interaction or dispose the wrapper.
    * @default true
    */
   enabled: boolean;
   /**
-   * The currently active gamepad, or `null` if no gamepad is connected.
+   * The active gamepad snapshot, or `null` if none has been adopted.
+   * Automatic selection keeps its adopted slot until an observed loss.
    */
   gamepad: Gamepad | null;
   /**
@@ -72,6 +76,8 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
   get vibrationSupported(): boolean;
   /**
    * Advances the controller by one frame. Call this inside your render loop.
+   * While paused, polling-only losses remain unobserved until updates resume.
+   * Resume compares button state with the last observation, without replay.
    *
    * @param deltaTime - Seconds since the last frame.
    */
@@ -98,7 +104,9 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
    */
   resetVibration(): Promise<GamepadHapticsResult | null>;
   /**
-   * Removes all event listeners attached by this controller. Call when no longer needed.
+   * Removes this wrapper's internal input listeners, clears state, and disables
+   * it without dispatching a synthetic disconnection. Does not dispose the
+   * wrapped Three.js control or affect other wrappers. Reuse is unsupported.
    */
   dispose(): void;
   /**
@@ -116,8 +124,8 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
    */
   protected onGamepadConnected(gamepad: Gamepad): void;
   /**
-   * Called when the active gamepad disconnects or is replaced through the
-   * shared input reader.
+   * Called when the shared input reader observes a matching disconnection
+   * event or a missing/disconnected active slot, including events during pause.
    *
    * The default dispatches a `disconnected` event.
    *
@@ -125,5 +133,4 @@ declare abstract class GamepadControls extends EventDispatcher<GamepadControlsEv
    */
   protected onGamepadDisconnected(gamepad: Gamepad): void;
 }
-//#endregion
-export { GamepadControls, GamepadControlsEventMap, GamepadControlsOptions };
+//#endregion

package/dist/gamepad-controls.js

@@ -9,12 +9,15 @@ import { EventDispatcher } from "three";
 */
 var GamepadControls = class extends EventDispatcher {
 	/**
-	* When `false`, all input processing is paused.
+	* When `false`, `update()` pauses polling and subclass input application,
+	* retaining state. Browser connection/disconnection listeners remain active.
+	* Assignment alone does not cancel an interaction or dispose the wrapper.
 	* @default true
 	*/
 	enabled = true;
 	/**
-	* The currently active gamepad, or `null` if no gamepad is connected.
+	* The active gamepad snapshot, or `null` if none has been adopted.
+	* Automatic selection keeps its adopted slot until an observed loss.
 	*/
 	gamepad = null;
 	#gamepadInput;
@@ -73,6 +76,8 @@ var GamepadControls = class extends EventDispatcher {
 	}
 	/**
 	* Advances the controller by one frame. Call this inside your render loop.
+	* While paused, polling-only losses remain unobserved until updates resume.
+	* Resume compares button state with the last observation, without replay.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	*/
@@ -80,7 +85,7 @@ var GamepadControls = class extends EventDispatcher {
 		if (!this.enabled) return;
 		this.#gamepadInput.update();
 		this.gamepad = this.#gamepadInput.gamepad;
-		if (this.gamepad === null) return;
+		if (!this.enabled || this.gamepad === null) return;
 		this.onUpdate(deltaTime);
 	}
 	/**
@@ -109,7 +114,9 @@ var GamepadControls = class extends EventDispatcher {
 		return this.#gamepadInput.resetVibration();
 	}
 	/**
-	* Removes all event listeners attached by this controller. Call when no longer needed.
+	* Removes this wrapper's internal input listeners, clears state, and disables
+	* it without dispatching a synthetic disconnection. Does not dispose the
+	* wrapped Three.js control or affect other wrappers. Reuse is unsupported.
 	*/
 	dispose() {
 		this.#gamepadInput.removeEventListener("connected", this.#onGamepadConnected);
@@ -132,8 +139,8 @@ var GamepadControls = class extends EventDispatcher {
 		});
 	}
 	/**
-	* Called when the active gamepad disconnects or is replaced through the
-	* shared input reader.
+	* Called when the shared input reader observes a matching disconnection
+	* event or a missing/disconnected active slot, including events during pause.
 	*
 	* The default dispatches a `disconnected` event.
 	*

package/dist/gamepad-drag-controls.d.ts

@@ -7,7 +7,7 @@ import { DragControls } from "three/addons/controls/DragControls.js";
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadDragControlsOptions = GamepadControlsOptions & {
+export type GamepadDragControlsOptions = GamepadControlsOptions & {
   /**
    * Screen-relative translation speed multiplier.
    * @default 1.0
@@ -40,7 +40,7 @@ type GamepadDragControlsOptions = GamepadControlsOptions & {
  * The center of the viewport acts as a logical reticle. Press the select button
  * once to grab the centered object and again to drop it.
  */
-declare class GamepadDragControls extends GamepadControls {
+export declare class GamepadDragControls extends GamepadControls {
   #private;
   /**
    * @param controls - A Three.js `DragControls` instance.
@@ -56,8 +56,7 @@ declare class GamepadDragControls extends GamepadControls {
    */
   protected onUpdate(deltaTime: number): void;
   /**
-   * Releases any selected object and removes hover state before disposing the
-   * gamepad lifecycle listeners.
+   * Disables gamepad updates, releases selection, and removes hover state.
    */
   dispose(): void;
   /**
@@ -67,5 +66,4 @@ declare class GamepadDragControls extends GamepadControls {
    */
   protected onGamepadDisconnected(gamepad: Gamepad): void;
 }
-//#endregion
-export { GamepadDragControls, GamepadDragControlsOptions };
+//#endregion

package/dist/gamepad-drag-controls.js

@@ -73,13 +73,8 @@ var GamepadDragControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	onUpdate(deltaTime) {
-		const controls = this.#controls;
 		const selectStarted = this.gamepadInput.wasPressed(this.#options.buttonSelect);
-		if (!controls.enabled) {
-			this.#releaseSelected();
-			this.#clearHover();
-			return;
-		}
+		if (!this.#canApplyInput()) return;
 		const selected = this.#selected;
 		if (selected !== null) {
 			if (selectStarted) {
@@ -91,16 +86,19 @@ var GamepadDragControls = class extends GamepadControls {
 		}
 		const hit = this.#intersectCenter();
 		this.#updateHover(hit?.object ?? null);
-		if (selectStarted && hit !== void 0) this.#grabObject(hit.object);
+		if (!this.#canApplyInput()) return;
+		if (selectStarted && hit !== void 0) {
+			this.#grabObject(hit.object);
+			this.#canApplyInput();
+		}
 	}
 	/**
-	* Releases any selected object and removes hover state before disposing the
-	* gamepad lifecycle listeners.
+	* Disables gamepad updates, releases selection, and removes hover state.
 	*/
 	dispose() {
+		super.dispose();
 		this.#releaseSelected();
 		this.#clearHover();
-		super.dispose();
 	}
 	/**
 	* Releases the selected object if the active gamepad disconnects mid-drag.
@@ -112,6 +110,14 @@ var GamepadDragControls = class extends GamepadControls {
 		this.#clearHover();
 		super.onGamepadDisconnected(gamepad);
 	}
+	#canApplyInput() {
+		if (!this.#controls.enabled) {
+			this.#releaseSelected();
+			this.#clearHover();
+			return false;
+		}
+		return this.enabled && this.gamepad !== null;
+	}
 	/**
 	* Updates the selected object from gamepad drag and rotation input.
 	*
@@ -125,10 +131,13 @@ var GamepadDragControls = class extends GamepadControls {
 		const rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
 		const dragged = this.#applyDrag(selected, deltaTime, drag.x, drag.y, dragSpeed);
 		const rotated = this.#applyRotation(selected, deltaTime, rotate.x, rotate.y, rotateSpeed);
-		if (dragged || rotated) this.#controls.dispatchEvent({
-			type: "drag",
-			object: selected
-		});
+		if (dragged || rotated) {
+			this.#controls.dispatchEvent({
+				type: "drag",
+				object: selected
+			});
+			this.#canApplyInput();
+		}
 	}
 	/**
 	* Moves the selected object in the camera-facing plane.
@@ -188,7 +197,7 @@ var GamepadDragControls = class extends GamepadControls {
 	#updateHover(object) {
 		if (this.#hovered === object) return;
 		this.#clearHover();
-		if (object === null) return;
+		if (object === null || !this.#canApplyInput()) return;
 		this.#hovered = object;
 		this.#controls.dispatchEvent({
 			type: "hoveron",

package/dist/gamepad-first-person-controls.d.ts

@@ -7,7 +7,7 @@ import { FirstPersonControls } from "three/addons/controls/FirstPersonControls.j
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
+export type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
   /**
    * Multiplier on `FirstPersonControls.movementSpeed` for translation.
    * @default 1.0
@@ -49,7 +49,7 @@ type GamepadFirstPersonControlsOptions = GamepadControlsOptions & {
  * `gamepadControls.update(delta)` before `controls.update(delta)` each frame.
  * Bindings and speeds are configurable via {@link GamepadFirstPersonControlsOptions}.
  */
-declare class GamepadFirstPersonControls extends GamepadControls {
+export declare class GamepadFirstPersonControls extends GamepadControls {
   #private;
   /**
    * @param controls - A Three.js `FirstPersonControls` instance.
@@ -64,5 +64,4 @@ declare class GamepadFirstPersonControls extends GamepadControls {
    */
   protected onUpdate(deltaTime: number): void;
 }
-//#endregion
-export { GamepadFirstPersonControls, GamepadFirstPersonControlsOptions };
+//#endregion

package/dist/gamepad-first-person-controls.js

@@ -58,6 +58,7 @@ var GamepadFirstPersonControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	onUpdate(deltaTime) {
+		if (!this.#controls.enabled) return;
 		const { moveSpeed, lookSpeed, moveStick, lookStick, buttonDeadzone, buttonMoveUp, buttonMoveDown } = this.#options;
 		this.#applyMovement(deltaTime, moveSpeed, moveStick, buttonDeadzone, buttonMoveUp, buttonMoveDown);
 		this.#applyLook(deltaTime, lookSpeed, lookStick);

package/dist/gamepad-fly-controls.d.ts

@@ -7,7 +7,7 @@ import { FlyControls } from "three/addons/controls/FlyControls.js";
  *
  * Every property has a sensible default, so you only need to pass the properties you want to override.
  */
-type GamepadFlyControlsOptions = GamepadControlsOptions & {
+export type GamepadFlyControlsOptions = GamepadControlsOptions & {
   /**
    * Multiplier on `FlyControls.movementSpeed` for translation.
    * @default 1.0
@@ -59,7 +59,7 @@ type GamepadFlyControlsOptions = GamepadControlsOptions & {
  * `gamepadControls.update(delta)` and `controls.update(delta)` each frame.
  * Bindings and speeds are configurable via {@link GamepadFlyControlsOptions}.
  */
-declare class GamepadFlyControls extends GamepadControls {
+export declare class GamepadFlyControls extends GamepadControls {
   #private;
   /**
    * @param controls - A Three.js `FlyControls` instance.
@@ -74,5 +74,4 @@ declare class GamepadFlyControls extends GamepadControls {
    */
   protected onUpdate(deltaTime: number): void;
 }
-//#endregion
-export { GamepadFlyControls, GamepadFlyControlsOptions };
+//#endregion

package/dist/gamepad-fly-controls.js

@@ -55,6 +55,7 @@ var GamepadFlyControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	onUpdate(deltaTime) {
+		if (!this.#controls.enabled) return;
 		const { moveSpeed, rotateSpeed, buttonDeadzone, moveStick, lookStick, buttonRollLeft, buttonRollRight, buttonMoveUp, buttonMoveDown } = this.#options;
 		const input = this.gamepadInput;
 		const move = input.stick(moveStick.xAxis, moveStick.yAxis, moveStick.pipeline);

package/dist/gamepad-input.d.ts

@@ -4,7 +4,7 @@ import { EventDispatcher } from "three";
 /**
  * Event map for {@link GamepadInput}.
  */
-type GamepadInputEventMap = {
+export type GamepadInputEventMap = {
   /**
    * Fired when a gamepad is connected and becomes active.
    */
@@ -15,7 +15,9 @@ type GamepadInputEventMap = {
     gamepad: Gamepad;
   };
   /**
-   * Fired when the active gamepad is disconnected or replaced in its slot.
+   * Fired on a matching browser disconnection event or when polling observes
+   * the active slot missing or disconnected. Continuous snapshots in the same
+   * slot do not establish a physical-device identity or signal replacement.
    */
   disconnected: {
     /**
@@ -27,7 +29,7 @@ type GamepadInputEventMap = {
 /**
  * Configuration for {@link GamepadInput}.
  */
-type GamepadInputOptions = {
+export type GamepadInputOptions = {
   /**
    * Default dead zone threshold for {@link GamepadInput.axis} reads.
    * @default 0.1
@@ -41,7 +43,9 @@ type GamepadInputOptions = {
   /**
    * Browser-assigned gamepad slot to use.
    *
-   * When omitted, the connected gamepad with the lowest index is selected.
+   * When omitted, the lowest connected index is chosen at adoption and kept
+   * until its loss is observed, even if a lower index subsequently connects.
+   * Multiple unconfigured instances may adopt the same slot.
    * The index must be an integer from `MIN_GAMEPAD_INDEX` through
    * `MAX_GAMEPAD_INDEX`.
    * A valid but empty slot keeps this input disconnected without falling back
@@ -52,7 +56,7 @@ type GamepadInputOptions = {
 /**
  * Options for axis reads.
  */
-type GamepadAxisOptions = {
+export type GamepadAxisOptions = {
   /**
    * Axis dead zone threshold for this read.
    */
@@ -63,10 +67,12 @@ type GamepadAxisOptions = {
  *
  * Call {@link update} once per frame before reading button transitions or axes.
  */
-declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
+export declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
   #private;
   /**
-   * When `false`, input polling is paused.
+   * When `false`, polling through `update()` is paused and the last observed
+   * state, including button transitions, is retained. Browser listeners remain
+   * active and may adopt or disconnect a gamepad; connection events may poll.
    * @default true
    */
   enabled: boolean;
@@ -112,10 +118,15 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
   get vibrationSupported(): boolean;
   /**
    * Polls the gamepad and refreshes current and previous button state.
+   *
+   * Resuming compares against the last observed state, without replaying clicks
+   * completed during the pause. Adoption seeds held buttons without transitions.
    */
   update(): void;
   /**
-   * Removes all window-level event listeners attached by this input reader.
+   * Removes this reader's window listeners, clears its state, and disables it.
+   * Does not dispatch a synthetic disconnection or affect other input readers.
+   * Reusing a disposed reader is unsupported; create a new instance instead.
    */
   dispose(): void;
   /**
@@ -126,17 +137,19 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
    */
   isPressed(button: number): boolean;
   /**
-   * Returns whether a button was pressed during the latest update.
+   * Returns whether a button changed to pressed in the latest observed state.
+   * Paused updates retain this result until the next observation or cleanup.
    *
    * @param button - Button index to inspect.
-   * @returns `true` only on the frame where the button transitions to pressed.
+   * @returns Whether the latest observed button state transitioned to pressed.
    */
   wasPressed(button: number): boolean;
   /**
-   * Returns whether a button was released during the latest update.
+   * Returns whether a button changed to released in the latest observed state.
+   * Paused updates retain this result until the next observation or cleanup.
    *
    * @param button - Button index to inspect.
-   * @returns `true` only on the frame where the button transitions to released.
+   * @returns Whether the latest observed button state transitioned to released.
    */
   wasReleased(button: number): boolean;
   /**
@@ -185,5 +198,4 @@ declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
    */
   resetVibration(): Promise<GamepadHapticsResult | null>;
 }
-//#endregion
-export { GamepadAxisOptions, GamepadInput, GamepadInputEventMap, GamepadInputOptions };
+//#endregion