@webspatial/core-sdk 1.2.1 → 1.4.0

package/dist/index.js

@@ -2,7 +2,7 @@
     (function(){
       if(typeof window === 'undefined') return;
       if(!window.__webspatialsdk__) window.__webspatialsdk__ = {}
-      window.__webspatialsdk__['core-sdk-version'] = "1.2.1"
+      window.__webspatialsdk__['core-sdk-version'] = "1.4.0"
   })()
     
 var __defProp = Object.defineProperty;
@@ -93,6 +93,368 @@ var init_CommandResultUtils = __esm({
   }
 });
 
+// src/platform-adapter/puppeteer/PuppeteerPlatform.ts
+var PuppeteerPlatform_exports = {};
+__export(PuppeteerPlatform_exports, {
+  PuppeteerPlatform: () => PuppeteerPlatform
+});
+var PuppeteerPlatform;
+var init_PuppeteerPlatform = __esm({
+  "src/platform-adapter/puppeteer/PuppeteerPlatform.ts"() {
+    "use strict";
+    init_CommandResultUtils();
+    console.log("PuppeteerPlatform");
+    PuppeteerPlatform = class {
+      // store iframe instance
+      iframeRegistry = /* @__PURE__ */ new Map();
+      constructor() {
+      }
+      callJSB(cmd, msg) {
+        return new Promise((resolve) => {
+          try {
+            if (window.__handleJSBMessage) {
+              try {
+                console.log(` core-sdk Puppeteer Platform: callJSB: ${cmd}::${msg}`);
+                const result = window.__handleJSBMessage(`${cmd}::${msg}`);
+                console.log(
+                  ` core-sdk Puppeteer Platform callJSB result: ${result}`
+                );
+                resolve(CommandResultSuccess(result));
+              } catch (err) {
+                resolve(CommandResultFailure("500", "JSB execution error"));
+              }
+            } else {
+              resolve(CommandResultSuccess("ok"));
+            }
+          } catch (error) {
+            console.error(
+              `PuppeteerPlatform cmd Error: ${cmd}, msg: ${msg} error: ${error}`
+            );
+            resolve(CommandResultFailure("500", "Internal error"));
+          }
+        });
+      }
+      /**
+       * Synchronously create Spatialized2DElement to Puppeteer Runner
+       */
+      createSpatializedElementSync(spatialId, webspatialUrl) {
+        try {
+          console.log(
+            `[Puppeteer Platform] Creating spatialized element sync with id: ${spatialId}, url: ${webspatialUrl}`
+          );
+          const win = window;
+          if (win.__handleJSBMessage) {
+            const createCommand = {
+              id: spatialId,
+              url: webspatialUrl
+            };
+            win.__handleJSBMessage(
+              `CreateSpatialized2DElement::${JSON.stringify(createCommand)}`
+            );
+          }
+        } catch (error) {
+          console.error("Error creating spatialized element sync:", error);
+        }
+      }
+      callWebSpatialProtocol(command, query, target, features) {
+        console.log(
+          `PuppeteerPlatform: Calling webspatial protocol: webspatial://${command}${query ? `?${query}` : ""}`
+        );
+        return new Promise((resolve) => {
+          try {
+            const webspatialUrl = `webspatial://${command}${query ? `?${query}` : ""}`;
+            const { spatialId, iframe, windowProxy } = this.createIframeWindow(
+              webspatialUrl,
+              target,
+              features
+            );
+            if (command === "createSpatialized2DElement") {
+              this.createSpatializedElementSync(spatialId, webspatialUrl);
+            }
+            console.log(
+              `[Puppeteer Platform] iframe created with spatialId: ${spatialId}`
+            );
+            this.iframeRegistry.set(spatialId, iframe);
+            resolve(CommandResultSuccess({ windowProxy, id: spatialId }));
+          } catch (error) {
+            console.error("Error calling webspatial protocol:", error);
+            resolve(
+              CommandResultFailure("500", "Failed to call webspatial protocol")
+            );
+          }
+        });
+      }
+      callWebSpatialProtocolSync(command, query, target, features) {
+        try {
+          const webspatialUrl = `webspatial://${command}${query ? `?${query}` : ""}`;
+          console.log(`Calling webspatial protocol sync: ${webspatialUrl}`);
+          const { spatialId, iframe, windowProxy } = this.createIframeWindow(
+            webspatialUrl,
+            target,
+            features
+          );
+          if (command === "createSpatialized2DElement") {
+            this.createSpatializedElementSync(spatialId, webspatialUrl);
+          }
+          this.iframeRegistry.set(spatialId, iframe);
+          return CommandResultSuccess({ windowProxy, id: spatialId });
+        } catch (error) {
+          console.error("Error calling webspatial protocol sync:", error);
+          return CommandResultFailure(
+            "500",
+            "Failed to call webspatial protocol sync"
+          );
+        }
+      }
+      /**
+       * Synchronously create iframe-based window
+       */
+      createIframeWindow(url, target, features) {
+        const iframe = document.createElement("iframe");
+        iframe.style.border = "none";
+        iframe.style.display = "none";
+        iframe.style.width = "100%";
+        iframe.style.height = "100%";
+        const spatialId = this.generateUUID();
+        iframe.spatialId = spatialId;
+        iframe.id = `spatial-iframe-${spatialId}`;
+        const featuresObj = this.parseFeatures(features || "");
+        if (featuresObj.width) {
+          iframe.style.width = featuresObj.width;
+        }
+        if (featuresObj.height) {
+          iframe.style.height = featuresObj.height;
+        }
+        if (featuresObj.left) {
+          iframe.style.left = featuresObj.left;
+          iframe.style.position = "absolute";
+        }
+        if (featuresObj.top) {
+          iframe.style.top = featuresObj.top;
+          iframe.style.position = "absolute";
+        }
+        document.body.appendChild(iframe);
+        const windowProxy = this.createEnhancedWindowProxy(iframe, url, spatialId);
+        iframe.src = "about:blank";
+        console.log(
+          `PuppeteerPlatform created iframe window with spatialId: ${spatialId}, URL: ${url}`
+        );
+        this.initializeIframeContent(iframe, url, spatialId);
+        return { spatialId, iframe, windowProxy };
+      }
+      /**
+       * create enhanced windowProxy object
+       */
+      createEnhancedWindowProxy(iframe, url, spatialId) {
+        return {
+          // basic properties
+          location: {
+            href: url,
+            toString: () => url,
+            reload: () => {
+              if (iframe.contentWindow) {
+                iframe.contentWindow.location.reload();
+              }
+            }
+          },
+          navigator: {
+            userAgent: `Mozilla/5.0 (WebKit) SpatialId/${spatialId}`
+          },
+          // methods
+          close: () => {
+            console.log(`Closing iframe with spatialId: ${spatialId}`);
+            iframe.remove();
+            this.iframeRegistry.delete(spatialId);
+          },
+          // document access
+          document: iframe.contentDocument || {},
+          contentWindow: iframe.contentWindow || {},
+          // add message communication method
+          postMessage: (message, targetOrigin) => {
+            if (iframe.contentWindow) {
+              iframe.contentWindow.postMessage(message, targetOrigin || "*");
+            }
+          },
+          // add event listener method
+          addEventListener: (type, listener) => {
+            if (iframe.contentWindow) {
+              iframe.contentWindow.addEventListener(type, listener);
+            }
+          },
+          removeEventListener: (type, listener) => {
+            if (iframe.contentWindow) {
+              iframe.contentWindow.removeEventListener(type, listener);
+            }
+          },
+          // execute JavaScript
+          executeScript: (code) => {
+            if (iframe.contentWindow) {
+              try {
+                const win = iframe.contentWindow;
+                return win.eval(code);
+              } catch (error) {
+                console.error(
+                  `Error executing script in iframe ${spatialId}:`,
+                  error
+                );
+                return null;
+              }
+            }
+            return null;
+          },
+          // get iframe reference
+          getIframe: () => iframe,
+          // get spatialId
+          getSpatialId: () => spatialId
+        };
+      }
+      /**
+       * initialize iframe content
+       */
+      initializeIframeContent(iframe, url, spatialId) {
+        try {
+          iframe.onload = () => {
+            try {
+              const iframeContent = `
+            // inject communication script
+            window.webSpatialId = '${spatialId}';
+            window.SpatialId = '${spatialId}';
+            
+            // override window.open to support webspatial protocol
+            const originalOpen = window.open;
+            window.open = function(url, target, features) {
+              if (url && url.startsWith('webspatial://')) {
+                // handle webspatial protocol through windowProxy
+                const windowProxy = new Proxy({}, {
+                  get: function(target, prop) {
+                    if (prop === 'toString') {
+                      return function() { return url; };
+                    }
+                    return undefined;
+                  }
+                });
+                return windowProxy;
+              }
+              return originalOpen.call(window, url, target, features);
+            };
+            
+            // set navigator.userAgent to identify webspatial environment
+            Object.defineProperty(navigator, 'userAgent', {
+              value: 'WebSpatial/1.0 ' + navigator.userAgent,
+              configurable: true
+            });
+            
+            // send loaded message
+            window.parent.postMessage({
+              type: 'iframe_loaded',
+              spatialId: '${spatialId}',
+              url: '${url}'
+            }, '${window.location.origin}');
+            
+            // set message handler
+            window.addEventListener('message', (event) => {
+              if (event.origin !== window.parent.location.origin) return;
+              
+              const data = event.data;
+              if (data && data.type === 'webspatial_command') {
+                // handle command from parent window
+                console.log('Received command in iframe from parent:', data.command);
+                // add command handling logic here
+              }
+            });
+          `;
+              const doc = iframe.contentDocument;
+              if (doc) {
+                doc.open();
+                doc.write(`
+              <!DOCTYPE html>
+              <html>
+              <head>
+                <title>Spatial Iframe - ${spatialId}</title>
+                <meta charset="UTF-8">
+                <style>
+                  body {
+                    margin: 0;
+                    padding: 0;
+                    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                  }
+                </style>
+              </head>
+              <body>
+                <script>${iframeContent}</script>
+              </body>
+              </html>
+            `);
+                doc.close();
+              }
+            } catch (error) {
+              console.error("Error initializing iframe content:", error);
+            }
+          };
+        } catch (error) {
+          console.error("Error setting up iframe:", error);
+        }
+      }
+      /**
+       * parse features string to object
+       */
+      parseFeatures(features) {
+        const result = {};
+        const pairs = features.split(",");
+        pairs.forEach((pair) => {
+          const [key, value] = pair.split("=").map((s) => s.trim());
+          if (key && value) {
+            result[key] = value;
+          }
+        });
+        return result;
+      }
+      /**
+       * send message to iframe with specified spatialId
+       */
+      sendMessageToIframe(spatialId, message) {
+        const iframe = this.iframeRegistry.get(spatialId);
+        if (iframe && iframe.contentWindow) {
+          iframe.contentWindow.postMessage(message, window.location.origin);
+          return true;
+        }
+        return false;
+      }
+      /**
+       * get all active iframes
+       */
+      getAllActiveIframes() {
+        const result = [];
+        this.iframeRegistry.forEach((iframe, spatialId) => {
+          result.push({ spatialId, iframe });
+        });
+        return result;
+      }
+      /**
+       * dispose all active iframes
+       */
+      dispose() {
+        this.iframeRegistry.forEach((iframe, spatialId) => {
+          console.log(`Disposing iframe with spatialId: ${spatialId}`);
+          iframe.remove();
+        });
+        this.iframeRegistry.clear();
+      }
+      // generate UUID function
+      generateUUID() {
+        return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(
+          /[xy]/g,
+          function(c) {
+            const r = Math.random() * 16 | 0;
+            const v = c === "x" ? r : r & 3 | 8;
+            return v.toString(16).toUpperCase();
+          }
+        );
+      }
+    };
+  }
+});
+
 // src/SpatialWebEvent.ts
 var SpatialWebEvent;
 var init_SpatialWebEvent = __esm({
@@ -401,7 +763,10 @@ function createPlatform() {
   }
   const userAgent = window.navigator.userAgent;
   const webSpatialVersion = getWebSpatialVersion(userAgent);
-  if (userAgent.includes("PicoWebApp") && isVersionGreater(webSpatialVersion, [0, 0, 1])) {
+  if (window.navigator.userAgent.includes("Puppeteer")) {
+    const PuppeteerPlatform2 = (init_PuppeteerPlatform(), __toCommonJS(PuppeteerPlatform_exports)).PuppeteerPlatform;
+    return new PuppeteerPlatform2();
+  } else if (userAgent.includes("PicoWebApp") && isVersionGreater(webSpatialVersion, [0, 0, 1])) {
     const XRPlatform2 = (init_XRPlatform(), __toCommonJS(XRPlatform_exports)).XRPlatform;
     return new XRPlatform2();
   } else if (userAgent.includes("Android") || userAgent.includes("Linux")) {
@@ -469,7 +834,7 @@ var init_utils = __esm({
 });
 
 // src/JSBCommand.ts
-var platform, JSBCommand, UpdateEntityPropertiesCommand, UpdateEntityEventCommand, UpdateSpatialSceneProperties, UpdateSceneConfig, FocusScene, GetSpatialSceneState, SpatializedElementCommand, UpdateSpatialized2DElementProperties, UpdateSpatializedDynamic3DElementProperties, UpdateUnlitMaterialProperties, UpdateSpatializedElementTransform, UpdateSpatializedStatic3DElementProperties, AddSpatializedElementToSpatialized2DElement, AddSpatializedElementToSpatialScene, CreateSpatializedStatic3DElementCommand, CreateSpatializedDynamic3DElementCommand, CreateSpatialEntityCommand, CreateModelComponentCommand, CreateSpatialModelEntityCommand, CreateModelAssetCommand, CreateSpatialGeometryCommand, CreateSpatialUnlitMaterialCommand, AddComponentToEntityCommand, SetParentForEntityCommand, ConvertFromEntityToEntityCommand, ConvertFromEntityToSceneCommand, ConvertFromSceneToEntityCommand, InspectCommand, DestroyCommand, CheckWebViewCanCreateCommand, WebSpatialProtocolCommand, createSpatialized2DElementCommand, createSpatialSceneCommand;
+var platform, JSBCommand, UpdateEntityPropertiesCommand, UpdateEntityEventCommand, UpdateSpatialSceneProperties, UpdateSceneConfig, FocusScene, GetSpatialSceneState, SpatializedElementCommand, UpdateSpatialized2DElementProperties, UpdateSpatializedDynamic3DElementProperties, UpdateUnlitMaterialProperties, UpdateSpatializedElementTransform, UpdateSpatializedStatic3DElementProperties, AddSpatializedElementToSpatialized2DElement, AddSpatializedElementToSpatialScene, CreateSpatializedStatic3DElementCommand, CreateSpatializedDynamic3DElementCommand, CreateSpatialEntityCommand, CreateModelComponentCommand, CreateSpatialModelEntityCommand, CreateModelAssetCommand, CreateSpatialGeometryCommand, CreateSpatialUnlitMaterialCommand, AddComponentToEntityCommand, SetParentForEntityCommand, ConvertFromEntityToEntityCommand, ConvertFromEntityToSceneCommand, ConvertFromSceneToEntityCommand, ConvertCoordinateCommand, InspectCommand, DestroyCommand, CheckWebViewCanCreateCommand, WebSpatialProtocolCommand, createSpatialized2DElementCommand, createSpatialSceneCommand, CreateAttachmentEntityCommand, InitializeAttachmentCommand, UpdateAttachmentEntityCommand;
 var init_JSBCommand = __esm({
   "src/JSBCommand.ts"() {
     "use strict";
@@ -807,6 +1172,22 @@ var init_JSBCommand = __esm({
       }
       commandType = "ConvertFromSceneToEntity";
     };
+    ConvertCoordinateCommand = class extends JSBCommand {
+      constructor(position, fromId, toId) {
+        super();
+        this.position = position;
+        this.fromId = fromId;
+        this.toId = toId;
+      }
+      getParams() {
+        return {
+          position: this.position,
+          fromId: this.fromId,
+          toId: this.toId
+        };
+      }
+      commandType = "ConvertCoordinate";
+    };
     InspectCommand = class extends JSBCommand {
       constructor(id = "") {
         super();
@@ -896,6 +1277,47 @@ var init_JSBCommand = __esm({
         };
       }
     };
+    CreateAttachmentEntityCommand = class extends WebSpatialProtocolCommand {
+      constructor(options) {
+        super();
+        this.options = options;
+      }
+      commandType = "createAttachment";
+      getParams() {
+        return {};
+      }
+    };
+    InitializeAttachmentCommand = class extends JSBCommand {
+      constructor(attachmentId, options) {
+        super();
+        this.attachmentId = attachmentId;
+        this.options = options;
+      }
+      commandType = "InitializeAttachment";
+      getParams() {
+        return {
+          id: this.attachmentId,
+          parentEntityId: this.options.parentEntityId,
+          position: this.options.position ?? [0, 0, 0],
+          size: this.options.size,
+          ownerViewId: this.options.ownerViewId
+        };
+      }
+    };
+    UpdateAttachmentEntityCommand = class extends JSBCommand {
+      constructor(attachmentId, options) {
+        super();
+        this.attachmentId = attachmentId;
+        this.options = options;
+      }
+      commandType = "UpdateAttachmentEntity";
+      getParams() {
+        return {
+          id: this.attachmentId,
+          ...this.options
+        };
+      }
+    };
   }
 });
 
@@ -939,6 +1361,7 @@ init_JSBCommand();
 
 // src/SpatialScene.ts
 init_JSBCommand();
+init_JSBCommand();
 var instance;
 var SpatialScene = class _SpatialScene extends SpatialObject {
   /**
@@ -952,6 +1375,19 @@ var SpatialScene = class _SpatialScene extends SpatialObject {
     }
     return instance;
   }
+  async convertCoordinate(position, fromId, toId) {
+    try {
+      const ret = await new ConvertCoordinateCommand(
+        position,
+        fromId,
+        toId
+      ).execute();
+      return ret?.data ?? position;
+    } catch (error) {
+      console.warn("SpatialScene.convertCoordinate error:", error);
+      throw error;
+    }
+  }
   /**
    * Updates the properties of the spatial scene.
    * This can include background settings, lighting, and other scene-wide properties.
@@ -1451,29 +1887,6 @@ var SpatializedElement = class extends SpatialObject {
     const { type } = data;
     if (type === "objectdestroy" /* objectdestroy */) {
       this.isDestroyed = true;
-    } else if (type === "cubeInfo" /* cubeInfo */) {
-      const cubeInfoMsg = data;
-      this._cubeInfo = new CubeInfo(cubeInfoMsg.size, cubeInfoMsg.origin);
-    } else if (type === "transform" /* transform */) {
-      this._transform = new DOMMatrix([
-        data.detail.column0[0],
-        data.detail.column0[1],
-        data.detail.column0[2],
-        0,
-        data.detail.column1[0],
-        data.detail.column1[1],
-        data.detail.column1[2],
-        0,
-        data.detail.column2[0],
-        data.detail.column2[1],
-        data.detail.column2[2],
-        0,
-        data.detail.column3[0],
-        data.detail.column3[1],
-        data.detail.column3[2],
-        1
-      ]);
-      this._transformInv = this._transform.inverse();
     } else if (type === "spatialtap" /* spatialtap */) {
       const event = createSpatialEvent(
         "spatialtap" /* spatialtap */,
@@ -1627,6 +2040,16 @@ var Spatialized2DElement = class extends SpatializedElement {
 // src/SpatializedStatic3DElement.ts
 init_JSBCommand();
 var SpatializedStatic3DElement = class extends SpatializedElement {
+  /**
+   * Creates a new spatialized static 3D element with the specified ID and URL.
+   * Registers the element to receive spatial events.
+   * @param id Unique identifier for this element
+   * @param modelURL URL of the 3D model
+   */
+  constructor(id, modelURL) {
+    super(id);
+    this.modelURL = modelURL;
+  }
   /**
    * Promise resolver for the ready state.
    * Used to resolve the ready promise when the model is loaded.
@@ -1636,12 +2059,13 @@ var SpatializedStatic3DElement = class extends SpatializedElement {
    * Caches the last model URL to detect changes.
    * Used to reset the ready promise when the model URL changes.
    */
-  modelURL = "";
+  modelURL;
   /**
    * Creates a new promise for tracking the ready state of the model.
    * @returns Promise that resolves when the model is loaded (true) or fails to load (false)
    */
   createReadyPromise() {
+    this._readyResolve?.(false);
     return new Promise((resolve) => {
       this._readyResolve = resolve;
     });
@@ -1717,6 +2141,7 @@ var SpatializedStatic3DElement = class extends SpatializedElement {
 init_JSBCommand();
 var SpatializedDynamic3DElement = class extends SpatializedElement {
   children = [];
+  events = {};
   constructor(id) {
     super(id);
   }
@@ -1726,6 +2151,17 @@ var SpatializedDynamic3DElement = class extends SpatializedElement {
     entity.parent = this;
     return ans;
   }
+  addEvent(type, callback) {
+    this.events[type] = callback;
+  }
+  removeEvent(eventName) {
+    if (this.events[eventName]) {
+      delete this.events[eventName];
+    }
+  }
+  dispatchEvent(evt) {
+    this.events[evt.type]?.(evt);
+  }
   async updateProperties(properties) {
     return new UpdateSpatializedDynamic3DElementProperties(
       this,
@@ -1754,7 +2190,7 @@ async function createSpatializedStatic3DElement(modelURL) {
     throw new Error("createSpatializedStatic3DElement failed");
   } else {
     const { id } = result.data;
-    return new SpatializedStatic3DElement(id);
+    return new SpatializedStatic3DElement(id, modelURL);
   }
 }
 async function createSpatializedDynamic3DElement() {
@@ -1767,6 +2203,37 @@ async function createSpatializedDynamic3DElement() {
   }
 }
 
+// src/reality/Attachment.ts
+init_JSBCommand();
+var Attachment = class extends SpatialObject {
+  constructor(id, windowProxy, options) {
+    super(id);
+    this.windowProxy = windowProxy;
+    this.options = options;
+  }
+  getContainer() {
+    return this.windowProxy.document.body;
+  }
+  getWindowProxy() {
+    return this.windowProxy;
+  }
+  async update(options) {
+    if (this.isDestroyed) return;
+    if (options.position) this.options.position = options.position;
+    if (options.size) this.options.size = options.size;
+    return new UpdateAttachmentEntityCommand(this.id, options).execute();
+  }
+};
+async function createAttachmentEntity(options) {
+  const result = await new CreateAttachmentEntityCommand(options).execute();
+  if (!result.success) {
+    throw new Error("createAttachmentEntity failed: " + result?.errorMessage);
+  }
+  const { id, windowProxy } = result.data;
+  await new InitializeAttachmentCommand(id, options).execute();
+  return new Attachment(id, windowProxy, options);
+}
+
 // src/reality/realityCreator.ts
 init_JSBCommand();
 
@@ -1774,7 +2241,7 @@ init_JSBCommand();
 init_JSBCommand();
 init_JSBCommand();
 init_SpatialWebEvent();
-var SpatialEntity = class _SpatialEntity extends SpatialObject {
+var SpatialEntity = class extends SpatialObject {
   constructor(id, userData) {
     super(id);
     this.userData = userData;
@@ -1786,6 +2253,20 @@ var SpatialEntity = class _SpatialEntity extends SpatialObject {
   events = {};
   children = [];
   parent = null;
+  _enableInput = false;
+  get enableInput() {
+    return this._enableInput;
+  }
+  set enableInput(value) {
+    if (this._enableInput === value) return;
+    this._enableInput = value;
+    void this.updateEntityEvent("spatialtap", value).catch((err) => {
+      console.error("enableInput updateEntityEvent failed", "spatialtap", err);
+      if (this._enableInput === value) {
+        this._enableInput = !value;
+      }
+    });
+  }
   async addComponent(component) {
     return new AddComponentToEntityCommand(this, component).execute();
   }
@@ -1853,10 +2334,7 @@ var SpatialEntity = class _SpatialEntity extends SpatialObject {
     if (type === "objectdestroy" /* objectdestroy */) {
       this.isDestroyed = true;
     } else if (type === "spatialtap" /* spatialtap */) {
-      const evt = createSpatialEvent(
-        "spatialtap" /* spatialtap */,
-        data.detail
-      );
+      const evt = createSpatialEvent("spatialtap" /* spatialtap */, data.detail);
       this.dispatchEvent(evt);
     } else if (type === "spatialdragstart" /* spatialdragstart */) {
       const evt = createSpatialEvent(
@@ -1865,10 +2343,7 @@ var SpatialEntity = class _SpatialEntity extends SpatialObject {
       );
       this.dispatchEvent(evt);
     } else if (type === "spatialdrag" /* spatialdrag */) {
-      const evt = createSpatialEvent(
-        "spatialdrag" /* spatialdrag */,
-        data.detail
-      );
+      const evt = createSpatialEvent("spatialdrag" /* spatialdrag */, data.detail);
       this.dispatchEvent(evt);
     } else if (type === "spatialdragend" /* spatialdragend */) {
       const evt = createSpatialEvent(
@@ -1908,7 +2383,7 @@ var SpatialEntity = class _SpatialEntity extends SpatialObject {
     }
     this.events[evt.type]?.(evt);
     if (evt.bubbles && !evt.cancelBubble) {
-      if (this.parent && this.parent instanceof _SpatialEntity) {
+      if (this.parent) {
         this.parent.dispatchEvent(evt);
       }
     }
@@ -2156,7 +2631,7 @@ var SpatialSession = class {
    * @param modelURL Optional URL to the 3D model to load
    * @returns Promise resolving to a new SpatializedStatic3DElement instance
    */
-  createSpatializedStatic3DElement(modelURL = "") {
+  createSpatializedStatic3DElement(modelURL) {
     return createSpatializedStatic3DElement(modelURL);
   }
   /**
@@ -2257,11 +2732,21 @@ var SpatialSession = class {
   createSpatialModelEntity(options, userData) {
     return createSpatialModelEntity(options, userData);
   }
+  /**
+   * Creates an attachment entity that renders 2D HTML content as a child
+   * of a 3D entity in the scene graph.
+   * @param options Configuration options including parent entity ID, position, and size
+   * @returns Promise resolving to a new Attachment instance
+   */
+  createAttachmentEntity(options) {
+    return createAttachmentEntity(options);
+  }
 };
 
 // src/Spatial.ts
 init_SpatialWebEvent();
 var Spatial = class {
+  wsAppShellVersionFromUA;
   /**
    * Requests a spatial session object from the browser.
    * This is the primary method to initialize spatial functionality.
@@ -2287,6 +2772,20 @@ var Spatial = class {
     }
     return false;
   }
+  getShellVersionFromUA() {
+    if (this.wsAppShellVersionFromUA !== void 0) {
+      return this.wsAppShellVersionFromUA;
+    }
+    if (typeof navigator === "undefined" || typeof navigator.userAgent !== "string") {
+      this.wsAppShellVersionFromUA = null;
+      return null;
+    }
+    const match = navigator.userAgent.match(
+      /WSAppShell\/(\d+(?:\.\d+){2}(?:[-+][0-9A-Za-z.-]+)*)/
+    );
+    this.wsAppShellVersionFromUA = match ? match[1] : "1.3.0";
+    return this.wsAppShellVersionFromUA;
+  }
   /** @deprecated
    * Checks if WebSpatial is supported in the current environment.
    * Verifies compatibility between native and client versions.
@@ -2304,7 +2803,7 @@ var Spatial = class {
     if (window.__WebSpatialData && window.__WebSpatialData.getNativeVersion) {
       return window.__WebSpatialData.getNativeVersion();
     }
-    return window.WebSpatailNativeVersion === "PACKAGE_VERSION" ? this.getClientVersion() : window.WebSpatailNativeVersion;
+    return window.WebSpatailNativeVersion === "WS_SHELL_VERSION" ? this.getClientVersion() : window.WebSpatailNativeVersion;
   }
   /** @deprecated
    * Gets the client SDK version.
@@ -2312,10 +2811,70 @@ var Spatial = class {
    * @returns Client SDK version string in format "x.x.x"
    */
   getClientVersion() {
-    return "1.2.1";
+    return "1.4.0";
   }
 };
 
+// src/physicalMetrics.ts
+var physicalMetrics_exports = {};
+__export(physicalMetrics_exports, {
+  getValue: () => getValue,
+  physicalToPoint: () => physicalToPoint,
+  pointToPhysical: () => pointToPhysical,
+  subscribe: () => subscribe
+});
+init_SpatialWebEvent();
+var snapshot = {
+  meterToPtUnscaled: 1360,
+  meterToPtScaled: 1360
+};
+function getWorldScalingCompensation(options) {
+  return options?.worldScalingCompensation ?? "scaled";
+}
+function pointToPhysical(point, options) {
+  updateValue();
+  const compensation = getWorldScalingCompensation(options);
+  if (compensation === "unscaled") {
+    return point / snapshot.meterToPtUnscaled;
+  }
+  return point / snapshot.meterToPtScaled;
+}
+function physicalToPoint(physical, options) {
+  updateValue();
+  const compensation = getWorldScalingCompensation(options);
+  if (compensation === "unscaled") {
+    return physical * snapshot.meterToPtUnscaled;
+  }
+  return physical * snapshot.meterToPtScaled;
+}
+function updateValue() {
+  if (typeof window === "undefined") return;
+  const src = window.__webspatialsdk__?.physicalMetrics;
+  if (!src) return;
+  const next = {
+    meterToPtScaled: src.meterToPtScaled ?? snapshot.meterToPtScaled,
+    meterToPtUnscaled: src.meterToPtUnscaled ?? snapshot.meterToPtUnscaled
+  };
+  if (next.meterToPtScaled !== snapshot.meterToPtScaled || next.meterToPtUnscaled !== snapshot.meterToPtUnscaled) {
+    snapshot = next;
+  }
+}
+function getValue() {
+  updateValue();
+  return snapshot;
+}
+function subscribe(cb) {
+  if (typeof window === "undefined") return () => {
+  };
+  const handler = () => {
+    cb();
+  };
+  SpatialWebEvent.addEventReceiver("window", handler);
+  return () => {
+    SpatialWebEvent.removeEventReceiver("window");
+  };
+}
+
 // src/index.ts
 init_ssr_polyfill();
 
@@ -2463,9 +3022,11 @@ if (!isSSREnv() && navigator.userAgent.indexOf("WebSpatial/") > 0) {
   spatialWindowPolyfill();
 }
 export {
+  Attachment,
   BaseplateVisibilityValues,
   CubeInfo,
   ModelComponent,
+  physicalMetrics_exports as PhysicalMetrics,
   Spatial,
   SpatialBoxGeometry,
   SpatialComponent,
@@ -2491,6 +3052,7 @@ export {
   SpatializedStatic3DElement,
   WorldAlignmentValues,
   WorldScalingValues,
+  createAttachmentEntity,
   isSSREnv,
   isValidBaseplateVisibilityType,
   isValidSceneUnit,