@webspatial/react-sdk 1.2.0 → 1.3.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.2.0"
+        window.__webspatialsdk__['react-sdk-version'] = "1.3.0"
         window.__webspatialsdk__['XR_ENV'] = "web"
     })()
       
@@ -849,7 +849,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/noRuntime.ts
 var Spatial = class {
@@ -1205,12 +1205,12 @@ function useSync2DFrame(spatialId, portalInstanceObject, spatializedContainerObj
 
 // src/spatialized-container/hooks/useSpatializedElement.ts
 import { useEffect as useEffect6, useState as useState3 } from "react";
-function useSpatializedElement(createSpatializedElement3, portalInstanceObject) {
+function useSpatializedElement(createSpatializedElement2, portalInstanceObject) {
   const [spatializedElement, setSpatializedElement] = useState3();
   useEffect6(() => {
     let isDestroyed = false;
     let spatializedElement2;
-    createSpatializedElement3().then(
+    createSpatializedElement2().then(
       (inSpatializedElement) => {
         if (!isDestroyed) {
           spatializedElement2 = inSpatializedElement;
@@ -1228,7 +1228,7 @@ function useSpatializedElement(createSpatializedElement3, portalInstanceObject)
         spatializedElement2 = void 0;
       }
     };
-  }, [createSpatializedElement3, portalInstanceObject]);
+  }, [createSpatializedElement2, portalInstanceObject]);
   return spatializedElement;
 }
 
@@ -1262,7 +1262,7 @@ function renderPlaceholderInSubPortal(portalInstanceObject, El) {
 function PortalSpatializedContainer(props) {
   const {
     spatializedContent: Content,
-    createSpatializedElement: createSpatializedElement3,
+    createSpatializedElement: createSpatializedElement2,
     getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
     onSpatialTap,
     onSpatialDragStart,
@@ -1296,7 +1296,7 @@ function PortalSpatializedContainer(props) {
   }, []);
   useSync2DFrame(spatialId, portalInstanceObject, spatializedContainerObject);
   const spatializedElement = useSpatializedElement(
-    createSpatializedElement3,
+    createSpatializedElement2,
     portalInstanceObject
   );
   const PlaceholderEl = renderPlaceholderInSubPortal(
@@ -1349,8 +1349,13 @@ function PortalSpatializedContainer(props) {
   ] });
 }
 
+// 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") {
@@ -1371,18 +1376,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;
@@ -1391,13 +1428,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,
@@ -1405,7 +1456,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,
@@ -1413,7 +1474,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,
@@ -1424,7 +1496,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,
@@ -1453,9 +1528,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
@@ -1473,9 +1548,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), []);
@@ -1511,33 +1586,48 @@ 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,
+    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: createSpatializedElement3,
-      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(() => {
@@ -1596,7 +1686,7 @@ function SpatializedContainerBase(inprops, ref) {
       }, [spatialContainerRefProxy.current]);
       const {
         spatializedContent,
-        createSpatializedElement: createSpatializedElement3,
+        createSpatializedElement: createSpatializedElement2,
         getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
         ...restProps
       } = props;
@@ -1646,7 +1736,7 @@ function SpatializedContainerBase(inprops, ref) {
     );
     const {
       spatializedContent,
-      createSpatializedElement: createSpatializedElement3,
+      createSpatializedElement: createSpatializedElement2,
       getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
       ...restProps
     } = props;
@@ -1691,28 +1781,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";
@@ -1724,23 +1833,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 = {
@@ -1766,19 +1970,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
@@ -1788,11 +1981,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(
@@ -1817,14 +2012,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");
@@ -1854,9 +2049,10 @@ var Spatialized2DElementContainer = forwardRef5(
 import {
   forwardRef as forwardRef6,
   useCallback as useCallback6,
-  useContext as useContext8,
-  useEffect as useEffect12,
-  useMemo as useMemo3
+  useContext as useContext9,
+  useEffect as useEffect13,
+  useMemo as useMemo3,
+  useRef as useRef4
 } from "react";
 import { Fragment as Fragment2, jsx as jsx8 } from "react/jsx-runtime";
 function getAbsoluteURL(url) {
@@ -1893,16 +2089,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(
@@ -1915,7 +2111,7 @@ function SpatializedContent2(props) {
       spatializedStatic3DElement.onLoadCallback = void 0;
     }
   }, [onLoad]);
-  useEffect12(() => {
+  useEffect13(() => {
     if (onError) {
       spatializedStatic3DElement.onLoadFailureCallback = () => {
         onError(
@@ -1930,10 +2126,13 @@ function SpatializedContent2(props) {
   }, [onError]);
   return /* @__PURE__ */ jsx8(Fragment2, {});
 }
-async function createSpatializedElement2() {
-  return getSession().createSpatializedStatic3DElement();
-}
 function SpatializedStatic3DElementContainerBase(props, ref) {
+  const promiseRef = useRef4(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();
@@ -1942,14 +2141,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;
@@ -1957,7 +2152,7 @@ function SpatializedStatic3DElementContainerBase(props, ref) {
         set entityTransform(value) {
           modelTransform = value;
           const spatializedElement = domProxy.__spatializedElement;
-          spatializedElement.updateModelTransform(modelTransform);
+          spatializedElement?.updateModelTransform(modelTransform);
         }
       };
     },
@@ -2028,10 +2223,10 @@ function initScene(name, callback) {
 import { forwardRef as forwardRef9 } from "react";
 
 // src/spatialized-container-monitor/useMonitorDomChange.tsx
-import { useRef as useRef4, useEffect as useEffect13, useMemo as useMemo4 } from "react";
+import { useRef as useRef5, useEffect as useEffect14, useMemo as useMemo4 } from "react";
 function useMonitorDomChange(inRef) {
-  const ref = useRef4(null);
-  useEffect13(() => {
+  const ref = useRef5(null);
+  useEffect14(() => {
     const observer = new MutationObserver((mutationsList) => {
       notifyDOMUpdate(mutationsList);
     });
@@ -2067,9 +2262,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();
     });
@@ -2129,17 +2324,66 @@ 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);
+    return map ? Array.from(map.values()) : [];
+  }
+  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 useRef5 } from "react";
+import { useEffect as useEffect16, useRef as useRef6 } from "react";
 
 // src/reality/utils/ResourceRegistry.ts
 var ResourceRegistry = class {
@@ -2220,8 +2464,8 @@ var AbortResourceManager = class {
 
 // src/reality/hooks/useEntityTransform.tsx
 function useEntityTransform(entity, { position, rotation, scale }) {
-  const last = useRef5({});
-  useEffect15(() => {
+  const last = useRef6({});
+  useEffect16(() => {
     if (!entity) return;
     const shouldUpdate = !shallowEqualVec3(last.current.position, position) || !shallowEqualRotation(last.current.rotation, rotation) || !shallowEqualVec3(last.current.scale, scale);
     if (!shouldUpdate) return;
@@ -2240,7 +2484,7 @@ function useEntityTransform(entity, { position, rotation, scale }) {
 }
 
 // src/reality/hooks/useEntityEvent.tsx
-import { useEffect as useEffect17, useRef as useRef7 } from "react";
+import { useEffect as useEffect18, useRef as useRef8 } from "react";
 
 // src/reality/type.ts
 var eventMap = {
@@ -2377,14 +2621,75 @@ 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 = useRef7(/* @__PURE__ */ new Set());
-  useEffect17(() => {
+  const eventsSetRef = useRef8(/* @__PURE__ */ new Set());
+  useEffect18(() => {
     const entity = instance.entity;
     if (!entity) return;
     Object.entries(eventMap).forEach(([reactKey, spatialEvent]) => {
@@ -2397,7 +2702,7 @@ var useEntityEvent = ({ instance, ...handlers }) => {
     return () => {
     };
   }, [instance.entity, ...Object.values(handlers)]);
-  useEffect17(() => {
+  useEffect18(() => {
     const entity = instance.entity;
     if (!entity) return;
     return () => {
@@ -2411,10 +2716,10 @@ var useEntityEvent = ({ instance, ...handlers }) => {
 };
 
 // src/reality/hooks/useEntityId.tsx
-import { useEffect as useEffect18 } from "react";
+import { useEffect as useEffect19 } from "react";
 var useEntityId = ({ id, entity }) => {
   const ctx = useRealityContext();
-  useEffect18(() => {
+  useEffect19(() => {
     if (!id || !entity || !ctx) return;
     ctx.resourceRegistry.add(id, Promise.resolve(entity));
     return () => {
@@ -2425,7 +2730,7 @@ var useEntityId = ({ id, entity }) => {
 };
 
 // src/reality/hooks/useEntity.tsx
-import { useEffect as useEffect19, useRef as useRef8 } from "react";
+import { useEffect as useEffect20, useRef as useRef9 } from "react";
 var useEntity = ({
   ref,
   id,
@@ -2447,9 +2752,9 @@ var useEntity = ({
 }) => {
   const ctx = useRealityContext();
   const parent = useParentContext();
-  const instanceRef = useRef8(new EntityRef(null, ctx));
+  const instanceRef = useRef9(new EntityRef(null, ctx));
   const forceUpdate = useForceUpdate2();
-  useEffect19(() => {
+  useEffect20(() => {
     if (!ctx) return;
     const controller = new AbortController();
     const init = async () => {
@@ -2606,11 +2911,11 @@ var BoxEntity = forwardRef13(
 );
 
 // src/reality/components/UnlitMaterial.tsx
-import { useEffect as useEffect20, useRef as useRef9 } from "react";
+import { useEffect as useEffect21, useRef as useRef10 } from "react";
 var UnlitMaterial = ({ children, ...options }) => {
   const ctx = useRealityContext();
-  const materialRef = useRef9();
-  useEffect20(() => {
+  const materialRef = useRef10();
+  useEffect21(() => {
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
     const init = async () => {
@@ -2726,7 +3031,7 @@ var SceneGraph = ({ children }) => {
 };
 
 // src/reality/components/ModelAsset.tsx
-import { useEffect as useEffect21, useRef as useRef10 } from "react";
+import { useEffect as useEffect22, useRef as useRef11 } from "react";
 var resolveAssetUrl = (url) => {
   if (url.startsWith("http://") || url.startsWith("https://")) {
     return url;
@@ -2735,8 +3040,8 @@ var resolveAssetUrl = (url) => {
 };
 var ModelAsset = ({ children, ...options }) => {
   const ctx = useRealityContext();
-  const materialRef = useRef10();
-  useEffect21(() => {
+  const materialRef = useRef11();
+  useEffect22(() => {
     const controller = new AbortController();
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
@@ -2803,13 +3108,20 @@ var ModelEntity = forwardRef18(
 import {
   forwardRef as forwardRef19,
   useCallback as useCallback8,
-  useEffect as useEffect22,
-  useRef as useRef11,
+  useEffect as useEffect23,
+  useRef as useRef12,
   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,
@@ -2821,16 +3133,17 @@ var Reality = forwardRef19(
       onSpatialMagnifyEnd,
       ...props
     } = inProps;
-    const ctxRef = useRef11(null);
-    const creationId = useRef11(0);
+    const ctxRef = useRef12(null);
+    const creationId = useRef12(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(() => {
+    useEffect23(() => {
       return () => {
         creationId.current++;
         cleanupReality();
@@ -2839,15 +3152,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;
       }
@@ -2855,16 +3171,23 @@ 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;
       }
@@ -2886,13 +3209,132 @@ var Reality = forwardRef19(
   }
 );
 
+// src/reality/components/AttachmentAsset.tsx
+import { useEffect as useEffect24, 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([]);
+  useEffect24(() => {
+    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}`)) });
+};
+
+// src/reality/components/AttachmentEntity.tsx
+import { useEffect as useEffect25, useRef as useRef13, useState as useState10 } from "react";
+var instanceCounter = 0;
+var AttachmentEntity = ({
+  attachment: attachmentName,
+  position,
+  size
+}) => {
+  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(() => {
+    if (!ctx || !parent) 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
+        });
+        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%";
+        await syncParentHeadToChild(windowProxy);
+        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]);
+  useEffect25(() => {
+    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 });
+  useEffect25(() => {
+    if (!attachmentRef.current) return;
+    attachmentRef.current.update({ position, size });
+  }, [position?.[0], position?.[1], position?.[2], size?.width, size?.height]);
+  return null;
+};
+
 // src/Model.tsx
 import { forwardRef as forwardRef20 } from "react";
-import { jsx as jsx23 } from "react/jsx-runtime";
+import { jsx as jsx24 } from "react/jsx-runtime";
 var spatial2 = new Spatial();
 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,
@@ -2904,19 +3346,21 @@ function ModelBase(props, ref) {
       onSpatialMagnifyEnd,
       ...modelProps
     } = restProps;
-    return /* @__PURE__ */ jsx23("model", { ref, ...modelProps });
+    return /* @__PURE__ */ jsx24("model", { ref, ...modelProps });
   }
-  return /* @__PURE__ */ jsx23(SpatializedStatic3DElementContainer, { ref, ...restProps });
+  return /* @__PURE__ */ jsx24(SpatializedStatic3DElementContainer, { ref, ...restProps });
 }
 var Model = withSSRSupported(forwardRef20(ModelBase));
 Model.displayName = "Model";
 
 // src/index.ts
-var version = "1.2.0";
+var version = "1.3.0";
 if (typeof window !== "undefined") {
   initPolyfill();
 }
 export {
+  AttachmentAsset,
+  AttachmentEntity,
   BoxEntity,
   ConeEntity,
   CylinderEntity,