three-gamepad-controls 0.24.0 → 0.24.2

package/dist/gamepad-transform-controls.js

@@ -99,7 +99,18 @@ var GamepadTransformControls = class extends GamepadControls {
 	#rotationQuaternion;
 	#rotationQuaternion2;
 	#tempQuaternion;
-	#isTransforming = false;
+	#segment = null;
+	#updating = false;
+	#ending = false;
+	#disposed = false;
+	#interrupted = false;
+	#needsNeutral = false;
+	#pointerRevision = 0;
+	#mouseDownEvent = {
+		type: "mouseDown",
+		mode: "translate"
+	};
+	#onNativeMouseDown;
 	#rotationAmount = 0;
 	#freeRotationX = 0;
 	#freeRotationY = 0;
@@ -150,6 +161,10 @@ var GamepadTransformControls = class extends GamepadControls {
 		this.#rotationQuaternion = new Quaternion();
 		this.#rotationQuaternion2 = new Quaternion();
 		this.#tempQuaternion = new Quaternion();
+		this.#onNativeMouseDown = (event) => {
+			if (event !== this.#mouseDownEvent) this.#pointerRevision += 1;
+		};
+		controls.addEventListener("mouseDown", this.#onNativeMouseDown);
 	}
 	/**
 	* Maps the current gamepad state to `TransformControls` mode, axis,
@@ -158,38 +173,83 @@ var GamepadTransformControls = class extends GamepadControls {
 	* @param deltaTime - Seconds since the last frame.
 	*/
 	onUpdate(deltaTime) {
+		if (this.#updating || this.#ending) return;
+		this.#updating = true;
+		this.#interrupted = false;
+		try {
+			this.#updateTransform(deltaTime);
+		} finally {
+			this.#updating = false;
+		}
+	}
+	/**
+	* Processes one frame of selection, reset, and movement while respecting
+	* segment ownership and the neutral input required before reacquisition.
+	*
+	* @param deltaTime - Seconds since the last frame.
+	*/
+	#updateTransform(deltaTime) {
+		const controls = this.#controls;
+		const { transformStick } = this.#options;
+		const transform = this.gamepadInput.stick(transformStick.xAxis, transformStick.yAxis, transformStick.pipeline);
+		const neutral = transform.x === 0 && transform.y === 0;
+		this.#reconcileSegment();
+		if (neutral) this.#needsNeutral = false;
+		if (!this.#canApplyInput()) return;
+		if (controls.dragging && this.#segment === null) {
+			this.#needsNeutral = !neutral;
+			return;
+		}
 		const startedButtons = this.#getStartedButtons();
 		this.#handleModeAndAxisButtons(startedButtons);
+		if (!this.#canApplyInput()) return;
 		if (startedButtons.has(this.#options.buttonReset)) this.#resetActiveTransform();
-		const controls = this.#controls;
+		if (!this.#canApplyInput()) return;
 		const object = controls.object;
-		if (!controls.enabled || object === void 0) {
+		if (object === void 0) {
 			this.#endTransform(true);
 			return;
 		}
-		const axis = this.#ensureValidAxis();
-		if (axis === null) {
-			this.#endTransform(true);
-			return;
-		}
-		const { transformStick } = this.#options;
-		const transform = this.gamepadInput.stick(transformStick.xAxis, transformStick.yAxis, transformStick.pipeline);
-		if (transform.x === 0 && transform.y === 0) {
+		if (neutral) {
 			this.#endTransform(false);
 			return;
 		}
-		if (!this.#isTransforming) this.#startTransform(object);
+		if (this.#needsNeutral) return;
+		const axis = this.#resolveAxis();
+		this.#setActiveAxis(axis);
+		if (!this.#canApplyInput()) return;
+		if (axis === null) return;
+		if (this.#segment === null) this.#startTransform(object, axis);
+		if (!this.#canApplyInput()) return;
+		const segment = this.#segment;
+		if (!segment.started) {
+			segment.started = true;
+			const context = this.#readContext();
+			this.#mouseDownEvent.mode = segment.mode;
+			controls.dispatchEvent(this.#mouseDownEvent);
+			this.#afterCallback(context);
+		}
+		if (!this.#canApplyInput()) return;
 		if (this.#applyCurrentTransform(object, axis, deltaTime, transform.x, transform.y)) {
+			const context = this.#readContext();
 			controls.dispatchEvent({ type: "change" });
+			if (!this.#afterCallback(context)) return;
 			controls.dispatchEvent({ type: "objectChange" });
+			this.#afterCallback(context);
 		}
 	}
 	/**
-	* Ends any active transform before disposing the gamepad lifecycle listeners.
+	* Disables gamepad updates and ends only this wrapper's active transform.
 	*/
 	dispose() {
-		this.#endTransform(true);
 		super.dispose();
+		this.#disposed = true;
+		if (this.#ending) return;
+		try {
+			this.#endTransform(true);
+		} finally {
+			this.#controls.removeEventListener("mouseDown", this.#onNativeMouseDown);
+		}
 	}
 	/**
 	* Ends any active transform if the active gamepad disconnects mid-drag.
@@ -201,22 +261,108 @@ var GamepadTransformControls = class extends GamepadControls {
 		super.onGamepadDisconnected(gamepad);
 	}
 	/**
+	* Checks whether this update can continue applying gamepad input.
+	* Native disable ends the owned segment; a wrapper pause retains it.
+	*
+	* @returns `true` when input remains enabled, a gamepad is available,
+	*          and no callback has interrupted this update.
+	*/
+	#canApplyInput() {
+		if (!this.#controls.enabled) {
+			this.#endTransform(true);
+			return false;
+		}
+		return !this.#interrupted && this.enabled && this.gamepad !== null;
+	}
+	/**
+	* Captures the native context and pointer acquisition revision without
+	* modifying the control or copying the attached object's transform.
+	*
+	* @returns A context snapshot for segment and callback validation.
+	*/
+	#readContext() {
+		const { object, mode, space, axis, dragging } = this.#controls;
+		return {
+			object,
+			mode,
+			space,
+			axis,
+			dragging,
+			pointerRevision: this.#pointerRevision
+		};
+	}
+	/**
+	* Compares the current native context and pointer revision with a snapshot.
+	*
+	* @param context - Expected object, selection, dragging state, and pointer revision.
+	* @returns `true` when every captured context field still matches.
+	*/
+	#matchesContext(context) {
+		const controls = this.#controls;
+		return controls.object === context.object && controls.mode === context.mode && controls.space === context.space && controls.axis === context.axis && controls.dragging === context.dragging && this.#pointerRevision === context.pointerRevision;
+	}
+	/**
+	* Ends the owned segment when its context changes or its axis is disallowed.
+	* A change of attached object also requires neutral input before reacquisition.
+	*/
+	#reconcileSegment() {
+		const segment = this.#segment;
+		if (segment === null) return;
+		if (!this.#matchesContext(segment) || !this.#isAxisAllowed(segment.mode, segment.axis)) {
+			if (this.#controls.object !== segment.object) this.#needsNeutral = true;
+			this.#endTransform(false);
+		}
+	}
+	/**
+	* Revalidates context, segment ownership, and permissions after synchronous
+	* callbacks, interrupting this update if its context or segment was invalidated.
+	*
+	* @param context - Context expected after the operation that invoked callbacks.
+	* @returns `true` when this update may continue applying gamepad input.
+	*/
+	#afterCallback(context) {
+		const segment = this.#segment;
+		if (!this.#matchesContext(context)) {
+			this.#interrupted = true;
+			if (this.#controls.object !== context.object) this.#needsNeutral = true;
+		}
+		this.#reconcileSegment();
+		if (segment !== null && this.#segment !== segment) this.#interrupted = true;
+		return this.#canApplyInput();
+	}
+	/**
+	* Writes a native property and revalidates the context after its synchronous
+	* notifications, accounting for the intended property change.
+	*
+	* @param key - Native selection or dragging property to update.
+	* @param value - Value to assign to the selected property.
+	*/
+	#writeProperty(key, value) {
+		const context = {
+			...this.#readContext(),
+			[key]: value
+		};
+		const controls = this.#controls;
+		controls[key] = value;
+		this.#afterCallback(context);
+	}
+	/**
 	* Applies mode, space, and axis button transitions from the current frame.
 	*
 	* @param startedButtons - Button indices that transitioned to pressed.
 	*/
 	#handleModeAndAxisButtons(startedButtons) {
 		const { buttonTranslate, buttonRotate, buttonScale, buttonToggleSpace, buttonAxisX, buttonAxisY, buttonAxisZ, buttonAxisComposite, buttonAxisPrevious, buttonAxisNext } = this.#options;
-		if (startedButtons.has(buttonTranslate)) this.#setMode("translate");
-		if (startedButtons.has(buttonRotate)) this.#setMode("rotate");
-		if (startedButtons.has(buttonScale)) this.#setMode("scale");
-		if (startedButtons.has(buttonToggleSpace)) this.#toggleSpace();
-		if (startedButtons.has(buttonAxisX)) this.#selectAxis("X");
-		if (startedButtons.has(buttonAxisY)) this.#selectAxis("Y");
-		if (startedButtons.has(buttonAxisZ)) this.#selectAxis("Z");
-		if (startedButtons.has(buttonAxisComposite)) this.#cycleCompositeAxis();
-		if (startedButtons.has(buttonAxisPrevious)) this.#cycleAxis(-1);
-		if (startedButtons.has(buttonAxisNext)) this.#cycleAxis(1);
+		if (startedButtons.has(buttonTranslate) && this.#canApplyInput()) this.#setMode("translate");
+		if (startedButtons.has(buttonRotate) && this.#canApplyInput()) this.#setMode("rotate");
+		if (startedButtons.has(buttonScale) && this.#canApplyInput()) this.#setMode("scale");
+		if (startedButtons.has(buttonToggleSpace) && this.#canApplyInput()) this.#toggleSpace();
+		if (startedButtons.has(buttonAxisX) && this.#canApplyInput()) this.#selectAxis("X");
+		if (startedButtons.has(buttonAxisY) && this.#canApplyInput()) this.#selectAxis("Y");
+		if (startedButtons.has(buttonAxisZ) && this.#canApplyInput()) this.#selectAxis("Z");
+		if (startedButtons.has(buttonAxisComposite) && this.#canApplyInput()) this.#cycleCompositeAxis();
+		if (startedButtons.has(buttonAxisPrevious) && this.#canApplyInput()) this.#cycleAxis(-1);
+		if (startedButtons.has(buttonAxisNext) && this.#canApplyInput()) this.#cycleAxis(1);
 	}
 	/**
 	* Switches TransformControls mode and refreshes the active axis.
@@ -226,13 +372,28 @@ var GamepadTransformControls = class extends GamepadControls {
 	#setMode(mode) {
 		if (this.#controls.mode === mode) return;
 		this.#endTransform(false);
+		if (!this.#canApplyInput()) return;
+		const context = {
+			...this.#readContext(),
+			mode
+		};
 		this.#controls.setMode(mode);
-		this.#ensureValidAxis();
+		if (this.#afterCallback(context)) this.#setActiveAxis(this.#resolveAxis(null));
 	}
+	/**
+	* Ends the owned segment and toggles between local and world transform space
+	* if input remains permitted after the end notification.
+	*/
 	#toggleSpace() {
 		const nextSpace = this.#controls.space === "world" ? "local" : "world";
 		this.#endTransform(false);
+		if (!this.#canApplyInput()) return;
+		const context = {
+			...this.#readContext(),
+			space: nextSpace
+		};
 		this.#controls.setSpace(nextSpace);
+		this.#afterCallback(context);
 	}
 	/**
 	* Selects an explicit axis when it is valid for the current mode.
@@ -242,9 +403,12 @@ var GamepadTransformControls = class extends GamepadControls {
 	#selectAxis(axis) {
 		if (!this.#isAxisAllowed(this.#controls.mode, axis)) return;
 		this.#endTransform(false);
-		this.#activeAxisByMode[this.#controls.mode] = axis;
-		this.#ensureValidAxis();
+		if (!this.#canApplyInput()) return;
+		this.#setActiveAxis(axis);
 	}
+	/**
+	* Selects the next visible composite axis available in the current mode.
+	*/
 	#cycleCompositeAxis() {
 		const validAxes = this.#getVisibleAxes(COMPOSITE_AXES[this.#controls.mode]);
 		this.#cycleThroughAxes(validAxes, 1);
@@ -264,30 +428,30 @@ var GamepadTransformControls = class extends GamepadControls {
 	* @param direction - `1` for next axis, `-1` for previous axis.
 	*/
 	#cycleThroughAxes(axes, direction) {
+		this.#endTransform(false);
+		if (!this.#canApplyInput()) return;
 		if (axes.length === 0) {
 			this.#setActiveAxis(null);
 			return;
 		}
-		this.#endTransform(false);
-		const current = this.#activeAxisByMode[this.#controls.mode];
-		const currentIndex = current === null ? -1 : axes.indexOf(current);
+		const current = this.#resolveAxis();
+		const currentIndex = axes.indexOf(current);
 		const nextIndex = currentIndex === -1 ? 0 : (currentIndex + direction + axes.length) % axes.length;
-		this.#activeAxisByMode[this.#controls.mode] = axes[nextIndex];
-		this.#ensureValidAxis();
+		this.#setActiveAxis(axes[nextIndex]);
 	}
 	/**
-	* Ensures the highlighted TransformControls axis is valid and visible.
+	* Resolves selection without writing to the native control or axis memory.
 	*
+	* @param nativeAxis - Preferred native axis, defaulting to the current selection.
+	*                     Pass `null` to use mode memory before the first allowed axis.
 	* @returns The active valid axis, or `null` when no axis is available.
 	*/
-	#ensureValidAxis() {
+	#resolveAxis(nativeAxis = this.#controls.axis) {
 		const mode = this.#controls.mode;
+		if (nativeAxis !== null && this.#isAxisAllowed(mode, nativeAxis)) return nativeAxis;
 		const current = this.#activeAxisByMode[mode];
 		const validAxes = this.#getValidAxes(mode);
-		const nextAxis = current !== null && validAxes.includes(current) ? current : validAxes[0] ?? null;
-		this.#activeAxisByMode[mode] = nextAxis;
-		if (this.#controls.axis !== nextAxis) this.#controls.axis = nextAxis;
-		return nextAxis;
+		return current !== null && validAxes.includes(current) ? current : validAxes[0] ?? null;
 	}
 	/**
 	* Updates both the remembered axis for the current mode and the control axis.
@@ -296,7 +460,7 @@ var GamepadTransformControls = class extends GamepadControls {
 	*/
 	#setActiveAxis(axis) {
 		this.#activeAxisByMode[this.#controls.mode] = axis;
-		if (this.#controls.axis !== axis) this.#controls.axis = axis;
+		if (this.#controls.axis !== axis) this.#writeProperty("axis", axis);
 	}
 	/**
 	* Returns all visible axes supported by a TransformControls mode.
@@ -349,43 +513,71 @@ var GamepadTransformControls = class extends GamepadControls {
 		}
 	}
 	/**
-	* Starts a TransformControls drag interaction for the active object and axis.
+	* Captures a segment's transform origin and claims dragging ownership before
+	* notifying native property listeners. The update publishes `mouseDown` later.
 	*
 	* @param object - Object attached to TransformControls for this update.
+	* @param axis - Valid axis acquired for the new segment.
 	*/
-	#startTransform(object) {
-		const controls = this.#controls;
+	#startTransform(object, axis) {
 		this.#captureTransformStart(object);
-		controls.dragging = true;
-		this.#isTransforming = true;
-		controls.dispatchEvent({
-			type: "mouseDown",
-			mode: controls.mode
-		});
+		this.#segment = {
+			...this.#readContext(),
+			object,
+			axis,
+			dragging: true,
+			started: false
+		};
+		this.#writeProperty("dragging", true);
 	}
 	/**
-	* Ends an active TransformControls drag interaction.
+	* Releases the owned segment and ends its published interaction once,
+	* preserving pointer ownership and context changes made by callbacks.
 	*
-	* @param clearAxis - Whether to clear the highlighted axis after ending.
+	* @param clearAxis - Whether to clear the highlighted axis if ownership
+	*                    and context still permit it after end notifications.
 	*/
 	#endTransform(clearAxis) {
+		const segment = this.#segment;
+		if (segment === null) return;
 		const controls = this.#controls;
-		if (this.#isTransforming) {
-			this.#isTransforming = false;
-			controls.dispatchEvent({
+		const context = this.#readContext();
+		this.#segment = null;
+		this.#ending = true;
+		try {
+			if (segment.started) controls.dispatchEvent({
 				type: "mouseUp",
-				mode: controls.mode
+				mode: segment.mode
 			});
-			controls.dragging = false;
+			const unchanged = this.#matchesContext(context);
+			if (!unchanged) {
+				this.#interrupted = true;
+				if (controls.object !== context.object) this.#needsNeutral = true;
+			}
+			const ownsDragging = this.#pointerRevision === segment.pointerRevision;
+			if (ownsDragging && controls.dragging === context.dragging) this.#writeProperty("dragging", false);
+			if (clearAxis && ownsDragging && unchanged && this.#matchesContext({
+				...context,
+				dragging: false
+			}) && controls.axis === segment.axis) this.#setActiveAxis(null);
+		} finally {
+			this.#ending = false;
+			if (this.#disposed) controls.removeEventListener("mouseDown", this.#onNativeMouseDown);
 		}
-		if (clearAxis) this.#setActiveAxis(null);
 	}
+	/**
+	* Restores the owned segment's transform origin through native reset and
+	* resets its accumulators if callbacks leave the same segment active.
+	*/
 	#resetActiveTransform() {
-		const object = this.#controls.object;
-		if (!this.#isTransforming || object === void 0) return;
+		const segment = this.#segment;
+		if (segment === null) return;
+		const context = this.#readContext();
 		this.#controls.reset();
-		this.#accumulatedPosition.copy(object.position);
-		this.#accumulatedScale.copy(object.scale);
+		this.#afterCallback(context);
+		if (this.#segment !== segment) return;
+		this.#accumulatedPosition.copy(segment.object.position);
+		this.#accumulatedScale.copy(segment.object.scale);
 		this.#rotationAmount = 0;
 		this.#freeRotationX = 0;
 		this.#freeRotationY = 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "three-gamepad-controls",
   "description": "Gamepad support for Three.js controls.",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "license": "MIT",
   "homepage": "https://github.com/luckasnix/three-gamepad-controls#readme",
   "author": {
@@ -46,19 +46,20 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.11",
-    "@commitlint/cli": "21.2.2",
-    "@commitlint/config-conventional": "21.2.2",
-    "@commitlint/types": "21.2.0",
+    "@biomejs/biome": "2.5.14",
+    "@commitlint/cli": "21.2.3",
+    "@commitlint/config-conventional": "21.2.3",
+    "@commitlint/types": "21.2.3",
     "@types/node": "24.13.3",
     "@types/three": "0.186.0",
-    "@vitest/coverage-v8": "5.0.0",
+    "@vitest/browser-playwright": "5.0.2",
+    "@vitest/coverage-v8": "5.0.2",
     "husky": "9.1.7",
-    "jsdom": "29.1.1",
+    "playwright": "1.63.0",
     "three": "0.186.0",
-    "tsdown": "0.22.14",
+    "tsdown": "0.23.0",
     "typescript": "7.0.2",
-    "vitest": "5.0.0"
+    "vitest": "5.0.2"
   },
   "peerDependencies": {
     "@types/three": "~0.186.0",