@webspatial/core-sdk 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webspatial/core-sdk",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "this is the core js API for webspatial",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/JSBCommand.ts

@@ -21,6 +21,8 @@ import {
   SpatialModelEntityCreationOptions,
   SpatialEntityEventType,
   Vec3,
+  AttachmentEntityOptions,
+  AttachmentEntityUpdateOptions,
 } from './types/types'
 import { SpatialSceneCreationOptionsInternal } from './types/internal'
 import { composeSRT } from './utils'
@@ -620,6 +622,36 @@ export class createSpatialSceneCommand extends WebSpatialProtocolCommand {
   }
 }
 
+export class CreateAttachmentEntityCommand extends WebSpatialProtocolCommand {
+  commandType = 'createAttachment'
+  constructor(private options: AttachmentEntityOptions) {
+    super()
+  }
+  protected getParams() {
+    return {
+      parentEntityId: this.options.parentEntityId,
+      position: this.options.position ?? [0, 0, 0],
+      size: this.options.size,
+    }
+  }
+}
+
+export class UpdateAttachmentEntityCommand extends JSBCommand {
+  commandType = 'UpdateAttachmentEntity'
+  constructor(
+    private attachmentId: string,
+    private options: AttachmentEntityUpdateOptions,
+  ) {
+    super()
+  }
+  protected getParams() {
+    return {
+      id: this.attachmentId,
+      ...this.options,
+    }
+  }
+}
+
 // TODO: Can crypto.randomUUID be used instead including in dev environments without https
 function uuid(): string {
   return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {

package/src/SpatialSession.ts

@@ -6,6 +6,7 @@ import {
   createSpatializedDynamic3DElement,
 } from './SpatializedElementCreator'
 import { createSpatializedStatic3DElement } from './SpatializedElementCreator'
+import { Attachment, createAttachmentEntity } from './reality/Attachment'
 import { SpatializedStatic3DElement } from './SpatializedStatic3DElement'
 import {
   ModelComponentOptions,
@@ -20,6 +21,7 @@ import {
   SpatialSphereGeometryOptions,
   SpatialUnlitMaterialOptions,
   SpatialEntityUserData,
+  AttachmentEntityOptions,
 } from './types/types'
 import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
 import { SpatialEntity } from './reality/entity/SpatialEntity'
@@ -70,7 +72,7 @@ export class SpatialSession {
    * @returns Promise resolving to a new SpatializedStatic3DElement instance
    */
   createSpatializedStatic3DElement(
-    modelURL: string = '',
+    modelURL: string,
   ): Promise<SpatializedStatic3DElement> {
     return createSpatializedStatic3DElement(modelURL)
   }
@@ -187,4 +189,16 @@ export class SpatialSession {
   ) {
     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: AttachmentEntityOptions,
+  ): Promise<Attachment> {
+    return createAttachmentEntity(options)
+  }
 }

package/src/SpatializedElementCreator.ts

@@ -30,7 +30,7 @@ export async function createSpatializedStatic3DElement(
     throw new Error('createSpatializedStatic3DElement failed')
   } else {
     const { id } = result.data
-    return new SpatializedStatic3DElement(id)
+    return new SpatializedStatic3DElement(id, modelURL)
   }
 }
 

package/src/SpatializedStatic3DElement.ts

@@ -9,6 +9,17 @@ import { SpatialWebMsgType } from './WebMsgCommand'
  * and provides events for load success and failure.
  */
 export class SpatializedStatic3DElement 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: string, modelURL: string) {
+    super(id)
+    this.modelURL = modelURL
+  }
+
   /**
    * Promise resolver for the ready state.
    * Used to resolve the ready promise when the model is loaded.
@@ -19,7 +30,7 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * Caches the last model URL to detect changes.
    * Used to reset the ready promise when the model URL changes.
    */
-  private modelURL: string = ''
+  private modelURL: string
 
   /**
    * Creates a new promise for tracking the ready state of the model.

package/src/platform-adapter/index.ts

@@ -32,7 +32,11 @@ export function createPlatform(): PlatformAbility {
   }
   const userAgent = window.navigator.userAgent
   const webSpatialVersion = getWebSpatialVersion(userAgent)
-  if (
+  if (window.navigator.userAgent.includes('Puppeteer')) {
+    const PuppeteerPlatform =
+      require('./puppeteer/PuppeteerPlatform').PuppeteerPlatform
+    return new PuppeteerPlatform()
+  } else if (
     userAgent.includes('PicoWebApp') &&
     isVersionGreater(webSpatialVersion, [0, 0, 1])
   ) {

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

@@ -0,0 +1,470 @@
+import { PlatformAbility, CommandResult } from '../interface'
+import {
+  CommandResultFailure,
+  CommandResultSuccess,
+} from '../CommandResultUtils'
+
+// 添加window扩展接口
+declare global {
+  interface Window {
+    __handleJSBMessage: (message: string) => any
+    SpatialId?: string
+  }
+
+  interface HTMLIFrameElement {
+    spatialId?: string
+    webSpatialId?: string
+  }
+}
+
+type JSBError = {
+  message: string
+}
+
+console.log('PuppeteerPlatform')
+
+export class PuppeteerPlatform implements PlatformAbility {
+  // 存储iframe实例
+  private iframeRegistry: Map<string, HTMLIFrameElement> = new Map()
+
+  constructor() {}
+
+  callJSB(cmd: string, msg: string): Promise<CommandResult> {
+    return new Promise(resolve => {
+      try {
+        // 检查__handleJSBMessage是否存在
+        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: unknown) {
+        console.error(
+          `PuppeteerPlatform cmd Error: ${cmd}, msg: ${msg} error: ${error}`,
+        )
+        resolve(CommandResultFailure('500', 'Internal error'))
+      }
+    })
+  }
+
+  /**
+   * 同步创建Spatialized2DElement到Puppeteer Runner
+   */
+  private createSpatializedElementSync(
+    spatialId: string,
+    webspatialUrl: string,
+  ): void {
+    try {
+      console.log(
+        `[Puppeteer Platform] Creating spatialized element sync with id: ${spatialId}, url: ${webspatialUrl}`,
+      )
+      // 直接调用Puppeteer Runner的方法来创建元素
+      const win = window as any
+      if (win.__handleJSBMessage) {
+        // 使用更简洁的格式，确保JSBManager能正确使用我们传递的spatialId
+        const createCommand = {
+          id: spatialId,
+          url: webspatialUrl,
+        }
+        win.__handleJSBMessage(
+          `CreateSpatialized2DElement::${JSON.stringify(createCommand)}`,
+        )
+      }
+    } catch (error) {
+      console.error('Error creating spatialized element sync:', error)
+    }
+  }
+
+  callWebSpatialProtocol(
+    command: string,
+    query?: string,
+    target?: string,
+    features?: string,
+  ): Promise<CommandResult> {
+    console.log(
+      `PuppeteerPlatform: Calling webspatial protocol: webspatial://${command}${query ? `?${query}` : ''}`,
+    )
+    return new Promise(resolve => {
+      try {
+        // 创建完整的webspatial URL
+        const webspatialUrl = `webspatial://${command}${query ? `?${query}` : ''}`
+        // 使用iframe创建新窗口
+        const { spatialId, iframe, windowProxy } = this.createIframeWindow(
+          webspatialUrl,
+          target,
+          features,
+        )
+
+        // 对于createSpatialized2DElement命令，同步创建元素
+        if (command === 'createSpatialized2DElement') {
+          this.createSpatializedElementSync(spatialId, webspatialUrl)
+        }
+        console.log(
+          `[Puppeteer Platform] iframe created with spatialId: ${spatialId}`,
+        )
+        // 注册iframe
+        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: string,
+    query?: string,
+    target?: string,
+    features?: string,
+  ): CommandResult {
+    try {
+      // 创建完整的webspatial URL
+      const webspatialUrl = `webspatial://${command}${query ? `?${query}` : ''}`
+      console.log(`Calling webspatial protocol sync: ${webspatialUrl}`)
+
+      // 使用iframe创建新窗口
+      const { spatialId, iframe, windowProxy } = this.createIframeWindow(
+        webspatialUrl,
+        target,
+        features,
+      )
+
+      // 对于createSpatialized2DElement命令，同步创建元素
+      if (command === 'createSpatialized2DElement') {
+        this.createSpatializedElementSync(spatialId, webspatialUrl)
+      }
+
+      // 注册iframe
+      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',
+      )
+    }
+  }
+
+  /**
+   * 创建基于iframe的窗口
+   */
+  private createIframeWindow(url: string, target?: string, features?: string) {
+    // 创建iframe元素
+    const iframe = document.createElement('iframe')
+
+    // 设置iframe属性
+    iframe.style.border = 'none'
+    iframe.style.display = 'none' // 初始隐藏
+    iframe.style.width = '100%'
+    iframe.style.height = '100%'
+
+    // 生成唯一的spatialId
+    const spatialId = this.generateUUID()
+    iframe.spatialId = spatialId
+    iframe.id = `spatial-iframe-${spatialId}`
+
+    // 解析features参数
+    const featuresObj = this.parseFeatures(features || '')
+
+    // 根据features设置iframe样式
+    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'
+    }
+
+    // 添加iframe到DOM
+    document.body.appendChild(iframe)
+
+    // 创建增强的windowProxy模拟对象
+    const windowProxy = this.createEnhancedWindowProxy(iframe, url, spatialId)
+
+    // 设置iframe的src
+    iframe.src = 'about:blank'
+
+    console.log(
+      `PuppeteerPlatform created iframe window with spatialId: ${spatialId}, URL: ${url}`,
+    )
+
+    // 初始化iframe内容
+    this.initializeIframeContent(iframe, url, spatialId)
+
+    return { spatialId, iframe, windowProxy }
+  }
+
+  /**
+   * 创建增强的windowProxy对象
+   */
+  private createEnhancedWindowProxy(
+    iframe: HTMLIFrameElement,
+    url: string,
+    spatialId: string,
+  ) {
+    // 创建增强的windowProxy模拟对象
+    return {
+      // 基本属性
+      location: {
+        href: url,
+        toString: () => url,
+        reload: () => {
+          if (iframe.contentWindow) {
+            iframe.contentWindow.location.reload()
+          }
+        },
+      },
+      navigator: {
+        userAgent: `Mozilla/5.0 (WebKit) SpatialId/${spatialId}`,
+      },
+
+      // 方法
+      close: () => {
+        console.log(`Closing iframe with spatialId: ${spatialId}`)
+        iframe.remove()
+        this.iframeRegistry.delete(spatialId)
+      },
+
+      // 文档访问
+      document: iframe.contentDocument || ({} as Document),
+      contentWindow: iframe.contentWindow || ({} as Window),
+
+      // 添加消息通信方法
+      postMessage: (message: any, targetOrigin?: string) => {
+        if (iframe.contentWindow) {
+          iframe.contentWindow.postMessage(message, targetOrigin || '*')
+        }
+      },
+
+      // 添加事件监听方法
+      addEventListener: (
+        type: string,
+        listener: EventListenerOrEventListenerObject,
+      ) => {
+        if (iframe.contentWindow) {
+          iframe.contentWindow.addEventListener(type, listener)
+        }
+      },
+
+      removeEventListener: (
+        type: string,
+        listener: EventListenerOrEventListenerObject,
+      ) => {
+        if (iframe.contentWindow) {
+          iframe.contentWindow.removeEventListener(type, listener)
+        }
+      },
+
+      // 执行JavaScript
+      executeScript: (code: string): any => {
+        if (iframe.contentWindow) {
+          try {
+            // 使用类型断言和更安全的方式执行脚本
+            const win = iframe.contentWindow as any
+            return win.eval(code)
+          } catch (error) {
+            console.error(
+              `Error executing script in iframe ${spatialId}:`,
+              error,
+            )
+            return null
+          }
+        }
+        return null
+      },
+
+      // 获取iframe引用
+      getIframe: () => iframe,
+
+      // 获取spatialId
+      getSpatialId: () => spatialId,
+    }
+  }
+
+  /**
+   * 初始化iframe内容
+   */
+  private initializeIframeContent(
+    iframe: HTMLIFrameElement,
+    url: string,
+    spatialId: string,
+  ): void {
+    try {
+      // 等待iframe加载完成
+      iframe.onload = () => {
+        try {
+          // 设置iframe内容
+          const iframeContent = `
+            // 注入通信脚本
+            window.webSpatialId = '${spatialId}';
+            window.SpatialId = '${spatialId}';
+            
+            // 重写window.open以支持webspatial协议
+            const originalOpen = window.open;
+            window.open = function(url, target, features) {
+              if (url && url.startsWith('webspatial://')) {
+                // 通过windowProxy处理webspatial协议
+                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);
+            };
+            
+            // 设置navigator.userAgent以识别webspatial环境
+            Object.defineProperty(navigator, 'userAgent', {
+              value: 'WebSpatial/1.0 ' + navigator.userAgent,
+              configurable: true
+            });
+            
+            // 发送加载完成消息
+            window.parent.postMessage({
+              type: 'iframe_loaded',
+              spatialId: '${spatialId}',
+              url: '${url}'
+            }, '${window.location.origin}');
+            
+            // 设置消息处理器
+            window.addEventListener('message', (event) => {
+              if (event.origin !== window.parent.location.origin) return;
+              
+              const data = event.data;
+              if (data && data.type === 'webspatial_command') {
+                // 处理来自父窗口的命令
+                console.log('Received command in iframe from parent:', data.command);
+                // 这里可以添加命令处理逻辑
+              }
+            });
+          `
+
+          // 使用document.write代替eval，更安全且符合类型定义
+          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)
+    }
+  }
+
+  /**
+   * 解析features字符串为对象
+   */
+  private parseFeatures(features: string): Record<string, string> {
+    const result: Record<string, string> = {}
+    const pairs = features.split(',')
+
+    pairs.forEach(pair => {
+      const [key, value] = pair.split('=').map(s => s.trim())
+      if (key && value) {
+        result[key] = value
+      }
+    })
+
+    return result
+  }
+
+  /**
+   * 发送消息到指定spatialId的iframe
+   */
+  public sendMessageToIframe(spatialId: string, message: any): boolean {
+    const iframe = this.iframeRegistry.get(spatialId)
+    if (iframe && iframe.contentWindow) {
+      iframe.contentWindow.postMessage(message, window.location.origin)
+      return true
+    }
+    return false
+  }
+
+  /**
+   * 获取所有活跃的iframe
+   */
+  public getAllActiveIframes(): Array<{
+    spatialId: string
+    iframe: HTMLIFrameElement
+  }> {
+    const result: Array<{ spatialId: string; iframe: HTMLIFrameElement }> = []
+
+    this.iframeRegistry.forEach((iframe, spatialId) => {
+      result.push({ spatialId, iframe })
+    })
+
+    return result
+  }
+
+  /**
+   * 清理资源
+   */
+  public dispose(): void {
+    // 关闭所有iframe
+    this.iframeRegistry.forEach((iframe, spatialId) => {
+      console.log(`Disposing iframe with spatialId: ${spatialId}`)
+      iframe.remove()
+    })
+    this.iframeRegistry.clear()
+  }
+
+  // 生成UUID函数
+  private generateUUID(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(
+      /[xy]/g,
+      function (c) {
+        const r = (Math.random() * 16) | 0
+        const v = c === 'x' ? r : (r & 0x3) | 0x8
+        return v.toString(16).toUpperCase()
+      },
+    )
+  }
+}

package/src/reality/Attachment.ts

@@ -0,0 +1,45 @@
+import { SpatialObject } from '../SpatialObject'
+import {
+  CreateAttachmentEntityCommand,
+  UpdateAttachmentEntityCommand,
+} from '../JSBCommand'
+import {
+  AttachmentEntityOptions,
+  AttachmentEntityUpdateOptions,
+} from '../types/types'
+
+export class Attachment extends SpatialObject {
+  constructor(
+    id: string,
+    private readonly windowProxy: WindowProxy,
+    private options: AttachmentEntityOptions,
+  ) {
+    super(id)
+  }
+
+  getContainer(): HTMLElement {
+    return (this.windowProxy as Window).document.body
+  }
+
+  getWindowProxy(): WindowProxy {
+    return this.windowProxy
+  }
+
+  async update(options: AttachmentEntityUpdateOptions) {
+    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()
+  }
+}
+
+export async function createAttachmentEntity(
+  options: AttachmentEntityOptions,
+): Promise<Attachment> {
+  const result = await new CreateAttachmentEntityCommand(options).execute()
+  if (!result.success) {
+    throw new Error('createAttachmentEntity failed: ' + result?.errorMessage)
+  }
+  const { id, windowProxy } = result.data!
+  return new Attachment(id, windowProxy, options)
+}

package/src/reality/index.ts

@@ -3,3 +3,4 @@ export * from './component'
 export * from './material'
 export * from './geometry'
 export * from './resource'
+export * from './Attachment'

package/src/types/types.ts

@@ -344,12 +344,14 @@ export class CubeInfo {
 
 export interface SpatialTapEventDetail {
   location3D: Point3D
+  globalLocation3D?: Point3D
 }
 
 export type SpatialTapEvent = CustomEvent<SpatialTapEventDetail>
 
 export interface SpatialDragStartEventDetail {
   startLocation3D: Point3D
+  globalLocation3D?: Point3D
 }
 
 export interface SpatialDragEventDetail {
@@ -384,3 +386,14 @@ export type SpatialMagnifyEvent = CustomEvent<SpatialMagnifyEventDetail>
 export type SpatialMagnifyEndEvent = CustomEvent<SpatialMagnifyEndEventDetail>
 
 export type SpatialEntityOrReality = SpatialEntity | SpatializedDynamic3DElement
+
+export interface AttachmentEntityOptions {
+  parentEntityId: string
+  position?: [number, number, number]
+  size: { width: number; height: number }
+}
+
+export interface AttachmentEntityUpdateOptions {
+  position?: [number, number, number]
+  size?: { width: number; height: number }
+}