@relu-interactives/spatial-ecs 0.4.5 → 0.5.1

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) {
@@ -9819,6 +9998,88 @@ 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) {
@@ -9842,6 +10103,11 @@ function debugColorFor(kind, semanticLabel) {
 }
 __name(debugColorFor, "debugColorFor");
 var GLOBAL_MESH_DEBUG_OPACITY = 0.35;
+var GLOBAL_MESH_SWITCH_MARGIN = 1.5;
+function isGlobalMeshSurface(mesh) {
+  return (mesh.semanticLabel ?? null) === "global mesh";
+}
+__name(isGlobalMeshSurface, "isGlobalMeshSurface");
 var DEBUG_RENDER_ORDER = 900;
 var ROOM_CAPTURE_DELAY_SECONDS = 3;
 var SYNTHETIC_FLOOR_EXTENT = 50;
@@ -9862,12 +10128,30 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     /** 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 frame's viewer position in reference space, for room election. */
+    this.viewerPos = null;
+    /** The ONE global room mesh currently allowed to spawn. */
+    this.electedGlobalMesh = null;
+    this.tmpViewerMatrix = new THREE26__namespace.Matrix4();
+    this.tmpViewPos = new THREE26__namespace.Vector3();
   }
   update(world, deltaTime = 0) {
     const presenting = world.isXrPresenting();
@@ -9905,13 +10189,22 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     const meshesAvailable = Boolean(frame.detectedMeshes);
     const useMesh = (mode === "mesh" || mode === "auto") && meshesAvailable;
     const usePlanes = mode === "planes" || mode === "auto" && !useMesh;
+    const viewer = frame.getViewerPose?.(referenceSpace);
+    if (viewer) {
+      const vm = viewer.transform.matrix;
+      this.viewerPos = { x: vm[12], y: vm[13], z: vm[14] };
+      this.viewerInverse = this.tmpViewerMatrix.fromArray(vm).invert();
+    } else {
+      this.viewerPos = null;
+      this.viewerInverse = 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);
     }
@@ -9998,7 +10291,7 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     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) {
@@ -10007,6 +10300,9 @@ 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;
@@ -10015,8 +10311,11 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       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) {
@@ -10036,11 +10335,12 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
           }
         }
       }
-      entry.emulated = emulated;
-      if (!emulated) 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) {
@@ -10049,7 +10349,20 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
         this.meshes.delete(mesh);
       }
     }
+    for (const mesh of this.pendingMeshes.keys()) {
+      if (!detected.has(mesh)) this.pendingMeshes.delete(mesh);
+    }
+    const electedGlobal = this.electGlobalMesh(frame, detected, referenceSpace);
     for (const mesh of detected) {
+      if (isGlobalMeshSurface(mesh) && mesh !== electedGlobal) {
+        const stale = this.meshes.get(mesh);
+        if (stale) {
+          this.destroyEntry(world, stale);
+          this.meshes.delete(mesh);
+        }
+        this.pendingMeshes.delete(mesh);
+        continue;
+      }
       const pose = frame.getPose(mesh.meshSpace, referenceSpace);
       if (!pose) continue;
       const emulated = pose.emulatedPosition === true;
@@ -10057,17 +10370,95 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       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);
       }
-      entry.emulated = emulated;
-      if (!emulated) 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);
+    }
+  }
+  /**
+   * Pick THE room's global mesh: the one whose scan origin is nearest the
+   * viewer, sticky to the current choice within a margin so origin jitter
+   * can't flap the room. Without a viewer pose (or with a single candidate)
+   * the first candidate stands; ties are impossible to break anyway.
+   */
+  electGlobalMesh(frame, detected, referenceSpace) {
+    let nearest = null;
+    let nearestDist = Number.POSITIVE_INFINITY;
+    let currentDist = Number.POSITIVE_INFINITY;
+    let currentStillDetected = false;
+    for (const mesh of detected) {
+      if (!isGlobalMeshSurface(mesh)) continue;
+      if (!this.viewerPos) {
+        return this.electedGlobalMesh && detected.has(this.electedGlobalMesh) ? this.electedGlobalMesh : mesh;
+      }
+      const pose = frame.getPose(mesh.meshSpace, referenceSpace);
+      if (!pose) continue;
+      const m = pose.transform.matrix;
+      const d = Math.hypot(
+        m[12] - this.viewerPos.x,
+        m[13] - this.viewerPos.y,
+        m[14] - this.viewerPos.z
+      );
+      if (mesh === this.electedGlobalMesh) {
+        currentDist = d;
+        currentStillDetected = true;
+      }
+      if (d < nearestDist) {
+        nearestDist = d;
+        nearest = mesh;
+      }
+    }
+    if (currentStillDetected && currentDist < nearestDist + GLOBAL_MESH_SWITCH_MARGIN) {
+      return this.electedGlobalMesh;
+    }
+    this.electedGlobalMesh = nearest;
+    return nearest;
+  }
+  /**
+   * 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);
@@ -10087,7 +10478,8 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       lastChangedTime: plane.lastChangedTime ?? 0,
       geometry: null,
       material: null,
-      emulated: false
+      emulated: false,
+      gate: new SurfacePoseGate()
     };
     if (this.debugVisible) {
       this.attachPlaneDebug(world, entry, collider, plane.semanticLabel ?? null);
@@ -10160,7 +10552,8 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       lastChangedTime: mesh.lastChangedTime ?? 0,
       geometry,
       material,
-      emulated: false
+      emulated: false,
+      gate: new SurfacePoseGate()
     };
   }
   /** A thin box so a detected plane can be SEEN, not just collided with. */
@@ -10241,6 +10634,9 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
   clearAll(world) {
     this.clearMap(world, this.planes);
     this.clearMap(world, this.meshes);
+    this.pendingPlanes.clear();
+    this.pendingMeshes.clear();
+    this.electedGlobalMesh = null;
   }
   dispose(world) {
     this.clearAll(world);
@@ -10252,6 +10648,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();
@@ -10364,9 +11672,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) {
@@ -10386,8 +11698,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);
@@ -10397,6 +11712,7 @@ var _XRAnchorSystem = class _XRAnchorSystem {
         if (existing) {
           existing.delete?.();
           this.anchors.delete(entityId);
+          this.gates.delete(entityId);
         }
         continue;
       }
@@ -10407,7 +11723,21 @@ var _XRAnchorSystem = class _XRAnchorSystem {
       }
       const pose = frame.getPose(anchor.anchorSpace, referenceSpace);
       if (pose && pose.emulatedPosition !== true) {
-        decomposeXrPose(pose.transform.matrix, transform);
+        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);
+        }
       }
     }
   }
@@ -10452,6 +11782,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();
@@ -11716,6 +13047,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;