@relu-interactives/spatial-ecs 0.3.6 → 0.3.8

package/dist/index.cjs

@@ -2611,6 +2611,218 @@ function createVRTeleportAreaComponent(world, entityId, ...args) {
 }
 __name(createVRTeleportAreaComponent, "createVRTeleportAreaComponent");
 
+// core/xr/handPosePresets.ts
+var WIDE = 0.35;
+var NARROW = 0.25;
+var EXTENDED = { curl: 0.05, tolerance: WIDE };
+var CURLED = { curl: 0.95, tolerance: WIDE };
+var THUMB_TUCKED = { curl: 0.7, tolerance: NARROW + 0.1 };
+var THUMB_RELAXED = { curl: 0.6, tolerance: 0.4 };
+function fingers(thumb, index, middle, ring, pinky) {
+  return { thumb, index, middle, ring, pinky };
+}
+__name(fingers, "fingers");
+var THUMB_UP = {
+  axis: "thumb",
+  direction: "up",
+  toleranceDegrees: 45
+};
+var THUMB_DOWN = {
+  axis: "thumb",
+  direction: "down",
+  toleranceDegrees: 45
+};
+var HAND_POSE_PRESETS = {
+  fist: {
+    id: "fist",
+    name: "Fist",
+    fingers: fingers(THUMB_TUCKED, CURLED, CURLED, CURLED, CURLED)
+  },
+  "open-palm": {
+    id: "open-palm",
+    name: "Open Palm",
+    fingers: fingers(EXTENDED, EXTENDED, EXTENDED, EXTENDED, EXTENDED)
+  },
+  point: {
+    id: "point",
+    name: "Point",
+    fingers: fingers(THUMB_RELAXED, EXTENDED, CURLED, CURLED, CURLED)
+  },
+  "thumbs-up": {
+    id: "thumbs-up",
+    name: "Thumbs Up",
+    fingers: fingers(EXTENDED, CURLED, CURLED, CURLED, CURLED),
+    orientation: THUMB_UP
+  },
+  "thumbs-down": {
+    id: "thumbs-down",
+    name: "Thumbs Down",
+    fingers: fingers(EXTENDED, CURLED, CURLED, CURLED, CURLED),
+    orientation: THUMB_DOWN
+  },
+  peace: {
+    id: "peace",
+    name: "Peace",
+    fingers: fingers(THUMB_RELAXED, EXTENDED, EXTENDED, CURLED, CURLED)
+  },
+  pinch: {
+    id: "pinch",
+    name: "Pinch",
+    // Curl is left loose: what defines a pinch is the tips MEETING, and people
+    // pinch with wildly different amounts of finger bend.
+    fingers: fingers(
+      { curl: 0.5, tolerance: 0.5 },
+      { curl: 0.5, tolerance: 0.5 },
+      { curl: 0.5, tolerance: 0.5 },
+      { curl: 0.5, tolerance: 0.5 },
+      { curl: 0.5, tolerance: 0.5 }
+    ),
+    pinch: { finger: "index", target: 1, tolerance: 0.25 }
+  },
+  ok: {
+    id: "ok",
+    name: "OK Sign",
+    // Thumb and index meet in a ring while the rest stay up — that contrast with
+    // a plain pinch is the whole gesture, so the other three are constrained.
+    fingers: fingers(
+      { curl: 0.5, tolerance: 0.4 },
+      { curl: 0.55, tolerance: 0.35 },
+      EXTENDED,
+      EXTENDED,
+      EXTENDED
+    ),
+    pinch: { finger: "index", target: 1, tolerance: 0.3 }
+  },
+  gun: {
+    id: "gun",
+    name: "Gun",
+    fingers: fingers(EXTENDED, EXTENDED, CURLED, CURLED, CURLED)
+  },
+  rock: {
+    id: "rock",
+    name: "Rock Horns",
+    fingers: fingers(THUMB_TUCKED, EXTENDED, CURLED, CURLED, EXTENDED)
+  },
+  shaka: {
+    id: "shaka",
+    name: "Shaka",
+    fingers: fingers(EXTENDED, CURLED, CURLED, CURLED, EXTENDED)
+  },
+  "palm-up": {
+    id: "palm-up",
+    name: "Palm Up",
+    fingers: fingers(EXTENDED, EXTENDED, EXTENDED, EXTENDED, EXTENDED),
+    orientation: {
+      axis: "palm-normal",
+      direction: "up",
+      toleranceDegrees: 40
+    }
+  }
+};
+var HAND_POSE_PRESET_IDS = Object.keys(HAND_POSE_PRESETS);
+function getHandPosePreset(id) {
+  const preset = HAND_POSE_PRESETS[id];
+  if (!preset) return null;
+  return cloneHandPose(preset);
+}
+__name(getHandPosePreset, "getHandPosePreset");
+function cloneHandPose(definition) {
+  return {
+    ...definition,
+    fingers: {
+      thumb: { ...definition.fingers.thumb },
+      index: { ...definition.fingers.index },
+      middle: { ...definition.fingers.middle },
+      ring: { ...definition.fingers.ring },
+      pinky: { ...definition.fingers.pinky }
+    },
+    pinch: definition.pinch ? { ...definition.pinch } : void 0,
+    orientation: definition.orientation ? { ...definition.orientation } : void 0
+  };
+}
+__name(cloneHandPose, "cloneHandPose");
+function handPoseFromCurls(id, name, curls, options) {
+  const tolerance = options?.tolerance ?? NARROW;
+  const target = /* @__PURE__ */ __name((curl) => ({
+    curl: Math.min(1, Math.max(0, curl)),
+    tolerance
+  }), "target");
+  return {
+    id,
+    name,
+    fingers: {
+      thumb: target(curls.thumb),
+      index: target(curls.index),
+      middle: target(curls.middle),
+      ring: target(curls.ring),
+      pinky: target(curls.pinky)
+    },
+    pinch: options?.pinch,
+    orientation: options?.orientation,
+    hand: options?.hand
+  };
+}
+__name(handPoseFromCurls, "handPoseFromCurls");
+
+// core/components/XRHandPose.ts
+var DEFAULT_POSE_CURLS = {
+  thumb: 0,
+  index: 0,
+  middle: 0,
+  ring: 0,
+  pinky: 0
+};
+function createHandPoseEntry(partial) {
+  return {
+    id: partial.id,
+    name: partial.name ?? partial.id,
+    preset: partial.preset ?? null,
+    curls: { ...DEFAULT_POSE_CURLS, ...partial.curls },
+    tolerance: partial.tolerance ?? 0.25,
+    hand: partial.hand ?? null,
+    orientation: partial.orientation ?? null,
+    minHoldSeconds: partial.minHoldSeconds ?? 0.15,
+    enabled: partial.enabled ?? true
+  };
+}
+__name(createHandPoseEntry, "createHandPoseEntry");
+function handPoseDefinitionFor(entry, resolvePreset) {
+  if (entry.preset) {
+    const preset = resolvePreset(entry.preset);
+    if (!preset) return null;
+    return {
+      ...preset,
+      id: entry.id,
+      name: entry.name,
+      hand: entry.hand ?? preset.hand,
+      orientation: entry.orientation ?? preset.orientation
+    };
+  }
+  return handPoseFromCurls(entry.id, entry.name, entry.curls, {
+    tolerance: entry.tolerance,
+    orientation: entry.orientation ?? void 0,
+    hand: entry.hand ?? void 0
+  });
+}
+__name(handPoseDefinitionFor, "handPoseDefinitionFor");
+var _XRHandPoseComponent = class _XRHandPoseComponent extends Component {
+  constructor(options) {
+    super();
+    this.enabled = options?.enabled ?? true;
+    this.poses = (options?.poses ?? []).map((pose) => createHandPoseEntry(pose));
+  }
+};
+__name(_XRHandPoseComponent, "XRHandPoseComponent");
+var XRHandPoseComponent = _XRHandPoseComponent;
+
+// core/factories/components/XRHandPoseFactory.ts
+function createXRHandPoseComponent(world, entityId, ...args) {
+  const component = new XRHandPoseComponent(...args);
+  world.addComponent(entityId, component);
+  return component;
+}
+__name(createXRHandPoseComponent, "createXRHandPoseComponent");
+
 // core/components/XRInteractable.ts
 var _XRInteractableComponent = class _XRInteractableComponent extends Component {
   constructor(options) {
@@ -2619,6 +2831,22 @@ var _XRInteractableComponent = class _XRInteractableComponent extends Component
     this.grabbable = options?.grabbable ?? true;
     this.pointable = options?.pointable ?? true;
     this.grabMode = options?.grabMode ?? "kinematic";
+    this.grabReach = options?.grabReach ?? "both";
+    this.distanceBehavior = options?.distanceBehavior ?? "snap";
+    this.grabGesture = options?.grabGesture ?? "any";
+    this.grabRadius = options?.grabRadius ?? 0.15;
+    this.grabOffsetPosition = options?.grabOffsetPosition ?? {
+      x: 0,
+      y: 0,
+      z: 0
+    };
+    this.grabOffsetRotation = options?.grabOffsetRotation ?? {
+      x: 0,
+      y: 0,
+      z: 0
+    };
+    this.throwOnRelease = options?.throwOnRelease ?? true;
+    this.throwStrength = options?.throwStrength ?? 1;
     this.highlightOnHover = options?.highlightOnHover ?? true;
   }
 };
@@ -2683,6 +2911,7 @@ function registerDefaultComponentFactories(objectManagementSystem) {
   objectManagementSystem.registerComponentFactory("image", createImageComponent);
   objectManagementSystem.registerComponentFactory("xrRig", createXRRigComponent);
   objectManagementSystem.registerComponentFactory("vrTeleportArea", createVRTeleportAreaComponent);
+  objectManagementSystem.registerComponentFactory("xrHandPose", createXRHandPoseComponent);
   objectManagementSystem.registerComponentFactory("xrInteractable", createXRInteractableComponent);
   objectManagementSystem.registerComponentFactory("xrInteractor", createXRInteractorComponent);
   objectManagementSystem.registerComponentFactory("xrInteractorSide", createXRInteractorSideComponent);
@@ -3705,6 +3934,7 @@ __export(components_exports, {
   DEFAULT_INSTANCE_TRANSFORM: () => DEFAULT_INSTANCE_TRANSFORM,
   DEFAULT_MESH_GEOMETRY_PARAMETERS: () => DEFAULT_MESH_GEOMETRY_PARAMETERS,
   DEFAULT_PHYSICS_STATE: () => DEFAULT_PHYSICS_STATE,
+  DEFAULT_POSE_CURLS: () => DEFAULT_POSE_CURLS,
   DEFAULT_POSTPROCESSING_STATE: () => DEFAULT_POSTPROCESSING_STATE,
   DEFAULT_RIGIDBODY_STATE: () => DEFAULT_RIGIDBODY_STATE,
   EntityType: () => EntityType,
@@ -3734,11 +3964,14 @@ __export(components_exports, {
   TransformComponent: () => TransformComponent,
   VRTeleportAreaComponent: () => VRTeleportAreaComponent,
   VideoComponent: () => VideoComponent,
+  XRHandPoseComponent: () => XRHandPoseComponent,
   XRInteractableComponent: () => XRInteractableComponent,
   XRInteractorComponent: () => XRInteractorComponent,
   XRInteractorSideComponent: () => XRInteractorSideComponent,
   XRRigComponent: () => XRRigComponent,
+  createHandPoseEntry: () => createHandPoseEntry,
   defaultMaterialValue: () => defaultMaterialValue,
+  handPoseDefinitionFor: () => handPoseDefinitionFor,
   normalizePhysicsState: () => normalizePhysicsState,
   setPhysicsLiveRef: () => setPhysicsLiveRef
 });
@@ -4427,6 +4660,10 @@ function buildComponentValueMaps(snapshot) {
       snapshot.components,
       "XRInteractorComponent"
     ),
+    xrHandPoseValues: readByComponent(
+      snapshot.components,
+      "XRHandPoseComponent"
+    ),
     xrInteractorSideValues: readByComponent(
       snapshot.components,
       "XRInteractorSideComponent"
@@ -4612,11 +4849,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 = asRecord3(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 = asRecord3(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 = asRecord3(
+      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) => asRecord3(entry)).filter(
+          (entry) => entry !== null && typeof entry.id === "string"
+        ).map(
+          (entry) => createHandPoseEntry(
+            entry
+          )
+        );
+      }
+    }
+  }
   {
     const sourceInteractor = asRecord3(
       values.xrInteractorValues.get(sourceEntityId)
@@ -9178,6 +9469,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. */
@@ -10320,13 +10622,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 THREE39__namespace.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 THREE39__namespace.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 THREE39__namespace.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 THREE39__namespace.Matrix4();
     this.session = null;
     this.onSelectStart = /* @__PURE__ */ __name((event) => this.mark(event, "pendingSelectStart"), "onSelectStart");
     this.onSelectEnd = /* @__PURE__ */ __name((event) => this.mark(event, "pendingSelectEnd"), "onSelectEnd");
@@ -10406,6 +10760,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);
@@ -10416,7 +10778,7 @@ var _XRInputSystem = class _XRInputSystem {
       if (frame && referenceSpace && source.targetRaySpace) {
         const pose = frame.getPose(source.targetRaySpace, referenceSpace);
         if (pose) {
-          const m = new THREE39__namespace.Matrix4().fromArray(pose.transform.matrix);
+          const m = new THREE39__namespace.Matrix4().fromArray(pose.transform.matrix).premultiply(rigMatrix);
           state.rayOrigin.setFromMatrixPosition(m);
           state.rayDirection.set(0, 0, -1).applyQuaternion(
             new THREE39__namespace.Quaternion().setFromRotationMatrix(m)
@@ -10426,7 +10788,7 @@ var _XRInputSystem = class _XRInputSystem {
       if (frame && referenceSpace && source.gripSpace) {
         const gripPose = frame.getPose(source.gripSpace, referenceSpace);
         if (gripPose) {
-          const m = new THREE39__namespace.Matrix4().fromArray(gripPose.transform.matrix);
+          const m = new THREE39__namespace.Matrix4().fromArray(gripPose.transform.matrix).premultiply(rigMatrix);
           state.gripPosition ?? (state.gripPosition = new THREE39__namespace.Vector3());
           state.gripQuaternion ?? (state.gripQuaternion = new THREE39__namespace.Quaternion());
           state.gripPosition.setFromMatrixPosition(m);
@@ -10436,6 +10798,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);
@@ -10500,20 +10873,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 THREE39__namespace.Vector3();
+    let best = new THREE39__namespace.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 THREE39__namespace.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 THREE39__namespace.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(THREE39__namespace.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 THREE39__namespace.Vector3();
+  return new THREE39__namespace.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 THREE39__namespace.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;
@@ -10524,29 +10961,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 THREE39__namespace.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 });
@@ -10557,6 +11065,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) {
@@ -10569,43 +11078,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 THREE39__namespace.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 THREE39__namespace.Vector3(
+        transform.position.x,
+        transform.position.y,
+        transform.position.z
+      );
+      remoteDistance = position.distanceTo(input.rayOrigin);
+      offset = new THREE39__namespace.Vector3();
+    } else if (viaDistance) {
+      offset = new THREE39__namespace.Vector3(
+        interactable.grabOffsetPosition.x,
+        interactable.grabOffsetPosition.y,
+        interactable.grabOffsetPosition.z
+      );
+    } else {
+      offset = new THREE39__namespace.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 THREE39__namespace.Quaternion().setFromEuler(
+        new THREE39__namespace.Euler(
+          interactable.grabOffsetRotation.x,
+          interactable.grabOffsetRotation.y,
+          interactable.grabOffsetRotation.z
+        )
+      ),
+      remoteDistance,
+      remote,
+      restoreBodyType,
+      tracker,
+      lastHandQuaternion: handQuaternion.clone(),
+      angularVelocity: new THREE39__namespace.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 THREE39__namespace.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 THREE39__namespace.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) {
@@ -10614,14 +11200,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 THREE39__namespace.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 THREE39__namespace.Quaternion().setFromUnitVectors(
+      new THREE39__namespace.Vector3(0, 0, -1),
+      input.rayDirection.clone().normalize()
+    );
+  }
   dispatch(world, entityId, visit) {
     const script = world.getComponent(entityId, ScriptComponent);
     const instances = script?.scriptInstances;
@@ -10697,6 +11294,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;
@@ -10704,6 +11305,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
   update(world, deltaTime) {
     this.aimCurve = [];
     this.landingPoint = null;
+    this.aimValid = false;
     if (!world.isXrPresenting()) {
       this.parentingChecked = false;
       return;
@@ -10711,6 +11313,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;
@@ -10728,6 +11331,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.
    *
@@ -10795,29 +11418,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];
@@ -10848,6 +11502,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;
@@ -11130,6 +11788,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;
   }
@@ -11146,8 +11805,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);
@@ -11155,6 +11817,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];
@@ -11294,6 +11970,7 @@ __name(_XRControllerVisualSystem, "XRControllerVisualSystem");
 var XRControllerVisualSystem = _XRControllerVisualSystem;
 var MARKER_RADIUS = 0.28;
 var ACCENT = new THREE39__namespace.Color("#4da3ff");
+var BLOCKED = new THREE39__namespace.Color("#ff5a5a");
 var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
   constructor(locomotionSystem) {
     this.group = new THREE39__namespace.Group();
@@ -11324,16 +12001,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);
@@ -11344,9 +12027,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",
@@ -11407,6 +12090,511 @@ 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 THREE39__namespace.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 THREE39__namespace.Vector3().subVectors(aTip, aBase);
+  const dirB = new THREE39__namespace.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 THREE39__namespace.Vector3().subVectors(indexBase, wrist);
+  const v = new THREE39__namespace.Vector3().subVectors(pinkyBase, wrist);
+  const normal = new THREE39__namespace.Vector3().crossVectors(u, v);
+  if (normal.lengthSq() < 1e-12) return null;
+  normal.normalize();
+  if (handedness === "left") normal.multiplyScalar(-1);
+  const right = new THREE39__namespace.Vector3().subVectors(indexBase, pinkyBase);
+  if (right.lengthSq() < 1e-12) return null;
+  right.normalize();
+  if (handedness === "left") right.multiplyScalar(-1);
+  const up = new THREE39__namespace.Vector3().crossVectors(normal, right).normalize();
+  const center = new THREE39__namespace.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 fingers2 = {};
+  let tracked = 0;
+  for (const finger of XR_FINGERS) {
+    const curl = computeFingerCurl(joints, finger);
+    if (curl) {
+      fingers2[finger] = curl;
+      tracked += 1;
+    } else {
+      fingers2[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 THREE39__namespace.Vector3().subVectors(thumbTip, thumbBase);
+    if (direction.lengthSq() > 1e-12) thumbDirection = direction.normalize();
+  }
+  return {
+    handedness,
+    fingers: fingers2,
+    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 THREE39__namespace.Vector3(0, 1, 0),
+  down: new THREE39__namespace.Vector3(0, -1, 0),
+  forward: new THREE39__namespace.Vector3(0, 0, -1),
+  back: new THREE39__namespace.Vector3(0, 0, 1),
+  left: new THREE39__namespace.Vector3(-1, 0, 0),
+  right: new THREE39__namespace.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 THREE39__namespace.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 = THREE39__namespace.MathUtils.radToDeg(
+        Math.acos(THREE39__namespace.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 THREE39__namespace.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;
 
 // core/World.ts
 var _World = class _World {
@@ -12790,15 +13978,26 @@ exports.AnimationStateManager = AnimationStateManager;
 exports.AnimationSystem = AnimationSystem;
 exports.AudioSystem = AudioSystem;
 exports.Behaviour = Behaviour;
+exports.CURLED_COS = CURLED_COS;
 exports.CameraSyncSystem = CameraSyncSystem;
 exports.Component = Component;
 exports.CoreComponents = components_exports;
+exports.DEFAULT_ENTER_CONFIDENCE = DEFAULT_ENTER_CONFIDENCE;
+exports.DEFAULT_EXIT_CONFIDENCE = DEFAULT_EXIT_CONFIDENCE;
+exports.DEFAULT_LOST_GRACE_SECONDS = DEFAULT_LOST_GRACE_SECONDS;
+exports.DEFAULT_MIN_HOLD_SECONDS = DEFAULT_MIN_HOLD_SECONDS;
 exports.EnvironmentSyncSystem = EnvironmentSyncSystem;
+exports.FALLBACK_HAND_SCALE = FALLBACK_HAND_SCALE;
+exports.HAND_POSE_PRESETS = HAND_POSE_PRESETS;
+exports.HAND_POSE_PRESET_IDS = HAND_POSE_PRESET_IDS;
 exports.HYDRATABLE_ENTITY_KINDS = HYDRATABLE_ENTITY_KINDS;
+exports.HandPoseTracker = HandPoseTracker;
 exports.InputSystem = InputSystem;
 exports.InstancedMeshSystem = InstancedMeshSystem;
 exports.KeyboardKeys = KeyboardKeys;
 exports.LightSyncSystem = LightSyncSystem;
+exports.MATCH_FALLOFF = MATCH_FALLOFF;
+exports.MAX_SAMPLE_AGE_SECONDS = MAX_SAMPLE_AGE_SECONDS;
 exports.MaterialSyncSystem = MaterialSyncSystem;
 exports.MeshGeometrySystem = MeshGeometrySystem;
 exports.NODE_KEY_SEPARATOR = NODE_KEY_SEPARATOR;
@@ -12807,6 +14006,7 @@ exports.OVERRIDE_DIFF_EXCLUDED_COMPONENTS = OVERRIDE_DIFF_EXCLUDED_COMPONENTS;
 exports.OVERRIDE_ROOT_EXCLUDED_COMPONENTS = OVERRIDE_ROOT_EXCLUDED_COMPONENTS;
 exports.ObjectManagementSystem = ObjectManagementSystem;
 exports.ObjectVisibilitySystem = ObjectVisibilitySystem;
+exports.PINCH_FINGERS = PINCH_FINGERS;
 exports.PREFAB_FILE_VERSION = PREFAB_FILE_VERSION;
 exports.PREFAB_FILE_VERSION_NESTED = PREFAB_FILE_VERSION_NESTED;
 exports.PhysicsSyncSystem = PhysicsSyncSystem;
@@ -12814,19 +14014,25 @@ exports.PostprocessingSyncSystem = PostprocessingSyncSystem;
 exports.RenderSystem = RenderSystem;
 exports.SCRIPT_OBJECT_ROOT_FLAG = SCRIPT_OBJECT_ROOT_FLAG;
 exports.SHARED_MODEL_RESOURCE_FLAG = SHARED_MODEL_RESOURCE_FLAG;
+exports.STRAIGHT_COS = STRAIGHT_COS;
 exports.ScriptBehaviourSystem = ScriptBehaviourSystem;
 exports.ScriptObject = ScriptObject;
 exports.ScriptObjectSystem = ScriptObjectSystem;
+exports.ThrowVelocityTracker = ThrowVelocityTracker;
 exports.TransformSyncSystem = TransformSyncSystem;
+exports.VELOCITY_SAMPLES = VELOCITY_SAMPLES;
 exports.VRTeleportAreaSystem = VRTeleportAreaSystem;
 exports.VideoSystem = VideoSystem;
 exports.World = World;
 exports.XRControllerVisualSystem = XRControllerVisualSystem;
+exports.XRHandPoseSystem = XRHandPoseSystem;
 exports.XRInputSystem = XRInputSystem;
 exports.XRInteractionSystem = XRInteractionSystem;
 exports.XRLocomotionSystem = XRLocomotionSystem;
 exports.XRSessionSystem = XRSessionSystem;
 exports.XRTeleportVisualSystem = XRTeleportVisualSystem;
+exports.XR_FINGERS = XR_FINGERS;
+exports.angularVelocityFrom = angularVelocityFrom;
 exports.applyHandMaterial = applyHandMaterial;
 exports.applyPrefabToSnapshotInstances = applyPrefabToSnapshotInstances;
 exports.arcGroundCrossing = arcGroundCrossing;
@@ -12836,11 +14042,18 @@ exports.buildNodeMapsFromSnapshot = buildNodeMapsFromSnapshot;
 exports.canonicalizeComponentValue = canonicalizeComponentValue;
 exports.clearModelCache = clearModelCache;
 exports.clearPrefabCache = clearPrefabCache;
+exports.cloneHandPose = cloneHandPose;
 exports.collectDiffPaths = collectDiffPaths;
 exports.collectDirectPrefabDependencies = collectDirectPrefabDependencies;
 exports.collectEntitySubtree = collectEntitySubtree;
 exports.collectSnapshotSubtreeIds = collectSnapshotSubtreeIds;
+exports.computeFingerCurl = computeFingerCurl;
+exports.computeHandShape = computeHandShape;
 exports.computeInstanceOverrides = computeInstanceOverrides;
+exports.computePalmPose = computePalmPose;
+exports.computePalmWidth = computePalmWidth;
+exports.computePinch = computePinch;
+exports.computeSpread = computeSpread;
 exports.createAnimationComponent = createAnimationComponent;
 exports.createAudioComponent = createAudioComponent;
 exports.createCameraComponent = createCameraComponent;
@@ -12870,6 +14083,7 @@ exports.createSpriteComponent = createSpriteComponent;
 exports.createTransformComponent = createTransformComponent;
 exports.createVRTeleportAreaComponent = createVRTeleportAreaComponent;
 exports.createVideoComponent = createVideoComponent;
+exports.createXRHandPoseComponent = createXRHandPoseComponent;
 exports.createXRInteractableComponent = createXRInteractableComponent;
 exports.createXRInteractorComponent = createXRInteractorComponent;
 exports.createXRInteractorSideComponent = createXRInteractorSideComponent;
@@ -12877,15 +14091,19 @@ exports.createXRRigComponent = createXRRigComponent;
 exports.decanonicalizeComponentValue = decanonicalizeComponentValue;
 exports.despawnPrefab = despawnPrefab;
 exports.encodeOverride = encodeOverride;
+exports.estimateHandScale = estimateHandScale;
 exports.findSnapshotRootEntityIds = findSnapshotRootEntityIds;
 exports.findTopLevelNestedRegions = findTopLevelNestedRegions;
+exports.getHandPosePreset = getHandPosePreset;
 exports.groupOverridePaths = groupOverridePaths;
+exports.handPoseFromCurls = handPoseFromCurls;
 exports.hydrateWorldFromSnapshot = hydrateWorldFromSnapshot;
 exports.hydrateWorldFromSnapshotDetailed = hydrateWorldFromSnapshotDetailed;
 exports.indexSnapshotByEntity = indexSnapshotByEntity;
 exports.instantiateSubtree = instantiateSubtree;
 exports.loadPrefab = loadPrefab;
 exports.loadSharedGltf = loadSharedGltf;
+exports.matchHandPose = matchHandPose;
 exports.mergeComponentValue = mergeComponentValue;
 exports.parseOverride = parseOverride;
 exports.parsePrefabAsset = parsePrefabAsset;