@webspatial/react-sdk 1.2.1 → 1.4.0

package/dist/default/index.js

@@ -2,7 +2,7 @@
       (function(){
         if(typeof window === 'undefined') return;
         if(!window.__webspatialsdk__) window.__webspatialsdk__ = {}
-        window.__webspatialsdk__['react-sdk-version'] = "1.2.1"
+        window.__webspatialsdk__['react-sdk-version'] = "1.4.0"
         window.__webspatialsdk__['XR_ENV'] = "avp"
     })()
       
@@ -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, {
@@ -849,7 +843,7 @@ var TransformVisibilityTaskContainer = forwardRef2(
 );
 
 // src/spatialized-container/SpatializedContainer.tsx
-import { forwardRef as forwardRef4, useContext as useContext6, useEffect as useEffect10, useMemo as useMemo2 } from "react";
+import { forwardRef as forwardRef4, useContext as useContext7, useEffect as useEffect10, useMemo as useMemo2 } from "react";
 
 // src/utils/getSession.ts
 import { isSSREnv, Spatial } from "@webspatial/core-sdk";
@@ -897,37 +891,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;
@@ -1012,40 +975,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
     });
   }
@@ -1163,18 +1094,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();
         }
@@ -1182,9 +1114,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]);
@@ -1193,6 +1127,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;
@@ -1231,6 +1177,7 @@ function PortalSpatializedContainer(props) {
     onSpatialRotateEnd,
     onSpatialMagnify,
     onSpatialMagnifyEnd,
+    spatialEventOptions,
     [SpatialID]: spatialId,
     ...restProps
   } = props;
@@ -1302,14 +1249,27 @@ 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
   ] });
 }
 
+// src/reality/context/InsideAttachmentContext.tsx
+import { createContext as createContext4, useContext as useContext5 } from "react";
+var InsideAttachmentContext = createContext4(false);
+var useInsideAttachment = () => useContext5(InsideAttachmentContext);
+
 // src/spatialized-container/hooks/useSpatialEvents.ts
-function createEventProxy(event, currentTargetGetter, offsetXGetter, offsetYGetter, offsetZGetter) {
+function createEventProxy(event, currentTargetGetter, offsetXGetter, offsetYGetter, offsetZGetter, clientXGetter, clientYGetter, clientZGetter, translationXGetter, translationYGetter, translationZGetter, quaternionGetter, magnificationGetter) {
   return new Proxy(event, {
     get(target, prop) {
       if (prop === "currentTarget") {
@@ -1330,18 +1290,50 @@ function createEventProxy(event, currentTargetGetter, offsetXGetter, offsetYGett
       if (prop === "offsetZ" && offsetZGetter) {
         return offsetZGetter(target) ?? 0;
       }
+      if (prop === "clientX" && clientXGetter) {
+        return clientXGetter(target) ?? 0;
+      }
+      if (prop === "clientY" && clientYGetter) {
+        return clientYGetter(target) ?? 0;
+      }
+      if (prop === "clientZ" && clientZGetter) {
+        return clientZGetter(target) ?? 0;
+      }
+      if (prop === "translationX" && translationXGetter) {
+        return translationXGetter(target) ?? 0;
+      }
+      if (prop === "translationY" && translationYGetter) {
+        return translationYGetter(target) ?? 0;
+      }
+      if (prop === "translationZ" && translationZGetter) {
+        return translationZGetter(target) ?? 0;
+      }
+      if (prop === "quaternion" && quaternionGetter) {
+        return quaternionGetter(target) ?? { x: 0, y: 0, z: 0, w: 1 };
+      }
+      if (prop === "magnification" && magnificationGetter) {
+        return magnificationGetter(target) ?? 1;
+      }
       return Reflect.get(target, prop);
     }
   });
 }
-function createEventHandler(handler, currentTargetGetter, offsetXGetter, offsetYGetter, offsetZGetter) {
+function createEventHandler(handler, currentTargetGetter, offsetXGetter, offsetYGetter, offsetZGetter, clientXGetter, clientYGetter, clientZGetter, translationXGetter, translationYGetter, translationZGetter, quaternionGetter, magnificationGetter) {
   return handler ? (event) => {
     const proxyEvent = createEventProxy(
       event,
       currentTargetGetter,
       offsetXGetter,
       offsetYGetter,
-      offsetZGetter
+      offsetZGetter,
+      clientXGetter,
+      clientYGetter,
+      clientZGetter,
+      translationXGetter,
+      translationYGetter,
+      translationZGetter,
+      quaternionGetter,
+      magnificationGetter
     );
     handler(proxyEvent);
   } : void 0;
@@ -1350,13 +1342,27 @@ function useSpatialEventsBase(spatialEvents, currentTargetGetter) {
   const onSpatialTap = createEventHandler(
     spatialEvents.onSpatialTap,
     currentTargetGetter,
+    // offsetX/Y/Z come from local coordinates
     (ev) => ev.detail?.location3D?.x,
     (ev) => ev.detail?.location3D?.y,
-    (ev) => ev.detail?.location3D?.z
+    (ev) => ev.detail?.location3D?.z,
+    // clientX/Y/Z come from global scene coordinates
+    (ev) => ev.detail?.globalLocation3D?.x,
+    (ev) => ev.detail?.globalLocation3D?.y,
+    (ev) => ev.detail?.globalLocation3D?.z
   );
   const onSpatialDrag = createEventHandler(
     spatialEvents.onSpatialDrag,
-    currentTargetGetter
+    currentTargetGetter,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    (ev) => ev.detail?.translation3D?.x,
+    (ev) => ev.detail?.translation3D?.y,
+    (ev) => ev.detail?.translation3D?.z
   );
   const onSpatialDragEnd = createEventHandler(
     spatialEvents.onSpatialDragEnd,
@@ -1364,7 +1370,17 @@ function useSpatialEventsBase(spatialEvents, currentTargetGetter) {
   );
   const onSpatialRotate = createEventHandler(
     spatialEvents.onSpatialRotate,
-    currentTargetGetter
+    currentTargetGetter,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    (ev) => ev.detail?.quaternion
   );
   const onSpatialRotateEnd = createEventHandler(
     spatialEvents.onSpatialRotateEnd,
@@ -1372,7 +1388,18 @@ function useSpatialEventsBase(spatialEvents, currentTargetGetter) {
   );
   const onSpatialMagnify = createEventHandler(
     spatialEvents.onSpatialMagnify,
-    currentTargetGetter
+    currentTargetGetter,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    (ev) => ev.detail?.magnification
   );
   const onSpatialMagnifyEnd = createEventHandler(
     spatialEvents.onSpatialMagnifyEnd,
@@ -1383,7 +1410,10 @@ function useSpatialEventsBase(spatialEvents, currentTargetGetter) {
     currentTargetGetter,
     (ev) => ev.detail?.startLocation3D?.x,
     (ev) => ev.detail?.startLocation3D?.y,
-    (ev) => ev.detail?.startLocation3D?.z
+    (ev) => ev.detail?.startLocation3D?.z,
+    (ev) => ev.detail?.globalLocation3D?.x,
+    (ev) => ev.detail?.globalLocation3D?.y,
+    (ev) => ev.detail?.globalLocation3D?.z
   );
   return {
     onSpatialTap,
@@ -1412,9 +1442,9 @@ function useSpatialEventsWhenSpatializedContainerExist(spatialEvents, spatialId,
 }
 
 // src/ssr/SSRContext.tsx
-import { createContext as createContext4, useState as useState4, useEffect as useEffect8 } from "react";
+import { createContext as createContext5, useState as useState4, useEffect as useEffect8 } from "react";
 import { jsx as jsx4 } from "react/jsx-runtime";
-var SSRContext = createContext4(false);
+var SSRContext = createContext5(false);
 var SSRProvider = ({
   isSSR: initialIsSSR = true,
   children
@@ -1432,9 +1462,9 @@ var SSRProvider = ({
 import { forwardRef as forwardRef3 } from "react";
 
 // src/ssr/useSSRPhase.tsx
-import { useContext as useContext5, useState as useState5, useEffect as useEffect9 } from "react";
+import { useContext as useContext6, useState as useState5, useEffect as useEffect9 } from "react";
 function useSSRPhase() {
-  const isSSRContext = useContext5(SSRContext);
+  const isSSRContext = useContext6(SSRContext);
   const isServer = typeof window === "undefined";
   const [hydrated, setHydrated] = useState5(false);
   useEffect9(() => setHydrated(true), []);
@@ -1470,33 +1500,49 @@ function withSSRSupported(Component) {
 
 // src/spatialized-container/SpatializedContainer.tsx
 import { jsx as jsx6, jsxs as jsxs2 } from "react/jsx-runtime";
+function DegradedContainer({
+  innerRef,
+  ...inprops
+}) {
+  const {
+    component: Component,
+    children,
+    ["enable-xr"]: _enableXR,
+    onSpatialTap: _onSpatialTap,
+    onSpatialDragStart: _onSpatialDragStart,
+    onSpatialDrag: _onSpatialDrag,
+    onSpatialDragEnd: _onSpatialDragEnd,
+    onSpatialRotate: _onSpatialRotate,
+    onSpatialRotateEnd: _onSpatialRotateEnd,
+    onSpatialMagnify: _onSpatialMagnify,
+    onSpatialMagnifyEnd: _onSpatialMagnifyEnd,
+    spatialEventOptions: _spatialEventOptions,
+    spatializedContent: _content,
+    createSpatializedElement: _create,
+    getExtraSpatializedElementProperties: _getExtra,
+    extraRefProps: _extraRef,
+    sizingMode: _sizingMode,
+    ...restProps
+  } = inprops;
+  return /* @__PURE__ */ jsx6(Component, { ref: innerRef, ...restProps, children });
+}
 function SpatializedContainerBase(inprops, ref) {
   const isWebSpatialEnv = getSession() !== null;
-  if (!isWebSpatialEnv) {
-    const {
-      component: Component,
-      spatializedContent,
-      createSpatializedElement: createSpatializedElement2,
-      getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
-      onSpatialTap: onSpatialTap2,
-      onSpatialDragStart: onSpatialDragStart2,
-      onSpatialDrag: onSpatialDrag2,
-      onSpatialDragEnd: onSpatialDragEnd2,
-      onSpatialRotate: onSpatialRotate2,
-      onSpatialRotateEnd: onSpatialRotateEnd2,
-      onSpatialMagnify: onSpatialMagnify2,
-      onSpatialMagnifyEnd: onSpatialMagnifyEnd2,
-      extraRefProps: extraRefProps2,
-      ...restProps
-    } = inprops;
-    return /* @__PURE__ */ jsx6(Component, { ref, ...restProps });
+  const insideAttachment = useInsideAttachment();
+  if (!isWebSpatialEnv || insideAttachment) {
+    if (insideAttachment) {
+      console.warn(
+        `[WebSpatial] ${inprops.component || "Spatial element"} cannot be used inside AttachmentAsset. Rendering as plain HTML.`
+      );
+    }
+    return /* @__PURE__ */ jsx6(DegradedContainer, { ...inprops, innerRef: ref });
   }
-  const layer = useContext6(SpatialLayerContext) + 1;
-  const rootSpatializedContainerObject = useContext6(
+  const layer = useContext7(SpatialLayerContext) + 1;
+  const rootSpatializedContainerObject = useContext7(
     SpatializedContainerContext
   );
   const inSpatializedContainer = !!rootSpatializedContainerObject;
-  const portalInstanceObject = useContext6(PortalInstanceContext);
+  const portalInstanceObject = useContext7(PortalInstanceContext);
   const inPortalInstanceEnv = !!portalInstanceObject;
   const isInStandardInstance = !inPortalInstanceEnv;
   const spatialId = useMemo2(() => {
@@ -1557,6 +1603,7 @@ function SpatializedContainerBase(inprops, ref) {
         spatializedContent,
         createSpatializedElement: createSpatializedElement2,
         getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
+        spatialEventOptions: _nestedSpatialEventOptions,
         ...restProps
       } = props;
       return /* @__PURE__ */ jsxs2(SpatialLayerContext.Provider, { value: layer, children: [
@@ -1607,6 +1654,7 @@ function SpatializedContainerBase(inprops, ref) {
       spatializedContent,
       createSpatializedElement: createSpatializedElement2,
       getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
+      spatialEventOptions: _rootSpatialEventOptions,
       ...restProps
     } = props;
     return /* @__PURE__ */ jsx6(SpatialLayerContext.Provider, { value: layer, children: /* @__PURE__ */ jsxs2(
@@ -1650,28 +1698,47 @@ var SpatializedContainer = withSSRSupported(
 );
 
 // src/spatialized-container/Spatialized2DElementContainer.tsx
+import { createPortal as createPortal2 } from "react-dom";
 import {
   forwardRef as forwardRef5,
-  useContext as useContext7,
-  useEffect as useEffect11
+  useContext as useContext8,
+  useEffect as useEffect12
 } from "react";
-import { createPortal as createPortal2 } from "react-dom";
-import { jsx as jsx7 } from "react/jsx-runtime";
-function asyncLoadStyleToChildWindow(childWindow, n) {
+
+// src/utils/windowStyleSync.ts
+function asyncLoadStyleToChildWindow(childWindow, link, isCurrent) {
   return new Promise((resolve) => {
-    n.href += "?uniqueURL=" + Math.random();
-    n.onerror = function(error) {
-      console.error("Failed to load style link", n.href);
-      resolve(false);
+    const { href } = link;
+    const sep = href.includes("?") ? "&" : "?";
+    link.href = `${href}${sep}uniqueURL=${Math.random()}`;
+    let finished = false;
+    const finish = (ok) => {
+      if (finished) return;
+      finished = true;
+      resolve(ok);
+    };
+    link.onerror = () => {
+      finish(false);
     };
-    n.onload = function() {
-      resolve(true);
+    link.onload = () => {
+      if (!isCurrent()) {
+        link.parentNode?.removeChild(link);
+        finish(false);
+        return;
+      }
+      finish(true);
     };
     setTimeout(() => {
-      childWindow.document.head.appendChild(n);
+      if (!isCurrent()) {
+        finish(false);
+        return;
+      }
+      childWindow.document.head.appendChild(link);
     }, 50);
   });
 }
+var WEBSPATIAL_SYNC_ATTR = "data-webspatial-sync";
+var WEBSPATIAL_SYNC_KEY_ATTR = "data-webspatial-sync-key";
 function setOpenWindowStyle(openedWindow) {
   openedWindow.document.documentElement.style.cssText += document.documentElement.style.cssText;
   openedWindow.document.documentElement.style.backgroundColor = "transparent";
@@ -1683,23 +1750,118 @@ function setOpenWindowStyle(openedWindow) {
   openedWindow.document.body.style.minWidth = "fit-content";
   openedWindow.document.body.style.background = "transparent";
 }
+var controllers = /* @__PURE__ */ new WeakMap();
+function getController(childWindow) {
+  const prev = controllers.get(childWindow);
+  if (prev) return prev;
+  const next = { version: 0 };
+  controllers.set(childWindow, next);
+  return next;
+}
 async function syncParentHeadToChild(childWindow) {
+  const controller = getController(childWindow);
+  const version2 = ++controller.version;
   const styleLoadedPromises = [];
-  for (let i = 0; i < document.head.children.length; i++) {
-    let n = document.head.children[i].cloneNode(true);
-    if (n.nodeName == "LINK" && n.rel == "stylesheet" && n.href) {
-      const promise = asyncLoadStyleToChildWindow(
-        childWindow,
-        n
-      );
-      styleLoadedPromises.push(promise);
-    } else {
-      childWindow.document.head.appendChild(n);
-    }
+  const { head } = childWindow.document;
+  const isCurrent = () => controller.version === version2;
+  const parentStyles = Array.from(document.head.querySelectorAll("style"));
+  const parentStylesheets = Array.from(
+    document.head.querySelectorAll('link[rel="stylesheet"][href]')
+  );
+  const desiredStylesheetKeys = /* @__PURE__ */ new Set();
+  for (const link of parentStylesheets) {
+    if (link.href) desiredStylesheetKeys.add(link.href);
+  }
+  const existingSyncedLinks = Array.from(
+    head.querySelectorAll(
+      `link[rel="stylesheet"][${WEBSPATIAL_SYNC_ATTR}="1"]`
+    )
+  );
+  for (const link of existingSyncedLinks) {
+    const key = link.getAttribute(WEBSPATIAL_SYNC_KEY_ATTR) ?? link.href;
+    if (!desiredStylesheetKeys.has(key)) link.parentNode?.removeChild(link);
+  }
+  const prevSyncedStyles = head.querySelectorAll(
+    `style[${WEBSPATIAL_SYNC_ATTR}="1"]`
+  );
+  prevSyncedStyles.forEach((n) => n.parentNode?.removeChild(n));
+  for (const styleEl of parentStyles) {
+    const node = styleEl.cloneNode(true);
+    node.setAttribute(WEBSPATIAL_SYNC_ATTR, "1");
+    head.appendChild(node);
+  }
+  const currentKeys = /* @__PURE__ */ new Set();
+  const currentSyncedLinks = Array.from(
+    head.querySelectorAll(
+      `link[rel="stylesheet"][${WEBSPATIAL_SYNC_ATTR}="1"]`
+    )
+  );
+  for (const link of currentSyncedLinks) {
+    currentKeys.add(link.getAttribute(WEBSPATIAL_SYNC_KEY_ATTR) ?? link.href);
+  }
+  for (const link of parentStylesheets) {
+    const key = link.href;
+    if (!key || currentKeys.has(key)) continue;
+    const node = link.cloneNode(true);
+    node.setAttribute(WEBSPATIAL_SYNC_ATTR, "1");
+    node.setAttribute(WEBSPATIAL_SYNC_KEY_ATTR, key);
+    styleLoadedPromises.push(
+      asyncLoadStyleToChildWindow(childWindow, node, isCurrent)
+    );
   }
   childWindow.document.documentElement.className = document.documentElement.className;
   return Promise.all(styleLoadedPromises);
 }
+
+// src/utils/useSyncHeadStyles.ts
+import { useEffect as useEffect11 } from "react";
+function defaultShouldSync(mutations) {
+  if (!Array.isArray(mutations) || mutations.length === 0) return false;
+  for (const mutation of mutations) {
+    const nodes = [
+      ...Array.from(mutation.addedNodes),
+      ...Array.from(mutation.removedNodes)
+    ];
+    for (const node of nodes) {
+      if (!(node instanceof Element)) continue;
+      const tag = node.tagName;
+      if (tag === "STYLE") return true;
+      if (tag === "LINK") {
+        const { rel } = node;
+        if (rel && rel.toLowerCase() === "stylesheet") return true;
+      }
+    }
+  }
+  return false;
+}
+function useSyncHeadStyles(childWindow, options) {
+  const delayMs = 100;
+  const subtree = options?.subtree ?? false;
+  const immediate = options?.immediate ?? true;
+  useEffect11(() => {
+    if (!childWindow) return;
+    let timer;
+    const scheduleSync = () => {
+      if (timer) window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        syncParentHeadToChild(childWindow);
+      }, delayMs);
+    };
+    if (immediate) scheduleSync();
+    const observer = new MutationObserver((mutations) => {
+      if (!defaultShouldSync(mutations)) return;
+      scheduleSync();
+    });
+    observer.observe(document.head, { childList: true, subtree });
+    return () => {
+      if (timer) window.clearTimeout(timer);
+      observer.disconnect();
+    };
+  }, [childWindow, delayMs, subtree, immediate]);
+}
+
+// src/spatialized-container/Spatialized2DElementContainer.tsx
+import { jsx as jsx7 } from "react/jsx-runtime";
 function getJSXPortalInstance(inProps, portalInstanceObject) {
   const { component: El, style: inStyle = {}, ...props } = inProps;
   const extraStyle = {
@@ -1725,19 +1887,8 @@ function getJSXPortalInstance(inProps, portalInstanceObject) {
   };
   return /* @__PURE__ */ jsx7(El, { style, ...props });
 }
-function useSyncHeaderStyle(windowProxy) {
-  useEffect11(() => {
-    const headObserver = new MutationObserver((_) => {
-      syncParentHeadToChild(windowProxy);
-    });
-    headObserver.observe(document.head, { childList: true, subtree: true });
-    return () => {
-      headObserver.disconnect();
-    };
-  }, []);
-}
 function useSyncDocumentTitle(windowProxy, spatializedElement, name) {
-  useEffect11(() => {
+  useEffect12(() => {
     windowProxy.document.title = name;
     spatializedElement.updateProperties({
       name
@@ -1747,11 +1898,13 @@ function useSyncDocumentTitle(windowProxy, spatializedElement, name) {
 function SpatializedContent(props) {
   const { spatializedElement, ...restProps } = props;
   const spatialized2DElement = spatializedElement;
-  const windowProxy = spatialized2DElement.windowProxy;
-  useSyncHeaderStyle(windowProxy);
+  const { windowProxy } = spatialized2DElement;
+  useSyncHeadStyles(windowProxy, {
+    subtree: false
+  });
   const name = restProps["data-name"] || "";
   useSyncDocumentTitle(windowProxy, spatialized2DElement, name);
-  const portalInstanceObject = useContext7(
+  const portalInstanceObject = useContext8(
     PortalInstanceContext
   );
   const JSXPortalInstance = getJSXPortalInstance(
@@ -1776,14 +1929,14 @@ function getExtraSpatializedElementProperties(computedStyle) {
 }
 async function createSpatializedElement() {
   const spatializedElement = await getSession().createSpatialized2DElement();
-  const windowProxy = spatializedElement.windowProxy;
+  const { windowProxy } = spatializedElement;
   setOpenWindowStyle(windowProxy);
   await syncParentHeadToChild(windowProxy);
   const viewport = windowProxy.document.querySelector('meta[name="viewport"]');
   if (viewport) {
     viewport?.setAttribute(
       "content",
-      ` initial-scale=1.0, maximum-scale=1.0, user-scalable=no`
+      " initial-scale=1.0, maximum-scale=1.0, user-scalable=no"
     );
   } else {
     const meta = windowProxy.document.createElement("meta");
@@ -1813,12 +1966,10 @@ var Spatialized2DElementContainer = forwardRef5(
 import {
   forwardRef as forwardRef6,
   useCallback as useCallback6,
-  useContext as useContext8,
-  useEffect as useEffect12,
+  useContext as useContext9,
+  useEffect as useEffect13,
   useMemo as useMemo3,
-  useState as useState6,
-  useImperativeHandle,
-  useRef as useRef4
+  useRef as useRef5
 } from "react";
 import { Fragment as Fragment2, jsx as jsx8 } from "react/jsx-runtime";
 function getAbsoluteURL(url) {
@@ -1855,16 +2006,16 @@ function createLoadSuccessEvent(targetGetter) {
 function SpatializedContent2(props) {
   const { src, spatializedElement, onLoad, onError } = props;
   const spatializedStatic3DElement = spatializedElement;
-  const portalInstanceObject = useContext8(
+  const portalInstanceObject = useContext9(
     PortalInstanceContext
   );
   const currentSrc = useMemo3(() => getAbsoluteURL(src), [src]);
-  useEffect12(() => {
+  useEffect13(() => {
     if (src) {
       spatializedStatic3DElement.updateProperties({ modelURL: currentSrc });
     }
   }, [currentSrc]);
-  useEffect12(() => {
+  useEffect13(() => {
     if (onLoad) {
       spatializedStatic3DElement.onLoadCallback = () => {
         onLoad(
@@ -1877,7 +2028,7 @@ function SpatializedContent2(props) {
       spatializedStatic3DElement.onLoadCallback = void 0;
     }
   }, [onLoad]);
-  useEffect12(() => {
+  useEffect13(() => {
     if (onError) {
       spatializedStatic3DElement.onLoadFailureCallback = () => {
         onError(
@@ -1893,14 +2044,12 @@ function SpatializedContent2(props) {
   return /* @__PURE__ */ jsx8(Fragment2, {});
 }
 function SpatializedStatic3DElementContainerBase(props, ref) {
-  const containerRef = useRef4(null);
-  const [elementCreated, setElementCreated] = useState6(false);
-  useImperativeHandle(ref, () => elementCreated ? containerRef.current : null, [elementCreated]);
-  const createSpatializedElement2 = useCallback6(async () => {
-    const element = await getSession().createSpatializedStatic3DElement();
-    setElementCreated(true);
-    return element;
-  }, [setElementCreated]);
+  const promiseRef = useRef5(null);
+  const createSpatializedElement2 = useCallback6(() => {
+    const url = getAbsoluteURL(props.src);
+    promiseRef.current = getSession().createSpatializedStatic3DElement(url);
+    return promiseRef.current;
+  }, []);
   const extraRefProps = useCallback6(
     (domProxy) => {
       let modelTransform = new DOMMatrixReadOnly();
@@ -1909,14 +2058,10 @@ function SpatializedStatic3DElementContainerBase(props, ref) {
           return getAbsoluteURL(props.src);
         },
         get ready() {
-          const spatializedElement = domProxy.__spatializedElement;
-          const promise = spatializedElement.ready.then((success) => {
-            if (success) {
-              return createLoadSuccessEvent(() => domProxy);
-            }
+          return promiseRef.current.then((spatializedElement) => spatializedElement.ready).then((success) => {
+            if (success) return createLoadSuccessEvent(() => domProxy);
             throw createLoadFailureEvent(() => domProxy);
           });
-          return promise;
         },
         get entityTransform() {
           return modelTransform;
@@ -1924,7 +2069,7 @@ function SpatializedStatic3DElementContainerBase(props, ref) {
         set entityTransform(value) {
           modelTransform = value;
           const spatializedElement = domProxy.__spatializedElement;
-          spatializedElement.updateModelTransform(modelTransform);
+          spatializedElement?.updateModelTransform(modelTransform);
         }
       };
     },
@@ -1933,7 +2078,7 @@ function SpatializedStatic3DElementContainerBase(props, ref) {
   return /* @__PURE__ */ jsx8(
     SpatializedContainer,
     {
-      ref: containerRef,
+      ref,
       component: "div",
       createSpatializedElement: createSpatializedElement2,
       spatializedContent: SpatializedContent2,
@@ -1995,10 +2140,10 @@ function initScene(name, callback, options) {
 import { forwardRef as forwardRef9 } from "react";
 
 // src/spatialized-container-monitor/useMonitorDomChange.tsx
-import { useRef as useRef5, useEffect as useEffect13, useMemo as useMemo4 } from "react";
+import { useRef as useRef6, useEffect as useEffect14, useMemo as useMemo4 } from "react";
 function useMonitorDomChange(inRef) {
-  const ref = useRef5(null);
-  useEffect13(() => {
+  const ref = useRef6(null);
+  useEffect14(() => {
     const observer = new MutationObserver((mutationsList) => {
       notifyDOMUpdate(mutationsList);
     });
@@ -2034,9 +2179,9 @@ function useMonitorDomChange(inRef) {
 }
 
 // src/spatialized-container-monitor/useMonitorDocumentHeaderChange.tsx
-import { useEffect as useEffect14 } from "react";
+import { useEffect as useEffect15 } from "react";
 function useMonitorDocumentHeaderChange() {
-  useEffect14(() => {
+  useEffect15(() => {
     const observer = new MutationObserver((mutationsList) => {
       notifyUpdateStandInstanceLayout();
     });
@@ -2096,17 +2241,70 @@ import { forwardRef as forwardRef11 } from "react";
 import { forwardRef as forwardRef10 } from "react";
 
 // src/reality/context/RealityContext.tsx
-import { createContext as createContext5, useContext as useContext9 } from "react";
-var RealityContext = createContext5(null);
-var useRealityContext = () => useContext9(RealityContext);
+import { createContext as createContext6, useContext as useContext10 } from "react";
+var RealityContext = createContext6(null);
+var useRealityContext = () => useContext10(RealityContext);
 
 // src/reality/context/ParentContext.tsx
-import { createContext as createContext6, useContext as useContext10 } from "react";
-var ParentContext = createContext6(null);
-var useParentContext = () => useContext10(ParentContext);
+import { createContext as createContext7, useContext as useContext11 } from "react";
+var ParentContext = createContext7(null);
+var useParentContext = () => useContext11(ParentContext);
+
+// src/reality/context/AttachmentContext.tsx
+import { createContext as createContext8, useContext as useContext12 } from "react";
+var AttachmentRegistry = class {
+  // name → (instanceId → container)
+  containers = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Map();
+  addContainer(name, instanceId, container) {
+    if (!this.containers.has(name)) {
+      this.containers.set(name, /* @__PURE__ */ new Map());
+    }
+    this.containers.get(name).set(instanceId, container);
+    this.notifyListeners(name);
+  }
+  removeContainer(name, instanceId) {
+    this.containers.get(name)?.delete(instanceId);
+    if (this.containers.get(name)?.size === 0) {
+      this.containers.delete(name);
+    }
+    this.notifyListeners(name);
+  }
+  getContainers(name) {
+    const map = this.containers.get(name);
+    if (!map) return [];
+    return Array.from(map, ([instanceId, container]) => ({
+      instanceId,
+      container
+    }));
+  }
+  onContainersChange(name, cb) {
+    const current = this.getContainers(name);
+    if (current.length > 0) {
+      cb(current);
+    }
+    const prev = this.listeners.get(name);
+    if (prev) prev([]);
+    this.listeners.set(name, cb);
+    return () => {
+      if (this.listeners.get(name) === cb) {
+        this.listeners.delete(name);
+      }
+    };
+  }
+  notifyListeners(name) {
+    const cs = this.getContainers(name);
+    this.listeners.get(name)?.(cs);
+  }
+  destroy() {
+    this.containers.clear();
+    this.listeners.clear();
+  }
+};
+var AttachmentContext = createContext8(null);
 
 // src/reality/hooks/useEntityTransform.tsx
-import { useEffect as useEffect15, useRef as useRef6 } from "react";
+import { useEffect as useEffect16, useRef as useRef7 } from "react";
 
 // src/reality/utils/ResourceRegistry.ts
 var ResourceRegistry = class {
@@ -2187,8 +2385,8 @@ var AbortResourceManager = class {
 
 // src/reality/hooks/useEntityTransform.tsx
 function useEntityTransform(entity, { position, rotation, scale }) {
-  const last = useRef6({});
-  useEffect15(() => {
+  const last = useRef7({});
+  useEffect16(() => {
     if (!entity) return;
     const shouldUpdate = !shallowEqualVec3(last.current.position, position) || !shallowEqualRotation(last.current.rotation, rotation) || !shallowEqualVec3(last.current.scale, scale);
     if (!shouldUpdate) return;
@@ -2207,7 +2405,7 @@ function useEntityTransform(entity, { position, rotation, scale }) {
 }
 
 // src/reality/hooks/useEntityEvent.tsx
-import { useEffect as useEffect17, useRef as useRef8 } from "react";
+import { useEffect as useEffect18, useRef as useRef9 } from "react";
 
 // src/reality/type.ts
 var eventMap = {
@@ -2218,19 +2416,17 @@ var eventMap = {
   onSpatialDrag: "spatialdrag",
   onSpatialDragEnd: "spatialdragend",
   // rotate
-  onSpatialRotateStart: "spatialrotatestart",
   onSpatialRotate: "spatialrotate",
   onSpatialRotateEnd: "spatialrotateend",
   // magnify
-  onSpatialMagnifyStart: "spatialmagnifystart",
   onSpatialMagnify: "spatialmagnify",
   onSpatialMagnifyEnd: "spatialmagnifyend"
 };
 
 // src/reality/hooks/useEntityRef.tsx
-import { useImperativeHandle as useImperativeHandle2 } from "react";
+import { useImperativeHandle } from "react";
 var useEntityRef = (ref, instance) => {
-  useImperativeHandle2(ref, () => instance);
+  useImperativeHandle(ref, () => instance);
 };
 var EntityRef = class {
   _entity;
@@ -2297,7 +2493,8 @@ var EntityRef = class {
   }
 };
 
-// src/reality/hooks/useEntityEvent.tsx
+// src/reality/hooks/useRealityEvents.tsx
+import { useEffect as useEffect19, useRef as useRef10 } from "react";
 function createEventProxy2(ev, instance) {
   return new Proxy(ev, {
     get(target, prop) {
@@ -2344,44 +2541,99 @@ function createEventProxy2(ev, instance) {
         }
         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 useEntityEvent = ({ instance, ...handlers }) => {
-  const eventsSetRef = useRef8(/* @__PURE__ */ new Set());
-  useEffect17(() => {
-    const entity = instance.entity;
-    if (!entity) return;
+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(createEventProxy2(ev, instance));
-      entity.addEvent(spatialEvent, wrapped);
-      eventsSetRef.current.add(reactKey);
+      instance.addEvent(spatialEvent, wrapped);
+      eventsSetRef.current.add(spatialEvent);
     });
     return () => {
-    };
-  }, [instance.entity, ...Object.values(handlers)]);
-  useEffect17(() => {
-    const entity = instance.entity;
-    if (!entity) return;
-    return () => {
-      for (let x of eventsSetRef.current) {
-        entity.removeEvent(x);
+      if (instance) {
+        for (let x of eventsSetRef.current) {
+          instance.removeEvent(x);
+        }
+        eventsSetRef.current.clear();
       }
-      eventsSetRef.current.clear();
     };
-  }, [instance.entity]);
-  return null;
+  }, [instance, ...Object.values(handlers)]);
 };
 
 // src/reality/hooks/useEntityId.tsx
-import { useEffect as useEffect18 } from "react";
+import { useEffect as useEffect20 } from "react";
 var useEntityId = ({ id, entity }) => {
   const ctx = useRealityContext();
-  useEffect18(() => {
+  useEffect20(() => {
     if (!id || !entity || !ctx) return;
     ctx.resourceRegistry.add(id, Promise.resolve(entity));
     return () => {
@@ -2392,31 +2644,21 @@ var useEntityId = ({ id, entity }) => {
 };
 
 // src/reality/hooks/useEntity.tsx
-import { useEffect as useEffect19, useRef as useRef9 } from "react";
+import { useEffect as useEffect21, useRef as useRef11 } from "react";
 var useEntity = ({
   ref,
   id,
   position,
   rotation,
   scale,
-  onSpatialTap,
-  onSpatialDragStart,
-  onSpatialDrag,
-  onSpatialDragEnd,
-  // onSpatialRotateStart,
-  onSpatialRotate,
-  onSpatialRotateEnd,
-  // onSpatialMagnifyStart,
-  onSpatialMagnify,
-  onSpatialMagnifyEnd,
-  // TODO: add other event handlers
+  enableInput,
   createEntity
 }) => {
   const ctx = useRealityContext();
   const parent = useParentContext();
-  const instanceRef = useRef9(new EntityRef(null, ctx));
+  const instanceRef = useRef11(new EntityRef(null, ctx));
   const forceUpdate = useForceUpdate2();
-  useEffect19(() => {
+  useEffect21(() => {
     if (!ctx) return;
     const controller = new AbortController();
     const init = async () => {
@@ -2449,26 +2691,20 @@ var useEntity = ({
   useEntityId({ id, entity: instanceRef.current.entity });
   useEntityTransform(instanceRef.current.entity, { position, rotation, scale });
   useEntityRef(ref, instanceRef.current);
-  useEntityEvent({
-    instance: instanceRef.current,
-    onSpatialTap,
-    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 useState8 } from "react";
+import { useCallback as useCallback7, useState as useState7 } from "react";
 var useForceUpdate2 = () => {
-  const [, setTick] = useState8(0);
+  const [, setTick] = useState7(0);
   return useCallback7(() => setTick((tick) => tick + 1), []);
 };
 
@@ -2573,11 +2809,14 @@ var BoxEntity = forwardRef13(
 );
 
 // src/reality/components/UnlitMaterial.tsx
-import { useEffect as useEffect20, useRef as useRef10 } from "react";
-var UnlitMaterial = ({ children, ...options }) => {
+import { useEffect as useEffect22, useRef as useRef12 } from "react";
+var UnlitMaterial = ({
+  children,
+  ...options
+}) => {
   const ctx = useRealityContext();
-  const materialRef = useRef10();
-  useEffect20(() => {
+  const materialRef = useRef12();
+  useEffect22(() => {
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
     const init = async () => {
@@ -2693,7 +2932,7 @@ var SceneGraph = ({ children }) => {
 };
 
 // src/reality/components/ModelAsset.tsx
-import { useEffect as useEffect21, useRef as useRef11 } from "react";
+import { useEffect as useEffect23, useRef as useRef13 } from "react";
 var resolveAssetUrl = (url) => {
   if (url.startsWith("http://") || url.startsWith("https://")) {
     return url;
@@ -2702,8 +2941,8 @@ var resolveAssetUrl = (url) => {
 };
 var ModelAsset = ({ children, ...options }) => {
   const ctx = useRealityContext();
-  const materialRef = useRef11();
-  useEffect21(() => {
+  const materialRef = useRef13();
+  useEffect23(() => {
     const controller = new AbortController();
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
@@ -2770,13 +3009,20 @@ var ModelEntity = forwardRef18(
 import {
   forwardRef as forwardRef19,
   useCallback as useCallback8,
-  useEffect as useEffect22,
-  useRef as useRef12,
-  useState as useState9
+  useEffect as useEffect24,
+  useRef as useRef14,
+  useState as useState8
 } from "react";
 import { Fragment as Fragment3, jsx as jsx22, jsxs as jsxs3 } from "react/jsx-runtime";
 var Reality = forwardRef19(
   function RealityBase({ children, ...inProps }, ref) {
+    const insideAttachment = useInsideAttachment();
+    if (insideAttachment) {
+      console.warn(
+        "[WebSpatial] Reality cannot be used inside AttachmentAsset."
+      );
+      return null;
+    }
     const {
       onSpatialTap,
       onSpatialDragStart,
@@ -2788,16 +3034,17 @@ var Reality = forwardRef19(
       onSpatialMagnifyEnd,
       ...props
     } = inProps;
-    const ctxRef = useRef12(null);
-    const creationId = useRef12(0);
-    const [isReady, setIsReady] = useState9(false);
+    const ctxRef = useRef14(null);
+    const creationId = useRef14(0);
+    const [isReady, setIsReady] = useState8(false);
     const cleanupReality = useCallback8(() => {
+      ctxRef.current?.attachmentRegistry.destroy();
       ctxRef.current?.resourceRegistry.destroy();
       ctxRef.current?.reality.destroy();
       ctxRef.current = null;
       setIsReady(false);
     }, []);
-    useEffect22(() => {
+    useEffect24(() => {
       return () => {
         creationId.current++;
         cleanupReality();
@@ -2806,15 +3053,18 @@ var Reality = forwardRef19(
     const createReality = useCallback8(async () => {
       const id = ++creationId.current;
       const resourceRegistry = new ResourceRegistry();
+      const attachmentRegistry = new AttachmentRegistry();
       const session = await getSession();
       if (!session) {
         resourceRegistry.destroy();
+        attachmentRegistry.destroy();
         return null;
       }
       const reality = await session.createSpatializedDynamic3DElement();
       const isCancelled = () => id !== creationId.current;
       if (isCancelled()) {
         resourceRegistry.destroy();
+        attachmentRegistry.destroy();
         reality.destroy();
         return null;
       }
@@ -2822,21 +3072,39 @@ var Reality = forwardRef19(
         const result = await session.getSpatialScene().addSpatializedElement(reality);
         if (!result.success || isCancelled()) {
           resourceRegistry.destroy();
+          attachmentRegistry.destroy();
           reality.destroy();
           return null;
         }
         cleanupReality();
-        ctxRef.current = { session, reality, resourceRegistry };
+        ctxRef.current = {
+          session,
+          reality,
+          resourceRegistry,
+          attachmentRegistry
+        };
         setIsReady(true);
         return reality;
       } catch (err) {
         console.error("[createReality] failed", err);
         resourceRegistry.destroy();
+        attachmentRegistry.destroy();
         reality.destroy();
         return null;
       }
     }, [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,
@@ -2853,14 +3121,146 @@ var Reality = forwardRef19(
   }
 );
 
+// src/reality/components/AttachmentAsset.tsx
+import { useEffect as useEffect25, useState as useState9 } from "react";
+import { createPortal as createPortal3 } from "react-dom";
+import { jsx as jsx23 } from "react/jsx-runtime";
+var AttachmentAsset = ({
+  name,
+  children
+}) => {
+  const ctx = useRealityContext();
+  const [containers, setContainers] = useState9([]);
+  useEffect25(() => {
+    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(
+    ({ instanceId, container }) => createPortal3(children, container, instanceId)
+  ) });
+};
+
+// src/reality/components/AttachmentEntity.tsx
+import { useEffect as useEffect26, useRef as useRef15, useState as useState10 } from "react";
+var instanceCounter = 0;
+var AttachmentEntity = ({
+  attachment: attachmentName,
+  position,
+  size
+}) => {
+  const ctx = useRealityContext();
+  const parent = useParentContext();
+  const attachmentRef = useRef15(null);
+  const parentIdRef = useRef15(null);
+  const instanceIdRef = useRef15(`att_${++instanceCounter}`);
+  const attachmentNameRef = useRef15(attachmentName);
+  const [childWindow, setChildWindow] = useState10(null);
+  useEffect26(() => {
+    if (!ctx || !parent) return;
+    if (attachmentRef.current) return;
+    const parentId = parent.id;
+    parentIdRef.current = parentId;
+    let cancelled = false;
+    const init = async () => {
+      try {
+        const att = await ctx.session.createAttachmentEntity({
+          parentEntityId: parentId,
+          position: position ?? [0, 0, 0],
+          size,
+          ownerViewId: ctx.reality.id
+        });
+        if (cancelled) {
+          att.destroy();
+          return;
+        }
+        const windowProxy = att.getWindowProxy();
+        setOpenWindowStyle(windowProxy);
+        windowProxy.document.body.style.display = "block";
+        windowProxy.document.body.style.minWidth = "100%";
+        windowProxy.document.body.style.maxWidth = "100%";
+        windowProxy.document.body.style.minHeight = "100%";
+        const viewport = windowProxy.document.querySelector(
+          'meta[name="viewport"]'
+        );
+        if (!viewport) {
+          const meta = windowProxy.document.createElement("meta");
+          meta.name = "viewport";
+          meta.content = "width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no";
+          windowProxy.document.head.appendChild(meta);
+        }
+        const base = windowProxy.document.createElement("base");
+        base.href = document.baseURI;
+        windowProxy.document.head.appendChild(base);
+        attachmentRef.current = att;
+        setChildWindow(windowProxy);
+        ctx.attachmentRegistry.addContainer(
+          attachmentNameRef.current,
+          instanceIdRef.current,
+          att.getContainer()
+        );
+      } catch (error) {
+        console.error("[AttachmentEntity] init error:", error);
+      }
+    };
+    init();
+    return () => {
+      cancelled = true;
+      const att = attachmentRef.current;
+      if (att) {
+        ctx.attachmentRegistry.removeContainer(
+          attachmentNameRef.current,
+          instanceIdRef.current
+        );
+        att.destroy();
+        attachmentRef.current = null;
+        setChildWindow(null);
+      }
+    };
+  }, [ctx, parent]);
+  useEffect26(() => {
+    if (!ctx) return;
+    const att = attachmentRef.current;
+    const prevName = attachmentNameRef.current;
+    if (att && prevName !== attachmentName) {
+      ctx.attachmentRegistry.removeContainer(prevName, instanceIdRef.current);
+      ctx.attachmentRegistry.addContainer(
+        attachmentName,
+        instanceIdRef.current,
+        att.getContainer()
+      );
+      attachmentNameRef.current = attachmentName;
+    } else {
+      attachmentNameRef.current = attachmentName;
+    }
+  }, [ctx, attachmentName]);
+  useSyncHeadStyles(childWindow, { subtree: false });
+  useEffect26(() => {
+    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 { Spatial as Spatial2 } from "@webspatial/core-sdk";
-import { jsx as jsx23 } from "react/jsx-runtime";
+import { jsx as jsx25 } from "react/jsx-runtime";
 var spatial2 = new Spatial2();
 function ModelBase(props, ref) {
+  const insideAttachment = useInsideAttachment();
   const { "enable-xr": enableXR, ...restProps } = props;
-  if (!enableXR || !spatial2.runInSpatialWeb()) {
+  if (!enableXR || !spatial2.runInSpatialWeb() || insideAttachment) {
     const {
       onSpatialTap,
       onSpatialDragStart,
@@ -2870,28 +3270,126 @@ function ModelBase(props, ref) {
       onSpatialRotateEnd,
       onSpatialMagnify,
       onSpatialMagnifyEnd,
+      spatialEventOptions: _spatialEventOptions,
       ...modelProps
     } = restProps;
-    return /* @__PURE__ */ jsx23("model", { ref, ...modelProps });
+    return /* @__PURE__ */ jsx25("model", { ref, ...modelProps });
   }
-  return /* @__PURE__ */ jsx23(SpatializedStatic3DElementContainer, { ref, ...restProps });
+  return /* @__PURE__ */ jsx25(SpatializedStatic3DElementContainer, { ref, ...restProps });
 }
 var Model = withSSRSupported(forwardRef20(ModelBase));
 Model.displayName = "Model";
 
+// src/useMetrics.tsx
+import { useSyncExternalStore } from "react";
+import { PhysicalMetrics } from "@webspatial/core-sdk";
+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.2.1";
+var version = "1.4.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,
@@ -2900,14 +3398,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