@relu-interactives/spatial-ecs 0.4.4 → 0.5.0

package/dist/{index-7YCk4cmQ.d.cts → index-I2IsocYW.d.cts}

@@ -1,4 +1,4 @@
-import { k as EcsSystem, l as World, r as EntityId } from './System-ln4Q7Eot.cjs';
+import { k as EcsSystem, l as World, I as InputSystem, r as EntityId } from './System-V_mv07le.cjs';
 import * as THREE from 'three';
 import { m as XrHandJoints, r as XrHandShape } from './handPose-DlcTtqgx.cjs';
 
@@ -426,6 +426,7 @@ declare class XRInteractionSystem implements EcsSystem {
     private readonly grabs;
     private hoveredEntityId;
     /** Per-hand hover, with the hit distance so the ray can stop at the surface. */
+    private readonly busyContributors;
     private readonly hovers;
     /** Monotonic seconds, accumulated from deltaTime for velocity sampling. */
     private elapsed;
@@ -529,6 +530,14 @@ declare class XRInteractionSystem implements EcsSystem {
      * grabbed and teleported.
      */
     isSourceBusy(world: World, input: XrInputState): boolean;
+    /** OR-ed into isSourceBusy; see the comment there. */
+    registerBusyContributor(contributor: (world: World, input: XrInputState) => boolean): void;
+    /** Hover for a specific input source (handedness-free — Vision Pro's
+     * transient pointers all report handedness "none"). */
+    getHoverForInput(input: XrInputState): {
+        entityId: number;
+        distance: number;
+    } | null;
     /** True when THIS hand is holding something. */
     isGrabbingWith(handedness: XrInputState["handedness"]): boolean;
     /**
@@ -651,6 +660,25 @@ declare class XRSessionSystem implements EcsSystem {
     private session;
     constructor(inputSystem?: XRInputSystem);
     update(world: World): void;
+    /**
+     * Stop three's depth-occlusion pass from writing COLOR.
+     *
+     * With depth sensing granted, three draws a full-screen, head-locked mesh
+     * every frame whose fragment shader assigns ONLY `gl_FragDepth` — that is
+     * the whole occlusion mechanism — but its material never sets
+     * `colorWrite: false`, so the colour output is UNDEFINED per GLSL. Desktop
+     * drivers happen to zero it, which is why this ships unnoticed; Quest's
+     * mobile GPU frequently leaves the last-computed temporary in the register —
+     * the sampled DEPTH value — so the pass paints the depth camera's view over
+     * the screen as faint head-locked contour bands. On device that reads as "a
+     * large wireframe dome that follows my head".
+     *
+     * The mesh is created lazily inside three's render, so this is re-checked
+     * every frame rather than hooked once; the write is idempotent and the
+     * check is two property reads. Depth-only is the mesh's entire purpose —
+     * occlusion is unaffected.
+     */
+    private muteDepthOcclusionColor;
     private handleSessionStart;
     /**
      * Apply the rig's authored tracking origin, and compensate when the device
@@ -690,12 +718,26 @@ declare class XREnvironmentSystem implements EcsSystem {
     /** Keyed by the XRPlane/XRMesh object itself — the runtime's own identity. */
     private readonly planes;
     private readonly meshes;
+    /**
+     * Surfaces observed but not yet SPAWNED — their gate is still proving the
+     * pose is world-anchored. Creating from an unflagged head-glued pose (seen
+     * on-device after a suspend/resume regenerated the scan identities) plants
+     * a rotated ghost copy of the room wherever the head happens to be, which
+     * the apply-gate then freezes there — wrong forever. So admission itself
+     * is gated: a few frames of world-anchored behavior first.
+     */
+    private readonly pendingPlanes;
+    private readonly pendingMeshes;
     private presenting;
     private debugVisible;
     /** Seconds presenting, used to decide the room has genuinely nothing in it. */
     private elapsed;
     /** `initiateRoomCapture` may be called only ONCE per session. */
     private roomCaptureRequested;
+    /** This frame's inverse viewer matrix, or null when unavailable. */
+    private viewerInverse;
+    private readonly tmpViewerMatrix;
+    private readonly tmpViewPos;
     update(world: World, deltaTime?: number): void;
     /**
      * Ask the runtime to scan the room when it turns out we have no room.
@@ -718,9 +760,47 @@ declare class XREnvironmentSystem implements EcsSystem {
         planes: number;
         meshes: number;
     };
+    /**
+     * A census of every surface currently spawned: what it is, where it sits and
+     * roughly how big it is. Built for the template's post-session readout, so a
+     * mystery shape on the headset can be looked up by its label instead of
+     * guessed at — a small-radius entry at head height IS the mystery shape, and
+     * a clean list means whatever was seen did not come from this system.
+     */
+    getDebugSnapshot(world: World): {
+        kind: "plane" | "mesh";
+        label: string | null;
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        radius: number;
+        /** Tracking currently lost — pose frozen at the last known place. */
+        emulated: boolean;
+    }[];
+    /** Create the no-scan floor once; it lives in the ordinary plane map. */
+    private ensureSyntheticFloor;
+    /** Real scene data exists (or arrived) — the stand-in must go. */
+    private removeSyntheticFloor;
     private findRig;
     private syncPlanes;
     private syncMeshes;
+    /**
+     * Admission control for a NOT-yet-spawned surface. With a viewer pose
+     * available, the surface must behave world-anchored for a few frames before
+     * an entity is created for it; without one (older runtimes, tests) it is
+     * admitted immediately — the gate can't classify anyway. Returns the
+     * warmed-up gate (carried into the entry so its motion history survives),
+     * or null while the surface must keep waiting.
+     */
+    private admit;
+    /**
+     * Run a surface's pose through its head-glue gate: position in reference
+     * space vs position relative to the viewer. Without a viewer pose the gate
+     * passes everything, degrading to the flag-only behavior.
+     */
+    private gateAllows;
     private createPlaneEntity;
     private applyPlaneCollider;
     private createMeshEntity;
@@ -734,6 +814,106 @@ declare class XREnvironmentSystem implements EcsSystem {
     dispose(world: World): void;
 }
 
+declare class UIInteractionSystem implements EcsSystem {
+    private readonly interaction;
+    private readonly inputSystem;
+    private readonly xrPresses;
+    private mousePress;
+    private mouseHover;
+    /** entityId → seconds of pressed-tint left to display. */
+    private readonly tintFloors;
+    private readonly tinted;
+    private readonly raycaster;
+    /**
+     * @param interaction The XR interaction system, or null in a world with no
+     *   XR (flat 3D experiences) — the mouse path still works via
+     *   `options.inputSystem`.
+     */
+    constructor(interaction: XRInteractionSystem | null, options?: {
+        inputSystem?: InputSystem;
+    });
+    update(world: World, deltaTime?: number): void;
+    private updateXr;
+    private updateMouse;
+    private raycastMouse;
+    private widgetKind;
+    private fire;
+    private dragSlider;
+    private dragSliderMouse;
+    private applySliderPoint;
+    private widgetObject;
+    private rayHitsWidget;
+    private rayPointOnWidget;
+    /**
+     * Dispatch to the widget's Behaviours, then BUBBLE up the parent chain so a
+     * panel script hears its children. Bubbling (not a world broadcast) keeps
+     * two spawned copies of the same menu prefab independent.
+     */
+    private dispatchBubbling;
+    private actionIdOf;
+    private beginPressTint;
+    private endPressTint;
+    private updateTints;
+    private setTint;
+}
+
+/**
+ * Renders spatial-UI widgets: panels, text, buttons, toggles and sliders.
+ *
+ * Lives in `World.setup`'s DEFAULT system list (like `VRTeleportAreaSystem`)
+ * so the editor and every runtime render UI with no consumer wiring. Each
+ * widget's face is ONE canvas-textured quad, rebuilt only when its style
+ * SIGNATURE changes — a canvas redraw plus GPU upload costs 1–3 ms, fine per
+ * edit and catastrophic per frame. Interaction state (hover/pressed) never
+ * touches the canvas: `UIInteractionSystem` tints the material instead.
+ *
+ * Toggle knobs and slider knob/fill are separate GEOMETRY positioned from the
+ * value each frame, so dragging a slider redraws nothing.
+ *
+ * Widget SIZE is authored on the component in metres, never via transform
+ * scale — the texture is rasterised for the authored size, so scale would
+ * stretch texels into blur (and folding live scale into the signature would
+ * rebuild every frame during a two-hand scale gesture).
+ */
+/** Structural canvas type so tests can inject a stub with no DOM. */
+type UiCanvasLike = {
+    width: number;
+    height: number;
+    getContext(kind: "2d"): CanvasRenderingContext2D | null;
+};
+declare class UIPanelSystem implements EcsSystem {
+    private readonly entries;
+    private readonly createCanvas;
+    constructor(options?: {
+        createCanvas?: () => UiCanvasLike;
+    });
+    update(world: World, deltaTime?: number): void;
+    /** All GPU/canvas resources; call on world teardown. */
+    dispose(): void;
+    private syncPanel;
+    private syncText;
+    private syncButton;
+    private syncToggle;
+    private syncSlider;
+    private rebuildIfChanged;
+    private configureTexture;
+    private makeQuad;
+    /** A filled disc (or arc segment, for the fill's rounded cap). */
+    private makeDisc;
+    private addPart;
+    /** Remove + dispose knob/fill/cap so a sync pass rebuilds them fresh. */
+    private disposeMovingParts;
+    /**
+     * Billboard: yaw the ENTITY TRANSFORM toward the camera. Writing the
+     * Object3D directly would be overwritten by `TransformSyncSystem` (which
+     * runs after this system, before render) — the same reason locomotion
+     * writes the rig transform. Skipped in the editor so the gizmo and the
+     * authored rotation stay in charge while authoring.
+     */
+    private applyFollow;
+    private destroyEntry;
+}
+
 /**
  * Answers "where does this ray meet the real world?".
  *
@@ -787,8 +967,12 @@ declare class XRAnchorSystem implements EcsSystem {
     private readonly anchors;
     /** In-flight creations, so one entity is not anchored twice. */
     private readonly pending;
+    /** Per-anchor head-glue gates — see XREnvironmentSystem's TrackedEntry. */
+    private readonly gates;
     private presenting;
-    update(world: World): void;
+    private readonly tmpViewerMatrix;
+    private readonly tmpViewPos;
+    update(world: World, deltaTime?: number): void;
     /** Whether this entity's pose is currently being driven by an anchor. */
     isAnchored(entityId: EntityId): boolean;
     private requestAnchor;
@@ -979,4 +1163,4 @@ declare class XRHoverVisualSystem implements EcsSystem {
     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, type XrHandPoseEventDetail as b, AudioSystem as c, MeshGeometrySystem as d, type ModuleLoader as e, PostprocessingSyncSystem as f, ScriptBehaviourSystem as g, ScriptObjectSystem as h, type SelectionContext as i, VideoSystem as j, XRAnchorSystem as k, XRControllerVisualSystem as l, XREnvironmentSystem as m, XRHandPoseSystem as n, XRHitTestSystem as o, XRHoverVisualSystem as p, XRInputSystem as q, XRInteractionSystem as r, XRLocomotionSystem as s, XRSessionSystem as t, XRTeleportVisualSystem as u, XR_HOVER_SHELL_FLAG as v, type XrHandedness as w, type XrHitResult as x, type XrInputKind as y, readXrCapabilities as z };
+export { AnimationSystem as A, type XrInputKind as B, CameraSyncSystem as C, readXrCapabilities as D, 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, UIInteractionSystem as U, VRTeleportAreaSystem as V, type XrCapabilities as X, type XrInputState as a, type XrHandPoseEventDetail as b, AudioSystem as c, MeshGeometrySystem as d, type ModuleLoader as e, PostprocessingSyncSystem as f, ScriptBehaviourSystem as g, ScriptObjectSystem as h, type SelectionContext as i, UIPanelSystem as j, type UiCanvasLike as k, VideoSystem as l, XRAnchorSystem as m, XRControllerVisualSystem as n, XREnvironmentSystem as o, XRHandPoseSystem as p, XRHitTestSystem as q, XRHoverVisualSystem as r, XRInputSystem as s, XRInteractionSystem as t, XRLocomotionSystem as u, XRSessionSystem as v, XRTeleportVisualSystem as w, XR_HOVER_SHELL_FLAG as x, type XrHandedness as y, type XrHitResult as z };