@relu-interactives/spatial-ecs 0.5.3 → 0.9.0

package/dist/docs/api/Behaviour/classes/Behaviour.md

@@ -6,55 +6,7 @@
 
 # Class: Behaviour
 
-Defined in: [Behaviour.ts:64](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L64)
-
-Base class for all user-authored scripts attached to an entity through a
-`ScriptComponent`. Subclass `Behaviour` to drive per-frame logic on a single
-entity with full access to the [World](../../index/classes/World.md), the entity's
-[TransformComponent](../../components/classes/TransformComponent.md), and its three.js [Object3DRef](../../components/classes/Object3DRef.md).
-
-## Remarks
-
-Scripts are dispatched by `ScriptBehaviourSystem` once per frame in this
-order: [Behaviour.init](#init) (first frame only) → [Behaviour.onUpdate](#onupdate).
-Override [Behaviour.onUpdate](#onupdate) for per-frame logic — never override
-[Behaviour.update](#update), which is the engine-managed entry point.
-
-**Editor vs runtime**: `Behaviour` subclasses run ONLY at preview/runtime —
-they never execute in the editor. For a visual that must render and animate
-inside the editor (custom shaders, procedural geometry, grass, anything the
-object palette can't produce), use [ScriptObject](../../index/classes/ScriptObject.md) instead.
-
-The runtime recognizes a script by its **default export** plus the
-inherited static marker `__reluBehaviourClass`. Do not override the marker.
-
-## Example
-
-```ts
-import { Behaviour, type Component } from "@relu-interactives/spatial-ecs";
-
-export default class Spinner extends Behaviour {
-  data: {
-   speed: number;
-   axis: "x" | "y" | "z";
- };
-
-  init() {
-    this.data.speed ??= 1;
-    this.data.axis ??= "y";
-  }
-
-  onUpdate() {
-    this.transform.rotation[this.data.axis] += this.data.speed * this.deltaTime;
-  }
-}
-```
-
-## See
-
- - [World](../../index/classes/World.md)
- - [TransformComponent](../../components/classes/TransformComponent.md)
- - [Object3DRef](../../components/classes/Object3DRef.md)
+Defined in: [Behaviour.ts:83](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L83)
 
 ## Implements
 
@@ -71,7 +23,7 @@ new Behaviour(
    component): Behaviour;
 ```
 
-Defined in: [Behaviour.ts:122](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L122)
+Defined in: [Behaviour.ts:141](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L141)
 
 Engine-managed constructor. Hosts (`ScriptBehaviourSystem`) instantiate
 subclasses with the owning world, the entity id, and the script's `data`
@@ -93,13 +45,13 @@ payload. User code should not call this directly.
 
 | Property | Type | Default value | Description | Defined in |
 | ------ | ------ | ------ | ------ | ------ |
-| <a id="data"></a> `data` | \| [`Component`](../../Component/classes/Component.md) \| `Record`\<`string`, `unknown`\> | `undefined` | Inspector-bound payload from the entity's `ScriptComponent`. Override the type on subclasses with `declare data: MyDataShape` to get type safety inside hooks. Saved with the project so values persist across reloads. | [Behaviour.ts:80](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L80) |
-| <a id="entityid"></a> `entityId` | `number` | `undefined` | Numeric id of the entity this script is attached to. | [Behaviour.ts:83](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L83) |
-| <a id="entity"></a> `entity` | `WorldEntityView` | `undefined` | View of the owning entity (id + components) at construction time. | [Behaviour.ts:86](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L86) |
-| <a id="threeref"></a> `threeRef` | [`Object3DRef`](../../components/classes/Object3DRef.md) | `undefined` | Live three.js object wrapper for the entity. May be `null` for entities with no scene presence; helpers on this class return `null` in that case. | [Behaviour.ts:92](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L92) |
-| <a id="transform"></a> `transform` | [`TransformComponent`](../../components/classes/TransformComponent.md) | `undefined` | The entity's [TransformComponent](../../components/classes/TransformComponent.md). Mutating `position`, `rotation`, or `scale` here is picked up the same frame by `TransformSyncSystem`. | [Behaviour.ts:98](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L98) |
-| <a id="world"></a> `world` | [`World`](../../index/classes/World.md) | `undefined` | The owning [World](../../index/classes/World.md). Refreshed each frame in [Behaviour.update](#update). Use it to query other entities or components. | [Behaviour.ts:104](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L104) |
-| <a id="deltatime"></a> `deltaTime` | `number` | `0` | Seconds elapsed since the last frame. Set by the engine before each [Behaviour.onUpdate](#onupdate). | [Behaviour.ts:110](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L110) |
+| <a id="data"></a> `data` | \| [`Component`](../../Component/classes/Component.md) \| `Record`\<`string`, `unknown`\> | `undefined` | Inspector-bound payload from the entity's `ScriptComponent`. Override the type on subclasses with `declare data: MyDataShape` to get type safety inside hooks. Saved with the project so values persist across reloads. | [Behaviour.ts:99](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L99) |
+| <a id="entityid"></a> `entityId` | `number` | `undefined` | Numeric id of the entity this script is attached to. | [Behaviour.ts:102](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L102) |
+| <a id="entity"></a> `entity` | `WorldEntityView` | `undefined` | View of the owning entity (id + components) at construction time. | [Behaviour.ts:105](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L105) |
+| <a id="threeref"></a> `threeRef` | [`Object3DRef`](../../components/classes/Object3DRef.md) | `undefined` | Live three.js object wrapper for the entity. May be `null` for entities with no scene presence; helpers on this class return `null` in that case. | [Behaviour.ts:111](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L111) |
+| <a id="transform"></a> `transform` | [`TransformComponent`](../../components/classes/TransformComponent.md) | `undefined` | The entity's [TransformComponent](../../components/classes/TransformComponent.md). Mutating `position`, `rotation`, or `scale` here is picked up the same frame by `TransformSyncSystem`. | [Behaviour.ts:117](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L117) |
+| <a id="world"></a> `world` | [`World`](../../index/classes/World.md) | `undefined` | The owning [World](../../index/classes/World.md). Refreshed each frame in [Behaviour.update](#update). Use it to query other entities or components. | [Behaviour.ts:123](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L123) |
+| <a id="deltatime"></a> `deltaTime` | `number` | `0` | Seconds elapsed since the last frame. Set by the engine before each [Behaviour.onUpdate](#onupdate). | [Behaviour.ts:129](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L129) |
 
 ## Methods
 
@@ -109,7 +61,7 @@ payload. User code should not call this directly.
 update(world, deltaTime): void;
 ```
 
-Defined in: [Behaviour.ts:146](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L146)
+Defined in: [Behaviour.ts:165](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L165)
 
 Engine-managed per-frame entry point. Refreshes [Behaviour.deltaTime](#deltatime)
 and delegates to [Behaviour.onUpdate](#onupdate).
@@ -144,7 +96,7 @@ CustomEcsSystem.update
 optional dispose(world): void;
 ```
 
-Defined in: [Behaviour.ts:158](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L158)
+Defined in: [Behaviour.ts:177](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L177)
 
 Optional cleanup hook invoked when the script is detached or the entity
 is destroyed. Override to release timers, listeners, or other resources.
@@ -173,7 +125,7 @@ CustomEcsSystem.dispose
 spawnPrefab(source, options?): Promise<number>;
 ```
 
-Defined in: [Behaviour.ts:181](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L181)
+Defined in: [Behaviour.ts:200](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L200)
 
 Instantiate a prefab asset into the world at runtime.
 
@@ -212,7 +164,7 @@ async onUpdate() {
 despawn(rootEntityId): number;
 ```
 
-Defined in: [Behaviour.ts:192](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L192)
+Defined in: [Behaviour.ts:211](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L211)
 
 Remove a spawned prefab instance (the root entity and all descendants).
 Returns the number of entities removed.
@@ -235,7 +187,7 @@ Returns the number of entities removed.
 getWorldPosition(): Vector3 | null;
 ```
 
-Defined in: [Behaviour.ts:200](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L200)
+Defined in: [Behaviour.ts:219](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L219)
 
 Returns the entity's world-space position as a new `THREE.Vector3`, or
 `null` if the entity has no scene presence.
@@ -252,7 +204,7 @@ Returns the entity's world-space position as a new `THREE.Vector3`, or
 getWorldDirection(): Vector3 | null;
 ```
 
-Defined in: [Behaviour.ts:215](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L215)
+Defined in: [Behaviour.ts:234](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L234)
 
 Returns the entity's forward direction in world space (the +Z axis of its
 world matrix), or `null` if the entity has no scene presence.
@@ -269,7 +221,7 @@ world matrix), or `null` if the entity has no scene presence.
 directionTo(targetPosition): Vector3 | null;
 ```
 
-Defined in: [Behaviour.ts:232](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L232)
+Defined in: [Behaviour.ts:251](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L251)
 
 Returns a unit vector pointing from this entity toward the given world
 position, or `null` if the entity has no scene presence.
@@ -292,7 +244,7 @@ position, or `null` if the entity has no scene presence.
 distanceTo(targetPosition): number | null;
 ```
 
-Defined in: [Behaviour.ts:247](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L247)
+Defined in: [Behaviour.ts:266](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L266)
 
 Returns the world-space distance from this entity to the given position,
 or `null` if the entity has no scene presence.
@@ -315,7 +267,7 @@ or `null` if the entity has no scene presence.
 lerpTo(targetPosition, alpha): void;
 ```
 
-Defined in: [Behaviour.ts:265](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L265)
+Defined in: [Behaviour.ts:284](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L284)
 
 Linearly interpolates the entity's position toward `targetPosition` and
 writes the result back through [TransformComponent](../../components/classes/TransformComponent.md). No-op if the
@@ -340,7 +292,7 @@ entity has no scene presence.
 slerpTo(targetRotation, alpha): void;
 ```
 
-Defined in: [Behaviour.ts:287](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L287)
+Defined in: [Behaviour.ts:306](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L306)
 
 Spherically interpolates the entity's rotation toward `targetRotation`
 and writes the result back through [TransformComponent](../../components/classes/TransformComponent.md). No-op if
@@ -365,7 +317,7 @@ the entity has no scene presence.
 lookAt(targetPosition): void;
 ```
 
-Defined in: [Behaviour.ts:306](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L306)
+Defined in: [Behaviour.ts:325](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L325)
 
 Rotates the entity to face `targetPosition` in world space and writes the
 resulting orientation back through [TransformComponent](../../components/classes/TransformComponent.md). No-op if
@@ -389,7 +341,7 @@ the entity has no scene presence.
 getComponents(): Component[];
 ```
 
-Defined in: [Behaviour.ts:320](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L320)
+Defined in: [Behaviour.ts:339](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L339)
 
 Returns every component currently attached to this entity.
 
@@ -405,7 +357,7 @@ Returns every component currently attached to this entity.
 getComponent<T>(componentClass): T | null;
 ```
 
-Defined in: [Behaviour.ts:337](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L337)
+Defined in: [Behaviour.ts:356](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L356)
 
 Returns the entity's component of the given class, or `null` if it has
 no such component.
@@ -441,7 +393,7 @@ if (mesh) console.log(mesh.geometryRef);
 getEntity(): WorldEntityView | null;
 ```
 
-Defined in: [Behaviour.ts:347](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L347)
+Defined in: [Behaviour.ts:366](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L366)
 
 Returns the latest [WorldEntityView](../../types/type-aliases/WorldEntityView.md) snapshot for this entity, or
 `null` if it was destroyed.
@@ -458,7 +410,7 @@ Returns the latest [WorldEntityView](../../types/type-aliases/WorldEntityView.md
 getParent(): ParentLookup;
 ```
 
-Defined in: [Behaviour.ts:357](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L357)
+Defined in: [Behaviour.ts:376](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L376)
 
 Resolves the entity's parent from the [ParentId](../../components/classes/ParentId.md) component, if any.
 
@@ -477,7 +429,7 @@ A [ParentLookup](../../types/type-aliases/ParentLookup.md) with the parent compo
 getChildren(): WorldEntityView[];
 ```
 
-Defined in: [Behaviour.ts:378](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L378)
+Defined in: [Behaviour.ts:397](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L397)
 
 Returns every direct child entity of this one (entities whose
 [ParentId](../../components/classes/ParentId.md) matches `entityId`).
@@ -494,7 +446,7 @@ Returns every direct child entity of this one (entities whose
 protected init(): void;
 ```
 
-Defined in: [Behaviour.ts:393](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L393)
+Defined in: [Behaviour.ts:412](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L412)
 
 Called once before the first [Behaviour.onUpdate](#onupdate). Override to
 default and validate [Behaviour.data](#data), cache references, or set
@@ -512,7 +464,7 @@ initial state. Runs at preview/runtime only — never in the editor.
 protected onUpdate(): void;
 ```
 
-Defined in: [Behaviour.ts:402](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L402)
+Defined in: [Behaviour.ts:421](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L421)
 
 Called every frame while the script is enabled. Override with the
 script's main per-frame logic. Runs at preview/runtime only — never in the
@@ -530,7 +482,7 @@ editor (use [ScriptObject](../../index/classes/ScriptObject.md) for editor-visib
 onSelect(): void;
 ```
 
-Defined in: [Behaviour.ts:407](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L407)
+Defined in: [Behaviour.ts:426](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L426)
 
 Called when the editor selects this entity. Optional UX hook.
 
@@ -546,7 +498,7 @@ Called when the editor selects this entity. Optional UX hook.
 onDeselect(): void;
 ```
 
-Defined in: [Behaviour.ts:412](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L412)
+Defined in: [Behaviour.ts:431](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L431)
 
 Called when the editor deselects this entity. Optional UX hook.
 
@@ -562,7 +514,7 @@ Called when the editor deselects this entity. Optional UX hook.
 onTargetFound(target): void;
 ```
 
-Defined in: [Behaviour.ts:422](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L422)
+Defined in: [Behaviour.ts:441](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L441)
 
 Called when an image-tracking target this entity depends on becomes
 visible. Optional AR hook.
@@ -585,7 +537,7 @@ visible. Optional AR hook.
 onTargetLost(target): void;
 ```
 
-Defined in: [Behaviour.ts:432](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L432)
+Defined in: [Behaviour.ts:451](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L451)
 
 Called when an image-tracking target this entity depends on is lost.
 Optional AR hook.
@@ -599,3 +551,338 @@ Optional AR hook.
 #### Returns
 
 `void`
+
+***
+
+### onXRSessionStart()
+
+```ts
+onXRSessionStart(capabilities): void;
+```
+
+Defined in: [Behaviour.ts:470](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L470)
+
+Called once when an immersive session starts. Optional XR hook.
+
+Use it to set up XR-only state. Inspect `capabilities` rather than guessing
+by device: feature support differs sharply per headset (for example Vision
+Pro grants no passthrough on the web today).
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `capabilities` | [`XrCapabilities`](../../index/type-aliases/XrCapabilities.md) | What the session actually granted, read from `XRSession.enabledFeatures`. |
+
+#### Returns
+
+`void`
+
+***
+
+### onXRSessionEnd()
+
+```ts
+onXRSessionEnd(): void;
+```
+
+Defined in: [Behaviour.ts:475](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L475)
+
+Called once when the immersive session ends. Optional XR hook.
+
+#### Returns
+
+`void`
+
+***
+
+### onSelectStart()
+
+```ts
+onSelectStart(input): void;
+```
+
+Defined in: [Behaviour.ts:485](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L485)
+
+Called when a primary action begins — controller trigger, hand pinch, or
+Vision Pro gaze-pinch. Optional XR hook.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `input` | [`XrInputState`](../../index/type-aliases/XrInputState.md) | Normalized state for the source that acted. |
+
+#### Returns
+
+`void`
+
+***
+
+### onSelectEnd()
+
+```ts
+onSelectEnd(input): void;
+```
+
+Defined in: [Behaviour.ts:490](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L490)
+
+Called when the primary action ends. Optional XR hook.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `input` | [`XrInputState`](../../index/type-aliases/XrInputState.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onSecondaryGrab()
+
+```ts
+onSecondaryGrab(_input): void;
+```
+
+Defined in: [Behaviour.ts:508](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L508)
+
+A SECOND hand joined a two-hand grab on this entity.
+
+The first hand anchors the object and keeps holding it; this fires for the
+hand that came second — the foregrip on a rifle, say.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_input` | [`XrInputState`](../../index/type-aliases/XrInputState.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onSecondaryRelease()
+
+```ts
+onSecondaryRelease(_input): void;
+```
+
+Defined in: [Behaviour.ts:513](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L513)
+
+The second hand let go, leaving the object in the first hand alone.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_input` | [`XrInputState`](../../index/type-aliases/XrInputState.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onHandPoseStart()
+
+```ts
+onHandPoseStart(_event): void;
+```
+
+Defined in: [Behaviour.ts:523](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L523)
+
+A hand pose declared on this entity started being held.
+
+Fires once the pose has been sustained for its hold time, not the instant
+the fingers pass through it.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_event` | [`XrHandPoseEventDetail`](../../index/type-aliases/XrHandPoseEventDetail.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onHandPoseEnd()
+
+```ts
+onHandPoseEnd(_event): void;
+```
+
+Defined in: [Behaviour.ts:528](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L528)
+
+A held hand pose ended, or its hand stopped being tracked.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_event` | [`XrHandPoseEventDetail`](../../index/type-aliases/XrHandPoseEventDetail.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onGrab()
+
+```ts
+onGrab(input): void;
+```
+
+Defined in: [Behaviour.ts:532](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L532)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `input` | [`XrInputState`](../../index/type-aliases/XrInputState.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onRelease()
+
+```ts
+onRelease(input): void;
+```
+
+Defined in: [Behaviour.ts:537](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L537)
+
+Called when this entity is released. Optional XR hook.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `input` | [`XrInputState`](../../index/type-aliases/XrInputState.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onUiPress()
+
+```ts
+onUiPress(_event): void;
+```
+
+Defined in: [Behaviour.ts:543](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L543)
+
+A UI button on this entity (or a descendant) was clicked. Clicks fire on
+RELEASE while still pointing at the widget — sliding off cancels.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_event` | [`UiInteractionEvent`](../type-aliases/UiInteractionEvent.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onUiHoverStart()
+
+```ts
+onUiHoverStart(_event): void;
+```
+
+Defined in: [Behaviour.ts:548](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L548)
+
+A pointer began hovering a UI widget on this entity (or a descendant).
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_event` | [`UiInteractionEvent`](../type-aliases/UiInteractionEvent.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onUiHoverEnd()
+
+```ts
+onUiHoverEnd(_event): void;
+```
+
+Defined in: [Behaviour.ts:553](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L553)
+
+The pointer left the widget.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_event` | [`UiInteractionEvent`](../type-aliases/UiInteractionEvent.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onUiToggle()
+
+```ts
+onUiToggle(_event): void;
+```
+
+Defined in: [Behaviour.ts:558](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L558)
+
+A UI toggle flipped; `event.value` is the new boolean.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_event` | [`UiInteractionEvent`](../type-aliases/UiInteractionEvent.md) |
+
+#### Returns
+
+`void`
+
+***
+
+### onUiChange()
+
+```ts
+onUiChange(_event): void;
+```
+
+Defined in: [Behaviour.ts:564](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L564)
+
+A UI slider moved; `event.value` is the new number. Fires on real value
+changes during the drag and once more on release.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_event` | [`UiInteractionEvent`](../type-aliases/UiInteractionEvent.md) |
+
+#### Returns
+
+`void`

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

@@ -8,8 +8,12 @@
 
 ## Classes
 
-### Scripting
-
 | Class | Description |
 | ------ | ------ |
-| [Behaviour](classes/Behaviour.md) | Base class for all user-authored scripts attached to an entity through a `ScriptComponent`. Subclass `Behaviour` to drive per-frame logic on a single entity with full access to the [World](../index/classes/World.md), the entity's [TransformComponent](../components/classes/TransformComponent.md), and its three.js [Object3DRef](../components/classes/Object3DRef.md). |
+| [Behaviour](classes/Behaviour.md) | - |
+
+## Type Aliases
+
+| Type Alias | Description |
+| ------ | ------ |
+| [UiInteractionEvent](type-aliases/UiInteractionEvent.md) | Payload for spatial-UI hooks. |

package/dist/docs/api/Behaviour/type-aliases/UiInteractionEvent.md

@@ -0,0 +1,35 @@
+[**@relu-interactives/spatial-ecs**](../../index.md)
+
+***
+
+[@relu-interactives/spatial-ecs](../../index.md) / [Behaviour](../index.md) / UiInteractionEvent
+
+# Type Alias: UiInteractionEvent
+
+```ts
+type UiInteractionEvent = {
+  targetEntityId: number;
+  actionId: string;
+  input: XrInputState | null;
+  value?: boolean | number;
+};
+```
+
+Defined in: [Behaviour.ts:75](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L75)
+
+Payload for spatial-UI hooks.
+
+`targetEntityId` is the WIDGET that was interacted with — hooks bubble up
+the parent chain, so a panel script receives its children's events and can
+switch on `actionId` (the widget's authored id, defaulting to its entity
+name). `input` is null when the event came from the mouse in a flat
+preview rather than an XR pointer.
+
+## Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="targetentityid"></a> `targetEntityId` | `number` | - | [Behaviour.ts:76](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L76) |
+| <a id="actionid"></a> `actionId` | `string` | - | [Behaviour.ts:77](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L77) |
+| <a id="input"></a> `input` | [`XrInputState`](../../index/type-aliases/XrInputState.md) \| `null` | - | [Behaviour.ts:78](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L78) |
+| <a id="value"></a> `value?` | `boolean` \| `number` | Toggle: the new boolean. Slider: the new number. Absent for presses. | [Behaviour.ts:80](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/72f129a02ec4b2f93ff337d16361a731efd8cc5d/core/Behaviour.ts#L80) |