@webspatial/react-sdk 1.2.1 → 1.3.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.3.0"
         window.__webspatialsdk__['XR_ENV'] = "avp"
     })()
       
@@ -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/utils/getSession.ts
 import { isSSREnv, Spatial } from "@webspatial/core-sdk";
@@ -1308,8 +1308,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") {
@@ -1330,18 +1335,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 +1387,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 +1415,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 +1433,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 +1455,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 +1487,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 +1507,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 +1545,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: 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(() => {
@@ -1650,28 +1740,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);
     };
-    n.onload = function() {
-      resolve(true);
+    link.onerror = () => {
+      finish(false);
+    };
+    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 +1792,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 +1929,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 +1940,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 +1971,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,11 +2008,9 @@ 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
 } from "react";
 import { Fragment as Fragment2, jsx as jsx8 } from "react/jsx-runtime";
@@ -1855,16 +2048,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 +2070,7 @@ function SpatializedContent2(props) {
       spatializedStatic3DElement.onLoadCallback = void 0;
     }
   }, [onLoad]);
-  useEffect12(() => {
+  useEffect13(() => {
     if (onError) {
       spatializedStatic3DElement.onLoadFailureCallback = () => {
         onError(
@@ -1893,14 +2086,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 = 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();
@@ -1909,14 +2100,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 +2111,7 @@ function SpatializedStatic3DElementContainerBase(props, ref) {
         set entityTransform(value) {
           modelTransform = value;
           const spatializedElement = domProxy.__spatializedElement;
-          spatializedElement.updateModelTransform(modelTransform);
+          spatializedElement?.updateModelTransform(modelTransform);
         }
       };
     },
@@ -1933,7 +2120,7 @@ function SpatializedStatic3DElementContainerBase(props, ref) {
   return /* @__PURE__ */ jsx8(
     SpatializedContainer,
     {
-      ref: containerRef,
+      ref,
       component: "div",
       createSpatializedElement: createSpatializedElement2,
       spatializedContent: SpatializedContent2,
@@ -1995,10 +2182,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 useRef5, useEffect as useEffect14, useMemo as useMemo4 } from "react";
 function useMonitorDomChange(inRef) {
   const ref = useRef5(null);
-  useEffect13(() => {
+  useEffect14(() => {
     const observer = new MutationObserver((mutationsList) => {
       notifyDOMUpdate(mutationsList);
     });
@@ -2034,9 +2221,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 +2283,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 useRef6 } from "react";
+import { useEffect as useEffect16, useRef as useRef6 } from "react";
 
 // src/reality/utils/ResourceRegistry.ts
 var ResourceRegistry = class {
@@ -2188,7 +2424,7 @@ var AbortResourceManager = class {
 // src/reality/hooks/useEntityTransform.tsx
 function useEntityTransform(entity, { position, rotation, scale }) {
   const last = useRef6({});
-  useEffect15(() => {
+  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 +2443,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 useRef8 } from "react";
 
 // src/reality/type.ts
 var eventMap = {
@@ -2228,9 +2464,9 @@ var eventMap = {
 };
 
 // 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;
@@ -2344,6 +2580,67 @@ 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;
     }
@@ -2351,7 +2648,7 @@ function createEventProxy2(ev, instance) {
 }
 var useEntityEvent = ({ instance, ...handlers }) => {
   const eventsSetRef = useRef8(/* @__PURE__ */ new Set());
-  useEffect17(() => {
+  useEffect18(() => {
     const entity = instance.entity;
     if (!entity) return;
     Object.entries(eventMap).forEach(([reactKey, spatialEvent]) => {
@@ -2364,7 +2661,7 @@ var useEntityEvent = ({ instance, ...handlers }) => {
     return () => {
     };
   }, [instance.entity, ...Object.values(handlers)]);
-  useEffect17(() => {
+  useEffect18(() => {
     const entity = instance.entity;
     if (!entity) return;
     return () => {
@@ -2378,10 +2675,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 () => {
@@ -2392,7 +2689,7 @@ var useEntityId = ({ id, entity }) => {
 };
 
 // src/reality/hooks/useEntity.tsx
-import { useEffect as useEffect19, useRef as useRef9 } from "react";
+import { useEffect as useEffect20, useRef as useRef9 } from "react";
 var useEntity = ({
   ref,
   id,
@@ -2416,7 +2713,7 @@ var useEntity = ({
   const parent = useParentContext();
   const instanceRef = useRef9(new EntityRef(null, ctx));
   const forceUpdate = useForceUpdate2();
-  useEffect19(() => {
+  useEffect20(() => {
     if (!ctx) return;
     const controller = new AbortController();
     const init = async () => {
@@ -2466,9 +2763,9 @@ var useEntity = ({
 };
 
 // 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 +2870,11 @@ var BoxEntity = forwardRef13(
 );
 
 // src/reality/components/UnlitMaterial.tsx
-import { useEffect as useEffect20, useRef as useRef10 } from "react";
+import { useEffect as useEffect21, useRef as useRef10 } from "react";
 var UnlitMaterial = ({ children, ...options }) => {
   const ctx = useRealityContext();
   const materialRef = useRef10();
-  useEffect20(() => {
+  useEffect21(() => {
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
     const init = async () => {
@@ -2693,7 +2990,7 @@ var SceneGraph = ({ children }) => {
 };
 
 // src/reality/components/ModelAsset.tsx
-import { useEffect as useEffect21, useRef as useRef11 } from "react";
+import { useEffect as useEffect22, useRef as useRef11 } from "react";
 var resolveAssetUrl = (url) => {
   if (url.startsWith("http://") || url.startsWith("https://")) {
     return url;
@@ -2703,7 +3000,7 @@ var resolveAssetUrl = (url) => {
 var ModelAsset = ({ children, ...options }) => {
   const ctx = useRealityContext();
   const materialRef = useRef11();
-  useEffect21(() => {
+  useEffect22(() => {
     const controller = new AbortController();
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
@@ -2770,13 +3067,20 @@ var ModelEntity = forwardRef18(
 import {
   forwardRef as forwardRef19,
   useCallback as useCallback8,
-  useEffect as useEffect22,
+  useEffect as useEffect23,
   useRef as useRef12,
-  useState as useState9
+  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,
@@ -2790,14 +3094,15 @@ var Reality = forwardRef19(
     } = inProps;
     const ctxRef = useRef12(null);
     const creationId = useRef12(0);
-    const [isReady, setIsReady] = useState9(false);
+    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();
@@ -2806,15 +3111,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,16 +3130,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;
       }
@@ -2853,14 +3168,133 @@ 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 { Spatial as Spatial2 } from "@webspatial/core-sdk";
-import { jsx as jsx23 } from "react/jsx-runtime";
+import { jsx as jsx24 } 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,
@@ -2872,19 +3306,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.1";
+var version = "1.3.0";
 if (typeof window !== "undefined") {
   initPolyfill();
 }
 export {
+  AttachmentAsset,
+  AttachmentEntity,
   BoxEntity,
   ConeEntity,
   CylinderEntity,