@relu-interactives/spatial-ecs 0.3.6 → 0.3.8

package/dist/{chunk-WRJ2K3LZ.js → chunk-LMTB4KQ4.js}

@@ -1,5 +1,5 @@
-import { resolveDracoDecoderPath, applyTransform, SHARED_MODEL_RESOURCE_FLAG } from './chunk-JRJ3CL5H.js';
-import { AnimationComponent, ModelComponent, CameraComponent, Object3DRef, Environment, Postprocessing, TransformComponent, PhysicsComponent, setPhysicsLiveRef, LightComponent, MaterialComponent, DEFAULT_MESH_GEOMETRY_PARAMETERS, MeshGeometryComponent, InstancedMeshComponent, ParentId, ScriptComponent, ScriptObjectComponent, XRRigComponent, VRTeleportAreaComponent, XRInteractableComponent, XRInteractorComponent, XRInteractorSideComponent, InstanceSlotComponent, Name, ImageComponent, SpriteComponent, VideoComponent, AudioComponent, ImageTarget, Selectable, PrefabNode, PrefabInstance } from './chunk-N4GKZ7IV.js';
+import { resolveDracoDecoderPath, applyTransform, SHARED_MODEL_RESOURCE_FLAG } from './chunk-L5BP727H.js';
+import { AnimationComponent, ModelComponent, CameraComponent, Object3DRef, Environment, Postprocessing, TransformComponent, PhysicsComponent, setPhysicsLiveRef, LightComponent, MaterialComponent, DEFAULT_MESH_GEOMETRY_PARAMETERS, MeshGeometryComponent, InstancedMeshComponent, ParentId, ScriptComponent, ScriptObjectComponent, XRRigComponent, VRTeleportAreaComponent, XRInteractableComponent, XRHandPoseComponent, createHandPoseEntry, XRInteractorComponent, XRInteractorSideComponent, InstanceSlotComponent, Name, ImageComponent, SpriteComponent, VideoComponent, AudioComponent, ImageTarget, Selectable, PrefabNode, PrefabInstance, handPoseDefinitionFor, getHandPosePreset } from './chunk-KVGGAL5V.js';
 import { __name } from './chunk-OY7ZODZP.js';
 import * as THREE7 from 'three';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
@@ -2795,6 +2795,10 @@ function buildComponentValueMaps(snapshot) {
       snapshot.components,
       "XRInteractorComponent"
     ),
+    xrHandPoseValues: readByComponent(
+      snapshot.components,
+      "XRHandPoseComponent"
+    ),
     xrInteractorSideValues: readByComponent(
       snapshot.components,
       "XRInteractorSideComponent"
@@ -2980,11 +2984,65 @@ function restorePostCreateComponents(world, objectManagementSystem, targetEntity
       if (typeof sourceInteractable.grabMode === "string") {
         interactable.grabMode = sourceInteractable.grabMode;
       }
+      if (typeof sourceInteractable.grabReach === "string") {
+        interactable.grabReach = sourceInteractable.grabReach;
+      }
+      if (typeof sourceInteractable.distanceBehavior === "string") {
+        interactable.distanceBehavior = sourceInteractable.distanceBehavior;
+      }
+      if (typeof sourceInteractable.grabGesture === "string") {
+        interactable.grabGesture = sourceInteractable.grabGesture;
+      }
+      if (typeof sourceInteractable.grabRadius === "number") {
+        interactable.grabRadius = sourceInteractable.grabRadius;
+      }
+      if (typeof sourceInteractable.throwOnRelease === "boolean") {
+        interactable.throwOnRelease = sourceInteractable.throwOnRelease;
+      }
+      if (typeof sourceInteractable.throwStrength === "number") {
+        interactable.throwStrength = sourceInteractable.throwStrength;
+      }
+      const grabPos = asRecord(sourceInteractable.grabOffsetPosition);
+      if (grabPos) {
+        interactable.grabOffsetPosition = {
+          x: typeof grabPos.x === "number" ? grabPos.x : 0,
+          y: typeof grabPos.y === "number" ? grabPos.y : 0,
+          z: typeof grabPos.z === "number" ? grabPos.z : 0
+        };
+      }
+      const grabRot = asRecord(sourceInteractable.grabOffsetRotation);
+      if (grabRot) {
+        interactable.grabOffsetRotation = {
+          x: typeof grabRot.x === "number" ? grabRot.x : 0,
+          y: typeof grabRot.y === "number" ? grabRot.y : 0,
+          z: typeof grabRot.z === "number" ? grabRot.z : 0
+        };
+      }
       if (typeof sourceInteractable.highlightOnHover === "boolean") {
         interactable.highlightOnHover = sourceInteractable.highlightOnHover;
       }
     }
   }
+  {
+    const sourceHandPose = asRecord(
+      values.xrHandPoseValues.get(sourceEntityId)
+    );
+    const handPose = world.getComponent(targetEntityId, XRHandPoseComponent);
+    if (sourceHandPose && handPose) {
+      if (typeof sourceHandPose.enabled === "boolean") {
+        handPose.enabled = sourceHandPose.enabled;
+      }
+      if (Array.isArray(sourceHandPose.poses)) {
+        handPose.poses = sourceHandPose.poses.map((entry) => asRecord(entry)).filter(
+          (entry) => entry !== null && typeof entry.id === "string"
+        ).map(
+          (entry) => createHandPoseEntry(
+            entry
+          )
+        );
+      }
+    }
+  }
   {
     const sourceInteractor = asRecord(
       values.xrInteractorValues.get(sourceEntityId)
@@ -4914,6 +4972,17 @@ var _Behaviour = class _Behaviour {
    *
    * @param input - The source doing the grabbing.
    */
+  /**
+   * A hand pose declared on this entity started being held.
+   *
+   * Fires once the pose has been sustained for its hold time, not the instant
+   * the fingers pass through it.
+   */
+  onHandPoseStart(_event) {
+  }
+  /** A held hand pose ended, or its hand stopped being tracked. */
+  onHandPoseEnd(_event) {
+  }
   onGrab(input) {
   }
   /** Called when this entity is released. Optional XR hook. */
@@ -6056,13 +6125,65 @@ function blankState(source) {
     squeezeEnd: false,
     axes: [],
     hasAxes: false,
-    buttons: []
+    buttons: [],
+    joints: null
   };
 }
 __name(blankState, "blankState");
+var JOINT_MATRIX_BUFFER = new Float32Array(25 * 16);
+function readHandJoints(frame, hand, referenceSpace, rigMatrix, existing) {
+  const names = [];
+  const spaces = [];
+  for (const [name, space] of hand) {
+    names.push(name);
+    spaces.push(space);
+  }
+  if (spaces.length === 0) return null;
+  const target = existing ?? {};
+  const matrix = new THREE7.Matrix4();
+  const buffer = spaces.length * 16 <= JOINT_MATRIX_BUFFER.length ? JOINT_MATRIX_BUFFER : new Float32Array(spaces.length * 16);
+  const fillPoses = frame.fillPoses;
+  if (typeof fillPoses === "function") {
+    let filled = false;
+    try {
+      filled = fillPoses.call(frame, spaces, referenceSpace, buffer);
+    } catch {
+      filled = false;
+    }
+    if (filled) {
+      for (let i = 0; i < names.length; i += 1) {
+        matrix.fromArray(buffer, i * 16).premultiply(rigMatrix);
+        const vector = target[names[i]] ?? new THREE7.Vector3();
+        vector.setFromMatrixPosition(matrix);
+        target[names[i]] = vector;
+      }
+      return target;
+    }
+  }
+  let anyTracked = false;
+  for (let i = 0; i < names.length; i += 1) {
+    const pose = frame.getJointPose?.(
+      spaces[i],
+      referenceSpace
+    );
+    if (!pose) {
+      target[names[i]] = void 0;
+      continue;
+    }
+    matrix.fromArray(pose.transform.matrix).premultiply(rigMatrix);
+    const vector = target[names[i]] ?? new THREE7.Vector3();
+    vector.setFromMatrixPosition(matrix);
+    target[names[i]] = vector;
+    anyTracked = true;
+  }
+  return anyTracked ? target : null;
+}
+__name(readHandJoints, "readHandJoints");
 var _XRInputSystem = class _XRInputSystem {
   constructor() {
     this.records = /* @__PURE__ */ new Map();
+    /** Reference-space → world matrix, rebuilt each frame from the XR rig. */
+    this.referenceToWorld = new THREE7.Matrix4();
     this.session = null;
     this.onSelectStart = /* @__PURE__ */ __name((event) => this.mark(event, "pendingSelectStart"), "onSelectStart");
     this.onSelectEnd = /* @__PURE__ */ __name((event) => this.mark(event, "pendingSelectEnd"), "onSelectEnd");
@@ -6142,6 +6263,14 @@ var _XRInputSystem = class _XRInputSystem {
     const referenceSpace = renderer.xr.getReferenceSpace();
     const frame = renderer.xr.getFrame?.();
     const live = /* @__PURE__ */ new Set();
+    const rigMatrix = this.referenceToWorld;
+    const rig = world.getCamera().parent;
+    if (rig) {
+      rig.updateMatrixWorld();
+      rigMatrix.copy(rig.matrixWorld);
+    } else {
+      rigMatrix.identity();
+    }
     for (const source of session.inputSources) {
       live.add(source);
       const record = this.ensureRecord(source);
@@ -6152,7 +6281,7 @@ var _XRInputSystem = class _XRInputSystem {
       if (frame && referenceSpace && source.targetRaySpace) {
         const pose = frame.getPose(source.targetRaySpace, referenceSpace);
         if (pose) {
-          const m = new THREE7.Matrix4().fromArray(pose.transform.matrix);
+          const m = new THREE7.Matrix4().fromArray(pose.transform.matrix).premultiply(rigMatrix);
           state.rayOrigin.setFromMatrixPosition(m);
           state.rayDirection.set(0, 0, -1).applyQuaternion(
             new THREE7.Quaternion().setFromRotationMatrix(m)
@@ -6162,7 +6291,7 @@ var _XRInputSystem = class _XRInputSystem {
       if (frame && referenceSpace && source.gripSpace) {
         const gripPose = frame.getPose(source.gripSpace, referenceSpace);
         if (gripPose) {
-          const m = new THREE7.Matrix4().fromArray(gripPose.transform.matrix);
+          const m = new THREE7.Matrix4().fromArray(gripPose.transform.matrix).premultiply(rigMatrix);
           state.gripPosition ?? (state.gripPosition = new THREE7.Vector3());
           state.gripQuaternion ?? (state.gripQuaternion = new THREE7.Quaternion());
           state.gripPosition.setFromMatrixPosition(m);
@@ -6172,6 +6301,17 @@ var _XRInputSystem = class _XRInputSystem {
         state.gripPosition = null;
         state.gripQuaternion = null;
       }
+      if (frame && referenceSpace && source.hand) {
+        state.joints = readHandJoints(
+          frame,
+          source.hand,
+          referenceSpace,
+          rigMatrix,
+          state.joints
+        );
+      } else {
+        state.joints = null;
+      }
       const gamepad = source.gamepad;
       if (gamepad) {
         state.axes = Array.from(gamepad.axes);
@@ -6236,20 +6376,84 @@ var _XRInputSystem = class _XRInputSystem {
 };
 __name(_XRInputSystem, "XRInputSystem");
 var XRInputSystem = _XRInputSystem;
+var VELOCITY_SAMPLES = 5;
+var MAX_SAMPLE_AGE_SECONDS = 0.2;
+var _ThrowVelocityTracker = class _ThrowVelocityTracker {
+  constructor() {
+    this.samples = [];
+  }
+  /** Record where the hand is now. Call once per frame while held. */
+  record(position, time) {
+    this.samples.push({ position: position.clone(), time });
+    if (this.samples.length > VELOCITY_SAMPLES) {
+      this.samples.shift();
+    }
+  }
+  /**
+   * Velocity to release with, in metres/second.
+   *
+   * Uses the FASTEST segment inside the window rather than the most recent or
+   * the window average. Users decelerate as they open their hand, so the last
+   * segment understates the throw and the average washes it out; peak speed is
+   * what matches the motion the user actually felt they made.
+   */
+  computeVelocity(now) {
+    const fresh = this.samples.filter(
+      (sample) => now - sample.time <= MAX_SAMPLE_AGE_SECONDS
+    );
+    if (fresh.length < 2) return new THREE7.Vector3();
+    let best = new THREE7.Vector3();
+    let bestSpeed = 0;
+    for (let i = 1; i < fresh.length; i += 1) {
+      const previous = fresh[i - 1];
+      const current = fresh[i];
+      const dt = current.time - previous.time;
+      if (dt <= 1e-5) continue;
+      const velocity = new THREE7.Vector3().subVectors(current.position, previous.position).divideScalar(dt);
+      const speed = velocity.length();
+      if (speed > bestSpeed) {
+        bestSpeed = speed;
+        best = velocity;
+      }
+    }
+    return best;
+  }
+  clear() {
+    this.samples.length = 0;
+  }
+};
+__name(_ThrowVelocityTracker, "ThrowVelocityTracker");
+var ThrowVelocityTracker = _ThrowVelocityTracker;
+function angularVelocityFrom(previous, current, deltaTime) {
+  if (deltaTime <= 1e-5) return new THREE7.Vector3();
+  const delta = current.clone().multiply(previous.clone().invert());
+  if (delta.w < 0) {
+    delta.set(-delta.x, -delta.y, -delta.z, -delta.w);
+  }
+  const angle = 2 * Math.acos(THREE7.MathUtils.clamp(delta.w, -1, 1));
+  const sinHalf = Math.sqrt(Math.max(0, 1 - delta.w * delta.w));
+  if (sinHalf < 1e-6 || angle < 1e-6) return new THREE7.Vector3();
+  return new THREE7.Vector3(delta.x, delta.y, delta.z).divideScalar(sinHalf).multiplyScalar(angle / deltaTime);
+}
+__name(angularVelocityFrom, "angularVelocityFrom");
+
+// core/systems/XRInteractionSystem.ts
 var RAYLESS_HOLD_DISTANCE = 0.5;
 var _XRInteractionSystem = class _XRInteractionSystem {
   constructor(inputSystem) {
     this.raycaster = new THREE7.Raycaster();
-    /** Which entity each source is holding. Keyed by source state identity. */
     this.grabs = /* @__PURE__ */ new Map();
     this.hoveredEntityId = null;
+    /** Monotonic seconds, accumulated from deltaTime for velocity sampling. */
+    this.elapsed = 0;
     this.inputSystem = inputSystem;
   }
-  update(world) {
+  update(world, deltaTime) {
     if (!world.isXrPresenting()) {
       this.releaseAll(world);
       return;
     }
+    this.elapsed += Math.max(0, deltaTime);
     const inputs = this.inputSystem.getInputs();
     const interactables = this.collectInteractables(world);
     this.hoveredEntityId = null;
@@ -6260,29 +6464,100 @@ var _XRInteractionSystem = class _XRInteractionSystem {
       }
       const held = this.grabs.get(input);
       if (held) {
-        this.moveHeld(world, input, held);
-        if (input.selectEnd) this.release(world, input);
+        this.moveHeld(world, input, held, deltaTime);
+        if (this.wantsRelease(world, input, held)) {
+          this.release(world, input);
+        }
         continue;
       }
-      const hitEntityId = this.raycast(input, interactables);
-      if (hitEntityId === null) continue;
+      const candidate = this.findGrabCandidate(world, input, interactables);
+      if (candidate === null) continue;
       if (this.hoveredEntityId === null) {
-        this.hoveredEntityId = hitEntityId;
+        this.hoveredEntityId = candidate.entityId;
       }
       const interactable = world.getComponent(
-        hitEntityId,
+        candidate.entityId,
         XRInteractableComponent
       );
-      if (input.selectStart && interactable?.grabbable) {
-        this.grab(world, input, hitEntityId);
+      if (interactable?.grabbable && this.gestureMatches(
+        input,
+        interactable,
+        /* starting */
+        true
+      )) {
+        this.grab(world, input, candidate.entityId, candidate.viaDistance);
+      }
+    }
+  }
+  /** Whether the grab gesture for this object is currently starting. */
+  gestureMatches(input, interactable, starting) {
+    const pinch = starting ? input.selectStart : input.select;
+    const full = starting ? input.squeezeStart : input.squeeze;
+    switch (interactable.grabGesture) {
+      case "pinch":
+        return pinch;
+      case "full":
+        return full;
+      default:
+        return pinch || full;
+    }
+  }
+  /** True once the gesture that started the grab has ended. */
+  wantsRelease(world, input, held) {
+    const interactable = world.getComponent(
+      held.entityId,
+      XRInteractableComponent
+    );
+    if (!interactable) return true;
+    switch (interactable.grabGesture) {
+      case "pinch":
+        return input.selectEnd || !input.select;
+      case "full":
+        return input.squeezeEnd || !input.squeeze;
+      default:
+        return !input.select && !input.squeeze;
+    }
+  }
+  /**
+   * Find what this hand would grab: a physically-reachable object first, then
+   * one along the pointer ray.
+   *
+   * Proximity wins over the ray so that reaching for something you are touching
+   * never picks up a distant object behind it, which feels broken.
+   */
+  findGrabCandidate(world, input, interactables) {
+    const hand = this.handPosition(input);
+    let nearestId = null;
+    let nearestDistance = Number.POSITIVE_INFINITY;
+    for (const entry of interactables) {
+      const interactable2 = world.getComponent(
+        entry.entityId,
+        XRInteractableComponent
+      );
+      if (!interactable2) continue;
+      if (interactable2.grabReach === "distance") continue;
+      const position = new THREE7.Vector3();
+      entry.object.getWorldPosition(position);
+      const distance = position.distanceTo(hand);
+      if (distance <= interactable2.grabRadius && distance < nearestDistance) {
+        nearestDistance = distance;
+        nearestId = entry.entityId;
       }
     }
+    if (nearestId !== null) {
+      return { entityId: nearestId, viaDistance: false };
+    }
+    const hitId = this.raycast(input, interactables);
+    if (hitId === null) return null;
+    const interactable = world.getComponent(hitId, XRInteractableComponent);
+    const viaDistanceAllowed = interactable?.grabReach === "distance" || interactable?.grabReach === "both";
+    return { entityId: hitId, viaDistance: viaDistanceAllowed };
   }
   collectInteractables(world) {
     const out = [];
     for (const entityId of world.query(XRInteractableComponent, Object3DRef)) {
       const interactable = world.getComponent(entityId, XRInteractableComponent);
-      if (!interactable?.enabled || !interactable.pointable) continue;
+      if (!interactable?.enabled) continue;
       if (!world.isEntityVisible(entityId)) continue;
       const object = world.getComponent(entityId, Object3DRef)?.object;
       if (object) out.push({ entityId, object });
@@ -6293,6 +6568,7 @@ var _XRInteractionSystem = class _XRInteractionSystem {
   raycast(input, interactables) {
     if (interactables.length === 0) return null;
     this.raycaster.set(input.rayOrigin, input.rayDirection);
+    this.raycaster.far = Number.POSITIVE_INFINITY;
     let nearestId = null;
     let nearestDistance = Number.POSITIVE_INFINITY;
     for (const entry of interactables) {
@@ -6305,43 +6581,120 @@ var _XRInteractionSystem = class _XRInteractionSystem {
     }
     return nearestId;
   }
-  grab(world, input, entityId) {
+  grab(world, input, entityId, viaDistance) {
     const transform = world.getComponent(entityId, TransformComponent);
-    if (!transform) return;
+    const interactable = world.getComponent(entityId, XRInteractableComponent);
+    if (!transform || !interactable) return;
     const hand = this.handPosition(input);
-    const offset = new THREE7.Vector3(
-      transform.position.x - hand.x,
-      transform.position.y - hand.y,
-      transform.position.z - hand.z
-    );
+    const handQuaternion = this.handQuaternion(input);
+    const remote = viaDistance && interactable.distanceBehavior === "remote";
+    let offset;
+    let remoteDistance = 0;
+    if (remote) {
+      const position = new THREE7.Vector3(
+        transform.position.x,
+        transform.position.y,
+        transform.position.z
+      );
+      remoteDistance = position.distanceTo(input.rayOrigin);
+      offset = new THREE7.Vector3();
+    } else if (viaDistance) {
+      offset = new THREE7.Vector3(
+        interactable.grabOffsetPosition.x,
+        interactable.grabOffsetPosition.y,
+        interactable.grabOffsetPosition.z
+      );
+    } else {
+      offset = new THREE7.Vector3(
+        transform.position.x - hand.x,
+        transform.position.y - hand.y,
+        transform.position.z - hand.z
+      );
+    }
     const physics = world.getComponent(entityId, PhysicsComponent);
     let restoreBodyType = null;
-    const interactable = world.getComponent(entityId, XRInteractableComponent);
-    if (physics && interactable?.grabMode === "kinematic") {
+    if (physics) {
       restoreBodyType = physics.values.rigidbody.type;
       physics.values.rigidbody.type = "kinematicPosition";
     }
-    this.grabs.set(input, { entityId, offset, restoreBodyType });
+    const tracker = new ThrowVelocityTracker();
+    tracker.record(hand, this.elapsed);
+    this.grabs.set(input, {
+      entityId,
+      offset,
+      rotationOffset: new THREE7.Quaternion().setFromEuler(
+        new THREE7.Euler(
+          interactable.grabOffsetRotation.x,
+          interactable.grabOffsetRotation.y,
+          interactable.grabOffsetRotation.z
+        )
+      ),
+      remoteDistance,
+      remote,
+      restoreBodyType,
+      tracker,
+      lastHandQuaternion: handQuaternion.clone(),
+      angularVelocity: new THREE7.Vector3()
+    });
     this.dispatch(world, entityId, (b) => b.onGrab(input));
   }
-  moveHeld(world, input, held) {
+  moveHeld(world, input, held, deltaTime) {
     const transform = world.getComponent(held.entityId, TransformComponent);
     if (!transform) return;
     const hand = this.handPosition(input);
-    transform.position.x = hand.x + held.offset.x;
-    transform.position.y = hand.y + held.offset.y;
-    transform.position.z = hand.z + held.offset.z;
+    if (held.remote) {
+      const target = new THREE7.Vector3().copy(input.rayDirection).multiplyScalar(held.remoteDistance).add(input.rayOrigin);
+      transform.position.x = target.x;
+      transform.position.y = target.y;
+      transform.position.z = target.z;
+    } else {
+      transform.position.x = hand.x + held.offset.x;
+      transform.position.y = hand.y + held.offset.y;
+      transform.position.z = hand.z + held.offset.z;
+    }
+    held.tracker.record(
+      held.remote ? new THREE7.Vector3(
+        transform.position.x,
+        transform.position.y,
+        transform.position.z
+      ) : hand,
+      this.elapsed
+    );
+    const handQuaternion = this.handQuaternion(input);
+    held.angularVelocity = angularVelocityFrom(
+      held.lastHandQuaternion,
+      handQuaternion,
+      deltaTime
+    );
+    held.lastHandQuaternion = handQuaternion;
   }
   release(world, input) {
     const held = this.grabs.get(input);
     if (!held) return;
     this.grabs.delete(input);
-    if (held.restoreBodyType !== null) {
-      const physics = world.getComponent(held.entityId, PhysicsComponent);
-      if (physics) {
-        physics.values.rigidbody.type = held.restoreBodyType;
+    const interactable = world.getComponent(
+      held.entityId,
+      XRInteractableComponent
+    );
+    const physics = world.getComponent(held.entityId, PhysicsComponent);
+    if (held.restoreBodyType !== null && physics) {
+      physics.values.rigidbody.type = held.restoreBodyType;
+      const body = physics.rigidBody;
+      const dynamic = held.restoreBodyType === "dynamic";
+      if (body && dynamic && interactable?.throwOnRelease) {
+        const velocity = held.tracker.computeVelocity(this.elapsed).multiplyScalar(interactable.throwStrength);
+        try {
+          body.setLinvel(
+            { x: velocity.x, y: velocity.y, z: velocity.z },
+            true
+          );
+          const spin = held.angularVelocity;
+          body.setAngvel({ x: spin.x, y: spin.y, z: spin.z }, true);
+        } catch {
+        }
       }
     }
+    held.tracker.clear();
     this.dispatch(world, held.entityId, (b) => b.onRelease(input));
   }
   releaseAll(world) {
@@ -6350,14 +6703,25 @@ var _XRInteractionSystem = class _XRInteractionSystem {
     }
   }
   /**
-   * Where the "hand" is for this source. Controllers and tracked hands report a
-   * grip pose; gaze and transient-pointer sources have none, so we hold the
-   * object a fixed distance along the ray instead.
+   * Where the "hand" is. Controllers and tracked hands report a grip pose;
+   * gaze and transient-pointer sources have none, so we hold the object a fixed
+   * distance along the ray instead — which is what makes Vision Pro work.
    */
   handPosition(input) {
     if (input.gripPosition) return input.gripPosition;
     return new THREE7.Vector3().copy(input.rayDirection).multiplyScalar(RAYLESS_HOLD_DISTANCE).add(input.rayOrigin);
   }
+  /**
+   * Hand orientation. Grip-less sources (gaze / transient-pointer) have none,
+   * so we derive one from the aim direction — enough for spin on release.
+   */
+  handQuaternion(input) {
+    if (input.gripQuaternion) return input.gripQuaternion.clone();
+    return new THREE7.Quaternion().setFromUnitVectors(
+      new THREE7.Vector3(0, 0, -1),
+      input.rayDirection.clone().normalize()
+    );
+  }
   dispatch(world, entityId, visit) {
     const script = world.getComponent(entityId, ScriptComponent);
     const instances = script?.scriptInstances;
@@ -6433,6 +6797,10 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     /** Curve up to the landing point, for the visual system. Empty when not aiming. */
     this.aimCurve = [];
     this.landingPoint = null;
+    /** True when the current aim lands somewhere the player may actually stand. */
+    this.aimValid = false;
+    /** Sources currently aiming via thumbstick (hysteresis, so it doesn't chatter). */
+    this.stickAiming = /* @__PURE__ */ new WeakSet();
     /** True once we've tried to self-heal camera parenting for this session. */
     this.parentingChecked = false;
     this.inputSystem = inputSystem;
@@ -6440,6 +6808,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
   update(world, deltaTime) {
     this.aimCurve = [];
     this.landingPoint = null;
+    this.aimValid = false;
     if (!world.isXrPresenting()) {
       this.parentingChecked = false;
       return;
@@ -6447,6 +6816,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     if (!this.parentingChecked) {
       this.parentingChecked = true;
       this.ensureCameraUnderRig(world);
+      this.warnOnIncompleteSetup(world);
     }
     const rigEntityId = world.query(XRRigComponent, TransformComponent)[0];
     if (typeof rigEntityId !== "number") return;
@@ -6464,6 +6834,26 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
       this.applySmoothMove(world, rig, rigTransform, inputs, deltaTime);
     }
   }
+  /**
+   * Name what is missing, once per session.
+   *
+   * Inside a headset there is no console and no inspector, so a scene that
+   * simply cannot move gives the author nothing to go on. These messages are
+   * visible over remote debugging and say exactly which entity to add.
+   */
+  warnOnIncompleteSetup(world) {
+    if (typeof world.query(XRRigComponent)[0] !== "number") {
+      console.warn(
+        "[XRLocomotion] No XR Rig in this scene \u2014 the player cannot move. Add one via Add Object \u2192 VR \u2192 XR Rig (the scene camera is parented to it automatically)."
+      );
+      return;
+    }
+    if (world.query(VRTeleportAreaComponent).length === 0) {
+      console.warn(
+        "[XRLocomotion] No Teleport Area in this scene \u2014 teleport has nowhere to land. Add one via Add Object \u2192 VR \u2192 Teleport Area, or add a Teleport Area component to an existing floor."
+      );
+    }
+  }
   /**
    * Guarantee the render camera is a CHILD of the rig.
    *
@@ -6531,29 +6921,60 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
   }
   applyTeleport(world, transform, inputs) {
     const targets = this.collectTeleportTargets(world);
-    if (targets.length === 0) return;
     for (const input of inputs) {
-      if (!input.select && !input.selectEnd) continue;
+      const source = input;
+      const stick = this.readStickAim(input, source);
+      const aiming = input.select || stick.aiming;
+      const commit = input.selectEnd || stick.released;
+      if (!aiming && !commit) continue;
       const points = sampleTeleportArc(
         input.rayOrigin,
         input.rayDirection,
         this.arcPoints
       );
       const hit = this.raycastArc(points, targets);
-      if (!hit) continue;
-      this.landingPoint = hit.point;
-      this.aimCurve = points.slice(0, hit.segmentIndex + 1).concat(hit.point);
-      if (input.selectEnd) {
+      this.aimCurve = hit ? points.slice(0, hit.segmentIndex + 1).concat(hit.point) : points.slice();
+      this.landingPoint = hit ? hit.point : null;
+      this.aimValid = hit !== null;
+      if (commit && hit) {
         transform.position.x = hit.point.x;
         transform.position.y = hit.point.y;
         transform.position.z = hit.point.z;
         this.aimCurve = [];
         this.landingPoint = null;
+        this.aimValid = false;
+      } else if (commit) {
+        this.aimCurve = [];
+        this.aimValid = false;
       }
     }
   }
+  /**
+   * Thumbstick-forward aiming with hysteresis.
+   *
+   * Engaging at 0.6 and releasing at 0.3 stops a stick resting near the
+   * threshold from flickering the arc on and off — and the release edge is what
+   * commits the teleport, so chatter there would teleport the player randomly.
+   */
+  readStickAim(input, source) {
+    if (!input.hasAxes || input.axes.length < 4) {
+      return { aiming: false, released: false };
+    }
+    const forward = -(input.axes[3] ?? 0);
+    const wasAiming = this.stickAiming.has(source);
+    if (!wasAiming && forward > 0.6) {
+      this.stickAiming.add(source);
+      return { aiming: true, released: false };
+    }
+    if (wasAiming && forward < 0.3) {
+      this.stickAiming.delete(source);
+      return { aiming: false, released: true };
+    }
+    return { aiming: wasAiming, released: false };
+  }
   /** Walk the arc segment-by-segment, returning the first surface hit. */
   raycastArc(points, targets) {
+    if (targets.length === 0) return null;
     for (let i = 1; i < points.length; i += 1) {
       const from = points[i - 1];
       const to = points[i];
@@ -6584,6 +7005,10 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
   getAimCurve() {
     return this.aimCurve;
   }
+  /** True when the aim lands on a valid teleport area. */
+  isAimValid() {
+    return this.aimValid;
+  }
   /** Where the arc currently lands, or null when not aiming at a valid area. */
   getLandingPoint() {
     return this.landingPoint;
@@ -6866,6 +7291,7 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
     this.handStyleSignature = "";
     this.handMaterial = null;
     this.interactionSystem = options?.interactionSystem ?? null;
+    this.inputSystem = options?.inputSystem ?? null;
     this.group.name = "XRControllerVisuals";
     this.group.userData.ecsPreviewHidden = true;
   }
@@ -6882,8 +7308,11 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
     for (const { index, side } of SLOTS) {
       const visuals = this.slots.get(index);
       if (!visuals) continue;
-      visuals.controllerModel.visible = showControllers;
-      visuals.handModel.visible = showHands;
+      const liveKind = this.liveKindFor(side);
+      const hasController = liveKind === null || liveKind === "controller";
+      const hasHand = liveKind === null || liveKind === "hand";
+      visuals.controllerModel.visible = showControllers && hasController;
+      visuals.handModel.visible = showHands && hasHand;
       visuals.ray.visible = this.shouldShowRay(interactor);
       if (showHands && this.handMaterial) {
         applyHandMaterial(visuals.handModel, this.handMaterial);
@@ -6891,6 +7320,20 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
       this.syncCustomContent(world, visuals, side);
     }
   }
+  /**
+   * What kind of source is currently driving this hand, or null when we cannot
+   * tell (no input system wired) — in which case callers fall back to showing
+   * everything rather than hiding the user's hands entirely.
+   */
+  liveKindFor(side) {
+    if (!this.inputSystem) return null;
+    const inputs = this.inputSystem.getInputs();
+    if (inputs.length === 0) return null;
+    for (const input of inputs) {
+      if (input.handedness === side && input.connected) return input.kind;
+    }
+    return "none";
+  }
   /** The scene's interactor config, if one was authored. */
   resolveInteractor(world) {
     const entityId = world.query(XRInteractorComponent)[0];
@@ -7030,6 +7473,7 @@ __name(_XRControllerVisualSystem, "XRControllerVisualSystem");
 var XRControllerVisualSystem = _XRControllerVisualSystem;
 var MARKER_RADIUS = 0.28;
 var ACCENT = new THREE7.Color("#4da3ff");
+var BLOCKED = new THREE7.Color("#ff5a5a");
 var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
   constructor(locomotionSystem) {
     this.group = new THREE7.Group();
@@ -7060,16 +7504,22 @@ var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
     }
     const curve = this.locomotionSystem.getAimCurve();
     const landing = this.locomotionSystem.getLandingPoint();
-    if (!landing || curve.length < 2) {
+    const valid = this.locomotionSystem.isAimValid();
+    if (curve.length < 2) {
       this.setVisible(false);
       return;
     }
-    this.updateArcGeometry(curve);
-    this.marker.position.copy(landing);
-    this.marker.position.y += 0.01;
+    this.updateArcGeometry(curve, valid ? ACCENT : BLOCKED);
+    if (valid && landing) {
+      this.marker.position.copy(landing);
+      this.marker.position.y += 0.01;
+      this.marker.visible = true;
+    } else {
+      this.marker.visible = false;
+    }
     this.setVisible(true);
   }
-  updateArcGeometry(curve) {
+  updateArcGeometry(curve, tint) {
     const count = curve.length;
     const positions = new Float32Array(count * 3);
     const colors = new Float32Array(count * 3);
@@ -7080,9 +7530,9 @@ var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
       positions[i * 3 + 2] = point.z;
       const t = count > 1 ? i / (count - 1) : 0;
       const fade = 1 - t * 0.75;
-      colors[i * 3] = ACCENT.r * fade;
-      colors[i * 3 + 1] = ACCENT.g * fade;
-      colors[i * 3 + 2] = ACCENT.b * fade;
+      colors[i * 3] = tint.r * fade;
+      colors[i * 3 + 1] = tint.g * fade;
+      colors[i * 3 + 2] = tint.b * fade;
     }
     this.arcGeometry.setAttribute(
       "position",
@@ -7143,7 +7593,512 @@ var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
 };
 __name(_XRTeleportVisualSystem, "XRTeleportVisualSystem");
 var XRTeleportVisualSystem = _XRTeleportVisualSystem;
+var XR_FINGERS = [
+  "thumb",
+  "index",
+  "middle",
+  "ring",
+  "pinky"
+];
+var PINCH_FINGERS = [
+  "index",
+  "middle",
+  "ring",
+  "pinky"
+];
+var FINGER_CHAINS = {
+  thumb: [
+    "thumb-metacarpal",
+    "thumb-phalanx-proximal",
+    "thumb-phalanx-distal",
+    "thumb-tip"
+  ],
+  index: [
+    "index-finger-metacarpal",
+    "index-finger-phalanx-proximal",
+    "index-finger-phalanx-intermediate",
+    "index-finger-phalanx-distal",
+    "index-finger-tip"
+  ],
+  middle: [
+    "middle-finger-metacarpal",
+    "middle-finger-phalanx-proximal",
+    "middle-finger-phalanx-intermediate",
+    "middle-finger-phalanx-distal",
+    "middle-finger-tip"
+  ],
+  ring: [
+    "ring-finger-metacarpal",
+    "ring-finger-phalanx-proximal",
+    "ring-finger-phalanx-intermediate",
+    "ring-finger-phalanx-distal",
+    "ring-finger-tip"
+  ],
+  pinky: [
+    "pinky-finger-metacarpal",
+    "pinky-finger-phalanx-proximal",
+    "pinky-finger-phalanx-intermediate",
+    "pinky-finger-phalanx-distal",
+    "pinky-finger-tip"
+  ]
+};
+var TIP_JOINTS = {
+  thumb: "thumb-tip",
+  index: "index-finger-tip",
+  middle: "middle-finger-tip",
+  ring: "ring-finger-tip",
+  pinky: "pinky-finger-tip"
+};
+var METACARPAL_JOINTS = {
+  thumb: "thumb-metacarpal",
+  index: "index-finger-metacarpal",
+  middle: "middle-finger-metacarpal",
+  ring: "ring-finger-metacarpal",
+  pinky: "pinky-finger-metacarpal"
+};
+var FALLBACK_HAND_SCALE = 0.08;
+var STRAIGHT_COS = 0.95;
+var CURLED_COS = 0.55;
+function clamp01(value) {
+  return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+__name(clamp01, "clamp01");
+function boneDirections(joints, finger) {
+  const chain = FINGER_CHAINS[finger];
+  const directions = [];
+  for (let i = 1; i < chain.length; i += 1) {
+    const from = joints[chain[i - 1]];
+    const to = joints[chain[i]];
+    if (!from || !to) return null;
+    const direction = new THREE7.Vector3().subVectors(to, from);
+    if (direction.lengthSq() < 1e-12) return null;
+    directions.push(direction.normalize());
+  }
+  return directions.length >= 2 ? directions : null;
+}
+__name(boneDirections, "boneDirections");
+function bendAmounts(directions) {
+  const bends = [];
+  for (let i = 1; i < directions.length; i += 1) {
+    const cos = directions[i - 1].dot(directions[i]);
+    const straightness = clamp01((cos - CURLED_COS) / (STRAIGHT_COS - CURLED_COS));
+    bends.push(1 - straightness);
+  }
+  return bends;
+}
+__name(bendAmounts, "bendAmounts");
+function average(values) {
+  if (values.length === 0) return 0;
+  let sum = 0;
+  for (const value of values) sum += value;
+  return sum / values.length;
+}
+__name(average, "average");
+function computeFingerCurl(joints, finger) {
+  const directions = boneDirections(joints, finger);
+  if (!directions) return null;
+  const bends = bendAmounts(directions);
+  if (bends.length === 0) return null;
+  return {
+    baseCurl: bends[0],
+    tipCurl: average(bends.slice(1)) || bends[bends.length - 1],
+    curl: average(bends)
+  };
+}
+__name(computeFingerCurl, "computeFingerCurl");
+function computePalmWidth(joints) {
+  const index = joints["index-finger-metacarpal"];
+  const pinky = joints["pinky-finger-metacarpal"];
+  if (!index || !pinky) return null;
+  const width = index.distanceTo(pinky);
+  return width > 1e-6 ? width : null;
+}
+__name(computePalmWidth, "computePalmWidth");
+function estimateHandScale(joints) {
+  const measurements = [];
+  const width = computePalmWidth(joints);
+  if (width !== null) measurements.push(width);
+  const wrist = joints.wrist;
+  const middleTip = joints["middle-finger-tip"];
+  if (wrist && middleTip) {
+    const span = wrist.distanceTo(middleTip);
+    if (span > 1e-6) measurements.push(span * 0.5);
+  }
+  if (measurements.length === 0) return FALLBACK_HAND_SCALE;
+  return average(measurements);
+}
+__name(estimateHandScale, "estimateHandScale");
+function computePinch(joints, finger) {
+  const thumbTip = joints["thumb-tip"];
+  const fingerTip = joints[TIP_JOINTS[finger]];
+  if (!thumbTip || !fingerTip) return null;
+  const scale = estimateHandScale(joints);
+  const distance = thumbTip.distanceTo(fingerTip);
+  return clamp01(1 - distance / (scale * 0.7));
+}
+__name(computePinch, "computePinch");
+function computeSpread(joints, a, b) {
+  const aBase = joints[METACARPAL_JOINTS[a]];
+  const aTip = joints[TIP_JOINTS[a]];
+  const bBase = joints[METACARPAL_JOINTS[b]];
+  const bTip = joints[TIP_JOINTS[b]];
+  if (!aBase || !aTip || !bBase || !bTip) return null;
+  const dirA = new THREE7.Vector3().subVectors(aTip, aBase);
+  const dirB = new THREE7.Vector3().subVectors(bTip, bBase);
+  if (dirA.lengthSq() < 1e-12 || dirB.lengthSq() < 1e-12) return null;
+  return clamp01((1 - dirA.normalize().dot(dirB.normalize())) / 0.45);
+}
+__name(computeSpread, "computeSpread");
+function computePalmPose(joints, handedness) {
+  const wrist = joints.wrist;
+  const indexBase = joints["index-finger-metacarpal"];
+  const pinkyBase = joints["pinky-finger-metacarpal"];
+  if (!wrist || !indexBase || !pinkyBase) return null;
+  const u = new THREE7.Vector3().subVectors(indexBase, wrist);
+  const v = new THREE7.Vector3().subVectors(pinkyBase, wrist);
+  const normal = new THREE7.Vector3().crossVectors(u, v);
+  if (normal.lengthSq() < 1e-12) return null;
+  normal.normalize();
+  if (handedness === "left") normal.multiplyScalar(-1);
+  const right = new THREE7.Vector3().subVectors(indexBase, pinkyBase);
+  if (right.lengthSq() < 1e-12) return null;
+  right.normalize();
+  if (handedness === "left") right.multiplyScalar(-1);
+  const up = new THREE7.Vector3().crossVectors(normal, right).normalize();
+  const center = new THREE7.Vector3().add(wrist).add(indexBase).add(pinkyBase).divideScalar(3);
+  return {
+    center,
+    normal,
+    right,
+    up,
+    width: computePalmWidth(joints) ?? FALLBACK_HAND_SCALE
+  };
+}
+__name(computePalmPose, "computePalmPose");
+function computeHandShape(joints, handedness) {
+  const fingers = {};
+  let tracked = 0;
+  for (const finger of XR_FINGERS) {
+    const curl = computeFingerCurl(joints, finger);
+    if (curl) {
+      fingers[finger] = curl;
+      tracked += 1;
+    } else {
+      fingers[finger] = { baseCurl: 0, tipCurl: 0, curl: 0 };
+    }
+  }
+  if (tracked === 0) return null;
+  const pinch = {};
+  for (const finger of PINCH_FINGERS) {
+    pinch[finger] = computePinch(joints, finger) ?? 0;
+  }
+  const thumbBase = joints["thumb-metacarpal"];
+  const thumbTip = joints["thumb-tip"];
+  let thumbDirection = null;
+  if (thumbBase && thumbTip) {
+    const direction = new THREE7.Vector3().subVectors(thumbTip, thumbBase);
+    if (direction.lengthSq() > 1e-12) thumbDirection = direction.normalize();
+  }
+  return {
+    handedness,
+    fingers,
+    pinch,
+    spread: {
+      thumbIndex: computeSpread(joints, "thumb", "index") ?? 0,
+      indexMiddle: computeSpread(joints, "index", "middle") ?? 0,
+      middleRing: computeSpread(joints, "middle", "ring") ?? 0,
+      ringPinky: computeSpread(joints, "ring", "pinky") ?? 0
+    },
+    palm: computePalmPose(joints, handedness),
+    scale: estimateHandScale(joints),
+    thumbDirection
+  };
+}
+__name(computeHandShape, "computeHandShape");
+var MATCH_FALLOFF = 0.25;
+var NO_MATCH = {
+  matched: false,
+  confidence: 0,
+  worstConstraint: null
+};
+function scoreAgainst(actual, target, tolerance) {
+  const error = Math.abs(actual - target);
+  if (error <= tolerance) return 1;
+  return clamp01(1 - (error - tolerance) / MATCH_FALLOFF);
+}
+__name(scoreAgainst, "scoreAgainst");
+var WORLD_DIRECTIONS = {
+  up: new THREE7.Vector3(0, 1, 0),
+  down: new THREE7.Vector3(0, -1, 0),
+  forward: new THREE7.Vector3(0, 0, -1),
+  back: new THREE7.Vector3(0, 0, 1),
+  left: new THREE7.Vector3(-1, 0, 0),
+  right: new THREE7.Vector3(1, 0, 0)
+};
+function axisVector(shape, axis) {
+  if (axis === "thumb") return shape.thumbDirection;
+  if (!shape.palm) return null;
+  return axis === "palm-normal" ? shape.palm.normal : shape.palm.up;
+}
+__name(axisVector, "axisVector");
+function resolveDirection(direction, shape, context) {
+  if (direction !== "toward-head" && direction !== "away-from-head") {
+    return WORLD_DIRECTIONS[direction];
+  }
+  const head = context?.headPosition;
+  const origin = shape.palm?.center;
+  if (!head || !origin) return null;
+  const toHead = new THREE7.Vector3().subVectors(head, origin);
+  if (toHead.lengthSq() < 1e-12) return null;
+  toHead.normalize();
+  return direction === "toward-head" ? toHead : toHead.multiplyScalar(-1);
+}
+__name(resolveDirection, "resolveDirection");
+function matchHandPose(shape, definition, context) {
+  if (definition.hand && definition.hand !== shape.handedness) return NO_MATCH;
+  let confidence = 1;
+  let worstScore = 1;
+  let worstConstraint = null;
+  const consider = /* @__PURE__ */ __name((score, label) => {
+    if (score < confidence) confidence = score;
+    if (score < worstScore) {
+      worstScore = score;
+      worstConstraint = label;
+    }
+  }, "consider");
+  for (const finger of XR_FINGERS) {
+    const target = definition.fingers[finger];
+    if (!target) continue;
+    const actual = shape.fingers[finger];
+    consider(scoreAgainst(actual.curl, target.curl, target.tolerance), finger);
+    if (target.baseCurl !== void 0) {
+      consider(
+        scoreAgainst(actual.baseCurl, target.baseCurl, target.tolerance),
+        `${finger} knuckle`
+      );
+    }
+    if (target.tipCurl !== void 0) {
+      consider(
+        scoreAgainst(actual.tipCurl, target.tipCurl, target.tolerance),
+        `${finger} tip`
+      );
+    }
+  }
+  if (definition.pinch) {
+    const { finger, target, tolerance } = definition.pinch;
+    consider(
+      scoreAgainst(shape.pinch[finger], target, tolerance),
+      `${finger} pinch`
+    );
+  }
+  if (definition.orientation) {
+    const { axis, direction, toleranceDegrees } = definition.orientation;
+    const handAxis = axisVector(shape, axis);
+    const wanted = resolveDirection(direction, shape, context);
+    if (!handAxis || !wanted) {
+      consider(0, "orientation");
+    } else {
+      const angle = THREE7.MathUtils.radToDeg(
+        Math.acos(THREE7.MathUtils.clamp(handAxis.dot(wanted), -1, 1))
+      );
+      const normalizedError = Math.max(0, angle - toleranceDegrees) / 90;
+      consider(clamp01(1 - normalizedError / MATCH_FALLOFF), "orientation");
+    }
+  }
+  return {
+    matched: confidence >= 1,
+    confidence,
+    worstConstraint: confidence >= 1 ? null : worstConstraint
+  };
+}
+__name(matchHandPose, "matchHandPose");
+var DEFAULT_ENTER_CONFIDENCE = 0.8;
+var DEFAULT_EXIT_CONFIDENCE = 0.55;
+var DEFAULT_MIN_HOLD_SECONDS = 0.15;
+var DEFAULT_LOST_GRACE_SECONDS = 0.25;
+var _HandPoseTracker = class _HandPoseTracker {
+  constructor(options) {
+    this.active = false;
+    this.holdingSince = null;
+    this.lostSince = null;
+    this.enterConfidence = options?.enterConfidence ?? DEFAULT_ENTER_CONFIDENCE;
+    const exit = options?.exitConfidence ?? DEFAULT_EXIT_CONFIDENCE;
+    this.exitConfidence = Math.min(exit, this.enterConfidence - 1e-3);
+    this.minHoldSeconds = options?.minHoldSeconds ?? DEFAULT_MIN_HOLD_SECONDS;
+    this.lostGraceSeconds = options?.lostGraceSeconds ?? DEFAULT_LOST_GRACE_SECONDS;
+  }
+  isActive() {
+    return this.active;
+  }
+  /** Feed this frame's confidence. Returns an event on a transition. */
+  update(confidence, now) {
+    this.lostSince = null;
+    if (this.active) {
+      if (confidence < this.exitConfidence) {
+        this.active = false;
+        this.holdingSince = null;
+        return "end";
+      }
+      return null;
+    }
+    if (confidence >= this.enterConfidence) {
+      if (this.holdingSince === null) this.holdingSince = now;
+      if (now - this.holdingSince >= this.minHoldSeconds) {
+        this.active = true;
+        return "start";
+      }
+      return null;
+    }
+    this.holdingSince = null;
+    return null;
+  }
+  /** Feed a frame where the hand isn't tracked at all. */
+  miss(now) {
+    this.holdingSince = null;
+    if (!this.active) return null;
+    if (this.lostSince === null) this.lostSince = now;
+    if (now - this.lostSince < this.lostGraceSeconds) return null;
+    this.active = false;
+    this.lostSince = null;
+    return "end";
+  }
+  reset() {
+    this.active = false;
+    this.holdingSince = null;
+    this.lostSince = null;
+  }
+};
+__name(_HandPoseTracker, "HandPoseTracker");
+var HandPoseTracker = _HandPoseTracker;
+
+// core/systems/XRHandPoseSystem.ts
+var _XRHandPoseSystem = class _XRHandPoseSystem {
+  constructor(inputSystem) {
+    this.trackers = /* @__PURE__ */ new Map();
+    this.shapes = /* @__PURE__ */ new Map();
+    /** Reused so head-relative orientation checks allocate nothing per frame. */
+    this.headPosition = new THREE7.Vector3();
+    this.elapsed = 0;
+    this.inputSystem = inputSystem;
+  }
+  update(world, deltaTime) {
+    if (!world.isXrPresenting()) {
+      this.resetAll();
+      return;
+    }
+    this.elapsed += deltaTime;
+    this.refreshShapes();
+    const entries = this.collectEntries(world);
+    if (entries.length === 0) return;
+    world.getCamera().getWorldPosition(this.headPosition);
+    const context = { headPosition: this.headPosition };
+    for (const { entityId, entry } of entries) {
+      const definition = handPoseDefinitionFor(entry, getHandPosePreset);
+      if (!definition) continue;
+      for (const handedness of ["left", "right"]) {
+        if (entry.hand && entry.hand !== handedness) continue;
+        const key = `${entityId}:${entry.id}`;
+        const trackers = this.trackersFor(handedness);
+        let tracker = trackers.get(key);
+        if (!tracker) {
+          tracker = new HandPoseTracker({
+            minHoldSeconds: entry.minHoldSeconds
+          });
+          trackers.set(key, tracker);
+        }
+        const shape = this.shapes.get(handedness) ?? null;
+        if (!shape) {
+          if (tracker.miss(this.elapsed) === "end") {
+            this.dispatch(world, entityId, "end", {
+              poseId: entry.id,
+              poseName: entry.name,
+              handedness,
+              confidence: 0
+            });
+          }
+          continue;
+        }
+        const match = matchHandPose(shape, definition, context);
+        const event = tracker.update(match.confidence, this.elapsed);
+        if (event) {
+          this.dispatch(world, entityId, event, {
+            poseId: entry.id,
+            poseName: entry.name,
+            handedness,
+            confidence: match.confidence
+          });
+        }
+      }
+    }
+  }
+  /** Derive each hand's shape once for the whole frame. */
+  refreshShapes() {
+    for (const handedness of ["left", "right"]) {
+      const input = this.inputSystem.getInput(handedness);
+      const joints = input?.joints ?? null;
+      this.shapes.set(
+        handedness,
+        joints ? computeHandShape(joints, handedness) : null
+      );
+    }
+  }
+  collectEntries(world) {
+    const collected = [];
+    for (const entityId of world.query(XRHandPoseComponent)) {
+      const component = world.getComponent(entityId, XRHandPoseComponent);
+      if (!component?.enabled) continue;
+      for (const entry of component.poses) {
+        if (entry.enabled) collected.push({ entityId, entry });
+      }
+    }
+    return collected;
+  }
+  trackersFor(handedness) {
+    let trackers = this.trackers.get(handedness);
+    if (!trackers) {
+      trackers = /* @__PURE__ */ new Map();
+      this.trackers.set(handedness, trackers);
+    }
+    return trackers;
+  }
+  /**
+   * Deliver to the entity's own Behaviours.
+   *
+   * Scoped to the entity that declared the pose rather than broadcast, so two
+   * objects listening for the same gesture stay independent.
+   */
+  dispatch(world, entityId, event, detail) {
+    const script = world.getComponent(entityId, ScriptComponent);
+    const instances = script?.scriptInstances;
+    if (!instances) return;
+    for (const instance of instances.values()) {
+      if (!(instance instanceof Behaviour)) continue;
+      try {
+        if (event === "start") instance.onHandPoseStart(detail);
+        else instance.onHandPoseEnd(detail);
+      } catch (error) {
+        console.error("[XRHandPoseSystem] Behaviour hook failed:", error);
+      }
+    }
+  }
+  resetAll() {
+    for (const trackers of this.trackers.values()) {
+      for (const tracker of trackers.values()) tracker.reset();
+    }
+    this.shapes.clear();
+  }
+  /** Live shape for a hand — powers the editor's pose readout. */
+  getHandShape(handedness) {
+    return this.shapes.get(handedness) ?? null;
+  }
+  /** Whether a given entity's pose is currently held. */
+  isPoseActive(entityId, poseId, handedness) {
+    return this.trackers.get(handedness)?.get(`${entityId}:${poseId}`)?.isActive() ?? false;
+  }
+};
+__name(_XRHandPoseSystem, "XRHandPoseSystem");
+var XRHandPoseSystem = _XRHandPoseSystem;
 
-export { ADDED_NODE_MARKER_COMPONENT, ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, HYDRATABLE_ENTITY_KINDS, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, NODE_KEY_SEPARATOR, NO_XR_CAPABILITIES, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, SCRIPT_OBJECT_ROOT_FLAG, ScriptBehaviourSystem, ScriptObject, ScriptObjectSystem, TransformSyncSystem, VRTeleportAreaSystem, VideoSystem, XRControllerVisualSystem, XRInputSystem, XRInteractionSystem, XRLocomotionSystem, XRSessionSystem, XRTeleportVisualSystem, applyHandMaterial, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, createHandMaterial, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, readXrCapabilities, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, setPrefabAssetUrlResolver, spawnPrefab };
-//# sourceMappingURL=chunk-WRJ2K3LZ.js.map
-//# sourceMappingURL=chunk-WRJ2K3LZ.js.map
+export { ADDED_NODE_MARKER_COMPONENT, ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, AnimationSystem, AudioSystem, Behaviour, CURLED_COS, CameraSyncSystem, DEFAULT_ENTER_CONFIDENCE, DEFAULT_EXIT_CONFIDENCE, DEFAULT_LOST_GRACE_SECONDS, DEFAULT_MIN_HOLD_SECONDS, EnvironmentSyncSystem, FALLBACK_HAND_SCALE, HYDRATABLE_ENTITY_KINDS, HandPoseTracker, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MATCH_FALLOFF, MAX_SAMPLE_AGE_SECONDS, MaterialSyncSystem, MeshGeometrySystem, NODE_KEY_SEPARATOR, NO_XR_CAPABILITIES, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PINCH_FINGERS, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, SCRIPT_OBJECT_ROOT_FLAG, STRAIGHT_COS, ScriptBehaviourSystem, ScriptObject, ScriptObjectSystem, ThrowVelocityTracker, TransformSyncSystem, VELOCITY_SAMPLES, VRTeleportAreaSystem, VideoSystem, XRControllerVisualSystem, XRHandPoseSystem, XRInputSystem, XRInteractionSystem, XRLocomotionSystem, XRSessionSystem, XRTeleportVisualSystem, XR_FINGERS, angularVelocityFrom, applyHandMaterial, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeFingerCurl, computeHandShape, computeInstanceOverrides, computePalmPose, computePalmWidth, computePinch, computeSpread, createHandMaterial, decanonicalizeComponentValue, despawnPrefab, encodeOverride, estimateHandScale, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, matchHandPose, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, readXrCapabilities, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, setPrefabAssetUrlResolver, spawnPrefab };
+//# sourceMappingURL=chunk-LMTB4KQ4.js.map
+//# sourceMappingURL=chunk-LMTB4KQ4.js.map