@relu-interactives/spatial-ecs 0.5.2 → 0.8.0

package/dist/docs/api/components/functions/defaultMaterialValue.md

@@ -10,7 +10,7 @@
 function defaultMaterialValue(): MaterialValueState;
 ```
 
-Defined in: [components/Material.ts:155](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Material.ts#L155)
+Defined in: [components/Material.ts:202](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Material.ts#L202)
 
 ## Returns
 

package/dist/docs/api/components/functions/handPoseDefinitionFor.md

@@ -0,0 +1,33 @@
+[**@relu-interactives/spatial-ecs**](../../index.md)
+
+***
+
+[@relu-interactives/spatial-ecs](../../index.md) / [components](../index.md) / handPoseDefinitionFor
+
+# Function: handPoseDefinitionFor()
+
+```ts
+function handPoseDefinitionFor(entry, resolvePreset): 
+  | XrHandPoseDefinition
+  | null;
+```
+
+Defined in: [components/XRHandPose.ts:101](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/XRHandPose.ts#L101)
+
+Resolve an entry to the definition the matcher consumes.
+
+Preset entries defer to the shared library but still honour the entry's own
+hand restriction and hold time, so a scene can reuse "thumbs up" while
+scoping it to one hand.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `entry` | [`XrHandPoseEntry`](../type-aliases/XrHandPoseEntry.md) |
+| `resolvePreset` | (`id`) => \| [`XrHandPoseDefinition`](../../index/type-aliases/XrHandPoseDefinition.md) \| `null` |
+
+## Returns
+
+  \| [`XrHandPoseDefinition`](../../index/type-aliases/XrHandPoseDefinition.md)
+  \| `null`

package/dist/docs/api/components/functions/normalizeEnvironmentLighting.md

@@ -0,0 +1,30 @@
+[**@relu-interactives/spatial-ecs**](../../index.md)
+
+***
+
+[@relu-interactives/spatial-ecs](../../index.md) / [components](../index.md) / normalizeEnvironmentLighting
+
+# Function: normalizeEnvironmentLighting()
+
+```ts
+function normalizeEnvironmentLighting(value): 
+  | Required<EnvironmentLightingState>
+  | undefined;
+```
+
+Defined in: [components/Environment.ts:240](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L240)
+
+Normalize a lighting block to a complete [EnvironmentLightingState](../type-aliases/EnvironmentLightingState.md).
+Returns `undefined` when `value` is not an object, so a scene without the
+block stays without it.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `unknown` |
+
+## Returns
+
+  \| `Required`\<[`EnvironmentLightingState`](../type-aliases/EnvironmentLightingState.md)\>
+  \| `undefined`

package/dist/docs/api/components/functions/normalizePhysicsState.md

@@ -10,7 +10,7 @@
 function normalizePhysicsState(value): PhysicsState;
 ```
 
-Defined in: [components/Physics.ts:319](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L319)
+Defined in: [components/Physics.ts:319](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L319)
 
 ## Parameters
 

package/dist/docs/api/components/functions/setModelLoadState.md

@@ -0,0 +1,33 @@
+[**@relu-interactives/spatial-ecs**](../../index.md)
+
+***
+
+[@relu-interactives/spatial-ecs](../../index.md) / [components](../index.md) / setModelLoadState
+
+# Function: setModelLoadState()
+
+```ts
+function setModelLoadState(
+   component, 
+   state, 
+   error?): void;
+```
+
+Defined in: [components/Model.ts:17](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Model.ts#L17)
+
+Write a model's load state as NON-ENUMERABLE own properties, so it never
+enters snapshots, undo history or saved projects. Always via defineProperty
+(the pattern `setPhysicsLiveRef` uses): plain assignment on a
+history-restored clone would create an ENUMERABLE property instead.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `component` | [`ModelComponent`](../classes/ModelComponent.md) |
+| `state` | [`ModelLoadState`](../type-aliases/ModelLoadState.md) |
+| `error?` | `string` |
+
+## Returns
+
+`void`

package/dist/docs/api/components/functions/setPhysicsLiveRef.md

@@ -13,21 +13,15 @@ function setPhysicsLiveRef(
    value): void;
 ```
 
-Defined in: [components/Physics.ts:357](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L357)
-
-Write a live Rapier ref as a NON-ENUMERABLE own property. Always via
-defineProperty (mirroring ScriptObjectComponent's `instance` ref): a
-history-restored clone that dropped the original slot would otherwise get an
-ENUMERABLE property from plain assignment, leaking Rapier objects — and for
-trimesh their huge vertex buffers — into snapshot/history/debug walks.
+Defined in: [components/Physics.ts:370](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L370)
 
 ## Parameters
 
 | Parameter | Type |
 | ------ | ------ |
 | `component` | [`PhysicsComponent`](../classes/PhysicsComponent.md) |
-| `key` | `"collider"` \| `"rigidBody"` |
-| `value` | `RigidBody` \| `Collider` \| `null` |
+| `key` | `"collider"` \| `"rigidBody"` \| `"pendingVelocity"` |
+| `value` | `RigidBody` \| `Collider` \| `PendingBodyVelocity` \| `null` |
 
 ## Returns
 

package/dist/docs/api/components/index.md

@@ -16,7 +16,7 @@
 | [AudioComponent](classes/AudioComponent.md) | Plays an audio clip from `path`. Supports both global stereo (`positional: false`) and 3D positional audio with the configured distance model. Runtime fields (`object`, `audio`, `isPlaying`, `isPaused`) are recreated when the project loads and are never persisted to saved snapshots. |
 | [CameraComponent](classes/CameraComponent.md) | Camera entity state. Supports perspective and orthographic projections, a `3d` or `ar` runtime type, and an `isDefault` flag for the camera that the preview/editor renders through. Field-of-view, near/far, ortho frustum, and zoom are persisted; the live `THREE.Camera` is recreated when the project loads. |
 | [EntityType](classes/EntityType.md) | Tags an entity with the kind it was created from (`cube`, `sphere`, `model`, `directionalLight`, etc.). Factories use this to drive kind-specific behavior; the editor inspector uses it to select component editors. |
-| [Environment](classes/Environment.md) | Scene environment settings: skybox (gradient/color/image), fog (linear/exponential), and gravity vector for the physics world. Singleton-style — attached to one environment entity per scene. |
+| [Environment](classes/Environment.md) | Scene environment settings: skybox (gradient/color/image), fog (linear/exponential), gravity vector for the physics world, and optional image-based lighting / tone mapping (`values.lighting`). Singleton-style — attached to one environment entity per scene. |
 | [ImageComponent](classes/ImageComponent.md) | Renders a 2D image as a textured quad in the scene. Width/height are in world units. Texture loading is handled by the image system, which populates [ImageComponent.texture](classes/ImageComponent.md#texture) and [ImageComponent.object](classes/ImageComponent.md#object) asynchronously. |
 | [ImageTarget](classes/ImageTarget.md) | Image-tracking target metadata used by AR projects. Holds the source images users uploaded plus the URL of the compiled `.mind` target file produced by the image-target compiler. Pair with [ImageTargetAnchor](classes/ImageTargetAnchor.md) on child entities that should appear when the target is detected. |
 | [ImageTargetAnchor](classes/ImageTargetAnchor.md) | Marks an entity as an anchor for an image-tracking target. The image tracking system reveals the entity when the referenced target is found and hides it when the target is lost. |
@@ -26,7 +26,7 @@
 | [MaterialComponent](classes/MaterialComponent.md) | Material catalog for an entity. Tracks the live three.js materials (`materials`, `material`) plus serialized authoring state (`values[]`) mirrored from the inspector. Supports `standard`, `basic`, `phong`, and `physical` PBR types with optional texture map slots. |
 | [MeshComponent](classes/MeshComponent.md) | Holds the live three.js `Object3D` for an entity that renders as a primitive mesh (cube, sphere, plane, capsule, cylinder). For loaded GLTF/GLB models see [ModelComponent](classes/ModelComponent.md); for the editable geometry parameters see [MeshGeometryComponent](classes/MeshGeometryComponent.md). |
 | [MeshGeometryComponent](classes/MeshGeometryComponent.md) | Editable geometry parameters for primitive meshes (cube, sphere, plane, capsule, cylinder) and the placeholder for `model` entities. Holds the authoring values plus shadow casting/receiving flags. The mesh-geometry system rebuilds the underlying `BufferGeometry` when parameters change. |
-| [ModelComponent](classes/ModelComponent.md) | References a GLTF/GLB asset loaded from `path`. The model loading system resolves the asset asynchronously and populates [ModelComponent.object](classes/ModelComponent.md#object) once available; loading is deferred-tolerant so the entity exists before the model finishes loading. |
+| [ModelComponent](classes/ModelComponent.md) | References a GLTF/GLB asset loaded from `path`. The model loading system resolves the asset asynchronously and populates [ModelComponent.object](classes/ModelComponent.md#object) once available; loading is deferred-tolerant so the entity exists before the model finishes loading. [ModelComponent.loadState](classes/ModelComponent.md#loadstate) reports progress (`"loading"` → `"loaded"` or `"error"`). |
 | [Name](classes/Name.md) | Human-readable name for an entity. Shown in the editor hierarchy panel and preserved across save/reload. |
 | [Object3DRef](classes/Object3DRef.md) | Wraps the live `THREE.Object3D` for an entity. Almost every entity that renders to the scene carries an `Object3DRef` so transform sync, selection, and parenting systems can manipulate the underlying object. |
 | [ParentId](classes/ParentId.md) | Records the parent entity id for hierarchical scene graphs. `null` means the entity is at the world root. The `ObjectManagementSystem` reconciles scene-graph parenting from this component each frame. |
@@ -40,26 +40,43 @@
 | [SelectionTransformState](classes/SelectionTransformState.md) | Singleton-style component (attached once to a system entity) that mirrors the editor's current transform-gizmo state into the ECS world. Persisted in snapshots so undo/redo restores the exact gizmo configuration. |
 | [SpriteComponent](classes/SpriteComponent.md) | Camera-facing 2D sprite. Unlike [ImageComponent](classes/ImageComponent.md), sprites use `THREE.Sprite` and always render as billboards. |
 | [TransformComponent](classes/TransformComponent.md) | Position, rotation, and scale of an entity in its parent's local space. |
+| [UIButtonComponent](classes/UIButtonComponent.md) | A pressable control. |
+| [UIPanelComponent](classes/UIPanelComponent.md) | A flat UI surface in the world — the backdrop menus and HUDs are built on. |
+| [UISliderComponent](classes/UISliderComponent.md) | A draggable value control. |
+| [UITextComponent](classes/UITextComponent.md) | A block of text drawn onto a transparent canvas quad. |
+| [UIToggleComponent](classes/UIToggleComponent.md) | An on/off switch. |
+| [VRTeleportAreaComponent](classes/VRTeleportAreaComponent.md) | Marks an entity's surface as a valid teleport destination. |
 | [VideoComponent](classes/VideoComponent.md) | Plays a video file as a texture on a quad. Supports green-screen keying (`isGreenScreen`, `backgroundColor`, `similarity`, `smoothness`, `spill`). The video element, texture, and material are runtime-only and re-created when the project loads. |
+| [XRAnchorComponent](classes/XRAnchorComponent.md) | Pins an entity to a real-world position. |
+| [XREnvironmentComponent](classes/XREnvironmentComponent.md) | Marks an entity as a piece of the user's REAL room, detected at runtime. |
+| [XRHandPoseComponent](classes/XRHandPoseComponent.md) | Listens for hand poses and reports them to the entity's Behaviours. |
+| [XRInteractableComponent](classes/XRInteractableComponent.md) | Makes an entity respond to XR pointers and hands. |
+| [XRInteractorComponent](classes/XRInteractorComponent.md) | Configures what the user sees as their hands, and hosts custom hand content. |
+| [XRInteractorSideComponent](classes/XRInteractorSideComponent.md) | Marks an entity as the left or right hand slot of an [XRInteractorComponent](classes/XRInteractorComponent.md). |
+| [XRRigComponent](classes/XRRigComponent.md) | Marks an entity as the XR rig — the player's movable origin. |
 
 ## Type Aliases
 
 | Type Alias | Description |
 | ------ | ------ |
 | [AnimationComponentOptions](type-aliases/AnimationComponentOptions.md) | Initializer for [AnimationComponent](classes/AnimationComponent.md). |
-| [CameraRuntimeType](type-aliases/CameraRuntimeType.md) | Runtime camera mode. `3d` is a free camera; `ar` is composited over a tracked image/face feed. |
+| [CameraRuntimeType](type-aliases/CameraRuntimeType.md) | Runtime camera mode. `3d` is a free camera; `ar` is composited over a tracked image/face feed; `xr` is driven by an immersive WebXR session (the headset owns the pose and projection — locomotion moves the camera's XR rig parent). |
 | [CameraProjection](type-aliases/CameraProjection.md) | Projection model. |
 | [CameraComponentOptions](type-aliases/CameraComponentOptions.md) | Optional initializer for [CameraComponent](classes/CameraComponent.md). Any field omitted falls back to the defaults documented on the component. |
 | [EnvironmentSkyboxType](type-aliases/EnvironmentSkyboxType.md) | Skybox rendering modes. `none` disables skybox rendering entirely. |
 | [EnvironmentGradientEffect](type-aliases/EnvironmentGradientEffect.md) | Gradient distribution applied when [EnvironmentSkyboxState.type](type-aliases/EnvironmentSkyboxState.md#type) is `"gradient"`. |
 | [EnvironmentFogType](type-aliases/EnvironmentFogType.md) | Fog distance models. `none` disables fog. |
+| [EnvironmentSkyboxImageProjection](type-aliases/EnvironmentSkyboxImageProjection.md) | How an `"image"` skybox is projected. |
+| [EnvironmentToneMapping](type-aliases/EnvironmentToneMapping.md) | Tone-mapping operator applied by the renderer. `"none"` leaves colours linear-clamped (three's `NoToneMapping`). |
 | [EnvironmentSkyboxState](type-aliases/EnvironmentSkyboxState.md) | Skybox configuration. Only the fields relevant to [type](type-aliases/EnvironmentSkyboxState.md#type) are read at render time. |
 | [EnvironmentFogState](type-aliases/EnvironmentFogState.md) | Fog configuration. Mirrors three.js `Fog` / `FogExp2`. |
+| [EnvironmentLightingState](type-aliases/EnvironmentLightingState.md) | Image-based lighting and renderer colour settings. Every field is optional; the defaults below apply when a field is missing. When the whole block is absent the scene's environment map and the renderer's tone mapping are left untouched. |
 | [EnvironmentState](type-aliases/EnvironmentState.md) | Aggregated authoring state owned by [Environment](classes/Environment.md). |
 | [ImageTargetReference](type-aliases/ImageTargetReference.md) | Single uploaded image used as input to the image-target compiler. |
 | [ImageTargetAnchorOptions](type-aliases/ImageTargetAnchorOptions.md) | Optional initializer for [ImageTargetAnchor](classes/ImageTargetAnchor.md). |
 | [InstanceTransform](type-aliases/InstanceTransform.md) | Per-instance transform stored inside [InstancedMeshComponent](classes/InstancedMeshComponent.md). All rotations are in radians. |
 | [InstancedMeshKind](type-aliases/InstancedMeshKind.md) | Primitive geometry kinds and custom 3D model kind supported by instanced mesh rendering. |
+| [LightShadowState](type-aliases/LightShadowState.md) | Optional shadow tuning for a shadow-casting light (directional, spot, point). Only the fields present are applied; a missing field keeps three's default, and a light without a `shadow` block is never touched. |
 | [LightValueState](type-aliases/LightValueState.md) | Authoring state for [LightComponent](classes/LightComponent.md). Common fields apply to every light kind; the optional fields are only meaningful for specific kinds. |
 | [MaterialTypeValue](type-aliases/MaterialTypeValue.md) | Supported material classes. Each maps to a three.js `Mesh*Material` type. |
 | [TextureFilteringValue](type-aliases/TextureFilteringValue.md) | Texture sampling mode. `smooth` uses linear filtering; `sharp` uses nearest filtering for pixel-art look. |
@@ -71,6 +88,7 @@
 | [RadiusHeightMeshParameters](type-aliases/RadiusHeightMeshParameters.md) | Radius + height primitive parameters (capsule, cylinder). |
 | [MeshGeometryParametersByKind](type-aliases/MeshGeometryParametersByKind.md) | Map from [EditableMeshObjectKind](type-aliases/EditableMeshObjectKind.md) to its parameter shape. |
 | [MeshGeometryParameters](type-aliases/MeshGeometryParameters.md) | - |
+| [ModelLoadState](type-aliases/ModelLoadState.md) | Load progress of a [ModelComponent](classes/ModelComponent.md)'s asset. |
 | [RigidbodyType](type-aliases/RigidbodyType.md) | Rigidbody body type: - `dynamic`: simulated by physics; affected by forces and gravity. - `fixed`: immovable static body. - `kinematicPosition`: moved by setting next position; ignores forces. - `kinematicVelocity`: moved by setting velocity; ignores forces. |
 | [RigidbodyState](type-aliases/RigidbodyState.md) | Authoring state for the rigidbody half of [PhysicsComponent](classes/PhysicsComponent.md). Saved with the project. |
 | [ColliderShape](type-aliases/ColliderShape.md) | Collider primitive shape. `trimesh` derives geometry from the entity's mesh. |
@@ -84,24 +102,63 @@
 | [TransformSpaceValue](type-aliases/TransformSpaceValue.md) | Reference frame for the active gizmo. |
 | [Vec3](type-aliases/Vec3.md) | Plain XYZ vector. All ECS transform fields use this shape rather than `THREE.Vector3` so they save cleanly with the project. |
 | [TransformData](type-aliases/TransformData.md) | Optional initial values passed to [TransformComponent](classes/TransformComponent.md). Missing axes default to `0` for position/rotation and `1` for scale. |
+| [UIButtonOptions](type-aliases/UIButtonOptions.md) | Optional initializer for [UIButtonComponent](classes/UIButtonComponent.md). |
+| [UiFollowMode](type-aliases/UiFollowMode.md) | How a panel orients itself while the experience runs. |
+| [UIPanelOptions](type-aliases/UIPanelOptions.md) | Optional initializer for [UIPanelComponent](classes/UIPanelComponent.md). |
+| [UISliderOptions](type-aliases/UISliderOptions.md) | Optional initializer for [UISliderComponent](classes/UISliderComponent.md). |
+| [UiTextAlign](type-aliases/UiTextAlign.md) | - |
+| [UiTextVAlign](type-aliases/UiTextVAlign.md) | - |
+| [UITextOptions](type-aliases/UITextOptions.md) | Optional initializer for [UITextComponent](classes/UITextComponent.md). |
+| [UIToggleOptions](type-aliases/UIToggleOptions.md) | Optional initializer for [UIToggleComponent](classes/UIToggleComponent.md). |
+| [VrTeleportShape](type-aliases/VrTeleportShape.md) | Footprint of a teleport destination. |
+| [VRTeleportAreaOptions](type-aliases/VRTeleportAreaOptions.md) | Optional initializer for [VRTeleportAreaComponent](classes/VRTeleportAreaComponent.md). |
+| [XRAnchorOptions](type-aliases/XRAnchorOptions.md) | Optional initializer for [XRAnchorComponent](classes/XRAnchorComponent.md). |
+| [XrEnvironmentKind](type-aliases/XrEnvironmentKind.md) | Which WebXR module reported this piece of the room. |
+| [XrEnvironmentOrientation](type-aliases/XrEnvironmentOrientation.md) | How a detected plane sits in the world, when the runtime says. |
+| [XrHandPoseEntry](type-aliases/XrHandPoseEntry.md) | One pose an entity listens for. |
+| [XRHandPoseOptions](type-aliases/XRHandPoseOptions.md) | - |
+| [XrGrabReach](type-aliases/XrGrabReach.md) | How close the user must be to grab. |
+| [XrDistanceGrabBehavior](type-aliases/XrDistanceGrabBehavior.md) | What a distance grab does to the object. |
+| [XrGrabGesture](type-aliases/XrGrabGesture.md) | Which gesture grabs the object. |
+| [XrAttachPoint](type-aliases/XrAttachPoint.md) | A hand-hold authored on the object. |
+| [XrGrabHands](type-aliases/XrGrabHands.md) | How many hands may hold the object at once, and what a second grab does. |
+| [XrTwoHandRotation](type-aliases/XrTwoHandRotation.md) | How the second hand affects orientation. See `solveTwoHandTransform`. |
+| [XRInteractableOptions](type-aliases/XRInteractableOptions.md) | Optional initializer for [XRInteractableComponent](classes/XRInteractableComponent.md). |
+| [XrInteractorType](type-aliases/XrInteractorType.md) | - |
+| [XrHandPreset](type-aliases/XrHandPreset.md) | Look applied to tracked-hand meshes. |
+| [XrInteractorSide](type-aliases/XrInteractorSide.md) | Which hand a child interactor entity follows. |
+| [XRInteractorOptions](type-aliases/XRInteractorOptions.md) | Optional initializer for [XRInteractorComponent](classes/XRInteractorComponent.md). |
+| [XrTrackingOrigin](type-aliases/XrTrackingOrigin.md) | Where the headset's origin sits in the scene. |
+| [XrLocomotionMode](type-aliases/XrLocomotionMode.md) | How the player moves through the scene in an immersive session. |
+| [XrEnvironmentPhysics](type-aliases/XrEnvironmentPhysics.md) | Which real-world geometry becomes physics colliders in a passthrough session. |
+| [XRRigOptions](type-aliases/XRRigOptions.md) | Optional initializer for [XRRigComponent](classes/XRRigComponent.md). |
 
 ## Variables
 
 | Variable | Description |
 | ------ | ------ |
+| [DEFAULT\_ENVIRONMENT\_LIGHTING](variables/DEFAULT_ENVIRONMENT_LIGHTING.md) | Defaults for every [EnvironmentLightingState](type-aliases/EnvironmentLightingState.md) field. |
 | [DEFAULT\_ENVIRONMENT\_STATE](variables/DEFAULT_ENVIRONMENT_STATE.md) | - |
 | [DEFAULT\_INSTANCE\_TRANSFORM](variables/DEFAULT_INSTANCE_TRANSFORM.md) | Default identity instance transform. |
 | [DEFAULT\_INSTANCED\_MESH\_PARAMETERS](variables/DEFAULT_INSTANCED_MESH_PARAMETERS.md) | Default geometry parameters per instanced mesh kind. For "model" kind, cube params are stored as a placeholder (unused). |
 | [DEFAULT\_MESH\_GEOMETRY\_PARAMETERS](variables/DEFAULT_MESH_GEOMETRY_PARAMETERS.md) | - |
+| [MODEL\_NO\_PATH\_MESSAGE](variables/MODEL_NO_PATH_MESSAGE.md) | Message used when a model entity has no asset path to load. |
 | [DEFAULT\_RIGIDBODY\_STATE](variables/DEFAULT_RIGIDBODY_STATE.md) | - |
 | [DEFAULT\_COLLIDER\_STATE](variables/DEFAULT_COLLIDER_STATE.md) | - |
 | [DEFAULT\_PHYSICS\_STATE](variables/DEFAULT_PHYSICS_STATE.md) | - |
 | [DEFAULT\_POSTPROCESSING\_STATE](variables/DEFAULT_POSTPROCESSING_STATE.md) | - |
+| [DEFAULT\_POSE\_CURLS](variables/DEFAULT_POSE_CURLS.md) | - |
+| [DEFAULT\_POSE\_DIRECTIONS](variables/DEFAULT_POSE_DIRECTIONS.md) | - |
 
 ## Functions
 
 | Function | Description |
 | ------ | ------ |
+| [normalizeEnvironmentLighting](functions/normalizeEnvironmentLighting.md) | Normalize a lighting block to a complete [EnvironmentLightingState](type-aliases/EnvironmentLightingState.md). Returns `undefined` when `value` is not an object, so a scene without the block stays without it. |
 | [defaultMaterialValue](functions/defaultMaterialValue.md) | - |
+| [setModelLoadState](functions/setModelLoadState.md) | Write a model's load state as NON-ENUMERABLE own properties, so it never enters snapshots, undo history or saved projects. Always via defineProperty (the pattern `setPhysicsLiveRef` uses): plain assignment on a history-restored clone would create an ENUMERABLE property instead. |
 | [normalizePhysicsState](functions/normalizePhysicsState.md) | - |
-| [setPhysicsLiveRef](functions/setPhysicsLiveRef.md) | Write a live Rapier ref as a NON-ENUMERABLE own property. Always via defineProperty (mirroring ScriptObjectComponent's `instance` ref): a history-restored clone that dropped the original slot would otherwise get an ENUMERABLE property from plain assignment, leaking Rapier objects — and for trimesh their huge vertex buffers — into snapshot/history/debug walks. |
+| [setPhysicsLiveRef](functions/setPhysicsLiveRef.md) | - |
+| [createHandPoseEntry](functions/createHandPoseEntry.md) | A pose entry with every field populated, for the editor and AI tools. |
+| [handPoseDefinitionFor](functions/handPoseDefinitionFor.md) | Resolve an entry to the definition the matcher consumes. |
+| [createAttachPoint](functions/createAttachPoint.md) | An attach point with every field populated, for the editor and AI tools. |

package/dist/docs/api/components/type-aliases/AnimationComponentOptions.md

@@ -24,7 +24,7 @@ type AnimationComponentOptions = {
 };
 ```
 
-Defined in: [components/Animation.ts:10](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L10)
+Defined in: [components/Animation.ts:10](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Animation.ts#L10)
 
 Initializer for [AnimationComponent](../classes/AnimationComponent.md).
 
@@ -32,11 +32,11 @@ Initializer for [AnimationComponent](../classes/AnimationComponent.md).
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="clips"></a> `clips?` | `THREE.AnimationClip`[] | Initial set of clips imported from the entity's model. | [components/Animation.ts:12](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L12) |
-| <a id="externalclipsources"></a> `externalClipSources?` | `string`[] | URLs (or `localasset://` paths) of clips to load asynchronously and merge into the catalog. | [components/Animation.ts:14](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L14) |
-| <a id="activestate"></a> `activeState?` | `string` \| `null` | Name of the state to activate after construction. | [components/Animation.ts:16](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L16) |
-| <a id="paused"></a> `paused?` | `boolean` | Whether playback starts paused. | [components/Animation.ts:18](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L18) |
-| <a id="reverse"></a> `reverse?` | `boolean` | Play the active clip in reverse. | [components/Animation.ts:20](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L20) |
-| <a id="timescale"></a> `timeScale?` | `number` | Time-scale multiplier (`1` = real-time). | [components/Animation.ts:22](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L22) |
-| <a id="crossfadeduration"></a> `crossFadeDuration?` | `number` | Default cross-fade duration in seconds when switching states. | [components/Animation.ts:24](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L24) |
-| <a id="states"></a> `states?` | \{ `name`: `string`; `clip`: `string`; `clipId?`: `string`; `loop?`: `boolean`; \}[] | Predefined state machine entries (`name` -> clip binding). | [components/Animation.ts:26](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L26) |
+| <a id="clips"></a> `clips?` | `THREE.AnimationClip`[] | Initial set of clips imported from the entity's model. | [components/Animation.ts:12](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Animation.ts#L12) |
+| <a id="externalclipsources"></a> `externalClipSources?` | `string`[] | URLs (or `localasset://` paths) of clips to load asynchronously and merge into the catalog. | [components/Animation.ts:14](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Animation.ts#L14) |
+| <a id="activestate"></a> `activeState?` | `string` \| `null` | Name of the state to activate after construction. | [components/Animation.ts:16](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Animation.ts#L16) |
+| <a id="paused"></a> `paused?` | `boolean` | Whether playback starts paused. | [components/Animation.ts:18](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Animation.ts#L18) |
+| <a id="reverse"></a> `reverse?` | `boolean` | Play the active clip in reverse. | [components/Animation.ts:20](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Animation.ts#L20) |
+| <a id="timescale"></a> `timeScale?` | `number` | Time-scale multiplier (`1` = real-time). | [components/Animation.ts:22](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Animation.ts#L22) |
+| <a id="crossfadeduration"></a> `crossFadeDuration?` | `number` | Default cross-fade duration in seconds when switching states. | [components/Animation.ts:24](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Animation.ts#L24) |
+| <a id="states"></a> `states?` | \{ `name`: `string`; `clip`: `string`; `clipId?`: `string`; `loop?`: `boolean`; \}[] | Predefined state machine entries (`name` -> clip binding). | [components/Animation.ts:26](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Animation.ts#L26) |

package/dist/docs/api/components/type-aliases/CameraComponentOptions.md

@@ -23,7 +23,7 @@ type CameraComponentOptions = {
 };
 ```
 
-Defined in: [components/Camera.ts:11](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L11)
+Defined in: [components/Camera.ts:15](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L15)
 
 Optional initializer for [CameraComponent](../classes/CameraComponent.md). Any field omitted falls back to the defaults documented on the component.
 
@@ -31,15 +31,15 @@ Optional initializer for [CameraComponent](../classes/CameraComponent.md). Any f
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="camera"></a> `camera?` | `THREE.Camera` | Pre-built three.js camera. When omitted the component creates one from [projection](#projection). | [components/Camera.ts:13](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L13) |
-| <a id="type"></a> `type?` | [`CameraRuntimeType`](CameraRuntimeType.md) | Runtime camera mode. | [components/Camera.ts:15](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L15) |
-| <a id="isdefault"></a> `isDefault?` | `boolean` | Mark this camera as the default camera the renderer uses. | [components/Camera.ts:17](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L17) |
-| <a id="projection"></a> `projection?` | [`CameraProjection`](CameraProjection.md) | Projection model. | [components/Camera.ts:19](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L19) |
-| <a id="fov"></a> `fov?` | `number` | Vertical field of view in **degrees** (perspective only). | [components/Camera.ts:21](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L21) |
-| <a id="near"></a> `near?` | `number` | Near clip plane in world units. | [components/Camera.ts:23](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L23) |
-| <a id="far"></a> `far?` | `number` | Far clip plane in world units. | [components/Camera.ts:25](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L25) |
-| <a id="left"></a> `left?` | `number` | Left edge of the orthographic frustum in world units. | [components/Camera.ts:27](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L27) |
-| <a id="right"></a> `right?` | `number` | Right edge of the orthographic frustum in world units. | [components/Camera.ts:29](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L29) |
-| <a id="top"></a> `top?` | `number` | Top edge of the orthographic frustum in world units. | [components/Camera.ts:31](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L31) |
-| <a id="bottom"></a> `bottom?` | `number` | Bottom edge of the orthographic frustum in world units. | [components/Camera.ts:33](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L33) |
-| <a id="zoom"></a> `zoom?` | `number` | Zoom multiplier (`1` = no zoom). | [components/Camera.ts:35](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L35) |
+| <a id="camera"></a> `camera?` | `THREE.Camera` | Pre-built three.js camera. When omitted the component creates one from [projection](#projection). | [components/Camera.ts:17](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L17) |
+| <a id="type"></a> `type?` | [`CameraRuntimeType`](CameraRuntimeType.md) | Runtime camera mode. | [components/Camera.ts:19](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L19) |
+| <a id="isdefault"></a> `isDefault?` | `boolean` | Mark this camera as the default camera the renderer uses. | [components/Camera.ts:21](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L21) |
+| <a id="projection"></a> `projection?` | [`CameraProjection`](CameraProjection.md) | Projection model. | [components/Camera.ts:23](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L23) |
+| <a id="fov"></a> `fov?` | `number` | Vertical field of view in **degrees** (perspective only). | [components/Camera.ts:25](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L25) |
+| <a id="near"></a> `near?` | `number` | Near clip plane in world units. | [components/Camera.ts:27](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L27) |
+| <a id="far"></a> `far?` | `number` | Far clip plane in world units. | [components/Camera.ts:29](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L29) |
+| <a id="left"></a> `left?` | `number` | Left edge of the orthographic frustum in world units. | [components/Camera.ts:31](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L31) |
+| <a id="right"></a> `right?` | `number` | Right edge of the orthographic frustum in world units. | [components/Camera.ts:33](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L33) |
+| <a id="top"></a> `top?` | `number` | Top edge of the orthographic frustum in world units. | [components/Camera.ts:35](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L35) |
+| <a id="bottom"></a> `bottom?` | `number` | Bottom edge of the orthographic frustum in world units. | [components/Camera.ts:37](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L37) |
+| <a id="zoom"></a> `zoom?` | `number` | Zoom multiplier (`1` = no zoom). | [components/Camera.ts:39](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L39) |

package/dist/docs/api/components/type-aliases/CameraProjection.md

@@ -10,6 +10,6 @@
 type CameraProjection = "perspective" | "orthographic";
 ```
 
-Defined in: [components/Camera.ts:8](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L8)
+Defined in: [components/Camera.ts:12](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L12)
 
 Projection model.

package/dist/docs/api/components/type-aliases/CameraRuntimeType.md

@@ -7,9 +7,11 @@
 # Type Alias: CameraRuntimeType
 
 ```ts
-type CameraRuntimeType = "3d" | "ar";
+type CameraRuntimeType = "3d" | "ar" | "xr";
 ```
 
-Defined in: [components/Camera.ts:6](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Camera.ts#L6)
+Defined in: [components/Camera.ts:10](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Camera.ts#L10)
 
-Runtime camera mode. `3d` is a free camera; `ar` is composited over a tracked image/face feed.
+Runtime camera mode. `3d` is a free camera; `ar` is composited over a tracked
+image/face feed; `xr` is driven by an immersive WebXR session (the headset
+owns the pose and projection — locomotion moves the camera's XR rig parent).

package/dist/docs/api/components/type-aliases/ColliderShape.md

@@ -10,6 +10,6 @@
 type ColliderShape = "cuboid" | "ball" | "capsule" | "cylinder" | "trimesh";
 ```
 
-Defined in: [components/Physics.ts:83](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L83)
+Defined in: [components/Physics.ts:83](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L83)
 
 Collider primitive shape. `trimesh` derives geometry from the entity's mesh.

package/dist/docs/api/components/type-aliases/ColliderState.md

@@ -33,7 +33,7 @@ type ColliderState = {
 };
 ```
 
-Defined in: [components/Physics.ts:91](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L91)
+Defined in: [components/Physics.ts:91](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L91)
 
 Authoring state for the collider half of [PhysicsComponent](../classes/PhysicsComponent.md). Only the size fields relevant to [ColliderState.shape](#shape) are read at simulation time.
 
@@ -41,22 +41,22 @@ Authoring state for the collider half of [PhysicsComponent](../classes/PhysicsCo
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="enabled"></a> `enabled` | `boolean` | When `false`, the collider is removed from physics simulation but kept in state. | [components/Physics.ts:93](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L93) |
-| <a id="shape"></a> `shape` | [`ColliderShape`](ColliderShape.md) | Collider primitive shape. | [components/Physics.ts:95](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L95) |
-| <a id="offsetposition"></a> `offsetPosition` | \{ `x`: `number`; `y`: `number`; `z`: `number`; \} | Local offset of the collider relative to the entity's transform, in world units. | [components/Physics.ts:97](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L97) |
-| `offsetPosition.x` | `number` | Offset along local X. | [components/Physics.ts:99](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L99) |
-| `offsetPosition.y` | `number` | Offset along local Y. | [components/Physics.ts:101](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L101) |
-| `offsetPosition.z` | `number` | Offset along local Z. | [components/Physics.ts:103](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L103) |
-| <a id="offsetrotation"></a> `offsetRotation` | \{ `x`: `number`; `y`: `number`; `z`: `number`; \} | Local rotation offset in **radians** (Euler XYZ). | [components/Physics.ts:106](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L106) |
-| `offsetRotation.x` | `number` | Rotation around local X (radians). | [components/Physics.ts:108](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L108) |
-| `offsetRotation.y` | `number` | Rotation around local Y (radians). | [components/Physics.ts:110](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L110) |
-| `offsetRotation.z` | `number` | Rotation around local Z (radians). | [components/Physics.ts:112](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L112) |
-| <a id="size"></a> `size` | \{ `x`: `number`; `y`: `number`; `z`: `number`; \} | FULL edge lengths for `cuboid` shape (NOT half-extents), in unscaled local units — multiplied by the entity world scale at collider build time. | [components/Physics.ts:115](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L115) |
-| `size.x` | `number` | Half-extent along X. | [components/Physics.ts:117](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L117) |
-| `size.y` | `number` | Half-extent along Y. | [components/Physics.ts:119](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L119) |
-| `size.z` | `number` | Half-extent along Z. | [components/Physics.ts:121](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L121) |
-| <a id="radius"></a> `radius` | `number` | Radius for `ball`, `capsule`, and `cylinder` shapes. | [components/Physics.ts:124](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L124) |
-| <a id="height"></a> `height` | `number` | Height for `capsule` (segment length between caps) and `cylinder`. | [components/Physics.ts:126](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L126) |
-| <a id="restitution"></a> `restitution` | `number` | Bounciness in `[0, 1]`. `0` is no bounce; `1` is perfectly elastic. | [components/Physics.ts:128](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L128) |
-| <a id="friction"></a> `friction` | `number` | Surface friction coefficient. `0` is frictionless. | [components/Physics.ts:130](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L130) |
-| <a id="issensor"></a> `isSensor` | `boolean` | When `true`, the collider reports overlaps but does not generate contact responses. | [components/Physics.ts:132](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Physics.ts#L132) |
+| <a id="enabled"></a> `enabled` | `boolean` | When `false`, the collider is removed from physics simulation but kept in state. | [components/Physics.ts:93](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L93) |
+| <a id="shape"></a> `shape` | [`ColliderShape`](ColliderShape.md) | Collider primitive shape. | [components/Physics.ts:95](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L95) |
+| <a id="offsetposition"></a> `offsetPosition` | \{ `x`: `number`; `y`: `number`; `z`: `number`; \} | Local offset of the collider relative to the entity's transform, in world units. | [components/Physics.ts:97](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L97) |
+| `offsetPosition.x` | `number` | Offset along local X. | [components/Physics.ts:99](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L99) |
+| `offsetPosition.y` | `number` | Offset along local Y. | [components/Physics.ts:101](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L101) |
+| `offsetPosition.z` | `number` | Offset along local Z. | [components/Physics.ts:103](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L103) |
+| <a id="offsetrotation"></a> `offsetRotation` | \{ `x`: `number`; `y`: `number`; `z`: `number`; \} | Local rotation offset in **radians** (Euler XYZ). | [components/Physics.ts:106](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L106) |
+| `offsetRotation.x` | `number` | Rotation around local X (radians). | [components/Physics.ts:108](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L108) |
+| `offsetRotation.y` | `number` | Rotation around local Y (radians). | [components/Physics.ts:110](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L110) |
+| `offsetRotation.z` | `number` | Rotation around local Z (radians). | [components/Physics.ts:112](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L112) |
+| <a id="size"></a> `size` | \{ `x`: `number`; `y`: `number`; `z`: `number`; \} | FULL edge lengths for `cuboid` shape (NOT half-extents), in unscaled local units — multiplied by the entity world scale at collider build time. | [components/Physics.ts:115](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L115) |
+| `size.x` | `number` | Half-extent along X. | [components/Physics.ts:117](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L117) |
+| `size.y` | `number` | Half-extent along Y. | [components/Physics.ts:119](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L119) |
+| `size.z` | `number` | Half-extent along Z. | [components/Physics.ts:121](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L121) |
+| <a id="radius"></a> `radius` | `number` | Radius for `ball`, `capsule`, and `cylinder` shapes. | [components/Physics.ts:124](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L124) |
+| <a id="height"></a> `height` | `number` | Height for `capsule` (segment length between caps) and `cylinder`. | [components/Physics.ts:126](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L126) |
+| <a id="restitution"></a> `restitution` | `number` | Bounciness in `[0, 1]`. `0` is no bounce; `1` is perfectly elastic. | [components/Physics.ts:128](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L128) |
+| <a id="friction"></a> `friction` | `number` | Surface friction coefficient. `0` is frictionless. | [components/Physics.ts:130](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L130) |
+| <a id="issensor"></a> `isSensor` | `boolean` | When `true`, the collider reports overlaps but does not generate contact responses. | [components/Physics.ts:132](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Physics.ts#L132) |

package/dist/docs/api/components/type-aliases/CubeMeshParameters.md

@@ -14,7 +14,7 @@ type CubeMeshParameters = {
 };
 ```
 
-Defined in: [components/MeshGeometry.ts:15](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/MeshGeometry.ts#L15)
+Defined in: [components/MeshGeometry.ts:15](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/MeshGeometry.ts#L15)
 
 Box geometry parameters in world units.
 
@@ -22,6 +22,6 @@ Box geometry parameters in world units.
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="width"></a> `width` | `number` | Box width along X. | [components/MeshGeometry.ts:17](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/MeshGeometry.ts#L17) |
-| <a id="height"></a> `height` | `number` | Box height along Y. | [components/MeshGeometry.ts:19](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/MeshGeometry.ts#L19) |
-| <a id="depth"></a> `depth` | `number` | Box depth along Z. | [components/MeshGeometry.ts:21](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/MeshGeometry.ts#L21) |
+| <a id="width"></a> `width` | `number` | Box width along X. | [components/MeshGeometry.ts:17](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/MeshGeometry.ts#L17) |
+| <a id="height"></a> `height` | `number` | Box height along Y. | [components/MeshGeometry.ts:19](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/MeshGeometry.ts#L19) |
+| <a id="depth"></a> `depth` | `number` | Box depth along Z. | [components/MeshGeometry.ts:21](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/MeshGeometry.ts#L21) |

package/dist/docs/api/components/type-aliases/EditableMeshObjectKind.md

@@ -10,6 +10,6 @@
 type EditableMeshObjectKind = "capsule" | "cube" | "cylinder" | "model" | "plane" | "sphere";
 ```
 
-Defined in: [components/MeshGeometry.ts:6](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/MeshGeometry.ts#L6)
+Defined in: [components/MeshGeometry.ts:6](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/MeshGeometry.ts#L6)
 
 Editable primitive kinds the mesh-geometry system can rebuild on the fly. `model` is a passthrough placeholder for entities that own a loaded GLTF/GLB instead.

package/dist/docs/api/components/type-aliases/EnvironmentFogState.md

@@ -20,7 +20,7 @@ type EnvironmentFogState = {
 };
 ```
 
-Defined in: [components/Environment.ts:28](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L28)
+Defined in: [components/Environment.ts:49](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L49)
 
 Fog configuration. Mirrors three.js `Fog` / `FogExp2`.
 
@@ -28,10 +28,10 @@ Fog configuration. Mirrors three.js `Fog` / `FogExp2`.
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="type"></a> `type` | [`EnvironmentFogType`](EnvironmentFogType.md) | Active fog model. | [components/Environment.ts:30](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L30) |
-| <a id="color"></a> `color` | `string` | Fog color as `#rrggbb`. | [components/Environment.ts:32](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L32) |
-| <a id="linear"></a> `linear` | \{ `near`: `number`; `far`: `number`; \} | Linear-fog parameters used when [type](#type) is `"linear"`. | [components/Environment.ts:34](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L34) |
-| `linear.near` | `number` | Distance at which fog begins to take effect. | [components/Environment.ts:36](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L36) |
-| `linear.far` | `number` | Distance at which fog reaches full opacity. | [components/Environment.ts:38](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L38) |
-| <a id="exponential"></a> `exponential` | \{ `density`: `number`; \} | Exponential-fog parameters used when [type](#type) is `"exponential"`. | [components/Environment.ts:41](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L41) |
-| `exponential.density` | `number` | Density coefficient. Higher values produce thicker fog. | [components/Environment.ts:43](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L43) |
+| <a id="type"></a> `type` | [`EnvironmentFogType`](EnvironmentFogType.md) | Active fog model. | [components/Environment.ts:51](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L51) |
+| <a id="color"></a> `color` | `string` | Fog color as `#rrggbb`. | [components/Environment.ts:53](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L53) |
+| <a id="linear"></a> `linear` | \{ `near`: `number`; `far`: `number`; \} | Linear-fog parameters used when [type](#type) is `"linear"`. | [components/Environment.ts:55](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L55) |
+| `linear.near` | `number` | Distance at which fog begins to take effect. | [components/Environment.ts:57](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L57) |
+| `linear.far` | `number` | Distance at which fog reaches full opacity. | [components/Environment.ts:59](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L59) |
+| <a id="exponential"></a> `exponential` | \{ `density`: `number`; \} | Exponential-fog parameters used when [type](#type) is `"exponential"`. | [components/Environment.ts:62](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L62) |
+| `exponential.density` | `number` | Density coefficient. Higher values produce thicker fog. | [components/Environment.ts:64](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L64) |

package/dist/docs/api/components/type-aliases/EnvironmentFogType.md

@@ -10,6 +10,6 @@
 type EnvironmentFogType = "linear" | "exponential" | "none";
 ```
 
-Defined in: [components/Environment.ts:8](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L8)
+Defined in: [components/Environment.ts:8](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L8)
 
 Fog distance models. `none` disables fog.

package/dist/docs/api/components/type-aliases/EnvironmentGradientEffect.md

@@ -10,6 +10,6 @@
 type EnvironmentGradientEffect = "radial" | "linear" | "angular";
 ```
 
-Defined in: [components/Environment.ts:6](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Environment.ts#L6)
+Defined in: [components/Environment.ts:6](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/components/Environment.ts#L6)
 
 Gradient distribution applied when [EnvironmentSkyboxState.type](EnvironmentSkyboxState.md#type) is `"gradient"`.