@webspatial/react-sdk 1.3.0 → 1.5.0

package/dist/web/index.js

@@ -2,7 +2,7 @@
       (function(){
         if(typeof window === 'undefined') return;
         if(!window.__webspatialsdk__) window.__webspatialsdk__ = {}
-        window.__webspatialsdk__['react-sdk-version'] = "1.3.0"
+        window.__webspatialsdk__['react-sdk-version'] = "1.5.0"
         window.__webspatialsdk__['XR_ENV'] = "web"
     })()
       
@@ -170,18 +170,12 @@ var SpatialContainerRefProxy = class {
             if (prop === "__raw") {
               return target;
             }
-            if (prop === "clientDepth") {
+            if (prop === "xrClientDepth") {
               return target.style.getPropertyValue(SpatialCustomStyleVars.depth);
             }
-            if (prop === "offsetBack") {
+            if (prop === "xrOffsetBack") {
               return target.style.getPropertyValue(SpatialCustomStyleVars.back);
             }
-            if (prop === "getBoundingClientRect") {
-              return dom.__getBoundingClientRect;
-            }
-            if (prop === "getBoundingClientCube") {
-              return dom.__getBoundingClientCube;
-            }
             if (prop === "style") {
               if (!self.styleProxy) {
                 self.styleProxy = new Proxy(target.style, {
@@ -893,6 +887,20 @@ var Spatial = class {
 function isSSREnv() {
   return false;
 }
+var PhysicalMetrics = {
+  pointToPhysical: (point, options) => {
+    return point / 1360;
+  },
+  physicalToPoint: (physical, options) => {
+    return physical * 1360;
+  },
+  getValue: () => ({
+    meterToPtUnscaled: 1360,
+    meterToPtScaled: 1360
+  }),
+  subscribe: (cb) => {
+  }
+};
 
 // src/utils/getSession.ts
 var spatial = null;
@@ -938,37 +946,6 @@ function enableDebugTool() {
   });
 }
 
-// src/spatialized-container/transform-utils.ts
-function toSceneSpatial(point, spatializedElement) {
-  return spatializedElement.__toSceneSpace(point);
-}
-function toLocalSpace(point, spatializedElement) {
-  return spatializedElement.__toLocalSpace(point);
-}
-function convertDOMRectToSceneSpace(originalRect, matrix) {
-  const topLeft = new DOMPoint(originalRect.left, originalRect.top);
-  const topRight = new DOMPoint(originalRect.right, originalRect.top);
-  const bottomRight = new DOMPoint(originalRect.right, originalRect.bottom);
-  const bottomLeft = new DOMPoint(originalRect.left, originalRect.bottom);
-  const transformedTopLeft = matrix.transformPoint(topLeft);
-  const transformedTopRight = matrix.transformPoint(topRight);
-  const transformedBottomRight = matrix.transformPoint(bottomRight);
-  const transformedBottomLeft = matrix.transformPoint(bottomLeft);
-  const allPoints = [
-    transformedTopLeft,
-    transformedTopRight,
-    transformedBottomRight,
-    transformedBottomLeft
-  ];
-  const xCoords = allPoints.map((point) => point.x);
-  const yCoords = allPoints.map((point) => point.y);
-  const newMinX = Math.min(...xCoords);
-  const newMaxX = Math.max(...xCoords);
-  const newMinY = Math.min(...yCoords);
-  const newMaxY = Math.max(...yCoords);
-  return new DOMRect(newMinX, newMinY, newMaxX - newMinX, newMaxY - newMinY);
-}
-
 // src/spatialized-container/context/PortalInstanceContext.ts
 var PortalInstanceObject = class {
   spatialId;
@@ -1053,40 +1030,8 @@ var PortalInstanceObject = class {
       isFixedPosition: computedStyle.getPropertyValue("position") === "fixed"
     };
     this.updateSpatializedElementProperties();
-    const __getBoundingClientCube = () => {
-      return this.spatializedElement?.cubeInfo;
-    };
-    const __getBoundingClientRect = () => {
-      if (!this.spatializedElement?.transform) {
-        return null;
-      }
-      const domRect = new DOMRect(
-        0,
-        0,
-        this.domRect?.width,
-        this.domRect?.height
-      );
-      return convertDOMRectToSceneSpace(
-        domRect,
-        this.spatializedElement?.transform
-      );
-    };
-    const __toSceneSpace = (point) => {
-      return new DOMPoint(point.x, point.y, point.z).matrixTransform(
-        this.spatializedElement?.transform
-      );
-    };
-    const __toLocalSpace = (point) => {
-      return new DOMPoint(point.x, point.y, point.z).matrixTransform(
-        this.spatializedElement?.transformInv
-      );
-    };
     const __innerSpatializedElement = () => this.spatializedElement;
     Object.assign(dom, {
-      __getBoundingClientCube,
-      __getBoundingClientRect,
-      __toSceneSpace,
-      __toLocalSpace,
       __innerSpatializedElement
     });
   }
@@ -1204,18 +1149,19 @@ function useSync2DFrame(spatialId, portalInstanceObject, spatializedContainerObj
 }
 
 // src/spatialized-container/hooks/useSpatializedElement.ts
-import { useEffect as useEffect6, useState as useState3 } from "react";
+import { useEffect as useEffect6, useRef as useRef4, useState as useState3 } from "react";
 function useSpatializedElement(createSpatializedElement2, portalInstanceObject) {
   const [spatializedElement, setSpatializedElement] = useState3();
+  const elementRef = useRef4(void 0);
   useEffect6(() => {
     let isDestroyed = false;
-    let spatializedElement2;
     createSpatializedElement2().then(
       (inSpatializedElement) => {
+        if (!inSpatializedElement) return;
         if (!isDestroyed) {
-          spatializedElement2 = inSpatializedElement;
-          portalInstanceObject.attachSpatializedElement(spatializedElement2);
-          setSpatializedElement(spatializedElement2);
+          elementRef.current = inSpatializedElement;
+          portalInstanceObject.attachSpatializedElement(inSpatializedElement);
+          setSpatializedElement(inSpatializedElement);
         } else {
           inSpatializedElement?.destroy();
         }
@@ -1223,9 +1169,11 @@ function useSpatializedElement(createSpatializedElement2, portalInstanceObject)
     );
     return () => {
       isDestroyed = true;
-      if (spatializedElement2) {
-        spatializedElement2.destroy();
-        spatializedElement2 = void 0;
+      const el = elementRef.current;
+      if (el) {
+        el.destroy();
+        elementRef.current = void 0;
+        setSpatializedElement(void 0);
       }
     };
   }, [createSpatializedElement2, portalInstanceObject]);
@@ -1234,6 +1182,18 @@ function useSpatializedElement(createSpatializedElement2, portalInstanceObject)
 
 // src/spatialized-container/PortalSpatializedContainer.tsx
 import { Fragment, jsx as jsx3, jsxs } from "react/jsx-runtime";
+function constrainedAxisToVec3(input) {
+  if (input == null) return { x: 0, y: 0, z: 0 };
+  if (Array.isArray(input)) {
+    return { x: input[0] ?? 0, y: input[1] ?? 0, z: input[2] ?? 0 };
+  }
+  const v = input;
+  return { x: v.x, y: v.y, z: v.z };
+}
+function constrainedAxisKey(input) {
+  const v = constrainedAxisToVec3(input);
+  return `${v.x},${v.y},${v.z}`;
+}
 function renderPlaceholderInSubPortal(portalInstanceObject, El) {
   const spatialId = portalInstanceObject.spatialId;
   const inPortalInstanceEnv = !!portalInstanceObject.parentPortalInstanceObject;
@@ -1272,6 +1232,7 @@ function PortalSpatializedContainer(props) {
     onSpatialRotateEnd,
     onSpatialMagnify,
     onSpatialMagnifyEnd,
+    spatialEventOptions,
     [SpatialID]: spatialId,
     ...restProps
   } = props;
@@ -1343,6 +1304,14 @@ function PortalSpatializedContainer(props) {
       spatializedElement.onSpatialDragStart = onSpatialDragStart;
     }
   }, [spatializedElement, onSpatialDragStart]);
+  const rotateConstraintKey = constrainedAxisKey(
+    spatialEventOptions?.constrainedToAxis
+  );
+  useEffect7(() => {
+    if (!spatializedElement) return;
+    const axis = constrainedAxisToVec3(spatialEventOptions?.constrainedToAxis);
+    void spatializedElement.updateProperties({ rotateConstrainedToAxis: axis });
+  }, [spatializedElement, rotateConstraintKey]);
   return /* @__PURE__ */ jsxs(PortalInstanceContext.Provider, { value: portalInstanceObject, children: [
     spatializedElement && portalInstanceObject.dom && /* @__PURE__ */ jsx3(Content, { spatializedElement, ...restProps }),
     PlaceholderEl
@@ -1602,6 +1571,7 @@ function DegradedContainer({
     onSpatialRotateEnd: _onSpatialRotateEnd,
     onSpatialMagnify: _onSpatialMagnify,
     onSpatialMagnifyEnd: _onSpatialMagnifyEnd,
+    spatialEventOptions: _spatialEventOptions,
     spatializedContent: _content,
     createSpatializedElement: _create,
     getExtraSpatializedElementProperties: _getExtra,
@@ -1688,6 +1658,7 @@ function SpatializedContainerBase(inprops, ref) {
         spatializedContent,
         createSpatializedElement: createSpatializedElement2,
         getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
+        spatialEventOptions: _nestedSpatialEventOptions,
         ...restProps
       } = props;
       return /* @__PURE__ */ jsxs2(SpatialLayerContext.Provider, { value: layer, children: [
@@ -1738,6 +1709,7 @@ function SpatializedContainerBase(inprops, ref) {
       spatializedContent,
       createSpatializedElement: createSpatializedElement2,
       getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
+      spatialEventOptions: _rootSpatialEventOptions,
       ...restProps
     } = props;
     return /* @__PURE__ */ jsx6(SpatialLayerContext.Provider, { value: layer, children: /* @__PURE__ */ jsxs2(
@@ -2052,7 +2024,7 @@ import {
   useContext as useContext9,
   useEffect as useEffect13,
   useMemo as useMemo3,
-  useRef as useRef4
+  useRef as useRef5
 } from "react";
 import { Fragment as Fragment2, jsx as jsx8 } from "react/jsx-runtime";
 function getAbsoluteURL(url) {
@@ -2127,7 +2099,7 @@ function SpatializedContent2(props) {
   return /* @__PURE__ */ jsx8(Fragment2, {});
 }
 function SpatializedStatic3DElementContainerBase(props, ref) {
-  const promiseRef = useRef4(null);
+  const promiseRef = useRef5(null);
   const createSpatializedElement2 = useCallback6(() => {
     const url = getAbsoluteURL(props.src);
     promiseRef.current = getSession().createSpatializedStatic3DElement(url);
@@ -2223,9 +2195,9 @@ function initScene(name, callback) {
 import { forwardRef as forwardRef9 } from "react";
 
 // src/spatialized-container-monitor/useMonitorDomChange.tsx
-import { useRef as useRef5, useEffect as useEffect14, useMemo as useMemo4 } from "react";
+import { useRef as useRef6, useEffect as useEffect14, useMemo as useMemo4 } from "react";
 function useMonitorDomChange(inRef) {
-  const ref = useRef5(null);
+  const ref = useRef6(null);
   useEffect14(() => {
     const observer = new MutationObserver((mutationsList) => {
       notifyDOMUpdate(mutationsList);
@@ -2355,7 +2327,11 @@ var AttachmentRegistry = class {
   }
   getContainers(name) {
     const map = this.containers.get(name);
-    return map ? Array.from(map.values()) : [];
+    if (!map) return [];
+    return Array.from(map, ([instanceId, container]) => ({
+      instanceId,
+      container
+    }));
   }
   onContainersChange(name, cb) {
     const current = this.getContainers(name);
@@ -2383,7 +2359,7 @@ var AttachmentRegistry = class {
 var AttachmentContext = createContext8(null);
 
 // src/reality/hooks/useEntityTransform.tsx
-import { useEffect as useEffect16, useRef as useRef6 } from "react";
+import { useEffect as useEffect16, useRef as useRef7 } from "react";
 
 // src/reality/utils/ResourceRegistry.ts
 var ResourceRegistry = class {
@@ -2428,6 +2404,20 @@ function shallowEqualRotation(a, b) {
   if (!a || !b) return false;
   return a.x === b.x && a.y === b.y && a.z === b.z && ("w" in a ? a.w === b.w : true);
 }
+function shallowEqualObject(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((key) => a[key] === b[key]);
+}
+function shallowEqualArray(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.length !== b.length) return false;
+  return a.every((val, i) => val === b[i]);
+}
 
 // src/reality/utils/AbortResourceManager.ts
 var AbortResourceManager = class {
@@ -2464,7 +2454,7 @@ var AbortResourceManager = class {
 
 // src/reality/hooks/useEntityTransform.tsx
 function useEntityTransform(entity, { position, rotation, scale }) {
-  const last = useRef6({});
+  const last = useRef7({});
   useEffect16(() => {
     if (!entity) return;
     const shouldUpdate = !shallowEqualVec3(last.current.position, position) || !shallowEqualRotation(last.current.rotation, rotation) || !shallowEqualVec3(last.current.scale, scale);
@@ -2484,7 +2474,7 @@ function useEntityTransform(entity, { position, rotation, scale }) {
 }
 
 // src/reality/hooks/useEntityEvent.tsx
-import { useEffect as useEffect18, useRef as useRef8 } from "react";
+import { useEffect as useEffect18, useRef as useRef9 } from "react";
 
 // src/reality/type.ts
 var eventMap = {
@@ -2495,11 +2485,9 @@ var eventMap = {
   onSpatialDrag: "spatialdrag",
   onSpatialDragEnd: "spatialdragend",
   // rotate
-  onSpatialRotateStart: "spatialrotatestart",
   onSpatialRotate: "spatialrotate",
   onSpatialRotateEnd: "spatialrotateend",
   // magnify
-  onSpatialMagnifyStart: "spatialmagnifystart",
   onSpatialMagnify: "spatialmagnify",
   onSpatialMagnifyEnd: "spatialmagnifyend"
 };
@@ -2688,7 +2676,7 @@ function createEventProxy2(ev, instance) {
   });
 }
 var useEntityEvent = ({ instance, ...handlers }) => {
-  const eventsSetRef = useRef8(/* @__PURE__ */ new Set());
+  const eventsSetRef = useRef9(/* @__PURE__ */ new Set());
   useEffect18(() => {
     const entity = instance.entity;
     if (!entity) return;
@@ -2715,11 +2703,147 @@ var useEntityEvent = ({ instance, ...handlers }) => {
   return null;
 };
 
+// src/reality/hooks/useRealityEvents.tsx
+import { useEffect as useEffect19, useRef as useRef10 } from "react";
+function createEventProxy3(ev, instance) {
+  return new Proxy(ev, {
+    get(target, prop) {
+      if (prop === "currentTarget") {
+        return instance;
+      }
+      if (prop === "target") {
+        const origin = target.__origin;
+        if (origin) {
+          return new EntityRef(origin, null);
+        }
+        return instance;
+      }
+      if (prop === "bubbles") {
+        return true;
+      }
+      if (prop === "offsetX") {
+        const type = target.type;
+        if (type === "spatialtap") {
+          return target.detail?.location3D?.x ?? 0;
+        }
+        if (type === "spatialdragstart") {
+          return target.detail?.startLocation3D?.x ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "offsetY") {
+        const type = target.type;
+        if (type === "spatialtap") {
+          return target.detail?.location3D?.y ?? 0;
+        }
+        if (type === "spatialdragstart") {
+          return target.detail?.startLocation3D?.y ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "offsetZ") {
+        const type = target.type;
+        if (type === "spatialtap") {
+          return target.detail?.location3D?.z ?? 0;
+        }
+        if (type === "spatialdragstart") {
+          return target.detail?.startLocation3D?.z ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "translationX") {
+        const type = target.type;
+        if (type === "spatialdrag") {
+          return target.detail?.translation3D?.x ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "translationY") {
+        const type = target.type;
+        if (type === "spatialdrag") {
+          return target.detail?.translation3D?.y ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "translationZ") {
+        const type = target.type;
+        if (type === "spatialdrag") {
+          return target.detail?.translation3D?.z ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "quaternion") {
+        const type = target.type;
+        if (type === "spatialrotate") {
+          return target.detail?.quaternion ?? {
+            x: 0,
+            y: 0,
+            z: 0,
+            w: 1
+          };
+        }
+        return void 0;
+      }
+      if (prop === "magnification") {
+        const type = target.type;
+        if (type === "spatialmagnify") {
+          return target.detail?.magnification ?? 1;
+        }
+        return void 0;
+      }
+      if (prop === "clientX") {
+        const type = target.type;
+        if (type === "spatialtap" || type === "spatialdragstart") {
+          return target.detail?.globalLocation3D?.x ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "clientY") {
+        const type = target.type;
+        if (type === "spatialtap" || type === "spatialdragstart") {
+          return target.detail?.globalLocation3D?.y ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "clientZ") {
+        const type = target.type;
+        if (type === "spatialtap" || type === "spatialdragstart") {
+          return target.detail?.globalLocation3D?.z ?? 0;
+        }
+        return void 0;
+      }
+      const val = target[prop];
+      return typeof val === "function" ? val.bind(target) : val;
+    }
+  });
+}
+var useRealityEvents = ({ instance, ...handlers }) => {
+  const eventsSetRef = useRef10(/* @__PURE__ */ new Set());
+  useEffect19(() => {
+    if (!instance) return;
+    Object.entries(eventMap).forEach(([reactKey, spatialEvent]) => {
+      const handlerFn = handlers[reactKey];
+      if (!handlerFn) return;
+      const wrapped = (ev) => handlerFn(createEventProxy3(ev, instance));
+      instance.addEvent(spatialEvent, wrapped);
+      eventsSetRef.current.add(spatialEvent);
+    });
+    return () => {
+      if (instance) {
+        for (let x of eventsSetRef.current) {
+          instance.removeEvent(x);
+        }
+        eventsSetRef.current.clear();
+      }
+    };
+  }, [instance, ...Object.values(handlers)]);
+};
+
 // src/reality/hooks/useEntityId.tsx
-import { useEffect as useEffect19 } from "react";
+import { useEffect as useEffect20 } from "react";
 var useEntityId = ({ id, entity }) => {
   const ctx = useRealityContext();
-  useEffect19(() => {
+  useEffect20(() => {
     if (!id || !entity || !ctx) return;
     ctx.resourceRegistry.add(id, Promise.resolve(entity));
     return () => {
@@ -2730,31 +2854,30 @@ var useEntityId = ({ id, entity }) => {
 };
 
 // src/reality/hooks/useEntity.tsx
-import { useEffect as useEffect20, useRef as useRef9 } from "react";
+import { useEffect as useEffect21, useRef as useRef11 } from "react";
 var useEntity = ({
   ref,
   id,
   position,
   rotation,
   scale,
+  enableInput,
   onSpatialTap,
   onSpatialDragStart,
   onSpatialDrag,
   onSpatialDragEnd,
-  // onSpatialRotateStart,
   onSpatialRotate,
   onSpatialRotateEnd,
-  // onSpatialMagnifyStart,
   onSpatialMagnify,
   onSpatialMagnifyEnd,
-  // TODO: add other event handlers
-  createEntity
+  createEntity,
+  recreateKey
 }) => {
   const ctx = useRealityContext();
   const parent = useParentContext();
-  const instanceRef = useRef9(new EntityRef(null, ctx));
+  const instanceRef = useRef11(new EntityRef(null, ctx));
   const forceUpdate = useForceUpdate2();
-  useEffect20(() => {
+  useEffect21(() => {
     if (!ctx) return;
     const controller = new AbortController();
     const init = async () => {
@@ -2765,6 +2888,11 @@ var useEntity = ({
           ent.destroy();
           return;
         }
+        await ent.updateTransform({ position, rotation, scale });
+        if (controller.signal.aborted) {
+          ent.destroy();
+          return;
+        }
         if (parent) {
           const result = await parent.addEntity(ent);
           if (!result.success) throw new Error("parent.addEntity failed");
@@ -2783,7 +2911,7 @@ var useEntity = ({
       controller.abort();
       instanceRef.current?.destroy();
     };
-  }, [ctx, parent]);
+  }, [ctx, parent, recreateKey]);
   useEntityId({ id, entity: instanceRef.current.entity });
   useEntityTransform(instanceRef.current.entity, { position, rotation, scale });
   useEntityRef(ref, instanceRef.current);
@@ -2793,31 +2921,37 @@ var useEntity = ({
     onSpatialDragStart,
     onSpatialDrag,
     onSpatialDragEnd,
-    // onSpatialRotateStart,
     onSpatialRotate,
     onSpatialRotateEnd,
-    // onSpatialMagnifyStart,
     onSpatialMagnify,
     onSpatialMagnifyEnd
   });
+  useEffect21(() => {
+    const ent = instanceRef.current.entity;
+    if (!ent) return;
+    if (enableInput !== void 0) {
+      ent.enableInput = !!enableInput;
+    }
+  }, [instanceRef.current.entity, enableInput]);
   return instanceRef.current.entity;
 };
 
 // src/reality/hooks/useForceUpdate.tsx
-import { useCallback as useCallback7, useState as useState7 } from "react";
+import { useCallback as useCallback7, useState as useState6 } from "react";
 var useForceUpdate2 = () => {
-  const [, setTick] = useState7(0);
+  const [, setTick] = useState6(0);
   return useCallback7(() => setTick((tick) => tick + 1), []);
 };
 
 // src/reality/components/BaseEntity.tsx
 import { jsx as jsx12 } from "react/jsx-runtime";
 var BaseEntity = forwardRef10(
-  ({ children, createEntity, ...rest }, ref) => {
+  ({ children, createEntity, recreateKey, ...rest }, ref) => {
     const ctx = useRealityContext();
     const entity = useEntity({
       ...rest,
       ref,
+      recreateKey,
       createEntity: (signal) => createEntity(ctx, signal)
     });
     if (!entity) return null;
@@ -2845,35 +2979,102 @@ var Entity = forwardRef11((props, ref) => {
 import { forwardRef as forwardRef13 } from "react";
 
 // src/reality/components/GeometryEntity.tsx
-import { forwardRef as forwardRef12 } from "react";
+import { forwardRef as forwardRef12, useEffect as useEffect22, useRef as useRef12 } from "react";
 import { jsx as jsx14 } from "react/jsx-runtime";
 var GeometryEntity = forwardRef12(
   ({ id, children, name, materials, geometryOptions, createGeometry, ...rest }, ref) => {
+    const ctx = useRealityContext();
+    const entityRef = useRef12(null);
+    const componentRef = useRef12(null);
+    const mutableRef = useRef12({
+      lastSnapshot: null,
+      rebuildGen: 0
+    });
+    useEffect22(() => {
+      const { lastSnapshot } = mutableRef.current;
+      if (!ctx || !entityRef.current || lastSnapshot === null) return;
+      const geometryChanged = !shallowEqualObject(
+        lastSnapshot.geometryOptions,
+        geometryOptions
+      );
+      const materialsChanged = !shallowEqualArray(
+        lastSnapshot.materials,
+        materials
+      );
+      if (!geometryChanged && !materialsChanged) return;
+      mutableRef.current.lastSnapshot = { geometryOptions, materials };
+      mutableRef.current.rebuildGen += 1;
+      const gen = mutableRef.current.rebuildGen;
+      const rebuild = async () => {
+        const entity = entityRef.current;
+        if (!entity) return;
+        try {
+          const oldComponent = componentRef.current;
+          if (oldComponent) {
+            await entity.removeComponent(oldComponent);
+            await oldComponent.destroy();
+            componentRef.current = null;
+            if (gen !== mutableRef.current.rebuildGen) return;
+          }
+          const geometry = await createGeometry(geometryOptions);
+          if (gen !== mutableRef.current.rebuildGen) {
+            await geometry.destroy();
+            return;
+          }
+          const materialList = await Promise.all(
+            materials?.map((mid) => ctx.resourceRegistry.get(mid)).filter(Boolean) ?? []
+          );
+          if (gen !== mutableRef.current.rebuildGen) {
+            await geometry.destroy();
+            return;
+          }
+          const modelComponent = await ctx.session.createModelComponent({
+            mesh: geometry,
+            materials: materialList
+          });
+          if (gen !== mutableRef.current.rebuildGen) {
+            await modelComponent.destroy();
+            await geometry.destroy();
+            return;
+          }
+          await entity.addComponent(modelComponent);
+          componentRef.current = modelComponent;
+        } catch (error) {
+          if (gen === mutableRef.current.rebuildGen) {
+            console.error("GeometryEntity: rebuild failed", error);
+          }
+        }
+      };
+      rebuild();
+    }, [ctx, geometryOptions, materials, createGeometry]);
     return /* @__PURE__ */ jsx14(
       BaseEntity,
       {
         ...rest,
         id,
         ref,
-        createEntity: async (ctx, signal) => {
+        createEntity: async (ctx2, signal) => {
           const manager = new AbortResourceManager(signal);
           try {
             const ent = await manager.addResource(
-              () => ctx.session.createEntity({ id, name })
+              () => ctx2.session.createEntity({ id, name })
             );
             const geometry = await manager.addResource(
               () => createGeometry(geometryOptions)
             );
             const materialList = await Promise.all(
-              materials?.map((id2) => ctx.resourceRegistry.get(id2)).filter(Boolean) ?? []
+              materials?.map((id2) => ctx2.resourceRegistry.get(id2)).filter(Boolean) ?? []
             );
             const modelComponent = await manager.addResource(
-              () => ctx.session.createModelComponent({
+              () => ctx2.session.createModelComponent({
                 mesh: geometry,
                 materials: materialList
               })
             );
             await ent.addComponent(modelComponent);
+            entityRef.current = ent;
+            componentRef.current = modelComponent;
+            mutableRef.current.lastSnapshot = { geometryOptions, materials };
             return ent;
           } catch (error) {
             await manager.dispose();
@@ -2911,11 +3112,15 @@ var BoxEntity = forwardRef13(
 );
 
 // src/reality/components/UnlitMaterial.tsx
-import { useEffect as useEffect21, useRef as useRef10 } from "react";
-var UnlitMaterial = ({ children, ...options }) => {
+import { useEffect as useEffect23, useRef as useRef13 } from "react";
+var UnlitMaterial = ({
+  children,
+  ...options
+}) => {
   const ctx = useRealityContext();
-  const materialRef = useRef10();
-  useEffect21(() => {
+  const materialRef = useRef13();
+  const isInitializedRef = useRef13(false);
+  useEffect23(() => {
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
     const init = async () => {
@@ -2924,6 +3129,7 @@ var UnlitMaterial = ({ children, ...options }) => {
       try {
         const mat = await materialPromise;
         materialRef.current = mat;
+        isInitializedRef.current = true;
       } catch (error) {
         console.error(" ~ UnlitMaterial ~ error:", error);
       }
@@ -2931,8 +3137,21 @@ var UnlitMaterial = ({ children, ...options }) => {
     init();
     return () => {
       resourceRegistry.removeAndDestroy(options.id);
+      materialRef.current = void 0;
+      isInitializedRef.current = false;
     };
   }, [ctx]);
+  useEffect23(() => {
+    if (!isInitializedRef.current || !materialRef.current) return;
+    const updates = {};
+    if (options.color !== void 0) updates.color = options.color;
+    if (options.transparent !== void 0)
+      updates.transparent = options.transparent;
+    if (options.opacity !== void 0) updates.opacity = options.opacity;
+    if (Object.keys(updates).length > 0) {
+      materialRef.current.updateProperties(updates);
+    }
+  }, [options.color, options.transparent, options.opacity]);
   return null;
 };
 
@@ -3031,7 +3250,7 @@ var SceneGraph = ({ children }) => {
 };
 
 // src/reality/components/ModelAsset.tsx
-import { useEffect as useEffect22, useRef as useRef11 } from "react";
+import { useEffect as useEffect24, useRef as useRef14 } from "react";
 var resolveAssetUrl = (url) => {
   if (url.startsWith("http://") || url.startsWith("https://")) {
     return url;
@@ -3040,8 +3259,8 @@ var resolveAssetUrl = (url) => {
 };
 var ModelAsset = ({ children, ...options }) => {
   const ctx = useRealityContext();
-  const materialRef = useRef11();
-  useEffect22(() => {
+  const materialRef = useRef14();
+  useEffect24(() => {
     const controller = new AbortController();
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
@@ -3071,29 +3290,66 @@ var ModelAsset = ({ children, ...options }) => {
 };
 
 // src/reality/components/ModelEntity.tsx
-import { forwardRef as forwardRef18 } from "react";
+import { forwardRef as forwardRef18, useEffect as useEffect25, useRef as useRef15 } from "react";
 import { jsx as jsx21 } from "react/jsx-runtime";
 var ModelEntity = forwardRef18(
-  ({ id, model, children, name, ...rest }, ref) => {
+  ({ id, model, children, name, materials, ...rest }, ref) => {
+    const ctx = useRealityContext();
+    const entityRef = useRef15(null);
+    const lastMaterialsRef = useRef15(void 0);
+    useEffect25(() => {
+      if (!ctx || !entityRef.current) return;
+      const next = materials ?? [];
+      const prev = lastMaterialsRef.current ?? [];
+      if (shallowEqualArray(prev, next)) return;
+      lastMaterialsRef.current = next;
+      const apply = async () => {
+        try {
+          const materialList = (await Promise.all(
+            next.map((mid) => ctx.resourceRegistry.get(mid))
+          )).filter(Boolean);
+          if (entityRef.current) {
+            await entityRef.current.setMaterials(materialList);
+          }
+        } catch (error) {
+          console.error("ModelEntity: failed to set materials", error);
+        }
+      };
+      apply();
+    }, [ctx, materials]);
     return /* @__PURE__ */ jsx21(
       BaseEntity,
       {
         ...rest,
         id,
         ref,
-        createEntity: async (ctx, signal) => {
+        recreateKey: model,
+        createEntity: async (ctx2, signal) => {
           try {
-            const modelAsset = await ctx.resourceRegistry.get(model);
+            const modelAsset = await ctx2.resourceRegistry.get(model);
             if (!modelAsset)
               throw new Error(`ModelEntity: model not found ${model}`);
             if (signal.aborted) return null;
-            return ctx.session.createSpatialModelEntity(
+            const ent = await ctx2.session.createSpatialModelEntity(
               {
                 modelAssetId: modelAsset.id,
                 name
               },
               { id, name }
             );
+            entityRef.current = ent;
+            if (materials && materials.length > 0) {
+              const materialList = (await Promise.all(
+                materials.map(
+                  (mid) => ctx2.resourceRegistry.get(mid)
+                )
+              )).filter(Boolean);
+              if (materialList.length > 0 && !signal.aborted) {
+                await ent.setMaterials(materialList);
+              }
+            }
+            lastMaterialsRef.current = materials ?? [];
+            return ent;
           } catch (error) {
             return null;
           }
@@ -3108,9 +3364,9 @@ var ModelEntity = forwardRef18(
 import {
   forwardRef as forwardRef19,
   useCallback as useCallback8,
-  useEffect as useEffect23,
-  useRef as useRef12,
-  useState as useState8
+  useEffect as useEffect26,
+  useRef as useRef16,
+  useState as useState7
 } from "react";
 import { Fragment as Fragment3, jsx as jsx22, jsxs as jsxs3 } from "react/jsx-runtime";
 var Reality = forwardRef19(
@@ -3133,9 +3389,9 @@ var Reality = forwardRef19(
       onSpatialMagnifyEnd,
       ...props
     } = inProps;
-    const ctxRef = useRef12(null);
-    const creationId = useRef12(0);
-    const [isReady, setIsReady] = useState8(false);
+    const ctxRef = useRef16(null);
+    const creationId = useRef16(0);
+    const [isReady, setIsReady] = useState7(false);
     const cleanupReality = useCallback8(() => {
       ctxRef.current?.attachmentRegistry.destroy();
       ctxRef.current?.resourceRegistry.destroy();
@@ -3143,7 +3399,7 @@ var Reality = forwardRef19(
       ctxRef.current = null;
       setIsReady(false);
     }, []);
-    useEffect23(() => {
+    useEffect26(() => {
       return () => {
         creationId.current++;
         cleanupReality();
@@ -3193,6 +3449,17 @@ var Reality = forwardRef19(
       }
     }, [cleanupReality]);
     const content = useCallback8(() => /* @__PURE__ */ jsx22(Fragment3, {}), []);
+    useRealityEvents({
+      instance: ctxRef.current?.reality ?? null,
+      onSpatialTap,
+      onSpatialDragStart,
+      onSpatialDrag,
+      onSpatialDragEnd,
+      onSpatialRotate,
+      onSpatialRotateEnd,
+      onSpatialMagnify,
+      onSpatialMagnifyEnd
+    });
     return /* @__PURE__ */ jsxs3(RealityContext.Provider, { value: ctxRef.current, children: [
       /* @__PURE__ */ jsx22(
         SpatializedContainer,
@@ -3210,7 +3477,7 @@ var Reality = forwardRef19(
 );
 
 // src/reality/components/AttachmentAsset.tsx
-import { useEffect as useEffect24, useState as useState9 } from "react";
+import { useEffect as useEffect27, useState as useState8 } from "react";
 import { createPortal as createPortal3 } from "react-dom";
 import { jsx as jsx23 } from "react/jsx-runtime";
 var AttachmentAsset = ({
@@ -3218,17 +3485,19 @@ var AttachmentAsset = ({
   children
 }) => {
   const ctx = useRealityContext();
-  const [containers, setContainers] = useState9([]);
-  useEffect24(() => {
+  const [containers, setContainers] = useState8([]);
+  useEffect27(() => {
     if (!ctx) return;
     return ctx.attachmentRegistry.onContainersChange(name, setContainers);
   }, [ctx, name]);
   if (!containers.length) return null;
-  return /* @__PURE__ */ jsx23(InsideAttachmentContext.Provider, { value: true, children: containers.map((c, idx) => createPortal3(children, c, `${name}-${idx}`)) });
+  return /* @__PURE__ */ jsx23(InsideAttachmentContext.Provider, { value: true, children: containers.map(
+    ({ instanceId, container }) => createPortal3(children, container, instanceId)
+  ) });
 };
 
 // src/reality/components/AttachmentEntity.tsx
-import { useEffect as useEffect25, useRef as useRef13, useState as useState10 } from "react";
+import { useEffect as useEffect28, useRef as useRef17, useState as useState9 } from "react";
 var instanceCounter = 0;
 var AttachmentEntity = ({
   attachment: attachmentName,
@@ -3237,13 +3506,14 @@ var AttachmentEntity = ({
 }) => {
   const ctx = useRealityContext();
   const parent = useParentContext();
-  const attachmentRef = useRef13(null);
-  const parentIdRef = useRef13(null);
-  const instanceIdRef = useRef13(`att_${++instanceCounter}`);
-  const attachmentNameRef = useRef13(attachmentName);
-  const [childWindow, setChildWindow] = useState10(null);
-  useEffect25(() => {
+  const attachmentRef = useRef17(null);
+  const parentIdRef = useRef17(null);
+  const instanceIdRef = useRef17(`att_${++instanceCounter}`);
+  const attachmentNameRef = useRef17(attachmentName);
+  const [childWindow, setChildWindow] = useState9(null);
+  useEffect28(() => {
     if (!ctx || !parent) return;
+    if (attachmentRef.current) return;
     const parentId = parent.id;
     parentIdRef.current = parentId;
     let cancelled = false;
@@ -3252,7 +3522,8 @@ var AttachmentEntity = ({
         const att = await ctx.session.createAttachmentEntity({
           parentEntityId: parentId,
           position: position ?? [0, 0, 0],
-          size
+          size,
+          ownerViewId: ctx.reality.id
         });
         if (cancelled) {
           att.destroy();
@@ -3264,7 +3535,6 @@ var AttachmentEntity = ({
         windowProxy.document.body.style.minWidth = "100%";
         windowProxy.document.body.style.maxWidth = "100%";
         windowProxy.document.body.style.minHeight = "100%";
-        await syncParentHeadToChild(windowProxy);
         const viewport = windowProxy.document.querySelector(
           'meta[name="viewport"]'
         );
@@ -3303,7 +3573,7 @@ var AttachmentEntity = ({
       }
     };
   }, [ctx, parent]);
-  useEffect25(() => {
+  useEffect28(() => {
     if (!ctx) return;
     const att = attachmentRef.current;
     const prevName = attachmentNameRef.current;
@@ -3320,16 +3590,26 @@ var AttachmentEntity = ({
     }
   }, [ctx, attachmentName]);
   useSyncHeadStyles(childWindow, { subtree: false });
-  useEffect25(() => {
+  useEffect28(() => {
     if (!attachmentRef.current) return;
     attachmentRef.current.update({ position, size });
   }, [position?.[0], position?.[1], position?.[2], size?.width, size?.height]);
   return null;
 };
 
+// src/reality/components/Material.tsx
+import { jsx as jsx24 } from "react/jsx-runtime";
+var Material = (props) => {
+  if (props.type === "unlit") {
+    const { type, ...rest } = props;
+    return /* @__PURE__ */ jsx24(UnlitMaterial, { ...rest });
+  }
+  return null;
+};
+
 // src/Model.tsx
 import { forwardRef as forwardRef20 } from "react";
-import { jsx as jsx24 } from "react/jsx-runtime";
+import { jsx as jsx25 } from "react/jsx-runtime";
 var spatial2 = new Spatial();
 function ModelBase(props, ref) {
   const insideAttachment = useInsideAttachment();
@@ -3344,30 +3624,125 @@ function ModelBase(props, ref) {
       onSpatialRotateEnd,
       onSpatialMagnify,
       onSpatialMagnifyEnd,
+      spatialEventOptions: _spatialEventOptions,
       ...modelProps
     } = restProps;
-    return /* @__PURE__ */ jsx24("model", { ref, ...modelProps });
+    return /* @__PURE__ */ jsx25("model", { ref, ...modelProps });
   }
-  return /* @__PURE__ */ jsx24(SpatializedStatic3DElementContainer, { ref, ...restProps });
+  return /* @__PURE__ */ jsx25(SpatializedStatic3DElementContainer, { ref, ...restProps });
 }
 var Model = withSSRSupported(forwardRef20(ModelBase));
 Model.displayName = "Model";
 
+// src/useMetrics.tsx
+import { useSyncExternalStore } from "react";
+function useMetrics() {
+  useSyncExternalStore(PhysicalMetrics.subscribe, PhysicalMetrics.getValue);
+  const { pointToPhysical, physicalToPoint } = PhysicalMetrics;
+  return { pointToPhysical, physicalToPoint };
+}
+
+// src/jsx/jsx-shared.ts
+import { jsxDEV as _jsxDEV } from "react/jsx-dev-runtime";
+import reactJSXRuntime from "react/jsx-runtime";
+import { createElement as reactCreateElement } from "react";
+var attributeFlag = "enable-xr";
+var styleFlag = "enableXr";
+var classFlag = "__enableXr__";
+var xrMonitorFlag = "enable-xr-monitor";
+function replaceToSpatialPrimitiveType(type, props) {
+  if (type === Model) {
+    return type;
+  }
+  const propsObject = props;
+  if (attributeFlag in propsObject) {
+    delete propsObject[attributeFlag];
+    return withSpatialized2DElementContainer(type);
+  }
+  if (xrMonitorFlag in propsObject) {
+    delete propsObject[xrMonitorFlag];
+    return withSpatialMonitor(type);
+  }
+  if (propsObject && propsObject.style && styleFlag in propsObject.style) {
+    delete propsObject.style[styleFlag];
+    return withSpatialized2DElementContainer(type);
+  }
+  if (propsObject && typeof propsObject.className === "string") {
+    const originalClassNames = propsObject.className.split(" ");
+    const idx = originalClassNames.indexOf(classFlag);
+    if (idx !== -1) {
+      originalClassNames.splice(idx, 1);
+      propsObject.className = originalClassNames.join(" ");
+      return withSpatialized2DElementContainer(type);
+    }
+  }
+  return type;
+}
+function createElement(...args) {
+  const [type, props, ...rest] = args;
+  const newType = replaceToSpatialPrimitiveType(type, props);
+  return reactCreateElement(newType, props, ...rest);
+}
+
+// src/utils/convertCoordinate.ts
+function resolveSpatialObjectId(target) {
+  if (typeof window !== "undefined" && target === window) {
+    const scene = getSession()?.getSpatialScene();
+    return scene?.id ?? "";
+  }
+  const maybeEntity = target;
+  if (maybeEntity && typeof maybeEntity === "object" && "entity" in maybeEntity) {
+    return maybeEntity.entity?.id ?? null;
+  }
+  const dom = target?.__raw ?? target;
+  if (dom && typeof dom === "object") {
+    const spatializedElement = dom.__spatializedElement ?? dom.__innerSpatializedElement?.();
+    if (spatializedElement && spatializedElement.id) {
+      return spatializedElement.id;
+    }
+  }
+  return null;
+}
+async function convertCoordinate(position, { from, to }) {
+  try {
+    const fromId = resolveSpatialObjectId(from);
+    const toId = resolveSpatialObjectId(to);
+    if (fromId === null || toId === null) {
+      console.warn(
+        "convertCoordinate error: from or to is not a valid coordinate convertible"
+      );
+      return position;
+    }
+    const spatialScene = getSession()?.getSpatialScene();
+    if (!spatialScene) return position;
+    const ret = await spatialScene.convertCoordinate(position, fromId, toId);
+    return ret ?? position;
+  } catch (error) {
+    console.warn("convertCoordinate error:", error);
+    return position;
+  }
+}
+
 // src/index.ts
-var version = "1.3.0";
+var version = "1.5.0";
 if (typeof window !== "undefined") {
   initPolyfill();
 }
 export {
   AttachmentAsset,
   AttachmentEntity,
+  BoxEntity as Box,
   BoxEntity,
+  ConeEntity as Cone,
   ConeEntity,
+  CylinderEntity as Cylinder,
   CylinderEntity,
   Entity,
+  Material,
   Model,
   ModelAsset,
   ModelEntity,
+  PlaneEntity as Plane,
   PlaneEntity,
   Reality,
   SSRProvider,
@@ -3376,14 +3751,17 @@ export {
   Spatialized2DElementContainer,
   SpatializedContainer,
   SpatializedStatic3DElementContainer,
+  SphereEntity as Sphere,
   SphereEntity,
   UnlitMaterial,
+  SceneGraph as World,
+  convertCoordinate,
+  createElement,
   enableDebugTool,
   eventMap,
   initPolyfill,
   initScene,
-  toLocalSpace,
-  toSceneSpatial,
+  useMetrics,
   version,
   withSpatialMonitor,
   withSpatialized2DElementContainer