@webspatial/core-sdk 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webspatial/core-sdk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "this is the core js API for webspatial",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/JSBCommand.ts

@@ -1,5 +1,4 @@
-import { createPlatform } from './platform-adapter'
-import { WebSpatialProtocolResult } from './platform-adapter/interface'
+import { getPlatform } from './platform-runtime'
 import { SpatialComponent } from './reality/component/SpatialComponent'
 import { SpatialEntity } from './reality/entity/SpatialEntity'
 import { SpatialMaterial } from './reality/material/SpatialMaterial'
@@ -24,13 +23,12 @@ import {
   Vec3,
   AttachmentEntityOptions,
   AttachmentEntityUpdateOptions,
+  ModelLoadingMode,
   ModelSource,
+  SpatialTextureResourceOptions,
 } from './types/types'
-import { SpatialSceneCreationOptionsInternal } from './types/internal'
 import { composeSRT } from './utils'
 
-const platform = createPlatform()
-
 abstract class JSBCommand {
   commandType: string = ''
   protected abstract getParams(): Record<string, any> | undefined
@@ -38,6 +36,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 +292,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 +563,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 +572,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,88 +628,6 @@ 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 createSpatialized2DElementCommand extends WebSpatialProtocolCommand {
-  commandType = 'createSpatialized2DElement'
-  constructor() {
-    super()
-  }
-  protected getParams() {
-    return {}
-  }
-}
-
-export class createSpatialSceneCommand extends WebSpatialProtocolCommand {
-  commandType = 'createSpatialScene'
-
-  constructor(
-    private url: string,
-    private config: SpatialSceneCreationOptionsInternal | undefined,
-    public target?: string,
-    public features?: string,
-  ) {
-    super()
-  }
-  protected getParams() {
-    return {
-      url: this.url,
-      config: this.config,
-    }
-  }
-}
-
-export class CreateAttachmentEntityCommand extends WebSpatialProtocolCommand {
-  commandType = 'createAttachment'
-  constructor(private options: AttachmentEntityOptions) {
-    super()
-  }
-  protected getParams() {
-    return {} // No metadata — just trigger engine/webview creation
-  }
-}
-
 export class InitializeAttachmentCommand extends JSBCommand {
   commandType = 'InitializeAttachment'
   constructor(
@@ -722,13 +662,3 @@ export class UpdateAttachmentEntityCommand extends JSBCommand {
     }
   }
 }
-
-// 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)
-  })
-}
-
-/* WebSpatial Protocol End */

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/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/SpatializedDynamic3DElement.ts

@@ -1,5 +1,4 @@
 import {
-  AddEntityToDynamic3DCommand,
   SetParentForEntityCommand,
   UpdateSpatializedDynamic3DElementProperties,
 } from './JSBCommand'

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

package/src/SpatializedStatic3DElement.ts

@@ -1,6 +1,7 @@
 import { UpdateSpatializedStatic3DElementProperties } from './JSBCommand'
 import { ReceiveEventData, SpatializedElement } from './SpatializedElement'
 import {
+  ModelLoadingMode,
   ModelSource,
   SpatializedStatic3DElementProperties,
 } from './types/types'
@@ -24,11 +25,18 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * @param id Unique identifier for this element
    * @param modelURL URL of the 3D model
    * @param sources Optional fallback model sources
+   * @param loading Initial loading mode (`'eager'` by default)
    */
-  constructor(id: string, modelURL?: string, sources?: ModelSource[]) {
+  constructor(
+    id: string,
+    modelURL?: string,
+    sources?: ModelSource[],
+    loading: ModelLoadingMode = 'eager',
+  ) {
     super(id)
     this.modelURL = modelURL
     this.sources = sources
+    this._loading = loading
   }
 
   /**
@@ -42,6 +50,10 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * Used to reset the ready promise when the model URL changes.
    */
   private modelURL?: string
+  // @TODO: Deprecate modelURL property from Web and Swift code
+  get modelUrl(): string | undefined {
+    return this.modelURL
+  }
 
   /**
    * Caches the last sources array to detect changes.
@@ -109,8 +121,23 @@ export class SpatializedStatic3DElement extends SpatializedElement {
       this._loop = properties.loop
     }
     if (properties.playbackRate !== undefined) {
+      // Re-anchor so extrapolation uses the new rate only for future elapsed
+      // time, not the window between the last sample and this change.
+      if (!this._paused) {
+        this._currentTime = this.currentTime
+        this._anchorTimestamp = Date.now()
+      }
       this._playbackRate = properties.playbackRate
     }
+    if (properties.currentTime !== undefined) {
+      // Optimistically update the local anchor so subsequent reads reflect
+      // the requested seek without waiting for the next native sample.
+      this._currentTime = properties.currentTime
+      this._anchorTimestamp = Date.now()
+    }
+    if (properties.loading !== undefined) {
+      this._loading = properties.loading
+    }
     return new UpdateSpatializedStatic3DElementProperties(
       this,
       properties,
@@ -148,6 +175,49 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     this.updateProperties({ playbackRate: value })
   }
 
+  /**
+   * Last playback position sampled from native (seconds).
+   */
+  private _currentTime: number = 0
+
+  /**
+   * Unix epoch time (ms) corresponding to `_currentTime`. Sourced from the
+   * native `timestamp` on samples, or `Date.now()` on local seeks/transitions.
+   */
+  private _anchorTimestamp: number = 0
+
+  private clampTime(time: number): number {
+    if (!Number.isFinite(time) || time < 0) return 0
+    // When looping the current time is modulo the duration
+    if (time > this._duration) {
+      return this.loop && this.duration > 0
+        ? time % this._duration
+        : this.duration
+    }
+    return time
+  }
+
+  /**
+   * Returns the current (un-scaled) playback position in seconds. While
+   * playing, the value is extrapolated from the last anchor using
+   * `playbackRate` and clamped to `[0, duration]`; while paused it returns
+   * the anchor directly.
+   */
+  get currentTime(): number {
+    if (this._paused) return this._currentTime
+    const elapsed = (Date.now() - this._anchorTimestamp) / 1000
+    return this.clampTime(this._currentTime + elapsed * this._playbackRate)
+  }
+
+  /**
+   * Seeks the animation to `value` seconds (clamped to `[0, duration]`) and
+   * forwards the request to native.
+   */
+  set currentTime(value: number) {
+    const time = Number.isNaN(value) ? 0 : clamp(value, 0, this.duration)
+    this.updateProperties({ currentTime: time })
+  }
+
   /**
    * Whether the animation is currently paused.
    */
@@ -181,6 +251,10 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * @returns Promise resolving when the command is sent
    */
   async play(): Promise<void> {
+    if (this._paused) {
+      // Start extrapolating from the last known position on resume.
+      this._anchorTimestamp = Date.now()
+    }
     this._paused = false
     await this.updateProperties({ animationPaused: false })
   }
@@ -190,6 +264,12 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * @returns Promise resolving when the command is sent
    */
   async pause(): Promise<void> {
+    if (!this._paused) {
+      // Freeze the extrapolated position so reads remain stable until the
+      // next native sample arrives.
+      this._currentTime = this.currentTime
+      this._anchorTimestamp = Date.now()
+    }
     this._paused = true
     await this.updateProperties({ animationPaused: true })
   }
@@ -213,6 +293,9 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     } else if (data.type === SpatialWebMsgType.animationstatechange) {
       this._paused = data.detail.paused
       this._duration = data.detail.duration
+      // In unsupported environments currentTime is invalid
+      this._currentTime = data.detail.currentTime ?? 0
+      this._anchorTimestamp = data.detail.timestamp ?? Date.now()
       this._onAnimationStateChangeCallback?.(data.detail)
     } else {
       // Handle other spatial events using the base class implementation
@@ -232,6 +315,16 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     return this._autoplay
   }
 
+  /**
+   * Asset fetch policy. `'lazy'` defers fetching until the host signals the
+   * element is in view; `'eager'` fetches immediately.
+   */
+  private _loading: ModelLoadingMode = 'eager'
+
+  get loading(): ModelLoadingMode {
+    return this._loading
+  }
+
   /**
    * Whether the model animation should loop continuously.
    */
@@ -276,6 +369,11 @@ export class SpatializedStatic3DElement extends SpatializedElement {
   }
 }
 
+// Equivalent of proposed Math.clamp
+function clamp(num: number, min: number, max: number) {
+  return num <= min ? min : num >= max ? max : num
+}
+
 type Static3DReceiveEventData =
   | ModelLoadSuccess
   | ModelLoadFailure

package/src/WebMsgCommand.ts

@@ -81,6 +81,16 @@ export interface ModelLoadFailure {
 export interface AnimationStateChangeDetail {
   paused: boolean
   duration: number
+  /**
+   * Sampled animation playback position in seconds at `timestamp`.
+   * Optional for compatibility with older native runtimes.
+   */
+  currentTime?: number
+  /**
+   * Unix epoch time in milliseconds at which `currentTime` was sampled.
+   * Used to extrapolate `currentTime` between samples while playing.
+   */
+  timestamp?: number
 }
 
 export interface AnimationStateChangeMsg {