@needle-tools/engine 5.1.4 → 5.1.5

package/src/engine/xr/NeedleXRSync.ts

@@ -1,7 +1,6 @@
 import type { Context } from "../engine_context.js";
 import { RoomEvents, UserJoinedOrLeftRoomModel } from "../engine_networking.js";
 import { getParam } from "../engine_utils.js";
-import { NeedleXRController } from "./NeedleXRController.js";
 import { NeedleXRSession } from "./NeedleXRSession.js";
 
 const debug = getParam("debugwebxr");
@@ -11,8 +10,9 @@ declare type XRControllerType = "hand" | "controller";
 
 declare type XRControllerState = {
     // adding a guid so it's saved on the server, ideally we have a "room lifetime" store that doesnt save state forever on disc but just until the room is disposed (we have to add support for this in the networking backend tho)
+    // The guid is derived from the handedness (see XRUserState) so it is stable across input-type
+    // switches (hand <-> controller), which reuse/reorder input-source indices.
     guid: string;
-    index: number;
     handedness: XRHandedness;
     isTracking: boolean;
     type: XRControllerType;
@@ -41,55 +41,37 @@ class XRUserState {
     onReceivedControllerState = (state: XRControllerState) => {
         if (debug) console.log(`XRSync: Received change for ${this.userId}: ${state.type} ${state.handedness}; tracked=${state.isTracking}`);
 
-        let found = false;
+        // Identity is the handedness: there is exactly one left and one right hand per user. Keying by
+        // handedness (instead of the input-source index, which is reused/reordered when switching
+        // hand <-> controller) keeps the tracking state correct across input-type switches.
         for (let i = 0; i < this.controllerStates.length; i++) {
-            const ctrl = this.controllerStates[i];
-            if (ctrl.index === state.index) {
+            if (this.controllerStates[i].handedness === state.handedness) {
                 this.controllerStates[i] = state;
-                found = true;
-                break;
-            }
-        }
-        if (!found) {
-            this.controllerStates.push(state);
-        }
-
-        // When switching input type (e.g. hand -> controller), the new input source gets a new index.
-        // The old controller's state lingers here (we only ever add/update by index), and a stale
-        // non-tracking entry for the same handedness would otherwise mask the new tracked one. Once a
-        // tracking state arrives for a handedness, drop any other (stale) states for that handedness.
-        if (state.isTracking) {
-            for (let i = this.controllerStates.length - 1; i >= 0; i--) {
-                const other = this.controllerStates[i];
-                if (other.index !== state.index && other.handedness === state.handedness) {
-                    this.controllerStates.splice(i, 1);
-                }
+                return;
             }
         }
+        this.controllerStates.push(state);
     }
 
     update(session: NeedleXRSession) {
         if (this.context.connection.isConnected == false) return;
 
+        // Remove states whose handedness no longer has ANY input source in the session (the hand/
+        // controller was fully removed), broadcasting a not-tracking + deleting the persisted state.
         for (let i = this.controllerStates.length - 1; i >= 0; i--) {
             const state = this.controllerStates[i];
-            let foundController = false;
-            for (let i = 0; i < session.controllers.length; i++) {
-                const ctrl = session.controllers[i];
-                if (ctrl.index === state.index) {
-                    foundController = true;
-                }
-            }
-            if (!foundController) {
-                // controller was removed
-                if (debug) console.log(`XRSync: ${state.type} ${state.handedness} removed`, state.index);
+            const stillPresent = session.controllers.some(ctrl => ctrl.side === state.handedness);
+            if (!stillPresent) {
+                if (debug) console.log(`XRSync: ${state.type} ${state.handedness} removed`);
                 this.controllerStates.splice(i, 1);
                 this.sendControllerRemoved(state);
             }
         }
 
+        // Update per-handedness tracking. Calling this once per controller is idempotent: it aggregates
+        // across all sources of that handedness, so a second call for the same side is a no-op.
         for (const ctrl of session.controllers) {
-            this.updateControllerStates(ctrl);
+            this.updateHandednessState(ctrl.side, session);
         }
     }
 
@@ -110,29 +92,45 @@ class XRUserState {
         this.context.connection.sendDeleteRemoteState(state.guid);
     }
 
-    private updateControllerStates(ctrl: NeedleXRController) {
+    private updateHandednessState(handedness: XRHandedness, session: NeedleXRSession) {
+        // Aggregate across all input sources of this handedness: the side is "tracking" if ANY of its
+        // sources is tracking. During a hand <-> controller switch both can momentarily coexist; the
+        // avatar has a single hand object per side, so any tracked source keeps it visible.
+        let isTracking = false;
+        let type: XRControllerType | undefined = undefined;
+        let anyOfSide = false;
+        for (const ctrl of session.controllers) {
+            if (ctrl.side !== handedness) continue;
+            anyOfSide = true;
+            const ctrlType: XRControllerType = ctrl.hand ? "hand" : "controller";
+            if (ctrl.isTracking) {
+                isTracking = true;
+                type = ctrlType; // prefer the type of a currently-tracking source
+            }
+            else if (type === undefined) {
+                type = ctrlType;
+            }
+        }
+        if (!anyOfSide) return;
 
-        // this.context.connection.send(this.userStateEvtName, {});
-        const existing = this.controllerStates.find(x => x.index === ctrl.index);
+        const existing = this.controllerStates.find(x => x.handedness === handedness);
         if (existing) {
-            let hasChanged = false;
-            hasChanged ||= existing.isTracking != ctrl.isTracking;
-            if (hasChanged) {
-                existing.isTracking = ctrl.isTracking;
+            if (existing.isTracking !== isTracking || existing.type !== type) {
+                existing.isTracking = isTracking;
+                existing.type = type!;
                 this.context.connection.send(this.userStateEvtName, existing);
             }
         }
         else {
             const state: XRControllerState = {
-                guid: this.userId + "-" + ctrl.index,
-                isTracking: ctrl.isTracking,
-                handedness: ctrl.side,
-                index: ctrl.index,
-                type: ctrl.hand ? "hand" : "controller"
+                guid: this.userId + "-" + handedness,
+                isTracking,
+                handedness,
+                type: type!,
             }
             this.controllerStates.push(state);
             this.context.connection.send(this.userStateEvtName, state);
-            if (debug) console.log(`XRSync: ${state.type} ${state.handedness} added`, state.index);
+            if (debug) console.log(`XRSync: ${state.type} ${state.handedness} added`);
         }
     }
 
@@ -151,9 +149,8 @@ export class NeedleXRSync {
         if (!userId) return undefined;
         const user = this._states.get(userId);
         if (!user) return undefined;
-        // Consider it tracked if ANY controller state for this handedness is tracking. After switching
-        // input type a stale non-tracking entry can still exist for a frame before it's pruned - this
-        // makes sure it doesn't mask the new tracked controller/hand.
+        // There is one state per handedness (keyed by side), so this finds that side's state and
+        // reports whether it is currently tracking.
         return user.controllerStates.some(x => x.handedness === handedness && x.isTracking);
     }
 

package/src/engine/xr/TempXRContext.ts

@@ -3,7 +3,7 @@ import { ArrayCamera, AxesHelper, Camera, Color, DirectionalLight, Fog, GridHelp
 import { needleLogoOnlySVG } from "../assets/index.js";
 import { isDevEnvironment } from "../debug/index.js";
 import { ObjectUtils, PrimitiveType } from "../engine_create_objects.js";
-import { __QhCnOwd } from "../engine_license.js";
+import { $PLKRCQIf } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { delay, DeviceUtilities } from "../engine_utils.js";
 
@@ -215,7 +215,7 @@ export class TemporaryXRContext {
         this._scene.background = new Color(0x000000);
 
         let logoSrc = needleLogoOnlySVG;
-        if (__QhCnOwd()) {
+        if ($PLKRCQIf()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

package/src/engine-components/DragControls.ts

@@ -627,6 +627,13 @@ interface IDragHandler {
 
 /** Scratch quaternion for {@link MultiTouchDragHandler}'s per-frame delta rotation. */
 const _mtRotDelta = new Quaternion();
+/** Scratch vectors for the on-screen twist → yaw mapping (view-plane twist path). */
+const _mtCross = new Vector3();
+const _mtToEye = new Vector3();
+const _mtCamOffset = new Vector3();
+/** Scratch vectors for aiming the SnapToSurfaceConstraint ray in MultiTouchDragHandler.onDragUpdate. */
+const _mtSnapRayOrigin = new Vector3();
+const _mtSnapRayDir = new Vector3();
 
 // #region MultiTouchDragHandler
 /** 
@@ -652,6 +659,9 @@ class MultiTouchDragHandler implements IDragHandler {
     private _keepRotationConstraint: KeepRotationConstraint = new KeepRotationConstraint();
     /** GrabPointPlaneConstraint returned by the active strategy (if any); used to sync snapResolution. */
     private _planeConstraint: GrabPointPlaneConstraint | null = null;
+    /** SnapToSurfaceConstraint returned by the active strategy (SnapToSurfaces mode); its snap ray
+     *  is re-aimed every frame in onDragUpdate so it targets what the fingers point at. */
+    private _snapToSurfaceConstraint: SnapToSurfaceConstraint | null = null;
     private _activeConstraints: IDragConstraint[] = [];
 
     constructor(dragControls: DragControls, gameObject: Object3D, pointerA: DragPointerHandler, pointerB: DragPointerHandler) {
@@ -751,6 +761,9 @@ class MultiTouchDragHandler implements IDragHandler {
         this._planeConstraint = strategyConstraints.find(
             c => c instanceof GrabPointPlaneConstraint
         ) as GrabPointPlaneConstraint ?? null;
+        this._snapToSurfaceConstraint = strategyConstraints.find(
+            c => c instanceof SnapToSurfaceConstraint
+        ) as SnapToSurfaceConstraint ?? null;
         const hasStrategyConstraints = strategyConstraints.length > 0;
         this._activeConstraints = [
             ...strategyConstraints,
@@ -762,6 +775,13 @@ class MultiTouchDragHandler implements IDragHandler {
         }
         this._scaleLimitConstraint.init(constraintCx);
 
+        // Yaw-locked strategies (XZPlane) expose their world-space rotation axis. For screen
+        // two-finger input we drive an intuitive on-screen twist → yaw mapping around it (see
+        // alignManipulator). XR keeps the free 3D-delta path for now.
+        this._yawConstraintAxis = !isSpatialInput(this._deviceMode)
+            ? (this.handlerA.currentStrategy.yawConstraintAxis ?? null)
+            : null;
+
         // align _manipulatorObject in the same way it would if this was a drag update
         this.alignManipulator();
 
@@ -780,7 +800,15 @@ class MultiTouchDragHandler implements IDragHandler {
         }
 
         // we want to initialize the drag points for these handlers again.
-        // one of them will be removed, but we don't know here which one
+        // one of them will be removed, but we don't know here which one.
+        // Re-derive each handler's grab point from its current pointer ray BEFORE recentering:
+        // during the two-pointer drag the object moved relative to each pointer, so the grab
+        // point captured at pointer-down is stale — without the rebase the surviving handler
+        // would yank the object until that old grab point is back under the pointer (visible
+        // jump on release). recenter() then re-captures start transforms and re-initializes
+        // constraints using the rebased grab point.
+        this.handlerA.rebaseGrabPointToPointer();
+        this.handlerB.rebaseGrabPointToPointer();
         this.handlerA.recenter();
         this.handlerB.recenter();
 
@@ -814,6 +842,16 @@ class MultiTouchDragHandler implements IDragHandler {
     /** True only for the very first `alignManipulator` call; triggers the one-time lookAt seed. */
     private _isFirstAlignFrame: boolean = true;
 
+    /** World-space yaw axis when the active strategy locks rotation to a single axis (XZPlane),
+     *  for screen input only. Null ⇒ use the free 3D-delta rotation path. Set in onDragStart. */
+    private _yawConstraintAxis: Vector3 | null = null;
+    /** Camera forward captured while computing the view-plane twist (scratch). */
+    private readonly _viewForward = new Vector3();
+    /** A→B projected into the view plane on the previous frame; reference for the twist delta. */
+    private readonly _prevViewTwistDir = new Vector3();
+    /** A→B projected into the view plane on the current frame (scratch). */
+    private readonly _currViewTwistDir = new Vector3();
+
     private alignManipulator() {
         if (!this.handlerA || !this.handlerB) {
             console.error("alignManipulator called on MultiTouchDragHandler without valid handlers. This is likely a bug.", this);
@@ -840,33 +878,39 @@ class MultiTouchDragHandler implements IDragHandler {
         const dist = this._tempVec1.distanceTo(this._tempVec2);
         this._currentScaleRatio = dist / this._initialDistance;
 
-        // Rotation: delta-frame approach instead of per-frame lookAt.
-        // lookAt recomputes the full world orientation every frame using camera.worldUp as the
-        // stabilising axis, which breaks when the A→B vector aligns with that up and causes
-        // flips or jitter.  Here we instead accumulate only the angular delta of A→B between
-        // consecutive frames via setFromUnitVectors, so translation never contaminates rotation
-        // and camera tilt has no effect after the initial seed.
+        // Rotation: accumulate a per-frame delta so translation never contaminates rotation.
+        // Two paths:
+        //  - Yaw-locked screen drag (XZPlane, _yawConstraintAxis set): map the on-screen finger
+        //    twist directly to yaw around the constraint axis, so the gesture stays usable from
+        //    any view angle — a side-on view no longer collapses it. See _applyViewPlaneTwist.
+        //  - Free rotation (XR / other modes): accumulate the full 3D delta of the A→B direction
+        //    via setFromUnitVectors (camera tilt has no effect after the initial seed).
         this._currABDir.subVectors(this._tempVec2, this._tempVec1);
         if (this._currABDir.lengthSq() > 1e-10) {
-            this._currABDir.normalize();
             if (this._isFirstAlignFrame) {
-                // Seed the initial orientation once with lookAt so _manipulatorRotOffset
-                // (captured right after this call in onDragStart) is consistent with the
-                // dragged object's starting rotation.
+                // Seed the manipulator orientation once. Only the manipulator's *change* since
+                // this frame drives the object (the follow-object offset captured in onDragStart
+                // absorbs the absolute seed), so the seed value itself is arbitrary — lookAt just
+                // gives a well-defined starting frame. Seed both rotation-source histories too.
                 const camera = this.context.mainCamera;
                 this.tempLookMatrix.lookAt(this._tempVec3, this._tempVec2, (camera as any as IGameObject).worldUp);
                 this._manipulatorObject.quaternion.setFromRotationMatrix(this.tempLookMatrix);
                 this._isFirstAlignFrame = false;
+                this._prevABDirection.copy(this._currABDir).normalize();
+                this._computeViewPlaneAB(this._prevViewTwistDir);
+            } else if (this._yawConstraintAxis) {
+                this._applyViewPlaneTwist(this._yawConstraintAxis);
             } else {
                 // Accumulate the rotation delta from previous A→B to current A→B.
                 // Guard against the degenerate ~180° flip case where setFromUnitVectors
                 // is undefined (dot ≈ -1).
+                this._currABDir.normalize();
                 if (this._prevABDirection.dot(this._currABDir) > -0.9999) {
                     _mtRotDelta.setFromUnitVectors(this._prevABDirection, this._currABDir);
                     this._manipulatorObject.quaternion.premultiply(_mtRotDelta);
                 }
+                this._prevABDirection.copy(this._currABDir);
             }
-            this._prevABDirection.copy(this._currABDir);
         }
 
         this._manipulatorObject.updateMatrix();
@@ -881,6 +925,51 @@ class MultiTouchDragHandler implements IDragHandler {
         }
     }
 
+    /** Projects the current world-space A→B direction (_currABDir) onto the plane perpendicular
+     *  to the camera forward — i.e. the grab line as it appears on screen — into `out`.
+     *  Also refreshes _viewForward. */
+    private _computeViewPlaneAB(out: Vector3): void {
+        const camera = this.context.mainCamera as unknown as IGameObject;
+        this._viewForward.copy(camera.worldForward);
+        out.copy(this._currABDir);
+        out.addScaledVector(this._viewForward, -out.dot(this._viewForward));
+    }
+
+    /** Maps the frame-to-frame on-screen twist of the two grab points to a yaw delta around
+     *  `axis` and premultiplies it onto the manipulator. Decouples gesture magnitude (screen
+     *  twist) from the applied axis (plane normal), so yaw stays controllable from any view. */
+    private _applyViewPlaneTwist(axis: Vector3): void {
+        this._computeViewPlaneAB(this._currViewTwistDir);
+        const prev = this._prevViewTwistDir;
+        const curr = this._currViewTwistDir;
+        const eps = 1e-8;
+        // Grab line points into the screen (fingers overlap) — no usable twist this frame.
+        if (curr.lengthSq() < eps) return;
+        if (prev.lengthSq() >= eps) {
+            // Signed twist of the grab line in the view plane, measured about the axis pointing
+            // toward the camera so a CCW-on-screen twist is positive.
+            _mtToEye.copy(this._viewForward).multiplyScalar(-1);
+            _mtCross.crossVectors(prev, curr);
+            const screenTwist = Math.atan2(_mtCross.dot(_mtToEye), prev.dot(curr));
+
+            // Sign by which side of the plane the camera sits on. This is stable through a
+            // side-on view (where "CCW on screen" is otherwise ill-defined) and correctly
+            // inverts the gesture when viewing the plane from below. It also agrees with the
+            // visual sense wherever that is well-defined, so tilting the view never flips it.
+            const camPos = (this.context.mainCamera as unknown as IGameObject).worldPosition;
+            _mtCamOffset.copy(camPos).sub(this._tempVec3);
+            const side = axis.dot(_mtCamOffset) >= 0 ? -1 : 1;
+
+            const yaw = screenTwist * side;
+            if (yaw !== 0) {
+                _mtRotDelta.setFromAxisAngle(axis, yaw);
+                this._manipulatorObject.quaternion.premultiply(_mtRotDelta);
+            }
+            if (debug) Gizmos.DrawLabel(this._tempVec3, `twist ${yaw.toFixed(3)}`, 0.03);
+        }
+        prev.copy(curr);
+    }
+
     onDragUpdate() {
         // At this point we've run both the other handlers, but their effects have been suppressed because they can't handle
         // two events at the same time. They're basically providing us with two Object3D's and we can combine these here
@@ -927,6 +1016,23 @@ class MultiTouchDragHandler implements IDragHandler {
         // scale-aware constraints (e.g. XZPlaneDragStrategy's bounds-bottom height lock).
         // Pass 1 when keepScale is true so the correction is a no-op.
         this.handlerA.currentStrategy.onTwoPointerScaleUpdate?.(keepScale ? 1 : this._currentScaleRatio);
+        // SnapToSurfaces: aim the constraint's snap ray from the pointer origins through the
+        // current grab midpoint, so the two-finger snap targets what the fingers point at —
+        // the same semantics as the single-pointer surface raycast (which uses the pointer ray).
+        if (this._snapToSurfaceConstraint) {
+            const spaceA = this.handlerA.followObject.parent;
+            const spaceB = this.handlerB.followObject.parent;
+            if (spaceA && spaceB) {
+                spaceA.getWorldPosition(_mtSnapRayOrigin);
+                _mtSnapRayOrigin.add(spaceB.getWorldPosition(_mtSnapRayDir)).multiplyScalar(0.5);
+                // _manipulatorObject is a scene child positioned at the world-space midpoint of
+                // the two grab points (set in alignManipulator earlier this frame).
+                _mtSnapRayDir.copy(this._manipulatorObject.position).sub(_mtSnapRayOrigin);
+                if (_mtSnapRayDir.lengthSq() > 1e-10) {
+                    this._snapToSurfaceConstraint.setRay(_mtSnapRayOrigin, _mtSnapRayDir.normalize());
+                }
+            }
+        }
         applyFollowObjectConstraints(this._followObject, this._activeConstraints);
 
         // TODO should use unscaled time here // some test for lerp speed depending on distance
@@ -1033,6 +1139,15 @@ export interface IDragPlaneStrategy {
      * implement this. Pass `1` when `keepScale` is true so the correction is a no-op.
      */
     onTwoPointerScaleUpdate?(ratio: number): void;
+    /**
+     * Optional: if this strategy locks the dragged object's rotation to a single world-space
+     * axis (e.g. {@link XZPlaneDragStrategy} yaw around the plane normal), return that axis.
+     * {@link MultiTouchDragHandler} uses it to map the on-screen two-finger twist directly to
+     * yaw around this axis, keeping rotation controllable from any view angle (including
+     * side-on). The vector is read live (not copied) and must stay unit-length for the drag.
+     * Undefined ⇒ free rotation.
+     */
+    readonly yawConstraintAxis?: Vector3;
 }
 
 /**
@@ -1046,9 +1161,6 @@ class SnapToSurfacesDragStrategy implements IDragPlaneStrategy {
     private _lastSurfacePlaneRefreshTime: number = 0;
     private _hasLastSurfaceHitPoint: boolean = false;
     private readonly _lastSurfaceHitPoint: Vector3 = new Vector3();
-    /** Original grab point (object local space) captured at drag start. Used to preserve the
-     *  surface-plane component of the grab offset when snapping to surfaces. */
-    private readonly _originalHitPointInLocalSpace: Vector3 = new Vector3();
     /** Context stored at initialize() time so getConstraints() can pass it to the multi-touch constraint. */
     private _context: Context | null = null;
 
@@ -1059,7 +1171,6 @@ class SnapToSurfacesDragStrategy implements IDragPlaneStrategy {
         this._draggedOverObjectLastNormal.set(0, 0, 0);
         this._lastSurfacePlaneRefreshTime = 0;
         this._hasLastSurfaceHitPoint = false;
-        this._originalHitPointInLocalSpace.set(0, 0, 0);
     }
 
     readonly requiresPlaneIntersection = true;
@@ -1068,10 +1179,6 @@ class SnapToSurfacesDragStrategy implements IDragPlaneStrategy {
         this._context = cx.context;
         cx.setPlaneViewAligned(hitWP, false);
         this.reset();
-        // Capture the exact point the user grabbed (in object local space). This is used
-        // to preserve the surface-plane component of the grab offset while only adjusting
-        // the normal-direction component to rest the object on the target surface.
-        this._originalHitPointInLocalSpace.copy(cx.hitPointInLocalSpace);
     }
 
     update(cx: IDragStrategyContext, ray: Ray, dragSource: IGameObject, draggedObject: Object3D | null): boolean | null {
@@ -1105,79 +1212,57 @@ class SnapToSurfacesDragStrategy implements IDragPlaneStrategy {
                 this._hasLastSurfaceHitPoint = true;
                 this._lastSurfaceHitPoint.copy(hit.point);
 
-                const dragTimeThreshold = 0.15;
-                const dragTimeSatisfied = this._draggedOverObjectDuration >= dragTimeThreshold;
-                const dragDistance = 0.001;
-                const dragDistanceSatisfied = cx.totalMovement.length() >= dragDistance;
                 // TODO: if the "hit.normal" is undefined we use the hit.face.normal which is still localspace
                 const worldNormal = getTempVector(hit.normal || hit.face.normal).applyQuaternion(hit.object.worldQuaternion);
 
-                // Detect whether the surface object or its normal has changed.
-                const needsAnchorUpdate = this._draggedOverObjectLastSetUp !== this._draggedOverObject
+                // Wait until the drag has actually started (enough hover time or pointer movement)
+                // before snapping to the surface, so a click that never becomes a drag doesn't move
+                // the object. Bail out BEFORE touching any snap state: the surface/normal bookkeeping
+                // below must only advance once a real drag is underway, otherwise the change-detection
+                // trigger is consumed on a pre-threshold frame and the anchor/plane refresh is skipped
+                // on the first frame that actually moves the object (leaving it on the stale
+                // view-aligned plane until the 1 s periodic refresh).
+                const dragTimeSatisfied = this._draggedOverObjectDuration >= 0.15;
+                const dragDistanceSatisfied = cx.totalMovement.length() >= 0.001;
+                if (!(dragTimeSatisfied || dragDistanceSatisfied)) {
+                    return null; // abort frame update — drag hasn't really started yet
+                }
+
+                // Refresh the anchor + drag plane when the surface object or its normal changes, and
+                // periodically on flat same-normal surfaces (e.g. stepping across multi-level floors).
+                // _draggedOverObjectLastNormal is stored in WORLD space to match worldNormal — it used
+                // to store the local face normal, so on any rotated surface the dot never reached 1 and
+                // this fired every frame.
+                const surfaceChanged = this._draggedOverObjectLastSetUp !== this._draggedOverObject
                     || this._draggedOverObjectLastNormal.dot(worldNormal) < 0.999999;
-                // Periodically refresh the drag plane on flat same-normal surfaces (e.g. multi-level floors).
-                const needsPlaneRefresh = needsAnchorUpdate
+                const needsRefresh = surfaceChanged
                     || (cx.context.time.time - this._lastSurfacePlaneRefreshTime) >= 1.0;
 
-                // Always update the grab anchor when the surface or normal changes — even BEFORE the
-                // movement threshold — so the first movement frame uses the correct anchor (no jump).
-                // The anchor preserves the original grab point's surface-plane components; only the
-                // normal-direction component is adjusted so the object rests flush on the surface.
-                if (needsAnchorUpdate) {
+                if (needsRefresh) {
+                    this._lastSurfacePlaneRefreshTime = cx.context.time.time;
                     this._draggedOverObjectLastSetUp = this._draggedOverObject;
-                    this._draggedOverObjectLastNormal.copy(hit.face.normal);
-
+                    this._draggedOverObjectLastNormal.copy(worldNormal);
+
+                    // Snap the OBJECT ORIGIN under the cursor: the origin's lateral position follows the
+                    // pointer→surface hit while the object's contact face rests on the surface. Where the
+                    // user grabbed is ignored, so placement is consistent regardless of grab point.
+                    // The origin is (0,0,0) in local space, so origin·normal = 0 and the anchor collapses
+                    // to the contact face projected onto the normal — the same anchor the multi-touch
+                    // SnapToSurfaceConstraint uses, so single- and two-pointer snapping now match.
                     const center = getTempVector();
                     const size = getTempVector();
                     cx.bounds.getCenter(center);
                     cx.bounds.getSize(size);
-                    // Surface-contact point: the face of the bounding box that touches the surface.
+                    // Contact face of the bounds along the surface normal (the face that rests on it).
+                    // NOTE: bounds are local/axis-aligned, so this assumes the object is upright w.r.t. the
+                    // surface normal — exact for the common keepRotation case, approximate if tilted.
                     center.sub(size.multiplyScalar(0.5).multiply(worldNormal));
-                    // Scalar projection of contact point onto the surface normal.
                     const contactAlongNormal = center.dot(worldNormal);
-                    // Scalar projection of the original grab point onto the same normal.
-                    const grabAlongNormal = this._originalHitPointInLocalSpace.dot(worldNormal);
-                    // Build the new anchor: keep the grab point's surface-plane offset, shift only
-                    // its normal component to match the contact surface (object rests on surface).
-                    cx.hitPointInLocalSpace
-                        .copy(this._originalHitPointInLocalSpace)
-                        .addScaledVector(worldNormal, contactAlongNormal - grabAlongNormal);
+                    cx.hitPointInLocalSpace.copy(worldNormal).multiplyScalar(contactAlongNormal);
                     cx.hitNormalInLocalSpace.copy(hit.face.normal);
-                }
 
-                // If the drag has just started and we're not yet really starting to update the
-                // object's position, wait until there's been enough movement or time.
-                // The anchor is already set correctly above so movement will begin without a jump.
-                if (!(dragTimeSatisfied || dragDistanceSatisfied)) {
-                    return null; // abort frame update
-                }
-
-                // Update the drag plane when the surface/normal changes or periodically.
-                if (needsPlaneRefresh) {
-                    this._lastSurfacePlaneRefreshTime = cx.context.time.time;
-
-                    // ensure plane is far enough up that we don't drag into the surface
-                    // Which offset we use here depends on the face normal direction we hit
-                    // If we hit the bottom, we want to use the top, and vice versa
-                    // To do this dynamically, we can find the intersection between our local bounds and the hit face normal (which is already in local space)
-                    const center = getTempVector();
-                    const size = getTempVector();
-                    cx.bounds.getCenter(center);
-                    cx.bounds.getSize(size);
-                    center.add(size.multiplyScalar(0.5).multiply(hit.face.normal));
-
-                    const offset = getTempVector(cx.hitPointInLocalSpace).add(center);
-                    cx.followObject.localToWorld(offset);
-
-                    // See https://linear.app/needle/issue/NE-5004
-                    // const offsetWP = this._followObject.worldPosition.sub(offset);
-                    const point = hit.point;//.sub(offsetWP);
-
-                    // Gizmos.DrawWireSphere(point, 2, 0xff0000, .3);
-                    // Gizmos.DrawDirection(point, worldNormal, 0xffff00, 1);
-                    // console.log(hit.normal)
-
-                    cx.dragPlane.setFromNormalAndCoplanarPoint(worldNormal, point);
+                    // Drag plane sits on the surface; the origin-anchor lands on the pointer→surface hit.
+                    cx.dragPlane.setFromNormalAndCoplanarPoint(worldNormal, hit.point);
                 }
             }
         }
@@ -1192,8 +1277,9 @@ class SnapToSurfacesDragStrategy implements IDragPlaneStrategy {
     getConstraints(ctx: IDragConstraintContext): IDragConstraint[] {
         // Single-pointer (boundsAtScaleOne === null): the existing update() + plane-intersection
         // path handles surface snapping; no constraint needed here.
-        // Multi-touch (boundsAtScaleOne !== null): inject a constraint that casts a downward
-        // ray each frame and directly snaps the follow object to the detected surface.
+        // Multi-touch (boundsAtScaleOne !== null): inject a constraint that snaps the follow
+        // object onto the surface the fingers point at. MultiTouchDragHandler aims its ray
+        // (pointer origins → grab midpoint) every frame, mirroring the single-pointer raycast.
         if (!ctx.boundsAtScaleOne || !this._context) return [];
         const c = new SnapToSurfaceConstraint(this._context);
         c.init(ctx);
@@ -1220,6 +1306,9 @@ class XZPlaneDragStrategy implements IDragPlaneStrategy {
     /** The fixed XZ plane established at drag start. Used as the clamping target. */
     readonly xzPlane = new Plane();
 
+    /** Two-finger twist maps to yaw around this axis — the plane normal (parent's world up). */
+    get yawConstraintAxis(): Vector3 { return this.xzPlane.normal; }
+
     private _inFallback = false;
     /** Stable world-space point on xzPlane, captured once when entering fallback mode. */
     private readonly _fallbackAnchor = new Vector3();
@@ -1448,6 +1537,26 @@ class DragPointerHandler implements IDragHandler {
         this._keepRotationConstraint = new KeepRotationConstraint();
     }
 
+    /**
+     * Re-derives the grab point from the current pointer ray ∩ drag plane so that when a
+     * two-pointer drag hands control back to this single pointer, the object keeps its current
+     * offset to the pointer instead of snapping the original (now stale) grab point back under it.
+     * Only needed for plane-intersection strategies — Attached-style modes re-base fully via
+     * {@link recenter}. Call BEFORE {@link recenter} so the recomputed grab-start distance and
+     * the constraint re-initialization use the rebased grab point.
+     */
+    rebaseGrabPointToPointer() {
+        if (!this._currentStrategy.requiresPlaneIntersection) return;
+        if (!this.gameObject || !this._followObject.parent) return;
+        const dragSource = this._followObject.parent as IGameObject;
+        const ray = new Ray(dragSource.worldPosition, dragSource.worldForward);
+        if (!ray.intersectPlane(this._dragPlane, this._tempVec)) return;
+        // Keep the new grab point on the constraint plane (it differs from _dragPlane in the
+        // XZPlane side-view fallback) so GrabPointPlaneConstraint doesn't add a one-time offset.
+        this._grabPointPlaneConstraint?.plane.projectPoint(this._tempVec, this._tempVec);
+        this._hitPointInLocalSpace.copy(this.gameObject.worldToLocal(this._tempVec));
+    }
+
     recenter() {
         if (!this._followObject.parent) {
             console.warn("Error: space follow object doesn't have parent but recenter() is called. This is likely a bug");