@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/platform-adapter/spatialRequestMetadata.test.ts

@@ -0,0 +1,175 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+describe('spatial request metadata', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+    vi.resetModules()
+    delete window.__webspatialsdk__
+  })
+
+  it('builds opaque request ids and includes page epoch when available', async () => {
+    window.__webspatialsdk__ = { pageEpoch: 7 }
+    const { buildSpatialRequestQuery, createSpatialRequestId } = await import(
+      './spatialRequestMetadata'
+    )
+
+    const first = createSpatialRequestId()
+    const second = createSpatialRequestId()
+    expect(first).not.toBe(second)
+
+    const params = new URLSearchParams(buildSpatialRequestQuery(first))
+    expect(params.get('rid')).toBe(first)
+    expect(params.get('wsepoch')).toBe('7')
+  })
+
+  it('emits request id without epoch when host state is unavailable', async () => {
+    const { buildSpatialRequestQuery, createSpatialRequestId } = await import(
+      './spatialRequestMetadata'
+    )
+
+    const requestId = createSpatialRequestId()
+    const params = new URLSearchParams(buildSpatialRequestQuery(requestId))
+    expect(params.get('rid')).toBe(requestId)
+    expect(params.get('wsepoch')).toBeNull()
+  })
+
+  it('builds refresh-safe request ids across module reinitialization', async () => {
+    const nonceValues = [
+      [1, 2],
+      [3, 4],
+    ]
+    const getRandomValues = vi.fn((values: Uint32Array) => {
+      const next = nonceValues.shift() ?? [5, 6]
+      values[0] = next[0]
+      values[1] = next[1]
+      return values
+    })
+
+    vi.stubGlobal('crypto', { getRandomValues })
+
+    const firstModule = await import('./spatialRequestMetadata')
+    const first = firstModule.createSpatialRequestId()
+
+    vi.resetModules()
+
+    const secondModule = await import('./spatialRequestMetadata')
+    const second = secondModule.createSpatialRequestId()
+
+    expect(first).toMatch(/^wsreq_/)
+    expect(second).toMatch(/^wsreq_/)
+    expect(first).not.toBe(second)
+  })
+})
+
+describe('PicoOSPlatform SpatialDiv request correlation', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+    vi.resetModules()
+    delete window.__webspatialsdk__
+    delete (window as any).__SpatialWebEvent
+  })
+
+  it('opens SpatialDiv protocol with rid and wsepoch', async () => {
+    window.__webspatialsdk__ = { pageEpoch: '3' }
+    const { SpatialWebEvent } = await import('../SpatialWebEvent')
+    SpatialWebEvent.init()
+    const open = vi.fn(
+      () =>
+        ({
+          document: {
+            readyState: 'complete',
+            addEventListener: vi.fn(),
+            removeEventListener: vi.fn(),
+          },
+        }) as unknown as Window,
+    )
+    vi.spyOn(window, 'open').mockImplementation(open)
+
+    const { PicoOSPlatform } = await import('./pico-os/PicoOSPlatform')
+    const platform = new PicoOSPlatform()
+    const pending = platform.createNativeSpatialDiv()
+
+    const openedUrl = (open.mock.calls[0] as unknown[])[0] as string
+    const url = new URL(openedUrl)
+    const requestId = url.searchParams.get('rid')
+    expect(url.protocol).toBe('webspatial:')
+    expect(url.host).toBe('createSpatialized2DElement')
+    expect(requestId).toBeTruthy()
+    expect(url.searchParams.get('wsepoch')).toBe('3')
+
+    window.__SpatialWebEvent({
+      id: requestId!,
+      data: { spatialId: 'spatial-1' },
+    })
+
+    await expect(pending).resolves.toMatchObject({
+      success: true,
+      data: { id: 'spatial-1' },
+    })
+    expect(SpatialWebEvent.eventReceiver[requestId!]).toBeUndefined()
+  })
+
+  it('opens attachment protocol with rid and wsepoch', async () => {
+    window.__webspatialsdk__ = { pageEpoch: '4' }
+    const { SpatialWebEvent } = await import('../SpatialWebEvent')
+    SpatialWebEvent.init()
+    const open = vi.fn(
+      () =>
+        ({
+          document: {
+            readyState: 'complete',
+            addEventListener: vi.fn(),
+            removeEventListener: vi.fn(),
+          },
+        }) as unknown as Window,
+    )
+    vi.spyOn(window, 'open').mockImplementation(open)
+
+    const { PicoOSPlatform } = await import('./pico-os/PicoOSPlatform')
+    const platform = new PicoOSPlatform()
+    const pending = platform.createNativeAttachment()
+
+    const openedUrl = (open.mock.calls[0] as unknown[])[0] as string
+    const url = new URL(openedUrl)
+    const requestId = url.searchParams.get('rid')
+    expect(url.protocol).toBe('webspatial:')
+    expect(url.host).toBe('createAttachment')
+    expect(requestId).toBeTruthy()
+    expect(url.searchParams.get('wsepoch')).toBe('4')
+
+    window.__SpatialWebEvent({
+      id: requestId!,
+      data: { spatialId: 'attachment-1' },
+    })
+
+    await expect(pending).resolves.toMatchObject({
+      success: true,
+      data: { id: 'attachment-1' },
+    })
+    expect(SpatialWebEvent.eventReceiver[requestId!]).toBeUndefined()
+  })
+
+  it('times out pending SpatialDiv requests', async () => {
+    vi.useFakeTimers()
+    vi.spyOn(window, 'open').mockImplementation(() => null)
+    const { SpatialWebEvent } = await import('../SpatialWebEvent')
+
+    const { PicoOSPlatform } = await import('./pico-os/PicoOSPlatform')
+    const { DEFAULT_SPATIAL_REQUEST_TIMEOUT_MS } = await import(
+      './spatialRequestMetadata'
+    )
+
+    const platform = new PicoOSPlatform()
+    const pending = platform.createNativeSpatialDiv()
+    await vi.advanceTimersByTimeAsync(DEFAULT_SPATIAL_REQUEST_TIMEOUT_MS)
+
+    await expect(pending).resolves.toMatchObject({
+      success: false,
+      errorCode: 'E_SPATIAL_REQUEST_TIMEOUT',
+    })
+    expect(Object.keys(SpatialWebEvent.eventReceiver)).toHaveLength(0)
+  })
+})

package/src/platform-adapter/spatialRequestMetadata.ts

@@ -0,0 +1,48 @@
+const REQUEST_ID_PREFIX = 'wsreq'
+
+export const DEFAULT_SPATIAL_REQUEST_TIMEOUT_MS = 30_000
+
+let requestSequence = 0
+
+// One nonce per JS execution context keeps request ids refresh-safe without
+// exposing host-specific lifecycle details in the protocol surface.
+const contextNonce = createContextNonce()
+
+function createContextNonce(): string {
+  const cryptoApi = globalThis.crypto
+  if (cryptoApi?.getRandomValues) {
+    const values = new Uint32Array(2)
+    cryptoApi.getRandomValues(values)
+    return Array.from(values, value => value.toString(36)).join('')
+  }
+
+  return Math.random().toString(36).slice(2, 12)
+}
+
+export function createSpatialRequestId(): string {
+  requestSequence += 1
+  return `${REQUEST_ID_PREFIX}_${contextNonce}_${requestSequence}`
+}
+
+export function getCurrentPageEpoch(): string | undefined {
+  const pageEpoch = window.__webspatialsdk__?.pageEpoch
+  if (pageEpoch === undefined || pageEpoch === null || pageEpoch === '') {
+    return undefined
+  }
+
+  return String(pageEpoch)
+}
+
+export function buildSpatialRequestQuery(
+  requestId: string,
+  pageEpoch = getCurrentPageEpoch(),
+): string {
+  const params = new URLSearchParams()
+  params.set('rid', requestId)
+
+  if (pageEpoch !== undefined) {
+    params.set('wsepoch', pageEpoch)
+  }
+
+  return params.toString()
+}

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/vision-os/VisionOSPlatform.ts

@@ -1,13 +1,28 @@
-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'
+import {
+  buildSpatialRequestQuery,
+  createSpatialRequestId,
+} from '../spatialRequestMetadata'
 
 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 +32,48 @@ 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 })
   }
 
-  callWebSpatialProtocolSync(
+  createNativeSpatialDiv(): Promise<WebSpatialProtocolResult> {
+    return this.openProtocolAsync('createSpatialized2DElement')
+  }
+
+  createNativeAttachment(
+    _options?: AttachmentEntityOptions,
+  ): Promise<WebSpatialProtocolResult> {
+    return this.openProtocolAsync('createAttachment')
+  }
+
+  private async openProtocolAsync(
     command: string,
-    query?: string,
-    target?: string,
-    features?: string,
-  ): CommandResult {
+  ): Promise<WebSpatialProtocolResult> {
+    const requestId = createSpatialRequestId()
     const { spatialId: id = '', windowProxy } = this.openWindow(
       command,
-      query,
-      target,
-      features,
+      buildSpatialRequestQuery(requestId),
+      undefined,
+      undefined,
     )
-
     return CommandResultSuccess({ windowProxy, id })
   }
 
@@ -60,17 +82,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

@@ -3,6 +3,7 @@ import {
   ConvertFromEntityToSceneCommand,
   ConvertFromSceneToEntityCommand,
   SetParentForEntityCommand,
+  AnimateTransformJSBCommand,
 } from './../../JSBCommand'
 import {
   SpatialEntityEventType,
@@ -10,11 +11,15 @@ import {
   SpatialEntityUserData,
   Vec3,
 } from '../../types/types'
+import type {
+  AnimateTransformCommand,
+  AnimateTransformResult,
+  TransformValues,
+  AnimationError,
+} from '../../types/animation'
 import {
   AddComponentToEntityCommand,
-  AddEntityToEntityCommand,
   RemoveComponentFromEntityCommand,
-  RemoveEntityFromParentCommand,
   UpdateEntityEventCommand,
   UpdateEntityPropertiesCommand,
 } from '../../JSBCommand'
@@ -23,6 +28,7 @@ import { SpatialEntityProperties } from '../../types/types'
 import { SpatialComponent } from '../component/SpatialComponent'
 import { SpatialWebEvent } from '../../SpatialWebEvent'
 import { createSpatialEvent } from '../../SpatialWebEventCreator'
+import { decomposeSRT } from '../../utils'
 import {
   ObjectDestroyMsg,
   SpatialDragEndMsg,
@@ -34,6 +40,9 @@ import {
   SpatialRotateMsg,
   SpatialTapMsg,
   SpatialWebMsgType,
+  AnimationCompletedEventPayload,
+  AnimationCanceledEventPayload,
+  AnimationFailedEventPayload,
 } from '../../WebMsgCommand'
 
 export class SpatialEntity extends SpatialObject {
@@ -120,6 +129,122 @@ export class SpatialEntity extends SpatialObject {
     return new UpdateEntityPropertiesCommand(this, properties).execute()
   }
 
+  /**
+   * Send an animation command to the native layer.
+   *
+   * For `play`: registers event listeners for completion / stop / failure,
+   * sends the JSB command, and returns an `AnimateTransformResult` with
+   * `finished` and `stopped` promises.
+   *
+   * For `pause`, `resume`, `cancel``: sends the command and resolves when
+   * the bridge acknowledges it.
+   */
+  animateTransform(
+    command: AnimateTransformCommand & { type: 'play' },
+  ): Promise<AnimateTransformResult>
+  animateTransform(command: AnimateTransformCommand): Promise<void>
+  async animateTransform(
+    command: AnimateTransformCommand,
+  ): Promise<AnimateTransformResult | void> {
+    const { animationId, type } = command
+
+    if (type === 'play') {
+      // Register event listeners BEFORE sending the play command
+      // to avoid race conditions where native fires before we listen.
+      let resolveFinished!: (val: TransformValues) => void
+      let resolveCancel!: (val: TransformValues) => void
+      let resolveFailed!: (err: AnimationError) => void
+
+      const finished = new Promise<TransformValues>(r => {
+        resolveFinished = r
+      })
+      const canceled = new Promise<TransformValues>(r => {
+        resolveCancel = r
+      })
+      const failed = new Promise<AnimationError>(r => {
+        resolveFailed = r
+      })
+
+      const cleanup = () => {
+        SpatialWebEvent.removeEventReceiver(`${animationId}_completed`)
+        SpatialWebEvent.removeEventReceiver(`${animationId}_canceled`)
+        SpatialWebEvent.removeEventReceiver(`${animationId}_failed`)
+      }
+
+      SpatialWebEvent.addEventReceiver(
+        `${animationId}_completed`,
+        (data: AnimationCompletedEventPayload) => {
+          cleanup()
+          const values = decomposeSRT(data.transform)
+          // Update local entity state to match the native final transform
+          if (values.position) this.position = values.position
+          if (values.rotation) this.rotation = values.rotation
+          if (values.scale) this.scale = values.scale
+          resolveFinished(values)
+        },
+      )
+
+      SpatialWebEvent.addEventReceiver(
+        `${animationId}_canceled`,
+        (data: AnimationCanceledEventPayload) => {
+          cleanup()
+          const values = decomposeSRT(data.transform)
+          if (values.position) this.position = values.position
+          if (values.rotation) this.rotation = values.rotation
+          if (values.scale) this.scale = values.scale
+          resolveCancel(values)
+        },
+      )
+
+      SpatialWebEvent.addEventReceiver(
+        `${animationId}_failed`,
+        (data: AnimationFailedEventPayload) => {
+          cleanup()
+          resolveFailed({
+            animationId: data.animationId,
+            command: data.command,
+            code: data.code,
+            reason: data.reason,
+          })
+        },
+      )
+
+      // Send the play command
+      const result = await new AnimateTransformJSBCommand(command).execute()
+      if (!result.success) {
+        cleanup()
+        throw new Error(
+          result.errorMessage ?? 'AnimateTransform play command failed',
+        )
+      }
+
+      return {
+        animationId,
+        finished,
+        canceled,
+        failed,
+      } as AnimateTransformResult
+    } else {
+      // pause / resume / cancel — fire and wait for bridge ack
+      const result = await new AnimateTransformJSBCommand(command).execute()
+      if (!result.success) {
+        throw new Error(
+          result.errorMessage ?? `AnimateTransform ${type} command failed`,
+        )
+      }
+    }
+  }
+
+  /**
+   * Remove all animation event receivers for a given animationId.
+   * Called on entity unmount to prevent leaked listeners.
+   */
+  cleanupAnimationListeners(animationId: string) {
+    SpatialWebEvent.removeEventReceiver(`${animationId}_completed`)
+    SpatialWebEvent.removeEventReceiver(`${animationId}_canceled`)
+    SpatialWebEvent.removeEventReceiver(`${animationId}_failed`)
+  }
+
   async addEvent(type: SpatialEntityEventType, callback: (data: any) => void) {
     if (this.events[type]) {
       // replace if exist

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
+  }
+}