@relu-interactives/spatial-ecs 0.3.7 → 0.3.9

package/dist/index.d.cts

@@ -1,13 +1,15 @@
-import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-TmC2EijF.cjs';
-export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-TmC2EijF.cjs';
+import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-31wk-A0g.cjs';
+export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-31wk-A0g.cjs';
 import * as THREE from 'three';
-import { O as Object3DRef, af as XrHandPreset } from './XRInteractor-I2q6TKtF.cjs';
-export { an as AnimationStateCallbacks, ao as AnimationStateMachine, ap as AnimationStateManager, aq as StateMachine } from './XRInteractor-I2q6TKtF.cjs';
-import { X as XrCapabilities, a as XrInputState } from './index-B9nwRDf9.cjs';
-export { A as AnimationSystem, b as AudioSystem, C as CameraSyncSystem, E as EnvironmentSyncSystem, I as InstancedMeshSystem, L as LightSyncSystem, M as MaterialSyncSystem, c as MeshGeometrySystem, d as ModuleLoader, N as NO_XR_CAPABILITIES, O as ObjectVisibilitySystem, P as PhysicsSyncSystem, e as PostprocessingSyncSystem, S as SCRIPT_OBJECT_ROOT_FLAG, f as ScriptBehaviourSystem, g as ScriptObjectSystem, h as SelectionContext, V as VRTeleportAreaSystem, i as VideoSystem, j as XRControllerVisualSystem, k as XRInputSystem, l as XRInteractionSystem, m as XRLocomotionSystem, n as XRSessionSystem, o as XRTeleportVisualSystem, p as XrHandedness, q as XrInputKind, r as readXrCapabilities } from './index-B9nwRDf9.cjs';
-export { i as CoreComponents } from './index-BltjPEhg.cjs';
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.cjs';
+import { O as Object3DRef, aj as XrHandPreset } from './XRHandPose-VuSbe4iz.cjs';
+export { at as AnimationStateCallbacks, au as AnimationStateMachine, av as AnimationStateManager, aw as StateMachine } from './XRHandPose-VuSbe4iz.cjs';
+import { X as XrCapabilities, a as XrInputState, b as XrHandPoseEventDetail } from './index-DyN50JZo.cjs';
+export { A as AnimationSystem, c as AudioSystem, C as CameraSyncSystem, E as EnvironmentSyncSystem, I as InstancedMeshSystem, L as LightSyncSystem, M as MaterialSyncSystem, d as MeshGeometrySystem, e as ModuleLoader, N as NO_XR_CAPABILITIES, O as ObjectVisibilitySystem, P as PhysicsSyncSystem, f as PostprocessingSyncSystem, S as SCRIPT_OBJECT_ROOT_FLAG, g as ScriptBehaviourSystem, h as ScriptObjectSystem, i as SelectionContext, V as VRTeleportAreaSystem, j as VideoSystem, k as XRControllerVisualSystem, l as XRHandPoseSystem, m as XRInputSystem, n as XRInteractionSystem, o as XRLocomotionSystem, p as XRSessionSystem, q as XRTeleportVisualSystem, r as XrHandedness, s as XrInputKind, t as readXrCapabilities } from './index-DyN50JZo.cjs';
+export { i as CoreComponents } from './index-BIQoaKAA.cjs';
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRHandPoseComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.cjs';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { X as XrHandPoseDefinition, a as XrFinger, b as XrHandPoseOrientation } from './handPose-dFxqbFFY.cjs';
+export { C as CURLED_COS, D as DEFAULT_ENTER_CONFIDENCE, c as DEFAULT_EXIT_CONFIDENCE, d as DEFAULT_LOST_GRACE_SECONDS, e as DEFAULT_MIN_HOLD_SECONDS, F as FALLBACK_HAND_SCALE, H as HandPoseTracker, f as HandPoseTrackerOptions, M as MATCH_FALLOFF, P as PINCH_FINGERS, S as STRAIGHT_COS, g as XR_FINGERS, h as XrFingerCurl, i as XrFingerTarget, j as XrHandJointName, k as XrHandJoints, l as XrHandPoseAxis, m as XrHandPoseContext, n as XrHandPoseDirection, o as XrHandPoseEvent, p as XrHandPoseMatch, q as XrHandShape, r as XrPalmPose, s as computeFingerCurl, t as computeHandShape, u as computePalmPose, v as computePalmWidth, w as computePinch, x as computeSpread, y as estimateHandScale, z as matchHandPose } from './handPose-dFxqbFFY.cjs';
 import '@dimforge/rapier3d-compat';
 
 interface CustomEcsSystem extends EcsSystem {
@@ -301,6 +303,15 @@ declare class Behaviour implements CustomEcsSystem {
      *
      * @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: XrHandPoseEventDetail): void;
+    /** A held hand pose ended, or its hand stopped being tracked. */
+    onHandPoseEnd(_event: XrHandPoseEventDetail): void;
     onGrab(input: XrInputState): void;
     /** Called when this entity is released. Optional XR hook. */
     onRelease(input: XrInputState): void;
@@ -431,6 +442,7 @@ type ComponentValueMaps = {
     vrTeleportAreaValues: Map<number, unknown>;
     xrInteractableValues: Map<number, unknown>;
     xrInteractorValues: Map<number, unknown>;
+    xrHandPoseValues: Map<number, unknown>;
     xrInteractorSideValues: Map<number, unknown>;
     instancedMeshValues: Map<number, unknown>;
     instanceSlotValues: Map<number, unknown>;
@@ -810,4 +822,101 @@ declare function createHandMaterial(preset: XrHandPreset, options: HandMaterialO
 /** Apply a preset material to every mesh under a hand model. */
 declare function applyHandMaterial(root: THREE.Object3D, material: THREE.Material): void;
 
-export { ADDED_NODE_MARKER_COMPONENT, ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HandMaterialOptions, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, ScriptObject, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, XrCapabilities, XrInputState, applyHandMaterial, applyPrefabToSnapshotInstances, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, createHandMaterial, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, serializeEntitySubtree, setDracoDecoderPath };
+/**
+ * Built-in poses, keyed by id.
+ *
+ * The set covers the industry consensus (fist, open palm, point, thumbs up,
+ * pinch) plus the widely-requested ones the major toolkits omit — OK sign and
+ * gun — and the expressive extras that read well in social VR.
+ */
+declare const HAND_POSE_PRESETS: Record<string, XrHandPoseDefinition>;
+/** Preset ids, in the order the editor lists them. */
+declare const HAND_POSE_PRESET_IDS: readonly string[];
+/**
+ * A deep copy of a preset.
+ *
+ * Returned by value because scenes edit their poses: handing out the shared
+ * object would let one scene's tweak leak into every other pose in the app.
+ */
+declare function getHandPosePreset(id: string): XrHandPoseDefinition | null;
+declare function cloneHandPose(definition: XrHandPoseDefinition): XrHandPoseDefinition;
+/**
+ * Build a pose from five curl values — the shape the editor's sliders and the
+ * AI tools produce.
+ */
+declare function handPoseFromCurls(id: string, name: string, curls: Record<XrFinger, number>, options?: {
+    tolerance?: number;
+    pinch?: XrHandPoseDefinition["pinch"];
+    orientation?: XrHandPoseOrientation;
+    hand?: "left" | "right";
+}): XrHandPoseDefinition;
+
+/**
+ * Estimates release velocity for thrown objects.
+ *
+ * Naively differencing the last two frames produces terrible throws: a single
+ * noisy sample (or the tiny decelerating motion as the user opens their hand)
+ * lands right on the release frame and the object dribbles out. Real throws are
+ * recovered by looking back over a short WINDOW and taking the best of it — the
+ * approach every mature VR toolkit converges on.
+ *
+ * Pure and frame-rate independent so throw feel can be unit-tested without a
+ * headset.
+ */
+/** Samples retained. ~5 frames ≈ 55ms at 90Hz — long enough to smooth noise. */
+declare const VELOCITY_SAMPLES = 5;
+/**
+ * Samples older than this are ignored on release.
+ *
+ * Without it, pausing mid-grab then opening your hand would throw using motion
+ * from before the pause.
+ */
+declare const MAX_SAMPLE_AGE_SECONDS = 0.2;
+/**
+ * Fastest hand motion treated as real, in metres/second.
+ *
+ * Samples are recorded in WORLD space, so anything that moves the XR rig while
+ * an object is held — teleport, snap turn — relocates the hand instantly and
+ * implies an enormous velocity. Releasing after a teleport would otherwise
+ * launch the object out of the world.
+ *
+ * A very hard human throw is under ~15 m/s; a teleport across a room in one
+ * frame is hundreds. The gap is wide enough that one threshold separates them
+ * cleanly, and it also absorbs the frame-timing glitches that produce the same
+ * artefact on standalone headsets.
+ */
+declare const MAX_PLAUSIBLE_SPEED = 20;
+type VelocitySample = {
+    position: THREE.Vector3;
+    /** Seconds, monotonically increasing. */
+    time: number;
+};
+/**
+ * Rolling buffer of hand positions used to recover throw velocity.
+ *
+ * One per active grab; cleared on release.
+ */
+declare class ThrowVelocityTracker {
+    private readonly samples;
+    /** Record where the hand is now. Call once per frame while held. */
+    record(position: THREE.Vector3, time: number): void;
+    /**
+     * 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: number): THREE.Vector3;
+    clear(): void;
+}
+/**
+ * Angular velocity from a rotation delta, as an axis-angle vector (rad/s).
+ *
+ * Spin makes a thrown ball read as thrown rather than launched, and it is what
+ * lets a scene do curve shots or spinning props.
+ */
+declare function angularVelocityFrom(previous: THREE.Quaternion, current: THREE.Quaternion, deltaTime: number): THREE.Vector3;
+
+export { ADDED_NODE_MARKER_COMPONENT, ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HAND_POSE_PRESETS, HAND_POSE_PRESET_IDS, HYDRATABLE_ENTITY_KINDS, type HandMaterialOptions, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, MAX_PLAUSIBLE_SPEED, MAX_SAMPLE_AGE_SECONDS, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, ScriptObject, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, ThrowVelocityTracker, VELOCITY_SAMPLES, type VelocitySample, World, WorldEntityView, XrCapabilities, XrFinger, XrHandPoseDefinition, XrHandPoseEventDetail, XrHandPoseOrientation, XrInputState, angularVelocityFrom, applyHandMaterial, applyPrefabToSnapshotInstances, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, cloneHandPose, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, createHandMaterial, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, getHandPosePreset, groupOverridePaths, handPoseFromCurls, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, serializeEntitySubtree, setDracoDecoderPath };

package/dist/index.d.ts

@@ -1,13 +1,15 @@
-import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-TmC2EijF.js';
-export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-TmC2EijF.js';
+import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-31wk-A0g.js';
+export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-31wk-A0g.js';
 import * as THREE from 'three';
-import { O as Object3DRef, af as XrHandPreset } from './XRInteractor-CCUzSqg9.js';
-export { an as AnimationStateCallbacks, ao as AnimationStateMachine, ap as AnimationStateManager, aq as StateMachine } from './XRInteractor-CCUzSqg9.js';
-import { X as XrCapabilities, a as XrInputState } from './index-_q9TVDI5.js';
-export { A as AnimationSystem, b as AudioSystem, C as CameraSyncSystem, E as EnvironmentSyncSystem, I as InstancedMeshSystem, L as LightSyncSystem, M as MaterialSyncSystem, c as MeshGeometrySystem, d as ModuleLoader, N as NO_XR_CAPABILITIES, O as ObjectVisibilitySystem, P as PhysicsSyncSystem, e as PostprocessingSyncSystem, S as SCRIPT_OBJECT_ROOT_FLAG, f as ScriptBehaviourSystem, g as ScriptObjectSystem, h as SelectionContext, V as VRTeleportAreaSystem, i as VideoSystem, j as XRControllerVisualSystem, k as XRInputSystem, l as XRInteractionSystem, m as XRLocomotionSystem, n as XRSessionSystem, o as XRTeleportVisualSystem, p as XrHandedness, q as XrInputKind, r as readXrCapabilities } from './index-_q9TVDI5.js';
-export { i as CoreComponents } from './index-W8pUajCW.js';
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.js';
+import { O as Object3DRef, aj as XrHandPreset } from './XRHandPose-CxPz8VBp.js';
+export { at as AnimationStateCallbacks, au as AnimationStateMachine, av as AnimationStateManager, aw as StateMachine } from './XRHandPose-CxPz8VBp.js';
+import { X as XrCapabilities, a as XrInputState, b as XrHandPoseEventDetail } from './index-C7XQyrgE.js';
+export { A as AnimationSystem, c as AudioSystem, C as CameraSyncSystem, E as EnvironmentSyncSystem, I as InstancedMeshSystem, L as LightSyncSystem, M as MaterialSyncSystem, d as MeshGeometrySystem, e as ModuleLoader, N as NO_XR_CAPABILITIES, O as ObjectVisibilitySystem, P as PhysicsSyncSystem, f as PostprocessingSyncSystem, S as SCRIPT_OBJECT_ROOT_FLAG, g as ScriptBehaviourSystem, h as ScriptObjectSystem, i as SelectionContext, V as VRTeleportAreaSystem, j as VideoSystem, k as XRControllerVisualSystem, l as XRHandPoseSystem, m as XRInputSystem, n as XRInteractionSystem, o as XRLocomotionSystem, p as XRSessionSystem, q as XRTeleportVisualSystem, r as XrHandedness, s as XrInputKind, t as readXrCapabilities } from './index-C7XQyrgE.js';
+export { i as CoreComponents } from './index-BxdXgqiI.js';
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRHandPoseComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.js';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { X as XrHandPoseDefinition, a as XrFinger, b as XrHandPoseOrientation } from './handPose-dFxqbFFY.js';
+export { C as CURLED_COS, D as DEFAULT_ENTER_CONFIDENCE, c as DEFAULT_EXIT_CONFIDENCE, d as DEFAULT_LOST_GRACE_SECONDS, e as DEFAULT_MIN_HOLD_SECONDS, F as FALLBACK_HAND_SCALE, H as HandPoseTracker, f as HandPoseTrackerOptions, M as MATCH_FALLOFF, P as PINCH_FINGERS, S as STRAIGHT_COS, g as XR_FINGERS, h as XrFingerCurl, i as XrFingerTarget, j as XrHandJointName, k as XrHandJoints, l as XrHandPoseAxis, m as XrHandPoseContext, n as XrHandPoseDirection, o as XrHandPoseEvent, p as XrHandPoseMatch, q as XrHandShape, r as XrPalmPose, s as computeFingerCurl, t as computeHandShape, u as computePalmPose, v as computePalmWidth, w as computePinch, x as computeSpread, y as estimateHandScale, z as matchHandPose } from './handPose-dFxqbFFY.js';
 import '@dimforge/rapier3d-compat';
 
 interface CustomEcsSystem extends EcsSystem {
@@ -301,6 +303,15 @@ declare class Behaviour implements CustomEcsSystem {
      *
      * @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: XrHandPoseEventDetail): void;
+    /** A held hand pose ended, or its hand stopped being tracked. */
+    onHandPoseEnd(_event: XrHandPoseEventDetail): void;
     onGrab(input: XrInputState): void;
     /** Called when this entity is released. Optional XR hook. */
     onRelease(input: XrInputState): void;
@@ -431,6 +442,7 @@ type ComponentValueMaps = {
     vrTeleportAreaValues: Map<number, unknown>;
     xrInteractableValues: Map<number, unknown>;
     xrInteractorValues: Map<number, unknown>;
+    xrHandPoseValues: Map<number, unknown>;
     xrInteractorSideValues: Map<number, unknown>;
     instancedMeshValues: Map<number, unknown>;
     instanceSlotValues: Map<number, unknown>;
@@ -810,4 +822,101 @@ declare function createHandMaterial(preset: XrHandPreset, options: HandMaterialO
 /** Apply a preset material to every mesh under a hand model. */
 declare function applyHandMaterial(root: THREE.Object3D, material: THREE.Material): void;
 
-export { ADDED_NODE_MARKER_COMPONENT, ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HandMaterialOptions, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, ScriptObject, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, XrCapabilities, XrInputState, applyHandMaterial, applyPrefabToSnapshotInstances, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, createHandMaterial, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, serializeEntitySubtree, setDracoDecoderPath };
+/**
+ * Built-in poses, keyed by id.
+ *
+ * The set covers the industry consensus (fist, open palm, point, thumbs up,
+ * pinch) plus the widely-requested ones the major toolkits omit — OK sign and
+ * gun — and the expressive extras that read well in social VR.
+ */
+declare const HAND_POSE_PRESETS: Record<string, XrHandPoseDefinition>;
+/** Preset ids, in the order the editor lists them. */
+declare const HAND_POSE_PRESET_IDS: readonly string[];
+/**
+ * A deep copy of a preset.
+ *
+ * Returned by value because scenes edit their poses: handing out the shared
+ * object would let one scene's tweak leak into every other pose in the app.
+ */
+declare function getHandPosePreset(id: string): XrHandPoseDefinition | null;
+declare function cloneHandPose(definition: XrHandPoseDefinition): XrHandPoseDefinition;
+/**
+ * Build a pose from five curl values — the shape the editor's sliders and the
+ * AI tools produce.
+ */
+declare function handPoseFromCurls(id: string, name: string, curls: Record<XrFinger, number>, options?: {
+    tolerance?: number;
+    pinch?: XrHandPoseDefinition["pinch"];
+    orientation?: XrHandPoseOrientation;
+    hand?: "left" | "right";
+}): XrHandPoseDefinition;
+
+/**
+ * Estimates release velocity for thrown objects.
+ *
+ * Naively differencing the last two frames produces terrible throws: a single
+ * noisy sample (or the tiny decelerating motion as the user opens their hand)
+ * lands right on the release frame and the object dribbles out. Real throws are
+ * recovered by looking back over a short WINDOW and taking the best of it — the
+ * approach every mature VR toolkit converges on.
+ *
+ * Pure and frame-rate independent so throw feel can be unit-tested without a
+ * headset.
+ */
+/** Samples retained. ~5 frames ≈ 55ms at 90Hz — long enough to smooth noise. */
+declare const VELOCITY_SAMPLES = 5;
+/**
+ * Samples older than this are ignored on release.
+ *
+ * Without it, pausing mid-grab then opening your hand would throw using motion
+ * from before the pause.
+ */
+declare const MAX_SAMPLE_AGE_SECONDS = 0.2;
+/**
+ * Fastest hand motion treated as real, in metres/second.
+ *
+ * Samples are recorded in WORLD space, so anything that moves the XR rig while
+ * an object is held — teleport, snap turn — relocates the hand instantly and
+ * implies an enormous velocity. Releasing after a teleport would otherwise
+ * launch the object out of the world.
+ *
+ * A very hard human throw is under ~15 m/s; a teleport across a room in one
+ * frame is hundreds. The gap is wide enough that one threshold separates them
+ * cleanly, and it also absorbs the frame-timing glitches that produce the same
+ * artefact on standalone headsets.
+ */
+declare const MAX_PLAUSIBLE_SPEED = 20;
+type VelocitySample = {
+    position: THREE.Vector3;
+    /** Seconds, monotonically increasing. */
+    time: number;
+};
+/**
+ * Rolling buffer of hand positions used to recover throw velocity.
+ *
+ * One per active grab; cleared on release.
+ */
+declare class ThrowVelocityTracker {
+    private readonly samples;
+    /** Record where the hand is now. Call once per frame while held. */
+    record(position: THREE.Vector3, time: number): void;
+    /**
+     * 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: number): THREE.Vector3;
+    clear(): void;
+}
+/**
+ * Angular velocity from a rotation delta, as an axis-angle vector (rad/s).
+ *
+ * Spin makes a thrown ball read as thrown rather than launched, and it is what
+ * lets a scene do curve shots or spinning props.
+ */
+declare function angularVelocityFrom(previous: THREE.Quaternion, current: THREE.Quaternion, deltaTime: number): THREE.Vector3;
+
+export { ADDED_NODE_MARKER_COMPONENT, ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HAND_POSE_PRESETS, HAND_POSE_PRESET_IDS, HYDRATABLE_ENTITY_KINDS, type HandMaterialOptions, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, MAX_PLAUSIBLE_SPEED, MAX_SAMPLE_AGE_SECONDS, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, ScriptObject, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, ThrowVelocityTracker, VELOCITY_SAMPLES, type VelocitySample, World, WorldEntityView, XrCapabilities, XrFinger, XrHandPoseDefinition, XrHandPoseEventDetail, XrHandPoseOrientation, XrInputState, angularVelocityFrom, applyHandMaterial, applyPrefabToSnapshotInstances, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, cloneHandPose, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, createHandMaterial, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, getHandPosePreset, groupOverridePaths, handPoseFromCurls, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, serializeEntitySubtree, setDracoDecoderPath };

package/dist/index.js

@@ -1,11 +1,11 @@
-import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, VRTeleportAreaSystem, PhysicsSyncSystem, AnimationSystem, AudioSystem, VideoSystem, CameraSyncSystem, TransformSyncSystem, ObjectVisibilitySystem, RenderSystem, spawnPrefab, despawnPrefab, buildNodeKeyMapsFromSnapshot, indexSnapshotByEntity, findTopLevelNestedRegions, collectSnapshotSubtreeIds, groupOverridePaths, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, canonicalizeComponentValue, mergeComponentValue, decanonicalizeComponentValue, computeInstanceOverrides, collectEntitySubtree, ADDED_NODE_MARKER_COMPONENT } from './chunk-O6FJA4XW.js';
-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 } from './chunk-O6FJA4XW.js';
-import { registerDefaultFactories } from './chunk-FQTOC7HK.js';
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './chunk-FQTOC7HK.js';
-import { ObjectManagementSystem } from './chunk-JRJ3CL5H.js';
-export { ObjectManagementSystem, SHARED_MODEL_RESOURCE_FLAG, clearModelCache, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath } from './chunk-JRJ3CL5H.js';
-import { SelectionTransformState, Object3DRef, Name, EntityType, ParentId, Environment, Postprocessing, ScriptComponent } from './chunk-N4GKZ7IV.js';
-export { AnimationStateMachine, AnimationStateManager, components_exports as CoreComponents } from './chunk-N4GKZ7IV.js';
+import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, VRTeleportAreaSystem, PhysicsSyncSystem, AnimationSystem, AudioSystem, VideoSystem, CameraSyncSystem, TransformSyncSystem, ObjectVisibilitySystem, RenderSystem, spawnPrefab, despawnPrefab, buildNodeKeyMapsFromSnapshot, indexSnapshotByEntity, findTopLevelNestedRegions, collectSnapshotSubtreeIds, groupOverridePaths, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, canonicalizeComponentValue, mergeComponentValue, decanonicalizeComponentValue, computeInstanceOverrides, collectEntitySubtree, ADDED_NODE_MARKER_COMPONENT } from './chunk-W5TSYV6Q.js';
+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_PLAUSIBLE_SPEED, 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 } from './chunk-W5TSYV6Q.js';
+import { registerDefaultFactories } from './chunk-KIKIWCEB.js';
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRHandPoseComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './chunk-KIKIWCEB.js';
+import { ObjectManagementSystem } from './chunk-L5BP727H.js';
+export { ObjectManagementSystem, SHARED_MODEL_RESOURCE_FLAG, clearModelCache, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath } from './chunk-L5BP727H.js';
+import { SelectionTransformState, Object3DRef, Name, EntityType, ParentId, Environment, Postprocessing, ScriptComponent } from './chunk-KVGGAL5V.js';
+export { AnimationStateMachine, AnimationStateManager, components_exports as CoreComponents, HAND_POSE_PRESETS, HAND_POSE_PRESET_IDS, cloneHandPose, getHandPosePreset, handPoseFromCurls } from './chunk-KVGGAL5V.js';
 import './chunk-QHILSPT4.js';
 import { normalizeDebugValue, DEBUG_CHANGE_IGNORED_SYSTEMS, cloneHistoryValue } from './chunk-OWQSESTO.js';
 import { __name } from './chunk-OY7ZODZP.js';