@webspatial/react-sdk 1.4.0 → 1.6.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.4.0"
+        window.__webspatialsdk__['react-sdk-version'] = "1.6.0"
         window.__webspatialsdk__['XR_ENV'] = "avp"
     })()
       
@@ -145,11 +145,20 @@ function joinToCSSText(cssKV) {
 }
 
 // src/spatialized-container/hooks/useDomProxy.ts
-function makeOriginalKey(key) {
-  return `__original_${key}`;
-}
 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;
@@ -159,211 +168,263 @@ var SpatialContainerRefProxy = class {
     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) {
-      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);
+    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
+                            );
                           }
-                        }.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);
+                          return value2.apply(this, args);
                         }
-                      });
-                      const appendedCSSText = joinToCSSText({
-                        transform: "none",
-                        visibility: "hidden"
-                      });
-                      return Reflect.set(
-                        target2,
-                        prop2,
-                        [appendedCSSText, filteredCssText].join(";")
-                      );
+                      }.bind(target2);
+                    } else {
+                      return value2.bind(target2);
                     }
-                    return Reflect.set(target2, prop2, value2);
+                  } else {
+                    return 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 = "";
-                    }
+                },
+                set(target2, prop2, value2) {
+                  if (prop2 === "visibility") {
+                    self.transformVisibilityTaskContainerDom?.style.setProperty(
+                      "visibility",
+                      value2
+                    );
                     return true;
                   }
-                  if (property === "class") {
-                    domProxy.className = "xr-spatial-default";
+                  if (prop2 === "transform") {
+                    self.transformVisibilityTaskContainerDom?.style.setProperty(
+                      "transform",
+                      value2
+                    );
                     return true;
                   }
-                };
-              }
-              return value.bind(target);
+                  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 value;
-          },
-          set(target, prop, value) {
-            if (prop === "className") {
-              if (value && value.indexOf("xr-spatial-default") === -1) {
-                value = value + " xr-spatial-default";
-              }
-              if (self.transformVisibilityTaskContainerDom) {
-                self.transformVisibilityTaskContainerDom.className = value;
-              }
+            return self.styleProxy;
+          }
+          if (typeof prop === "string" && self.extraRefProps) {
+            if (!cacheExtraRefProps) {
+              cacheExtraRefProps = self.extraRefProps(domProxy);
             }
-            if (typeof prop === "string" && self.extraRefProps) {
-              if (!cacheExtraRefProps) {
-                cacheExtraRefProps = self.extraRefProps(domProxy);
-              }
-              cacheExtraRefProps[prop] = value;
+            const extraProps = cacheExtraRefProps;
+            if (extraProps.hasOwnProperty(prop)) {
+              return extraProps[prop];
             }
-            return Reflect.set(target, prop, value);
           }
-        }
-      );
-      this.domProxy = domProxy;
-      const domClassList = dom.classList;
-      const domClassMethodKeys = ["add", "remove", "toggle", "replace"];
-      domClassMethodKeys.forEach((key) => {
-        const hiddenKey = makeOriginalKey(key);
-        const hiddenKeyExist = domClassList[hiddenKey] !== void 0;
-        const originalMethod = hiddenKeyExist ? domClassList[hiddenKey] : domClassList[key].bind(domClassList);
-        domClassList[hiddenKey] = originalMethod;
-        domClassList[key] = function(...args) {
-          const result = originalMethod(...args);
-          if (self.transformVisibilityTaskContainerDom) {
-            self.transformVisibilityTaskContainerDom.className = dom.className;
+          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 result;
-        };
-      });
-      this.styleProxy = void 0;
-      this.updateDomProxyToRef();
-      Object.assign(dom, {
-        __targetProxy: domProxy
-      });
-    }
+          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() {
@@ -843,7 +904,14 @@ var TransformVisibilityTaskContainer = forwardRef2(
 );
 
 // src/spatialized-container/SpatializedContainer.tsx
-import { forwardRef as forwardRef4, useContext as useContext7, useEffect as useEffect10, useMemo as useMemo2 } from "react";
+import {
+  forwardRef as forwardRef4,
+  useCallback as useCallback6,
+  useContext as useContext7,
+  useEffect as useEffect10,
+  useMemo as useMemo2,
+  useState as useState6
+} from "react";
 
 // src/utils/getSession.ts
 import { isSSREnv, Spatial } from "@webspatial/core-sdk";
@@ -1148,7 +1216,7 @@ function renderPlaceholderInSubPortal(portalInstanceObject, El) {
     return /* @__PURE__ */ jsx3(Fragment, {});
   }
   const { width, height } = portalInstanceObject.domRect;
-  const display = portalInstanceObject.computedStyle.getPropertyPriority("display");
+  const display = portalInstanceObject.computedStyle.getPropertyValue("display");
   const spatialIdProps = { [SpatialID]: spatialId };
   return /* @__PURE__ */ jsx3(
     El,
@@ -1593,6 +1661,20 @@ function SpatializedContainerBase(inprops, ref) {
         standardSpatializedContainerCallback,
         spatialContainerRefProxy
       } = useDomProxy(ref, extraRefProps);
+      const [probeClassName, setProbeClassName] = useState6(
+        () => props.className ?? ""
+      );
+      const notifyProbeClass = useCallback6((name) => {
+        setProbeClassName((prev) => prev === name ? prev : name);
+      }, []);
+      useEffect10(() => {
+        spatialContainerRefProxy.current.setMirrorClassNotify?.(
+          notifyProbeClass
+        );
+        return () => {
+          spatialContainerRefProxy.current.setMirrorClassNotify?.(null);
+        };
+      }, [spatialContainerRefProxy, notifyProbeClass]);
       useEffect10(() => {
         rootSpatializedContainerObject.updateSpatialContainerRefProxyInfo(
           spatialId,
@@ -1621,7 +1703,7 @@ function SpatializedContainerBase(inprops, ref) {
           {
             ref: transformVisibilityTaskContainerCallback,
             ...spatialIdProps,
-            className: props.className,
+            className: probeClassName,
             style: props.style
           }
         )
@@ -1633,6 +1715,18 @@ function SpatializedContainerBase(inprops, ref) {
       standardSpatializedContainerCallback,
       spatialContainerRefProxy
     } = useDomProxy(ref, extraRefProps);
+    const [probeClassName, setProbeClassName] = useState6(
+      () => props.className ?? ""
+    );
+    const notifyProbeClass = useCallback6((name) => {
+      setProbeClassName((prev) => prev === name ? prev : name);
+    }, []);
+    useEffect10(() => {
+      spatialContainerRefProxy.current.setMirrorClassNotify?.(notifyProbeClass);
+      return () => {
+        spatialContainerRefProxy.current.setMirrorClassNotify?.(null);
+      };
+    }, [spatialContainerRefProxy, notifyProbeClass]);
     const spatialEvents = useSpatialEvents(
       {
         onSpatialTap,
@@ -1684,7 +1778,7 @@ function SpatializedContainerBase(inprops, ref) {
             {
               ref: transformVisibilityTaskContainerCallback,
               ...spatialIdProps,
-              className: props.className,
+              className: probeClassName,
               style: props.style
             }
           )
@@ -1964,8 +2058,10 @@ var Spatialized2DElementContainer = forwardRef5(
 
 // src/spatialized-container/SpatializedStatic3DElementContainer.tsx
 import {
+  Children,
   forwardRef as forwardRef6,
-  useCallback as useCallback6,
+  isValidElement,
+  useCallback as useCallback7,
   useContext as useContext9,
   useEffect as useEffect13,
   useMemo as useMemo3,
@@ -1973,9 +2069,7 @@ import {
 } from "react";
 import { Fragment as Fragment2, jsx as jsx8 } from "react/jsx-runtime";
 function getAbsoluteURL(url) {
-  if (!url) {
-    return "";
-  }
+  if (!url) return url;
   try {
     return new URL(url, document.baseURI).toString();
   } catch {
@@ -2003,21 +2097,34 @@ function createLoadFailureEvent(targetGetter) {
 function createLoadSuccessEvent(targetGetter) {
   return createLoadEvent("modelloaded", targetGetter);
 }
+function collectSources(children) {
+  const sources = [];
+  Children.forEach(children, (child) => {
+    if (isValidElement(child) && child.type === "source") {
+      const { src, type } = child.props;
+      if (src) {
+        sources.push({ src: getAbsoluteURL(src), type });
+      }
+    }
+  });
+  return sources;
+}
 function SpatializedContent2(props) {
-  const { src, spatializedElement, onLoad, onError } = props;
-  const spatializedStatic3DElement = spatializedElement;
-  const portalInstanceObject = useContext9(
-    PortalInstanceContext
-  );
-  const currentSrc = useMemo3(() => getAbsoluteURL(src), [src]);
+  const { src, children, spatializedElement, onLoad, onError, autoPlay, loop } = props;
+  const portalInstanceObject = useContext9(PortalInstanceContext);
+  const modelURL = useMemo3(() => getAbsoluteURL(src), [src]);
+  const sources = useMemo3(() => collectSources(children), [children]);
   useEffect13(() => {
-    if (src) {
-      spatializedStatic3DElement.updateProperties({ modelURL: currentSrc });
-    }
-  }, [currentSrc]);
+    spatializedElement.updateProperties({
+      modelURL: modelURL ?? "",
+      sources,
+      autoplay: autoPlay,
+      loop
+    });
+  }, [modelURL, JSON.stringify(sources), autoPlay, loop]);
   useEffect13(() => {
     if (onLoad) {
-      spatializedStatic3DElement.onLoadCallback = () => {
+      spatializedElement.onLoadCallback = () => {
         onLoad(
           createLoadSuccessEvent(
             () => portalInstanceObject.dom.__targetProxy
@@ -2025,12 +2132,12 @@ function SpatializedContent2(props) {
         );
       };
     } else {
-      spatializedStatic3DElement.onLoadCallback = void 0;
+      spatializedElement.onLoadCallback = void 0;
     }
   }, [onLoad]);
   useEffect13(() => {
     if (onError) {
-      spatializedStatic3DElement.onLoadFailureCallback = () => {
+      spatializedElement.onLoadFailureCallback = () => {
         onError(
           createLoadFailureEvent(
             () => portalInstanceObject.dom.__targetProxy
@@ -2038,24 +2145,27 @@ function SpatializedContent2(props) {
         );
       };
     } else {
-      spatializedStatic3DElement.onLoadFailureCallback = void 0;
+      spatializedElement.onLoadFailureCallback = void 0;
     }
   }, [onError]);
   return /* @__PURE__ */ jsx8(Fragment2, {});
 }
 function SpatializedStatic3DElementContainerBase(props, ref) {
   const promiseRef = useRef5(null);
-  const createSpatializedElement2 = useCallback6(() => {
-    const url = getAbsoluteURL(props.src);
-    promiseRef.current = getSession().createSpatializedStatic3DElement(url);
+  const createSpatializedElement2 = useCallback7(() => {
+    promiseRef.current = getSession().createSpatializedStatic3DElement(
+      getAbsoluteURL(props.src),
+      collectSources(props.children)
+    );
     return promiseRef.current;
   }, []);
-  const extraRefProps = useCallback6(
+  const extraRefProps = useCallback7(
     (domProxy) => {
       let modelTransform = new DOMMatrixReadOnly();
       return {
         get currentSrc() {
-          return getAbsoluteURL(props.src);
+          const spatializedElement = domProxy.__spatializedElement;
+          return spatializedElement?.currentSrc ?? "";
         },
         get ready() {
           return promiseRef.current.then((spatializedElement) => spatializedElement.ready).then((success) => {
@@ -2070,6 +2180,32 @@ function SpatializedStatic3DElementContainerBase(props, ref) {
           modelTransform = value;
           const spatializedElement = domProxy.__spatializedElement;
           spatializedElement?.updateModelTransform(modelTransform);
+        },
+        async play() {
+          const spatializedElement = domProxy.__spatializedElement;
+          await spatializedElement?.play();
+        },
+        async pause() {
+          const spatializedElement = domProxy.__spatializedElement;
+          await spatializedElement?.pause();
+        },
+        get paused() {
+          const spatializedElement = domProxy.__spatializedElement;
+          return spatializedElement?.paused ?? true;
+        },
+        get duration() {
+          const spatializedElement = domProxy.__spatializedElement;
+          return spatializedElement?.duration ?? 0;
+        },
+        get playbackRate() {
+          const spatializedElement = domProxy.__spatializedElement;
+          return spatializedElement?.playbackRate ?? 1;
+        },
+        set playbackRate(value) {
+          const spatializedElement = domProxy.__spatializedElement;
+          if (spatializedElement) {
+            spatializedElement.playbackRate = value;
+          }
         }
       };
     },
@@ -2349,6 +2485,20 @@ function shallowEqualRotation(a, b) {
   if (!a || !b) return false;
   return a.x === b.x && a.y === b.y && a.z === b.z && ("w" in a ? a.w === b.w : true);
 }
+function shallowEqualObject(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((key) => a[key] === b[key]);
+}
+function shallowEqualArray(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.length !== b.length) return false;
+  return a.every((val, i) => val === b[i]);
+}
 
 // src/reality/utils/AbortResourceManager.ts
 var AbortResourceManager = class {
@@ -2493,9 +2643,150 @@ var EntityRef = class {
   }
 };
 
+// src/reality/hooks/useEntityEvent.tsx
+function createEventProxy2(ev, instance) {
+  return new Proxy(ev, {
+    get(target, prop) {
+      if (prop === "currentTarget") {
+        return instance;
+      }
+      if (prop === "target") {
+        const origin = target.__origin;
+        if (origin) {
+          return new EntityRef(origin, null);
+        }
+        return instance;
+      }
+      if (prop === "bubbles") {
+        return true;
+      }
+      if (prop === "offsetX") {
+        const type = target.type;
+        if (type === "spatialtap") {
+          return target.detail?.location3D?.x ?? 0;
+        }
+        if (type === "spatialdragstart") {
+          return target.detail?.startLocation3D?.x ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "offsetY") {
+        const type = target.type;
+        if (type === "spatialtap") {
+          return target.detail?.location3D?.y ?? 0;
+        }
+        if (type === "spatialdragstart") {
+          return target.detail?.startLocation3D?.y ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "offsetZ") {
+        const type = target.type;
+        if (type === "spatialtap") {
+          return target.detail?.location3D?.z ?? 0;
+        }
+        if (type === "spatialdragstart") {
+          return target.detail?.startLocation3D?.z ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "translationX") {
+        const type = target.type;
+        if (type === "spatialdrag") {
+          return target.detail?.translation3D?.x ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "translationY") {
+        const type = target.type;
+        if (type === "spatialdrag") {
+          return target.detail?.translation3D?.y ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "translationZ") {
+        const type = target.type;
+        if (type === "spatialdrag") {
+          return target.detail?.translation3D?.z ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "quaternion") {
+        const type = target.type;
+        if (type === "spatialrotate") {
+          return target.detail?.quaternion ?? {
+            x: 0,
+            y: 0,
+            z: 0,
+            w: 1
+          };
+        }
+        return void 0;
+      }
+      if (prop === "magnification") {
+        const type = target.type;
+        if (type === "spatialmagnify") {
+          return target.detail?.magnification ?? 1;
+        }
+        return void 0;
+      }
+      if (prop === "clientX") {
+        const type = target.type;
+        if (type === "spatialtap" || type === "spatialdragstart") {
+          return target.detail?.globalLocation3D?.x ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "clientY") {
+        const type = target.type;
+        if (type === "spatialtap" || type === "spatialdragstart") {
+          return target.detail?.globalLocation3D?.y ?? 0;
+        }
+        return void 0;
+      }
+      if (prop === "clientZ") {
+        const type = target.type;
+        if (type === "spatialtap" || type === "spatialdragstart") {
+          return target.detail?.globalLocation3D?.z ?? 0;
+        }
+        return void 0;
+      }
+      const val = target[prop];
+      return typeof val === "function" ? val.bind(target) : val;
+    }
+  });
+}
+var useEntityEvent = ({ instance, ...handlers }) => {
+  const eventsSetRef = useRef9(/* @__PURE__ */ new Set());
+  useEffect18(() => {
+    const entity = instance.entity;
+    if (!entity) return;
+    Object.entries(eventMap).forEach(([reactKey, spatialEvent]) => {
+      const handlerFn = handlers[reactKey];
+      if (!handlerFn) return;
+      const wrapped = (ev) => handlerFn(createEventProxy2(ev, instance));
+      entity.addEvent(spatialEvent, wrapped);
+      eventsSetRef.current.add(reactKey);
+    });
+    return () => {
+    };
+  }, [instance.entity, ...Object.values(handlers)]);
+  useEffect18(() => {
+    const entity = instance.entity;
+    if (!entity) return;
+    return () => {
+      for (let x of eventsSetRef.current) {
+        entity.removeEvent(x);
+      }
+      eventsSetRef.current.clear();
+    };
+  }, [instance.entity]);
+  return null;
+};
+
 // src/reality/hooks/useRealityEvents.tsx
 import { useEffect as useEffect19, useRef as useRef10 } from "react";
-function createEventProxy2(ev, instance) {
+function createEventProxy3(ev, instance) {
   return new Proxy(ev, {
     get(target, prop) {
       if (prop === "currentTarget") {
@@ -2614,7 +2905,7 @@ var useRealityEvents = ({ instance, ...handlers }) => {
     Object.entries(eventMap).forEach(([reactKey, spatialEvent]) => {
       const handlerFn = handlers[reactKey];
       if (!handlerFn) return;
-      const wrapped = (ev) => handlerFn(createEventProxy2(ev, instance));
+      const wrapped = (ev) => handlerFn(createEventProxy3(ev, instance));
       instance.addEvent(spatialEvent, wrapped);
       eventsSetRef.current.add(spatialEvent);
     });
@@ -2652,7 +2943,16 @@ var useEntity = ({
   rotation,
   scale,
   enableInput,
-  createEntity
+  onSpatialTap,
+  onSpatialDragStart,
+  onSpatialDrag,
+  onSpatialDragEnd,
+  onSpatialRotate,
+  onSpatialRotateEnd,
+  onSpatialMagnify,
+  onSpatialMagnifyEnd,
+  createEntity,
+  recreateKey
 }) => {
   const ctx = useRealityContext();
   const parent = useParentContext();
@@ -2669,6 +2969,11 @@ var useEntity = ({
           ent.destroy();
           return;
         }
+        await ent.updateTransform({ position, rotation, scale });
+        if (controller.signal.aborted) {
+          ent.destroy();
+          return;
+        }
         if (parent) {
           const result = await parent.addEntity(ent);
           if (!result.success) throw new Error("parent.addEntity failed");
@@ -2687,10 +2992,21 @@ var useEntity = ({
       controller.abort();
       instanceRef.current?.destroy();
     };
-  }, [ctx, parent]);
+  }, [ctx, parent, recreateKey]);
   useEntityId({ id, entity: instanceRef.current.entity });
   useEntityTransform(instanceRef.current.entity, { position, rotation, scale });
   useEntityRef(ref, instanceRef.current);
+  useEntityEvent({
+    instance: instanceRef.current,
+    onSpatialTap,
+    onSpatialDragStart,
+    onSpatialDrag,
+    onSpatialDragEnd,
+    onSpatialRotate,
+    onSpatialRotateEnd,
+    onSpatialMagnify,
+    onSpatialMagnifyEnd
+  });
   useEffect21(() => {
     const ent = instanceRef.current.entity;
     if (!ent) return;
@@ -2702,20 +3018,21 @@ var useEntity = ({
 };
 
 // src/reality/hooks/useForceUpdate.tsx
-import { useCallback as useCallback7, useState as useState7 } from "react";
+import { useCallback as useCallback8, useState as useState7 } from "react";
 var useForceUpdate2 = () => {
   const [, setTick] = useState7(0);
-  return useCallback7(() => setTick((tick) => tick + 1), []);
+  return useCallback8(() => setTick((tick) => tick + 1), []);
 };
 
 // src/reality/components/BaseEntity.tsx
 import { jsx as jsx12 } from "react/jsx-runtime";
 var BaseEntity = forwardRef10(
-  ({ children, createEntity, ...rest }, ref) => {
+  ({ children, createEntity, recreateKey, ...rest }, ref) => {
     const ctx = useRealityContext();
     const entity = useEntity({
       ...rest,
       ref,
+      recreateKey,
       createEntity: (signal) => createEntity(ctx, signal)
     });
     if (!entity) return null;
@@ -2743,35 +3060,102 @@ var Entity = forwardRef11((props, ref) => {
 import { forwardRef as forwardRef13 } from "react";
 
 // src/reality/components/GeometryEntity.tsx
-import { forwardRef as forwardRef12 } from "react";
+import { forwardRef as forwardRef12, useEffect as useEffect22, useRef as useRef12 } from "react";
 import { jsx as jsx14 } from "react/jsx-runtime";
 var GeometryEntity = forwardRef12(
   ({ id, children, name, materials, geometryOptions, createGeometry, ...rest }, ref) => {
+    const ctx = useRealityContext();
+    const entityRef = useRef12(null);
+    const componentRef = useRef12(null);
+    const mutableRef = useRef12({
+      lastSnapshot: null,
+      rebuildGen: 0
+    });
+    useEffect22(() => {
+      const { lastSnapshot } = mutableRef.current;
+      if (!ctx || !entityRef.current || lastSnapshot === null) return;
+      const geometryChanged = !shallowEqualObject(
+        lastSnapshot.geometryOptions,
+        geometryOptions
+      );
+      const materialsChanged = !shallowEqualArray(
+        lastSnapshot.materials,
+        materials
+      );
+      if (!geometryChanged && !materialsChanged) return;
+      mutableRef.current.lastSnapshot = { geometryOptions, materials };
+      mutableRef.current.rebuildGen += 1;
+      const gen = mutableRef.current.rebuildGen;
+      const rebuild = async () => {
+        const entity = entityRef.current;
+        if (!entity) return;
+        try {
+          const oldComponent = componentRef.current;
+          if (oldComponent) {
+            await entity.removeComponent(oldComponent);
+            await oldComponent.destroy();
+            componentRef.current = null;
+            if (gen !== mutableRef.current.rebuildGen) return;
+          }
+          const geometry = await createGeometry(geometryOptions);
+          if (gen !== mutableRef.current.rebuildGen) {
+            await geometry.destroy();
+            return;
+          }
+          const materialList = await Promise.all(
+            materials?.map((mid) => ctx.resourceRegistry.get(mid)).filter(Boolean) ?? []
+          );
+          if (gen !== mutableRef.current.rebuildGen) {
+            await geometry.destroy();
+            return;
+          }
+          const modelComponent = await ctx.session.createModelComponent({
+            mesh: geometry,
+            materials: materialList
+          });
+          if (gen !== mutableRef.current.rebuildGen) {
+            await modelComponent.destroy();
+            await geometry.destroy();
+            return;
+          }
+          await entity.addComponent(modelComponent);
+          componentRef.current = modelComponent;
+        } catch (error) {
+          if (gen === mutableRef.current.rebuildGen) {
+            console.error("GeometryEntity: rebuild failed", error);
+          }
+        }
+      };
+      rebuild();
+    }, [ctx, geometryOptions, materials, createGeometry]);
     return /* @__PURE__ */ jsx14(
       BaseEntity,
       {
         ...rest,
         id,
         ref,
-        createEntity: async (ctx, signal) => {
+        createEntity: async (ctx2, signal) => {
           const manager = new AbortResourceManager(signal);
           try {
             const ent = await manager.addResource(
-              () => ctx.session.createEntity({ id, name })
+              () => ctx2.session.createEntity({ id, name })
             );
             const geometry = await manager.addResource(
               () => createGeometry(geometryOptions)
             );
             const materialList = await Promise.all(
-              materials?.map((id2) => ctx.resourceRegistry.get(id2)).filter(Boolean) ?? []
+              materials?.map((id2) => ctx2.resourceRegistry.get(id2)).filter(Boolean) ?? []
             );
             const modelComponent = await manager.addResource(
-              () => ctx.session.createModelComponent({
+              () => ctx2.session.createModelComponent({
                 mesh: geometry,
                 materials: materialList
               })
             );
             await ent.addComponent(modelComponent);
+            entityRef.current = ent;
+            componentRef.current = modelComponent;
+            mutableRef.current.lastSnapshot = { geometryOptions, materials };
             return ent;
           } catch (error) {
             await manager.dispose();
@@ -2809,14 +3193,15 @@ var BoxEntity = forwardRef13(
 );
 
 // src/reality/components/UnlitMaterial.tsx
-import { useEffect as useEffect22, useRef as useRef12 } from "react";
+import { useEffect as useEffect23, useRef as useRef13 } from "react";
 var UnlitMaterial = ({
   children,
   ...options
 }) => {
   const ctx = useRealityContext();
-  const materialRef = useRef12();
-  useEffect22(() => {
+  const materialRef = useRef13();
+  const isInitializedRef = useRef13(false);
+  useEffect23(() => {
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
     const init = async () => {
@@ -2825,6 +3210,7 @@ var UnlitMaterial = ({
       try {
         const mat = await materialPromise;
         materialRef.current = mat;
+        isInitializedRef.current = true;
       } catch (error) {
         console.error(" ~ UnlitMaterial ~ error:", error);
       }
@@ -2832,8 +3218,21 @@ var UnlitMaterial = ({
     init();
     return () => {
       resourceRegistry.removeAndDestroy(options.id);
+      materialRef.current = void 0;
+      isInitializedRef.current = false;
     };
   }, [ctx]);
+  useEffect23(() => {
+    if (!isInitializedRef.current || !materialRef.current) return;
+    const updates = {};
+    if (options.color !== void 0) updates.color = options.color;
+    if (options.transparent !== void 0)
+      updates.transparent = options.transparent;
+    if (options.opacity !== void 0) updates.opacity = options.opacity;
+    if (Object.keys(updates).length > 0) {
+      materialRef.current.updateProperties(updates);
+    }
+  }, [options.color, options.transparent, options.opacity]);
   return null;
 };
 
@@ -2932,7 +3331,7 @@ var SceneGraph = ({ children }) => {
 };
 
 // src/reality/components/ModelAsset.tsx
-import { useEffect as useEffect23, useRef as useRef13 } from "react";
+import { useEffect as useEffect24, useRef as useRef14 } from "react";
 var resolveAssetUrl = (url) => {
   if (url.startsWith("http://") || url.startsWith("https://")) {
     return url;
@@ -2941,8 +3340,8 @@ var resolveAssetUrl = (url) => {
 };
 var ModelAsset = ({ children, ...options }) => {
   const ctx = useRealityContext();
-  const materialRef = useRef13();
-  useEffect23(() => {
+  const materialRef = useRef14();
+  useEffect24(() => {
     const controller = new AbortController();
     if (!ctx) return;
     const { session, reality, resourceRegistry } = ctx;
@@ -2972,29 +3371,66 @@ var ModelAsset = ({ children, ...options }) => {
 };
 
 // src/reality/components/ModelEntity.tsx
-import { forwardRef as forwardRef18 } from "react";
+import { forwardRef as forwardRef18, useEffect as useEffect25, useRef as useRef15 } from "react";
 import { jsx as jsx21 } from "react/jsx-runtime";
 var ModelEntity = forwardRef18(
-  ({ id, model, children, name, ...rest }, ref) => {
+  ({ id, model, children, name, materials, ...rest }, ref) => {
+    const ctx = useRealityContext();
+    const entityRef = useRef15(null);
+    const lastMaterialsRef = useRef15(void 0);
+    useEffect25(() => {
+      if (!ctx || !entityRef.current) return;
+      const next = materials ?? [];
+      const prev = lastMaterialsRef.current ?? [];
+      if (shallowEqualArray(prev, next)) return;
+      lastMaterialsRef.current = next;
+      const apply = async () => {
+        try {
+          const materialList = (await Promise.all(
+            next.map((mid) => ctx.resourceRegistry.get(mid))
+          )).filter(Boolean);
+          if (entityRef.current) {
+            await entityRef.current.setMaterials(materialList);
+          }
+        } catch (error) {
+          console.error("ModelEntity: failed to set materials", error);
+        }
+      };
+      apply();
+    }, [ctx, materials]);
     return /* @__PURE__ */ jsx21(
       BaseEntity,
       {
         ...rest,
         id,
         ref,
-        createEntity: async (ctx, signal) => {
+        recreateKey: model,
+        createEntity: async (ctx2, signal) => {
           try {
-            const modelAsset = await ctx.resourceRegistry.get(model);
+            const modelAsset = await ctx2.resourceRegistry.get(model);
             if (!modelAsset)
               throw new Error(`ModelEntity: model not found ${model}`);
             if (signal.aborted) return null;
-            return ctx.session.createSpatialModelEntity(
+            const ent = await ctx2.session.createSpatialModelEntity(
               {
                 modelAssetId: modelAsset.id,
                 name
               },
               { id, name }
             );
+            entityRef.current = ent;
+            if (materials && materials.length > 0) {
+              const materialList = (await Promise.all(
+                materials.map(
+                  (mid) => ctx2.resourceRegistry.get(mid)
+                )
+              )).filter(Boolean);
+              if (materialList.length > 0 && !signal.aborted) {
+                await ent.setMaterials(materialList);
+              }
+            }
+            lastMaterialsRef.current = materials ?? [];
+            return ent;
           } catch (error) {
             return null;
           }
@@ -3008,9 +3444,9 @@ var ModelEntity = forwardRef18(
 // src/reality/components/Reality.tsx
 import {
   forwardRef as forwardRef19,
-  useCallback as useCallback8,
-  useEffect as useEffect24,
-  useRef as useRef14,
+  useCallback as useCallback9,
+  useEffect as useEffect26,
+  useRef as useRef16,
   useState as useState8
 } from "react";
 import { Fragment as Fragment3, jsx as jsx22, jsxs as jsxs3 } from "react/jsx-runtime";
@@ -3034,23 +3470,23 @@ var Reality = forwardRef19(
       onSpatialMagnifyEnd,
       ...props
     } = inProps;
-    const ctxRef = useRef14(null);
-    const creationId = useRef14(0);
+    const ctxRef = useRef16(null);
+    const creationId = useRef16(0);
     const [isReady, setIsReady] = useState8(false);
-    const cleanupReality = useCallback8(() => {
+    const cleanupReality = useCallback9(() => {
       ctxRef.current?.attachmentRegistry.destroy();
       ctxRef.current?.resourceRegistry.destroy();
       ctxRef.current?.reality.destroy();
       ctxRef.current = null;
       setIsReady(false);
     }, []);
-    useEffect24(() => {
+    useEffect26(() => {
       return () => {
         creationId.current++;
         cleanupReality();
       };
     }, [cleanupReality]);
-    const createReality = useCallback8(async () => {
+    const createReality = useCallback9(async () => {
       const id = ++creationId.current;
       const resourceRegistry = new ResourceRegistry();
       const attachmentRegistry = new AttachmentRegistry();
@@ -3093,7 +3529,7 @@ var Reality = forwardRef19(
         return null;
       }
     }, [cleanupReality]);
-    const content = useCallback8(() => /* @__PURE__ */ jsx22(Fragment3, {}), []);
+    const content = useCallback9(() => /* @__PURE__ */ jsx22(Fragment3, {}), []);
     useRealityEvents({
       instance: ctxRef.current?.reality ?? null,
       onSpatialTap,
@@ -3122,7 +3558,7 @@ var Reality = forwardRef19(
 );
 
 // src/reality/components/AttachmentAsset.tsx
-import { useEffect as useEffect25, useState as useState9 } from "react";
+import { useEffect as useEffect27, useState as useState9 } from "react";
 import { createPortal as createPortal3 } from "react-dom";
 import { jsx as jsx23 } from "react/jsx-runtime";
 var AttachmentAsset = ({
@@ -3131,7 +3567,7 @@ var AttachmentAsset = ({
 }) => {
   const ctx = useRealityContext();
   const [containers, setContainers] = useState9([]);
-  useEffect25(() => {
+  useEffect27(() => {
     if (!ctx) return;
     return ctx.attachmentRegistry.onContainersChange(name, setContainers);
   }, [ctx, name]);
@@ -3142,7 +3578,7 @@ var AttachmentAsset = ({
 };
 
 // src/reality/components/AttachmentEntity.tsx
-import { useEffect as useEffect26, useRef as useRef15, useState as useState10 } from "react";
+import { useEffect as useEffect28, useRef as useRef17, useState as useState10 } from "react";
 var instanceCounter = 0;
 var AttachmentEntity = ({
   attachment: attachmentName,
@@ -3151,12 +3587,12 @@ var AttachmentEntity = ({
 }) => {
   const ctx = useRealityContext();
   const parent = useParentContext();
-  const attachmentRef = useRef15(null);
-  const parentIdRef = useRef15(null);
-  const instanceIdRef = useRef15(`att_${++instanceCounter}`);
-  const attachmentNameRef = useRef15(attachmentName);
+  const attachmentRef = useRef17(null);
+  const parentIdRef = useRef17(null);
+  const instanceIdRef = useRef17(`att_${++instanceCounter}`);
+  const attachmentNameRef = useRef17(attachmentName);
   const [childWindow, setChildWindow] = useState10(null);
-  useEffect26(() => {
+  useEffect28(() => {
     if (!ctx || !parent) return;
     if (attachmentRef.current) return;
     const parentId = parent.id;
@@ -3218,7 +3654,7 @@ var AttachmentEntity = ({
       }
     };
   }, [ctx, parent]);
-  useEffect26(() => {
+  useEffect28(() => {
     if (!ctx) return;
     const att = attachmentRef.current;
     const prevName = attachmentNameRef.current;
@@ -3235,7 +3671,7 @@ var AttachmentEntity = ({
     }
   }, [ctx, attachmentName]);
   useSyncHeadStyles(childWindow, { subtree: false });
-  useEffect26(() => {
+  useEffect28(() => {
     if (!attachmentRef.current) return;
     attachmentRef.current.update({ position, size });
   }, [position?.[0], position?.[1], position?.[2], size?.width, size?.height]);
@@ -3371,7 +3807,7 @@ async function convertCoordinate(position, { from, to }) {
 }
 
 // src/index.ts
-var version = "1.4.0";
+var version = "1.6.0";
 if (typeof window !== "undefined") {
   initPolyfill();
 }