@relu-interactives/spatial-ecs 0.4.4 → 0.5.0

package/dist/systems/index.cjs

@@ -2187,6 +2187,100 @@ var _XRAnchorComponent = class _XRAnchorComponent extends Component {
 __name(_XRAnchorComponent, "XRAnchorComponent");
 var XRAnchorComponent = _XRAnchorComponent;
 
+// core/components/UIPanel.ts
+var _UIPanelComponent = class _UIPanelComponent extends Component {
+  constructor(options) {
+    super();
+    this.width = options?.width ?? 0.6;
+    this.height = options?.height ?? 0.4;
+    this.backgroundColor = options?.backgroundColor ?? "#1c1c1c";
+    this.backgroundOpacity = options?.backgroundOpacity ?? 0.92;
+    this.cornerRadius = options?.cornerRadius ?? 0.02;
+    this.borderWidth = options?.borderWidth ?? 0;
+    this.borderColor = options?.borderColor ?? "#333333";
+    this.pixelDensity = options?.pixelDensity ?? 1024;
+    this.follow = options?.follow ?? "world";
+  }
+};
+__name(_UIPanelComponent, "UIPanelComponent");
+var UIPanelComponent = _UIPanelComponent;
+
+// core/components/UIText.ts
+var _UITextComponent = class _UITextComponent extends Component {
+  constructor(options) {
+    super();
+    this.text = options?.text ?? "Text";
+    this.width = options?.width ?? 0.5;
+    this.height = options?.height ?? 0.12;
+    this.fontSize = options?.fontSize ?? 0.035;
+    this.fontWeight = options?.fontWeight ?? 500;
+    this.color = options?.color ?? "#ffffff";
+    this.align = options?.align ?? "center";
+    this.valign = options?.valign ?? "middle";
+    this.lineHeight = options?.lineHeight ?? 1.25;
+    this.padding = options?.padding ?? 0.01;
+  }
+};
+__name(_UITextComponent, "UITextComponent");
+var UITextComponent = _UITextComponent;
+
+// core/components/UIButton.ts
+var _UIButtonComponent = class _UIButtonComponent extends Component {
+  constructor(options) {
+    super();
+    this.label = options?.label ?? "Button";
+    this.actionId = options?.actionId ?? "";
+    this.width = options?.width ?? 0.3;
+    this.height = options?.height ?? 0.1;
+    this.fontSize = options?.fontSize ?? 0.03;
+    this.fontWeight = options?.fontWeight ?? 600;
+    this.textColor = options?.textColor ?? "#ffffff";
+    this.backgroundColor = options?.backgroundColor ?? "#2a2a2a";
+    this.backgroundOpacity = options?.backgroundOpacity ?? 1;
+    this.cornerRadius = options?.cornerRadius ?? 0.02;
+    this.borderWidth = options?.borderWidth ?? 2e-3;
+    this.borderColor = options?.borderColor ?? "#3a3a3a";
+  }
+};
+__name(_UIButtonComponent, "UIButtonComponent");
+var UIButtonComponent = _UIButtonComponent;
+
+// core/components/UIToggle.ts
+var _UIToggleComponent = class _UIToggleComponent extends Component {
+  constructor(options) {
+    super();
+    this.value = options?.value ?? false;
+    this.actionId = options?.actionId ?? "";
+    this.width = options?.width ?? 0.14;
+    this.height = options?.height ?? 0.07;
+    this.trackColor = options?.trackColor ?? "#2a2a2a";
+    this.accentColor = options?.accentColor ?? "#ff6b35";
+    this.knobColor = options?.knobColor ?? "#ffffff";
+  }
+};
+__name(_UIToggleComponent, "UIToggleComponent");
+var UIToggleComponent = _UIToggleComponent;
+
+// core/components/UISlider.ts
+var _UISliderComponent = class _UISliderComponent extends Component {
+  constructor(options) {
+    super();
+    this.min = options?.min ?? 0;
+    this.max = options?.max ?? Math.max(1, this.min + 1);
+    if (this.max <= this.min) this.max = this.min + 1;
+    const v = options?.value ?? (this.min + this.max) / 2;
+    this.value = Math.min(this.max, Math.max(this.min, v));
+    this.actionId = options?.actionId ?? "";
+    this.width = options?.width ?? 0.4;
+    this.height = options?.height ?? 0.06;
+    this.trackColor = options?.trackColor ?? "#2a2a2a";
+    this.accentColor = options?.accentColor ?? "#ff6b35";
+    this.knobColor = options?.knobColor ?? "#ffffff";
+  }
+};
+__name(_UISliderComponent, "UISliderComponent");
+var UISliderComponent = _UISliderComponent;
+
 // core/components/XRInteractor.ts
 var _XRInteractorComponent = class _XRInteractorComponent extends Component {
   constructor(options) {
@@ -5288,6 +5382,11 @@ function buildComponentValueMaps(snapshot) {
       "XRHandPoseComponent"
     ),
     xrAnchorValues: readByComponent(snapshot.components, "XRAnchorComponent"),
+    uiPanelValues: readByComponent(snapshot.components, "UIPanelComponent"),
+    uiTextValues: readByComponent(snapshot.components, "UITextComponent"),
+    uiButtonValues: readByComponent(snapshot.components, "UIButtonComponent"),
+    uiToggleValues: readByComponent(snapshot.components, "UIToggleComponent"),
+    uiSliderValues: readByComponent(snapshot.components, "UISliderComponent"),
     xrInteractorSideValues: readByComponent(
       snapshot.components,
       "XRInteractorSideComponent"
@@ -5609,6 +5708,49 @@ function restorePostCreateComponents(world, objectManagementSystem, targetEntity
       }
     }
   }
+  {
+    const restoreUi = /* @__PURE__ */ __name((map, Ctor, existing) => {
+      const source = asRecord3(map.get(sourceEntityId));
+      if (!source) return;
+      let component = existing;
+      if (!component) {
+        component = new Ctor();
+        world.addComponent(targetEntityId, component);
+      }
+      const target = component;
+      for (const [key, value] of Object.entries(source)) {
+        const current = target[key];
+        if ((typeof value === "string" || typeof value === "number" || typeof value === "boolean") && typeof current === typeof value) {
+          target[key] = value;
+        }
+      }
+    }, "restoreUi");
+    restoreUi(
+      values.uiPanelValues,
+      UIPanelComponent,
+      world.getComponent(targetEntityId, UIPanelComponent)
+    );
+    restoreUi(
+      values.uiTextValues,
+      UITextComponent,
+      world.getComponent(targetEntityId, UITextComponent)
+    );
+    restoreUi(
+      values.uiButtonValues,
+      UIButtonComponent,
+      world.getComponent(targetEntityId, UIButtonComponent)
+    );
+    restoreUi(
+      values.uiToggleValues,
+      UIToggleComponent,
+      world.getComponent(targetEntityId, UIToggleComponent)
+    );
+    restoreUi(
+      values.uiSliderValues,
+      UISliderComponent,
+      world.getComponent(targetEntityId, UISliderComponent)
+    );
+  }
   {
     const sourceInteractor = asRecord3(
       values.xrInteractorValues.get(sourceEntityId)
@@ -7031,6 +7173,23 @@ var _Behaviour = class _Behaviour {
   /** Called when this entity is released. Optional XR hook. */
   onRelease(input) {
   }
+  /** A UI button on this entity (or a descendant) was clicked. Clicks fire on
+   * RELEASE while still pointing at the widget — sliding off cancels. */
+  onUiPress(_event) {
+  }
+  /** A pointer began hovering a UI widget on this entity (or a descendant). */
+  onUiHoverStart(_event) {
+  }
+  /** The pointer left the widget. */
+  onUiHoverEnd(_event) {
+  }
+  /** A UI toggle flipped; `event.value` is the new boolean. */
+  onUiToggle(_event) {
+  }
+  /** A UI slider moved; `event.value` is the new number. Fires on real value
+   * changes during the drag and once more on release. */
+  onUiChange(_event) {
+  }
 };
 __name(_Behaviour, "Behaviour");
 /**
@@ -8561,6 +8720,7 @@ var _XRInteractionSystem = class _XRInteractionSystem {
     this.grabs = /* @__PURE__ */ new Map();
     this.hoveredEntityId = null;
     /** Per-hand hover, with the hit distance so the ray can stop at the surface. */
+    this.busyContributors = [];
     this.hovers = /* @__PURE__ */ new Map();
     /** Monotonic seconds, accumulated from deltaTime for velocity sampling. */
     this.elapsed = 0;
@@ -8569,6 +8729,8 @@ var _XRInteractionSystem = class _XRInteractionSystem {
   update(world, deltaTime) {
     if (!world.isXrPresenting()) {
       this.releaseAll(world);
+      this.hovers.clear();
+      this.hoveredEntityId = null;
       return;
     }
     this.elapsed += Math.max(0, deltaTime);
@@ -9191,13 +9353,30 @@ var _XRInteractionSystem = class _XRInteractionSystem {
    */
   isSourceBusy(world, input) {
     if (this.grabs.has(input)) return true;
+    for (const contributor of this.busyContributors) {
+      try {
+        if (contributor(world, input)) return true;
+      } catch {
+      }
+    }
     const hover = this.hovers.get(input);
     if (!hover) return false;
     const interactable = world.getComponent(
       hover.entityId,
       XRInteractableComponent
     );
-    return Boolean(interactable?.enabled && interactable.grabbable);
+    return Boolean(
+      interactable?.enabled && (interactable.grabbable || interactable.pointable)
+    );
+  }
+  /** OR-ed into isSourceBusy; see the comment there. */
+  registerBusyContributor(contributor) {
+    this.busyContributors.push(contributor);
+  }
+  /** Hover for a specific input source (handedness-free — Vision Pro's
+   * transient pointers all report handedness "none"). */
+  getHoverForInput(input) {
+    return this.hovers.get(input) ?? null;
   }
   /** True when THIS hand is holding something. */
   isGrabbingWith(handedness) {
@@ -9348,6 +9527,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) {
@@ -9610,6 +9790,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) {
@@ -9763,8 +9969,12 @@ function planeColliderFromPolygon(polygon) {
 __name(planeColliderFromPolygon, "planeColliderFromPolygon");
 function writeXrMeshGeometry(vertices, indices, existing) {
   const geometry = existing ?? new THREE26__namespace.BufferGeometry();
-  geometry.setAttribute("position", new THREE26__namespace.BufferAttribute(vertices, 3));
-  geometry.setIndex(new THREE26__namespace.BufferAttribute(indices, 1));
+  geometry.setAttribute(
+    "position",
+    new THREE26__namespace.BufferAttribute(vertices.slice(), 3)
+  );
+  geometry.setIndex(new THREE26__namespace.BufferAttribute(indices.slice(), 1));
+  geometry.deleteAttribute("normal");
   geometry.computeBoundingSphere();
   geometry.computeVertexNormals();
   return geometry;
@@ -9788,20 +9998,151 @@ function decomposeXrPose(matrixElements, target) {
 }
 __name(decomposeXrPose, "decomposeXrPose");
 
+// core/xr/poseStability.ts
+var GLUED_REF_SPEED = 0.12;
+var STILL_SPEED = 0.05;
+var GLUED_FRAMES_TO_FREEZE = 3;
+var STATIC_FRAMES_TO_RECOVER = 10;
+var SNAP_SPEED = 3;
+var dist = /* @__PURE__ */ __name((a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z), "dist");
+var _SurfacePoseGate = class _SurfacePoseGate {
+  constructor() {
+    this.prevRef = null;
+    this.prevView = null;
+    this.gluedStreak = 0;
+    this.staticStreak = 0;
+    this.suspect = false;
+    this.deltas = 0;
+  }
+  /** True while poses are being rejected as head-glued. */
+  get frozen() {
+    return this.suspect;
+  }
+  /**
+   * True once enough motion has been observed to classify the pose at all.
+   * Surface CREATION waits for this: an entity spawned from a glued pose
+   * materializes wherever the head happens to be — a rotated ghost copy of
+   * the room — and freezing it there is barely better than letting it follow.
+   */
+  get warmedUp() {
+    return this.deltas >= GLUED_FRAMES_TO_FREEZE;
+  }
+  /**
+   * Feed this frame's surface position in reference space and in view
+   * (viewer-relative) space. Returns true when the pose should be APPLIED,
+   * false when it should be frozen out.
+   *
+   * `viewPos` may be null when the viewer pose is unavailable (older
+   * runtimes) — the gate then passes everything through, degrading to the
+   * flag-only behavior.
+   */
+  update(refPos, viewPos, deltaTime) {
+    if (!viewPos || deltaTime <= 0) {
+      this.prevRef = { ...refPos };
+      this.prevView = viewPos ? { ...viewPos } : null;
+      return !this.suspect;
+    }
+    const prevRef = this.prevRef;
+    const prevView = this.prevView;
+    this.prevRef = { ...refPos };
+    this.prevView = { ...viewPos };
+    if (!prevRef || !prevView) return !this.suspect;
+    this.deltas += 1;
+    const refSpeed = dist(refPos, prevRef) / deltaTime;
+    const viewSpeed = dist(viewPos, prevView) / deltaTime;
+    const glued = refSpeed > GLUED_REF_SPEED && viewSpeed < STILL_SPEED;
+    const worldStatic = refSpeed < STILL_SPEED && viewSpeed > GLUED_REF_SPEED;
+    if (this.suspect) {
+      if (refSpeed > SNAP_SPEED && viewSpeed > SNAP_SPEED) {
+        this.suspect = false;
+        this.gluedStreak = 0;
+        this.staticStreak = 0;
+        return true;
+      }
+      this.staticStreak = worldStatic ? this.staticStreak + 1 : 0;
+      if (this.staticStreak >= STATIC_FRAMES_TO_RECOVER) {
+        this.suspect = false;
+        this.gluedStreak = 0;
+        this.staticStreak = 0;
+        return true;
+      }
+      return false;
+    }
+    this.gluedStreak = glued ? this.gluedStreak + 1 : 0;
+    if (this.gluedStreak >= GLUED_FRAMES_TO_FREEZE) {
+      this.suspect = true;
+      this.staticStreak = 0;
+      return false;
+    }
+    return true;
+  }
+};
+__name(_SurfacePoseGate, "SurfacePoseGate");
+var SurfacePoseGate = _SurfacePoseGate;
+
 // 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. */
     this.planes = /* @__PURE__ */ new Map();
     this.meshes = /* @__PURE__ */ new Map();
+    /**
+     * 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.
+     */
+    this.pendingPlanes = /* @__PURE__ */ new Map();
+    this.pendingMeshes = /* @__PURE__ */ new Map();
     this.presenting = false;
     this.debugVisible = false;
     /** Seconds presenting, used to decide the room has genuinely nothing in it. */
     this.elapsed = 0;
     /** `initiateRoomCapture` may be called only ONCE per session. */
     this.roomCaptureRequested = false;
+    /** This frame's inverse viewer matrix, or null when unavailable. */
+    this.viewerInverse = null;
+    this.tmpViewerMatrix = new THREE26__namespace.Matrix4();
+    this.tmpViewPos = new THREE26__namespace.Vector3();
   }
   update(world, deltaTime = 0) {
     const presenting = world.isXrPresenting();
@@ -9831,16 +10172,23 @@ 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;
+    const viewer = frame.getViewerPose?.(referenceSpace);
+    this.viewerInverse = viewer ? this.tmpViewerMatrix.fromArray(viewer.transform.matrix).invert() : null;
     if (usePlanes) {
-      this.syncPlanes(world, frame, referenceSpace);
+      this.syncPlanes(world, frame, referenceSpace, deltaTime);
     } else if (this.planes.size > 0) {
       this.clearMap(world, this.planes);
     }
     if (useMesh) {
-      this.syncMeshes(world, frame, referenceSpace);
+      this.syncMeshes(world, frame, referenceSpace, deltaTime);
     } else if (this.meshes.size > 0) {
       this.clearMap(world, this.meshes);
     }
@@ -9877,12 +10225,57 @@ 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;
     return world.getComponent(ids[0], XRRigComponent) ?? null;
   }
-  syncPlanes(world, frame, referenceSpace) {
+  syncPlanes(world, frame, referenceSpace, deltaTime) {
     const detected = frame.detectedPlanes;
     if (!detected) return;
     for (const [plane, entry] of this.planes) {
@@ -9891,14 +10284,22 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
         this.planes.delete(plane);
       }
     }
+    for (const plane of this.pendingPlanes.keys()) {
+      if (!detected.has(plane)) this.pendingPlanes.delete(plane);
+    }
     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 gate = this.admit(this.pendingPlanes, plane, pose, deltaTime);
+        if (!gate) continue;
         const created = this.createPlaneEntity(world, plane);
         if (!created) continue;
+        created.gate = gate;
         entry = created;
         this.planes.set(plane, entry);
       } else if (changed !== entry.lastChangedTime) {
@@ -9909,14 +10310,21 @@ 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);
+      const allowed = !emulated && this.gateAllows(entry.gate, pose, deltaTime);
+      entry.emulated = emulated || entry.gate.frozen;
+      if (allowed) this.applyPose(world, entry.entityId, pose);
     }
   }
-  syncMeshes(world, frame, referenceSpace) {
+  syncMeshes(world, frame, referenceSpace, deltaTime) {
     const detected = frame.detectedMeshes;
     if (!detected) return;
     for (const [mesh, entry] of this.meshes) {
@@ -9925,22 +10333,67 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
         this.meshes.delete(mesh);
       }
     }
+    for (const mesh of this.pendingMeshes.keys()) {
+      if (!detected.has(mesh)) this.pendingMeshes.delete(mesh);
+    }
     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 gate = this.admit(this.pendingMeshes, mesh, pose, deltaTime);
+        if (!gate) continue;
         const created = this.createMeshEntity(world, mesh);
         if (!created) continue;
+        created.gate = gate;
         entry = created;
         this.meshes.set(mesh, entry);
       } else if (changed !== entry.lastChangedTime) {
         entry.lastChangedTime = changed;
         writeXrMeshGeometry(mesh.vertices, mesh.indices, entry.geometry);
       }
-      this.applyPose(world, entry.entityId, pose);
+      const allowed = !emulated && this.gateAllows(entry.gate, pose, deltaTime);
+      entry.emulated = emulated || entry.gate.frozen;
+      if (allowed) this.applyPose(world, entry.entityId, pose);
+    }
+  }
+  /**
+   * 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.
+   */
+  admit(pending, key, pose, deltaTime) {
+    if (!this.viewerInverse) return new SurfacePoseGate();
+    let gate = pending.get(key);
+    if (!gate) {
+      gate = new SurfacePoseGate();
+      pending.set(key, gate);
+    }
+    const allowed = this.gateAllows(gate, pose, deltaTime);
+    if (!allowed || !gate.warmedUp) return null;
+    pending.delete(key);
+    return gate;
+  }
+  /**
+   * 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.
+   */
+  gateAllows(gate, pose, deltaTime) {
+    const m = pose.transform.matrix;
+    const refPos = { x: m[12], y: m[13], z: m[14] };
+    let viewPos = null;
+    if (this.viewerInverse) {
+      const v = this.tmpViewPos.set(refPos.x, refPos.y, refPos.z).applyMatrix4(this.viewerInverse);
+      viewPos = { x: v.x, y: v.y, z: v.z };
     }
+    return gate.update(refPos, viewPos, deltaTime);
   }
   createPlaneEntity(world, plane) {
     const collider = planeColliderFromPolygon(plane.polygon);
@@ -9959,9 +10412,13 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       entityId,
       lastChangedTime: plane.lastChangedTime ?? 0,
       geometry: null,
-      material: null
+      material: null,
+      emulated: false,
+      gate: new SurfacePoseGate()
     };
-    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) {
@@ -9986,15 +10443,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 THREE26__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 THREE26__namespace.Group();
     const child = new THREE26__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),
@@ -10008,29 +10486,38 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       entityId,
       lastChangedTime: mesh.lastChangedTime ?? 0,
       geometry,
-      material
+      material,
+      emulated: false,
+      gate: new SurfacePoseGate()
     };
   }
   /** A thin box so a detected plane can be SEEN, not just collided with. */
-  attachPlaneDebug(world, entry, collider) {
-    const geometry = new THREE26__namespace.BoxGeometry(
+  attachPlaneDebug(world, entry, collider, semanticLabel) {
+    const box = new THREE26__namespace.BoxGeometry(
       collider.size.x,
       collider.size.y,
       collider.size.z
     );
-    const material = new THREE26__namespace.MeshBasicMaterial({
-      color: DEBUG_COLOR,
-      wireframe: true
+    const geometry = new THREE26__namespace.EdgesGeometry(box);
+    box.dispose();
+    const material = new THREE26__namespace.LineBasicMaterial({
+      color: debugColorFor("plane", semanticLabel),
+      // Same depth policy as the mesh overlay — see createMeshEntity.
+      depthTest: true,
+      depthWrite: false
     });
     const root = new THREE26__namespace.Group();
-    const child = new THREE26__namespace.Mesh(geometry, material);
+    const child = new THREE26__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));
@@ -10046,19 +10533,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);
@@ -10070,6 +10569,8 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
   clearAll(world) {
     this.clearMap(world, this.planes);
     this.clearMap(world, this.meshes);
+    this.pendingPlanes.clear();
+    this.pendingMeshes.clear();
   }
   dispose(world) {
     this.clearAll(world);
@@ -10081,6 +10582,918 @@ function normalizeOrientation(value) {
   return value === "horizontal" || value === "vertical" ? value : null;
 }
 __name(normalizeOrientation, "normalizeOrientation");
+var MOUSE_CLICK_TRAVEL_PX = 6;
+var PRESS_TINT_MIN_SECONDS = 0.1;
+var PRESS_TINT = 0.72;
+var HOVER_TINT = 0.9;
+var _UIInteractionSystem = class _UIInteractionSystem {
+  /**
+   * @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, options) {
+    this.xrPresses = /* @__PURE__ */ new Map();
+    this.mousePress = null;
+    this.mouseHover = null;
+    /** entityId → seconds of pressed-tint left to display. */
+    this.tintFloors = /* @__PURE__ */ new Map();
+    this.tinted = /* @__PURE__ */ new Set();
+    this.raycaster = new THREE26__namespace.Raycaster();
+    this.interaction = interaction;
+    this.inputSystem = options?.inputSystem ?? null;
+    interaction?.registerBusyContributor(
+      (_world, input) => this.xrPresses.has(input)
+    );
+  }
+  update(world, deltaTime = 0) {
+    if (world.isEditorMode()) return;
+    if (world.isXrPresenting()) {
+      this.updateXr(world);
+    } else {
+      this.updateMouse(world);
+    }
+    this.updateTints(world, deltaTime);
+  }
+  // ── XR path ────────────────────────────────────────────────────────────────
+  updateXr(world) {
+    const interaction = this.interaction;
+    if (!interaction) return;
+    const xrInput = interaction.inputSystem;
+    const inputs = xrInput.getInputs();
+    for (const input of inputs) {
+      const hover = interaction.getHoverForInput(input);
+      const hovered = hover ? this.widgetKind(world, hover.entityId) : null;
+      if (input.selectStart && hover && hovered) {
+        this.xrPresses.set(input, {
+          entityId: hover.entityId,
+          kind: hovered,
+          travelPx: 0
+        });
+        this.beginPressTint(world, hover.entityId);
+      }
+      const press = this.xrPresses.get(input);
+      if (press && press.kind === "slider") {
+        this.dragSlider(world, press.entityId, input);
+      }
+      if (input.selectEnd || !input.connected) {
+        if (press) {
+          this.xrPresses.delete(input);
+          const stillOn = hover?.entityId === press.entityId || // Vision Pro: the transient source is gone from the hover map on
+          // its release frame — confirm against the last latched ray.
+          this.rayHitsWidget(world, press.entityId, input);
+          if (stillOn || press.kind === "slider") {
+            this.fire(world, press, input);
+          }
+          this.endPressTint(press.entityId);
+        }
+      }
+    }
+    for (const [input] of this.xrPresses) {
+      if (!inputs.includes(input)) this.xrPresses.delete(input);
+    }
+  }
+  // ── Mouse path (flat preview) ──────────────────────────────────────────────
+  updateMouse(world) {
+    const input = this.inputSystem;
+    if (!input) return;
+    const hit = this.raycastMouse(world);
+    const hovered = hit && this.widgetKind(world, hit) ? hit : null;
+    if (hovered !== this.mouseHover) {
+      if (this.mouseHover !== null) {
+        this.setTint(world, this.mouseHover, 1);
+        this.dispatchBubbling(
+          world,
+          this.mouseHover,
+          (b, e) => b.onUiHoverEnd(e)
+        );
+      }
+      if (hovered !== null) {
+        this.setTint(world, hovered, HOVER_TINT);
+        this.dispatchBubbling(world, hovered, (b, e) => b.onUiHoverStart(e));
+      }
+      this.mouseHover = hovered;
+    }
+    if (input.getMouseDown("left") && hovered) {
+      const kind = this.widgetKind(world, hovered);
+      if (kind) {
+        this.mousePress = { entityId: hovered, kind, travelPx: 0 };
+        this.beginPressTint(world, hovered);
+      }
+    }
+    if (this.mousePress) {
+      const delta = input.getMouseDelta();
+      this.mousePress.travelPx += Math.hypot(delta.x, delta.y);
+      if (this.mousePress.kind === "slider") {
+        this.dragSliderMouse(world, this.mousePress.entityId);
+      }
+    }
+    if (input.getMouseUp("left") && this.mousePress) {
+      const press = this.mousePress;
+      this.mousePress = null;
+      const stillOn = hovered === press.entityId;
+      const withinTravel = press.travelPx <= MOUSE_CLICK_TRAVEL_PX;
+      if (press.kind === "slider" || stillOn && withinTravel) {
+        this.fire(world, press, null);
+      }
+      this.endPressTint(press.entityId);
+    }
+  }
+  raycastMouse(world) {
+    const input = this.inputSystem;
+    if (!input) return null;
+    const dom = world.getRenderer().domElement;
+    const rect = dom.getBoundingClientRect();
+    let ndcX = 0;
+    let ndcY = 0;
+    if (input.isMousePointerLocked()) {
+      ndcX = 0;
+      ndcY = 0;
+    } else {
+      const pos = input.getMousePosition();
+      ndcX = (pos.x - rect.left) / Math.max(1, rect.width) * 2 - 1;
+      ndcY = -((pos.y - rect.top) / Math.max(1, rect.height) * 2 - 1);
+      if (ndcX < -1 || ndcX > 1 || ndcY < -1 || ndcY > 1) return null;
+    }
+    this.raycaster.setFromCamera(new THREE26__namespace.Vector2(ndcX, ndcY), world.getCamera());
+    const hits = world.raycast(
+      this.raycaster.ray.origin,
+      this.raycaster.ray.direction
+    );
+    for (const hit of hits) {
+      if (typeof hit.entityId !== "number") continue;
+      if (this.widgetKind(world, hit.entityId)) return hit.entityId;
+      return null;
+    }
+    return null;
+  }
+  // ── Shared machinery ───────────────────────────────────────────────────────
+  widgetKind(world, entityId) {
+    if (world.getComponent(entityId, UIButtonComponent)) return "button";
+    if (world.getComponent(entityId, UIToggleComponent)) return "toggle";
+    if (world.getComponent(entityId, UISliderComponent)) return "slider";
+    return null;
+  }
+  fire(world, press, input) {
+    if (press.kind === "button") {
+      this.dispatchBubbling(world, press.entityId, (b, e) => b.onUiPress(e), input);
+      return;
+    }
+    if (press.kind === "toggle") {
+      const toggle = world.getComponent(press.entityId, UIToggleComponent);
+      if (!toggle) return;
+      toggle.value = !toggle.value;
+      this.dispatchBubbling(
+        world,
+        press.entityId,
+        (b, e) => b.onUiToggle(e),
+        input,
+        toggle.value
+      );
+      return;
+    }
+    const slider = world.getComponent(press.entityId, UISliderComponent);
+    if (!slider) return;
+    this.dispatchBubbling(
+      world,
+      press.entityId,
+      (b, e) => b.onUiChange(e),
+      input,
+      slider.value
+    );
+  }
+  dragSlider(world, entityId, input) {
+    const point = this.rayPointOnWidget(world, entityId, input);
+    if (point) this.applySliderPoint(world, entityId, point, input);
+  }
+  dragSliderMouse(world, entityId) {
+    const object = this.widgetObject(world, entityId);
+    if (!object) return;
+    const hits = this.raycaster.intersectObject(object, true);
+    if (hits.length > 0) this.applySliderPoint(world, entityId, hits[0].point, null);
+  }
+  applySliderPoint(world, entityId, worldPoint, input) {
+    const slider = world.getComponent(entityId, UISliderComponent);
+    const object = this.widgetObject(world, entityId);
+    if (!slider || !object) return;
+    const local = object.worldToLocal(worldPoint.clone());
+    const inset = slider.height / 2;
+    const usable = Math.max(1e-3, slider.width - inset * 2);
+    const t = Math.min(1, Math.max(0, local.x / usable + 0.5));
+    const next = slider.min + t * (slider.max - slider.min);
+    if (Math.abs(next - slider.value) < 1e-4) return;
+    slider.value = next;
+    this.dispatchBubbling(
+      world,
+      entityId,
+      (b, e) => b.onUiChange(e),
+      input,
+      next
+    );
+  }
+  widgetObject(world, entityId) {
+    return world.getComponent(entityId, Object3DRef)?.object;
+  }
+  rayHitsWidget(world, entityId, input) {
+    const object = this.widgetObject(world, entityId);
+    if (!object) return false;
+    this.raycaster.set(
+      input.rayOrigin.clone(),
+      input.rayDirection.clone().normalize()
+    );
+    return this.raycaster.intersectObject(object, true).length > 0;
+  }
+  rayPointOnWidget(world, entityId, input) {
+    const object = this.widgetObject(world, entityId);
+    if (!object) return null;
+    this.raycaster.set(
+      input.rayOrigin.clone(),
+      input.rayDirection.clone().normalize()
+    );
+    const hits = this.raycaster.intersectObject(object, true);
+    return hits.length > 0 ? hits[0].point : null;
+  }
+  /**
+   * 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.
+   */
+  dispatchBubbling(world, entityId, visit, input = null, value) {
+    const event = {
+      targetEntityId: entityId,
+      actionId: this.actionIdOf(world, entityId),
+      input,
+      ...value === void 0 ? {} : { value }
+    };
+    const visited = /* @__PURE__ */ new Set();
+    let current = entityId;
+    for (; ; ) {
+      if (visited.has(current)) break;
+      visited.add(current);
+      const script = world.getComponent(current, ScriptComponent);
+      const instances = script?.scriptInstances;
+      if (instances) {
+        for (const instance of instances.values()) {
+          if (!(instance instanceof Behaviour)) continue;
+          try {
+            visit(instance, event);
+          } catch (error) {
+            console.error("[UIInteractionSystem] hook failed:", error);
+          }
+        }
+      }
+      const parentId = world.getComponent(current, ParentId)?.value;
+      if (typeof parentId !== "number") break;
+      current = parentId;
+    }
+  }
+  actionIdOf(world, entityId) {
+    const button = world.getComponent(entityId, UIButtonComponent);
+    if (button?.actionId) return button.actionId;
+    const toggle = world.getComponent(entityId, UIToggleComponent);
+    if (toggle?.actionId) return toggle.actionId;
+    const slider = world.getComponent(entityId, UISliderComponent);
+    if (slider?.actionId) return slider.actionId;
+    const name = world.getComponent(entityId, Name)?.value;
+    return typeof name === "string" ? name : String(entityId);
+  }
+  // ── Pressed/hover tint ─────────────────────────────────────────────────────
+  beginPressTint(world, entityId) {
+    this.setTint(world, entityId, PRESS_TINT);
+    this.tintFloors.set(entityId, PRESS_TINT_MIN_SECONDS);
+  }
+  endPressTint(entityId) {
+    if (!this.tintFloors.has(entityId)) {
+      this.tintFloors.set(entityId, 0);
+    }
+  }
+  updateTints(world, deltaTime) {
+    for (const [entityId, remaining] of this.tintFloors) {
+      const next = remaining - deltaTime;
+      const stillHeld = [...this.xrPresses.values()].some((p) => p.entityId === entityId) || this.mousePress?.entityId === entityId;
+      if (stillHeld) continue;
+      if (next <= 0) {
+        this.tintFloors.delete(entityId);
+        this.setTint(
+          world,
+          entityId,
+          this.mouseHover === entityId ? HOVER_TINT : 1
+        );
+      } else {
+        this.tintFloors.set(entityId, next);
+      }
+    }
+  }
+  setTint(world, entityId, scalar) {
+    const object = this.widgetObject(world, entityId);
+    if (!object) return;
+    if (scalar === 1) this.tinted.delete(entityId);
+    else this.tinted.add(entityId);
+    object.traverse((child) => {
+      const material = child.material;
+      if (material?.color) material.color.setScalar(scalar);
+    });
+  }
+};
+__name(_UIInteractionSystem, "UIInteractionSystem");
+var UIInteractionSystem = _UIInteractionSystem;
+
+// core/ui/uiCanvas.ts
+var DEFAULT_PIXELS_PER_METER = 1024;
+var MIN_PIXELS_PER_METER = 256;
+var MAX_PIXELS_PER_METER = 2048;
+var MAX_CANVAS_SIDE = 2048;
+function resolveCanvasSize(widthMeters, heightMeters, pixelDensity = DEFAULT_PIXELS_PER_METER) {
+  const w = Math.max(0.01, widthMeters);
+  const h = Math.max(0.01, heightMeters);
+  const authored = Math.min(
+    MAX_PIXELS_PER_METER,
+    Math.max(MIN_PIXELS_PER_METER, pixelDensity)
+  );
+  const density = Math.min(authored, MAX_CANVAS_SIDE / Math.max(w, h));
+  const even = /* @__PURE__ */ __name((v) => Math.max(2, 2 * Math.round(v * density / 2)), "even");
+  return { pxWidth: even(w), pxHeight: even(h), density };
+}
+__name(resolveCanvasSize, "resolveCanvasSize");
+function wrapText(measure, text, maxWidthPx) {
+  const lines = [];
+  for (const paragraph of text.split("\n")) {
+    const words = paragraph.split(/\s+/).filter((w) => w.length > 0);
+    if (words.length === 0) {
+      lines.push("");
+      continue;
+    }
+    let line = "";
+    for (const word of words) {
+      const candidate = line ? `${line} ${word}` : word;
+      if (measure(candidate) <= maxWidthPx) {
+        line = candidate;
+        continue;
+      }
+      if (line) {
+        lines.push(line);
+        line = "";
+      }
+      if (measure(word) <= maxWidthPx) {
+        line = word;
+        continue;
+      }
+      let chunk = "";
+      for (const char of word) {
+        const next = chunk + char;
+        if (measure(next) <= maxWidthPx || chunk.length === 0) {
+          chunk = next;
+        } else {
+          lines.push(chunk);
+          chunk = char;
+        }
+      }
+      line = chunk;
+    }
+    lines.push(line);
+  }
+  return lines;
+}
+__name(wrapText, "wrapText");
+var ELLIPSIS = "\u2026";
+function clampLines(measure, lines, maxLines, maxWidthPx) {
+  if (maxLines <= 0) return [];
+  if (lines.length <= maxLines) return lines;
+  const kept = lines.slice(0, maxLines);
+  let last = kept[maxLines - 1];
+  while (last.length > 0 && measure(last + ELLIPSIS) > maxWidthPx) {
+    last = last.slice(0, -1);
+  }
+  kept[maxLines - 1] = last + ELLIPSIS;
+  return kept;
+}
+__name(clampLines, "clampLines");
+var UI_FONT_STACK = '-apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif';
+function tracePath(ctx, x, y, w, h, r) {
+  const radius = Math.max(0, Math.min(r, w / 2, h / 2));
+  ctx.beginPath();
+  if (typeof ctx.roundRect === "function") {
+    ctx.roundRect(x, y, w, h, radius);
+    return;
+  }
+  ctx.moveTo(x + radius, y);
+  ctx.arcTo(x + w, y, x + w, y + h, radius);
+  ctx.arcTo(x + w, y + h, x, y + h, radius);
+  ctx.arcTo(x, y + h, x, y, radius);
+  ctx.arcTo(x, y, x + w, y, radius);
+  ctx.closePath();
+}
+__name(tracePath, "tracePath");
+function withOpacity(ctx, color, opacity) {
+  if (opacity >= 1) return color;
+  ctx.save();
+  ctx.fillStyle = color;
+  const parsed = ctx.fillStyle;
+  ctx.restore();
+  if (parsed.startsWith("#") && (parsed.length === 7 || parsed.length === 4)) {
+    const hex = parsed.length === 4 ? `#${parsed[1]}${parsed[1]}${parsed[2]}${parsed[2]}${parsed[3]}${parsed[3]}` : parsed;
+    const r = Number.parseInt(hex.slice(1, 3), 16);
+    const g = Number.parseInt(hex.slice(3, 5), 16);
+    const b = Number.parseInt(hex.slice(5, 7), 16);
+    return `rgba(${r}, ${g}, ${b}, ${opacity})`;
+  }
+  return parsed;
+}
+__name(withOpacity, "withOpacity");
+function drawChrome(ctx, pxWidth, pxHeight, density, style) {
+  ctx.clearRect(0, 0, pxWidth, pxHeight);
+  const border = Math.max(0, style.borderWidthMeters * density);
+  const radius = style.cornerRadiusMeters * density;
+  tracePath(ctx, 0, 0, pxWidth, pxHeight, radius);
+  ctx.fillStyle = withOpacity(
+    ctx,
+    style.backgroundColor,
+    Math.max(0, Math.min(1, style.backgroundOpacity))
+  );
+  ctx.fill();
+  if (border > 0) {
+    tracePath(
+      ctx,
+      border / 2,
+      border / 2,
+      pxWidth - border,
+      pxHeight - border,
+      Math.max(0, radius - border / 2)
+    );
+    ctx.strokeStyle = style.borderColor;
+    ctx.lineWidth = border;
+    ctx.stroke();
+  }
+}
+__name(drawChrome, "drawChrome");
+function drawTextBlock(ctx, pxWidth, pxHeight, density, text, style) {
+  const fontPx = Math.max(4, style.fontSizeMeters * density);
+  const paddingPx = style.paddingMeters * density;
+  const contentW = Math.max(1, pxWidth - paddingPx * 2);
+  const contentH = Math.max(1, pxHeight - paddingPx * 2);
+  const lineHeightPx = fontPx * style.lineHeight;
+  ctx.font = `${style.fontWeight} ${fontPx}px ${UI_FONT_STACK}`;
+  const measure = /* @__PURE__ */ __name((s) => ctx.measureText(s).width, "measure");
+  const maxLines = Math.max(1, Math.floor(contentH / lineHeightPx));
+  const lines = clampLines(
+    measure,
+    wrapText(measure, text, contentW),
+    maxLines,
+    contentW
+  );
+  const blockH = lines.length * lineHeightPx;
+  const top = style.valign === "top" ? paddingPx : style.valign === "bottom" ? pxHeight - paddingPx - blockH : (pxHeight - blockH) / 2;
+  const anchorX = style.align === "left" ? paddingPx : style.align === "right" ? pxWidth - paddingPx : pxWidth / 2;
+  ctx.save();
+  tracePath(ctx, 0, 0, pxWidth, pxHeight, 0);
+  ctx.clip();
+  ctx.fillStyle = style.color;
+  ctx.textAlign = style.align;
+  ctx.textBaseline = "middle";
+  for (let i = 0; i < lines.length; i += 1) {
+    ctx.fillText(lines[i], anchorX, top + (i + 0.5) * lineHeightPx);
+  }
+  ctx.restore();
+}
+__name(drawTextBlock, "drawTextBlock");
+function panelSignature(widthM, heightM, size, style) {
+  return JSON.stringify([
+    widthM,
+    heightM,
+    size.pxWidth,
+    size.pxHeight,
+    style.backgroundColor,
+    style.backgroundOpacity,
+    style.cornerRadiusMeters,
+    style.borderWidthMeters,
+    style.borderColor
+  ]);
+}
+__name(panelSignature, "panelSignature");
+function textSignature(widthM, heightM, size, text, style) {
+  return JSON.stringify([
+    widthM,
+    heightM,
+    size.pxWidth,
+    size.pxHeight,
+    text,
+    style.fontSizeMeters,
+    style.fontWeight,
+    style.color,
+    style.align,
+    style.valign,
+    style.lineHeight,
+    style.paddingMeters
+  ]);
+}
+__name(textSignature, "textSignature");
+function buttonSignature(widthM, heightM, size, panel, label, text) {
+  return JSON.stringify([
+    panelSignature(widthM, heightM, size, panel),
+    label,
+    text.fontSizeMeters,
+    text.fontWeight,
+    text.color
+  ]);
+}
+__name(buttonSignature, "buttonSignature");
+function trackSignature(widthM, heightM, size, panel, accentColor, knobColor) {
+  return JSON.stringify([
+    panelSignature(widthM, heightM, size, panel),
+    accentColor,
+    knobColor
+  ]);
+}
+__name(trackSignature, "trackSignature");
+function drawRoundedBar(ctx, pxX, pxY, pxW, pxH, color) {
+  tracePath(ctx, pxX, pxY, pxW, pxH, pxH / 2);
+  ctx.fillStyle = color;
+  ctx.fill();
+}
+__name(drawRoundedBar, "drawRoundedBar");
+
+// core/systems/UIPanelSystem.ts
+var FACE_RENDER_ORDER = 10;
+var CHILD_Z = 2e-3;
+var _UIPanelSystem = class _UIPanelSystem {
+  constructor(options) {
+    this.entries = /* @__PURE__ */ new Map();
+    this.createCanvas = options?.createCanvas ?? (() => document.createElement("canvas"));
+  }
+  update(world, deltaTime = 0) {
+    const live = /* @__PURE__ */ new Set();
+    for (const entityId of world.query(UIPanelComponent, Object3DRef)) {
+      const panel = world.getComponent(entityId, UIPanelComponent);
+      if (!panel) continue;
+      live.add(entityId);
+      this.syncPanel(world, entityId, panel);
+      this.applyFollow(world, entityId, panel);
+    }
+    for (const entityId of world.query(UITextComponent, Object3DRef)) {
+      const text = world.getComponent(entityId, UITextComponent);
+      if (!text) continue;
+      live.add(entityId);
+      this.syncText(world, entityId, text);
+    }
+    for (const entityId of world.query(UIButtonComponent, Object3DRef)) {
+      const button = world.getComponent(entityId, UIButtonComponent);
+      if (!button) continue;
+      live.add(entityId);
+      this.syncButton(world, entityId, button);
+    }
+    for (const entityId of world.query(UIToggleComponent, Object3DRef)) {
+      const toggle = world.getComponent(entityId, UIToggleComponent);
+      if (!toggle) continue;
+      live.add(entityId);
+      this.syncToggle(world, entityId, toggle, deltaTime);
+    }
+    for (const entityId of world.query(UISliderComponent, Object3DRef)) {
+      const slider = world.getComponent(entityId, UISliderComponent);
+      if (!slider) continue;
+      live.add(entityId);
+      this.syncSlider(world, entityId, slider);
+    }
+    for (const [entityId, entry] of this.entries) {
+      if (!live.has(entityId)) {
+        this.destroyEntry(entry);
+        this.entries.delete(entityId);
+      }
+    }
+  }
+  /** All GPU/canvas resources; call on world teardown. */
+  dispose() {
+    for (const entry of this.entries.values()) this.destroyEntry(entry);
+    this.entries.clear();
+  }
+  // ── Widgets ────────────────────────────────────────────────────────────────
+  syncPanel(world, entityId, panel) {
+    const size = resolveCanvasSize(panel.width, panel.height, panel.pixelDensity);
+    const style = {
+      backgroundColor: panel.backgroundColor,
+      backgroundOpacity: panel.backgroundOpacity,
+      cornerRadiusMeters: panel.cornerRadius,
+      borderWidthMeters: panel.borderWidth,
+      borderColor: panel.borderColor
+    };
+    const signature = panelSignature(panel.width, panel.height, size, style);
+    this.rebuildIfChanged(world, entityId, signature, panel.width, panel.height, size, (ctx) => {
+      drawChrome(ctx, size.pxWidth, size.pxHeight, size.density, style);
+    });
+  }
+  syncText(world, entityId, text) {
+    const size = resolveCanvasSize(text.width, text.height);
+    const style = {
+      fontSizeMeters: text.fontSize,
+      fontWeight: text.fontWeight,
+      color: text.color,
+      align: text.align,
+      valign: text.valign,
+      lineHeight: text.lineHeight,
+      paddingMeters: text.padding
+    };
+    const signature = textSignature(text.width, text.height, size, text.text, style);
+    this.rebuildIfChanged(world, entityId, signature, text.width, text.height, size, (ctx) => {
+      ctx.clearRect(0, 0, size.pxWidth, size.pxHeight);
+      drawTextBlock(ctx, size.pxWidth, size.pxHeight, size.density, text.text, style);
+    });
+  }
+  syncButton(world, entityId, button) {
+    const size = resolveCanvasSize(button.width, button.height);
+    const chrome = {
+      backgroundColor: button.backgroundColor,
+      backgroundOpacity: button.backgroundOpacity,
+      cornerRadiusMeters: button.cornerRadius,
+      borderWidthMeters: button.borderWidth,
+      borderColor: button.borderColor
+    };
+    const label = {
+      fontSizeMeters: button.fontSize,
+      fontWeight: button.fontWeight,
+      color: button.textColor,
+      align: "center",
+      valign: "middle",
+      lineHeight: 1.2,
+      paddingMeters: 0.01
+    };
+    const signature = buttonSignature(
+      button.width,
+      button.height,
+      size,
+      chrome,
+      button.label,
+      label
+    );
+    this.rebuildIfChanged(world, entityId, signature, button.width, button.height, size, (ctx) => {
+      drawChrome(ctx, size.pxWidth, size.pxHeight, size.density, chrome);
+      drawTextBlock(ctx, size.pxWidth, size.pxHeight, size.density, button.label, label);
+    });
+  }
+  syncToggle(world, entityId, toggle, deltaTime) {
+    const size = resolveCanvasSize(toggle.width, toggle.height);
+    const chrome = {
+      backgroundColor: toggle.value ? toggle.accentColor : toggle.trackColor,
+      backgroundOpacity: 1,
+      cornerRadiusMeters: toggle.height / 2,
+      borderWidthMeters: 0,
+      borderColor: "#000000"
+    };
+    const signature = JSON.stringify([
+      trackSignature(
+        toggle.width,
+        toggle.height,
+        size,
+        chrome,
+        toggle.accentColor,
+        toggle.knobColor
+      ),
+      toggle.value
+    ]);
+    const entry = this.rebuildIfChanged(
+      world,
+      entityId,
+      signature,
+      toggle.width,
+      toggle.height,
+      size,
+      (ctx) => {
+        drawChrome(ctx, size.pxWidth, size.pxHeight, size.density, chrome);
+      }
+    );
+    if (!entry) return;
+    if (!entry.knob) {
+      entry.knob = this.makeDisc(
+        toggle.height * 0.4,
+        toggle.knobColor,
+        entry.face.parent,
+        CHILD_Z
+      );
+    }
+    const inset = toggle.height / 2;
+    const target = toggle.value ? toggle.width / 2 - inset : -(toggle.width / 2 - inset);
+    const knob = entry.knob;
+    const ease = Math.min(1, deltaTime * 14);
+    knob.position.x += (target - knob.position.x) * (deltaTime > 0 ? ease : 1);
+    knob.position.z = CHILD_Z;
+  }
+  syncSlider(world, entityId, slider) {
+    const size = resolveCanvasSize(slider.width, slider.height);
+    const trackThickness = slider.height * 0.32;
+    const knobRadius = slider.height * 0.45;
+    const usable = Math.max(1e-3, slider.width - slider.height);
+    const chrome = {
+      backgroundColor: slider.trackColor,
+      backgroundOpacity: 1,
+      cornerRadiusMeters: trackThickness / 2,
+      borderWidthMeters: 0,
+      borderColor: "#000000"
+    };
+    const signature = trackSignature(
+      slider.width,
+      slider.height,
+      size,
+      chrome,
+      slider.accentColor,
+      slider.knobColor
+    );
+    const entry = this.rebuildIfChanged(
+      world,
+      entityId,
+      signature,
+      slider.width,
+      slider.height,
+      size,
+      (ctx) => {
+        ctx.clearRect(0, 0, size.pxWidth, size.pxHeight);
+        const trackWidthM = usable + trackThickness;
+        drawRoundedBar(
+          ctx,
+          (slider.width - trackWidthM) / 2 * size.density,
+          (slider.height - trackThickness) / 2 * size.density,
+          trackWidthM * size.density,
+          trackThickness * size.density,
+          slider.trackColor
+        );
+      }
+    );
+    if (!entry) return;
+    if (!entry.fill) {
+      entry.fill = this.makeQuad(
+        1,
+        trackThickness,
+        slider.accentColor,
+        entry.face.parent,
+        CHILD_Z / 2
+      );
+      entry.cap = this.makeDisc(
+        trackThickness / 2,
+        slider.accentColor,
+        entry.face.parent,
+        CHILD_Z / 2,
+        Math.PI / 2,
+        Math.PI
+      );
+      entry.cap.position.x = -usable / 2;
+    }
+    if (!entry.knob) {
+      entry.knob = this.makeDisc(
+        knobRadius,
+        slider.knobColor,
+        entry.face.parent,
+        CHILD_Z
+      );
+    }
+    const range = Math.max(1e-6, slider.max - slider.min);
+    const t = Math.min(1, Math.max(0, (slider.value - slider.min) / range));
+    entry.knob.position.x = -usable / 2 + t * usable;
+    entry.knob.position.z = CHILD_Z;
+    entry.fill.scale.x = Math.max(1e-4, t * usable);
+    entry.fill.position.x = -usable / 2 + t * usable / 2;
+    entry.fill.position.z = CHILD_Z / 2;
+  }
+  // ── Machinery ──────────────────────────────────────────────────────────────
+  rebuildIfChanged(world, entityId, signature, widthM, heightM, size, draw) {
+    const root = world.getComponent(entityId, Object3DRef)?.object;
+    if (!root) return null;
+    let entry = this.entries.get(entityId);
+    if (entry && entry.signature === signature) return entry;
+    if (entry) this.disposeMovingParts(entry);
+    if (!entry) {
+      const canvas2 = this.createCanvas();
+      const texture = new THREE26__namespace.CanvasTexture(
+        canvas2
+      );
+      this.configureTexture(world, texture);
+      const material = new THREE26__namespace.MeshBasicMaterial({
+        map: texture,
+        transparent: true,
+        depthWrite: false,
+        // UI colours are authored absolutes; scene tone mapping would shift
+        // them (the classic "why is my white UI beige" bug).
+        toneMapped: false,
+        side: THREE26__namespace.DoubleSide,
+        premultipliedAlpha: true
+      });
+      const face = new THREE26__namespace.Mesh(
+        new THREE26__namespace.PlaneGeometry(widthM, heightM),
+        material
+      );
+      face.renderOrder = FACE_RENDER_ORDER;
+      root.add(face);
+      entry = {
+        signature: "",
+        face,
+        texture,
+        material,
+        canvas: canvas2,
+        knob: null,
+        fill: null,
+        cap: null
+      };
+      this.entries.set(entityId, entry);
+    }
+    const { canvas } = entry;
+    if (canvas.width !== size.pxWidth || canvas.height !== size.pxHeight) {
+      canvas.width = size.pxWidth;
+      canvas.height = size.pxHeight;
+    }
+    const params = entry.face.geometry.parameters;
+    if (params.width !== widthM || params.height !== heightM) {
+      entry.face.geometry.dispose();
+      entry.face.geometry = new THREE26__namespace.PlaneGeometry(widthM, heightM);
+    }
+    const ctx = canvas.getContext("2d");
+    if (ctx) draw(ctx);
+    entry.texture.needsUpdate = true;
+    entry.signature = signature;
+    return entry;
+  }
+  configureTexture(world, texture) {
+    texture.colorSpace = THREE26__namespace.SRGBColorSpace;
+    texture.generateMipmaps = true;
+    texture.minFilter = THREE26__namespace.LinearMipmapLinearFilter;
+    texture.magFilter = THREE26__namespace.LinearFilter;
+    texture.premultiplyAlpha = true;
+    try {
+      const max = world.getRenderer().capabilities?.getMaxAnisotropy?.();
+      if (typeof max === "number") texture.anisotropy = Math.min(8, max);
+    } catch {
+    }
+  }
+  makeQuad(widthM, heightM, color, parent, z) {
+    return this.addPart(
+      new THREE26__namespace.PlaneGeometry(widthM, heightM),
+      color,
+      parent,
+      z
+    );
+  }
+  /** A filled disc (or arc segment, for the fill's rounded cap). */
+  makeDisc(radiusM, color, parent, z, thetaStart = 0, thetaLength = Math.PI * 2) {
+    return this.addPart(
+      new THREE26__namespace.CircleGeometry(radiusM, 32, thetaStart, thetaLength),
+      color,
+      parent,
+      z
+    );
+  }
+  addPart(geometry, color, parent, z) {
+    const mesh = new THREE26__namespace.Mesh(
+      geometry,
+      new THREE26__namespace.MeshBasicMaterial({
+        color,
+        transparent: true,
+        depthWrite: false,
+        toneMapped: false,
+        side: THREE26__namespace.DoubleSide
+      })
+    );
+    mesh.renderOrder = FACE_RENDER_ORDER + 1;
+    mesh.position.z = z;
+    mesh.raycast = () => {
+    };
+    parent?.add(mesh);
+    return mesh;
+  }
+  /** Remove + dispose knob/fill/cap so a sync pass rebuilds them fresh. */
+  disposeMovingParts(entry) {
+    for (const key of ["knob", "fill", "cap"]) {
+      const mesh = entry[key];
+      if (!mesh) continue;
+      mesh.removeFromParent();
+      mesh.geometry.dispose();
+      mesh.material.dispose();
+      entry[key] = null;
+    }
+  }
+  /**
+   * 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.
+   */
+  applyFollow(world, entityId, panel) {
+    if (panel.follow !== "billboard" || world.isEditorMode()) return;
+    const transform = world.getComponent(entityId, TransformComponent);
+    const object = world.getComponent(entityId, Object3DRef)?.object;
+    if (!transform || !object) return;
+    const camera = world.getCamera();
+    const cam = new THREE26__namespace.Vector3();
+    const self = new THREE26__namespace.Vector3();
+    camera.getWorldPosition(cam);
+    object.getWorldPosition(self);
+    transform.rotation.y = Math.atan2(cam.x - self.x, cam.z - self.z);
+  }
+  destroyEntry(entry) {
+    this.disposeMovingParts(entry);
+    entry.face.removeFromParent();
+    entry.face.geometry.dispose();
+    entry.face.material.dispose();
+    entry.texture.dispose();
+  }
+};
+__name(_UIPanelSystem, "UIPanelSystem");
+var UIPanelSystem = _UIPanelSystem;
 var _XRHitTestSystem = class _XRHitTestSystem {
   constructor() {
     this.sources = /* @__PURE__ */ new Map();
@@ -10193,9 +11606,13 @@ var _XRAnchorSystem = class _XRAnchorSystem {
     this.anchors = /* @__PURE__ */ new Map();
     /** In-flight creations, so one entity is not anchored twice. */
     this.pending = /* @__PURE__ */ new Set();
+    /** Per-anchor head-glue gates — see XREnvironmentSystem's TrackedEntry. */
+    this.gates = /* @__PURE__ */ new Map();
     this.presenting = false;
+    this.tmpViewerMatrix = new THREE26__namespace.Matrix4();
+    this.tmpViewPos = new THREE26__namespace.Vector3();
   }
-  update(world) {
+  update(world, deltaTime = 0) {
     const presenting = world.isXrPresenting();
     if (!presenting) {
       if (this.presenting) {
@@ -10215,8 +11632,11 @@ var _XRAnchorSystem = class _XRAnchorSystem {
       if (!live.has(entityId)) {
         anchor.delete?.();
         this.anchors.delete(entityId);
+        this.gates.delete(entityId);
       }
     }
+    const viewer = frame.getViewerPose?.(referenceSpace);
+    const viewerInverse = viewer ? this.tmpViewerMatrix.fromArray(viewer.transform.matrix).invert() : null;
     for (const entityId of entityIds) {
       const component = world.getComponent(entityId, XRAnchorComponent);
       const transform = world.getComponent(entityId, TransformComponent);
@@ -10226,6 +11646,7 @@ var _XRAnchorSystem = class _XRAnchorSystem {
         if (existing) {
           existing.delete?.();
           this.anchors.delete(entityId);
+          this.gates.delete(entityId);
         }
         continue;
       }
@@ -10235,7 +11656,23 @@ var _XRAnchorSystem = class _XRAnchorSystem {
         continue;
       }
       const pose = frame.getPose(anchor.anchorSpace, referenceSpace);
-      if (pose) decomposeXrPose(pose.transform.matrix, transform);
+      if (pose && pose.emulatedPosition !== true) {
+        let gate = this.gates.get(entityId);
+        if (!gate) {
+          gate = new SurfacePoseGate();
+          this.gates.set(entityId, gate);
+        }
+        const m = pose.transform.matrix;
+        const refPos = { x: m[12], y: m[13], z: m[14] };
+        let viewPos = null;
+        if (viewerInverse) {
+          const v = this.tmpViewPos.set(refPos.x, refPos.y, refPos.z).applyMatrix4(viewerInverse);
+          viewPos = { x: v.x, y: v.y, z: v.z };
+        }
+        if (gate.update(refPos, viewPos, deltaTime)) {
+          decomposeXrPose(pose.transform.matrix, transform);
+        }
+      }
     }
   }
   /** Whether this entity's pose is currently being driven by an anchor. */
@@ -10279,6 +11716,7 @@ var _XRAnchorSystem = class _XRAnchorSystem {
     }).finally(() => this.pending.delete(entityId));
   }
   releaseAll() {
+    this.gates.clear();
     for (const anchor of this.anchors.values()) anchor.delete?.();
     this.anchors.clear();
     this.pending.clear();
@@ -11543,6 +12981,8 @@ exports.SCRIPT_OBJECT_ROOT_FLAG = SCRIPT_OBJECT_ROOT_FLAG;
 exports.ScriptBehaviourSystem = ScriptBehaviourSystem;
 exports.ScriptObjectSystem = ScriptObjectSystem;
 exports.TransformSyncSystem = TransformSyncSystem;
+exports.UIInteractionSystem = UIInteractionSystem;
+exports.UIPanelSystem = UIPanelSystem;
 exports.VRTeleportAreaSystem = VRTeleportAreaSystem;
 exports.VideoSystem = VideoSystem;
 exports.XRAnchorSystem = XRAnchorSystem;