@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/motion/native/serializeMotionTimeline.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'vitest'
+import { motionConfigToNativeTimeline } from './serializeMotionTimeline'
+
+describe('motionConfigToNativeTimeline', () => {
+  test('builds timeline payload for multi-track', () => {
+    const tl = motionConfigToNativeTimeline({
+      duration: 5,
+      tracks: [
+        {
+          property: 'transform.translate.x',
+          keyframes: [
+            { at: 0, value: 0 },
+            { at: 5, value: 100 },
+          ],
+        },
+        {
+          property: 'opacity',
+          timingFunction: 'easeOut',
+          keyframes: [
+            { at: 3, value: 0 },
+            { at: 5, value: 1 },
+          ],
+        },
+      ],
+    })
+    expect(tl.duration).toBe(5)
+    expect(tl.tracks).toHaveLength(2)
+    expect(tl.tracks[1].timingFunction).toBe('easeOut')
+  })
+
+  test('serializes keyframe and config timingFunction propagation', () => {
+    const tl = motionConfigToNativeTimeline({
+      duration: 4,
+      timingFunction: 'easeInOut',
+      tracks: [
+        {
+          property: 'transform.translate.x',
+          keyframes: [
+            { at: 0, value: 0, timingFunction: 'easeOut' },
+            { at: 2, value: 100 },
+            { at: 4, value: 200 },
+          ],
+        },
+        {
+          property: 'opacity',
+          keyframes: [
+            { at: 0, value: 0 },
+            { at: 4, value: 1 },
+          ],
+        },
+      ],
+    })
+
+    expect(tl.tracks[0].keyframes[0]).toMatchObject({
+      at: 0,
+      value: 0,
+      timingFunction: 'easeOut',
+    })
+    expect(tl.tracks[1].timingFunction).toBe('easeInOut')
+  })
+})

package/src/motion/native/serializeMotionTimeline.ts

@@ -0,0 +1,27 @@
+import type {
+  NormalizedSpatializedMotionConfig,
+  SpatializedMotionTimeline,
+} from '../../types/motion/spatializedMotion'
+
+/** Full timeline payload for native. */
+export function motionConfigToNativeTimeline(
+  config: NormalizedSpatializedMotionConfig,
+): SpatializedMotionTimeline {
+  return {
+    duration: config.duration,
+    delay: config.delay,
+    playbackRate: config.playbackRate,
+    loop: config.loop,
+    tracks: config.tracks.map(track => ({
+      property: track.property,
+      keyframes: track.keyframes.map(k => ({
+        at: k.at,
+        value: k.value,
+        ...(k.timingFunction !== undefined
+          ? { timingFunction: k.timingFunction }
+          : {}),
+      })),
+      timingFunction: track.timingFunction ?? config.timingFunction ?? 'linear',
+    })),
+  }
+}

package/src/platform-adapter/CommandResultUtils.ts

@@ -1,6 +1,6 @@
 import { CommandResult } from './interface'
 
-export function CommandResultSuccess(data: any): CommandResult {
+export function CommandResultSuccess<TData>(data: TData): CommandResult<TData> {
   return {
     success: true,
     data,
@@ -12,7 +12,7 @@ export function CommandResultSuccess(data: any): CommandResult {
 export function CommandResultFailure(
   errorCode: string,
   errorMessage = '',
-): CommandResult {
+): CommandResult<undefined> {
   return {
     success: false,
     data: undefined,

package/src/platform-adapter/createPlatformSync.ts

@@ -0,0 +1,36 @@
+import { resolveJsbAdapterPlatform } from '../runtime/jsbAdapterPlatform'
+import { isSSREnv } from '../isSSREnv'
+import { PlatformAbility } from './interface'
+import { PicoOSPlatform } from './pico-os/PicoOSPlatform'
+import { PuppeteerPlatform } from './puppeteer/PuppeteerPlatform'
+import { VisionOSPlatform } from './vision-os/VisionOSPlatform'
+
+const SSR_PLATFORM_ERROR =
+  'WebSpatial platform APIs (JSB / openSpatialScene) cannot run during SSR or without window. Use @webspatial/react-sdk default entry with facades, or CSR-gate spatial UI on the client.'
+
+function assertNever(_: never): never {
+  throw new Error('Unhandled jsb adapter platform kind')
+}
+
+/**
+ * Construct the JSB platform synchronously (static imports).
+ * Used by getPlatformSync (e.g. scene-polyfill openSpatialSceneSync) and kept
+ * consistent with async createPlatform so paths share one implementation.
+ */
+export function createPlatformSync(): PlatformAbility {
+  if (isSSREnv()) {
+    throw new Error(SSR_PLATFORM_ERROR)
+  }
+  const userAgent = window.navigator.userAgent
+  const kind = resolveJsbAdapterPlatform(userAgent)
+  switch (kind) {
+    case 'puppeteer':
+      return new PuppeteerPlatform()
+    case 'picoos':
+      return new PicoOSPlatform()
+    case 'visionos':
+      return new VisionOSPlatform()
+    default:
+      return assertNever(kind)
+  }
+}

package/src/platform-adapter/index.ts

@@ -1,53 +1,7 @@
-import { isSSREnv } from '../ssr-polyfill'
-import { PlatformAbility } from './interface'
-import { SSRPlatform } from './ssr/SSRPlatform'
+export { createPlatformSync } from './createPlatformSync'
+import { createPlatformSync } from './createPlatformSync'
+import type { PlatformAbility } from './interface'
 
-function getWebSpatialVersion(ua: string): number[] | null {
-  const match = ua.match(/WebSpatial\/(\d+)\.(\d+)\.(\d+)/)
-  if (!match) {
-    return null
-  }
-  return [Number(match[1]), Number(match[2]), Number(match[3])]
-}
-
-function isVersionGreater(a: number[] | null, b: number[]): boolean {
-  if (!a) {
-    return false
-  }
-  for (let index = 0; index < 3; index += 1) {
-    const diff = a[index] - b[index]
-    if (diff > 0) {
-      return true
-    }
-    if (diff < 0) {
-      return false
-    }
-  }
-  return false
-}
-
-export function createPlatform(): PlatformAbility {
-  if (isSSREnv()) {
-    return new SSRPlatform()
-  }
-  const userAgent = window.navigator.userAgent
-  const webSpatialVersion = getWebSpatialVersion(userAgent)
-  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])
-  ) {
-    const PicoOSPlatform = require('./pico-os/PicoOSPlatform').PicoOSPlatform
-    return new PicoOSPlatform()
-  } else if (userAgent.includes('Android') || userAgent.includes('Linux')) {
-    const AndroidPlatform = require('./android/AndroidPlatform').AndroidPlatform
-    return new AndroidPlatform()
-  } else {
-    const VisionOSPlatform =
-      require('./vision-os/VisionOSPlatform').VisionOSPlatform
-    return new VisionOSPlatform()
-  }
+export async function createPlatform(): Promise<PlatformAbility> {
+  return createPlatformSync()
 }

package/src/platform-adapter/interface.ts

@@ -1,36 +1,48 @@
-export interface CommandResult {
-  success: boolean
-  data: any
-  errorCode: string | undefined
-  errorMessage: string | undefined
-}
+import type { SpatialSceneCreationOptionsInternal } from '../types/internal'
+import type { AttachmentEntityOptions } from '../types/types'
 
-export interface WebSpatialProtocolResult extends CommandResult {
+export interface CommandResult<TData = any> {
   success: boolean
-  data:
-    | {
-        windowProxy: WindowProxy
-        id: string
-      }
-    | undefined
+  data: TData
   errorCode: string | undefined
   errorMessage: string | undefined
 }
 
+export type WebSpatialProtocolResult = CommandResult<
+  | {
+      // Platform-dependent window proxy shape:
+      // - browser WindowProxy (visionOS/PICO)
+      // - puppeteer simulated window object
+      // Keep broad to avoid over-constraining platform adapters/callers.
+      windowProxy: any
+      id: string
+    }
+  | undefined
+>
+
+/**
+ * Host/runtime bridge: JSB plus explicit spatial host capabilities.
+ * Implementations may use webspatial://, iframes, native events, etc.
+ */
 export interface PlatformAbility {
   callJSB(cmd: string, msg: string): Promise<CommandResult>
-  callWebSpatialProtocol(
-    schema: string,
-    query?: string,
-    target?: string,
-    features?: string,
-  ): Promise<WebSpatialProtocolResult>
 
-  callWebSpatialProtocolSync(
-    schema: string,
-    query?: string,
+  /**
+   * Open a spatial scene synchronously (e.g. window.open polyfill).
+   * Implementations may use webspatial://createSpatialScene under the hood.
+   */
+  openSpatialSceneSync(
+    url: string,
+    config: SpatialSceneCreationOptionsInternal | undefined,
     target?: string,
     features?: string,
-    resultCallback?: (result: CommandResult) => void,
   ): WebSpatialProtocolResult
+
+  /** Create a native-backed spatial 2D surface (spatial div). */
+  createNativeSpatialDiv(): Promise<WebSpatialProtocolResult>
+
+  /** Create a native attachment surface; options reserved for future protocol fields. */
+  createNativeAttachment(
+    options?: AttachmentEntityOptions,
+  ): Promise<WebSpatialProtocolResult>
 }

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

@@ -1,22 +1,36 @@
-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'
+import {
+  buildSpatialRequestQuery,
+  createSpatialRequestId,
+  DEFAULT_SPATIAL_REQUEST_TIMEOUT_MS,
+} from '../spatialRequestMetadata'
 
 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,104 +42,187 @@ 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) => {
-      const createdId = nextRequestId()
+  ): 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 = createSpatialRequestId()
+      let settled = false
+      let timeoutId: ReturnType<typeof setTimeout> | undefined
+      let cleanupDocumentReadyListener: (() => void) | undefined
+
+      // Native creation may respond synchronously, asynchronously, or never.
+      // Funnel every path through one settle() helper so receiver cleanup is
+      // exactly-once.
+      const settle = (result: WebSpatialProtocolResult) => {
+        if (settled) return
+        settled = true
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId)
+        }
+        cleanupDocumentReadyListener?.()
+        cleanupDocumentReadyListener = undefined
+        SpatialWebEvent.removeEventReceiver(createdId)
+        resolve(result)
+      }
+
       try {
-        let windowProxy: any = null
+        let windowProxy: WindowProxy | null = null
+        const settleWhenDocumentComplete = (spatialId: string) => {
+          const successResult = CommandResultSuccess({
+            windowProxy: windowProxy,
+            id: spatialId,
+          })
+          const childDocument = windowProxy?.document
+
+          if (!childDocument) {
+            settle(
+              CommandResultFailure(
+                'E_SPATIAL_DOCUMENT_UNAVAILABLE',
+                `${command} document is unavailable`,
+              ),
+            )
+            return
+          }
+
+          if (childDocument.readyState === 'complete') {
+            settle(successResult)
+            return
+          }
+
+          const onReadyStateChange = () => {
+            if (childDocument.readyState !== 'complete') return
+            settle(successResult)
+          }
+
+          cleanupDocumentReadyListener = () => {
+            childDocument.removeEventListener(
+              'readystatechange',
+              onReadyStateChange,
+            )
+          }
+          childDocument.addEventListener('readystatechange', onReadyStateChange)
+        }
+
+        timeoutId = setTimeout(() => {
+          settle(
+            CommandResultFailure(
+              'E_SPATIAL_REQUEST_TIMEOUT',
+              `${command} request timed out`,
+            ),
+          )
+        }, DEFAULT_SPATIAL_REQUEST_TIMEOUT_MS)
+
         SpatialWebEvent.addEventReceiver(
           createdId,
           (result: { spatialId: string }) => {
-            resolve(
-              CommandResultSuccess({
-                windowProxy: windowProxy,
-                id: result.spatialId,
-              }),
-            )
-            SpatialWebEvent.removeEventReceiver(createdId)
+            settleWhenDocumentComplete(result.spatialId)
           },
         )
         windowProxy = this.openWindow(
           command,
-          'rid=' + createdId,
-          target,
-          features,
+          buildSpatialRequestQuery(createdId),
         ).windowProxy
       } catch (error: unknown) {
-        const { code, message } = error as JSBError
-        SpatialWebEvent.removeEventReceiver(createdId)
-        resolve(CommandResultFailure(code, message))
+        const { code, message } = this.parseJSBError(error)
+        settle(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}` : ''}`