@webspatial/core-sdk 1.7.0 → 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/vision-os/VisionOSPlatform.ts

@@ -10,6 +10,10 @@ import {
 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
@@ -63,9 +67,10 @@ export class VisionOSPlatform implements PlatformAbility {
   private async openProtocolAsync(
     command: string,
   ): Promise<WebSpatialProtocolResult> {
+    const requestId = createSpatialRequestId()
     const { spatialId: id = '', windowProxy } = this.openWindow(
       command,
-      '',
+      buildSpatialRequestQuery(requestId),
       undefined,
       undefined,
     )

package/src/reality/entity/SpatialEntity.ts

@@ -3,6 +3,7 @@ import {
   ConvertFromEntityToSceneCommand,
   ConvertFromSceneToEntityCommand,
   SetParentForEntityCommand,
+  AnimateTransformJSBCommand,
 } from './../../JSBCommand'
 import {
   SpatialEntityEventType,
@@ -10,6 +11,12 @@ import {
   SpatialEntityUserData,
   Vec3,
 } from '../../types/types'
+import type {
+  AnimateTransformCommand,
+  AnimateTransformResult,
+  TransformValues,
+  AnimationError,
+} from '../../types/animation'
 import {
   AddComponentToEntityCommand,
   RemoveComponentFromEntityCommand,
@@ -21,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,
@@ -32,6 +40,9 @@ import {
   SpatialRotateMsg,
   SpatialTapMsg,
   SpatialWebMsgType,
+  AnimationCompletedEventPayload,
+  AnimationCanceledEventPayload,
+  AnimationFailedEventPayload,
 } from '../../WebMsgCommand'
 
 export class SpatialEntity extends SpatialObject {
@@ -118,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/runtime/capability-data.ts

@@ -1,6 +1,6 @@
 /**
  * Versioned capability rows transcribed from the product matrix (`capability-matrix.template.md`).
- * visionOS **WSAppShell/1.5.0** & **1.6.0**; picoOS **PicoWebApp/0.1.1** & **0.1.2** — see matrix in OpenSpec / product docs.
+ * visionOS **WSAppShell/1.5.0** & **1.6.0** & **1.7.0** & **1.8.0**; picoOS **PicoWebApp/0.1.1** & **0.1.2** & **0.2.2** & **0.3.1** & **0.4.90** — see matrix in OpenSpec / product docs.
  *
  * **picoOS** rows use dedicated builders (alpha2.0 / alpha2.1 subtokens); visionOS rows are separate.
  */
@@ -50,6 +50,11 @@ function matrixVision_1_5_0_Flags(): Record<string, boolean> {
     flags[`Model:${t}`] = false
   }
   flags['SpatialRotateEvent:constrainedToAxis'] = true
+  // Container useAnimation is not supported until WSAppShell/1.8.0.
+  flags['useAnimation'] = false
+  // Placement-shaped attachment protocol lands in picoOS PicoWebApp/0.4.90
+  // (OTA0); no visionOS shell decodes it yet.
+  flags['AttachmentEntity:placement'] = false
   return flags
 }
 
@@ -63,6 +68,32 @@ function matrixVision_1_6_0_Flags(): Record<string, boolean> {
     flags[`Model:${t}`] = false
   }
   flags['SpatialRotateEvent:constrainedToAxis'] = true
+  // Container useAnimation is not supported until WSAppShell/1.8.0.
+  flags['useAnimation'] = false
+  // Placement-shaped attachment protocol lands in picoOS PicoWebApp/0.4.90
+  // (OTA0); no visionOS shell decodes it yet.
+  flags['AttachmentEntity:placement'] = false
+  return flags
+}
+
+/**
+ * visionOS **WSAppShell/1.7.0** — entity transform animation support.
+ * Container `useAnimation` remains unavailable in this row.
+ */
+function matrixVision_1_7_0_Flags(): Record<string, boolean> {
+  const flags = matrixVision_1_6_0_Flags()
+  flags['Model:currentTime'] = true
+  flags['Model:loading'] = true
+  flags['Model:poster'] = true
+  return flags
+}
+
+/**
+ * visionOS **WSAppShell/1.8.0**.
+ */
+function matrixVision_1_8_0_Flags(): Record<string, boolean> {
+  const flags = matrixVision_1_7_0_Flags()
+  flags['useAnimation'] = true
   return flags
 }
 
@@ -78,13 +109,43 @@ function matrixPico_0_1_1_Flags(): Record<string, boolean> {
 }
 
 /**
- * picoOS **PicoWebApp/0.1.2** — alpha2.1 playback expansion (product matrix).
+ * picoOS **PicoWebApp/0.1.2** — beta2.0 playback expansion (product matrix).
  * **`xrInnerDepth` / `xrOuterDepth` N** (same as 0.1.1).
  */
 function matrixPico_0_1_2_Flags(): Record<string, boolean> {
   const flags = matrixVision_1_6_0_Flags()
   flags.xrInnerDepth = false
   flags.xrOuterDepth = false
+  flags['Model:currentTime'] = true
+  flags['Model:poster'] = true
+  return flags
+}
+
+/**
+ * picoOS **PicoWebApp/0.2.2** — entity transform animation support.
+ * Container `useAnimation` remains unavailable in this row.
+ */
+function matrixPico_0_2_2_Flags(): Record<string, boolean> {
+  const flags = matrixPico_0_1_2_Flags()
+  return flags
+}
+
+/**
+ * picoOS **PicoWebApp/0.3.1** — beta2.1
+ */
+function matrixPico_0_3_1_Flags(): Record<string, boolean> {
+  const flags = matrixPico_0_2_2_Flags()
+  flags['Model:loading'] = true
+  return flags
+}
+
+/**
+ * picoOS **PicoWebApp/0.4.90** — OTA0 container animation support.
+ */
+function matrixPico_0_4_90_Flags(): Record<string, boolean> {
+  const flags = matrixPico_0_3_1_Flags()
+  flags['useAnimation'] = true
+  flags['AttachmentEntity:placement'] = true
   return flags
 }
 
@@ -96,18 +157,57 @@ function visionOsRow_1_6_0(): CapabilityVersionRow {
   return { version: '1.6.0', flags: matrixVision_1_6_0_Flags() }
 }
 
+function visionOsRow_1_7_0(): CapabilityVersionRow {
+  return { version: '1.7.0', flags: matrixVision_1_7_0_Flags() }
+}
+
+/**
+ * Build the capability row for visionOS **WSAppShell/1.8.0**.
+ */
+function visionOsRow_1_8_0(): CapabilityVersionRow {
+  return { version: '1.8.0', flags: matrixVision_1_8_0_Flags() }
+}
+
 function picoOsRow_0_1_1(): CapabilityVersionRow {
   return { version: '0.1.1', flags: matrixPico_0_1_1_Flags() }
 }
 
+// Pico OS 6.0 Beta 2.0
 function picoOsRow_0_1_2(): CapabilityVersionRow {
   return { version: '0.1.2', flags: matrixPico_0_1_2_Flags() }
 }
 
+function picoOsRow_0_2_2(): CapabilityVersionRow {
+  return { version: '0.2.2', flags: matrixPico_0_2_2_Flags() }
+}
+
+// Pico OS 6.0 Beta 2.1
+function picoOsRow_0_3_1(): CapabilityVersionRow {
+  return { version: '0.3.1', flags: matrixPico_0_3_1_Flags() }
+}
+
+/**
+ * Build the capability row for picoOS **PicoWebApp/0.4.90** OTA0.
+ */
+function picoOsRow_0_4_90(): CapabilityVersionRow {
+  return { version: '0.4.90', flags: matrixPico_0_4_90_Flags() }
+}
+
 export const CAPABILITY_TABLE: {
   visionos: CapabilityVersionRow[]
   picoos: CapabilityVersionRow[]
 } = {
-  visionos: [visionOsRow_1_5_0(), visionOsRow_1_6_0()],
-  picoos: [picoOsRow_0_1_1(), picoOsRow_0_1_2()],
+  visionos: [
+    visionOsRow_1_5_0(),
+    visionOsRow_1_6_0(),
+    visionOsRow_1_7_0(),
+    visionOsRow_1_8_0(),
+  ],
+  picoos: [
+    picoOsRow_0_1_1(),
+    picoOsRow_0_1_2(),
+    picoOsRow_0_2_2(),
+    picoOsRow_0_3_1(),
+    picoOsRow_0_4_90(),
+  ],
 }

package/src/runtime/index.ts

@@ -15,14 +15,3 @@ export {
 export type { CapabilityVersionRow } from './capability-data'
 export { CAPABILITY_TABLE } from './capability-data'
 export type { CapabilityKey } from './keys'
-export {
-  TOP_LEVEL_KEYS,
-  SUB_TOKENS_BY_NAME,
-  COMPONENT_KEYS,
-  CSS_KEYS,
-  GESTURE_KEYS,
-  JS_SCENE_KEYS,
-  DOM_DEPTH_KEYS,
-  ELEMENT_DOM_DEPTH_KEYS,
-  WINDOW_DOM_DEPTH_KEYS,
-} from './keys'

package/src/runtime/keys.ts

@@ -1,6 +1,10 @@
 /**
- * Canonical `supports(name)` keys (OpenSpec `review.md` §3).
+ * Canonical `supports(name)` key registry (OpenSpec `review.md` §3).
  * Aliases are normalized before lookup (see `normalizeCapabilityName`).
+ *
+ * @internal SDK contract data — not part of the public `@webspatial/react-sdk`
+ * surface. Import via `@webspatial/core-sdk/runtime/keys` only for SDK demos,
+ * contract tests, and capability-matrix tooling.
  */
 
 export const COMPONENT_KEYS = [
@@ -39,6 +43,8 @@ export const GESTURE_KEYS = [
   'SpatialMagnifyEndEvent',
 ] as const
 
+export const ANIMATION_KEYS = ['useAnimation'] as const
+
 export const JS_SCENE_KEYS = [
   'useMetrics',
   'convertCoordinate',
@@ -68,6 +74,7 @@ export const TOP_LEVEL_KEYS = [
   ...COMPONENT_KEYS,
   ...CSS_KEYS,
   ...GESTURE_KEYS,
+  ...ANIMATION_KEYS,
   ...JS_SCENE_KEYS,
   ...DOM_DEPTH_KEYS,
 ] as const
@@ -100,6 +107,10 @@ export const SUB_TOKENS_BY_NAME: Readonly<Record<string, readonly string[]>> = {
     'baseplateVisibility',
   ],
   SpatialRotateEvent: ['constrainedToAxis'],
+  // Placement-shaped attachment JSB protocol (placementId + Vec3 transform +
+  // meter width/height). Runtimes without it take the legacy payload
+  // (parentEntityId + tuple position + point size).
+  AttachmentEntity: ['placement'],
   Model: [
     'autoplay',
     'loop',