@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/JSBCommand.ts

@@ -1,5 +1,10 @@
-import { createPlatform } from './platform-adapter'
-import { WebSpatialProtocolResult } from './platform-adapter/interface'
+import { getPlatform } from './platform-runtime'
+import { pointToPhysical } from './physicalMetrics'
+import {
+  getRuntime,
+  supports,
+  VISIONOS_DEBUG_SHELL_VERSION_PLACEHOLDER,
+} from './runtime/supports'
 import { SpatialComponent } from './reality/component/SpatialComponent'
 import { SpatialEntity } from './reality/entity/SpatialEntity'
 import { SpatialMaterial } from './reality/material/SpatialMaterial'
@@ -24,12 +29,16 @@ import {
   Vec3,
   AttachmentEntityOptions,
   AttachmentEntityUpdateOptions,
+  ModelLoadingMode,
   ModelSource,
+  SpatialTextureResourceOptions,
 } from './types/types'
-import { SpatialSceneCreationOptionsInternal } from './types/internal'
+import type { AnimateTransformCommand } from './types/animation'
 import { composeSRT } from './utils'
-
-const platform = createPlatform()
+import type {
+  ControlSpatializedElementAnimationCommand,
+  CreateSpatializedElementAnimationCommand,
+} from './types/motion/spatializedElementMotion'
 
 abstract class JSBCommand {
   commandType: string = ''
@@ -38,6 +47,7 @@ abstract class JSBCommand {
   async execute() {
     const param = this.getParams()
     const msg = param ? JSON.stringify(param) : ''
+    const platform = await getPlatform()
     return platform.callJSB(this.commandType, msg)
   }
 }
@@ -293,14 +303,20 @@ export class CreateSpatializedStatic3DElementCommand extends JSBCommand {
   constructor(
     readonly modelURL?: string,
     readonly sources?: ModelSource[],
+    readonly loading: ModelLoadingMode = 'eager',
   ) {
     super()
     this.modelURL = modelURL
     this.sources = sources
+    this.loading = loading
   }
 
   protected getParams() {
-    return { modelURL: this.modelURL, sources: this.sources }
+    return {
+      modelURL: this.modelURL,
+      sources: this.sources,
+      loading: this.loading,
+    }
   }
 }
 
@@ -558,7 +574,7 @@ export class ConvertCoordinateCommand extends JSBCommand {
   commandType = 'ConvertCoordinate'
 }
 
-export class CreateTextureResourceCommand extends JSBCommand {
+export class CreateTextureCommand extends JSBCommand {
   constructor(private url: string) {
     super()
   }
@@ -567,7 +583,24 @@ export class CreateTextureResourceCommand extends JSBCommand {
       url: this.url,
     }
   }
-  commandType = 'CreateTextureResource'
+  commandType = 'CreateTexture'
+}
+
+export class UpdateTexturePropertiesCommand extends SpatializedElementCommand {
+  properties: Partial<SpatialTextureResourceOptions>
+  commandType = 'UpdateTextureProperties'
+
+  constructor(
+    spatialObject: SpatialObject,
+    properties: Partial<SpatialTextureResourceOptions>,
+  ) {
+    super(spatialObject)
+    this.properties = properties
+  }
+
+  protected getExtraParams() {
+    return this.properties
+  }
 }
 
 export class InspectCommand extends JSBCommand {
@@ -606,86 +639,62 @@ export class CheckWebViewCanCreateCommand extends JSBCommand {
   }
 }
 
-/* WebSpatial Protocol Begin */
-abstract class WebSpatialProtocolCommand extends JSBCommand {
-  target?: string
-  features?: string
-
-  async execute(): Promise<WebSpatialProtocolResult> {
-    const query = this.getQuery()
-    return platform.callWebSpatialProtocol(
-      this.commandType,
-      query,
-      this.target,
-      this.features,
-    )
-  }
-
-  executeSync(): WebSpatialProtocolResult {
-    const query = this.getQuery()
-    return platform.callWebSpatialProtocolSync(
-      this.commandType,
-      query,
-      this.target,
-      this.features,
-    )
-  }
-
-  private getQuery() {
-    let query = undefined
-    const params = this.getParams()
-    if (params) {
-      query = Object.keys(params)
-        .map(key => {
-          const value = params[key]
-          const finalValue =
-            typeof value === 'object' ? JSON.stringify(value) : value
-          return `${key}=${encodeURIComponent(finalValue)}`
-        })
-        .join('&')
-    }
-
-    return query
-  }
-}
+export class AnimateTransformJSBCommand extends JSBCommand {
+  commandType = 'AnimateTransform'
 
-export class createSpatialized2DElementCommand extends WebSpatialProtocolCommand {
-  commandType = 'createSpatialized2DElement'
-  constructor() {
+  constructor(private command: AnimateTransformCommand) {
     super()
   }
-  protected getParams() {
-    return {}
-  }
-}
 
-export class createSpatialSceneCommand extends WebSpatialProtocolCommand {
-  commandType = 'createSpatialScene'
+  protected getParams(): Record<string, any> | undefined {
+    const { type, animationId, entityId } = this.command
+    const params: Record<string, any> = { type, animationId }
+
+    if (entityId !== undefined) params.entityId = entityId
+
+    if (type === 'play') {
+      if (this.command.toTransform) {
+        params.toTransform = Array.from(this.command.toTransform)
+      }
+      if (this.command.fromTransform) {
+        params.fromTransform = Array.from(this.command.fromTransform)
+      }
+      if (this.command.duration !== undefined)
+        params.duration = this.command.duration
+      if (this.command.timingFunction !== undefined)
+        params.timingFunction = this.command.timingFunction
+      if (this.command.delay !== undefined) params.delay = this.command.delay
+      if (this.command.loop !== undefined) params.loop = this.command.loop
+      if (this.command.playbackRate !== undefined)
+        params.playbackRate = this.command.playbackRate
+    }
 
-  constructor(
-    private url: string,
-    private config: SpatialSceneCreationOptionsInternal | undefined,
-    public target?: string,
-    public features?: string,
-  ) {
-    super()
+    return params
   }
-  protected getParams() {
-    return {
-      url: this.url,
-      config: this.config,
-    }
+}
+// TODO(remove): temporary OTA0 compat shim — delete once #1330 lands and
+// attachment JSB always uses the placement-shaped payload.
+function usePlacementProtocol(): boolean {
+  // WS_SHELL_VERSION debug shells claim every capability via supports(), but
+  // the in-repo visionOS runtime still decodes only the legacy attachment
+  // payload — keep sending it there.
+  const rt = getRuntime()
+  if (
+    rt.type === 'visionos' &&
+    rt.shellVersion === VISIONOS_DEBUG_SHELL_VERSION_PLACEHOLDER
+  ) {
+    return false
   }
+  return supports('AttachmentEntity', ['placement'])
 }
 
-export class CreateAttachmentEntityCommand extends WebSpatialProtocolCommand {
-  commandType = 'createAttachment'
-  constructor(private options: AttachmentEntityOptions) {
-    super()
-  }
-  protected getParams() {
-    return {} // No metadata — just trigger engine/webview creation
-  }
+function toPlacementVec3(position?: [number, number, number]): {
+  x: number
+  y: number
+  z: number
+} {
+  const [x, y, z] = position ?? [0, 0, 0]
+  return { x, y, z }
 }
 
 export class InitializeAttachmentCommand extends JSBCommand {
@@ -697,12 +706,25 @@ export class InitializeAttachmentCommand extends JSBCommand {
     super()
   }
   protected getParams() {
+    const p = this.options
+    if (!usePlacementProtocol()) {
+      return {
+        id: this.attachmentId,
+        parentEntityId: p.parentEntityId,
+        position: p.position ?? [0, 0, 0],
+        size: p.size,
+        ownerViewId: p.ownerViewId,
+      }
+    }
+    // Runtimes advertising this capability decode a Vec3 position and meter
+    // dimensions instead of the legacy tuple and point size.
     return {
       id: this.attachmentId,
-      parentEntityId: this.options.parentEntityId,
-      position: this.options.position ?? [0, 0, 0],
-      size: this.options.size,
-      ownerViewId: this.options.ownerViewId,
+      placementId: p.parentEntityId,
+      position: toPlacementVec3(p.position),
+      width: pointToPhysical(p.size.width),
+      height: pointToPhysical(p.size.height),
+      ownerViewId: p.ownerViewId,
     }
   }
 }
@@ -716,19 +738,54 @@ export class UpdateAttachmentEntityCommand extends JSBCommand {
     super()
   }
   protected getParams() {
+    if (!usePlacementProtocol()) {
+      return {
+        id: this.attachmentId,
+        ...this.options,
+      }
+    }
+    const { position, size } = this.options
     return {
       id: this.attachmentId,
-      ...this.options,
+      ...(position ? { position: toPlacementVec3(position) } : {}),
+      ...(size
+        ? {
+            width: pointToPhysical(size.width),
+            height: pointToPhysical(size.height),
+          }
+        : {}),
     }
   }
 }
 
-// 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 => {
-    const r = (Math.random() * 16) | 0
-    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16)
-  })
+export class CreateSpatializedElementAnimationJSBCommand extends JSBCommand {
+  commandType = 'CreateSpatializedElementAnimation'
+
+  constructor(private command: CreateSpatializedElementAnimationCommand) {
+    super()
+  }
+
+  protected getParams() {
+    const { elementId, timeline } = this.command
+    return {
+      elementId,
+      timeline,
+    }
+  }
 }
 
-/* WebSpatial Protocol End */
+export class ControlSpatializedElementAnimationJSBCommand extends JSBCommand {
+  commandType = 'ControlSpatializedElementAnimation'
+
+  constructor(private command: ControlSpatializedElementAnimationCommand) {
+    super()
+  }
+
+  protected getParams() {
+    const { animationId, type } = this.command
+    return {
+      animationId,
+      type,
+    }
+  }
+}

package/src/Spatial.ts

@@ -6,8 +6,6 @@ import { SpatialWebEvent } from './SpatialWebEvent'
  * This is the main entry point for the WebSpatial SDK, providing access to spatial capabilities.
  */
 export class Spatial {
-  private wsAppShellVersionFromUA: string | null | undefined
-
   /**
    * Requests a spatial session object from the browser.
    * This is the primary method to initialize spatial functionality.
@@ -35,25 +33,6 @@ export class Spatial {
     return false
   }
 
-  getShellVersionFromUA(): string | null {
-    if (this.wsAppShellVersionFromUA !== undefined) {
-      return this.wsAppShellVersionFromUA
-    }
-    if (
-      typeof navigator === 'undefined' ||
-      typeof navigator.userAgent !== 'string'
-    ) {
-      this.wsAppShellVersionFromUA = null
-      return null
-    }
-
-    const match = navigator.userAgent.match(
-      /WSAppShell\/(\d+(?:\.\d+){2}(?:[-+][0-9A-Za-z.-]+)*)/,
-    )
-    this.wsAppShellVersionFromUA = match ? match[1] : '1.3.0'
-    return this.wsAppShellVersionFromUA
-  }
-
   /** @deprecated
    * Checks if WebSpatial is supported in the current environment.
    * Verifies compatibility between native and client versions.

package/src/SpatialObject.ts

@@ -38,6 +38,16 @@ export class SpatialObject {
       return
     }
 
+    const errorMessage =
+      typeof ret.errorMessage === 'string' ? ret.errorMessage.toLowerCase() : ''
+    const isMissingNativeObject = errorMessage.includes('not exsit')
+    if (isMissingNativeObject) {
+      // Treat native pre-teardown as an idempotent destroy during page back navigation.
+      this.onDestroy()
+      this.isDestroyed = true
+      return
+    }
+
     throw new Error(ret.errorMessage)
   }
 

package/src/SpatialScene.ts

@@ -1,8 +1,4 @@
-import {
-  SpatialSceneCreationOptions,
-  SpatialSceneProperties,
-  Vec3,
-} from './types/types'
+import { SpatialSceneProperties, Vec3 } from './types/types'
 import { SpatialSceneCreationOptionsInternal } from './types/internal'
 import {
   AddSpatializedElementToSpatialScene,

package/src/SpatialSession.ts

@@ -14,14 +14,14 @@ import {
   SpatialBoxGeometryOptions,
   SpatialConeGeometryOptions,
   SpatialCylinderGeometryOptions,
-  SpatialGeometryOptions,
   SpatialModelEntityCreationOptions,
   SpatialPlaneGeometryOptions,
-  SpatialSceneCreationOptions,
   SpatialSphereGeometryOptions,
   SpatialUnlitMaterialOptions,
+  SpatialTextureResourceOptions,
   SpatialEntityUserData,
   AttachmentEntityOptions,
+  ModelLoadingMode,
   ModelSource,
 } from './types/types'
 import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
@@ -32,6 +32,7 @@ import {
   createSpatialEntity,
   createSpatialGeometry,
   createSpatialModelEntity,
+  createSpatialTexture,
   createSpatialUnlitMaterial,
 } from './reality/realityCreator'
 import {
@@ -70,13 +71,16 @@ export class SpatialSession {
    * Creates a new static 3D element with an optional model URL.
    * Static 3D elements represent pre-built 3D models that can be loaded from a URL.
    * @param modelURL Optional URL to the 3D model to load
+   * @param sources Optional list of fallback model sources
+   * @param loading Whether the asset should fetch eagerly or be deferred (`'lazy'`)
    * @returns Promise resolving to a new SpatializedStatic3DElement instance
    */
   createSpatializedStatic3DElement(
     modelURL?: string,
     sources?: ModelSource[],
+    loading: ModelLoadingMode = 'eager',
   ): Promise<SpatializedStatic3DElement> {
-    return createSpatializedStatic3DElement(modelURL, sources)
+    return createSpatializedStatic3DElement(modelURL, sources, loading)
   }
 
   /**
@@ -169,6 +173,16 @@ export class SpatialSession {
     return createSpatialUnlitMaterial(options)
   }
 
+  /**
+   * Creates a texture resource from the specified image URL.
+   * Texture resources can be referenced by materials and other spatial content.
+   * @param options Configuration options for the texture resource
+   * @returns Promise resolving to a new SpatialTextureResource instance
+   */
+  createTexture(options: SpatialTextureResourceOptions) {
+    return createSpatialTexture(options)
+  }
+
   /**
    * Creates a model asset with the specified configuration.
    * Model assets represent 3D model resources that can be used by entities.

package/src/Spatialized2DElement.ts

@@ -12,6 +12,11 @@ import { Spatialized2DElementProperties } from './types/types'
  * allowing HTML elements to be positioned and interacted with in spatial applications.
  */
 export class Spatialized2DElement extends SpatializedElement {
+  /**
+   * Identifies the motion target kind supported by this element.
+   */
+  override readonly kind = 'spatialized2d' as const
+
   /**
    * Creates a new spatialized 2D element.
    * @param id Unique identifier for this element

package/src/SpatializedDynamic3DElement.ts

@@ -1,5 +1,4 @@
 import {
-  AddEntityToDynamic3DCommand,
   SetParentForEntityCommand,
   UpdateSpatializedDynamic3DElementProperties,
 } from './JSBCommand'
@@ -12,6 +11,11 @@ import {
 } from './types/types'
 
 export class SpatializedDynamic3DElement extends SpatializedElement {
+  /**
+   * Identifies the motion target kind supported by this element.
+   */
+  override readonly kind = 'dynamic3d' as const
+
   children: SpatialEntityOrReality[] = []
   events: Record<string, (data: any) => void> = {}
 

package/src/SpatializedElement.ts

@@ -1,8 +1,14 @@
 import { UpdateSpatializedElementTransform } from './JSBCommand'
+import { AnimationObject } from './motion/AnimationObject'
 import { WebSpatialProtocolResult } from './platform-adapter/interface'
 import { SpatialObject } from './SpatialObject'
 import { SpatialWebEvent } from './SpatialWebEvent'
 import { createSpatialEvent } from './SpatialWebEventCreator'
+import {
+  normalizeMotionConfig,
+  validateNormalizedMotionConfig,
+} from './motion/compute'
+import { motionConfigToNativeTimeline } from './motion/native/serializeMotionTimeline'
 import {
   CubeInfo,
   SpatialDragEndEvent,
@@ -27,6 +33,10 @@ import {
   SpatialTapMsg,
   SpatialWebMsgType,
 } from './WebMsgCommand'
+import type {
+  SpatializedMotionConfig,
+  SpatializedMotionKind,
+} from './types/motion/spatializedMotion'
 
 /**
  * Abstract base class for all spatialized elements in the WebSpatial environment.
@@ -34,6 +44,11 @@ import {
  * including transformation handling and gesture event processing.
  */
 export abstract class SpatializedElement extends SpatialObject {
+  /**
+   * Identifies the motion target kind supported by this spatialized element.
+   */
+  abstract readonly kind: SpatializedMotionKind
+
   /**
    * Creates a new spatialized element with the specified ID.
    * Registers the element to receive spatial events.
@@ -55,6 +70,20 @@ export abstract class SpatializedElement extends SpatialObject {
     properties: Partial<SpatializedElementProperties>,
   ): Promise<WebSpatialProtocolResult>
 
+  /**
+   * Creates a native-first AnimationObject bound to this spatialized element.
+   */
+  async createAnimation(
+    config: SpatializedMotionConfig,
+  ): Promise<AnimationObject> {
+    const normalized = normalizeMotionConfig(config)
+    validateNormalizedMotionConfig(normalized)
+    return AnimationObject.create({
+      elementId: this.id,
+      timeline: motionConfigToNativeTimeline(normalized),
+    })
+  }
+
   /**
    * Updates the transformation matrix of this element in 3D space.
    * This affects the position, rotation, and scale of the element.

package/src/SpatializedElementCreator.ts

@@ -1,15 +1,15 @@
 import {
-  createSpatialized2DElementCommand,
   CreateSpatializedDynamic3DElementCommand,
   CreateSpatializedStatic3DElementCommand,
 } from './JSBCommand'
 import { Spatialized2DElement } from './Spatialized2DElement'
 import { SpatializedStatic3DElement } from './SpatializedStatic3DElement'
 import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
-import { ModelSource } from './types/types'
+import { createNativeSpatialDiv } from './spatial-host'
+import { ModelLoadingMode, ModelSource } from './types/types'
 
 export async function createSpatialized2DElement(): Promise<Spatialized2DElement> {
-  const result = await new createSpatialized2DElementCommand().execute()
+  const result = await createNativeSpatialDiv()
   if (!result.success) {
     throw new Error('createSpatialized2DElement failed')
   } else {
@@ -24,16 +24,18 @@ export async function createSpatialized2DElement(): Promise<Spatialized2DElement
 export async function createSpatializedStatic3DElement(
   modelURL?: string,
   sources?: ModelSource[],
+  loading: ModelLoadingMode = 'eager',
 ): Promise<SpatializedStatic3DElement> {
   const result = await new CreateSpatializedStatic3DElementCommand(
     modelURL,
     sources,
+    loading,
   ).execute()
   if (!result.success) {
     throw new Error('createSpatializedStatic3DElement failed')
   } else {
     const { id } = result.data
-    return new SpatializedStatic3DElement(id, modelURL, sources)
+    return new SpatializedStatic3DElement(id, modelURL, sources, loading)
   }
 }
 

package/src/SpatializedStatic3DElement.test.ts

@@ -136,4 +136,103 @@ describe('SpatializedStatic3DElement', () => {
     el.onReceiveEvent({ type: SpatialWebMsgType.modelloaded })
     await expect(p3).resolves.toBe(true)
   })
+
+  it('currentTime defaults to 0 before any sample', () => {
+    const el = new SpatializedStatic3DElement('ct1', 'a.glb')
+    expect(el.currentTime).toBe(0)
+  })
+
+  it('currentTime returns the anchor while paused', () => {
+    const el = new SpatializedStatic3DElement('ct2', 'a.glb')
+    el.onReceiveEvent({
+      type: SpatialWebMsgType.animationstatechange,
+      detail: {
+        paused: true,
+        duration: 10,
+        currentTime: 4,
+        timestamp: Date.now(),
+      },
+    })
+    expect(el.currentTime).toBe(4)
+  })
+
+  it('currentTime extrapolates while playing using playbackRate', () => {
+    const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(1_000)
+    const el = new SpatializedStatic3DElement('ct3', 'a.glb')
+    el.onReceiveEvent({
+      type: SpatialWebMsgType.animationstatechange,
+      detail: {
+        paused: false,
+        duration: 10,
+        currentTime: 2,
+        timestamp: 1_000,
+      },
+    })
+    nowSpy.mockReturnValue(2_000) // +1s real time
+    // default rate 1 → +1s animation time
+    expect(el.currentTime).toBe(3)
+    nowSpy.mockRestore()
+  })
+
+  it('currentTime clamps extrapolation to duration', () => {
+    const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(1_000)
+    const el = new SpatializedStatic3DElement('ct4', 'a.glb')
+    el.onReceiveEvent({
+      type: SpatialWebMsgType.animationstatechange,
+      detail: {
+        paused: false,
+        duration: 5,
+        currentTime: 4,
+        timestamp: 1_000,
+      },
+    })
+    nowSpy.mockReturnValue(11_000) // +10s real time → would extrapolate to 14
+    expect(el.currentTime).toBe(5)
+    nowSpy.mockRestore()
+  })
+
+  it('setting currentTime optimistically updates the anchor', async () => {
+    const el = new SpatializedStatic3DElement('ct5', 'a.glb')
+    el.onReceiveEvent({
+      type: SpatialWebMsgType.animationstatechange,
+      detail: {
+        paused: true,
+        duration: 10,
+        currentTime: 0,
+        timestamp: Date.now(),
+      },
+    })
+    el.currentTime = 7
+    expect(el.currentTime).toBe(7)
+  })
+
+  it('setting currentTime clamps negative values to 0', async () => {
+    const el = new SpatializedStatic3DElement('ct6', 'a.glb')
+    el.onReceiveEvent({
+      type: SpatialWebMsgType.animationstatechange,
+      detail: {
+        paused: true,
+        duration: 10,
+        currentTime: 5,
+        timestamp: Date.now(),
+      },
+    })
+    el.currentTime = -3
+    expect(el.currentTime).toBe(0)
+  })
+
+  it('setting currentTime clamps values above duration', async () => {
+    const el = new SpatializedStatic3DElement('ct7', 'a.glb')
+    el.onReceiveEvent({
+      type: SpatialWebMsgType.animationstatechange,
+      detail: {
+        paused: true,
+        duration: 8,
+        currentTime: 0,
+        timestamp: Date.now(),
+      },
+    })
+    el.currentTime = 100
+    expect(el.currentTime).toBe(8)
+  })
 })