@relu-interactives/spatial-ecs 0.3.5 → 0.3.6

package/dist/index.d.cts

@@ -1,12 +1,12 @@
-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-vrU46Vuw.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-vrU46Vuw.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-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 * as THREE from 'three';
-import { O as Object3DRef } from './XRRig-2686IqLQ.cjs';
-export { ag as AnimationStateCallbacks, ah as AnimationStateMachine, ai as AnimationStateManager, aj as StateMachine } from './XRRig-2686IqLQ.cjs';
-import { X as XrCapabilities, a as XrInputState } from './index-BvCmmuJ0.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-BvCmmuJ0.cjs';
-export { i as CoreComponents } from './index-Xu238jLn.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, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.cjs';
+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-C5FrDt3z.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-C5FrDt3z.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 { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import '@dimforge/rapier3d-compat';
 
@@ -430,6 +430,8 @@ type ComponentValueMaps = {
     xrRigValues: Map<number, unknown>;
     vrTeleportAreaValues: Map<number, unknown>;
     xrInteractableValues: Map<number, unknown>;
+    xrInteractorValues: Map<number, unknown>;
+    xrInteractorSideValues: Map<number, unknown>;
     instancedMeshValues: Map<number, unknown>;
     instanceSlotValues: Map<number, unknown>;
     prefabNodeValues: Map<number, unknown>;
@@ -784,4 +786,28 @@ declare function sampleTeleportArc(origin: THREE.Vector3, direction: THREE.Vecto
  */
 declare function arcGroundCrossing(points: THREE.Vector3[], groundY: number): THREE.Vector3 | null;
 
-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 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, applyPrefabToSnapshotInstances, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, serializeEntitySubtree, setDracoDecoderPath };
+/**
+ * Materials for tracked-hand meshes.
+ *
+ * three's `XRHandModelFactory` builds the joint geometry but gives it a plain
+ * default material, so hands look identical in every experience. These presets
+ * let an author pick a look in one click, with `custom` deferring entirely to
+ * the colour/opacity/emissive fields.
+ */
+type HandMaterialOptions = {
+    color: string;
+    opacity: number;
+    emissiveIntensity: number;
+};
+/**
+ * Build the material for a preset.
+ *
+ * Returns a fresh material each call — hands are per-session and disposed with
+ * the interactor, and sharing one instance across presets would make switching
+ * leak state between them.
+ */
+declare function createHandMaterial(preset: XrHandPreset, options: HandMaterialOptions): THREE.Material;
+/** 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 };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-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-vrU46Vuw.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-vrU46Vuw.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-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 * as THREE from 'three';
-import { O as Object3DRef } from './XRRig-D2QURXl1.js';
-export { ag as AnimationStateCallbacks, ah as AnimationStateMachine, ai as AnimationStateManager, aj as StateMachine } from './XRRig-D2QURXl1.js';
-import { X as XrCapabilities, a as XrInputState } from './index-B-CViRMx.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-B-CViRMx.js';
-export { i as CoreComponents } from './index-BtKOaHfY.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, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.js';
+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-BpbmZuOz.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-BpbmZuOz.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 { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import '@dimforge/rapier3d-compat';
 
@@ -430,6 +430,8 @@ type ComponentValueMaps = {
     xrRigValues: Map<number, unknown>;
     vrTeleportAreaValues: Map<number, unknown>;
     xrInteractableValues: Map<number, unknown>;
+    xrInteractorValues: Map<number, unknown>;
+    xrInteractorSideValues: Map<number, unknown>;
     instancedMeshValues: Map<number, unknown>;
     instanceSlotValues: Map<number, unknown>;
     prefabNodeValues: Map<number, unknown>;
@@ -784,4 +786,28 @@ declare function sampleTeleportArc(origin: THREE.Vector3, direction: THREE.Vecto
  */
 declare function arcGroundCrossing(points: THREE.Vector3[], groundY: number): THREE.Vector3 | null;
 
-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 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, applyPrefabToSnapshotInstances, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, serializeEntitySubtree, setDracoDecoderPath };
+/**
+ * Materials for tracked-hand meshes.
+ *
+ * three's `XRHandModelFactory` builds the joint geometry but gives it a plain
+ * default material, so hands look identical in every experience. These presets
+ * let an author pick a look in one click, with `custom` deferring entirely to
+ * the colour/opacity/emissive fields.
+ */
+type HandMaterialOptions = {
+    color: string;
+    opacity: number;
+    emissiveIntensity: number;
+};
+/**
+ * Build the material for a preset.
+ *
+ * Returns a fresh material each call — hands are per-session and disposed with
+ * the interactor, and sharing one instance across presets would make switching
+ * leak state between them.
+ */
+declare function createHandMaterial(preset: XrHandPreset, options: HandMaterialOptions): THREE.Material;
+/** 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 };

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-G53MZVKQ.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, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, readXrCapabilities, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, setPrefabAssetUrlResolver, spawnPrefab } from './chunk-G53MZVKQ.js';
-import { registerDefaultFactories } from './chunk-4BZYK3JP.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, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './chunk-4BZYK3JP.js';
-import { ObjectManagementSystem } from './chunk-2LVFGVWI.js';
-export { ObjectManagementSystem, SHARED_MODEL_RESOURCE_FLAG, clearModelCache, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath } from './chunk-2LVFGVWI.js';
-import { SelectionTransformState, Object3DRef, Name, EntityType, ParentId, Environment, Postprocessing, ScriptComponent } from './chunk-6QC2PJLD.js';
-export { AnimationStateMachine, AnimationStateManager, components_exports as CoreComponents } from './chunk-6QC2PJLD.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-WRJ2K3LZ.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-WRJ2K3LZ.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 './chunk-QHILSPT4.js';
 import { normalizeDebugValue, DEBUG_CHANGE_IGNORED_SYSTEMS, cloneHistoryValue } from './chunk-OWQSESTO.js';
 import { __name } from './chunk-OY7ZODZP.js';

package/dist/systems/index.cjs

@@ -2109,6 +2109,7 @@ var XRInteractableComponent = _XRInteractableComponent;
 var _XRRigComponent = class _XRRigComponent extends Component {
   constructor(options) {
     super();
+    this.trackingOrigin = options?.trackingOrigin ?? "floor";
     this.locomotion = options?.locomotion ?? "teleport";
     this.moveSpeed = options?.moveSpeed ?? 2;
     this.snapTurn = options?.snapTurn ?? true;
@@ -2119,6 +2120,29 @@ var _XRRigComponent = class _XRRigComponent extends Component {
 __name(_XRRigComponent, "XRRigComponent");
 var XRRigComponent = _XRRigComponent;
 
+// core/components/XRInteractor.ts
+var _XRInteractorComponent = class _XRInteractorComponent extends Component {
+  constructor(options) {
+    super();
+    this.interactorType = options?.interactorType ?? "both";
+    this.handPreset = options?.handPreset ?? "default";
+    this.handColor = options?.handColor ?? "#e8b48a";
+    this.handOpacity = options?.handOpacity ?? 1;
+    this.handEmissiveIntensity = options?.handEmissiveIntensity ?? 0;
+    this.showRay = options?.showRay ?? true;
+  }
+};
+__name(_XRInteractorComponent, "XRInteractorComponent");
+var XRInteractorComponent = _XRInteractorComponent;
+var _XRInteractorSideComponent = class _XRInteractorSideComponent extends Component {
+  constructor(options) {
+    super();
+    this.side = options?.side ?? "left";
+  }
+};
+__name(_XRInteractorSideComponent, "XRInteractorSideComponent");
+var XRInteractorSideComponent = _XRInteractorSideComponent;
+
 // core/utils/dracoDecoderPath.ts
 var LOCAL_DRACO_DECODER_RELATIVE_PATH = "./assets/draco/";
 var DRACO_DECODER_CDN_PATH = "https://www.gstatic.com/draco/versioned/decoders/1.5.7/";
@@ -4913,6 +4937,14 @@ function buildComponentValueMaps(snapshot) {
       snapshot.components,
       "XRInteractableComponent"
     ),
+    xrInteractorValues: readByComponent(
+      snapshot.components,
+      "XRInteractorComponent"
+    ),
+    xrInteractorSideValues: readByComponent(
+      snapshot.components,
+      "XRInteractorSideComponent"
+    ),
     instancedMeshValues: readByComponent(snapshot.components, "InstancedMeshComponent"),
     instanceSlotValues: readByComponent(snapshot.components, "InstanceSlotComponent"),
     prefabNodeValues: readByComponent(snapshot.components, "PrefabNode"),
@@ -5099,6 +5131,60 @@ function restorePostCreateComponents(world, objectManagementSystem, targetEntity
       }
     }
   }
+  {
+    const sourceInteractor = asRecord3(
+      values.xrInteractorValues.get(sourceEntityId)
+    );
+    const interactor = world.getComponent(targetEntityId, XRInteractorComponent);
+    if (sourceInteractor && interactor) {
+      if (typeof sourceInteractor.interactorType === "string") {
+        interactor.interactorType = sourceInteractor.interactorType;
+      }
+      if (typeof sourceInteractor.handPreset === "string") {
+        interactor.handPreset = sourceInteractor.handPreset;
+      }
+      if (typeof sourceInteractor.handColor === "string") {
+        interactor.handColor = sourceInteractor.handColor;
+      }
+      if (typeof sourceInteractor.handOpacity === "number") {
+        interactor.handOpacity = sourceInteractor.handOpacity;
+      }
+      if (typeof sourceInteractor.handEmissiveIntensity === "number") {
+        interactor.handEmissiveIntensity = sourceInteractor.handEmissiveIntensity;
+      }
+      if (typeof sourceInteractor.showRay === "boolean") {
+        interactor.showRay = sourceInteractor.showRay;
+      }
+    }
+  }
+  {
+    const sourceSide = asRecord3(
+      values.xrInteractorSideValues.get(sourceEntityId)
+    );
+    if (sourceSide && typeof sourceSide.side === "string") {
+      const existing = world.getComponent(
+        targetEntityId,
+        XRInteractorSideComponent
+      );
+      if (existing) {
+        existing.side = sourceSide.side;
+      } else {
+        world.addComponent(
+          targetEntityId,
+          new XRInteractorSideComponent({
+            side: sourceSide.side
+          })
+        );
+      }
+    }
+  }
+  {
+    const sourceRigOrigin = asRecord3(values.xrRigValues.get(sourceEntityId));
+    const rigForOrigin = world.getComponent(targetEntityId, XRRigComponent);
+    if (sourceRigOrigin && rigForOrigin && typeof sourceRigOrigin.trackingOrigin === "string") {
+      rigForOrigin.trackingOrigin = sourceRigOrigin.trackingOrigin;
+    }
+  }
   {
     const imComponent = world.getComponent(targetEntityId, InstancedMeshComponent);
     if (imComponent && imComponent.instanceEntityIds.length > 0) {
@@ -5688,6 +5774,7 @@ var HYDRATABLE_ENTITY_KINDS = /* @__PURE__ */ new Set([
   "instanceSlot",
   "scriptObject",
   "xrRig",
+  "xrInteractor",
   "teleportArea"
 ]);
 
@@ -7698,6 +7785,9 @@ var _XRInputSystem = class _XRInputSystem {
         state.hasAxes = false;
         state.buttons = [];
       }
+    }
+    for (const record of this.records.values()) {
+      const state = record.state;
       if (record.pendingSelectStart) {
         state.select = true;
         state.selectStart = true;
@@ -8126,6 +8216,8 @@ var _XRSessionSystem = class _XRSessionSystem {
   constructor(inputSystem) {
     this.presenting = false;
     this.capabilities = NO_XR_CAPABILITIES;
+    /** Y compensation applied when a floor-relative space was requested but not granted. */
+    this.appliedOriginOffset = 0;
     this.inputSystem = inputSystem ?? null;
   }
   update(world) {
@@ -8149,11 +8241,59 @@ var _XRSessionSystem = class _XRSessionSystem {
     if (session && this.inputSystem) {
       this.inputSystem.attachSession(session);
     }
+    this.applyTrackingOrigin(world, session ?? null);
     this.forEachBehaviour(world, (behaviour) => {
       behaviour.onXRSessionStart(this.capabilities);
     });
   }
+  /**
+   * Apply the rig's authored tracking origin, and compensate when the device
+   * cannot honour it.
+   *
+   * `floor` (`local-floor`) puts Y=0 on the user's real floor, which is what a
+   * scene authored standing on the ground expects. `eye` (`local`) puts Y=0 at
+   * the headset, for seated experiences.
+   *
+   * The compensation matters: `local-floor` is only ever REQUESTED as an
+   * optional feature (requiring it would make `requestSession` reject outright
+   * on devices that lack it). When it isn't granted, the runtime silently falls
+   * back to `local` — the origin jumps to head height and a floor-authored
+   * scene swallows the user, which is exactly the "I'm standing under the
+   * building" symptom. Offsetting the rig down by the eye height restores the
+   * intended floor relationship instead of leaving it broken.
+   */
+  applyTrackingOrigin(world, session) {
+    const rigEntityId = world.query(XRRigComponent, TransformComponent)[0];
+    if (typeof rigEntityId !== "number") return;
+    const rig = world.getComponent(rigEntityId, XRRigComponent);
+    const transform = world.getComponent(rigEntityId, TransformComponent);
+    if (!rig || !transform) return;
+    const renderer = world.getRenderer();
+    const wantsFloor = rig.trackingOrigin === "floor";
+    try {
+      renderer.xr.setReferenceSpaceType(wantsFloor ? "local-floor" : "local");
+    } catch {
+    }
+    const granted = session?.enabledFeatures;
+    const floorGranted = Array.isArray(granted) ? granted.includes("local-floor") : (
+      // No report at all: trust the request, since a wrong offset is worse
+      // than none on devices that did honour it.
+      true
+    );
+    this.appliedOriginOffset = wantsFloor && !floorGranted ? rig.fallbackEyeHeight : 0;
+    if (this.appliedOriginOffset !== 0) {
+      transform.position.y -= this.appliedOriginOffset;
+    }
+  }
   handleSessionEnd(world) {
+    if (this.appliedOriginOffset !== 0) {
+      const rigEntityId = world.query(XRRigComponent, TransformComponent)[0];
+      if (typeof rigEntityId === "number") {
+        const transform = world.getComponent(rigEntityId, TransformComponent);
+        if (transform) transform.position.y += this.appliedOriginOffset;
+      }
+      this.appliedOriginOffset = 0;
+    }
     this.capabilities = NO_XR_CAPABILITIES;
     this.inputSystem?.detachSession();
     this.forEachBehaviour(world, (behaviour) => {
@@ -8247,17 +8387,74 @@ var _VRTeleportAreaSystem = class _VRTeleportAreaSystem {
 };
 __name(_VRTeleportAreaSystem, "VRTeleportAreaSystem");
 var VRTeleportAreaSystem = _VRTeleportAreaSystem;
+function createHandMaterial(preset, options) {
+  const color = new THREE14__namespace.Color(options.color);
+  switch (preset) {
+    case "ghost":
+      return new THREE14__namespace.MeshBasicMaterial({
+        color,
+        transparent: true,
+        opacity: Math.min(1, Math.max(0.05, options.opacity * 0.45)),
+        depthWrite: false,
+        side: THREE14__namespace.DoubleSide
+      });
+    case "neon":
+      return new THREE14__namespace.MeshStandardMaterial({
+        color,
+        emissive: color,
+        emissiveIntensity: Math.max(0.5, options.emissiveIntensity || 2),
+        roughness: 0.35,
+        metalness: 0,
+        transparent: options.opacity < 1,
+        opacity: options.opacity
+      });
+    case "skeleton":
+      return new THREE14__namespace.MeshBasicMaterial({
+        color,
+        wireframe: true,
+        transparent: true,
+        opacity: options.opacity
+      });
+    case "custom":
+    case "default":
+      return new THREE14__namespace.MeshStandardMaterial({
+        color,
+        roughness: 0.85,
+        metalness: 0,
+        emissive: color,
+        emissiveIntensity: Math.max(0, options.emissiveIntensity),
+        transparent: options.opacity < 1,
+        opacity: options.opacity,
+        side: THREE14__namespace.DoubleSide
+      });
+    default: {
+      return new THREE14__namespace.MeshStandardMaterial({ color });
+    }
+  }
+}
+__name(createHandMaterial, "createHandMaterial");
+function applyHandMaterial(root, material) {
+  root.traverse((child) => {
+    const mesh = child;
+    if (!mesh.isMesh) return;
+    mesh.material = material;
+  });
+}
+__name(applyHandMaterial, "applyHandMaterial");
+var SLOTS = [
+  { index: 0, side: "left" },
+  { index: 1, side: "right" }
+];
 var _XRControllerVisualSystem = class _XRControllerVisualSystem {
   constructor(options) {
     this.controllerModelFactory = new XRControllerModelFactory_js.XRControllerModelFactory();
     this.handModelFactory = new XRHandModelFactory_js.XRHandModelFactory();
     this.group = new THREE14__namespace.Group();
-    this.built = false;
+    this.slots = /* @__PURE__ */ new Map();
     this.attachedTo = null;
-    /** Index → whether we've already attached visuals for that slot. */
-    this.ready = /* @__PURE__ */ new Set();
-    this.rays = [];
-    this.slots = options?.slots ?? 2;
+    /** Last applied preset signature, so materials rebuild only on real change. */
+    this.handStyleSignature = "";
+    this.handMaterial = null;
     this.interactionSystem = options?.interactionSystem ?? null;
     this.group.name = "XRControllerVisuals";
     this.group.userData.ecsPreviewHidden = true;
@@ -8266,39 +8463,111 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
     const renderer = world.getRenderer();
     if (!renderer.xr?.enabled) return;
     this.ensureAttached(world);
-    this.updateRayVisibility();
-    if (this.built) return;
-    for (let index = 0; index < this.slots; index += 1) {
-      if (this.ready.has(index)) continue;
+    this.ensureSlots(world);
+    const interactor = this.resolveInteractor(world);
+    const type = interactor?.interactorType ?? "both";
+    const showControllers = type === "controllers" || type === "both";
+    const showHands = type === "hands" || type === "both";
+    this.syncHandMaterial(interactor);
+    for (const { index, side } of SLOTS) {
+      const visuals = this.slots.get(index);
+      if (!visuals) continue;
+      visuals.controllerModel.visible = showControllers;
+      visuals.handModel.visible = showHands;
+      visuals.ray.visible = this.shouldShowRay(interactor);
+      if (showHands && this.handMaterial) {
+        applyHandMaterial(visuals.handModel, this.handMaterial);
+      }
+      this.syncCustomContent(world, visuals, side);
+    }
+  }
+  /** The scene's interactor config, if one was authored. */
+  resolveInteractor(world) {
+    const entityId = world.query(XRInteractorComponent)[0];
+    if (typeof entityId !== "number") return null;
+    return world.getComponent(entityId, XRInteractorComponent) ?? null;
+  }
+  /**
+   * Re-parent the author's left/right interactor content onto the tracked grip
+   * space so it follows the hand.
+   *
+   * `ObjectManagementSystem` reconciles ECS objects back under their ParentId
+   * every frame, so this re-attach has to be re-asserted — the same coexistence
+   * dance the AR anchor system performs.
+   */
+  syncCustomContent(world, visuals, side) {
+    let content = null;
+    for (const entityId of world.query(
+      XRInteractorSideComponent,
+      Object3DRef
+    )) {
+      const slot = world.getComponent(entityId, XRInteractorSideComponent);
+      if (slot?.side !== side) continue;
+      content = world.getComponent(entityId, Object3DRef)?.object ?? null;
+      break;
+    }
+    if (!content) {
+      visuals.attachedCustom = null;
+      return;
+    }
+    if (content.parent !== visuals.grip) {
+      visuals.grip.add(content);
+    }
+    visuals.attachedCustom = content;
+  }
+  /** Rebuild the hand material only when the authored style actually changes. */
+  syncHandMaterial(interactor) {
+    const preset = interactor?.handPreset ?? "default";
+    const color = interactor?.handColor ?? "#e8b48a";
+    const opacity = interactor?.handOpacity ?? 1;
+    const emissive = interactor?.handEmissiveIntensity ?? 0;
+    const signature = `${preset}:${color}:${opacity}:${emissive}`;
+    if (signature === this.handStyleSignature && this.handMaterial) return;
+    this.handStyleSignature = signature;
+    this.handMaterial?.dispose();
+    this.handMaterial = createHandMaterial(preset, {
+      color,
+      opacity,
+      emissiveIntensity: emissive
+    });
+  }
+  /**
+   * The ray is meaningful only when it points at something. Authors can turn it
+   * off entirely; otherwise it appears on hover/grab so it isn't permanent
+   * clutter implying the whole scene is clickable.
+   */
+  shouldShowRay(interactor) {
+    if (interactor && !interactor.showRay) return false;
+    if (!this.interactionSystem) return true;
+    return this.interactionSystem.getHoveredEntityId() !== null || this.interactionSystem.isGrabbing();
+  }
+  /** Lazily build per-slot visuals; the device reports profiles late. */
+  ensureSlots(world) {
+    const renderer = world.getRenderer();
+    for (const { index } of SLOTS) {
+      if (this.slots.has(index)) continue;
       const controller = renderer.xr.getController(index);
       const grip = renderer.xr.getControllerGrip(index);
       const hand = renderer.xr.getHand(index);
       if (!controller || !grip || !hand) continue;
       const ray = this.createRay();
-      this.rays.push(ray);
       controller.add(ray);
-      this.group.add(controller);
-      grip.add(this.controllerModelFactory.createControllerModel(grip));
-      this.group.add(grip);
-      hand.add(this.handModelFactory.createHandModel(hand, "mesh"));
-      this.group.add(hand);
-      this.ready.add(index);
-    }
-    if (this.ready.size >= this.slots) {
-      this.built = true;
+      const controllerModel = this.controllerModelFactory.createControllerModel(grip);
+      grip.add(controllerModel);
+      const handModel = this.handModelFactory.createHandModel(hand, "mesh");
+      hand.add(handModel);
+      this.group.add(controller, grip, hand);
+      this.slots.set(index, {
+        controller,
+        grip,
+        hand,
+        ray,
+        controllerModel,
+        handModel,
+        attachedCustom: null
+      });
     }
   }
-  /**
-   * Show the aim ray only when it is meaningful: hovering something
-   * interactive, or mid-grab. A permanently-drawn ray is visual noise, and it
-   * implies everything is clickable when most of the scene is not. Teleport
-   * aiming has its own arc, so the straight ray stays hidden for that.
-   */
-  updateRayVisibility() {
-    if (!this.interactionSystem) return;
-    const active = this.interactionSystem.getHoveredEntityId() !== null || this.interactionSystem.isGrabbing();
-    for (const ray of this.rays) ray.visible = active;
-  }
   /**
    * Parent the visuals to the XR rig when there is one, so locomotion moves the
    * hands with the player. Falls back to the scene root.
@@ -8324,7 +8593,7 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
     const line = new THREE14__namespace.Line(geometry, material);
     line.name = "XRPointerRay";
     line.renderOrder = 999;
-    line.visible = this.interactionSystem === null;
+    line.visible = false;
     return line;
   }
   dispose() {
@@ -8340,9 +8609,10 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
       }
     });
     this.group.clear();
-    this.rays.length = 0;
-    this.ready.clear();
-    this.built = false;
+    this.slots.clear();
+    this.handMaterial?.dispose();
+    this.handMaterial = null;
+    this.handStyleSignature = "";
     this.attachedTo = null;
   }
 };