@relu-interactives/spatial-ecs 0.4.4 → 0.5.0

package/dist/components/index.d.cts

@@ -1,6 +1,6 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as VRTeleportAreaComponent, a6 as VRTeleportAreaOptions, a7 as VideoComponent, a8 as VrTeleportShape, a9 as XRAnchorComponent, aa as XRAnchorOptions, ab as XRHandPoseComponent, ac as XRHandPoseOptions, ad as XRInteractableComponent, ae as XRInteractableOptions, af as XRInteractorComponent, ag as XRInteractorOptions, ah as XRInteractorSideComponent, ai as XRRigComponent, aj as XRRigOptions, ak as XrAttachPoint, al as XrDistanceGrabBehavior, am as XrEnvironmentPhysics, an as XrGrabGesture, ao as XrGrabHands, ap as XrGrabReach, aq as XrHandPoseEntry, ar as XrHandPreset, as as XrInteractorSide, at as XrInteractorType, au as XrLocomotionMode, av as XrTrackingOrigin, aw as XrTwoHandRotation, ax as createAttachPoint, ay as createHandPoseEntry, az as defaultMaterialValue, aA as handPoseDefinitionFor, aB as normalizePhysicsState, aC as setPhysicsLiveRef } from '../XRHandPose-CxPv-LBo.cjs';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-ln4Q7Eot.cjs';
-export { P as PrefabInstance, a as PrefabNode, X as XREnvironmentComponent, b as XrEnvironmentKind, c as XrEnvironmentOrientation } from '../index-CQsHUez3.cjs';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as UIButtonComponent, a6 as UIButtonOptions, a7 as UIPanelComponent, a8 as UIPanelOptions, a9 as UISliderComponent, aa as UISliderOptions, ab as UITextComponent, ac as UITextOptions, ad as UIToggleComponent, ae as UIToggleOptions, af as UiFollowMode, ag as UiTextAlign, ah as UiTextVAlign, ai as VRTeleportAreaComponent, aj as VRTeleportAreaOptions, ak as VideoComponent, al as VrTeleportShape, am as XRAnchorComponent, an as XRAnchorOptions, ao as XRHandPoseComponent, ap as XRHandPoseOptions, aq as XRInteractableComponent, ar as XRInteractableOptions, as as XRInteractorComponent, at as XRInteractorOptions, au as XRInteractorSideComponent, av as XRRigComponent, aw as XRRigOptions, ax as XrAttachPoint, ay as XrDistanceGrabBehavior, az as XrEnvironmentPhysics, aA as XrGrabGesture, aB as XrGrabHands, aC as XrGrabReach, aD as XrHandPoseEntry, aE as XrHandPreset, aF as XrInteractorSide, aG as XrInteractorType, aH as XrLocomotionMode, aI as XrTrackingOrigin, aJ as XrTwoHandRotation, aK as createAttachPoint, aL as createHandPoseEntry, aM as defaultMaterialValue, aN as handPoseDefinitionFor, aO as normalizePhysicsState, aP as setPhysicsLiveRef } from '../XRHandPose-CQTLGxFC.cjs';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-V_mv07le.cjs';
+export { P as PrefabInstance, a as PrefabNode, X as XREnvironmentComponent, b as XrEnvironmentKind, c as XrEnvironmentOrientation } from '../index-Dlr-7-4m.cjs';
 import 'three';
 import '@dimforge/rapier3d-compat';
 import '../handPose-DlcTtqgx.cjs';

package/dist/components/index.d.ts

@@ -1,6 +1,6 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as VRTeleportAreaComponent, a6 as VRTeleportAreaOptions, a7 as VideoComponent, a8 as VrTeleportShape, a9 as XRAnchorComponent, aa as XRAnchorOptions, ab as XRHandPoseComponent, ac as XRHandPoseOptions, ad as XRInteractableComponent, ae as XRInteractableOptions, af as XRInteractorComponent, ag as XRInteractorOptions, ah as XRInteractorSideComponent, ai as XRRigComponent, aj as XRRigOptions, ak as XrAttachPoint, al as XrDistanceGrabBehavior, am as XrEnvironmentPhysics, an as XrGrabGesture, ao as XrGrabHands, ap as XrGrabReach, aq as XrHandPoseEntry, ar as XrHandPreset, as as XrInteractorSide, at as XrInteractorType, au as XrLocomotionMode, av as XrTrackingOrigin, aw as XrTwoHandRotation, ax as createAttachPoint, ay as createHandPoseEntry, az as defaultMaterialValue, aA as handPoseDefinitionFor, aB as normalizePhysicsState, aC as setPhysicsLiveRef } from '../XRHandPose-BImIa4ZS.js';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-ln4Q7Eot.js';
-export { P as PrefabInstance, a as PrefabNode, X as XREnvironmentComponent, b as XrEnvironmentKind, c as XrEnvironmentOrientation } from '../index-CuGqxuk-.js';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as UIButtonComponent, a6 as UIButtonOptions, a7 as UIPanelComponent, a8 as UIPanelOptions, a9 as UISliderComponent, aa as UISliderOptions, ab as UITextComponent, ac as UITextOptions, ad as UIToggleComponent, ae as UIToggleOptions, af as UiFollowMode, ag as UiTextAlign, ah as UiTextVAlign, ai as VRTeleportAreaComponent, aj as VRTeleportAreaOptions, ak as VideoComponent, al as VrTeleportShape, am as XRAnchorComponent, an as XRAnchorOptions, ao as XRHandPoseComponent, ap as XRHandPoseOptions, aq as XRInteractableComponent, ar as XRInteractableOptions, as as XRInteractorComponent, at as XRInteractorOptions, au as XRInteractorSideComponent, av as XRRigComponent, aw as XRRigOptions, ax as XrAttachPoint, ay as XrDistanceGrabBehavior, az as XrEnvironmentPhysics, aA as XrGrabGesture, aB as XrGrabHands, aC as XrGrabReach, aD as XrHandPoseEntry, aE as XrHandPreset, aF as XrInteractorSide, aG as XrInteractorType, aH as XrLocomotionMode, aI as XrTrackingOrigin, aJ as XrTwoHandRotation, aK as createAttachPoint, aL as createHandPoseEntry, aM as defaultMaterialValue, aN as handPoseDefinitionFor, aO as normalizePhysicsState, aP as setPhysicsLiveRef } from '../XRHandPose-CU3vNFuS.js';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-V_mv07le.js';
+export { P as PrefabInstance, a as PrefabNode, X as XREnvironmentComponent, b as XrEnvironmentKind, c as XrEnvironmentOrientation } from '../index-C3ik3sA1.js';
 import 'three';
 import '@dimforge/rapier3d-compat';
 import '../handPose-DlcTtqgx.js';

package/dist/components/index.js

@@ -1,4 +1,4 @@
-export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSE_CURLS, DEFAULT_POSE_DIRECTIONS, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, ScriptObjectComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VRTeleportAreaComponent, VideoComponent, XRAnchorComponent, XREnvironmentComponent, XRHandPoseComponent, XRInteractableComponent, XRInteractorComponent, XRInteractorSideComponent, XRRigComponent, createAttachPoint, createHandPoseEntry, defaultMaterialValue, handPoseDefinitionFor, normalizePhysicsState, setPhysicsLiveRef } from '../chunk-4AK4I3QF.js';
+export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSE_CURLS, DEFAULT_POSE_DIRECTIONS, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, ScriptObjectComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, UIButtonComponent, UIPanelComponent, UISliderComponent, UITextComponent, UIToggleComponent, VRTeleportAreaComponent, VideoComponent, XRAnchorComponent, XREnvironmentComponent, XRHandPoseComponent, XRInteractableComponent, XRInteractorComponent, XRInteractorSideComponent, XRRigComponent, createAttachPoint, createHandPoseEntry, defaultMaterialValue, handPoseDefinitionFor, normalizePhysicsState, setPhysicsLiveRef } from '../chunk-BUEKOSR5.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/docs/guide/mixed-reality.md

@@ -7,9 +7,34 @@ With passthrough on, the experience composites over the user's real room instead
 of a virtual background. Turn it on in the inspector (XR Rig → Mixed Reality), or
 from a script by authoring the rig.
 
-Mixed reality is a **Quest and Android XR** capability. Safari on visionOS grants
-`immersive-ar` to no web page at all, so a passthrough project falls back to an
-ordinary VR session there rather than failing to start.
+Mixed reality passthrough is a **Quest and Android XR** capability.
+
+## Apple Vision Pro
+
+Safari on visionOS — checked through visionOS 27 — supports WebXR
+`immersive-vr` only. It grants `immersive-ar` to no web page, and exposes no
+plane detection, mesh detection or depth sensing. This is a platform policy,
+not a missing feature on our side; every web XR tool works within it (the
+industry-standard answer is a VR fallback mode).
+
+A mixed-reality project still works there, three ways:
+
+1. **Automatic VR fallback.** The session probe falls back to `immersive-vr`,
+   the authored background applies, and hands/pinch interaction works. The
+   entry page says so honestly: "Passthrough isn't available in this browser —
+   this experience will run in VR."
+2. **A synthetic floor, no scan needed.** With `environmentPhysics` on and no
+   scene understanding granted at all, the engine synthesizes one floor
+   collider whose top face sits at y = 0 — which `local-floor` makes the
+   user's REAL floor. Dropped objects land at floor height instead of falling
+   forever. (This only happens when the detection features are entirely
+   absent; a Quest that merely has not scanned yet keeps its room-capture
+   prompt instead.)
+3. **"View in your room" via AR Quick Look.** On Apple devices the entry page
+   offers a native placement preview: the scene's content is exported to
+   `.usdz` on the fly and handed to AR Quick Look, which places it in the real
+   room with passthrough — Apple's sanctioned web-AR path (it also works on
+   iPhone and iPad). This is a static snapshot: no scripts, no physics.
 
 ## What the rig controls
 
@@ -64,6 +89,64 @@ If a user reports "it never asked to scan my room" and the geometry does not
 match, they are almost certainly running against a stale scan from another
 space; re-running Space Setup for the current room fixes it.
 
+### Reading the `environmentDebug` overlay
+
+The overlay colours surfaces by what the runtime says they are, so a glance
+(or a screenshot) tells you which surface is wrong rather than just "wireframe
+somewhere":
+
+- **green** — the floor plane
+- **blue** — walls
+- **purple** — the ceiling
+- **orange** — labelled things: tables, couches, shelves, doors, windows
+- **faint gray** — the raw room scan (the "global mesh")
+
+Two things about the global mesh are easy to misread. It is deliberately
+COARSE — a couch becomes a melted lump, a wall gets bumps — because it is a
+collision mesh, not a picture; those lumps are not phantom objects. And under
+`environmentPhysics: "auto"` it is what the physics uses, with the flat planes
+skipped entirely, so orange furniture boxes and gray scan lumps can legitimately
+overlap the same real object.
+
+The overlay is depth-tested like ordinary geometry — the near wall hides the
+far one — but it never *writes* depth, so it cannot occlude actual content. (It
+was briefly rendered X-ray; on device, the dense global scan at low opacity
+fuses into translucent sheets, and without a depth test the walls' sheets drew
+through everything and stacked in front of the user's face.)
+
+For identifying a mystery shape, `XREnvironmentSystem.getDebugSnapshot(world)`
+returns a census of every spawned surface — kind, semantic label, position and
+approximate radius.
+
+One artifact is handled for you: three.js's depth-occlusion pass draws a
+head-locked mesh that writes only depth, but leaves its colour output
+undefined — on Quest hardware that painted the depth camera's view over the
+screen as faint contour bands that follow the head. `XRSessionSystem` forces
+`colorWrite` off on that mesh every frame, so enabling `depthOcclusion` costs
+no visual artifacts.
+
+### Lost tracking freezes a surface — it never follows the head
+
+When the headset loses tracking of a surface, WebXR does not stop reporting a
+pose — it reports an *emulated* one: the last known pose held relative to the
+viewer, i.e. glued to the head. Applying that to room geometry would make the
+surface — and its collider — follow the user around, shoving physics objects
+out of the way. The engine instead freezes the surface at its last tracked
+pose, resumes when tracking returns, and never creates a surface from an
+emulated pose in the first place. The diagnostics census marks such surfaces
+with `emulated: true`.
+
+### No artificial locomotion in passthrough
+
+While a session composites over the real world, `XRLocomotionSystem` disables
+ALL artificial locomotion — snap turn, teleport and smooth movement — whatever
+the rig says. Virtual content in mixed reality is registered to the real room;
+rotating or translating the rig swings every virtual object out of alignment
+while the passthrough room stays put, which feels broken rather than like
+movement. The user moves by walking. Note that `snapTurn` is a separate field
+from `locomotion`, so `locomotion: "none"` alone would NOT have stopped the
+stick from turning the rig — the gate is on the live blend mode.
+
 ## Finding the real room from a script
 
 Detected surfaces carry `XREnvironmentComponent`, so they are queryable like any
@@ -116,6 +199,36 @@ export default class RoomAware extends Behaviour {
 }
 ```
 
+## Hit-testing the real room from a script
+
+With `hitTest` on the rig, `XRHitTestSystem` keeps a ray from the viewer (and
+one per hand) cast against the real room. Systems are resolved by INSTANCE, so
+pass a throwaway one to `getSystem`:
+
+```ts
+import { Behaviour, XRHitTestSystem } from "@relu-interactives/spatial-ecs";
+import { TransformComponent } from "@relu-interactives/spatial-ecs/components";
+
+export default class PlaceOnRealSurface extends Behaviour {
+  onSelectStart() {
+    const hitTest = this.world.getSystem(new XRHitTestSystem());
+    // "viewer" = where the user is looking; "left"/"right" = hand rays.
+    const hit = hitTest.getHitResult("viewer");
+    if (!hit) return; // nothing granted, or no surface under the ray yet
+
+    const transform = this.world.getComponent(this.entityId, TransformComponent);
+    if (transform) {
+      transform.position.x = hit.position.x;
+      transform.position.y = hit.position.y;
+      transform.position.z = hit.position.z;
+    }
+  }
+}
+```
+
+`getHitResult` returns null until the runtime grants hit-testing and the ray
+actually meets a surface — always handle that case.
+
 ## Anchors
 
 A headset keeps revising where it thinks the room is. Content at fixed scene
@@ -129,6 +242,27 @@ on, and it stays put relative to the room.
 Because the anchor owns the transform, moving the entity by script or physics has
 no lasting effect — disable the component first, move it, then re-enable.
 
+From a script the toggle is the whole API:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import { XRAnchorComponent } from "@relu-interactives/spatial-ecs/components";
+
+export default class ReleaseOnGrab extends Behaviour {
+  onGrab() {
+    // Let the hand move it: release the weld for the duration of the grab.
+    const anchor = this.world.getComponent(this.entityId, XRAnchorComponent);
+    if (anchor) anchor.enabled = false;
+  }
+
+  onRelease() {
+    // Re-anchor wherever the user left it.
+    const anchor = this.world.getComponent(this.entityId, XRAnchorComponent);
+    if (anchor) anchor.enabled = true;
+  }
+}
+```
+
 Anchors last for the session only. Persisting one across launches needs
 `requestPersistentHandle`, which is a draft extension and not supported here.
 

package/dist/docs/guide/spatial-ui.md

@@ -0,0 +1,165 @@
+# Spatial UI
+
+Menus, HUDs, labels and settings panels that live **in the world**. UI is built
+from five widget entities — **panel**, **text**, **button**, **toggle**,
+**slider** — each a real entity with its own transform: move it with the gizmo,
+parent it like anything else, save it with the scene.
+
+Widgets render on both XR headsets (point with the ray or gaze, click with
+trigger or pinch) and flat 3D experiences (hover and click with the mouse).
+Hover and press feedback is built in — you never script your own highlight.
+
+## The one sizing rule
+
+**Widget size is authored in metres on the component — never with transform
+scale.** The widget's face is a texture rasterised for the authored size;
+scaling the entity stretches those texels into blur. To make a panel bigger,
+raise its `width`/`height` fields and it re-renders crisply.
+
+## Building a menu
+
+1. Create a **UI Panel** — the backdrop. A comfortable read is 1–2 m from the
+   player, centred around eye height (y ≈ 1.2–1.6).
+2. Create **Text**, **Button**, **Toggle**, **Slider** entities and parent
+   them under the panel. Place them with local transforms, a hair in front of
+   the backdrop (local z ≈ 0.01) so they draw over it.
+3. Give each interactive widget an `actionId` (empty means "use the entity's
+   name").
+4. Attach **one Behaviour to the panel**. UI events fire on the widget's own
+   entity first, then **bubble up the parent chain** — so the panel script
+   hears every child widget and can switch on `actionId`:
+
+```ts
+import { Behaviour, type UiInteractionEvent } from "@relu-interactives/spatial-ecs";
+
+export class MenuController extends Behaviour {
+  onUiPress(event: UiInteractionEvent) {
+    switch (event.actionId) {
+      case "start-game":
+        // A button under this panel was clicked.
+        break;
+      case "quit":
+        break;
+    }
+  }
+
+  onUiToggle(event: UiInteractionEvent) {
+    if (event.actionId === "music") {
+      const on = event.value === true;
+      console.log("music enabled:", on);
+    }
+  }
+
+  onUiChange(event: UiInteractionEvent) {
+    if (event.actionId === "volume" && typeof event.value === "number") {
+      console.log("volume:", event.value);
+    }
+  }
+}
+```
+
+Bubbling — not broadcast — is what keeps two copies of the same menu prefab
+independent: each panel script hears only its own children.
+
+## The widgets
+
+| Widget | Component | What it is |
+| --- | --- | --- |
+| Panel | `UIPanelComponent` | The flat backdrop. Rounded corners, border, translucency, follow mode. |
+| Text | `UITextComponent` | Wrapped, aligned text. `fontSize` is metres of glyph height. |
+| Button | `UIButtonComponent` | Pressable. Fires `onUiPress` on release. |
+| Toggle | `UIToggleComponent` | On/off switch. Fires `onUiToggle`; `value` persists with the scene. |
+| Slider | `UISliderComponent` | Draggable value in `[min, max]`. Fires `onUiChange`. |
+
+Images need no widget: parent an ordinary `image` entity under the panel.
+
+### Press semantics
+
+A click is **press, then release while still pointing at the same widget** —
+sliding off before releasing cancels, exactly like every platform's buttons.
+While a press or slider drag is held, that hand cannot accidentally teleport
+(suppressed the same way grabbing suppresses it).
+
+`onUiChange` streams while a slider is dragged (only on real value changes)
+and always fires once more with the final value on release.
+
+### Text sizing
+
+`fontSize` is **how tall the glyphs stand in the world**, in metres —
+`0.035` reads like comfortable body text at arm's length, independent of the
+panel's texture density. Lines wrap automatically to the component's `width`;
+overflow past `height` is clamped with an ellipsis.
+
+## Follow modes
+
+- `follow: "world"` (default) — the panel stays where you put it.
+- `follow: "billboard"` — the panel yaw-rotates to face the player every frame
+  at runtime (in the editor it holds still so you can work on it).
+
+For a **wrist menu**, don't billboard — parent the panel under an XR
+Interactor's **Left** or **Right** slot entity (the same slots used for custom
+hand meshes). It then rides the hand like a watch.
+
+## Reading and driving widgets from scripts
+
+Widget state is ordinary component data:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import {
+  UISliderComponent,
+  UITextComponent,
+} from "@relu-interactives/spatial-ecs/components";
+
+export class ScoreHud extends Behaviour {
+  private score = 0;
+
+  addPoint() {
+    this.score += 1;
+    // This entity is the HUD text; editing the component re-renders it.
+    const text = this.world.getComponent(this.entityId, UITextComponent);
+    if (text) text.text = `Score: ${this.score}`;
+  }
+
+  readVolume(sliderEntityId: number): number {
+    const slider = this.world.getComponent(sliderEntityId, UISliderComponent);
+    return slider ? slider.value : 0;
+  }
+}
+```
+
+Style/text edits re-render the widget's texture on the next frame. Toggle and
+slider `value` are authored state — what you set in the editor is the state
+the experience starts with.
+
+## Event payload
+
+Every UI hook receives the same shape:
+
+```ts
+import { Behaviour, type UiInteractionEvent } from "@relu-interactives/spatial-ecs";
+
+export class Inspect extends Behaviour {
+  onUiPress(event: UiInteractionEvent) {
+    event.targetEntityId; // the widget that was activated
+    event.actionId;       // its actionId, or its entity name
+    event.input;          // the XR input source, or null for mouse clicks
+    event.value;          // boolean (toggle) / number (slider); absent for presses
+  }
+
+  onUiHoverStart(event: UiInteractionEvent) {
+    // The pointer moved onto the widget (also fires for mouse hover).
+    console.log("hovering", event.targetEntityId);
+  }
+}
+```
+
+## Performance notes
+
+- A widget's face redraws only when its **style or content** changes — an
+  idle menu costs nothing per frame.
+- Slider drags and toggle flips move **geometry** (the knob and fill quads),
+  not pixels, so dragging never re-renders the texture.
+- `pixelDensity` (panel) trades texture memory for sharpness: the default
+  1024 px/m is crisp at arm's length; raise it only for panels the player
+  inspects up close.

package/dist/docs/guide/vr-and-hand-poses.md

@@ -185,6 +185,35 @@ onXRSessionStart(capabilities: XrCapabilities) {
 
 Two rules worth internalising: **move the rig, never the camera** (the headset owns the camera while presenting and overwrites it every frame), and give any destructive gesture a longer **Hold Time** so it cannot fire in passing.
 
+### Reading grab state from a script
+
+`XRInteractionSystem.getGrabInfo(entityId)` reports who is holding an entity —
+hand count, primary/secondary handedness, live hand separation (two-hand grabs)
+and the attach-point ids in use. Systems resolve by instance:
+
+```ts
+import {
+  Behaviour,
+  XRInputSystem,
+  XRInteractionSystem,
+} from "@relu-interactives/spatial-ecs";
+
+export default class TwoHandChargeUp extends Behaviour {
+  onUpdate() {
+    const interaction = this.world.getSystem(
+      new XRInteractionSystem(new XRInputSystem()),
+    );
+    const grab = interaction.getGrabInfo(this.entityId);
+    if (!grab || grab.hands < 2 || grab.handSeparation === null) return;
+
+    // Example: pull both hands apart to "charge" — separation is metres.
+    console.log("charge level", Math.min(1, grab.handSeparation / 0.8));
+  }
+}
+```
+
+Returns null while nothing holds the entity, so gate on it every frame.
+
 ## Hand poses
 
 Add an **XR Hand Pose** component and list the poses to watch for. Each is either a built-in preset or a custom set of finger curls.

package/dist/docs/guide/world-api.md

@@ -102,7 +102,7 @@ Both methods accept `Vec3` (`THREE.Vector3` or `{ x, y, z }`) and return `Inters
 
 | Method | Purpose |
 | --- | --- |
-| `getSystem(SystemClass)` | Resolve a registered system instance. |
+| `getSystem(instance)` | Resolve the REGISTERED system matching the argument's class — pass a throwaway instance (`world.getSystem(new XRHitTestSystem())`), never the class itself. |
 | `hasSystem(SystemClass)` | `true` if the system is registered. |
 | `getObjectManagementSystem()` | Shorthand for the built-in `ObjectManagementSystem`. Use this to spawn or destroy entities at runtime (`requestCreate`, `createNow`, `deleteEntity`). |
 | `getEnvironmentComponent()` | Returns the singleton [`Environment`](./scene/environment) component, or `undefined` if not yet initialized. Mutate `values` to change skybox, fog, or gravity at runtime. |