three-gamepad-controls 0.24.1 → 0.24.3

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-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.
    */