@webspatial/core-sdk 1.3.0 → 1.4.0

package/src/platform-adapter/puppeteer/PuppeteerPlatform.ts

@@ -4,7 +4,7 @@ import {
   CommandResultSuccess,
 } from '../CommandResultUtils'
 
-// 添加window扩展接口
+// add window interface for JSB call
 declare global {
   interface Window {
     __handleJSBMessage: (message: string) => any
@@ -24,7 +24,7 @@ type JSBError = {
 console.log('PuppeteerPlatform')
 
 export class PuppeteerPlatform implements PlatformAbility {
-  // 存储iframe实例
+  // store iframe instance
   private iframeRegistry: Map<string, HTMLIFrameElement> = new Map()
 
   constructor() {}
@@ -32,7 +32,7 @@ export class PuppeteerPlatform implements PlatformAbility {
   callJSB(cmd: string, msg: string): Promise<CommandResult> {
     return new Promise(resolve => {
       try {
-        // 检查__handleJSBMessage是否存在
+        // check __handleJSBMessage exist
         if (window.__handleJSBMessage) {
           try {
             console.log(` core-sdk Puppeteer Platform: callJSB: ${cmd}::${msg}`)
@@ -45,7 +45,7 @@ export class PuppeteerPlatform implements PlatformAbility {
             resolve(CommandResultFailure('500', 'JSB execution error'))
           }
         } else {
-          // 如果不存在，返回默认结果
+          // if not exist, return default result
           resolve(CommandResultSuccess('ok'))
         }
       } catch (error: unknown) {
@@ -58,7 +58,7 @@ export class PuppeteerPlatform implements PlatformAbility {
   }
 
   /**
-   * 同步创建Spatialized2DElement到Puppeteer Runner
+   * Synchronously create Spatialized2DElement to Puppeteer Runner
    */
   private createSpatializedElementSync(
     spatialId: string,
@@ -68,10 +68,10 @@ export class PuppeteerPlatform implements PlatformAbility {
       console.log(
         `[Puppeteer Platform] Creating spatialized element sync with id: ${spatialId}, url: ${webspatialUrl}`,
       )
-      // 直接调用Puppeteer Runner的方法来创建元素
+      // directly call Puppeteer Runner method to create element
       const win = window as any
       if (win.__handleJSBMessage) {
-        // 使用更简洁的格式，确保JSBManager能正确使用我们传递的spatialId
+        // use simpler format to ensure JSBManager can correctly use our passed spatialId
         const createCommand = {
           id: spatialId,
           url: webspatialUrl,
@@ -96,9 +96,9 @@ export class PuppeteerPlatform implements PlatformAbility {
     )
     return new Promise(resolve => {
       try {
-        // 创建完整的webspatial URL
+        // create complete webspatial URL
         const webspatialUrl = `webspatial://${command}${query ? `?${query}` : ''}`
-        // 使用iframe创建新窗口
+        // use iframe to create new window
         const { spatialId, iframe, windowProxy } = this.createIframeWindow(
           webspatialUrl,
           target,
@@ -112,7 +112,7 @@ export class PuppeteerPlatform implements PlatformAbility {
         console.log(
           `[Puppeteer Platform] iframe created with spatialId: ${spatialId}`,
         )
-        // 注册iframe
+        // store iframe instance
         this.iframeRegistry.set(spatialId, iframe)
         resolve(CommandResultSuccess({ windowProxy, id: spatialId }))
       } catch (error) {
@@ -131,7 +131,7 @@ export class PuppeteerPlatform implements PlatformAbility {
     features?: string,
   ): CommandResult {
     try {
-      // 创建完整的webspatial URL
+      // create complete webspatial URL
       const webspatialUrl = `webspatial://${command}${query ? `?${query}` : ''}`
       console.log(`Calling webspatial protocol sync: ${webspatialUrl}`)
 
@@ -147,7 +147,7 @@ export class PuppeteerPlatform implements PlatformAbility {
         this.createSpatializedElementSync(spatialId, webspatialUrl)
       }
 
-      // 注册iframe
+      // store iframe instance
       this.iframeRegistry.set(spatialId, iframe)
 
       return CommandResultSuccess({ windowProxy, id: spatialId })
@@ -161,27 +161,27 @@ export class PuppeteerPlatform implements PlatformAbility {
   }
 
   /**
-   * 创建基于iframe的窗口
+   * Synchronously create iframe-based window
    */
   private createIframeWindow(url: string, target?: string, features?: string) {
-    // 创建iframe元素
+    // create iframe element
     const iframe = document.createElement('iframe')
 
-    // 设置iframe属性
+    // set iframe attributes
     iframe.style.border = 'none'
-    iframe.style.display = 'none' // 初始隐藏
+    iframe.style.display = 'none'
     iframe.style.width = '100%'
     iframe.style.height = '100%'
 
-    // 生成唯一的spatialId
+    // set iframe id
     const spatialId = this.generateUUID()
     iframe.spatialId = spatialId
     iframe.id = `spatial-iframe-${spatialId}`
 
-    // 解析features参数
+    // parse features parameter
     const featuresObj = this.parseFeatures(features || '')
 
-    // 根据features设置iframe样式
+    // set iframe styles based on features
     if (featuresObj.width) {
       iframe.style.width = featuresObj.width
     }
@@ -197,36 +197,36 @@ export class PuppeteerPlatform implements PlatformAbility {
       iframe.style.position = 'absolute'
     }
 
-    // 添加iframe到DOM
+    // add iframe to DOM
     document.body.appendChild(iframe)
 
-    // 创建增强的windowProxy模拟对象
+    // create enhanced windowProxy object
     const windowProxy = this.createEnhancedWindowProxy(iframe, url, spatialId)
 
-    // 设置iframe的src
+    // set iframe src
     iframe.src = 'about:blank'
 
     console.log(
       `PuppeteerPlatform created iframe window with spatialId: ${spatialId}, URL: ${url}`,
     )
 
-    // 初始化iframe内容
+    // initialize iframe content
     this.initializeIframeContent(iframe, url, spatialId)
 
     return { spatialId, iframe, windowProxy }
   }
 
   /**
-   * 创建增强的windowProxy对象
+   * create enhanced windowProxy object
    */
   private createEnhancedWindowProxy(
     iframe: HTMLIFrameElement,
     url: string,
     spatialId: string,
   ) {
-    // 创建增强的windowProxy模拟对象
+    // create enhanced windowProxy object
     return {
-      // 基本属性
+      // basic properties
       location: {
         href: url,
         toString: () => url,
@@ -240,25 +240,25 @@ export class PuppeteerPlatform implements PlatformAbility {
         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 || ({} as Document),
       contentWindow: iframe.contentWindow || ({} as Window),
 
-      // 添加消息通信方法
+      // add message communication method
       postMessage: (message: any, targetOrigin?: string) => {
         if (iframe.contentWindow) {
           iframe.contentWindow.postMessage(message, targetOrigin || '*')
         }
       },
 
-      // 添加事件监听方法
+      // add event listener method
       addEventListener: (
         type: string,
         listener: EventListenerOrEventListenerObject,
@@ -277,11 +277,11 @@ export class PuppeteerPlatform implements PlatformAbility {
         }
       },
 
-      // 执行JavaScript
+      // execute JavaScript
       executeScript: (code: string): any => {
         if (iframe.contentWindow) {
           try {
-            // 使用类型断言和更安全的方式执行脚本
+            // use type assertion and safer way to execute script
             const win = iframe.contentWindow as any
             return win.eval(code)
           } catch (error) {
@@ -295,16 +295,16 @@ export class PuppeteerPlatform implements PlatformAbility {
         return null
       },
 
-      // 获取iframe引用
+      // get iframe reference
       getIframe: () => iframe,
 
-      // 获取spatialId
+      // get spatialId
       getSpatialId: () => spatialId,
     }
   }
 
   /**
-   * 初始化iframe内容
+   * initialize iframe content
    */
   private initializeIframeContent(
     iframe: HTMLIFrameElement,
@@ -312,20 +312,20 @@ export class PuppeteerPlatform implements PlatformAbility {
     spatialId: string,
   ): void {
     try {
-      // 等待iframe加载完成
+      // wait for iframe to load
       iframe.onload = () => {
         try {
-          // 设置iframe内容
+          // set iframe content
           const iframeContent = `
-            // 注入通信脚本
+            // inject communication script
             window.webSpatialId = '${spatialId}';
             window.SpatialId = '${spatialId}';
             
-            // 重写window.open以支持webspatial协议
+            // override window.open to support webspatial protocol
             const originalOpen = window.open;
             window.open = function(url, target, features) {
               if (url && url.startsWith('webspatial://')) {
-                // 通过windowProxy处理webspatial协议
+                // handle webspatial protocol through windowProxy
                 const windowProxy = new Proxy({}, {
                   get: function(target, prop) {
                     if (prop === 'toString') {
@@ -339,33 +339,33 @@ export class PuppeteerPlatform implements PlatformAbility {
               return originalOpen.call(window, url, target, features);
             };
             
-            // 设置navigator.userAgent以识别webspatial环境
+            // 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
               }
             });
           `
 
-          // 使用document.write代替eval，更安全且符合类型定义
+          // use document.write instead of eval for security and type compliance
           const doc = iframe.contentDocument
           if (doc) {
             doc.open()
@@ -400,7 +400,7 @@ export class PuppeteerPlatform implements PlatformAbility {
   }
 
   /**
-   * 解析features字符串为对象
+   * parse features string to object
    */
   private parseFeatures(features: string): Record<string, string> {
     const result: Record<string, string> = {}
@@ -417,7 +417,7 @@ export class PuppeteerPlatform implements PlatformAbility {
   }
 
   /**
-   * 发送消息到指定spatialId的iframe
+   * send message to iframe with specified spatialId
    */
   public sendMessageToIframe(spatialId: string, message: any): boolean {
     const iframe = this.iframeRegistry.get(spatialId)
@@ -429,7 +429,7 @@ export class PuppeteerPlatform implements PlatformAbility {
   }
 
   /**
-   * 获取所有活跃的iframe
+   * get all active iframes
    */
   public getAllActiveIframes(): Array<{
     spatialId: string
@@ -445,10 +445,10 @@ export class PuppeteerPlatform implements PlatformAbility {
   }
 
   /**
-   * 清理资源
+   * dispose all active iframes
    */
   public dispose(): void {
-    // 关闭所有iframe
+    // close all iframes
     this.iframeRegistry.forEach((iframe, spatialId) => {
       console.log(`Disposing iframe with spatialId: ${spatialId}`)
       iframe.remove()
@@ -456,7 +456,7 @@ export class PuppeteerPlatform implements PlatformAbility {
     this.iframeRegistry.clear()
   }
 
-  // 生成UUID函数
+  // generate UUID function
   private generateUUID(): string {
     return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(
       /[xy]/g,

package/src/reality/Attachment.ts

@@ -2,6 +2,7 @@ import { SpatialObject } from '../SpatialObject'
 import {
   CreateAttachmentEntityCommand,
   UpdateAttachmentEntityCommand,
+  InitializeAttachmentCommand,
 } from '../JSBCommand'
 import {
   AttachmentEntityOptions,
@@ -41,5 +42,6 @@ export async function createAttachmentEntity(
     throw new Error('createAttachmentEntity failed: ' + result?.errorMessage)
   }
   const { id, windowProxy } = result.data!
+  await new InitializeAttachmentCommand(id, options).execute()
   return new Attachment(id, windowProxy, options)
 }

package/src/reality/entity/SpatialEntity.ts

@@ -23,16 +23,16 @@ import { SpatialComponent } from '../component/SpatialComponent'
 import { SpatialWebEvent } from '../../SpatialWebEvent'
 import { createSpatialEvent } from '../../SpatialWebEventCreator'
 import {
-  CubeInfoMsg,
   ObjectDestroyMsg,
   SpatialDragEndMsg,
   SpatialDragMsg,
+  SpatialDragStartMsg,
+  SpatialMagnifyEndMsg,
   SpatialMagnifyMsg,
   SpatialRotateEndMsg,
   SpatialRotateMsg,
   SpatialTapMsg,
   SpatialWebMsgType,
-  TransformMsg,
 } from '../../WebMsgCommand'
 
 export class SpatialEntity extends SpatialObject {
@@ -43,6 +43,31 @@ export class SpatialEntity extends SpatialObject {
   events: Record<string, (data: any) => void> = {}
   children: SpatialEntity[] = []
   parent: SpatialEntityOrReality | null = null
+  private _enableInput: boolean = false
+
+  get enableInput(): boolean {
+    return this._enableInput
+  }
+
+  set enableInput(value: boolean) {
+    // Why enabling only 'spatialtap' makes the entity interactive:
+    // - On the native (Swift/RealityKit) side, SpatialEntity.updateGesture(type, isEnable)
+    //   toggles per-gesture flags. Then enableInteractive = enableTap || enableRotate || enableDrag || enableMagnify.
+    // - As soon as any gesture (e.g., 'spatialtap') is enabled, enableInteractive becomes true and
+    //   InputTargetComponent is attached, making the entity targetable by targetedToAnyEntity().
+    // - The view layer forwards hit gestures to the web, so enabling 'spatialtap' is sufficient to
+    //   make the entity targetable; enable additional gestures only when needed.
+    if (this._enableInput === value) return
+    this._enableInput = value
+    void this.updateEntityEvent('spatialtap', value).catch(err => {
+      console.error('enableInput updateEntityEvent failed', 'spatialtap', err)
+      // Roll back local flag if the native toggle fails to keep web/native states consistent.
+      // Otherwise, the web side would think the entity is interactive while RealityKit is not.
+      if (this._enableInput === value) {
+        this._enableInput = !value
+      }
+    })
+  }
   constructor(
     id: string,
     public userData?: SpatialEntityUserData,
@@ -123,13 +148,15 @@ export class SpatialEntity extends SpatialObject {
     return new UpdateEntityEventCommand(this, eventName, isEnable).execute()
   }
   private onReceiveEvent = (
-    data: // | CubeInfoMsg
-    // | TransformMsg
-    | SpatialTapMsg
-      // | SpatialDragMsg
-      // | SpatialDragEndMsg
-      // | SpatialRotateMsg
-      // | SpatialRotateEndMsg
+    data:
+      | SpatialTapMsg
+      | SpatialDragStartMsg
+      | SpatialDragMsg
+      | SpatialDragEndMsg
+      | SpatialMagnifyMsg
+      | SpatialMagnifyEndMsg
+      | SpatialRotateMsg
+      | SpatialRotateEndMsg
       | ObjectDestroyMsg,
   ) => {
     // console.log('SpatialEntityEvent', data)
@@ -139,27 +166,21 @@ export class SpatialEntity extends SpatialObject {
     }
     // tap
     else if (type === SpatialWebMsgType.spatialtap) {
-      const evt = createSpatialEvent(
-        SpatialWebMsgType.spatialtap,
-        (data as SpatialTapMsg).detail,
-      )
+      const evt = createSpatialEvent(SpatialWebMsgType.spatialtap, data.detail)
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialdragstart) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialdragstart,
-        (data as SpatialDragMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialdrag) {
-      const evt = createSpatialEvent(
-        SpatialWebMsgType.spatialdrag,
-        (data as SpatialDragMsg).detail,
-      )
+      const evt = createSpatialEvent(SpatialWebMsgType.spatialdrag, data.detail)
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialdragend) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialdragend,
-        (data as SpatialDragEndMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     }
@@ -167,13 +188,13 @@ export class SpatialEntity extends SpatialObject {
     else if (type === SpatialWebMsgType.spatialrotate) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialrotate,
-        (data as SpatialRotateMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialrotateend) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialrotateend,
-        (data as SpatialRotateEndMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     }
@@ -181,13 +202,13 @@ export class SpatialEntity extends SpatialObject {
     else if (type === SpatialWebMsgType.spatialmagnify) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialmagnify,
-        (data as SpatialMagnifyMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialmagnifyend) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialmagnifyend,
-        (data as SpatialMagnifyMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     }
@@ -200,7 +221,7 @@ export 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)
       }
     }

package/src/types/global.d.ts

@@ -1,3 +1,5 @@
+import type { PhysicalMetricsValueShape } from '../physicalMetrics'
+
 declare global {
   declare const __WEBSPATIAL_CORE_SDK_VERSION__: string
 
@@ -28,16 +30,16 @@ declare global {
       'natvie-version'?: string
       'react-sdk-version'?: string
       'core-sdk-version'?: string
+      physicalMetrics?: PhysicalMetricsValueShape
     }
 
-    innerDepth: number
-    outerDepth: number
+    xrInnerDepth: number
+    xrOuterDepth: number
   }
 
   interface HTMLElement {
-    offsetBack: number
-    clientDepth: number
-    getBoundingClientCube: () => CubeInfo | undefined
+    xrOffsetBack: number
+    xrClientDepth: number
   }
 }
 

package/src/types/types.ts

@@ -80,6 +80,11 @@ export interface SpatializedElementProperties {
   enableRotateEndGesture: boolean
   enableMagnifyGesture: boolean
   enableMagnifyEndGesture: boolean
+  /**
+   * Optional world-space axis for spatial rotate gesture. Omitted or zero vector
+   * means unconstrained rotation (platform default).
+   */
+  rotateConstrainedToAxis?: Vec3
 }
 
 export interface Spatialized2DElementProperties
@@ -115,6 +120,16 @@ export interface SpatialSceneCreationOptions {
   baseplateVisibility?: BaseplateVisibilityType
 }
 
+export type SpatialEntityEventType =
+  | 'spatialtap'
+  | 'spatialdragstart'
+  | 'spatialdrag'
+  | 'spatialdragend'
+  | 'spatialrotate'
+  | 'spatialrotateend'
+  | 'spatialmagnify'
+  | 'spatialmagnifyend'
+
 export const BaseplateVisibilityValues = [
   'automatic',
   'visible',
@@ -186,8 +201,6 @@ export interface SpatialEntityProperties {
   scale: Vec3
 }
 
-export type SpatialEntityEventType = 'spatialtap' //| 'drag' | 'rotate' | 'scale'
-
 export type SpatialGeometryType =
   | 'BoxGeometry'
   | 'PlaneGeometry'
@@ -391,6 +404,7 @@ export interface AttachmentEntityOptions {
   parentEntityId: string
   position?: [number, number, number]
   size: { width: number; height: number }
+  ownerViewId: string
 }
 
 export interface AttachmentEntityUpdateOptions {