@needle-tools/engine 5.1.4 → 5.1.5

package/lib/engine-components/DragControls.js

@@ -585,6 +585,13 @@ __decorate([
 ], DragControls.prototype, "dragEnded", void 0);
 /** 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
 /**
  * Handles two touch points affecting one object.
@@ -606,6 +613,9 @@ class MultiTouchDragHandler {
     _keepRotationConstraint = new KeepRotationConstraint();
     /** GrabPointPlaneConstraint returned by the active strategy (if any); used to sync snapResolution. */
     _planeConstraint = 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. */
+    _snapToSurfaceConstraint = null;
     _activeConstraints = [];
     constructor(dragControls, gameObject, pointerA, pointerB) {
         this.context = dragControls.context;
@@ -689,6 +699,7 @@ class MultiTouchDragHandler {
         };
         const strategyConstraints = this.handlerA.currentStrategy.getConstraints?.(constraintCx) ?? [];
         this._planeConstraint = strategyConstraints.find(c => c instanceof GrabPointPlaneConstraint) ?? null;
+        this._snapToSurfaceConstraint = strategyConstraints.find(c => c instanceof SnapToSurfaceConstraint) ?? null;
         const hasStrategyConstraints = strategyConstraints.length > 0;
         this._activeConstraints = [
             ...strategyConstraints,
@@ -699,6 +710,12 @@ class MultiTouchDragHandler {
             this._activeConstraints.push(this._keepRotationConstraint);
         }
         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();
         // and then parent it to the space object so it follows along.
@@ -713,7 +730,15 @@ class MultiTouchDragHandler {
             return;
         }
         // 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();
         // destroy helper objects
@@ -742,6 +767,15 @@ class MultiTouchDragHandler {
     _currABDir = new Vector3();
     /** True only for the very first `alignManipulator` call; triggers the one-time lookAt seed. */
     _isFirstAlignFrame = 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. */
+    _yawConstraintAxis = null;
+    /** Camera forward captured while computing the view-plane twist (scratch). */
+    _viewForward = new Vector3();
+    /** A→B projected into the view plane on the previous frame; reference for the twist delta. */
+    _prevViewTwistDir = new Vector3();
+    /** A→B projected into the view plane on the current frame (scratch). */
+    _currViewTwistDir = new Vector3();
     alignManipulator() {
         if (!this.handlerA || !this.handlerB) {
             console.error("alignManipulator called on MultiTouchDragHandler without valid handlers. This is likely a bug.", this);
@@ -763,34 +797,41 @@ class MultiTouchDragHandler {
         // separately and apply it directly to the dragged object in onDragUpdate.
         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.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();
         this._manipulatorObject.updateMatrixWorld(true);
@@ -801,6 +842,49 @@ class MultiTouchDragHandler {
             // Gizmos.DrawWireSphere(wp, this._initialScale.length() * dist / this._initialDistance, 0x00ff00, 0, false);
         }
     }
+    /** 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. */
+    _computeViewPlaneAB(out) {
+        const camera = this.context.mainCamera;
+        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. */
+    _applyViewPlaneTwist(axis) {
+        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.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
@@ -840,6 +924,23 @@ class MultiTouchDragHandler {
         // 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
         const t = Mathf.clamp01(this.context.time.deltaTime * lerpStrength * lerpFactor); // / (currentDist - 1 + 0.01));
@@ -877,9 +978,6 @@ class SnapToSurfacesDragStrategy {
     _lastSurfacePlaneRefreshTime = 0;
     _hasLastSurfaceHitPoint = false;
     _lastSurfaceHitPoint = 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. */
-    _originalHitPointInLocalSpace = new Vector3();
     /** Context stored at initialize() time so getConstraints() can pass it to the multi-touch constraint. */
     _context = null;
     reset() {
@@ -889,17 +987,12 @@ class SnapToSurfacesDragStrategy {
         this._draggedOverObjectLastNormal.set(0, 0, 0);
         this._lastSurfacePlaneRefreshTime = 0;
         this._hasLastSurfaceHitPoint = false;
-        this._originalHitPointInLocalSpace.set(0, 0, 0);
     }
     requiresPlaneIntersection = true;
     initialize(cx, hitWP, _rayDirection) {
         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, ray, dragSource, draggedObject) {
         const didHaveSurfaceHitPointLastFrame = this._hasLastSurfaceHitPoint;
@@ -928,69 +1021,52 @@ class SnapToSurfacesDragStrategy {
                 didHit = true;
                 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);
                 }
             }
         }
@@ -1003,8 +1079,9 @@ class SnapToSurfacesDragStrategy {
     getConstraints(ctx) {
         // 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);
@@ -1030,6 +1107,8 @@ class XZPlaneDragStrategy {
     requiresPlaneIntersection = true;
     /** The fixed XZ plane established at drag start. Used as the clamping target. */
     xzPlane = new Plane();
+    /** Two-finger twist maps to yaw around this axis — the plane normal (parent's world up). */
+    get yawConstraintAxis() { return this.xzPlane.normal; }
     _inFallback = false;
     /** Stable world-space point on xzPlane, captured once when entering fallback mode. */
     _fallbackAnchor = new Vector3();
@@ -1234,6 +1313,28 @@ class DragPointerHandler {
         this._gridSnapConstraint = new GridSnapConstraint(0);
         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;
+        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");