@relu-interactives/spatial-ecs 0.4.4 → 0.4.5

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

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

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

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

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

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

package/dist/{index-B2oHfqkj.d.ts → index-BphKHaV-.d.ts}

@@ -651,6 +651,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
@@ -718,6 +737,29 @@ 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;

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

@@ -651,6 +651,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
@@ -718,6 +737,29 @@ 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;

package/dist/index.cjs

@@ -12059,6 +12059,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     const rig = world.getComponent(rigEntityId, XRRigComponent);
     const rigTransform = world.getComponent(rigEntityId, TransformComponent);
     if (!rig || !rigTransform) return;
+    if (world.isXrPassthrough()) return;
     const inputs = this.inputSystem.getInputs();
     if (inputs.length === 0) return;
     if (rig.snapTurn) {
@@ -12321,6 +12322,32 @@ var _XRSessionSystem = class _XRSessionSystem {
     }
     if (presenting) {
       this.dispatchInputEdges(world);
+      this.muteDepthOcclusionColor(world);
+    }
+  }
+  /**
+   * 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.
+   */
+  muteDepthOcclusionColor(world) {
+    const xr = world.getRenderer().xr;
+    const material = xr.getDepthSensingMesh?.()?.material;
+    if (material && material.colorWrite !== false) {
+      material.colorWrite = false;
     }
   }
   handleSessionStart(world) {
@@ -12474,8 +12501,12 @@ function planeColliderFromPolygon(polygon) {
 __name(planeColliderFromPolygon, "planeColliderFromPolygon");
 function writeXrMeshGeometry(vertices, indices, existing) {
   const geometry = existing ?? new THREE51__namespace.BufferGeometry();
-  geometry.setAttribute("position", new THREE51__namespace.BufferAttribute(vertices, 3));
-  geometry.setIndex(new THREE51__namespace.BufferAttribute(indices, 1));
+  geometry.setAttribute(
+    "position",
+    new THREE51__namespace.BufferAttribute(vertices.slice(), 3)
+  );
+  geometry.setIndex(new THREE51__namespace.BufferAttribute(indices.slice(), 1));
+  geometry.deleteAttribute("normal");
   geometry.computeBoundingSphere();
   geometry.computeVertexNormals();
   return geometry;
@@ -12501,7 +12532,42 @@ __name(decomposeXrPose, "decomposeXrPose");
 
 // core/systems/XREnvironmentSystem.ts
 var DEBUG_COLOR = 5088255;
+function debugColorFor(kind, semanticLabel) {
+  switch (semanticLabel) {
+    case "floor":
+      return 5100666;
+    // green — the surface everything should rest on
+    case "ceiling":
+      return 11693055;
+    // purple
+    case "wall":
+    case "wall face":
+      return DEBUG_COLOR;
+    // blue, the family's base colour
+    case "global mesh":
+      return 9079442;
+    // dim gray — raw scan, not an object
+    default:
+      return semanticLabel ? 16747594 : DEBUG_COLOR;
+  }
+}
+__name(debugColorFor, "debugColorFor");
+var GLOBAL_MESH_DEBUG_OPACITY = 0.35;
+var DEBUG_RENDER_ORDER = 900;
 var ROOM_CAPTURE_DELAY_SECONDS = 3;
+var SYNTHETIC_FLOOR_EXTENT = 50;
+var SYNTHETIC_FLOOR_PLANE = {
+  planeSpace: {},
+  polygon: [
+    { x: -SYNTHETIC_FLOOR_EXTENT / 2, y: 0, z: -SYNTHETIC_FLOOR_EXTENT / 2 },
+    { x: SYNTHETIC_FLOOR_EXTENT / 2, y: 0, z: -SYNTHETIC_FLOOR_EXTENT / 2 },
+    { x: SYNTHETIC_FLOOR_EXTENT / 2, y: 0, z: SYNTHETIC_FLOOR_EXTENT / 2 },
+    { x: -SYNTHETIC_FLOOR_EXTENT / 2, y: 0, z: SYNTHETIC_FLOOR_EXTENT / 2 }
+  ],
+  orientation: "horizontal",
+  semanticLabel: "floor",
+  lastChangedTime: 0
+};
 var _XREnvironmentSystem = class _XREnvironmentSystem {
   constructor() {
     /** Keyed by the XRPlane/XRMesh object itself — the runtime's own identity. */
@@ -12542,6 +12608,11 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     const frame = xr.getFrame?.();
     const referenceSpace = xr.getReferenceSpace();
     if (!frame || !referenceSpace) return;
+    if (frame.detectedPlanes === void 0 && frame.detectedMeshes === void 0) {
+      this.ensureSyntheticFloor(world);
+      return;
+    }
+    this.removeSyntheticFloor(world);
     const meshesAvailable = Boolean(frame.detectedMeshes);
     const useMesh = (mode === "mesh" || mode === "auto") && meshesAvailable;
     const usePlanes = mode === "planes" || mode === "auto" && !useMesh;
@@ -12588,6 +12659,51 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
   getDetectedCount() {
     return { planes: this.planes.size, meshes: this.meshes.size };
   }
+  /**
+   * 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) {
+    const snapshot = [];
+    for (const [plane, entry] of this.planes) {
+      const transform = world.getComponent(entry.entityId, TransformComponent);
+      const collider = planeColliderFromPolygon(plane.polygon);
+      snapshot.push({
+        kind: "plane",
+        label: plane.semanticLabel ?? null,
+        position: transform ? { ...transform.position } : { x: 0, y: 0, z: 0 },
+        radius: collider ? Math.hypot(collider.size.x, collider.size.z) / 2 : 0,
+        emulated: entry.emulated
+      });
+    }
+    for (const [mesh, entry] of this.meshes) {
+      const transform = world.getComponent(entry.entityId, TransformComponent);
+      snapshot.push({
+        kind: "mesh",
+        label: mesh.semanticLabel ?? null,
+        position: transform ? { ...transform.position } : { x: 0, y: 0, z: 0 },
+        radius: entry.geometry?.boundingSphere?.radius ?? 0,
+        emulated: entry.emulated
+      });
+    }
+    return snapshot;
+  }
+  /** Create the no-scan floor once; it lives in the ordinary plane map. */
+  ensureSyntheticFloor(world) {
+    if (this.planes.has(SYNTHETIC_FLOOR_PLANE)) return;
+    const created = this.createPlaneEntity(world, SYNTHETIC_FLOOR_PLANE);
+    if (created) this.planes.set(SYNTHETIC_FLOOR_PLANE, created);
+  }
+  /** Real scene data exists (or arrived) — the stand-in must go. */
+  removeSyntheticFloor(world) {
+    const entry = this.planes.get(SYNTHETIC_FLOOR_PLANE);
+    if (!entry) return;
+    this.destroyEntry(world, entry);
+    this.planes.delete(SYNTHETIC_FLOOR_PLANE);
+  }
   findRig(world) {
     const ids = world.query(XRRigComponent);
     if (ids.length === 0) return null;
@@ -12605,9 +12721,11 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     for (const plane of detected) {
       const pose = frame.getPose(plane.planeSpace, referenceSpace);
       if (!pose) continue;
+      const emulated = pose.emulatedPosition === true;
       let entry = this.planes.get(plane);
       const changed = plane.lastChangedTime ?? 0;
       if (!entry) {
+        if (emulated) continue;
         const created = this.createPlaneEntity(world, plane);
         if (!created) continue;
         entry = created;
@@ -12620,11 +12738,17 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
           if (collider) {
             entry.geometry?.dispose();
             entry.geometry = null;
-            this.attachPlaneDebug(world, entry, collider);
+            this.attachPlaneDebug(
+              world,
+              entry,
+              collider,
+              plane.semanticLabel ?? null
+            );
           }
         }
       }
-      this.applyPose(world, entry.entityId, pose);
+      entry.emulated = emulated;
+      if (!emulated) this.applyPose(world, entry.entityId, pose);
     }
   }
   syncMeshes(world, frame, referenceSpace) {
@@ -12639,9 +12763,11 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     for (const mesh of detected) {
       const pose = frame.getPose(mesh.meshSpace, referenceSpace);
       if (!pose) continue;
+      const emulated = pose.emulatedPosition === true;
       let entry = this.meshes.get(mesh);
       const changed = mesh.lastChangedTime ?? 0;
       if (!entry) {
+        if (emulated) continue;
         const created = this.createMeshEntity(world, mesh);
         if (!created) continue;
         entry = created;
@@ -12650,7 +12776,8 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
         entry.lastChangedTime = changed;
         writeXrMeshGeometry(mesh.vertices, mesh.indices, entry.geometry);
       }
-      this.applyPose(world, entry.entityId, pose);
+      entry.emulated = emulated;
+      if (!emulated) this.applyPose(world, entry.entityId, pose);
     }
   }
   createPlaneEntity(world, plane) {
@@ -12670,9 +12797,12 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       entityId,
       lastChangedTime: plane.lastChangedTime ?? 0,
       geometry: null,
-      material: null
+      material: null,
+      emulated: false
     };
-    if (this.debugVisible) this.attachPlaneDebug(world, entry, collider);
+    if (this.debugVisible) {
+      this.attachPlaneDebug(world, entry, collider, plane.semanticLabel ?? null);
+    }
     return entry;
   }
   applyPlaneCollider(world, entityId, plane) {
@@ -12697,15 +12827,36 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
   createMeshEntity(world, mesh) {
     if (!mesh.vertices?.length || !mesh.indices?.length) return null;
     const geometry = writeXrMeshGeometry(mesh.vertices, mesh.indices);
+    const label = mesh.semanticLabel ?? null;
+    const isGlobalMesh = label === "global mesh";
     const material = new THREE51__namespace.MeshBasicMaterial({
-      color: DEBUG_COLOR,
-      wireframe: true
+      color: debugColorFor("mesh", label),
+      wireframe: true,
+      // The global scan is a coarse triangle soup of the whole room; at full
+      // strength it reads as phantom objects rather than as context.
+      transparent: isGlobalMesh,
+      opacity: isGlobalMesh ? GLOBAL_MESH_DEBUG_OPACITY : 1,
+      // Depth-TESTED, deliberately. The overlay was X-ray for one release —
+      // introduced on the theory that depth occlusion was carving it into a
+      // head-locked dome — but that theory was falsified (the dome was the
+      // depth mesh's unset colour output, plus emulated poses; both fixed).
+      // X-ray had its own on-device failure: the global scan is DENSE, and a
+      // dense wireframe at 0.35 opacity fuses into a translucent sheet — with
+      // no depth test the walls' sheets drew through everything, stacked in
+      // front of the user's eyes ("planes covering my face"). With the depth
+      // buffer now holding CORRECT real-world depth, normal testing gives the
+      // right picture: the near wall hides the far one. depthWrite stays off
+      // so the overlay never occludes actual content.
+      depthTest: true,
+      depthWrite: false
     });
     const root = new THREE51__namespace.Group();
     const child = new THREE51__namespace.Mesh(geometry, material);
     child.visible = this.debugVisible;
+    child.renderOrder = DEBUG_RENDER_ORDER;
     root.add(child);
     const entityId = world.createEntity();
+    root.userData.entityId = entityId;
     world.addComponents(entityId, [
       new TransformComponent(),
       new Object3DRef(root),
@@ -12719,29 +12870,37 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       entityId,
       lastChangedTime: mesh.lastChangedTime ?? 0,
       geometry,
-      material
+      material,
+      emulated: false
     };
   }
   /** A thin box so a detected plane can be SEEN, not just collided with. */
-  attachPlaneDebug(world, entry, collider) {
-    const geometry = new THREE51__namespace.BoxGeometry(
+  attachPlaneDebug(world, entry, collider, semanticLabel) {
+    const box = new THREE51__namespace.BoxGeometry(
       collider.size.x,
       collider.size.y,
       collider.size.z
     );
-    const material = new THREE51__namespace.MeshBasicMaterial({
-      color: DEBUG_COLOR,
-      wireframe: true
+    const geometry = new THREE51__namespace.EdgesGeometry(box);
+    box.dispose();
+    const material = new THREE51__namespace.LineBasicMaterial({
+      color: debugColorFor("plane", semanticLabel),
+      // Same depth policy as the mesh overlay — see createMeshEntity.
+      depthTest: true,
+      depthWrite: false
     });
     const root = new THREE51__namespace.Group();
-    const child = new THREE51__namespace.Mesh(geometry, material);
+    const child = new THREE51__namespace.LineSegments(geometry, material);
+    child.renderOrder = DEBUG_RENDER_ORDER;
     child.position.set(collider.offset.x, collider.offset.y, collider.offset.z);
     child.visible = this.debugVisible;
     root.add(child);
     entry.geometry = geometry;
     entry.material = material;
+    root.userData.entityId = entry.entityId;
     const existing = world.getComponent(entry.entityId, Object3DRef);
     if (existing) {
+      existing.object.removeFromParent();
       existing.object = root;
     } else {
       world.addComponent(entry.entityId, new Object3DRef(root));
@@ -12757,19 +12916,31 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       for (const [plane, entry] of this.planes) {
         if (entry.geometry) continue;
         const collider = planeColliderFromPolygon(plane.polygon);
-        if (collider) this.attachPlaneDebug(world, entry, collider);
+        if (collider) {
+          this.attachPlaneDebug(
+            world,
+            entry,
+            collider,
+            plane.semanticLabel ?? null
+          );
+        }
       }
     }
     for (const map of [this.planes, this.meshes]) {
       for (const entry of map.values()) {
         const ref = world.getComponent(entry.entityId, Object3DRef);
         ref?.object.traverse((child) => {
-          if (child.isMesh) child.visible = this.debugVisible;
+          const drawable = child;
+          if (drawable.isMesh || drawable.isLine) {
+            child.visible = this.debugVisible;
+          }
         });
       }
     }
   }
   destroyEntry(world, entry) {
+    const ref = world.getComponent(entry.entityId, Object3DRef);
+    ref?.object.removeFromParent();
     entry.geometry?.dispose();
     entry.material?.dispose();
     world.destroyEntity(entry.entityId);
@@ -12946,7 +13117,9 @@ var _XRAnchorSystem = class _XRAnchorSystem {
         continue;
       }
       const pose = frame.getPose(anchor.anchorSpace, referenceSpace);
-      if (pose) decomposeXrPose(pose.transform.matrix, transform);
+      if (pose && pose.emulatedPosition !== true) {
+        decomposeXrPose(pose.transform.matrix, transform);
+      }
     }
   }
   /** Whether this entity's pose is currently being driven by an anchor. */