three-gamepad-controls 0.23.0 → 0.24.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright (c) 2026 Lucas Alves Costa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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,12 +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.184.x` | `<=0.22.x` |
+| `0.185.x` | `0.23.x` |
+| `0.186.x` | `0.24.x` |
 
 ## 📖 Documentation
 
@@ -85,4 +114,4 @@ bun add -d @types/three # optional: for TypeScript projects
 
 ## 📄 License
 
-Licensed under the [MIT License](./LICENSE).
+Licensed under the [MIT License](./LICENSE.md).

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