three-gamepad-controls 0.24.2 → 0.25.0

package/README.md

@@ -92,7 +92,7 @@ pn test:coverage
 | --- | --- |
 | `0.184.x` | `<=0.22.x` |
 | `0.185.x` | `0.23.x` |
-| `0.186.x` | `0.24.x` |
+| `0.186.x` | `0.24.x`, `0.25.x` |
 
 ## 📖 Documentation
 

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

@@ -75,6 +75,8 @@ export type GamepadArcballControlsOptions = GamepadControlsOptions & {
  * Call `update()` inside the render loop to poll gamepad input and apply
  * Arcball transformations. The wrapped `ArcballControls.update()` is only
  * needed after manual camera or target changes, matching Arcball's native API.
+ * Gamepad `start`, `change`, and `end` events are dispatched on the native controls.
+ * The balanced session belongs to this wrapper, including isolated focus commands.
  */
 export declare class GamepadArcballControls extends GamepadControls {
   #private;
@@ -85,13 +87,31 @@ export declare class GamepadArcballControls extends GamepadControls {
    */
   constructor(controls: ArcballControls, options?: Partial<GamepadArcballControlsOptions>);
   /**
-   * Maps the current gamepad state to `ArcballControls` rotation, pan, zoom,
-   * z-rotation, and center focus.
+   * Polls and applies gamepad input, ignoring updates from synchronous native listeners.
+   * Pausing through `enabled` retains the owned interaction until input resumes,
+   * the gamepad disconnects, or the wrapper is disposed.
    *
    * @param deltaTime - Seconds since the last frame.
    */
+  update(deltaTime: number): void;
+  /**
+   * Reads each binding once and applies accepted Arcball transforms in one session.
+   * Revalidates the cached frame after `start` and `change`; an isolated focus
+   * command ends immediately, while continuous input keeps the session open.
+   *
+   * @param deltaTime - Seconds elapsed for this input frame.
+   */
   protected onUpdate(deltaTime: number): void;
+  /**
+   * Removes gamepad listeners and ends only this wrapper's active interaction.
+   * Repeated calls are safe; the native Arcball instance is not disposed.
+   */
   dispose(): void;
+  /**
+   * Ends the owned interaction before forwarding the active gamepad's disconnection.
+   *
+   * @param gamepad - The gamepad that just disconnected.
+   */
   protected onGamepadDisconnected(gamepad: Gamepad): void;
 }
 //#endregion

package/dist/gamepad-arcball-controls.js

@@ -32,6 +32,8 @@ const ZOOM_NOTCHES_PER_SECOND = 8;
 * Call `update()` inside the render loop to poll gamepad input and apply
 * Arcball transformations. The wrapped `ArcballControls.update()` is only
 * needed after manual camera or target changes, matching Arcball's native API.
+* Gamepad `start`, `change`, and `end` events are dispatched on the native controls.
+* The balanced session belongs to this wrapper, including isolated focus commands.
 */
 var GamepadArcballControls = class extends GamepadControls {
 	#controls;
@@ -43,7 +45,12 @@ var GamepadArcballControls = class extends GamepadControls {
 	#cameraForward;
 	#cameraRight;
 	#previousUp;
+	/** Whether this wrapper owns an active gamepad interaction. */
 	#wasInteracting = false;
+	/** Blocks recursive updates while a frame is being processed. */
+	#updating = false;
+	/** Blocks recursive updates while the owned interaction is ending. */
+	#ending = false;
 	/**
 	* @param controls - A Three.js `ArcballControls` instance.
 	* @param options - Optional overrides for the default behavior.
@@ -67,64 +74,134 @@ var GamepadArcballControls = class extends GamepadControls {
 		this.#previousUp = new Vector3();
 	}
 	/**
-	* Maps the current gamepad state to `ArcballControls` rotation, pan, zoom,
-	* z-rotation, and center focus.
+	* Polls and applies gamepad input, ignoring updates from synchronous native listeners.
+	* Pausing through `enabled` retains the owned interaction until input resumes,
+	* the gamepad disconnects, or the wrapper is disposed.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	*/
+	update(deltaTime) {
+		if (this.#updating || this.#ending) return;
+		this.#updating = true;
+		try {
+			super.update(deltaTime);
+		} finally {
+			this.#updating = false;
+		}
+	}
+	/**
+	* Reads each binding once and applies accepted Arcball transforms in one session.
+	* Revalidates the cached frame after `start` and `change`; an isolated focus
+	* command ends immediately, while continuous input keeps the session open.
+	*
+	* @param deltaTime - Seconds elapsed for this input frame.
+	*/
 	onUpdate(deltaTime) {
-		const controls = this.#controls;
-		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 (!this.#canApplyInput()) return;
-		let rotateX = 0;
-		let rotateY = 0;
-		if (controls.enableRotate) {
-			const rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
-			rotateX = rotate.x;
-			rotateY = rotate.y;
-		}
-		let panX = 0;
-		let panY = 0;
-		if (controls.enablePan) {
-			const pan = input.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
-			panX = pan.x;
-			panY = pan.y;
-		}
-		const zoom = controls.enableZoom ? input.buttonValue(buttonZoomIn) - input.buttonValue(buttonZoomOut) : 0;
-		const zRotation = controls.enableRotate ? input.buttonValue(buttonZRotateLeft) - input.buttonValue(buttonZRotateRight) : 0;
-		const activeInput = rotateX !== 0 || rotateY !== 0 || panX !== 0 || panY !== 0 || Math.abs(zoom) > buttonDeadzone || Math.abs(zRotation) > buttonDeadzone;
-		if (!activeInput && focusPoint === null) {
-			this.#endInteraction();
-			return;
-		}
+		const { rotateStick, panStick, buttonZoomIn, buttonZoomOut, buttonZRotateLeft, buttonZRotateRight, buttonFocus } = this.#options;
+		const input = this.gamepadInput;
+		const rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
+		const pan = input.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
+		const frame = {
+			rotateX: rotate.x,
+			rotateY: rotate.y,
+			panX: pan.x,
+			panY: pan.y,
+			zoom: input.buttonValue(buttonZoomIn) - input.buttonValue(buttonZoomOut),
+			zRotation: input.buttonValue(buttonZRotateLeft) - input.buttonValue(buttonZRotateRight),
+			focus: this.#consumeFocusPoint(buttonFocus)
+		};
+		let actions = this.#acceptActions(frame, deltaTime);
+		if (actions === null) return;
+		const controls = this.#controls;
 		if (!this.#wasInteracting) {
 			this.#wasInteracting = true;
 			controls.dispatchEvent({ type: "start" });
+			actions = this.#acceptActions(frame, deltaTime);
+			if (actions === null) return;
 		}
-		if (!this.#canApplyInput()) return;
-		let changed = false;
-		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;
+		let changed = this.#applyRotation(actions.rotateX, actions.rotateY);
+		changed = this.#applyPan(actions.panX, actions.panY) || changed;
+		changed = this.#applyZoom(actions.zoomSize) || changed;
+		changed = this.#applyZRotation(actions.zRotation) || changed;
+		changed = this.#applyFocus(actions.focus) || changed;
 		if (changed) {
 			controls.update();
 			controls.updateMatrixState();
 			controls.dispatchEvent({ type: "change" });
 		}
-		if (!activeInput || !controls.enabled) this.#endInteraction();
+		actions = this.#acceptActions(frame, deltaTime);
+		if (actions !== null && !this.#hasContinuousInput(actions)) this.#endInteraction();
+	}
+	/**
+	* Resolves a cached frame against current permissions, gains, and zoom validity.
+	* Zero deltas and invalid or neutral zoom factors do not sustain an interaction.
+	* Ends the owned session when neither continuous input nor focus remains accepted.
+	*
+	* @param frame - Already processed input and the focus point resolved for this frame.
+	* @param delta - Frame duration in seconds.
+	* @returns Accepted deltas and focus, or `null` when input application must stop.
+	*/
+	#acceptActions(frame, delta) {
+		if (!this.#canApplyInput()) return null;
+		const controls = this.#controls;
+		const options = this.#options;
+		const rotate = controls.enableRotate ? controls.rotateSpeed * options.rotateSpeed * delta * Math.PI : 0;
+		const pan = controls.enablePan ? controls._tbRadius * options.panSpeed * delta : 0;
+		const zRotation = controls.enableRotate && Math.abs(frame.zRotation) > options.buttonDeadzone ? frame.zRotation * options.zRotateSpeed * delta * Math.PI : 0;
+		let zoomSize = 1;
+		if (controls.enableZoom && Math.abs(frame.zoom) > options.buttonDeadzone && controls.scaleFactor > 0) {
+			const size = controls.scaleFactor ** (frame.zoom * options.zoomSpeed * delta * ZOOM_NOTCHES_PER_SECOND);
+			if (Number.isFinite(size) && size > 0) zoomSize = size;
+		}
+		const actions = {
+			rotateX: frame.rotateX * rotate,
+			rotateY: frame.rotateY * rotate,
+			panX: frame.panX * pan,
+			panY: frame.panY * pan,
+			zoomSize,
+			zRotation,
+			focus: controls.enablePan && controls.enableFocus ? frame.focus : null
+		};
+		if (!this.#hasContinuousInput(actions) && actions.focus === null) {
+			this.#endInteraction();
+			return null;
+		}
+		return actions;
 	}
+	/**
+	* Checks whether accepted movement can sustain a session, excluding one-shot focus.
+	*
+	* @param actions - Frame deltas already resolved against current permissions and gains.
+	* @returns `true` when any rotation, pan, or zoom delta is non-neutral.
+	*/
+	#hasContinuousInput(actions) {
+		return actions.rotateX !== 0 || actions.rotateY !== 0 || actions.panX !== 0 || actions.panY !== 0 || actions.zoomSize !== 1 || actions.zRotation !== 0;
+	}
+	/**
+	* Removes gamepad listeners and ends only this wrapper's active interaction.
+	* Repeated calls are safe; the native Arcball instance is not disposed.
+	*/
 	dispose() {
 		super.dispose();
 		this.#endInteraction();
 	}
+	/**
+	* Ends the owned interaction before forwarding the active gamepad's disconnection.
+	*
+	* @param gamepad - The gamepad that just disconnected.
+	*/
 	onGamepadDisconnected(gamepad) {
 		this.#endInteraction();
 		super.onGamepadDisconnected(gamepad);
 	}
+	/**
+	* Checks whether input remains applicable after a synchronous native callback.
+	* Native disable ends the owned session; a wrapper pause retains it until resume,
+	* disconnection, or disposal.
+	*
+	* @returns `true` when the wrapper and native controls are enabled and a gamepad is available.
+	*/
 	#canApplyInput() {
 		if (!this.#controls.enabled) {
 			this.#endInteraction();
@@ -133,27 +210,23 @@ var GamepadArcballControls = class extends GamepadControls {
 		return this.enabled && this.gamepad !== null;
 	}
 	/**
-	* Applies gamepad stick rotation through Arcball's runtime rotation helper.
+	* Applies accepted angular deltas through native rotation helpers.
 	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param rotateX - Horizontal rotation input after dead zone processing.
-	* @param rotateY - Vertical rotation input after dead zone processing.
-	* @param rotateSpeed - User-configured rotation speed multiplier.
-	* @returns `true` when a rotation was applied.
+	* @param rotateX - Horizontal rotation delta in radians.
+	* @param rotateY - Vertical rotation delta in radians.
+	* @returns `true` when at least one rotation transform was applied.
 	*/
-	#applyRotation(deltaTime, rotateX, rotateY, rotateSpeed) {
-		if (rotateX === 0 && rotateY === 0) return false;
+	#applyRotation(rotateX, rotateY) {
 		const controls = this.#controls;
-		const amount = controls.rotateSpeed * rotateSpeed * deltaTime * Math.PI;
 		let changed = false;
 		if (rotateX !== 0) {
 			this.#rotationAxis.copy(controls.object.up).normalize();
-			changed = this.#applyRotationAroundAxis(this.#rotationAxis, rotateX * amount) || changed;
+			changed = this.#applyRotationAroundAxis(this.#rotationAxis, rotateX);
 		}
 		if (rotateY !== 0) {
 			controls.object.getWorldDirection(this.#cameraForward);
 			this.#cameraRight.crossVectors(this.#cameraForward, controls.object.up).normalize();
-			changed = this.#applyRotationAroundAxis(this.#cameraRight, -rotateY * amount) || changed;
+			changed = this.#applyRotationAroundAxis(this.#cameraRight, -rotateY) || changed;
 		}
 		return changed;
 	}
@@ -174,38 +247,30 @@ var GamepadArcballControls = class extends GamepadControls {
 		return true;
 	}
 	/**
-	* Applies gamepad pan by converting stick input to Arcball trackball points.
+	* Applies accepted pan deltas between two virtual trackball points.
 	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param panX - Horizontal pan input after dead zone processing.
-	* @param panY - Vertical pan input after dead zone processing.
-	* @param panSpeed - User-configured pan speed multiplier.
-	* @returns `true` when a pan transform was applied.
+	* @param panX - Horizontal displacement in Arcball's virtual trackball space.
+	* @param panY - Vertical displacement in Arcball's virtual trackball space.
+	* @returns `true` when a nonzero pan transform was applied.
 	*/
-	#applyPan(deltaTime, panX, panY, panSpeed) {
+	#applyPan(panX, panY) {
 		if (panX === 0 && panY === 0) return false;
 		const controls = this.#controls;
-		const distance = controls._tbRadius * panSpeed * deltaTime;
 		controls.updateMatrixState();
 		this.#panStart.set(0, 0, 0);
-		this.#panEnd.set(panX * distance, panY * distance, 0);
+		this.#panEnd.set(panX, panY, 0);
 		this.#applyTransform(controls.pan(this.#panStart, this.#panEnd));
 		return true;
 	}
 	/**
-	* Applies trigger-driven zoom around Arcball's gizmo center.
+	* Applies an accepted zoom factor around the native gizmo center.
 	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param zoom - Signed zoom input from the configured trigger pair.
-	* @param zoomSpeed - User-configured zoom speed multiplier.
-	* @param buttonDeadzone - Trigger dead zone threshold.
-	* @returns `true` when a zoom transform was applied.
+	* @param size - Positive finite scale factor; `1` leaves zoom unchanged.
+	* @returns `true` when the factor is non-neutral and the native helper returns a transform.
 	*/
-	#applyZoom(deltaTime, zoom, zoomSpeed, buttonDeadzone) {
-		if (Math.abs(zoom) <= buttonDeadzone || this.#controls.scaleFactor <= 0) return false;
+	#applyZoom(size) {
+		if (size === 1) return false;
 		const controls = this.#controls;
-		const size = controls.scaleFactor ** (zoom * zoomSpeed * deltaTime * ZOOM_NOTCHES_PER_SECOND);
-		if (!Number.isFinite(size) || size <= 0 || size === 1) return false;
 		controls.updateMatrixState();
 		const transformation = controls.scale(size, controls._gizmos.position);
 		if (transformation === void 0) return false;
@@ -213,18 +278,14 @@ var GamepadArcballControls = class extends GamepadControls {
 		return true;
 	}
 	/**
-	* Applies shoulder-button rotation around the current camera view axis.
+	* Applies accepted rotation around the view axis and updates the camera's up vector.
 	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param zRotation - Signed z-rotation input from the configured buttons.
-	* @param zRotateSpeed - User-configured z-rotation speed multiplier.
-	* @param buttonDeadzone - Button value dead zone threshold.
-	* @returns `true` when a z-rotation transform was applied.
+	* @param angle - Rotation delta in radians.
+	* @returns `true` when a nonzero rotation transform was applied.
 	*/
-	#applyZRotation(deltaTime, zRotation, zRotateSpeed, buttonDeadzone) {
-		if (Math.abs(zRotation) <= buttonDeadzone) return false;
+	#applyZRotation(angle) {
+		if (angle === 0) return false;
 		const controls = this.#controls;
-		const angle = zRotation * zRotateSpeed * deltaTime * Math.PI;
 		controls.updateMatrixState();
 		controls.object.getWorldDirection(controls._rotationAxis);
 		this.#previousUp.copy(controls.object.up);
@@ -266,10 +327,19 @@ var GamepadArcballControls = class extends GamepadControls {
 		if (!this.gamepadInput.wasPressed(buttonFocus) || !controls.enabled || !controls.enablePan || !controls.enableFocus || controls.scene === null) return null;
 		return controls.unprojectOnObj(this.#centerNdc, controls.object);
 	}
+	/**
+	* Releases session ownership before dispatching the native `end` event once.
+	* Blocks recursive updates during finalization, including disconnection and disposal.
+	*/
 	#endInteraction() {
 		if (!this.#wasInteracting) return;
 		this.#wasInteracting = false;
-		this.#controls.dispatchEvent({ type: "end" });
+		this.#ending = true;
+		try {
+			this.#controls.dispatchEvent({ type: "end" });
+		} finally {
+			this.#ending = false;
+		}
 	}
 };
 //#endregion

package/dist/gamepad-controls.js

@@ -63,7 +63,7 @@ var GamepadControls = class extends EventDispatcher {
 	*/
 	#handleGamepadConnected(event) {
 		this.gamepad = this.#gamepadInput.gamepad;
-		this.onGamepadConnected(event.gamepad);
+		this.onGamepadConnected(event.detail.gamepad);
 	}
 	/**
 	* Forwards an input disconnection event to the overridable lifecycle hook.
@@ -72,7 +72,7 @@ var GamepadControls = class extends EventDispatcher {
 	*/
 	#handleGamepadDisconnected(event) {
 		this.gamepad = this.#gamepadInput.gamepad;
-		this.onGamepadDisconnected(event.gamepad);
+		this.onGamepadDisconnected(event.detail.gamepad);
 	}
 	/**
 	* Advances the controller by one frame. Call this inside your render loop.

package/dist/gamepad-input.d.ts

@@ -1,30 +1,33 @@
 import { GamepadStick, GamepadStickPipeline } from "./gamepad-stick-processing.js";
-import { EventDispatcher } from "three";
 //#region src/gamepad-input.d.ts
 /**
- * Event map for {@link GamepadInput}.
+ * Native custom event map for {@link GamepadInput}.
+ * Gamepad snapshots are available through `event.detail.gamepad`.
  */
 export type GamepadInputEventMap = {
   /**
    * Fired when a gamepad is connected and becomes active.
    */
-  connected: {
+  connected: CustomEvent<{
     /**
      * Gamepad snapshot that became active.
      */
     gamepad: Gamepad;
-  };
+  }>;
   /**
    * 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: {
+  disconnected: CustomEvent<{
     /**
      * Gamepad snapshot that was active before disconnection.
      */
     gamepad: Gamepad;
-  };
+  }>;
+};
+type GamepadInputEventListener<K extends keyof GamepadInputEventMap> = ((this: GamepadInput, event: GamepadInputEventMap[K]) => void) | {
+  handleEvent(event: GamepadInputEventMap[K]): void;
 };
 /**
  * Configuration for {@link GamepadInput}.
@@ -66,8 +69,13 @@ export type GamepadAxisOptions = {
  * Gamepad input state reader for gameplay, menus, and custom actions.
  *
  * Call {@link update} once per frame before reading button transitions or axes.
+ * Connection notifications are synchronous native `CustomEvent` objects with
+ * the gamepad snapshot in `event.detail.gamepad`. Input state is updated before
+ * listeners run. Inherited `dispatchEvent()` requires an `Event` instance;
+ * listener exceptions are reported by the browser instead of propagating to
+ * the dispatch caller.
  */
-export declare class GamepadInput extends EventDispatcher<GamepadInputEventMap> {
+export declare class GamepadInput extends EventTarget {
   #private;
   /**
    * When `false`, polling through `update()` is paused and the last observed
@@ -84,6 +92,67 @@ export declare class GamepadInput extends EventDispatcher<GamepadInputEventMap>
    * `MIN_GAMEPAD_INDEX` through `MAX_GAMEPAD_INDEX`.
    */
   constructor(options?: Partial<GamepadInputOptions>);
+  /**
+   * Adds a native event listener with typed connection event details.
+   *
+   * Connection callbacks receive a `CustomEvent` with `detail.gamepad`.
+   * Supports callback functions and objects with `handleEvent`. Registering
+   * the same event type, listener, and capture flag again does not duplicate it.
+   * A regular callback's `this` is this input; a listener object's `this` is
+   * the listener object. Manage subscriptions separately from {@link dispose}.
+   *
+   * @param type - Event name to observe.
+   * @param listener - Callback or listener object, or `null` for a no-op.
+   * @param options - Capture flag (default `false`) or native options including
+   * `capture`, `once`, `passive`, and `signal`.
+   * @example
+   * ```ts
+   * const subscriptions = new AbortController();
+   * input.addEventListener("connected", (event) => {
+   *   console.log(event.detail.gamepad.id);
+   * }, { signal: subscriptions.signal });
+   * subscriptions.abort();
+   * ```
+   */
+  addEventListener<K extends keyof GamepadInputEventMap>(type: K, listener: GamepadInputEventListener<K> | null, options?: boolean | AddEventListenerOptions): void;
+  /**
+   * Adds a listener using standard `EventTarget` types for any event name.
+   *
+   * @param type - Event name to observe.
+   * @param listener - Native callback or listener object, or `null` for a no-op.
+   * @param options - Capture flag or native event listener options.
+   */
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+  /**
+   * Removes a native event listener with the matching capture option.
+   *
+   * The event type, callback or object identity, and capture flag must match
+   * registration. Other registration options do not affect removal. A missing
+   * listener or `null` is a no-op. Removal during dispatch prevents a pending
+   * invocation of that listener.
+   *
+   * @param type - Event name being observed.
+   * @param listener - Previously registered callback or listener object, or `null`.
+   * @param options - Capture flag (default `false`) or an object with `capture`.
+   * @example
+   * ```ts
+   * const onConnected = (event: GamepadInputEventMap["connected"]) => {
+   *   console.log(event.detail.gamepad.id);
+   * };
+   * input.addEventListener("connected", onConnected);
+   * input.removeEventListener("connected", onConnected);
+   * ```
+   */
+  removeEventListener<K extends keyof GamepadInputEventMap>(type: K, listener: GamepadInputEventListener<K> | null, options?: boolean | EventListenerOptions): void;
+  /**
+   * Removes a listener using standard `EventTarget` types for any event name.
+   *
+   * @param type - Event name being observed.
+   * @param listener - Previously registered native callback or listener object,
+   * or `null` for a no-op.
+   * @param options - Capture flag or an object with the matching `capture` flag.
+   */
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
   /**
    * The currently active gamepad, or `null` if no gamepad is connected.
    *

package/dist/gamepad-input.js

@@ -1,7 +1,6 @@
 import { isGamepadVibrationSupported, playGamepadVibrationEffect, resetGamepadVibration } from "./gamepad-haptics.js";
 import { GamepadManager } from "./gamepad-manager.js";
 import { DEFAULT_GAMEPAD_STICK_PIPELINE } from "./gamepad-stick-processing.js";
-import { EventDispatcher } from "three";
 //#region src/gamepad-input.ts
 const DEFAULT_GAMEPAD_INPUT_OPTIONS = {
 	axisDeadzone: .1,
@@ -49,8 +48,13 @@ const getGamepadButtonValue = (gamepad, button) => {
 * Gamepad input state reader for gameplay, menus, and custom actions.
 *
 * Call {@link update} once per frame before reading button transitions or axes.
+* Connection notifications are synchronous native `CustomEvent` objects with
+* the gamepad snapshot in `event.detail.gamepad`. Input state is updated before
+* listeners run. Inherited `dispatchEvent()` requires an `Event` instance;
+* listener exceptions are reported by the browser instead of propagating to
+* the dispatch caller.
 */
-var GamepadInput = class extends EventDispatcher {
+var GamepadInput = class extends EventTarget {
 	/**
 	* When `false`, polling through `update()` is paused and the last observed
 	* state, including button transitions, is retained. Browser listeners remain
@@ -86,6 +90,12 @@ var GamepadInput = class extends EventDispatcher {
 		window.addEventListener("gamepadconnected", this.#onGamepadConnected);
 		window.addEventListener("gamepaddisconnected", this.#onGamepadDisconnected);
 	}
+	addEventListener(type, listener, options) {
+		super.addEventListener(type, listener, options);
+	}
+	removeEventListener(type, listener, options) {
+		super.removeEventListener(type, listener, options);
+	}
 	/**
 	* Forwards a browser connection event to the active-gamepad adoption logic.
 	*
@@ -156,19 +166,13 @@ var GamepadInput = class extends EventDispatcher {
 		if (connected !== null) {
 			this.#gamepad = gamepad;
 			this.#syncButtonState({ seedPrevious: true });
-			this.dispatchEvent({
-				type: "connected",
-				gamepad: connected
-			});
+			this.dispatchEvent(new CustomEvent("connected", { detail: { gamepad: connected } }));
 			return;
 		}
 		if (disconnected !== null) {
 			this.#gamepad = null;
 			this.#clearButtonState();
-			this.dispatchEvent({
-				type: "disconnected",
-				gamepad: disconnected
-			});
+			this.dispatchEvent(new CustomEvent("disconnected", { detail: { gamepad: disconnected } }));
 			return;
 		}
 		this.#gamepad = gamepad;
@@ -291,10 +295,7 @@ var GamepadInput = class extends EventDispatcher {
 		if (connectedGamepad === null) return;
 		this.#gamepad = connectedGamepad;
 		this.#syncButtonState({ seedPrevious: true });
-		this.dispatchEvent({
-			type: "connected",
-			gamepad: connectedGamepad
-		});
+		this.dispatchEvent(new CustomEvent("connected", { detail: { gamepad: connectedGamepad } }));
 	}
 	/**
 	* Handles a browser disconnection event for the active gamepad.
@@ -309,10 +310,7 @@ var GamepadInput = class extends EventDispatcher {
 		if (disconnectedGamepad === null) return;
 		this.#gamepad = null;
 		this.#clearButtonState();
-		this.dispatchEvent({
-			type: "disconnected",
-			gamepad: disconnectedGamepad
-		});
+		this.dispatchEvent(new CustomEvent("disconnected", { detail: { gamepad: disconnectedGamepad } }));
 	}
 	/**
 	* Refreshes current and previous pressed-button sets from the active snapshot.

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

@@ -8,6 +8,8 @@ import { MapControls } from "three/addons/controls/MapControls.js";
  * mouse conventions. All options from {@link GamepadOrbitControlsOptions} are available.
  *
  * Call `update()` inside the render loop **before** `MapControls.update()`.
+ * Gamepad interaction events, pause semantics, and combined native/wrapper speeds
+ * are inherited from {@link GamepadOrbitControls}.
  */
 export declare class GamepadMapControls extends GamepadOrbitControls {
   /**

package/dist/gamepad-map-controls.js

@@ -18,6 +18,8 @@ const DEFAULT_MAP_OPTIONS = {
 * mouse conventions. All options from {@link GamepadOrbitControlsOptions} are available.
 *
 * Call `update()` inside the render loop **before** `MapControls.update()`.
+* Gamepad interaction events, pause semantics, and combined native/wrapper speeds
+* are inherited from {@link GamepadOrbitControls}.
 */
 var GamepadMapControls = class extends GamepadOrbitControls {
 	/**

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

@@ -9,17 +9,17 @@ import { OrbitControls } from "three/addons/controls/OrbitControls.js";
  */
 export type GamepadOrbitControlsOptions = GamepadControlsOptions & {
   /**
-   * Multiplier on orbit rotation speed.
+   * Multiplier on `OrbitControls.rotateSpeed`.
    * @default 1.0
    */
   rotateSpeed: number;
   /**
-   * Multiplier on pan speed.
+   * Multiplier on `OrbitControls.panSpeed`.
    * @default 1.0
    */
   panSpeed: number;
   /**
-   * Multiplier on zoom (dolly) speed.
+   * Multiplier on `OrbitControls.zoomSpeed`.
    * @default 1.0
    */
   zoomSpeed: number;
@@ -34,7 +34,7 @@ export type GamepadOrbitControlsOptions = GamepadControlsOptions & {
    */
   panStick: GamepadStickBindingOptions;
   /**
-   * Dead zone threshold for analog trigger values.
+   * Each analog trigger must be strictly above this threshold to drive dolly.
    * @default 0.1
    */
   buttonDeadzone: number;
@@ -54,6 +54,8 @@ export type GamepadOrbitControlsOptions = GamepadControlsOptions & {
  *
  * Call `update()` inside the render loop **before** `OrbitControls.update()`.
  * Bindings and speeds are configurable via {@link GamepadOrbitControlsOptions}.
+ * The wrapper dispatches balanced gamepad `start` and `end` events on the native
+ * controls; native operations and damping remain responsible for `change`.
  */
 export declare class GamepadOrbitControls extends GamepadControls {
   #private;
@@ -64,10 +66,30 @@ export declare class GamepadOrbitControls extends GamepadControls {
    */
   constructor(controls: OrbitControls, options?: Partial<GamepadOrbitControlsOptions>);
   /**
-   * Maps the current gamepad state to `OrbitControls` rotation, pan, and dolly.
+   * Polls the gamepad and applies input, ignoring updates from synchronous listeners.
+   * Pausing through `enabled` retains the owned interaction until input resumes,
+   * the gamepad disconnects, or the wrapper is disposed.
    *
    * @param deltaTime - Seconds since the last frame.
    */
+  update(deltaTime: number): void;
+  /**
+   * Reads each binding once, manages the gamepad session, and applies native operations.
+   * Revalidates the cached frame after synchronous events can change permissions.
+   *
+   * @param deltaTime - Seconds elapsed for this input frame.
+   */
   protected onUpdate(deltaTime: number): void;
+  /**
+   * Removes gamepad listeners and ends only this wrapper's active interaction.
+   * Repeated calls are safe; the native controls and their damping are preserved.
+   */
+  dispose(): void;
+  /**
+   * Ends the owned interaction before forwarding the active gamepad's disconnection.
+   *
+   * @param gamepad - The gamepad that just disconnected.
+   */
+  protected onGamepadDisconnected(gamepad: Gamepad): void;
 }
 //#endregion

package/dist/gamepad-orbit-controls.js

@@ -25,10 +25,18 @@ const DEFAULT_ORBIT_OPTIONS = {
 *
 * Call `update()` inside the render loop **before** `OrbitControls.update()`.
 * Bindings and speeds are configurable via {@link GamepadOrbitControlsOptions}.
+* The wrapper dispatches balanced gamepad `start` and `end` events on the native
+* controls; native operations and damping remain responsible for `change`.
 */
 var GamepadOrbitControls = class extends GamepadControls {
 	#controls;
 	#options;
+	/** Whether this wrapper owns an active gamepad interaction. */
+	#interacting = false;
+	/** Blocks recursive updates while a frame is being processed. */
+	#updating = false;
+	/** Blocks recursive updates while the owned interaction is ending. */
+	#ending = false;
 	/**
 	* @param controls - A Three.js `OrbitControls` instance.
 	* @param options - Optional overrides for the default behavior.
@@ -45,39 +53,143 @@ var GamepadOrbitControls = class extends GamepadControls {
 		};
 	}
 	/**
-	* Maps the current gamepad state to `OrbitControls` rotation, pan, and dolly.
+	* Polls the gamepad and applies input, ignoring updates from synchronous listeners.
+	* Pausing through `enabled` retains the owned interaction until input resumes,
+	* the gamepad disconnects, or the wrapper is disposed.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	*/
+	update(deltaTime) {
+		if (this.#updating || this.#ending) return;
+		this.#updating = true;
+		try {
+			super.update(deltaTime);
+		} finally {
+			this.#updating = false;
+		}
+	}
+	/**
+	* Reads each binding once, manages the gamepad session, and applies native operations.
+	* Revalidates the cached frame after synchronous events can change permissions.
+	*
+	* @param deltaTime - Seconds elapsed for this input frame.
+	*/
 	onUpdate(deltaTime) {
-		if (!this.#canApplyInput()) return;
-		const controls = this.#controls;
-		const { rotateSpeed, panSpeed, zoomSpeed, rotateStick, panStick, buttonDeadzone, buttonDollyIn, buttonDollyOut } = this.#options;
+		if (!this.#controls.enabled) {
+			this.#endInteraction();
+			return;
+		}
+		const { rotateStick, panStick, buttonDeadzone, buttonDollyIn, buttonDollyOut } = this.#options;
 		const input = this.gamepadInput;
 		const rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
-		if (controls.enableRotate && rotate.x !== 0) {
-			controls.rotateLeft(rotate.x * rotateSpeed * deltaTime * Math.PI);
-			if (!this.#canApplyInput()) return;
-		}
-		if (controls.enableRotate && rotate.y !== 0) {
-			controls.rotateUp(rotate.y * rotateSpeed * deltaTime * Math.PI);
-			if (!this.#canApplyInput()) return;
-		}
 		const pan = input.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
-		if (controls.enablePan && (pan.x !== 0 || pan.y !== 0)) {
-			controls.pan(pan.x * panSpeed * deltaTime * 500, pan.y * panSpeed * deltaTime * 500);
-			if (!this.#canApplyInput()) return;
-		}
 		const triggerIn = input.buttonValue(buttonDollyIn);
 		const triggerOut = input.buttonValue(buttonDollyOut);
-		if (controls.enableZoom && triggerIn > buttonDeadzone) {
-			controls.dollyIn(1 / (1 + zoomSpeed * triggerIn * deltaTime));
-			if (!this.#canApplyInput()) return;
+		const frame = {
+			rotateX: rotate.x,
+			rotateY: rotate.y,
+			panX: pan.x,
+			panY: pan.y,
+			dollyIn: triggerIn > buttonDeadzone ? triggerIn : 0,
+			dollyOut: triggerOut > buttonDeadzone ? triggerOut : 0
+		};
+		let actions = this.#acceptActions(frame, deltaTime);
+		if (actions === null) return;
+		if (!this.#interacting) {
+			this.#interacting = true;
+			this.#controls.dispatchEvent({ type: "start" });
+			actions = this.#acceptActions(frame, deltaTime);
+			if (actions === null) return;
+		}
+		const controls = this.#controls;
+		if (actions.rotateX !== 0) {
+			controls.rotateLeft(actions.rotateX);
+			actions = this.#acceptActions(frame, deltaTime);
+			if (actions === null) return;
+		}
+		if (actions.rotateY !== 0) {
+			controls.rotateUp(actions.rotateY);
+			actions = this.#acceptActions(frame, deltaTime);
+			if (actions === null) return;
+		}
+		if (actions.panX !== 0 || actions.panY !== 0) {
+			controls.pan(actions.panX, actions.panY);
+			actions = this.#acceptActions(frame, deltaTime);
+			if (actions === null) return;
+		}
+		if (actions.dollyIn !== 0) {
+			controls.dollyIn(1 / (1 + actions.dollyIn));
+			actions = this.#acceptActions(frame, deltaTime);
+			if (actions === null) return;
+		}
+		if (actions.dollyOut !== 0) {
+			controls.dollyOut(1 / (1 + actions.dollyOut));
+			this.#acceptActions(frame, deltaTime);
 		}
-		if (controls.enableZoom && triggerOut > buttonDeadzone) controls.dollyOut(1 / (1 + zoomSpeed * triggerOut * deltaTime));
 	}
-	#canApplyInput() {
-		return this.enabled && this.#controls.enabled && this.gamepad !== null;
+	/**
+	* Removes gamepad listeners and ends only this wrapper's active interaction.
+	* Repeated calls are safe; the native controls and their damping are preserved.
+	*/
+	dispose() {
+		super.dispose();
+		this.#endInteraction();
+	}
+	/**
+	* Ends the owned interaction before forwarding the active gamepad's disconnection.
+	*
+	* @param gamepad - The gamepad that just disconnected.
+	*/
+	onGamepadDisconnected(gamepad) {
+		this.#endInteraction();
+		super.onGamepadDisconnected(gamepad);
+	}
+	/**
+	* Resolves a cached frame against current permissions and native/wrapper speeds.
+	* Native disable or lack of actionable input ends the owned session; a wrapper
+	* pause stops application while retaining it. Geometric limits do not erase intent.
+	*
+	* @param input - Already processed sticks and filtered triggers for this frame.
+	* @param delta - Frame duration in seconds.
+	* @returns Accepted frame deltas, or `null` when input application must stop.
+	*/
+	#acceptActions(input, delta) {
+		const controls = this.#controls;
+		if (!controls.enabled) {
+			this.#endInteraction();
+			return null;
+		}
+		if (!this.enabled || this.gamepad === null) return null;
+		const rotate = controls.enableRotate ? controls.rotateSpeed * this.#options.rotateSpeed * delta * Math.PI : 0;
+		const pan = controls.enablePan ? controls.panSpeed * this.#options.panSpeed * delta * 500 : 0;
+		const zoom = controls.enableZoom ? controls.zoomSpeed * this.#options.zoomSpeed * delta : 0;
+		const actions = {
+			rotateX: input.rotateX * rotate,
+			rotateY: input.rotateY * rotate,
+			panX: input.panX * pan,
+			panY: input.panY * pan,
+			dollyIn: input.dollyIn * zoom,
+			dollyOut: input.dollyOut * zoom
+		};
+		if (!Object.values(actions).some((value) => value !== 0)) {
+			this.#endInteraction();
+			return null;
+		}
+		return actions;
+	}
+	/**
+	* Releases session ownership before dispatching the native `end` event once.
+	* Blocks recursive updates during finalization without clearing native input or damping.
+	*/
+	#endInteraction() {
+		if (!this.#interacting) return;
+		this.#interacting = false;
+		this.#ending = true;
+		try {
+			this.#controls.dispatchEvent({ type: "end" });
+		} finally {
+			this.#ending = false;
+		}
 	}
 };
 //#endregion

package/dist/gamepad-pointer-lock-controls.d.ts

@@ -35,6 +35,8 @@ export type GamepadPointerLockControlsOptions = GamepadControlsOptions & {
  * Gamepad input is fully independent of pointer lock state. When the pointer
  * IS locked, mouse and gamepad look inputs are additive.
  * Bindings and speeds are configurable via {@link GamepadPointerLockControlsOptions}.
+ * Look dispatches `change` on the native controls after an actual orientation
+ * change; movement does not dispatch it or alter pointer lock state.
  */
 export declare class GamepadPointerLockControls extends GamepadControls {
   #private;
@@ -44,8 +46,19 @@ export declare class GamepadPointerLockControls extends GamepadControls {
    *                  Any property not provided falls back to its default value.
    */
   constructor(controls: PointerLockControls, options?: Partial<GamepadPointerLockControlsOptions>);
+  /**
+   * Polls and applies movement and look, ignoring updates from synchronous listeners.
+   * Gamepad input remains independent of the native pointer lock state.
+   *
+   * @param deltaTime - Seconds since the last frame.
+   */
+  update(deltaTime: number): void;
   /**
    * Maps the current gamepad state to `PointerLockControls` movement and look.
+   * Dispatches at most one native `change` after look changes orientation by more
+   * than `1e-7` radians, treating opposite quaternion signs as equivalent.
+   * Translation, zero look gain, and pitch-only input held at a clamp do not
+   * dispatch `change`; permitted yaw can still change orientation at a pitch limit.
    *
    * @param deltaTime - Seconds since the last frame.
    */

package/dist/gamepad-pointer-lock-controls.js

@@ -1,7 +1,7 @@
 import { GAMEPAD_AXIS } from "./core.js";
 import { DEFAULT_GAMEPAD_STICK_PIPELINE, resolveGamepadStickBinding } from "./gamepad-stick-processing.js";
 import { GamepadControls } from "./gamepad-controls.js";
-import { Euler } from "three";
+import { Euler, Quaternion } from "three";
 //#region src/gamepad-pointer-lock-controls.ts
 const DEFAULT_POINTER_LOCK_OPTIONS = {
 	moveSpeed: 5,
@@ -23,11 +23,17 @@ const DEFAULT_POINTER_LOCK_OPTIONS = {
 * Gamepad input is fully independent of pointer lock state. When the pointer
 * IS locked, mouse and gamepad look inputs are additive.
 * Bindings and speeds are configurable via {@link GamepadPointerLockControlsOptions}.
+* Look dispatches `change` on the native controls after an actual orientation
+* change; movement does not dispatch it or alter pointer lock state.
 */
 var GamepadPointerLockControls = class extends GamepadControls {
 	#controls;
 	#options;
 	#euler;
+	/** Reusable orientation snapshot for sign-independent angular change detection. */
+	#previousQuaternion = new Quaternion();
+	/** Blocks recursive input application from native `change` listeners. */
+	#updating = false;
 	/**
 	* @param controls - A Three.js `PointerLockControls` instance.
 	* @param options - Optional overrides for the default behavior.
@@ -45,7 +51,26 @@ var GamepadPointerLockControls = class extends GamepadControls {
 		this.#euler = new Euler(0, 0, 0, "YXZ");
 	}
 	/**
+	* Polls and applies movement and look, ignoring updates from synchronous listeners.
+	* Gamepad input remains independent of the native pointer lock state.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	*/
+	update(deltaTime) {
+		if (this.#updating) return;
+		this.#updating = true;
+		try {
+			super.update(deltaTime);
+		} finally {
+			this.#updating = false;
+		}
+	}
+	/**
 	* Maps the current gamepad state to `PointerLockControls` movement and look.
+	* Dispatches at most one native `change` after look changes orientation by more
+	* than `1e-7` radians, treating opposite quaternion signs as equivalent.
+	* Translation, zero look gain, and pitch-only input held at a clamp do not
+	* dispatch `change`; permitted yaw can still change orientation at a pitch limit.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	*/
@@ -57,14 +82,16 @@ var GamepadPointerLockControls = class extends GamepadControls {
 		if (move.y !== 0) this.#controls.moveForward(-move.y * moveSpeed * deltaTime);
 		if (move.x !== 0) this.#controls.moveRight(move.x * moveSpeed * deltaTime);
 		const look = input.stick(lookStick.xAxis, lookStick.yAxis, lookStick.pipeline);
-		if (look.x !== 0 || look.y !== 0) {
+		const scale = lookSpeed * this.#controls.pointerSpeed * deltaTime * Math.PI;
+		if ((look.x !== 0 || look.y !== 0) && scale !== 0) {
 			const camera = this.#controls.object;
-			const scale = lookSpeed * this.#controls.pointerSpeed * deltaTime * Math.PI;
+			this.#previousQuaternion.copy(camera.quaternion);
 			this.#euler.setFromQuaternion(camera.quaternion);
 			this.#euler.y -= look.x * scale;
 			this.#euler.x -= look.y * scale;
 			this.#euler.x = Math.max(Math.PI / 2 - this.#controls.maxPolarAngle, Math.min(Math.PI / 2 - this.#controls.minPolarAngle, this.#euler.x));
 			camera.quaternion.setFromEuler(this.#euler);
+			if (this.#previousQuaternion.angleTo(camera.quaternion) > 1e-7) this.#controls.dispatchEvent({ type: "change" });
 		}
 	}
 };

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

@@ -34,7 +34,7 @@ export type GamepadTrackballControlsOptions = GamepadControlsOptions & {
    */
   panStick: GamepadStickBindingOptions;
   /**
-   * Dead zone threshold for analog trigger values.
+   * Each analog trigger must be strictly above this threshold before subtraction.
    * @default 0.1
    */
   buttonDeadzone: number;
@@ -54,6 +54,8 @@ export type GamepadTrackballControlsOptions = GamepadControlsOptions & {
  *
  * Call `update()` inside the render loop **before** `TrackballControls.update()`.
  * Bindings and speed multipliers are configurable via {@link GamepadTrackballControlsOptions}.
+ * The wrapper dispatches balanced gamepad `start` and `end` events on the native
+ * controls; the native update applies speeds and damping and dispatches `change`.
  */
 export declare class GamepadTrackballControls extends GamepadControls {
   #private;
@@ -64,10 +66,30 @@ export declare class GamepadTrackballControls extends GamepadControls {
    */
   constructor(controls: TrackballControls, options?: Partial<GamepadTrackballControlsOptions>);
   /**
-   * Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
+   * Polls the gamepad and queues input, ignoring updates from synchronous listeners.
+   * Pausing through `enabled` retains the owned interaction until input resumes,
+   * the gamepad disconnects, or the wrapper is disposed.
    *
    * @param deltaTime - Seconds since the last frame.
    */
+  update(deltaTime: number): void;
+  /**
+   * Reads each binding once, manages the gamepad session, and adds accepted deltas
+   * to native pointer vectors. Revalidates permissions after the `start` event.
+   *
+   * @param deltaTime - Seconds elapsed for this input frame.
+   */
   protected onUpdate(deltaTime: number): void;
+  /**
+   * Removes gamepad listeners and ends only this wrapper's active interaction.
+   * Repeated calls are safe; native pointer vectors and damping are preserved.
+   */
+  dispose(): void;
+  /**
+   * Ends the owned interaction before forwarding the active gamepad's disconnection.
+   *
+   * @param gamepad - The gamepad that just disconnected.
+   */
+  protected onGamepadDisconnected(gamepad: Gamepad): void;
 }
 //#endregion

package/dist/gamepad-trackball-controls.js

@@ -25,10 +25,18 @@ const DEFAULT_TRACKBALL_OPTIONS = {
 *
 * Call `update()` inside the render loop **before** `TrackballControls.update()`.
 * Bindings and speed multipliers are configurable via {@link GamepadTrackballControlsOptions}.
+* The wrapper dispatches balanced gamepad `start` and `end` events on the native
+* controls; the native update applies speeds and damping and dispatches `change`.
 */
 var GamepadTrackballControls = class extends GamepadControls {
 	#controls;
 	#options;
+	/** Whether this wrapper owns an active gamepad interaction. */
+	#interacting = false;
+	/** Blocks recursive updates while a frame is being processed. */
+	#updating = false;
+	/** Blocks recursive updates while the owned interaction is ending. */
+	#ending = false;
 	/**
 	* @param controls - A Three.js `TrackballControls` instance.
 	* @param options - Optional overrides for the default behavior.
@@ -45,76 +53,125 @@ var GamepadTrackballControls = class extends GamepadControls {
 		};
 	}
 	/**
-	* Maps the current gamepad state to `TrackballControls` rotation, pan, and zoom.
+	* Polls the gamepad and queues input, ignoring updates from synchronous listeners.
+	* Pausing through `enabled` retains the owned interaction until input resumes,
+	* the gamepad disconnects, or the wrapper is disposed.
 	*
 	* @param deltaTime - Seconds since the last frame.
 	*/
-	onUpdate(deltaTime) {
-		if (!this.#controls.enabled) return;
-		const { rotateSpeed, panSpeed, zoomSpeed, rotateStick, panStick, buttonDeadzone, buttonZoomIn, buttonZoomOut } = this.#options;
-		this.#queueRotation(deltaTime, rotateSpeed, rotateStick);
-		this.#queuePan(deltaTime, panSpeed, panStick);
-		this.#queueZoom(deltaTime, zoomSpeed, buttonDeadzone, buttonZoomIn, buttonZoomOut);
+	update(deltaTime) {
+		if (this.#updating || this.#ending) return;
+		this.#updating = true;
+		try {
+			super.update(deltaTime);
+		} finally {
+			this.#updating = false;
+		}
 	}
 	/**
-	* Queues rotation input into TrackballControls' normalized move state.
+	* Reads each binding once, manages the gamepad session, and adds accepted deltas
+	* to native pointer vectors. Revalidates permissions after the `start` event.
 	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param rotateSpeed - User-configured rotation speed multiplier.
-	* @param rotateStick - Resolved stick binding for rotation.
+	* @param deltaTime - Seconds elapsed for this input frame.
 	*/
-	#queueRotation(deltaTime, rotateSpeed, rotateStick) {
+	onUpdate(deltaTime) {
+		if (!this.#controls.enabled) {
+			this.#endInteraction();
+			return;
+		}
+		const { rotateStick, panStick, buttonDeadzone, buttonZoomIn, buttonZoomOut } = this.#options;
+		const input = this.gamepadInput;
+		const rotate = input.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
+		const pan = input.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
+		const triggerIn = input.buttonValue(buttonZoomIn);
+		const triggerOut = input.buttonValue(buttonZoomOut);
+		const zoom = (triggerOut > buttonDeadzone ? triggerOut : 0) - (triggerIn > buttonDeadzone ? triggerIn : 0);
+		const frame = {
+			rotateX: rotate.x,
+			rotateY: rotate.y,
+			panX: pan.x,
+			panY: pan.y,
+			zoom
+		};
+		let actions = this.#acceptActions(frame, deltaTime);
+		if (actions === null) return;
+		if (!this.#interacting) {
+			this.#interacting = true;
+			this.#controls.dispatchEvent({ type: "start" });
+			actions = this.#acceptActions(frame, deltaTime);
+			if (actions === null) return;
+		}
 		const controls = this.#controls;
-		if (controls.noRotate) return;
-		const rotate = this.gamepadInput.stick(rotateStick.xAxis, rotateStick.yAxis, rotateStick.pipeline);
-		if (rotate.x === 0 && rotate.y === 0) return;
-		const scale = rotateSpeed * deltaTime * Math.PI;
-		controls._moveCurr.x += rotate.x * scale;
-		controls._moveCurr.y += -rotate.y * scale;
+		controls._moveCurr.x += actions.rotateX;
+		controls._moveCurr.y -= actions.rotateY;
+		controls._panEnd.x += actions.panX;
+		controls._panEnd.y += actions.panY;
+		controls._zoomEnd.y += actions.zoom;
 	}
 	/**
-	* Queues pan input into TrackballControls' normalized pan state.
-	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param panSpeed - User-configured pan speed multiplier.
-	* @param panStick - Resolved stick binding for panning.
+	* Removes gamepad listeners and ends only this wrapper's active interaction.
+	* Repeated calls are safe; native pointer vectors and damping are preserved.
 	*/
-	#queuePan(deltaTime, panSpeed, panStick) {
-		const controls = this.#controls;
-		if (controls.noPan) return;
-		const pan = this.gamepadInput.stick(panStick.xAxis, panStick.yAxis, panStick.pipeline);
-		if (pan.x === 0 && pan.y === 0) return;
-		const scale = panSpeed * deltaTime * this.#getInputDampingFactor();
-		controls._panEnd.x += pan.x * scale;
-		controls._panEnd.y += pan.y * scale;
+	dispose() {
+		super.dispose();
+		this.#endInteraction();
 	}
 	/**
-	* Queues trigger zoom input into TrackballControls' normalized zoom state.
+	* Ends the owned interaction before forwarding the active gamepad's disconnection.
 	*
-	* @param deltaTime - Seconds since the last frame.
-	* @param zoomSpeed - User-configured zoom speed multiplier.
-	* @param buttonDeadzone - Trigger dead zone threshold.
-	* @param buttonZoomIn - Button index for zooming in.
-	* @param buttonZoomOut - Button index for zooming out.
+	* @param gamepad - The gamepad that just disconnected.
 	*/
-	#queueZoom(deltaTime, zoomSpeed, buttonDeadzone, buttonZoomIn, buttonZoomOut) {
-		const controls = this.#controls;
-		if (controls.noZoom) return;
-		const input = this.gamepadInput;
-		const triggerIn = input.buttonValue(buttonZoomIn);
-		const triggerOut = input.buttonValue(buttonZoomOut);
-		if (triggerIn <= buttonDeadzone && triggerOut <= buttonDeadzone) return;
-		controls._zoomEnd.y += (triggerOut - triggerIn) * zoomSpeed * deltaTime * this.#getInputDampingFactor();
+	onGamepadDisconnected(gamepad) {
+		this.#endInteraction();
+		super.onGamepadDisconnected(gamepad);
 	}
 	/**
-	* Compensates for TrackballControls reapplying queued pan and zoom deltas
-	* while their input state catches up through damping.
+	* Resolves a cached frame against current permissions, wrapper speeds, and damping.
+	* Native speeds only gate acceptance here; Trackball applies them during its update.
+	* Native disable or lack of actionable input ends the owned session; a wrapper
+	* pause stops application while retaining it. Geometric limits do not erase intent.
 	*
-	* @returns Multiplier that matches TrackballControls' damping mode.
+	* @param input - Already processed sticks and independently filtered trigger difference.
+	* @param delta - Frame duration in seconds.
+	* @returns Accepted pointer-coordinate deltas, or `null` when application must stop.
 	*/
-	#getInputDampingFactor() {
+	#acceptActions(input, delta) {
 		const controls = this.#controls;
-		return controls.staticMoving ? 1 : controls.dynamicDampingFactor;
+		if (!controls.enabled) {
+			this.#endInteraction();
+			return null;
+		}
+		if (!this.enabled || this.gamepad === null) return null;
+		const damping = controls.staticMoving ? 1 : controls.dynamicDampingFactor;
+		const rotate = !controls.noRotate && controls.rotateSpeed !== 0 ? this.#options.rotateSpeed * delta * Math.PI : 0;
+		const pan = !controls.noPan && controls.panSpeed !== 0 ? this.#options.panSpeed * delta * damping : 0;
+		const zoom = !controls.noZoom && controls.zoomSpeed !== 0 ? this.#options.zoomSpeed * delta * damping : 0;
+		const actions = {
+			rotateX: input.rotateX * rotate,
+			rotateY: input.rotateY * rotate,
+			panX: input.panX * pan,
+			panY: input.panY * pan,
+			zoom: input.zoom * zoom
+		};
+		if (!Object.values(actions).some((value) => value !== 0)) {
+			this.#endInteraction();
+			return null;
+		}
+		return actions;
+	}
+	/**
+	* Releases session ownership before dispatching the native `end` event once.
+	* Blocks recursive updates during finalization without clearing native pointer vectors.
+	*/
+	#endInteraction() {
+		if (!this.#interacting) return;
+		this.#interacting = false;
+		this.#ending = true;
+		try {
+			this.#controls.dispatchEvent({ type: "end" });
+		} finally {
+			this.#ending = false;
+		}
 	}
 };
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "three-gamepad-controls",
   "description": "Gamepad support for Three.js controls.",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "license": "MIT",
   "homepage": "https://github.com/luckasnix/three-gamepad-controls#readme",
   "author": {