@webspatial/react-sdk 1.6.1 → 1.7.0

package/dist/default/index.js

@@ -2,498 +2,17 @@
       (function(){
         if(typeof window === 'undefined') return;
         if(!window.__webspatialsdk__) window.__webspatialsdk__ = {}
-        window.__webspatialsdk__['react-sdk-version'] = "1.6.1"
+        window.__webspatialsdk__['react-sdk-version'] = "1.7.0"
         window.__webspatialsdk__['XR_ENV'] = "avp"
     })()
       
 
-// src/spatialized-container/hooks/useDomProxy.ts
-import { useCallback, useEffect, useRef } from "react";
-
-// src/spatialized-container/types.ts
-var SpatialCustomStyleVars = {
-  back: "--xr-back",
-  depth: "--xr-depth",
-  backgroundMaterial: "--xr-background-material",
-  xrZIndex: "--xr-z-index"
-};
-
-// src/spatialized-container/utils.ts
-function getInheritedStyleProps(computedStyle) {
-  var propNames = [
-    "azimuth",
-    "borderCollapse",
-    "borderSpacing",
-    "captionSide",
-    "color",
-    "cursor",
-    "direction",
-    // 'elevation',
-    "emptyCells",
-    "fontFamily",
-    "fontSize",
-    "fontStyle",
-    "fontVariant",
-    "fontWeight",
-    "font",
-    "letterSpacing",
-    "lineHeight",
-    "listStyleImage",
-    "listStylePosition",
-    "listStyleType",
-    "listStyle",
-    "orphans",
-    // 'pitchRange',
-    // 'pitch',
-    "quotes",
-    // 'richness',
-    // 'speakHeader',
-    // 'speakNumeral',
-    // 'speakPunctuation',
-    // 'speak',
-    // 'speechRate',
-    // 'stress',
-    "textAlign",
-    "textIndent",
-    "textTransform",
-    "visibility",
-    // 'voiceFamily',
-    // 'volume',
-    "whiteSpace",
-    "widows",
-    "wordSpacing",
-    // background also need to be synced
-    "background",
-    // position also need to be synced
-    "position",
-    "width",
-    "height",
-    "display",
-    // content-visibility also need to be synced
-    "contentVisibility"
-  ];
-  var props = {};
-  for (var cssName of propNames) {
-    if (computedStyle[cssName]) {
-      props[cssName] = computedStyle[cssName];
-    }
-  }
-  return props;
-}
-function parseTransformOrigin(computedStyle) {
-  const transformOriginProperty = computedStyle.getPropertyValue("transform-origin");
-  const [x, y] = transformOriginProperty.split(" ").map(parseFloat);
-  const width = parseFloat(computedStyle.getPropertyValue("width"));
-  const height = parseFloat(computedStyle.getPropertyValue("height"));
-  return {
-    x: width > 0 ? x / width : 0.5,
-    y: height > 0 ? y / height : 0.5,
-    z: 0.5
-  };
-}
-function parseBorderRadius(borderProperty, width) {
-  if (borderProperty === "") {
-    return 0;
-  }
-  if (borderProperty.endsWith("%")) {
-    return width * parseFloat(borderProperty) / 100;
-  }
-  return parseFloat(borderProperty);
-}
-function parseCornerRadius(computedStyle) {
-  const width = parseFloat(computedStyle.getPropertyValue("width"));
-  const topLeftPropertyValue = computedStyle.getPropertyValue(
-    "border-top-left-radius"
-  );
-  const topRightPropertyValue = computedStyle.getPropertyValue(
-    "border-top-right-radius"
-  );
-  const bottomLeftPropertyValue = computedStyle.getPropertyValue(
-    "border-bottom-left-radius"
-  );
-  const bottomRightPropertyValue = computedStyle.getPropertyValue(
-    "border-bottom-right-radius"
-  );
-  const cornerRadius = {
-    topLeading: parseBorderRadius(topLeftPropertyValue, width),
-    bottomLeading: parseBorderRadius(bottomLeftPropertyValue, width),
-    topTrailing: parseBorderRadius(topRightPropertyValue, width),
-    bottomTrailing: parseBorderRadius(bottomRightPropertyValue, width)
-  };
-  return cornerRadius;
-}
-function extractAndRemoveCustomProperties(cssText, properties) {
-  if (!cssText) {
-    return { extractedValues: {}, filteredCssText: "" };
-  }
-  const extractedValues = {};
-  const rules = cssText.split(";");
-  const filteredRules = rules.filter((rule) => {
-    const [key, value] = rule.split(":").map((part) => part.trim());
-    if (properties.includes(key)) {
-      extractedValues[key] = value;
-      return false;
-    }
-    return true;
-  });
-  const filteredCssText = filteredRules.join(";").trim();
-  return { extractedValues, filteredCssText };
-}
-function joinToCSSText(cssKV) {
-  const rules = Object.entries(cssKV).map(([key, value]) => `${key}: ${value}`);
-  return rules.join(";");
-}
-
-// src/spatialized-container/hooks/useDomProxy.ts
-var SpatialContainerRefProxy = class {
-  transformVisibilityTaskContainerDom = null;
-  /** Raw Standard host element (styled root). Used to mirror class onto the transform probe. */
-  standardRawDom = null;
-  standardClassObserver = null;
-  /**
-   * When set, Standard's DOM className is forwarded here so TransformVisibilityTaskContainer
-   * can render it from React state (avoids React clobbering imperative class updates).
-   */
-  mirrorClassNotify = null;
-  /** Last class string applied to the probe + used to skip redundant syncs. */
-  lastMirroredClassName = null;
-  /** Coalesce multiple class sync triggers in the same turn (Observer + classList, etc.). */
-  classSyncMicrotaskQueued = false;
-  ref;
-  domProxy;
-  styleProxy;
-  // extre ref props, used to add extra props to ref
-  extraRefProps;
-  constructor(ref, extraRefProps) {
-    this.ref = ref;
-    this.extraRefProps = extraRefProps;
-  }
-  setMirrorClassNotify(fn) {
-    this.mirrorClassNotify = fn;
-    if (fn && this.standardRawDom) {
-      this.flushSyncTransformClassFromStandard(true);
-    }
-  }
-  disconnectStandardClassObserver() {
-    this.standardClassObserver?.disconnect();
-    this.standardClassObserver = null;
-  }
-  attachStandardClassObserver() {
-    this.disconnectStandardClassObserver();
-    if (!this.standardRawDom) {
-      return;
-    }
-    this.standardClassObserver = new MutationObserver(() => {
-      this.scheduleSyncTransformClassFromStandard();
-    });
-    this.standardClassObserver.observe(this.standardRawDom, {
-      attributes: true,
-      attributeFilter: ["class"]
-    });
-  }
-  /**
-   * Merge multiple sync requests (e.g. classList hook + MutationObserver) into one microtask.
-   */
-  scheduleSyncTransformClassFromStandard() {
-    if (this.classSyncMicrotaskQueued) {
-      return;
-    }
-    this.classSyncMicrotaskQueued = true;
-    queueMicrotask(() => {
-      this.classSyncMicrotaskQueued = false;
-      this.flushSyncTransformClassFromStandard(false);
-    });
-  }
-  /**
-   * Source of truth: Standard host DOM (incl. styled-components runtime class changes).
-   * @param force when true, skip same-string short-circuit (e.g. mirror notify just registered).
-   */
-  flushSyncTransformClassFromStandard(force) {
-    if (!this.standardRawDom) {
-      return;
-    }
-    const name = this.standardRawDom.className;
-    const probe = this.transformVisibilityTaskContainerDom;
-    if (!force && probe && probe.className === name && this.lastMirroredClassName === name) {
-      return;
-    }
-    this.lastMirroredClassName = name;
-    if (probe) {
-      probe.className = name;
-    }
-    this.mirrorClassNotify?.(name);
-  }
-  updateStandardSpatializedContainerDom(dom) {
-    const self = this;
-    if (!dom) {
-      this.disconnectStandardClassObserver();
-      this.standardRawDom = null;
-      this.lastMirroredClassName = null;
-      this.domProxy = void 0;
-      this.styleProxy = void 0;
-      this.updateDomProxyToRef();
-      return;
-    }
-    this.standardRawDom = dom;
-    let cacheExtraRefProps;
-    const domProxy = new Proxy(
-      dom,
-      {
-        get(target, prop) {
-          if (prop === "__raw") {
-            return target;
-          }
-          if (prop === "xrClientDepth") {
-            return target.style.getPropertyValue(SpatialCustomStyleVars.depth);
-          }
-          if (prop === "xrOffsetBack") {
-            return target.style.getPropertyValue(SpatialCustomStyleVars.back);
-          }
-          if (prop === "style") {
-            if (!self.styleProxy) {
-              self.styleProxy = new Proxy(target.style, {
-                get(target2, prop2) {
-                  if (prop2 === "visibility" || prop2 === "transform") {
-                    return self.transformVisibilityTaskContainerDom?.style.getPropertyValue(
-                      prop2
-                    );
-                  }
-                  const value2 = Reflect.get(target2, prop2);
-                  if (typeof value2 === "function") {
-                    if (prop2 === "setProperty" || prop2 === "removeProperty" || prop2 === "getPropertyValue") {
-                      return function(...args) {
-                        const validProperties = ["visibility", "transform"];
-                        const [property] = args;
-                        if (validProperties.includes(property)) {
-                          if (prop2 === "setProperty") {
-                            const [, kValue] = args;
-                            self.transformVisibilityTaskContainerDom?.style.setProperty(
-                              property,
-                              kValue
-                            );
-                          } else if (prop2 === "removeProperty") {
-                            self.transformVisibilityTaskContainerDom?.style.removeProperty(
-                              property
-                            );
-                          } else if (prop2 === "getPropertyValue") {
-                            return self.transformVisibilityTaskContainerDom?.style.getPropertyValue(
-                              property
-                            );
-                          }
-                        } else {
-                          return value2.apply(this, args);
-                        }
-                      }.bind(target2);
-                    } else {
-                      return value2.bind(target2);
-                    }
-                  } else {
-                    return value2;
-                  }
-                },
-                set(target2, prop2, value2) {
-                  if (prop2 === "visibility") {
-                    self.transformVisibilityTaskContainerDom?.style.setProperty(
-                      "visibility",
-                      value2
-                    );
-                    return true;
-                  }
-                  if (prop2 === "transform") {
-                    self.transformVisibilityTaskContainerDom?.style.setProperty(
-                      "transform",
-                      value2
-                    );
-                    return true;
-                  }
-                  if (prop2 === SpatialCustomStyleVars.backgroundMaterial) {
-                    target2.setProperty(
-                      SpatialCustomStyleVars.backgroundMaterial,
-                      value2
-                    );
-                  } else if (prop2 === SpatialCustomStyleVars.back) {
-                    target2.setProperty(
-                      SpatialCustomStyleVars.back,
-                      value2
-                    );
-                  } else if (prop2 === SpatialCustomStyleVars.xrZIndex) {
-                    target2.setProperty(
-                      SpatialCustomStyleVars.xrZIndex,
-                      value2
-                    );
-                  } else if (prop2 === SpatialCustomStyleVars.depth) {
-                    target2.setProperty(
-                      SpatialCustomStyleVars.depth,
-                      value2
-                    );
-                  } else if (prop2 === "cssText") {
-                    const toFilteredCSSProperties = ["transform", "visibility"];
-                    const { extractedValues, filteredCssText } = extractAndRemoveCustomProperties(
-                      value2,
-                      toFilteredCSSProperties
-                    );
-                    toFilteredCSSProperties.forEach((key) => {
-                      if (extractedValues[key]) {
-                        self.transformVisibilityTaskContainerDom?.style.setProperty(
-                          key,
-                          extractedValues[key]
-                        );
-                      } else {
-                        target2.removeProperty(key);
-                      }
-                    });
-                    const appendedCSSText = joinToCSSText({
-                      transform: "none",
-                      visibility: "hidden"
-                    });
-                    return Reflect.set(
-                      target2,
-                      prop2,
-                      [appendedCSSText, filteredCssText].join(";")
-                    );
-                  }
-                  return Reflect.set(target2, prop2, value2);
-                }
-              });
-            }
-            return self.styleProxy;
-          }
-          if (typeof prop === "string" && self.extraRefProps) {
-            if (!cacheExtraRefProps) {
-              cacheExtraRefProps = self.extraRefProps(domProxy);
-            }
-            const extraProps = cacheExtraRefProps;
-            if (extraProps.hasOwnProperty(prop)) {
-              return extraProps[prop];
-            }
-          }
-          const value = Reflect.get(target, prop);
-          if (typeof value === "function") {
-            if ("removeAttribute" === prop) {
-              return function(...args) {
-                const [property] = args;
-                if (property === "style") {
-                  dom.style.cssText = "visibility: hidden; transition: none; transform: none;";
-                  if (self.transformVisibilityTaskContainerDom) {
-                    self.transformVisibilityTaskContainerDom.style.visibility = "";
-                    self.transformVisibilityTaskContainerDom.style.transform = "";
-                  }
-                  return true;
-                }
-                if (property === "class") {
-                  domProxy.className = "xr-spatial-default";
-                  return true;
-                }
-              };
-            }
-            return value.bind(target);
-          }
-          return value;
-        },
-        set(target, prop, value) {
-          if (prop === "className") {
-            if (value && String(value).indexOf("xr-spatial-default") === -1) {
-              value = value + " xr-spatial-default";
-            }
-          }
-          if (typeof prop === "string" && self.extraRefProps) {
-            if (!cacheExtraRefProps) {
-              cacheExtraRefProps = self.extraRefProps(domProxy);
-            }
-            cacheExtraRefProps[prop] = value;
-          }
-          const ok = Reflect.set(target, prop, value);
-          if (ok && prop === "className") {
-            self.scheduleSyncTransformClassFromStandard();
-          }
-          return ok;
-        }
-      }
-    );
-    this.domProxy = domProxy;
-    this.styleProxy = void 0;
-    this.updateDomProxyToRef();
-    Object.assign(dom, {
-      __targetProxy: domProxy
-    });
-    this.attachStandardClassObserver();
-    this.scheduleSyncTransformClassFromStandard();
-  }
-  updateTransformVisibilityTaskContainerDom(dom) {
-    this.transformVisibilityTaskContainerDom = dom;
-    if (!dom) {
-      this.lastMirroredClassName = null;
-    }
-    this.scheduleSyncTransformClassFromStandard();
-    this.updateDomProxyToRef();
-  }
-  updateDomProxyToRef() {
-    const ref = this.ref;
-    if (!ref) {
-      return;
-    }
-    if (this.domProxy && this.transformVisibilityTaskContainerDom) {
-      if (typeof ref === "function") {
-        ref(this.domProxy);
-      } else {
-        ref.current = this.domProxy;
-      }
-    } else {
-      if (typeof ref === "function") {
-        ref(null);
-      } else {
-        ref.current = null;
-      }
-    }
-  }
-  updateRef(ref) {
-    this.ref = ref;
-  }
-};
-function hijackGetComputedStyle() {
-  const rawFn = window.getComputedStyle.bind(window);
-  window.getComputedStyle = (element, pseudoElt) => {
-    const dom = element.__raw;
-    if (dom) {
-      return rawFn(dom, pseudoElt);
-    }
-    return rawFn(element, pseudoElt);
-  };
-}
-function useDomProxy(ref, extraRefProps) {
-  const spatialContainerRefProxy = useRef(
-    new SpatialContainerRefProxy(ref, extraRefProps)
-  );
-  useEffect(() => {
-    spatialContainerRefProxy.current.updateRef(ref);
-  }, [ref]);
-  const transformVisibilityTaskContainerCallback = useCallback(
-    (el) => {
-      spatialContainerRefProxy.current.updateTransformVisibilityTaskContainerDom(
-        el
-      );
-    },
-    []
-  );
-  const standardSpatializedContainerCallback = useCallback(
-    (el) => {
-      spatialContainerRefProxy.current.updateStandardSpatializedContainerDom(el);
-    },
-    []
-  );
-  return {
-    transformVisibilityTaskContainerCallback,
-    standardSpatializedContainerCallback,
-    spatialContainerRefProxy
-  };
-}
-
 // src/spatialized-container/hooks/use2DFrameDetector.ts
 import {
   useContext,
   useLayoutEffect,
-  useEffect as useEffect2,
-  useCallback as useCallback2
+  useEffect,
+  useCallback
 } from "react";
 
 // src/spatialized-container/context/SpatializedContainerContext.ts
@@ -620,11 +139,11 @@ function use2DFrameDetector(ref) {
   const spatializedContainerObject = useContext(
     SpatializedContainerContext
   );
-  const notify2DFrameChange = useCallback2(() => {
+  const notify2DFrameChange = useCallback(() => {
     ref.current && spatializedContainerObject.notify2DFramePlaceHolderChange(ref.current);
   }, [ref.current, spatializedContainerObject]);
   useLayoutEffect(notify2DFrameChange, [notify2DFrameChange]);
-  useEffect2(() => {
+  useEffect(() => {
     if (!ref.current || !spatializedContainerObject) {
       console.warn(
         "Ref is not attached to the DOM or spatializedContainerObject is not available"
@@ -636,7 +155,7 @@ function use2DFrameDetector(ref) {
       window.removeEventListener("resize", notify2DFrameChange);
     };
   }, []);
-  useEffect2(() => {
+  useEffect(() => {
     if (!ref.current) {
       console.warn("Ref is not attached to the DOM");
       return;
@@ -647,7 +166,7 @@ function use2DFrameDetector(ref) {
       ro.disconnect();
     };
   }, []);
-  useEffect2(() => {
+  useEffect(() => {
     if (!ref.current) {
       console.warn("Ref is not attached to the DOM");
       return;
@@ -666,17 +185,17 @@ function use2DFrameDetector(ref) {
 // src/spatialized-container/StandardSpatializedContainer.tsx
 import {
   forwardRef,
-  useCallback as useCallback3,
+  useCallback as useCallback2,
   useContext as useContext2,
-  useEffect as useEffect3,
-  useRef as useRef2,
+  useEffect as useEffect2,
+  useRef,
   useState
 } from "react";
 import { jsx } from "react/jsx-runtime";
 function useSpatialTransformVisibilityWatcher(spatialId) {
   const [transformExist, setTransformExist] = useState(false);
   const spatializedContainerObject = useContext2(SpatializedContainerContext);
-  useEffect3(() => {
+  useEffect2(() => {
     const fn = (spatialTransform) => {
       setTransformExist(spatialTransform.transform !== "none");
     };
@@ -691,8 +210,8 @@ function useSpatialTransformVisibilityWatcher(spatialId) {
   return transformExist;
 }
 function useInternalRef(ref) {
-  const refInternal = useRef2(null);
-  const refInternalCallback = useCallback3(
+  const refInternal = useRef(null);
+  const refInternalCallback = useCallback2(
     (node) => {
       refInternal.current = node;
       if (typeof ref === "function") {
@@ -718,43 +237,70 @@ function StandardSpatializedContainerBase(props, ref) {
     use2DFrameDetector(refInternal);
   }
   const transformExist = useSpatialTransformVisibilityWatcher(props[SpatialID]);
-  const extraStyle = {
-    visibility: "hidden",
-    transition: "none",
-    transform: transformExist ? "translateZ(0)" : "none"
-  };
-  const style = { ...inStyle, ...extraStyle };
   const classNames = className ? `${className} xr-spatial-default` : "xr-spatial-default";
   return /* @__PURE__ */ jsx(
     Component,
     {
       ref: refInternalCallback,
-      style,
+      style: inStyle,
       className: classNames,
-      ...restProps
+      ...restProps,
+      "data-xr-host": "",
+      "data-xr-transform-active": transformExist ? "" : void 0
     }
   );
 }
 var StandardSpatializedContainer = forwardRef(
   StandardSpatializedContainerBase
 );
-function injectSpatialDefaultStyle() {
-  const styleElement = document.createElement("style");
+var SPATIAL_DEFAULT_STYLE_CSS = `
+  :where(.xr-spatial-default) {
+    --xr-back: 0;
+    --xr-depth: 0;
+    --xr-z-index: 0;
+    --xr-background-material: none;
+  }
+  .xr-spatial-default[data-xr-host] {
+    visibility: hidden !important;
+    transition: none !important;
+    transform: none !important;
+  }
+  .xr-spatial-default[data-xr-host][data-xr-transform-active] {
+    transform: translateZ(0) !important;
+  }
+`;
+var SPATIAL_DEFAULT_STYLE_MARKER = "data-xr-spatial-default-style";
+function ensureSpatialDefaultStyleInRoot(root) {
+  const queryRoot = root === document ? document.head : root;
+  if (queryRoot.querySelector(`style[${SPATIAL_DEFAULT_STYLE_MARKER}]`)) {
+    return;
+  }
+  const ownerDoc = root === document ? document : root.ownerDocument || document;
+  const styleElement = ownerDoc.createElement("style");
   styleElement.type = "text/css";
-  styleElement.innerHTML = " :where(.xr-spatial-default) {  --xr-back: 0; --xr-depth: 0; --xr-z-index: 0; --xr-background-material: none;  } ";
-  document.head.appendChild(styleElement);
+  styleElement.setAttribute(SPATIAL_DEFAULT_STYLE_MARKER, "");
+  styleElement.innerHTML = SPATIAL_DEFAULT_STYLE_CSS;
+  if (root === document) {
+    document.head.appendChild(styleElement);
+  } else {
+    ;
+    root.appendChild(styleElement);
+  }
+}
+function injectSpatialDefaultStyle() {
+  ensureSpatialDefaultStyleInRoot(document);
 }
 
 // src/spatialized-container/TransformVisibilityTaskContainer.tsx
 import {
   forwardRef as forwardRef2,
-  useCallback as useCallback5,
-  useRef as useRef3
+  useCallback as useCallback4,
+  useRef as useRef2
 } from "react";
 import { createPortal } from "react-dom";
 
 // src/spatialized-container/hooks/useSpatialTransformVisibility.ts
-import { useCallback as useCallback4, useContext as useContext3, useEffect as useEffect4 } from "react";
+import { useCallback as useCallback3, useContext as useContext3, useEffect as useEffect3 } from "react";
 
 // src/notifyUpdateStandInstanceLayout.ts
 function notifyUpdateStandInstanceLayout() {
@@ -784,7 +330,7 @@ function parseTransformAndVisibilityProperties(node) {
 }
 function useSpatialTransformVisibility(spatialId, ref) {
   const spatializedContainerObject = useContext3(SpatializedContainerContext);
-  const checkSpatialStyleUpdate = useCallback4(() => {
+  const checkSpatialStyleUpdate = useCallback3(() => {
     if (!ref.current) {
       return;
     }
@@ -796,10 +342,10 @@ function useSpatialTransformVisibility(spatialId, ref) {
       spatialTransformVisibility
     );
   }, []);
-  useEffect4(() => {
+  useEffect3(() => {
     checkSpatialStyleUpdate();
   }, [checkSpatialStyleUpdate]);
-  useEffect4(() => {
+  useEffect3(() => {
     const observer = new MutationObserver((mutationsList) => {
       checkSpatialStyleUpdate();
     });
@@ -815,7 +361,7 @@ function useSpatialTransformVisibility(spatialId, ref) {
       observer.disconnect();
     };
   }, []);
-  useEffect4(() => {
+  useEffect3(() => {
     const headObserver = new MutationObserver((mutations) => {
       checkSpatialStyleUpdate();
     });
@@ -824,7 +370,7 @@ function useSpatialTransformVisibility(spatialId, ref) {
       headObserver.disconnect();
     };
   }, []);
-  useEffect4(() => {
+  useEffect3(() => {
     const onDomUpdated = (event) => {
       checkSpatialStyleUpdate();
     };
@@ -858,8 +404,8 @@ function createOrGetCSSParserDivContainer() {
   return cssParserDivContainer;
 }
 function useInternalRef2(ref) {
-  const refInternal = useRef3(null);
-  const refInternalCallback = useCallback5(
+  const refInternal = useRef2(null);
+  const refInternalCallback = useCallback4(
     (node) => {
       refInternal.current = node;
       if (typeof ref === "function") {
@@ -909,7 +455,9 @@ import {
   useCallback as useCallback6,
   useContext as useContext7,
   useEffect as useEffect10,
+  useLayoutEffect as useLayoutEffect2,
   useMemo as useMemo2,
+  useRef as useRef5,
   useState as useState6
 } from "react";
 
@@ -928,19 +476,153 @@ function getSession() {
   if (_currentSession) {
     return _currentSession;
   }
-  _currentSession = spatial.requestSession();
-  return _currentSession;
+  _currentSession = spatial.requestSession();
+  return _currentSession;
+}
+
+// src/spatialized-container/context/SpatialLayerContext.ts
+import { createContext as createContext2 } from "react";
+var SpatialLayerContext = createContext2(0);
+
+// src/spatialized-container/PortalSpatializedContainer.tsx
+import { useMemo, useContext as useContext4, useEffect as useEffect6 } from "react";
+
+// src/spatialized-container/context/PortalInstanceContext.ts
+import { createContext as createContext3 } from "react";
+
+// src/spatialized-container/utils.ts
+function getInheritedStyleProps(computedStyle) {
+  var propNames = [
+    "azimuth",
+    "borderCollapse",
+    "borderSpacing",
+    "captionSide",
+    "color",
+    "cursor",
+    "direction",
+    // 'elevation',
+    "emptyCells",
+    "fontFamily",
+    "fontSize",
+    "fontStyle",
+    "fontVariant",
+    "fontWeight",
+    "font",
+    "letterSpacing",
+    "lineHeight",
+    "listStyleImage",
+    "listStylePosition",
+    "listStyleType",
+    "listStyle",
+    "orphans",
+    // 'pitchRange',
+    // 'pitch',
+    "quotes",
+    // 'richness',
+    // 'speakHeader',
+    // 'speakNumeral',
+    // 'speakPunctuation',
+    // 'speak',
+    // 'speechRate',
+    // 'stress',
+    "textAlign",
+    "textIndent",
+    "textTransform",
+    "visibility",
+    // 'voiceFamily',
+    // 'volume',
+    "whiteSpace",
+    "widows",
+    "wordSpacing",
+    // background also need to be synced
+    "background",
+    // position also need to be synced
+    "position",
+    "width",
+    "height",
+    "display",
+    // content-visibility also need to be synced
+    "contentVisibility"
+  ];
+  var props = {};
+  for (var cssName of propNames) {
+    if (computedStyle[cssName]) {
+      props[cssName] = computedStyle[cssName];
+    }
+  }
+  return props;
+}
+function parseTransformOrigin(computedStyle) {
+  const transformOriginProperty = computedStyle.getPropertyValue("transform-origin");
+  const [x, y] = transformOriginProperty.split(" ").map(parseFloat);
+  const width = parseFloat(computedStyle.getPropertyValue("width"));
+  const height = parseFloat(computedStyle.getPropertyValue("height"));
+  return {
+    x: width > 0 ? x / width : 0.5,
+    y: height > 0 ? y / height : 0.5,
+    z: 0.5
+  };
+}
+function parseBorderRadius(borderProperty, width) {
+  if (borderProperty === "") {
+    return 0;
+  }
+  if (borderProperty.endsWith("%")) {
+    return width * parseFloat(borderProperty) / 100;
+  }
+  return parseFloat(borderProperty);
+}
+function parseCornerRadius(computedStyle) {
+  const width = parseFloat(computedStyle.getPropertyValue("width"));
+  const topLeftPropertyValue = computedStyle.getPropertyValue(
+    "border-top-left-radius"
+  );
+  const topRightPropertyValue = computedStyle.getPropertyValue(
+    "border-top-right-radius"
+  );
+  const bottomLeftPropertyValue = computedStyle.getPropertyValue(
+    "border-bottom-left-radius"
+  );
+  const bottomRightPropertyValue = computedStyle.getPropertyValue(
+    "border-bottom-right-radius"
+  );
+  const cornerRadius = {
+    topLeading: parseBorderRadius(topLeftPropertyValue, width),
+    bottomLeading: parseBorderRadius(bottomLeftPropertyValue, width),
+    topTrailing: parseBorderRadius(topRightPropertyValue, width),
+    bottomTrailing: parseBorderRadius(bottomRightPropertyValue, width)
+  };
+  return cornerRadius;
+}
+function extractAndRemoveCustomProperties(cssText, properties) {
+  if (!cssText) {
+    return { extractedValues: {}, filteredCssText: "" };
+  }
+  const extractedValues = {};
+  const rules = cssText.split(";");
+  const filteredRules = rules.filter((rule) => {
+    const [key, value] = rule.split(":").map((part) => part.trim());
+    if (properties.includes(key)) {
+      extractedValues[key] = value;
+      return false;
+    }
+    return true;
+  });
+  const filteredCssText = filteredRules.join(";").trim();
+  return { extractedValues, filteredCssText };
+}
+function joinToCSSText(cssKV) {
+  const rules = Object.entries(cssKV).map(([key, value]) => `${key}: ${value}`);
+  return rules.join(";");
 }
 
-// src/spatialized-container/context/SpatialLayerContext.ts
-import { createContext as createContext2 } from "react";
-var SpatialLayerContext = createContext2(0);
-
-// src/spatialized-container/PortalSpatializedContainer.tsx
-import { useMemo, useContext as useContext4, useEffect as useEffect7 } from "react";
-
-// src/spatialized-container/context/PortalInstanceContext.ts
-import { createContext as createContext3 } from "react";
+// src/spatialized-container/types.ts
+var SpatialCustomStyleVars = {
+  back: "--xr-back",
+  depth: "--xr-depth",
+  backgroundMaterial: "--xr-background-material",
+  xrZIndex: "--xr-z-index"
+};
 
 // src/utils/debugTool.ts
 import { isSSREnv as isSSREnv2 } from "@webspatial/core-sdk";
@@ -959,6 +641,18 @@ function enableDebugTool() {
   });
 }
 
+// src/utils/urlUtils.ts
+function getAbsoluteUrl(url) {
+  if (typeof window === "undefined" || !window.location?.href) {
+    return url;
+  }
+  try {
+    return new URL(url, window.location.href).href;
+  } catch {
+    return url;
+  }
+}
+
 // src/spatialized-container/context/PortalInstanceContext.ts
 var PortalInstanceObject = class {
   spatialId;
@@ -1143,14 +837,14 @@ var PortalInstanceContext = createContext3(
 );
 
 // src/spatialized-container/hooks/useSync2DFrame.ts
-import { useEffect as useEffect5, useState as useState2 } from "react";
+import { useEffect as useEffect4, useState as useState2 } from "react";
 function useForceUpdate() {
   const [, setToggle] = useState2(false);
   return () => setToggle((toggle) => !toggle);
 }
 function useSync2DFrame(spatialId, portalInstanceObject, spatializedContainerObject) {
   const forceUpdate = useForceUpdate();
-  useEffect5(() => {
+  useEffect4(() => {
     spatializedContainerObject.on2DFrameChange(spatialId, () => {
       portalInstanceObject.notify2DFrameChange();
       forceUpdate();
@@ -1162,11 +856,11 @@ function useSync2DFrame(spatialId, portalInstanceObject, spatializedContainerObj
 }
 
 // src/spatialized-container/hooks/useSpatializedElement.ts
-import { useEffect as useEffect6, useRef as useRef4, useState as useState3 } from "react";
+import { useEffect as useEffect5, useRef as useRef3, useState as useState3 } from "react";
 function useSpatializedElement(createSpatializedElement2, portalInstanceObject) {
   const [spatializedElement, setSpatializedElement] = useState3();
-  const elementRef = useRef4(void 0);
-  useEffect6(() => {
+  const elementRef = useRef3(void 0);
+  useEffect5(() => {
     let isDestroyed = false;
     createSpatializedElement2().then(
       (inSpatializedElement) => {
@@ -1262,7 +956,7 @@ function PortalSpatializedContainer(props) {
     ),
     []
   );
-  useEffect7(() => {
+  useEffect6(() => {
     portalInstanceObject.init();
     return () => {
       portalInstanceObject.destroy();
@@ -1277,58 +971,417 @@ function PortalSpatializedContainer(props) {
     portalInstanceObject,
     props.component
   );
-  useEffect7(() => {
+  useEffect6(() => {
     if (spatializedElement) {
       spatializedElement.onSpatialTap = onSpatialTap;
     }
   }, [spatializedElement, onSpatialTap]);
-  useEffect7(() => {
+  useEffect6(() => {
     if (spatializedElement) {
       spatializedElement.onSpatialDrag = onSpatialDrag;
     }
-  }, [spatializedElement, onSpatialDrag]);
-  useEffect7(() => {
-    if (spatializedElement) {
-      spatializedElement.onSpatialDragEnd = onSpatialDragEnd;
+  }, [spatializedElement, onSpatialDrag]);
+  useEffect6(() => {
+    if (spatializedElement) {
+      spatializedElement.onSpatialDragEnd = onSpatialDragEnd;
+    }
+  }, [spatializedElement, onSpatialDragEnd]);
+  useEffect6(() => {
+    if (spatializedElement) {
+      spatializedElement.onSpatialRotate = onSpatialRotate;
+    }
+  }, [spatializedElement, onSpatialRotate]);
+  useEffect6(() => {
+    if (spatializedElement) {
+      spatializedElement.onSpatialRotateEnd = onSpatialRotateEnd;
+    }
+  }, [spatializedElement, onSpatialRotateEnd]);
+  useEffect6(() => {
+    if (spatializedElement) {
+      spatializedElement.onSpatialMagnify = onSpatialMagnify;
+    }
+  }, [spatializedElement, onSpatialMagnify]);
+  useEffect6(() => {
+    if (spatializedElement) {
+      spatializedElement.onSpatialMagnifyEnd = onSpatialMagnifyEnd;
+    }
+  }, [spatializedElement, onSpatialMagnifyEnd]);
+  useEffect6(() => {
+    if (spatializedElement) {
+      spatializedElement.onSpatialDragStart = onSpatialDragStart;
+    }
+  }, [spatializedElement, onSpatialDragStart]);
+  const rotateConstraintKey = constrainedAxisKey(
+    spatialEventOptions?.constrainedToAxis
+  );
+  useEffect6(() => {
+    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/spatialized-container/hooks/useDomProxy.ts
+import { useCallback as useCallback5, useEffect as useEffect7, useRef as useRef4 } from "react";
+import { supports } from "@webspatial/core-sdk";
+var SpatialContainerRefProxy = class {
+  transformVisibilityTaskContainerDom = null;
+  /** Raw Standard host element (styled root). Used to mirror class onto the transform probe. */
+  standardRawDom = null;
+  standardClassObserver = null;
+  /**
+   * When set, Standard's DOM className is forwarded here so TransformVisibilityTaskContainer
+   * can render it from React state (avoids React clobbering imperative class updates).
+   */
+  mirrorClassNotify = null;
+  /** Last class string applied to the probe + used to skip redundant syncs. */
+  lastMirroredClassName = null;
+  /** Coalesce multiple class sync triggers in the same turn (Observer + classList, etc.). */
+  classSyncMicrotaskQueued = false;
+  ref;
+  domProxy;
+  /** Last value dispatched to `ref` (undefined = none yet); avoids duplicate null/proxy writes. */
+  lastOutgoingToRef = void 0;
+  installedProperties = [];
+  // extre ref props, used to add extra props to ref
+  extraRefProps;
+  constructor(ref, extraRefProps) {
+    this.ref = ref;
+    this.extraRefProps = extraRefProps;
+  }
+  setMirrorClassNotify(fn) {
+    this.mirrorClassNotify = fn;
+    if (fn && this.standardRawDom) {
+      this.flushSyncTransformClassFromStandard(true);
+    }
+  }
+  disconnectStandardClassObserver() {
+    this.standardClassObserver?.disconnect();
+    this.standardClassObserver = null;
+  }
+  attachStandardClassObserver() {
+    this.disconnectStandardClassObserver();
+    if (!this.standardRawDom) {
+      return;
+    }
+    this.standardClassObserver = new MutationObserver(() => {
+      this.ensureSpatialDefaultClass();
+      this.scheduleSyncTransformClassFromStandard();
+    });
+    this.standardClassObserver.observe(this.standardRawDom, {
+      attributes: true,
+      attributeFilter: ["class"]
+    });
+  }
+  ensureSpatialDefaultClass() {
+    const dom = this.standardRawDom;
+    if (!dom) return;
+    if (dom.classList.contains("xr-spatial-default")) return;
+    dom.classList.add("xr-spatial-default");
+  }
+  /**
+   * Merge multiple sync requests (e.g. classList hook + MutationObserver) into one microtask.
+   */
+  scheduleSyncTransformClassFromStandard() {
+    if (this.classSyncMicrotaskQueued) {
+      return;
+    }
+    this.classSyncMicrotaskQueued = true;
+    queueMicrotask(() => {
+      this.classSyncMicrotaskQueued = false;
+      this.flushSyncTransformClassFromStandard(false);
+    });
+  }
+  /**
+   * Source of truth: Standard host DOM (incl. styled-components runtime class changes).
+   * @param force when true, skip same-string short-circuit (e.g. mirror notify just registered).
+   */
+  flushSyncTransformClassFromStandard(force) {
+    if (!this.standardRawDom) {
+      return;
+    }
+    const name = this.standardRawDom.className;
+    const probe = this.transformVisibilityTaskContainerDom;
+    if (!force && probe && probe.className === name && this.lastMirroredClassName === name) {
+      return;
+    }
+    this.lastMirroredClassName = name;
+    if (probe) {
+      probe.className = name;
+    }
+    this.mirrorClassNotify?.(name);
+  }
+  updateStandardSpatializedContainerDom(dom) {
+    if (!dom) {
+      this.disconnectStandardClassObserver();
+      this.clearInstalledProperties();
+      this.standardRawDom = null;
+      this.lastMirroredClassName = null;
+      this.domProxy = void 0;
+      this.updateDomProxyToRef();
+      return;
+    }
+    if (this.standardRawDom === dom && this.domProxy) {
+      this.scheduleSyncTransformClassFromStandard();
+      return;
+    }
+    this.clearInstalledProperties();
+    this.standardRawDom = dom;
+    this.domProxy = dom;
+    this.installSpatialRefBehavior(dom);
+    const root = dom.getRootNode();
+    if (root === document || root instanceof ShadowRoot) {
+      ensureSpatialDefaultStyleInRoot(root);
+    }
+    this.attachStandardClassObserver();
+    this.updateDomProxyToRef();
+    this.scheduleSyncTransformClassFromStandard();
+  }
+  clearInstalledProperties() {
+    const dom = this.standardRawDom;
+    if (!dom) return;
+    for (const prop of this.installedProperties) {
+      delete dom[prop];
+    }
+    this.installedProperties = [];
+  }
+  defineDomProperty(dom, prop, descriptor) {
+    Object.defineProperty(dom, prop, {
+      configurable: true,
+      ...descriptor
+    });
+    this.installedProperties.push(prop);
+  }
+  installSpatialRefBehavior(dom) {
+    const self = this;
+    const rawStyle = dom.style;
+    const rawRemoveProperty = rawStyle.removeProperty.bind(rawStyle);
+    const rawGetPropertyValue = rawStyle.getPropertyValue.bind(rawStyle);
+    const rawRemoveAttribute = dom.removeAttribute.bind(dom);
+    const spatialStyleProperties = ["visibility", "transform"];
+    const styleProxy = new Proxy(rawStyle, {
+      get(target, prop) {
+        if (prop === "visibility" || prop === "transform") {
+          return self.transformVisibilityTaskContainerDom?.style.getPropertyValue(
+            prop
+          );
+        }
+        const value = Reflect.get(target, prop);
+        if (typeof value === "function") {
+          if (prop === "setProperty" || prop === "removeProperty" || prop === "getPropertyValue") {
+            return function(...args) {
+              const [property] = args;
+              if (spatialStyleProperties.includes(property)) {
+                if (prop === "setProperty") {
+                  const [, kValue, priority] = args;
+                  self.transformVisibilityTaskContainerDom?.style.setProperty(
+                    property,
+                    kValue,
+                    priority
+                  );
+                } else if (prop === "removeProperty") {
+                  return self.transformVisibilityTaskContainerDom?.style.removeProperty(
+                    property
+                  );
+                } else if (prop === "getPropertyValue") {
+                  return self.transformVisibilityTaskContainerDom?.style.getPropertyValue(
+                    property
+                  );
+                }
+                return void 0;
+              }
+              return value.apply(this, args);
+            }.bind(target);
+          }
+          return value.bind(target);
+        }
+        return value;
+      },
+      set(target, prop, value) {
+        if (prop === "visibility") {
+          self.transformVisibilityTaskContainerDom?.style.setProperty(
+            "visibility",
+            value
+          );
+          return true;
+        }
+        if (prop === "transform") {
+          self.transformVisibilityTaskContainerDom?.style.setProperty(
+            "transform",
+            value
+          );
+          return true;
+        }
+        if (Object.values(SpatialCustomStyleVars).includes(prop)) {
+          target.setProperty(prop, value);
+          return true;
+        }
+        if (prop === "cssText") {
+          const { extractedValues, filteredCssText } = extractAndRemoveCustomProperties(
+            value,
+            spatialStyleProperties
+          );
+          spatialStyleProperties.forEach((key) => {
+            if (extractedValues[key]) {
+              self.transformVisibilityTaskContainerDom?.style.setProperty(
+                key,
+                extractedValues[key]
+              );
+            } else {
+              rawRemoveProperty(key);
+            }
+          });
+          const appendedCSSText = joinToCSSText({
+            transform: "none",
+            visibility: "hidden"
+          });
+          return Reflect.set(
+            target,
+            prop,
+            [appendedCSSText, filteredCssText].join(";")
+          );
+        }
+        return Reflect.set(target, prop, value);
+      }
+    });
+    this.defineDomProperty(dom, "style", {
+      get() {
+        return styleProxy;
+      },
+      set(value) {
+        styleProxy.cssText = String(value);
+      }
+    });
+    this.defineDomProperty(dom, "className", {
+      get() {
+        return dom.getAttribute("class") ?? "";
+      },
+      set(value) {
+        dom.setAttribute("class", String(value));
+        if (!dom.classList.contains("xr-spatial-default")) {
+          dom.classList.add("xr-spatial-default");
+        }
+        self.scheduleSyncTransformClassFromStandard();
+      }
+    });
+    this.defineDomProperty(dom, "removeAttribute", {
+      value(property) {
+        if (property === "style") {
+          rawStyle.cssText = "visibility: hidden; transition: none; transform: none;";
+          self.transformVisibilityTaskContainerDom?.style.removeProperty(
+            "visibility"
+          );
+          self.transformVisibilityTaskContainerDom?.style.removeProperty(
+            "transform"
+          );
+          return;
+        }
+        if (property === "class") {
+          dom.className = "xr-spatial-default";
+          return;
+        }
+        return rawRemoveAttribute(property);
+      }
+    });
+    if (supports("xrClientDepth")) {
+      this.defineDomProperty(dom, "xrClientDepth", {
+        get() {
+          return rawGetPropertyValue(SpatialCustomStyleVars.depth);
+        }
+      });
+    }
+    if (supports("xrOffsetBack")) {
+      this.defineDomProperty(dom, "xrOffsetBack", {
+        get() {
+          return rawGetPropertyValue(SpatialCustomStyleVars.back);
+        }
+      });
     }
-  }, [spatializedElement, onSpatialDragEnd]);
-  useEffect7(() => {
-    if (spatializedElement) {
-      spatializedElement.onSpatialRotate = onSpatialRotate;
+    if (this.extraRefProps) {
+      const extraProps = this.extraRefProps(dom);
+      for (const prop of Object.keys(extraProps)) {
+        this.defineDomProperty(dom, prop, {
+          get() {
+            return extraProps[prop];
+          },
+          set(value) {
+            extraProps[prop] = value;
+          }
+        });
+      }
     }
-  }, [spatializedElement, onSpatialRotate]);
-  useEffect7(() => {
-    if (spatializedElement) {
-      spatializedElement.onSpatialRotateEnd = onSpatialRotateEnd;
+  }
+  updateTransformVisibilityTaskContainerDom(dom) {
+    this.transformVisibilityTaskContainerDom = dom;
+    if (!dom) {
+      this.lastMirroredClassName = null;
     }
-  }, [spatializedElement, onSpatialRotateEnd]);
-  useEffect7(() => {
-    if (spatializedElement) {
-      spatializedElement.onSpatialMagnify = onSpatialMagnify;
+    this.scheduleSyncTransformClassFromStandard();
+    this.updateDomProxyToRef();
+  }
+  updateDomProxyToRef() {
+    const ref = this.ref;
+    if (!ref) {
+      return;
     }
-  }, [spatializedElement, onSpatialMagnify]);
-  useEffect7(() => {
-    if (spatializedElement) {
-      spatializedElement.onSpatialMagnifyEnd = onSpatialMagnifyEnd;
+    const next = this.domProxy && this.transformVisibilityTaskContainerDom ? this.domProxy : null;
+    if (this.lastOutgoingToRef === next) {
+      return;
     }
-  }, [spatializedElement, onSpatialMagnifyEnd]);
-  useEffect7(() => {
-    if (spatializedElement) {
-      spatializedElement.onSpatialDragStart = onSpatialDragStart;
+    this.lastOutgoingToRef = next;
+    if (next) {
+      if (typeof ref === "function") {
+        ref(next);
+      } else {
+        ref.current = next;
+      }
+    } else {
+      if (typeof ref === "function") {
+        ref(null);
+      } else {
+        ref.current = null;
+      }
     }
-  }, [spatializedElement, onSpatialDragStart]);
-  const rotateConstraintKey = constrainedAxisKey(
-    spatialEventOptions?.constrainedToAxis
+  }
+  updateRef(ref) {
+    if (this.ref === ref) {
+      return;
+    }
+    this.ref = ref;
+    this.lastOutgoingToRef = void 0;
+    this.updateDomProxyToRef();
+  }
+};
+function useDomProxy(ref, extraRefProps) {
+  const spatialContainerRefProxy = useRef4(
+    new SpatialContainerRefProxy(ref, extraRefProps)
   );
   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
-  ] });
+    spatialContainerRefProxy.current.updateRef(ref);
+  }, [ref]);
+  const transformVisibilityTaskContainerCallback = useCallback5(
+    (el) => {
+      spatialContainerRefProxy.current.updateTransformVisibilityTaskContainerDom(
+        el
+      );
+    },
+    []
+  );
+  const standardSpatializedContainerCallback = useCallback5(
+    (el) => {
+      spatialContainerRefProxy.current.updateStandardSpatializedContainerDom(el);
+    },
+    []
+  );
+  return {
+    transformVisibilityTaskContainerCallback,
+    standardSpatializedContainerCallback,
+    spatialContainerRefProxy
+  };
 }
 
 // src/reality/context/InsideAttachmentContext.tsx
@@ -1570,6 +1623,7 @@ function withSSRSupported(Component) {
 import { jsx as jsx6, jsxs as jsxs2 } from "react/jsx-runtime";
 function DegradedContainer({
   innerRef,
+  enableOnSpatialContentReadyFallback,
   ...inprops
 }) {
   const {
@@ -1590,9 +1644,48 @@ function DegradedContainer({
     getExtraSpatializedElementProperties: _getExtra,
     extraRefProps: _extraRef,
     sizingMode: _sizingMode,
+    onSpatialContentReady: _onSpatialContentReady,
     ...restProps
   } = inprops;
-  return /* @__PURE__ */ jsx6(Component, { ref: innerRef, ...restProps, children });
+  const [hostEl, setHostEl] = useState6(null);
+  const callbackRef = useRef5(_onSpatialContentReady);
+  callbackRef.current = _onSpatialContentReady;
+  useLayoutEffect2(() => {
+    if (!enableOnSpatialContentReadyFallback || !hostEl || !hostEl.isConnected || !callbackRef.current) {
+      return () => {
+      };
+    }
+    let cleanup;
+    try {
+      cleanup = callbackRef.current({ host: hostEl });
+    } catch (e) {
+      if (process.env.NODE_ENV !== "production") {
+        console.error("[WebSpatial] onSpatialContentReady threw", e);
+      }
+    }
+    return () => {
+      if (typeof cleanup !== "function") return;
+      try {
+        cleanup();
+      } catch (e) {
+        if (process.env.NODE_ENV !== "production") {
+          console.error("[WebSpatial] onSpatialContentReady cleanup threw", e);
+        }
+      }
+    };
+  }, [enableOnSpatialContentReadyFallback, hostEl]);
+  const setHostRef = useCallback6(
+    (node) => {
+      if (typeof innerRef === "function") {
+        innerRef(node);
+      } else if (innerRef != null) {
+        innerRef.current = node;
+      }
+      setHostEl(node);
+    },
+    [innerRef]
+  );
+  return /* @__PURE__ */ jsx6(Component, { ref: setHostRef, ...restProps, children });
 }
 function SpatializedContainerBase(inprops, ref) {
   const isWebSpatialEnv = getSession() !== null;
@@ -1603,7 +1696,14 @@ function SpatializedContainerBase(inprops, ref) {
         `[WebSpatial] ${inprops.component || "Spatial element"} cannot be used inside AttachmentAsset. Rendering as plain HTML.`
       );
     }
-    return /* @__PURE__ */ jsx6(DegradedContainer, { ...inprops, innerRef: ref });
+    return /* @__PURE__ */ jsx6(
+      DegradedContainer,
+      {
+        ...inprops,
+        innerRef: ref,
+        enableOnSpatialContentReadyFallback: !isWebSpatialEnv && !insideAttachment
+      }
+    );
   }
   const layer = useContext7(SpatialLayerContext) + 1;
   const rootSpatializedContainerObject = useContext7(
@@ -1686,6 +1786,7 @@ function SpatializedContainerBase(inprops, ref) {
         createSpatializedElement: createSpatializedElement2,
         getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
         spatialEventOptions: _nestedSpatialEventOptions,
+        onSpatialContentReady: _nestedOnSpatialContentReady,
         ...restProps
       } = props;
       return /* @__PURE__ */ jsxs2(SpatialLayerContext.Provider, { value: layer, children: [
@@ -1749,6 +1850,7 @@ function SpatializedContainerBase(inprops, ref) {
       createSpatializedElement: createSpatializedElement2,
       getExtraSpatializedElementProperties: getExtraSpatializedElementProperties2,
       spatialEventOptions: _rootSpatialEventOptions,
+      onSpatialContentReady: _rootOnSpatialContentReady,
       ...restProps
     } = props;
     return /* @__PURE__ */ jsx6(SpatialLayerContext.Provider, { value: layer, children: /* @__PURE__ */ jsxs2(
@@ -1795,8 +1897,10 @@ var SpatializedContainer = withSSRSupported(
 import { createPortal as createPortal2 } from "react-dom";
 import {
   forwardRef as forwardRef5,
+  useCallback as useCallback7,
   useContext as useContext8,
-  useEffect as useEffect12
+  useEffect as useEffect12,
+  useState as useState7
 } from "react";
 
 // src/utils/windowStyleSync.ts
@@ -1909,55 +2013,145 @@ async function syncParentHeadToChild(childWindow) {
 
 // src/utils/useSyncHeadStyles.ts
 import { useEffect as useEffect11 } from "react";
-function defaultShouldSync(mutations) {
-  if (!Array.isArray(mutations) || mutations.length === 0) return false;
+function getSyncTiming(mutations) {
+  if (!Array.isArray(mutations) || mutations.length === 0) return null;
+  let hasDelayed = false;
   for (const mutation of mutations) {
+    if (mutation.type === "characterData") {
+      const parent = mutation.target.parentElement;
+      if (parent?.tagName === "STYLE") return "immediate";
+    }
     const nodes = [
+      mutation.target,
       ...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 === "STYLE") return "immediate";
       if (tag === "LINK") {
         const { rel } = node;
-        if (rel && rel.toLowerCase() === "stylesheet") return true;
+        if (rel && rel.toLowerCase() === "stylesheet") hasDelayed = true;
       }
     }
   }
-  return false;
+  return hasDelayed ? "delayed" : null;
 }
 function useSyncHeadStyles(childWindow, options) {
   const delayMs = 100;
-  const subtree = options?.subtree ?? false;
+  const subtree = options?.subtree ?? true;
   const immediate = options?.immediate ?? true;
   useEffect11(() => {
     if (!childWindow) return;
     let timer;
-    const scheduleSync = () => {
+    let immediateQueued = false;
+    let disposed = false;
+    const scheduleSync = (timing = "delayed") => {
       if (timer) window.clearTimeout(timer);
+      if (timing === "immediate") {
+        if (immediateQueued) return;
+        immediateQueued = true;
+        queueMicrotask(() => {
+          immediateQueued = false;
+          if (disposed) return;
+          syncParentHeadToChild(childWindow);
+        });
+        return;
+      }
       timer = window.setTimeout(() => {
+        if (disposed) return;
         syncParentHeadToChild(childWindow);
       }, delayMs);
     };
     if (immediate) scheduleSync();
     const observer = new MutationObserver((mutations) => {
-      if (!defaultShouldSync(mutations)) return;
-      scheduleSync();
+      const timing = getSyncTiming(mutations);
+      if (!timing) return;
+      scheduleSync(timing);
+    });
+    observer.observe(document.head, {
+      childList: true,
+      characterData: true,
+      subtree
     });
-    observer.observe(document.head, { childList: true, subtree });
     return () => {
+      disposed = true;
       if (timer) window.clearTimeout(timer);
       observer.disconnect();
     };
   }, [childWindow, delayMs, subtree, immediate]);
 }
 
+// src/spatialized-container/hooks/useSpatialContentReady.ts
+import { useLayoutEffect as useLayoutEffect3, useRef as useRef6 } from "react";
+var isDev = process.env.NODE_ENV !== "production";
+function safeInvokeCleanup(cleanup) {
+  if (!cleanup) return;
+  try {
+    cleanup();
+  } catch (e) {
+    if (isDev) {
+      console.error("[WebSpatial] onSpatialContentReady cleanup threw", e);
+    }
+  }
+}
+function useSpatialContentReady(params) {
+  const {
+    spatializedElement,
+    portalInstanceObject,
+    hostElement,
+    onSpatialContentReady
+  } = params;
+  const callbackRef = useRef6(onSpatialContentReady);
+  callbackRef.current = onSpatialContentReady;
+  useLayoutEffect3(() => {
+    const dom = portalInstanceObject.dom;
+    const isReady = !!(spatializedElement && dom && hostElement && hostElement.isConnected);
+    if (!isReady || !hostElement) {
+      return () => {
+      };
+    }
+    const cb = callbackRef.current;
+    let cleanupFromCallback;
+    if (cb) {
+      try {
+        const ret = cb({ host: hostElement });
+        cleanupFromCallback = typeof ret === "function" ? ret : void 0;
+      } catch (e) {
+        if (isDev) {
+          console.error("[WebSpatial] onSpatialContentReady threw", e);
+        }
+      }
+    }
+    return () => {
+      safeInvokeCleanup(cleanupFromCallback);
+    };
+  }, [spatializedElement, portalInstanceObject.dom, hostElement]);
+}
+
 // src/spatialized-container/Spatialized2DElementContainer.tsx
 import { jsx as jsx7 } from "react/jsx-runtime";
-function getJSXPortalInstance(inProps, portalInstanceObject) {
-  const { component: El, style: inStyle = {}, ...props } = inProps;
+function mergeRefs(...refs) {
+  return (value) => {
+    for (const ref of refs) {
+      if (ref == null) continue;
+      if (typeof ref === "function") {
+        ref(value);
+      } else {
+        ;
+        ref.current = value;
+      }
+    }
+  };
+}
+function getJSXPortalInstance(inProps, portalInstanceObject, hostRef) {
+  const {
+    component: El,
+    style: inStyle = {},
+    ref: userRef,
+    ...props
+  } = inProps;
   const extraStyle = {
     visibility: "visible",
     position: "relative",
@@ -1979,7 +2173,8 @@ function getJSXPortalInstance(inProps, portalInstanceObject) {
     ...inheritedPortalStyle,
     ...extraStyle
   };
-  return /* @__PURE__ */ jsx7(El, { style, ...props });
+  const mergedRef = hostRef != null ? mergeRefs(hostRef, userRef) : userRef;
+  return /* @__PURE__ */ jsx7(El, { ref: mergedRef, style, ...props });
 }
 function useSyncDocumentTitle(windowProxy, spatializedElement, name) {
   useEffect12(() => {
@@ -1990,20 +2185,31 @@ function useSyncDocumentTitle(windowProxy, spatializedElement, name) {
   }, [name]);
 }
 function SpatializedContent(props) {
-  const { spatializedElement, ...restProps } = props;
+  const { spatializedElement, onSpatialContentReady, ...restProps } = props;
   const spatialized2DElement = spatializedElement;
   const { windowProxy } = spatialized2DElement;
+  const [hostEl, setHostEl] = useState7(null);
+  const portalInstanceObject = useContext8(
+    PortalInstanceContext
+  );
+  useSpatialContentReady({
+    spatializedElement,
+    portalInstanceObject,
+    hostElement: hostEl,
+    onSpatialContentReady
+  });
   useSyncHeadStyles(windowProxy, {
     subtree: false
   });
   const name = restProps["data-name"] || "";
   useSyncDocumentTitle(windowProxy, spatialized2DElement, name);
-  const portalInstanceObject = useContext8(
-    PortalInstanceContext
-  );
+  const setHostCallback = useCallback7((el) => {
+    setHostEl(el);
+  }, []);
   const JSXPortalInstance = getJSXPortalInstance(
     restProps,
-    portalInstanceObject
+    portalInstanceObject,
+    setHostCallback
   );
   return createPortal2(JSXPortalInstance, windowProxy.document.body);
 }
@@ -2061,11 +2267,11 @@ import {
   Children,
   forwardRef as forwardRef6,
   isValidElement,
-  useCallback as useCallback7,
+  useCallback as useCallback8,
   useContext as useContext9,
   useEffect as useEffect13,
   useMemo as useMemo3,
-  useRef as useRef5
+  useRef as useRef7
 } from "react";
 import { Fragment as Fragment2, jsx as jsx8 } from "react/jsx-runtime";
 function getAbsoluteURL(url) {
@@ -2110,24 +2316,57 @@ function collectSources(children) {
   return sources;
 }
 function SpatializedContent2(props) {
-  const { src, children, spatializedElement, onLoad, onError, autoPlay, loop } = props;
+  const {
+    src,
+    poster,
+    children,
+    spatializedElement,
+    onLoad,
+    onError,
+    autoPlay,
+    loop,
+    loading = "eager"
+  } = props;
   const portalInstanceObject = useContext9(PortalInstanceContext);
+  const wasVisible = useRef7(false);
   const modelURL = useMemo3(() => getAbsoluteURL(src), [src]);
+  const posterURL = useMemo3(() => getAbsoluteURL(poster), [poster]);
   const sources = useMemo3(() => collectSources(children), [children]);
+  const sourcesKey = useMemo3(() => JSON.stringify(sources), [sources]);
+  useEffect13(() => {
+    wasVisible.current = false;
+    const target = portalInstanceObject.dom;
+    if (loading !== "lazy" || !target) {
+      wasVisible.current = true;
+      return;
+    }
+    const observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) {
+        wasVisible.current = true;
+        observer.disconnect();
+        spatializedElement.updateProperties({ loading: "eager" });
+      }
+    });
+    observer.observe(target);
+    return () => observer.disconnect();
+  }, [modelURL, sourcesKey, portalInstanceObject]);
   useEffect13(() => {
+    if (loading !== "lazy") wasVisible.current = true;
     spatializedElement.updateProperties({
-      modelURL: modelURL ?? "",
+      modelURL: modelURL ?? (spatializedElement.modelUrl ? "" : modelURL),
       sources,
       autoplay: autoPlay,
-      loop
+      loop,
+      posterURL: posterURL ?? "",
+      loading: loading === "lazy" && wasVisible.current ? "eager" : loading
     });
-  }, [modelURL, JSON.stringify(sources), autoPlay, loop]);
+  }, [modelURL, sourcesKey, autoPlay, loop, posterURL, loading]);
   useEffect13(() => {
     if (onLoad) {
       spatializedElement.onLoadCallback = () => {
         onLoad(
           createLoadSuccessEvent(
-            () => portalInstanceObject.dom.__targetProxy
+            () => portalInstanceObject.dom
           )
         );
       };
@@ -2140,7 +2379,7 @@ function SpatializedContent2(props) {
       spatializedElement.onLoadFailureCallback = () => {
         onError(
           createLoadFailureEvent(
-            () => portalInstanceObject.dom.__targetProxy
+            () => portalInstanceObject.dom
           )
         );
       };
@@ -2151,15 +2390,16 @@ function SpatializedContent2(props) {
   return /* @__PURE__ */ jsx8(Fragment2, {});
 }
 function SpatializedStatic3DElementContainerBase(props, ref) {
-  const promiseRef = useRef5(null);
-  const createSpatializedElement2 = useCallback7(() => {
+  const promiseRef = useRef7(null);
+  const createSpatializedElement2 = useCallback8(() => {
     promiseRef.current = getSession().createSpatializedStatic3DElement(
       getAbsoluteURL(props.src),
-      collectSources(props.children)
+      collectSources(props.children),
+      props.loading === "lazy" ? "lazy" : "eager"
     );
     return promiseRef.current;
   }, []);
-  const extraRefProps = useCallback7(
+  const extraRefProps = useCallback8(
     (domProxy) => {
       let modelTransform = new DOMMatrixReadOnly();
       return {
@@ -2206,6 +2446,16 @@ function SpatializedStatic3DElementContainerBase(props, ref) {
           if (spatializedElement) {
             spatializedElement.playbackRate = value;
           }
+        },
+        get currentTime() {
+          const spatializedElement = domProxy.__spatializedElement;
+          return spatializedElement?.currentTime ?? 0;
+        },
+        set currentTime(value) {
+          const spatializedElement = domProxy.__spatializedElement;
+          if (spatializedElement) {
+            spatializedElement.currentTime = value;
+          }
         }
       };
     },
@@ -2262,11 +2512,19 @@ function withSpatialized2DElementContainer(Component) {
 
 // src/spatialized-container/index.ts
 function initPolyfill() {
-  hijackGetComputedStyle();
   injectSpatialDefaultStyle();
   initCSSParserDivContainer();
 }
 
+// src/webSpatialRuntime.ts
+import { supports as supports2 } from "@webspatial/core-sdk";
+var WebSpatialRuntime = {
+  supports: supports2
+};
+
+// src/index.ts
+import { WebSpatialRuntimeError } from "@webspatial/core-sdk";
+
 // src/initScene.ts
 function initScene(name, callback, options) {
   return getSession()?.initScene(name, callback, options);
@@ -2276,9 +2534,9 @@ function initScene(name, callback, options) {
 import { forwardRef as forwardRef9 } from "react";
 
 // src/spatialized-container-monitor/useMonitorDomChange.tsx
-import { useRef as useRef6, useEffect as useEffect14, useMemo as useMemo4 } from "react";
+import { useRef as useRef8, useEffect as useEffect14, useMemo as useMemo4 } from "react";
 function useMonitorDomChange(inRef) {
-  const ref = useRef6(null);
+  const ref = useRef8(null);
   useEffect14(() => {
     const observer = new MutationObserver((mutationsList) => {
       notifyDOMUpdate(mutationsList);
@@ -2440,37 +2698,87 @@ var AttachmentRegistry = class {
 var AttachmentContext = createContext8(null);
 
 // src/reality/hooks/useEntityTransform.tsx
-import { useEffect as useEffect16, useRef as useRef7 } from "react";
+import { useEffect as useEffect16, useRef as useRef9 } from "react";
 
 // src/reality/utils/ResourceRegistry.ts
 var ResourceRegistry = class {
+  /** Every id maps to a promise — either the real resource from add(), or a placeholder until then. */
   resources = /* @__PURE__ */ new Map();
+  /** If get() ran first, we stash resolve/reject so add() can complete the waiting promise. */
+  deferreds = /* @__PURE__ */ new Map();
+  /** Subscribers are notified whenever an id gets a fresh resolved or failed resource attempt. */
+  listeners = /* @__PURE__ */ new Map();
   add(id, resource) {
     this.resources.set(id, resource);
+    const deferred = this.deferreds.get(id);
+    if (deferred) {
+      resource.then(deferred.resolve).catch(
+        (err) => deferred.reject(err instanceof Error ? err : new Error(String(err)))
+      );
+      this.deferreds.delete(id);
+    }
+    resource.then(() => this.notify(id)).catch(() => this.notify(id));
+  }
+  subscribe(id, listener) {
+    const listeners = this.listeners.get(id) ?? /* @__PURE__ */ new Set();
+    listeners.add(listener);
+    this.listeners.set(id, listeners);
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        this.listeners.delete(id);
+      }
+    };
+  }
+  notify(id) {
+    const listeners = this.listeners.get(id);
+    if (!listeners) return;
+    for (const listener of Array.from(listeners)) {
+      listener();
+    }
+  }
+  get(id) {
+    const existing = this.resources.get(id);
+    if (existing) {
+      return existing;
+    }
+    const promise = new Promise((resolve, reject) => {
+      this.deferreds.set(id, { resolve, reject });
+    });
+    this.resources.set(id, promise);
+    return promise;
   }
   remove(id) {
     this.resources.delete(id);
+    this.deferreds.delete(id);
+    this.notify(id);
   }
-  // Remove the resource by id and destroy it once resolved
-  // This does not cancel in-flight creation; it schedules destruction after resolution
+  // Same as remove, but when the promise resolves, destroy the spatial object (best-effort).
   removeAndDestroy(id) {
     const p = this.resources.get(id);
     if (p) {
-      p.then((spatialObj) => spatialObj.destroy()).catch(() => {
+      p.then((obj) => obj.destroy()).catch(() => {
       });
     }
     this.resources.delete(id);
-  }
-  get(id) {
-    return this.resources.get(id);
+    this.deferreds.delete(id);
+    this.notify(id);
   }
   destroy() {
+    for (const [id, deferred] of this.deferreds) {
+      deferred.reject(
+        new Error(`ResourceRegistry destroyed \u2014 "${id}" never resolved`)
+      );
+    }
+    this.deferreds.clear();
+    const ids = Array.from(this.resources.keys());
+    for (const id of ids) {
+      this.notify(id);
+    }
+    this.listeners.clear();
     const pending = Array.from(this.resources.values());
     this.resources.clear();
-    pending.forEach(
-      (promise) => promise.then((spatialObj) => spatialObj.destroy()).catch(() => {
-      })
-    );
+    void Promise.allSettled(pending.map((p) => p.then((obj) => obj.destroy())));
   }
 };
 
@@ -2502,15 +2810,14 @@ function shallowEqualArray(a, b) {
 
 // src/reality/utils/AbortResourceManager.ts
 var AbortResourceManager = class {
+  resources = [];
+  aborted = false;
   constructor(signal) {
-    this.signal = signal;
     signal.addEventListener("abort", () => {
       this.aborted = true;
       void this.dispose();
     });
   }
-  resources = [];
-  aborted = false;
   async addResource(factory) {
     if (this.aborted) throw new DOMException("Aborted", "AbortError");
     const resource = await factory();
@@ -2535,7 +2842,7 @@ var AbortResourceManager = class {
 
 // src/reality/hooks/useEntityTransform.tsx
 function useEntityTransform(entity, { position, rotation, scale }) {
-  const last = useRef7({});
+  const last = useRef9({});
   useEffect16(() => {
     if (!entity) return;
     const shouldUpdate = !shallowEqualVec3(last.current.position, position) || !shallowEqualRotation(last.current.rotation, rotation) || !shallowEqualVec3(last.current.scale, scale);
@@ -2555,7 +2862,7 @@ function useEntityTransform(entity, { position, rotation, scale }) {
 }
 
 // src/reality/hooks/useEntityEvent.tsx
-import { useEffect as useEffect18, useRef as useRef9 } from "react";
+import { useEffect as useEffect17, useRef as useRef10 } from "react";
 
 // src/reality/type.ts
 var eventMap = {
@@ -2757,8 +3064,8 @@ function createEventProxy2(ev, instance) {
   });
 }
 var useEntityEvent = ({ instance, ...handlers }) => {
-  const eventsSetRef = useRef9(/* @__PURE__ */ new Set());
-  useEffect18(() => {
+  const eventsSetRef = useRef10(/* @__PURE__ */ new Set());
+  useEffect17(() => {
     const entity = instance.entity;
     if (!entity) return;
     Object.entries(eventMap).forEach(([reactKey, spatialEvent]) => {
@@ -2771,7 +3078,7 @@ var useEntityEvent = ({ instance, ...handlers }) => {
     return () => {
     };
   }, [instance.entity, ...Object.values(handlers)]);
-  useEffect18(() => {
+  useEffect17(() => {
     const entity = instance.entity;
     if (!entity) return;
     return () => {
@@ -2785,7 +3092,7 @@ var useEntityEvent = ({ instance, ...handlers }) => {
 };
 
 // src/reality/hooks/useRealityEvents.tsx
-import { useEffect as useEffect19, useRef as useRef10 } from "react";
+import { useEffect as useEffect18, useRef as useRef11 } from "react";
 function createEventProxy3(ev, instance) {
   return new Proxy(ev, {
     get(target, prop) {
@@ -2899,8 +3206,8 @@ function createEventProxy3(ev, instance) {
   });
 }
 var useRealityEvents = ({ instance, ...handlers }) => {
-  const eventsSetRef = useRef10(/* @__PURE__ */ new Set());
-  useEffect19(() => {
+  const eventsSetRef = useRef11(/* @__PURE__ */ new Set());
+  useEffect18(() => {
     if (!instance) return;
     Object.entries(eventMap).forEach(([reactKey, spatialEvent]) => {
       const handlerFn = handlers[reactKey];
@@ -2921,10 +3228,10 @@ var useRealityEvents = ({ instance, ...handlers }) => {
 };
 
 // src/reality/hooks/useEntityId.tsx
-import { useEffect as useEffect20 } from "react";
+import { useEffect as useEffect19 } from "react";
 var useEntityId = ({ id, entity }) => {
   const ctx = useRealityContext();
-  useEffect20(() => {
+  useEffect19(() => {
     if (!id || !entity || !ctx) return;
     ctx.resourceRegistry.add(id, Promise.resolve(entity));
     return () => {
@@ -2935,7 +3242,7 @@ var useEntityId = ({ id, entity }) => {
 };
 
 // src/reality/hooks/useEntity.tsx
-import { useEffect as useEffect21, useRef as useRef11 } from "react";
+import { useEffect as useEffect20, useRef as useRef12 } from "react";
 var useEntity = ({
   ref,
   id,
@@ -2956,9 +3263,9 @@ var useEntity = ({
 }) => {
   const ctx = useRealityContext();
   const parent = useParentContext();
-  const instanceRef = useRef11(new EntityRef(null, ctx));
+  const instanceRef = useRef12(new EntityRef(null, ctx));
   const forceUpdate = useForceUpdate2();
-  useEffect21(() => {
+  useEffect20(() => {
     if (!ctx) return;
     const controller = new AbortController();
     const init = async () => {
@@ -3007,7 +3314,7 @@ var useEntity = ({
     onSpatialMagnify,
     onSpatialMagnifyEnd
   });
-  useEffect21(() => {
+  useEffect20(() => {
     const ent = instanceRef.current.entity;
     if (!ent) return;
     if (enableInput !== void 0) {
@@ -3018,10 +3325,10 @@ var useEntity = ({
 };
 
 // src/reality/hooks/useForceUpdate.tsx
-import { useCallback as useCallback8, useState as useState7 } from "react";
+import { useCallback as useCallback9, useState as useState9 } from "react";
 var useForceUpdate2 = () => {
-  const [, setTick] = useState7(0);
-  return useCallback8(() => setTick((tick) => tick + 1), []);
+  const [, setTick] = useState9(0);
+  return useCallback9(() => setTick((tick) => tick + 1), []);
 };
 
 // src/reality/components/BaseEntity.tsx
@@ -3060,18 +3367,18 @@ var Entity = forwardRef11((props, ref) => {
 import { forwardRef as forwardRef13 } from "react";
 
 // src/reality/components/GeometryEntity.tsx
-import { forwardRef as forwardRef12, useEffect as useEffect22, useRef as useRef12 } from "react";
+import { forwardRef as forwardRef12, useEffect as useEffect21, useRef as useRef13 } from "react";
 import { jsx as jsx14 } from "react/jsx-runtime";
 var GeometryEntity = forwardRef12(
   ({ id, children, name, materials, geometryOptions, createGeometry, ...rest }, ref) => {
     const ctx = useRealityContext();
-    const entityRef = useRef12(null);
-    const componentRef = useRef12(null);
-    const mutableRef = useRef12({
+    const entityRef = useRef13(null);
+    const componentRef = useRef13(null);
+    const mutableRef = useRef13({
       lastSnapshot: null,
       rebuildGen: 0
     });
-    useEffect22(() => {
+    useEffect21(() => {
       const { lastSnapshot } = mutableRef.current;
       if (!ctx || !entityRef.current || lastSnapshot === null) return;
       const geometryChanged = !shallowEqualObject(
@@ -3193,22 +3500,50 @@ var BoxEntity = forwardRef13(
 );
 
 // src/reality/components/UnlitMaterial.tsx
-import { useEffect as useEffect23, useRef as useRef13 } from "react";
+import { useEffect as useEffect22, useRef as useRef14, useState as useState10 } from "react";
 var UnlitMaterial = ({
   children,
   ...options
 }) => {
   const ctx = useRealityContext();
-  const materialRef = useRef13();
-  const isInitializedRef = useRef13(false);
-  useEffect23(() => {
+  const materialRef = useRef14(void 0);
+  const isInitializedRef = useRef14(false);
+  const [textureRevision, setTextureRevision] = useState10(0);
+  useEffect22(() => {
+    if (!ctx || !options.textureId) return;
+    return ctx.resourceRegistry.subscribe(options.textureId, () => {
+      setTextureRevision((v) => v + 1);
+    });
+  }, [ctx, options.textureId]);
+  useEffect22(() => {
     if (!ctx) return;
-    const { session, reality, resourceRegistry } = ctx;
+    let cancelled = false;
+    const materialId = options.id;
+    const { session, resourceRegistry } = ctx;
     const init = async () => {
-      const materialPromise = session.createUnlitMaterial(options);
-      resourceRegistry.add(options.id, materialPromise);
       try {
+        let textureIdForNative = options.textureId;
+        if (options.textureId) {
+          const texturePromise = resourceRegistry.get(options.textureId);
+          try {
+            const textureResource = await texturePromise;
+            if (cancelled) return;
+            textureIdForNative = textureResource.id;
+          } catch {
+            textureIdForNative = "";
+          }
+        }
+        if (cancelled) return;
+        const commandOptions = {
+          color: options.color,
+          textureId: textureIdForNative,
+          transparent: options.transparent,
+          opacity: options.opacity
+        };
+        const materialPromise = session.createUnlitMaterial(commandOptions);
+        resourceRegistry.add(materialId, materialPromise);
         const mat = await materialPromise;
+        if (cancelled) return;
         materialRef.current = mat;
         isInitializedRef.current = true;
       } catch (error) {
@@ -3217,22 +3552,110 @@ var UnlitMaterial = ({
     };
     init();
     return () => {
-      resourceRegistry.removeAndDestroy(options.id);
+      cancelled = true;
+      resourceRegistry.removeAndDestroy(materialId);
       materialRef.current = void 0;
       isInitializedRef.current = false;
     };
-  }, [ctx]);
+  }, [ctx, options.id]);
+  useEffect22(() => {
+    if (!ctx || !isInitializedRef.current || !materialRef.current) return;
+    let cancelled = false;
+    void (async () => {
+      const updates = {};
+      if (options.color !== void 0) updates.color = options.color;
+      if (options.transparent !== void 0)
+        updates.transparent = options.transparent;
+      if (options.opacity !== void 0) updates.opacity = options.opacity;
+      if (options.textureId !== void 0) {
+        if (options.textureId === "") {
+          updates.textureId = "";
+        } else {
+          const texturePromise = ctx.resourceRegistry.get(options.textureId);
+          try {
+            const textureResource = await texturePromise;
+            if (cancelled) return;
+            updates.textureId = textureResource.id;
+          } catch {
+            updates.textureId = "";
+          }
+        }
+      }
+      if (cancelled || Object.keys(updates).length === 0) return;
+      const mat = materialRef.current;
+      if (mat) {
+        void mat.updateProperties(updates).catch(() => {
+        });
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    ctx,
+    options.color,
+    options.textureId,
+    options.transparent,
+    options.opacity,
+    textureRevision
+  ]);
+  return null;
+};
+
+// src/reality/components/Texture.tsx
+import { useEffect as useEffect23, useRef as useRef15 } from "react";
+var Texture = ({
+  children,
+  id,
+  url,
+  onLoad,
+  onError
+}) => {
+  const ctx = useRealityContext();
+  const textureRef = useRef15(null);
+  const urlRevisionRef = useRef15(0);
+  useEffect23(() => {
+    if (!ctx) return;
+    const { resourceRegistry } = ctx;
+    const capturedId = id;
+    return () => {
+      textureRef.current = null;
+      resourceRegistry.removeAndDestroy(capturedId);
+    };
+  }, [ctx, id]);
   useEffect23(() => {
-    if (!isInitializedRef.current || !materialRef.current) return;
-    const updates = {};
-    if (options.color !== void 0) updates.color = options.color;
-    if (options.transparent !== void 0)
-      updates.transparent = options.transparent;
-    if (options.opacity !== void 0) updates.opacity = options.opacity;
-    if (Object.keys(updates).length > 0) {
-      materialRef.current.updateProperties(updates);
-    }
-  }, [options.color, options.transparent, options.opacity]);
+    if (!ctx) return;
+    const { session, resourceRegistry } = ctx;
+    const revision = ++urlRevisionRef.current;
+    let cancelled = false;
+    void (async () => {
+      const resolvedUrl = getAbsoluteUrl(url);
+      try {
+        if (textureRef.current) {
+          await textureRef.current.updateProperties({ url: resolvedUrl });
+          if (cancelled || revision !== urlRevisionRef.current) return;
+          resourceRegistry.notify(id);
+          onLoad?.();
+          return;
+        }
+        const texturePromise = session.createTexture({ url: resolvedUrl });
+        resourceRegistry.add(id, texturePromise);
+        const tex = await texturePromise;
+        if (cancelled || revision !== urlRevisionRef.current) {
+          tex.destroy();
+          return;
+        }
+        textureRef.current = tex;
+        onLoad?.();
+      } catch (error) {
+        if (cancelled || revision !== urlRevisionRef.current) return;
+        onError?.(error);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [ctx, id, url]);
   return null;
 };
 
@@ -3331,23 +3754,17 @@ var SceneGraph = ({ children }) => {
 };
 
 // src/reality/components/ModelAsset.tsx
-import { useEffect as useEffect24, useRef as useRef14 } from "react";
-var resolveAssetUrl = (url) => {
-  if (url.startsWith("http://") || url.startsWith("https://")) {
-    return url;
-  }
-  return new URL(url, window.location.href).href;
-};
+import { useEffect as useEffect24, useRef as useRef16 } from "react";
 var ModelAsset = ({ children, ...options }) => {
   const ctx = useRealityContext();
-  const materialRef = useRef14();
+  const materialRef = useRef16(void 0);
   useEffect24(() => {
     const controller = new AbortController();
     if (!ctx) return;
-    const { session, reality, resourceRegistry } = ctx;
+    const { session, resourceRegistry } = ctx;
     const init = async () => {
       try {
-        const resolvedUrl = resolveAssetUrl(options.src);
+        const resolvedUrl = getAbsoluteUrl(options.src);
         const modelAssetPromise = session.createModelAsset({ url: resolvedUrl });
         resourceRegistry.add(options.id, modelAssetPromise);
         const mat = await modelAssetPromise;
@@ -3371,13 +3788,13 @@ var ModelAsset = ({ children, ...options }) => {
 };
 
 // src/reality/components/ModelEntity.tsx
-import { forwardRef as forwardRef18, useEffect as useEffect25, useRef as useRef15 } from "react";
+import { forwardRef as forwardRef18, useEffect as useEffect25, useRef as useRef17 } from "react";
 import { jsx as jsx21 } from "react/jsx-runtime";
 var ModelEntity = forwardRef18(
   ({ id, model, children, name, materials, ...rest }, ref) => {
     const ctx = useRealityContext();
-    const entityRef = useRef15(null);
-    const lastMaterialsRef = useRef15(void 0);
+    const entityRef = useRef17(null);
+    const lastMaterialsRef = useRef17(void 0);
     useEffect25(() => {
       if (!ctx || !entityRef.current) return;
       const next = materials ?? [];
@@ -3386,9 +3803,7 @@ var ModelEntity = forwardRef18(
       lastMaterialsRef.current = next;
       const apply = async () => {
         try {
-          const materialList = (await Promise.all(
-            next.map((mid) => ctx.resourceRegistry.get(mid))
-          )).filter(Boolean);
+          const materialList = (await Promise.all(next.map((mid) => ctx.resourceRegistry.get(mid)))).filter(Boolean);
           if (entityRef.current) {
             await entityRef.current.setMaterials(materialList);
           }
@@ -3421,9 +3836,7 @@ var ModelEntity = forwardRef18(
             entityRef.current = ent;
             if (materials && materials.length > 0) {
               const materialList = (await Promise.all(
-                materials.map(
-                  (mid) => ctx2.resourceRegistry.get(mid)
-                )
+                materials.map((mid) => ctx2.resourceRegistry.get(mid))
               )).filter(Boolean);
               if (materialList.length > 0 && !signal.aborted) {
                 await ent.setMaterials(materialList);
@@ -3444,10 +3857,10 @@ var ModelEntity = forwardRef18(
 // src/reality/components/Reality.tsx
 import {
   forwardRef as forwardRef19,
-  useCallback as useCallback9,
+  useCallback as useCallback10,
   useEffect as useEffect26,
-  useRef as useRef16,
-  useState as useState8
+  useRef as useRef18,
+  useState as useState11
 } from "react";
 import { Fragment as Fragment3, jsx as jsx22, jsxs as jsxs3 } from "react/jsx-runtime";
 var Reality = forwardRef19(
@@ -3470,10 +3883,10 @@ var Reality = forwardRef19(
       onSpatialMagnifyEnd,
       ...props
     } = inProps;
-    const ctxRef = useRef16(null);
-    const creationId = useRef16(0);
-    const [isReady, setIsReady] = useState8(false);
-    const cleanupReality = useCallback9(() => {
+    const ctxRef = useRef18(null);
+    const creationId = useRef18(0);
+    const [isReady, setIsReady] = useState11(false);
+    const cleanupReality = useCallback10(() => {
       ctxRef.current?.attachmentRegistry.destroy();
       ctxRef.current?.resourceRegistry.destroy();
       ctxRef.current?.reality.destroy();
@@ -3486,7 +3899,7 @@ var Reality = forwardRef19(
         cleanupReality();
       };
     }, [cleanupReality]);
-    const createReality = useCallback9(async () => {
+    const createReality = useCallback10(async () => {
       const id = ++creationId.current;
       const resourceRegistry = new ResourceRegistry();
       const attachmentRegistry = new AttachmentRegistry();
@@ -3529,7 +3942,7 @@ var Reality = forwardRef19(
         return null;
       }
     }, [cleanupReality]);
-    const content = useCallback9(() => /* @__PURE__ */ jsx22(Fragment3, {}), []);
+    const content = useCallback10(() => /* @__PURE__ */ jsx22(Fragment3, {}), []);
     useRealityEvents({
       instance: ctxRef.current?.reality ?? null,
       onSpatialTap,
@@ -3558,7 +3971,7 @@ var Reality = forwardRef19(
 );
 
 // src/reality/components/AttachmentAsset.tsx
-import { useEffect as useEffect27, useState as useState9 } from "react";
+import { useEffect as useEffect27, useState as useState12 } from "react";
 import { createPortal as createPortal3 } from "react-dom";
 import { jsx as jsx23 } from "react/jsx-runtime";
 var AttachmentAsset = ({
@@ -3566,7 +3979,7 @@ var AttachmentAsset = ({
   children
 }) => {
   const ctx = useRealityContext();
-  const [containers, setContainers] = useState9([]);
+  const [containers, setContainers] = useState12([]);
   useEffect27(() => {
     if (!ctx) return;
     return ctx.attachmentRegistry.onContainersChange(name, setContainers);
@@ -3578,7 +3991,7 @@ var AttachmentAsset = ({
 };
 
 // src/reality/components/AttachmentEntity.tsx
-import { useEffect as useEffect28, useRef as useRef17, useState as useState10 } from "react";
+import { useEffect as useEffect28, useRef as useRef19, useState as useState13 } from "react";
 var instanceCounter = 0;
 var AttachmentEntity = ({
   attachment: attachmentName,
@@ -3587,11 +4000,11 @@ var AttachmentEntity = ({
 }) => {
   const ctx = useRealityContext();
   const parent = useParentContext();
-  const attachmentRef = useRef17(null);
-  const parentIdRef = useRef17(null);
-  const instanceIdRef = useRef17(`att_${++instanceCounter}`);
-  const attachmentNameRef = useRef17(attachmentName);
-  const [childWindow, setChildWindow] = useState10(null);
+  const attachmentRef = useRef19(null);
+  const parentIdRef = useRef19(null);
+  const instanceIdRef = useRef19(`att_${++instanceCounter}`);
+  const attachmentNameRef = useRef19(attachmentName);
+  const [childWindow, setChildWindow] = useState13(null);
   useEffect28(() => {
     if (!ctx || !parent) return;
     if (attachmentRef.current) return;
@@ -3670,7 +4083,7 @@ var AttachmentEntity = ({
       attachmentNameRef.current = attachmentName;
     }
   }, [ctx, attachmentName]);
-  useSyncHeadStyles(childWindow, { subtree: false });
+  useSyncHeadStyles(childWindow);
   useEffect28(() => {
     if (!attachmentRef.current) return;
     attachmentRef.current.update({ position, size });
@@ -3734,7 +4147,7 @@ var styleFlag = "enableXr";
 var classFlag = "__enableXr__";
 var xrMonitorFlag = "enable-xr-monitor";
 function replaceToSpatialPrimitiveType(type, props) {
-  if (type === Model) {
+  if (type === Model || type === Reality) {
     return type;
   }
   const propsObject = props;
@@ -3777,7 +4190,7 @@ function resolveSpatialObjectId(target) {
   if (maybeEntity && typeof maybeEntity === "object" && "entity" in maybeEntity) {
     return maybeEntity.entity?.id ?? null;
   }
-  const dom = target?.__raw ?? target;
+  const dom = target;
   if (dom && typeof dom === "object") {
     const spatializedElement = dom.__spatializedElement ?? dom.__innerSpatializedElement?.();
     if (spatializedElement && spatializedElement.id) {
@@ -3807,7 +4220,7 @@ async function convertCoordinate(position, { from, to }) {
 }
 
 // src/index.ts
-var version = "1.6.1";
+var version = "1.7.0";
 if (typeof window !== "undefined") {
   initPolyfill();
 }
@@ -3836,12 +4249,16 @@ export {
   SpatializedStatic3DElementContainer,
   SphereEntity as Sphere,
   SphereEntity,
+  Texture,
   UnlitMaterial,
+  WebSpatialRuntime,
+  WebSpatialRuntimeError,
   SceneGraph as World,
   convertCoordinate,
   createElement,
   enableDebugTool,
   eventMap,
+  getAbsoluteUrl,
   initPolyfill,
   initScene,
   useMetrics,