@relu-interactives/spatial-ecs 0.3.0 → 0.3.2

package/dist/factories/index.d.cts

@@ -1,5 +1,5 @@
-import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, X as ScriptObjectComponentInput, W as ScriptObjectComponent, Z as Selectable, _ as SelectionTransformState, $ as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a3 as VideoComponent } from '../Video-AIQYTAAr.cjs';
-import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-CYWZ_Zx5.cjs';
+import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, X as ScriptObjectComponentInput, W as ScriptObjectComponent, Z as Selectable, _ as SelectionTransformState, $ as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a5 as VideoComponent, a9 as XRRigComponent, a3 as VRTeleportAreaComponent, a7 as XRInteractableComponent } from '../XRRig-Cu-EyliG.cjs';
+import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-vrU46Vuw.cjs';
 import * as THREE from 'three';
 import '@dimforge/rapier3d-compat';
 
@@ -74,8 +74,14 @@ declare function createInstanceSlotComponent(world: World, entityId: number, gro
 
 declare function createVideoComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof VideoComponent>): VideoComponent;
 
+declare function createXRRigComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRRigComponent>): XRRigComponent;
+
+declare function createVRTeleportAreaComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof VRTeleportAreaComponent>): VRTeleportAreaComponent;
+
+declare function createXRInteractableComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRInteractableComponent>): XRInteractableComponent;
+
 declare function registerDefaultComponentFactories(objectManagementSystem: ObjectManagementSystem): void;
 
 declare function registerDefaultFactories(objectManagementSystem: ObjectManagementSystem): void;
 
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories };
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRInteractableComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories };

package/dist/factories/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, X as ScriptObjectComponentInput, W as ScriptObjectComponent, Z as Selectable, _ as SelectionTransformState, $ as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a3 as VideoComponent } from '../Video-DlZ4G9ig.js';
-import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-CYWZ_Zx5.js';
+import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, X as ScriptObjectComponentInput, W as ScriptObjectComponent, Z as Selectable, _ as SelectionTransformState, $ as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a5 as VideoComponent, a9 as XRRigComponent, a3 as VRTeleportAreaComponent, a7 as XRInteractableComponent } from '../XRRig-CAmf04NX.js';
+import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-vrU46Vuw.js';
 import * as THREE from 'three';
 import '@dimforge/rapier3d-compat';
 
@@ -74,8 +74,14 @@ declare function createInstanceSlotComponent(world: World, entityId: number, gro
 
 declare function createVideoComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof VideoComponent>): VideoComponent;
 
+declare function createXRRigComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRRigComponent>): XRRigComponent;
+
+declare function createVRTeleportAreaComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof VRTeleportAreaComponent>): VRTeleportAreaComponent;
+
+declare function createXRInteractableComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRInteractableComponent>): XRInteractableComponent;
+
 declare function registerDefaultComponentFactories(objectManagementSystem: ObjectManagementSystem): void;
 
 declare function registerDefaultFactories(objectManagementSystem: ObjectManagementSystem): void;
 
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories };
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRInteractableComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories };

package/dist/factories/index.js

@@ -1,6 +1,6 @@
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from '../chunk-AT5SPSPM.js';
-import '../chunk-PZ4CAALA.js';
-import '../chunk-7BPHZWQ6.js';
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRInteractableComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from '../chunk-JWTRFJBL.js';
+import '../chunk-67WGASUJ.js';
+import '../chunk-U3MDYKPV.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index-Bc0YCz1A.d.cts

@@ -0,0 +1,514 @@
+import { k as EcsSystem, l as World } from './System-vrU46Vuw.cjs';
+import * as THREE from 'three';
+
+declare class AnimationSystem implements EcsSystem {
+    private readonly runtimeByEntity;
+    private readonly gltfLoader;
+    private readonly fbxLoader;
+    private loadClipsFromSource;
+    private refreshExternalClipSources;
+    private release;
+    update(world: World, deltaTime: number): void;
+    dispose(): void;
+}
+
+declare class CameraSyncSystem implements EcsSystem {
+    private readonly signatures;
+    update(world: World): void;
+}
+
+declare class ObjectVisibilitySystem implements EcsSystem {
+    update(world: World): void;
+}
+
+declare class EnvironmentSyncSystem implements EcsSystem {
+    private readonly scene;
+    private readonly textureLoader;
+    private signature;
+    private activeTexture;
+    private pendingImageUrl;
+    constructor(scene: THREE.Scene);
+    private disposeActiveTexture;
+    private applySkybox;
+    private applyFog;
+    update(world: World): void;
+    dispose(): void;
+}
+
+declare class PostprocessingSyncSystem implements EcsSystem {
+    private readonly renderer;
+    private readonly scene;
+    private readonly camera;
+    private signature;
+    private composer;
+    private composerEnabled;
+    constructor(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.PerspectiveCamera);
+    private setComposerEnabled;
+    private disposeComposer;
+    private buildComposer;
+    update(world: World): void;
+    dispose(): void;
+}
+
+declare class PhysicsSyncSystem implements EcsSystem {
+    private readonly rigidBodyHandles;
+    private readonly colliderHandles;
+    private readonly rigidBodySignatures;
+    private readonly colliderSignatures;
+    private readonly isEditorMode;
+    private rapier;
+    private isBootstrappingWorld;
+    private accumulator;
+    constructor(options?: {
+        isEditor?: boolean;
+    });
+    private ensurePhysicsWorld;
+    private removeEntityPhysics;
+    update(world: World, deltaTime: number): void;
+    dispose(world: World): void;
+}
+
+declare class LightSyncSystem implements EcsSystem {
+    private readonly signatures;
+    update(world: World): void;
+}
+
+declare class MaterialSyncSystem implements EcsSystem {
+    private readonly signatures;
+    private readonly textureCache;
+    update(world: World): void;
+    dispose(): void;
+}
+
+declare class MeshGeometrySystem implements EcsSystem {
+    private readonly geometrySignatures;
+    private readonly shadowSignatures;
+    update(world: World): void;
+}
+
+/**
+ * Maintains the runtime geometry for entities with an {@link InstancedMeshComponent}.
+ *
+ * - **Primitive kinds** (`cube`, `sphere`, `plane`, `cylinder`, `capsule`): creates a single
+ *   `THREE.InstancedMesh` on the anchor and writes per-instance matrices every frame.
+ * - **Model kind** (`model`): asynchronously loads the GLTF/GLB at `comp.modelPath`, traverses
+ *   the scene to collect all `THREE.Mesh` nodes, and creates one `THREE.InstancedMesh` per mesh
+ *   (preserving the mesh's local transform and original materials). All sub-meshes are grouped
+ *   under a `THREE.Group` stored in `comp.instancedMesh`. Per-instance matrices are composed as
+ *   `instanceTransform × meshLocalMatrix` every frame.
+ *
+ * Geometry is rebuilt whenever the signature (`meshKind:parameters:instanceCount` for primitives,
+ * `model:path:instanceCount` for model kind) changes.
+ */
+declare class InstancedMeshSystem implements EcsSystem {
+    /** Signature tracking for geometry + instance count changes. */
+    private readonly geometrySignatures;
+    /** Signature being loaded per entity. Maps entityId → geometrySignature in-flight.
+     * Prevents re-dispatching a load every frame while comp.instancedMesh is still null. */
+    private readonly loadingSignatures;
+    /** Per-mesh data for model kind, populated after GLTF load. */
+    private readonly modelMeshEntries;
+    /**
+     * System-internal ref to the Three.js mesh/group most recently placed on
+     * the anchor by this system. Used for cleanup on rebuild instead of
+     * `comp.instancedMesh`, which can be stale (pointing to a disposed mesh)
+     * after an undo/redo restores a history snapshot captured at an earlier
+     * geometry configuration. Relying on the stale comp ref would skip removal
+     * of the current live mesh → ghost mesh in the scene.
+     */
+    private readonly trackedMeshes;
+    update(world: World): void;
+}
+
+/**
+ * Shared infrastructure for the script-hosting systems (`ScriptBehaviourSystem`
+ * and `ScriptObjectSystem`): module loading, class resolution, data-envelope
+ * merge/resolve/serialize. Extracted verbatim from `ScriptBehaviourSystem` so
+ * both systems stay behaviourally identical for the parts they share.
+ */
+/** Resolves a script URL to its ES module namespace. */
+type ModuleLoader = (scriptUrl: string) => Promise<Record<string, unknown>>;
+
+/**
+ * Optional context that enables raycast-based onSelect / onDeselect dispatch.
+ * When provided, pointer/touch taps on the canvas fire a raycast against the
+ * scene. If the hit object (or any ancestor) carries userData.entityId, every
+ * Behaviour instance for that entity receives onSelect(); the previously
+ * selected entity's instances receive onDeselect().
+ */
+type SelectionContext = {
+    camera: THREE.Camera;
+    scene: THREE.Scene;
+    domElement: HTMLElement;
+};
+declare class ScriptBehaviourSystem implements EcsSystem {
+    private instances;
+    private loading;
+    private readonly moduleLoader;
+    private readonly selectionCtx;
+    private readonly raycaster;
+    private readonly ndcPointer;
+    private selectedEntityId;
+    private pendingEntityId;
+    private pointerDownPos;
+    private static readonly CLICK_THRESHOLD;
+    constructor(moduleLoader?: ModuleLoader, selectionContext?: SelectionContext);
+    /** Walk up the object hierarchy to find the nearest userData.entityId. */
+    private resolveEntityId;
+    /** Convert client (screen) coordinates to normalised device coordinates. */
+    private toNdc;
+    /** Fire raycast and queue the result to be dispatched in the next update(). */
+    private queueRaycast;
+    private onPointerDown;
+    private onPointerUp;
+    /**
+     * Apply a queued selection change.
+     * Calls onDeselect() on all behaviours of the previous entity and
+     * onSelect() on all behaviours of the newly selected entity.
+     */
+    private applySelection;
+    update(world: World, deltaTime: number): void;
+    dispose(world: World): void;
+    private loadBehaviour;
+}
+
+/** Tags the Object3D a script's `build()` returned, so reloads can find/remove it. */
+declare const SCRIPT_OBJECT_ROOT_FLAG = "__scriptObjectRoot";
+/**
+ * Builds, ticks, and disposes {@link ScriptObject} scripts. Unlike
+ * `ScriptBehaviourSystem`, this runs in the editor AND at runtime — there is NO
+ * `isEditorMode` gating anywhere here. A script's `build()` output is attached
+ * under the entity's `Object3DRef.object` (so it inherits transform, selection
+ * and visibility). `runtimeState` is written on transitions only (never every
+ * frame).
+ *
+ * Construct it and pass it to `World.setup({ systems })`.
+ *
+ * @category Systems
+ */
+declare class ScriptObjectSystem implements EcsSystem {
+    private readonly moduleLoader;
+    private instances;
+    private loading;
+    /** Bumped by invalidate*() so in-flight loads that predate it are discarded. */
+    private epoch;
+    constructor(moduleLoader?: ModuleLoader);
+    update(world: World, deltaTime: number): void;
+    private loadScriptObject;
+    /** Dispose a record's instance + built subtree. `keepTombstone` leaves an error marker. */
+    private teardownRecord;
+    private markError;
+    /** Dispose all live instances so the next update() reloads with fresh modules. */
+    invalidateAll(): void;
+    /** Invalidate only the entities whose script matches `scriptUrl`. */
+    invalidate(scriptUrl: string): void;
+    dispose(world: World): void;
+}
+
+/**
+ * Reconciles `AudioComponent` state with the underlying THREE.js audio objects
+ * each frame.
+ *
+ * **Playback** — drives `play()`, `pause()`, and `stop()` on the THREE.js
+ * audio node based on the `isPlaying` / `isPaused` flags set by
+ * `AudioComponent.play()`, `.pause()`, and `.stop()`.
+ *
+ * **Option sync** — detects changes to `loop`, `pitch`, `volume`,
+ * `refDistance`, `distanceModel`, and `rolloffFactor` and applies them live.
+ * Changes take effect on the next frame, so scripts and inspector edits during
+ * runtime are reflected without reloading the scene.
+ *
+ * Only active in **preview** mode (`isEditor: true` makes every update a
+ * no-op so the editor is unaffected).
+ *
+ * @category Systems
+ */
+declare class AudioSystem implements EcsSystem {
+    private readonly isEditor;
+    /** THREE.js `isPlaying` state captured at the end of the previous frame. */
+    private readonly prevPlayingState;
+    /** Snapshot of options applied in the previous frame, for change detection. */
+    private readonly prevOptions;
+    /** Tracks entities that were stopped due to invisibility. */
+    private readonly stoppedDueToInvisibility;
+    constructor({ isEditor }?: {
+        isEditor?: boolean;
+    });
+    update(world: World, _deltaTime: number): void;
+    /** Apply any changed options from the component to the THREE.js audio node. */
+    private _syncOptions;
+    dispose(_world: World): void;
+}
+
+/**
+ * Reconciles `VideoComponent` state with the underlying HTML video element
+ * and THREE.js mesh/material each frame.
+ *
+ * **Playback** — drives `play()`, `pause()`, and stop (pause + seek to 0) on
+ * the HTML `<video>` element based on the `isPlaying` / `isPaused` flags set
+ * by `VideoComponent.play()`, `.pause()`, and `.stop()`.
+ *
+ * **Option sync** — detects changes to `loop`, `volume`, `width`, `height`,
+ * and green-screen shader uniforms (`backgroundColor`, `similarity`,
+ * `smoothness`, `spill`) and applies them live without a scene reload.
+ *
+ * Only active in **preview** mode (`isEditor: true` makes every update a
+ * no-op so the editor is unaffected).
+ *
+ * @category Systems
+ */
+declare class VideoSystem implements EcsSystem {
+    private readonly isEditor;
+    /** Playback intent captured at the end of the previous frame. */
+    private readonly prevIntent;
+    /** Snapshot of options applied in the previous frame, for change detection. */
+    private readonly prevOptions;
+    /** Tracks entities that were manually paused due to invisibility. */
+    private readonly pausedDueToInvisibility;
+    constructor({ isEditor }?: {
+        isEditor?: boolean;
+    });
+    update(world: World, _deltaTime: number): void;
+    /** Apply any changed options from the component to the video element and mesh. */
+    private _syncOptions;
+    dispose(_world: World): void;
+}
+
+/**
+ * Shared vocabulary for the WebXR layer.
+ *
+ * The single most important design constraint here: **the three target
+ * platforms expose fundamentally different input models**, and a runtime that
+ * hard-codes one of them silently excludes the others.
+ *
+ * - Meta Quest / Pico  → motion controllers (trigger, grip, thumbstick) and,
+ *   optionally, tracked hands.
+ * - Android XR         → tracked hands are the PRIMARY input.
+ * - Apple Vision Pro   → no controllers at all. Input arrives as
+ *   `transient-pointer` sources that exist ONLY for the duration of a
+ *   gaze-and-pinch, appearing on pinch-start and disappearing on release.
+ *
+ * {@link XrInputState} normalizes all three into one shape so gameplay code and
+ * Behaviours are written once. Anything platform-specific is expressed as a
+ * capability (`kind`, `hasAxes`) rather than a branch on device name — we never
+ * sniff the user agent, per the WebXR guidance from every vendor.
+ */
+/** Which hand an input source belongs to (`none` for gaze / single-source devices). */
+type XrHandedness = "left" | "right" | "none";
+/**
+ * How an input source is physically driven.
+ *
+ * `transient-pointer` is the Vision Pro case: the source is EPHEMERAL — it is
+ * created when the user pinches and destroyed when they release, so it must
+ * never be cached across frames by identity.
+ */
+type XrInputKind = "controller" | "hand" | "transient-pointer" | "gaze";
+/**
+ * One frame of normalized input for a single source.
+ *
+ * Boolean actions follow the same pending→latched contract as the desktop
+ * `InputSystem`: `select` is the held state, while `selectStart` / `selectEnd`
+ * are true for exactly one frame. This lets Behaviours poll (`if (select)`) or
+ * edge-detect (`if (selectStart)`) without subscribing to events.
+ */
+type XrInputState = {
+    handedness: XrHandedness;
+    kind: XrInputKind;
+    /** False once the source disconnects (a released pinch on Vision Pro). */
+    connected: boolean;
+    /** Pointing ray in WORLD space, from the source's `targetRaySpace`. */
+    rayOrigin: THREE.Vector3;
+    rayDirection: THREE.Vector3;
+    /** Physical grip pose. Null for gaze and transient-pointer, which have no grip. */
+    gripPosition: THREE.Vector3 | null;
+    gripQuaternion: THREE.Quaternion | null;
+    /** Primary action: controller trigger, hand pinch, or Vision Pro gaze-pinch. */
+    select: boolean;
+    selectStart: boolean;
+    selectEnd: boolean;
+    /** Secondary action: controller grip squeeze. Never fires for hands/gaze. */
+    squeeze: boolean;
+    squeezeStart: boolean;
+    squeezeEnd: boolean;
+    /** Thumbstick / trackpad axes in [-1, 1]. Empty when {@link hasAxes} is false. */
+    axes: number[];
+    /** True only for sources with a physical stick — gates stick-driven locomotion. */
+    hasAxes: boolean;
+    /** Raw gamepad button pressed-states, when the source exposes a gamepad. */
+    buttons: boolean[];
+};
+/**
+ * What the ACTIVE session actually granted us.
+ *
+ * Always derived from `XRSession.enabledFeatures` — never from the device name.
+ * A feature being requested is not a promise it was granted, and support varies
+ * sharply per platform (e.g. Vision Pro grants no `immersive-ar` at all today).
+ */
+type XrCapabilities = {
+    /** The session's mode. `immersive-ar` implies passthrough / mixed reality. */
+    mode: "immersive-vr" | "immersive-ar" | "inline";
+    /** Tracked-hand joint data is available. */
+    handTracking: boolean;
+    /** Real-world plane detection (incubating; effectively Quest-only today). */
+    planeDetection: boolean;
+    /** Real-world mesh detection (draft spec; Quest-only today). */
+    meshDetection: boolean;
+    /** Per-frame depth buffer (Android XR stereo, Quest experimental). */
+    depthSensing: boolean;
+    /** Spatial anchors. */
+    anchors: boolean;
+    /** Ray-against-real-world hit testing. */
+    hitTest: boolean;
+    /** Everything the UA reported, verbatim, for diagnostics. */
+    enabledFeatures: string[];
+};
+/** Capabilities for "no session running" — every feature off. */
+declare const NO_XR_CAPABILITIES: XrCapabilities;
+/**
+ * Read granted features off a live session.
+ *
+ * `enabledFeatures` is optional in the spec and missing on some UAs; when it is
+ * absent we report nothing as granted rather than optimistically assuming
+ * support, so callers degrade instead of calling an API that will throw.
+ */
+declare function readXrCapabilities(session: XRSession | null, mode?: XrCapabilities["mode"]): XrCapabilities;
+
+declare class XRInputSystem implements EcsSystem {
+    private readonly records;
+    private session;
+    private readonly onSelectStart;
+    private readonly onSelectEnd;
+    private readonly onSqueezeStart;
+    private readonly onSqueezeEnd;
+    private mark;
+    private ensureRecord;
+    /** Bind to a session. Called by {@link XRSessionSystem} on session start. */
+    attachSession(session: XRSession): void;
+    /** Unbind and drop all per-source state. */
+    detachSession(): void;
+    update(world: World): void;
+    /** Every input source active this frame. */
+    getInputs(): XrInputState[];
+    /** The first source for a hand, or null. Prefer this for hand-specific logic. */
+    getInput(handedness: XrHandedness): XrInputState | null;
+    /** True while ANY source is selecting — the portable "is the user acting" check. */
+    isSelecting(): boolean;
+    dispose(): void;
+}
+
+declare class XRInteractionSystem implements EcsSystem {
+    private readonly inputSystem;
+    private readonly raycaster;
+    /** Which entity each source is holding. Keyed by source state identity. */
+    private readonly grabs;
+    private hoveredEntityId;
+    constructor(inputSystem: XRInputSystem);
+    update(world: World): void;
+    private collectInteractables;
+    /** Entity id of the nearest pointable hit along this source's ray, or null. */
+    private raycast;
+    private grab;
+    private moveHeld;
+    private release;
+    private releaseAll;
+    /**
+     * Where the "hand" is for this source. Controllers and tracked hands report a
+     * grip pose; gaze and transient-pointer sources have none, so we hold the
+     * object a fixed distance along the ray instead.
+     */
+    private handPosition;
+    private dispatch;
+    /** Entity currently under a pointer this frame, or null. */
+    getHoveredEntityId(): number | null;
+    /** True when any source is holding something. */
+    isGrabbing(): boolean;
+}
+
+declare class XRLocomotionSystem implements EcsSystem {
+    private readonly inputSystem;
+    private readonly raycaster;
+    /** Per-source latch so one stick push yields exactly one snap turn. */
+    private readonly turnLatched;
+    /** Where the pointer currently lands, for the consumer to draw a marker. */
+    private teleportPoint;
+    constructor(inputSystem: XRInputSystem);
+    update(world: World, deltaTime: number): void;
+    /**
+     * Snap turning, not smooth turning — rotating the view continuously is the
+     * single biggest cause of VR nausea, so the comfort-safe option is the one
+     * wired to the stick.
+     */
+    private applySnapTurn;
+    private applySmoothMove;
+    private applyTeleport;
+    private collectTeleportTargets;
+    /**
+     * Where the teleport pointer currently lands this frame, or null.
+     * Consumers use this to render an aim marker.
+     */
+    getTeleportPoint(): THREE.Vector3 | null;
+}
+
+/**
+ * Owns the immersive-session lifecycle and fans XR events out to Behaviours.
+ *
+ * Detects session start/end by polling `renderer.xr.isPresenting` rather than
+ * binding to `sessionstart`/`sessionend`: the session may already be running
+ * before this system is registered (the consumer owns the entry button), and
+ * polling a boolean makes the system correct regardless of construction order.
+ *
+ * Hook dispatch mirrors `ImageTargetAnchorSystem`'s AR precedent — walk live
+ * `ScriptComponent.scriptInstances` and call the public no-op hook — so XR and
+ * AR extend `Behaviour` the same way.
+ */
+declare class XRSessionSystem implements EcsSystem {
+    private presenting;
+    private capabilities;
+    private readonly inputSystem;
+    constructor(inputSystem?: XRInputSystem);
+    update(world: World): void;
+    private handleSessionStart;
+    private handleSessionEnd;
+    /**
+     * Relay this frame's one-frame select edges. Polling the latched state (rather
+     * than dispatching from the DOM event) keeps hook delivery on the ECS tick, so
+     * a Behaviour's `onSelectStart` always observes the same world state its
+     * `onUpdate` would.
+     */
+    private dispatchInputEdges;
+    private forEachBehaviour;
+    /** What the active session granted. `NO_XR_CAPABILITIES` when not presenting. */
+    getCapabilities(): XrCapabilities;
+    /** True while an immersive session is presenting. */
+    isPresenting(): boolean;
+    /** Convenience passthrough so consumers need only hold this system. */
+    getInputs(): XrInputState[];
+}
+
+declare class VRTeleportAreaSystem implements EcsSystem {
+    private readonly signatures;
+    update(world: World): void;
+}
+
+declare class XRControllerVisualSystem implements EcsSystem {
+    private readonly controllerModelFactory;
+    private readonly handModelFactory;
+    private readonly group;
+    private built;
+    private attachedTo;
+    /** Index → whether we've already attached visuals for that slot. */
+    private readonly ready;
+    /** How many controller slots to wire. Two covers every current headset. */
+    private readonly slots;
+    constructor(slots?: number);
+    update(world: World): void;
+    /**
+     * Parent the visuals to the XR rig when there is one, so locomotion moves the
+     * hands with the player. Falls back to the scene root.
+     */
+    private ensureAttached;
+    private createRay;
+    dispose(): void;
+}
+
+export { AnimationSystem as A, CameraSyncSystem as C, EnvironmentSyncSystem as E, InstancedMeshSystem as I, LightSyncSystem as L, MaterialSyncSystem as M, NO_XR_CAPABILITIES as N, ObjectVisibilitySystem as O, PhysicsSyncSystem as P, SCRIPT_OBJECT_ROOT_FLAG as S, VRTeleportAreaSystem as V, type XrCapabilities as X, type XrInputState as a, AudioSystem as b, MeshGeometrySystem as c, type ModuleLoader as d, PostprocessingSyncSystem as e, ScriptBehaviourSystem as f, ScriptObjectSystem as g, type SelectionContext as h, VideoSystem as i, XRControllerVisualSystem as j, XRInputSystem as k, XRInteractionSystem as l, XRLocomotionSystem as m, XRSessionSystem as n, type XrHandedness as o, type XrInputKind as p, readXrCapabilities as r };