@webspatial/core-sdk 1.6.0 → 1.7.0

package/src/platform-adapter/pico-os/PicoOSPlatform.ts

@@ -1,22 +1,31 @@
-import { PlatformAbility, CommandResult } from '../interface'
+import {
+  PlatformAbility,
+  CommandResult,
+  WebSpatialProtocolResult,
+} from '../interface'
 import {
   CommandResultFailure,
   CommandResultSuccess,
 } from '../CommandResultUtils'
+import { buildSpatialSceneQuery } from '../spatialSceneQuery'
 import { SpatialWebEvent } from '../../SpatialWebEvent'
+import type { SpatialSceneCreationOptionsInternal } from '../../types/internal'
+import type { AttachmentEntityOptions } from '../../types/types'
 
 interface JSBResponse {
   success: boolean
   data: any
 }
 type JSBError = {
-  code: string
+  code?: string
   message: string
 }
 
 let requestId = 0
 
 const MAX_ID = 100000
+const DEFAULT_JSB_ERROR_CODE = 'E_PICO_JSB'
+const DEFAULT_JSB_ERROR_MESSAGE = 'Pico JSB execution failed'
 
 function nextRequestId() {
   requestId = (requestId + 1) % MAX_ID
@@ -28,51 +37,67 @@ export class PicoOSPlatform implements PlatformAbility {
   async callJSB(cmd: string, msg: string): Promise<CommandResult> {
     // swan JS Bridge interface only support sync invoking
     // in order to implement promise API, register every request by requestId and remove when resolve/reject.
-    return new Promise((resolve, reject) => {
+    return new Promise(resolve => {
       try {
         const rId = nextRequestId()
 
         SpatialWebEvent.addEventReceiver(rId, (result: JSBResponse) => {
           SpatialWebEvent.removeEventReceiver(rId)
-          if (result.success) {
-            resolve(CommandResultSuccess(result.data))
-          } else {
-            const { code, message } = result.data as JSBError
-            resolve(CommandResultFailure(code, message))
-          }
+          resolve(this.toCommandResult(result))
         })
 
         const ans = window.webspatialBridge.postMessage(rId, cmd, msg)
         if (ans !== '') {
           SpatialWebEvent.removeEventReceiver(rId)
           // sync call
-          const result = JSON.parse(ans) as JSBResponse
-          if (result.success) {
-            resolve(CommandResultSuccess(result.data))
-          } else {
-            const { code, message } = result.data as JSBError
-            resolve(CommandResultFailure(code, message))
-          }
+          resolve(this.parseBridgeResponse(ans))
         }
       } catch (error: unknown) {
         console.error(`SwanPlatform cmd: ${cmd}, msg: ${msg} error: ${error}`)
-        const { code, message } = error as JSBError
+        const { code, message } = this.parseJSBError(error)
         resolve(CommandResultFailure(code, message))
       }
     })
   }
 
-  async callWebSpatialProtocol(
-    command: string,
-    query?: string,
+  openSpatialSceneSync(
+    url: string,
+    config: SpatialSceneCreationOptionsInternal | undefined,
     target?: string,
     features?: string,
-  ): Promise<CommandResult> {
-    // Waiting for request to create spatial div
-    return new Promise((resolve, reject) => {
+  ): WebSpatialProtocolResult {
+    const query = buildSpatialSceneQuery(url, config)
+    const { spatialId: id = '', windowProxy } = this.openWindow(
+      'createSpatialScene',
+      query,
+      target,
+      features,
+    )
+
+    return CommandResultSuccess({ windowProxy, id })
+  }
+
+  createNativeSpatialDiv(): Promise<WebSpatialProtocolResult> {
+    return this.waitForRidProtocolAsync('createSpatialized2DElement')
+  }
+
+  createNativeAttachment(
+    _options?: AttachmentEntityOptions,
+  ): Promise<WebSpatialProtocolResult> {
+    return this.waitForRidProtocolAsync('createAttachment')
+  }
+
+  /**
+   * Async path for createNativeSpatialDiv / createNativeAttachment: open webspatial URL
+   * with rid= correlation (Pico OS 6).
+   */
+  private waitForRidProtocolAsync(
+    command: string,
+  ): Promise<WebSpatialProtocolResult> {
+    return new Promise(resolve => {
       const createdId = nextRequestId()
       try {
-        let windowProxy: any = null
+        let windowProxy: WindowProxy | null = null
         SpatialWebEvent.addEventReceiver(
           createdId,
           (result: { spatialId: string }) => {
@@ -85,47 +110,54 @@ export class PicoOSPlatform implements PlatformAbility {
             SpatialWebEvent.removeEventReceiver(createdId)
           },
         )
-        windowProxy = this.openWindow(
-          command,
-          'rid=' + createdId,
-          target,
-          features,
-        ).windowProxy
+        windowProxy = this.openWindow(command, 'rid=' + createdId).windowProxy
       } catch (error: unknown) {
-        const { code, message } = error as JSBError
+        const { code, message } = this.parseJSBError(error)
         SpatialWebEvent.removeEventReceiver(createdId)
         resolve(CommandResultFailure(code, message))
       }
     })
   }
 
-  callWebSpatialProtocolSync(
+  private openWindow(
     command: string,
     query?: string,
     target?: string,
     features?: string,
-  ): CommandResult {
-    const { spatialId: id = '', windowProxy } = this.openWindow(
-      command,
-      query,
-      target,
-      features,
-    )
+  ): { spatialId: string; windowProxy: WindowProxy | null } {
+    const url = query
+      ? `webspatial://${command}?${query}`
+      : `webspatial://${command}`
+    const windowProxy = window.open(url, target, features)
+    return { spatialId: '', windowProxy }
+  }
 
-    return CommandResultSuccess({ windowProxy, id })
+  private parseBridgeResponse(ans: string): CommandResult {
+    try {
+      const result = JSON.parse(ans) as JSBResponse
+      return this.toCommandResult(result)
+    } catch {
+      return CommandResultFailure(
+        DEFAULT_JSB_ERROR_CODE,
+        'Invalid Pico JSB response payload',
+      )
+    }
   }
 
-  private openWindow(
-    command: string,
-    query?: string,
-    target?: string,
-    features?: string,
-  ) {
-    const windowProxy = window.open(
-      `webspatial://${command}?${query || ''}`,
-      target,
-      features,
-    )
-    return { spatialId: '', windowProxy }
+  private toCommandResult(result: JSBResponse): CommandResult {
+    if (result.success) {
+      return CommandResultSuccess(result.data)
+    }
+    const { code, message } = this.parseJSBError(result.data)
+    return CommandResultFailure(code, message)
+  }
+
+  private parseJSBError(error: unknown): { code: string; message: string } {
+    return {
+      code: (error as JSBError)?.code ?? DEFAULT_JSB_ERROR_CODE,
+      message:
+        (error as JSBError)?.message ??
+        (typeof error === 'string' ? error : DEFAULT_JSB_ERROR_MESSAGE),
+    }
   }
 }

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

@@ -1,4 +1,11 @@
-import { PlatformAbility, CommandResult } from '../interface'
+import {
+  PlatformAbility,
+  CommandResult,
+  WebSpatialProtocolResult,
+} from '../interface'
+import { buildSpatialSceneQuery } from '../spatialSceneQuery'
+import type { SpatialSceneCreationOptionsInternal } from '../../types/internal'
+import type { AttachmentEntityOptions } from '../../types/types'
 import {
   CommandResultFailure,
   CommandResultSuccess,
@@ -17,12 +24,6 @@ declare global {
   }
 }
 
-type JSBError = {
-  message: string
-}
-
-console.log('PuppeteerPlatform')
-
 export class PuppeteerPlatform implements PlatformAbility {
   // store iframe instance
   private iframeRegistry: Map<string, HTMLIFrameElement> = new Map()
@@ -85,12 +86,37 @@ export class PuppeteerPlatform implements PlatformAbility {
     }
   }
 
-  callWebSpatialProtocol(
+  openSpatialSceneSync(
+    url: string,
+    config: SpatialSceneCreationOptionsInternal | undefined,
+    target?: string,
+    features?: string,
+  ): WebSpatialProtocolResult {
+    const query = buildSpatialSceneQuery(url, config)
+    return this.runProtocolSync('createSpatialScene', query, target, features)
+  }
+
+  createNativeSpatialDiv(): Promise<WebSpatialProtocolResult> {
+    return this.runProtocolAsync(
+      'createSpatialized2DElement',
+      '',
+      undefined,
+      undefined,
+    )
+  }
+
+  createNativeAttachment(
+    _options?: AttachmentEntityOptions,
+  ): Promise<WebSpatialProtocolResult> {
+    return this.runProtocolAsync('createAttachment', '', undefined, undefined)
+  }
+
+  private runProtocolAsync(
     command: string,
     query?: string,
     target?: string,
     features?: string,
-  ): Promise<CommandResult> {
+  ): Promise<WebSpatialProtocolResult> {
     console.log(
       `PuppeteerPlatform: Calling webspatial protocol: webspatial://${command}${query ? `?${query}` : ''}`,
     )
@@ -124,12 +150,12 @@ export class PuppeteerPlatform implements PlatformAbility {
     })
   }
 
-  callWebSpatialProtocolSync(
+  private runProtocolSync(
     command: string,
     query?: string,
     target?: string,
     features?: string,
-  ): CommandResult {
+  ): WebSpatialProtocolResult {
     try {
       // create complete webspatial URL
       const webspatialUrl = `webspatial://${command}${query ? `?${query}` : ''}`

package/src/platform-adapter/spatialSceneQuery.ts

@@ -0,0 +1,17 @@
+import type { SpatialSceneCreationOptionsInternal } from '../types/internal'
+
+/** Build query string for webspatial://createSpatialScene (url + config). */
+export function buildSpatialSceneQuery(
+  url: string,
+  config: SpatialSceneCreationOptionsInternal | undefined,
+): string {
+  const params: Record<string, any> = { url, config }
+  return Object.keys(params)
+    .map(key => {
+      const value = params[key]
+      const finalValue =
+        typeof value === 'object' ? JSON.stringify(value) : value
+      return `${key}=${encodeURIComponent(finalValue)}`
+    })
+    .join('&')
+}

package/src/platform-adapter/ssr/SSRPlatform.ts

@@ -3,6 +3,8 @@ import {
   PlatformAbility,
   WebSpatialProtocolResult,
 } from '../interface'
+import type { SpatialSceneCreationOptionsInternal } from '../../types/internal'
+import type { AttachmentEntityOptions } from '../../types/types'
 
 export class SSRPlatform implements PlatformAbility {
   callJSB(cmd: string, msg: string): Promise<CommandResult> {
@@ -13,12 +15,22 @@ export class SSRPlatform implements PlatformAbility {
       errorMessage: undefined,
     })
   }
-  callWebSpatialProtocol(
-    schema: string,
-    query?: string,
-    target?: string,
-    features?: string,
-  ): Promise<WebSpatialProtocolResult> {
+
+  openSpatialSceneSync(
+    _url: string,
+    _config: SpatialSceneCreationOptionsInternal | undefined,
+    _target?: string,
+    _features?: string,
+  ): WebSpatialProtocolResult {
+    return {
+      success: true,
+      data: undefined,
+      errorCode: undefined,
+      errorMessage: undefined,
+    }
+  }
+
+  createNativeSpatialDiv(): Promise<WebSpatialProtocolResult> {
     return Promise.resolve({
       success: true,
       data: undefined,
@@ -26,18 +38,15 @@ export class SSRPlatform implements PlatformAbility {
       errorMessage: undefined,
     })
   }
-  callWebSpatialProtocolSync(
-    schema: string,
-    query?: string,
-    target?: string,
-    features?: string,
-    resultCallback?: (result: CommandResult) => void,
-  ): WebSpatialProtocolResult {
-    return {
+
+  createNativeAttachment(
+    _options?: AttachmentEntityOptions,
+  ): Promise<WebSpatialProtocolResult> {
+    return Promise.resolve({
       success: true,
       data: undefined,
       errorCode: undefined,
       errorMessage: undefined,
-    }
+    })
   }
 }

package/src/platform-adapter/vision-os/VisionOSPlatform.ts

@@ -1,13 +1,24 @@
-import { PlatformAbility, CommandResult } from '../interface'
+import {
+  PlatformAbility,
+  CommandResult,
+  WebSpatialProtocolResult,
+} from '../interface'
 import {
   CommandResultFailure,
   CommandResultSuccess,
 } from '../CommandResultUtils'
+import { buildSpatialSceneQuery } from '../spatialSceneQuery'
+import type { SpatialSceneCreationOptionsInternal } from '../../types/internal'
+import type { AttachmentEntityOptions } from '../../types/types'
 
 type JSBError = {
+  code?: string
   message: string
 }
 
+const UUID_RE =
+  /\b([0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12})\b/gi
+
 export class VisionOSPlatform implements PlatformAbility {
   async callJSB(cmd: string, msg: string): Promise<CommandResult> {
     try {
@@ -17,41 +28,47 @@ export class VisionOSPlatform implements PlatformAbility {
       return CommandResultSuccess(result)
     } catch (error: unknown) {
       // console.error(`VisionOSPlatform cmd: ${cmd}, msg: ${msg} error: ${error}`)
-      const { code, message } = JSON.parse((error as JSBError).message)
+      const { code, message } = this.parseJSBError(error)
       return CommandResultFailure(code, message)
     }
   }
 
-  callWebSpatialProtocol(
-    command: string,
-    query?: string,
+  openSpatialSceneSync(
+    url: string,
+    config: SpatialSceneCreationOptionsInternal | undefined,
     target?: string,
     features?: string,
-  ): Promise<CommandResult> {
-    const { spatialId: id, windowProxy } = this.openWindow(
-      command,
+  ): WebSpatialProtocolResult {
+    const query = buildSpatialSceneQuery(url, config)
+    const { spatialId: id = '', windowProxy } = this.openWindow(
+      'createSpatialScene',
       query,
       target,
       features,
     )
-    return Promise.resolve(
-      CommandResultSuccess({ windowProxy: windowProxy, id }),
-    )
+
+    return CommandResultSuccess({ windowProxy, id })
+  }
+
+  createNativeSpatialDiv(): Promise<WebSpatialProtocolResult> {
+    return this.openProtocolAsync('createSpatialized2DElement')
+  }
+
+  createNativeAttachment(
+    _options?: AttachmentEntityOptions,
+  ): Promise<WebSpatialProtocolResult> {
+    return this.openProtocolAsync('createAttachment')
   }
 
-  callWebSpatialProtocolSync(
+  private async openProtocolAsync(
     command: string,
-    query?: string,
-    target?: string,
-    features?: string,
-  ): CommandResult {
+  ): Promise<WebSpatialProtocolResult> {
     const { spatialId: id = '', windowProxy } = this.openWindow(
       command,
-      query,
-      target,
-      features,
+      '',
+      undefined,
+      undefined,
     )
-
     return CommandResultSuccess({ windowProxy, id })
   }
 
@@ -60,17 +77,31 @@ export class VisionOSPlatform implements PlatformAbility {
     query?: string,
     target?: string,
     features?: string,
-  ) {
+  ): { spatialId?: string; windowProxy: WindowProxy | null } {
     const windowProxy = window.open(
       `webspatial://${command}?${query || ''}`,
       target,
       features,
     )
     const ua = windowProxy?.navigator.userAgent
-    const spatialId = ua?.match(
-      /\b([0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12})\b/gi,
-    )?.[0]
+    const spatialId = ua?.match(UUID_RE)?.[0]
 
     return { spatialId, windowProxy }
   }
+
+  private parseJSBError(error: unknown): { code: string; message: string } {
+    try {
+      const parsed = JSON.parse((error as JSBError).message ?? '')
+      return {
+        code: parsed.code ?? 'E_VISIONOS_JSB',
+        message: parsed.message ?? 'VisionOS JSB execution failed',
+      }
+    } catch {
+      return {
+        code: 'E_VISIONOS_JSB',
+        message:
+          (error as JSBError)?.message ?? 'VisionOS JSB execution failed',
+      }
+    }
+  }
 }

package/src/platform-runtime.ts

@@ -0,0 +1,13 @@
+import { createPlatformSync } from './platform-adapter'
+import type { PlatformAbility } from './platform-adapter/interface'
+
+let platformResolved: PlatformAbility | undefined
+
+export function getPlatformSync(): PlatformAbility {
+  platformResolved ??= createPlatformSync()
+  return platformResolved
+}
+
+export async function getPlatform(): Promise<PlatformAbility> {
+  return getPlatformSync()
+}

package/src/reality/Attachment.ts

@@ -1,9 +1,9 @@
 import { SpatialObject } from '../SpatialObject'
 import {
-  CreateAttachmentEntityCommand,
   UpdateAttachmentEntityCommand,
   InitializeAttachmentCommand,
 } from '../JSBCommand'
+import { createNativeAttachment } from '../spatial-host'
 import {
   AttachmentEntityOptions,
   AttachmentEntityUpdateOptions,
@@ -37,7 +37,7 @@ export class Attachment extends SpatialObject {
 export async function createAttachmentEntity(
   options: AttachmentEntityOptions,
 ): Promise<Attachment> {
-  const result = await new CreateAttachmentEntityCommand(options).execute()
+  const result = await createNativeAttachment(options)
   if (!result.success) {
     throw new Error('createAttachmentEntity failed: ' + result?.errorMessage)
   }

package/src/reality/entity/SpatialEntity.ts

@@ -12,9 +12,7 @@ import {
 } from '../../types/types'
 import {
   AddComponentToEntityCommand,
-  AddEntityToEntityCommand,
   RemoveComponentFromEntityCommand,
-  RemoveEntityFromParentCommand,
   UpdateEntityEventCommand,
   UpdateEntityPropertiesCommand,
 } from '../../JSBCommand'

package/src/reality/realityCreator.ts

@@ -5,6 +5,7 @@ import {
   CreateSpatialGeometryCommand,
   CreateSpatialModelEntityCommand,
   CreateSpatialUnlitMaterialCommand,
+  CreateTextureCommand,
 } from '../JSBCommand'
 import {
   ModelComponentOptions,
@@ -13,12 +14,13 @@ import {
   SpatialModelEntityCreationOptions,
   SpatialUnlitMaterialOptions,
   SpatialEntityUserData,
+  SpatialTextureResourceOptions,
 } from '../types/types'
 import { SpatialEntity, SpatialModelEntity } from './entity'
 import { ModelComponent } from './component'
 import { SpatialGeometry } from './geometry'
 import { SpatialUnlitMaterial } from './material'
-import { SpatialModelAsset } from './resource'
+import { SpatialModelAsset, SpatialTextureResource } from './resource'
 
 export async function createSpatialEntity(
   userData?: SpatialEntityUserData,
@@ -92,3 +94,15 @@ export async function createModelAsset(options: ModelAssetOptions) {
     return new SpatialModelAsset(id, options)
   }
 }
+
+export async function createSpatialTexture(
+  options: SpatialTextureResourceOptions,
+) {
+  const result = await new CreateTextureCommand(options.url).execute()
+  if (!result.success) {
+    throw new Error('createSpatialTexture failed:' + result?.errorMessage)
+  } else {
+    const { id } = result.data
+    return new SpatialTextureResource(id, options)
+  }
+}

package/src/reality/resource/SpatialTextureResource.ts

@@ -0,0 +1,16 @@
+import { SpatialObject } from '../../SpatialObject'
+import { SpatialTextureResourceOptions } from '../../types/types'
+import { UpdateTexturePropertiesCommand } from '../../JSBCommand'
+
+export class SpatialTextureResource extends SpatialObject {
+  constructor(
+    public id: string,
+    public options: SpatialTextureResourceOptions,
+  ) {
+    super(id)
+  }
+
+  updateProperties(properties: Partial<SpatialTextureResourceOptions>) {
+    return new UpdateTexturePropertiesCommand(this, properties).execute()
+  }
+}

package/src/reality/resource/index.ts

@@ -1 +1,2 @@
 export * from './SpatialModelAsset'
+export * from './SpatialTextureResource'

package/src/runtime/WebSpatialRuntimeError.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown when a runtime-gated JS API is invoked but `supports('<name>')` is false.
+ * See OpenSpec `runtime-capabilities/spec.md` (Unsupported behavior contracts).
+ */
+export class WebSpatialRuntimeError extends Error {
+  public readonly capability: string
+
+  constructor(capability: string, message?: string) {
+    super(
+      message ??
+        `Capability "${capability}" is not supported in this WebSpatial runtime`,
+    )
+    this.name = 'WebSpatialRuntimeError'
+    this.capability = capability
+  }
+}