@webspatial/core-sdk 1.2.1 → 1.4.0

package/package.json

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

package/src/JSBCommand.ts

@@ -21,6 +21,8 @@ import {
   SpatialModelEntityCreationOptions,
   SpatialEntityEventType,
   Vec3,
+  AttachmentEntityOptions,
+  AttachmentEntityUpdateOptions,
 } from './types/types'
 import { SpatialSceneCreationOptionsInternal } from './types/internal'
 import { composeSRT } from './utils'
@@ -500,6 +502,24 @@ export class ConvertFromSceneToEntityCommand extends JSBCommand {
   commandType = 'ConvertFromSceneToEntity'
 }
 
+export class ConvertCoordinateCommand extends JSBCommand {
+  constructor(
+    public position: Vec3,
+    public fromId: string,
+    public toId: string,
+  ) {
+    super()
+  }
+  protected getParams(): Record<string, any> | undefined {
+    return {
+      position: this.position,
+      fromId: this.fromId,
+      toId: this.toId,
+    }
+  }
+  commandType = 'ConvertCoordinate'
+}
+
 export class CreateTextureResourceCommand extends JSBCommand {
   constructor(private url: string) {
     super()
@@ -620,6 +640,51 @@ export class createSpatialSceneCommand extends WebSpatialProtocolCommand {
   }
 }
 
+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(
+    private attachmentId: string,
+    private options: AttachmentEntityOptions,
+  ) {
+    super()
+  }
+  protected getParams() {
+    return {
+      id: this.attachmentId,
+      parentEntityId: this.options.parentEntityId,
+      position: this.options.position ?? [0, 0, 0],
+      size: this.options.size,
+      ownerViewId: this.options.ownerViewId,
+    }
+  }
+}
+
+export class UpdateAttachmentEntityCommand extends JSBCommand {
+  commandType = 'UpdateAttachmentEntity'
+  constructor(
+    private attachmentId: string,
+    private options: AttachmentEntityUpdateOptions,
+  ) {
+    super()
+  }
+  protected getParams() {
+    return {
+      id: this.attachmentId,
+      ...this.options,
+    }
+  }
+}
+
 // 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 => {

package/src/Spatial.ts

@@ -6,6 +6,8 @@ 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.
@@ -33,6 +35,25 @@ 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.
@@ -51,7 +72,7 @@ export class Spatial {
     if (window.__WebSpatialData && window.__WebSpatialData.getNativeVersion) {
       return window.__WebSpatialData.getNativeVersion()
     }
-    return window.WebSpatailNativeVersion === 'PACKAGE_VERSION'
+    return window.WebSpatailNativeVersion === 'WS_SHELL_VERSION'
       ? this.getClientVersion()
       : window.WebSpatailNativeVersion
   }

package/src/SpatialScene.ts

@@ -1,6 +1,7 @@
 import {
   SpatialSceneCreationOptions,
   SpatialSceneProperties,
+  Vec3,
 } from './types/types'
 import { SpatialSceneCreationOptionsInternal } from './types/internal'
 import {
@@ -9,6 +10,7 @@ import {
   UpdateSceneConfig,
   UpdateSpatialSceneProperties,
 } from './JSBCommand'
+import { ConvertCoordinateCommand } from './JSBCommand'
 
 import { SpatializedElement } from './SpatializedElement'
 import { SpatialObject } from './SpatialObject'
@@ -34,6 +36,24 @@ export class SpatialScene extends SpatialObject {
     return instance
   }
 
+  async convertCoordinate(
+    position: Vec3,
+    fromId: string,
+    toId: string,
+  ): Promise<Vec3> {
+    try {
+      const ret = await new ConvertCoordinateCommand(
+        position,
+        fromId,
+        toId,
+      ).execute()
+      return (ret as any)?.data ?? position
+    } catch (error) {
+      console.warn('SpatialScene.convertCoordinate error:', error)
+      throw error
+    }
+  }
+
   /**
    * Updates the properties of the spatial scene.
    * This can include background settings, lighting, and other scene-wide properties.

package/src/SpatialSession.ts

@@ -6,6 +6,7 @@ import {
   createSpatializedDynamic3DElement,
 } from './SpatializedElementCreator'
 import { createSpatializedStatic3DElement } from './SpatializedElementCreator'
+import { Attachment, createAttachmentEntity } from './reality/Attachment'
 import { SpatializedStatic3DElement } from './SpatializedStatic3DElement'
 import {
   ModelComponentOptions,
@@ -20,6 +21,7 @@ import {
   SpatialSphereGeometryOptions,
   SpatialUnlitMaterialOptions,
   SpatialEntityUserData,
+  AttachmentEntityOptions,
 } from './types/types'
 import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
 import { SpatialEntity } from './reality/entity/SpatialEntity'
@@ -70,7 +72,7 @@ export class SpatialSession {
    * @returns Promise resolving to a new SpatializedStatic3DElement instance
    */
   createSpatializedStatic3DElement(
-    modelURL: string = '',
+    modelURL: string,
   ): Promise<SpatializedStatic3DElement> {
     return createSpatializedStatic3DElement(modelURL)
   }
@@ -187,4 +189,16 @@ export class SpatialSession {
   ) {
     return createSpatialModelEntity(options, userData)
   }
+
+  /**
+   * Creates an attachment entity that renders 2D HTML content as a child
+   * of a 3D entity in the scene graph.
+   * @param options Configuration options including parent entity ID, position, and size
+   * @returns Promise resolving to a new Attachment instance
+   */
+  createAttachmentEntity(
+    options: AttachmentEntityOptions,
+  ): Promise<Attachment> {
+    return createAttachmentEntity(options)
+  }
 }

package/src/SpatializedDynamic3DElement.ts

@@ -6,11 +6,15 @@ import {
 import { SpatialEntity } from './reality'
 import { SpatializedElement } from './SpatializedElement'
 import {
+  SpatialEntityEventType,
   SpatialEntityOrReality,
   SpatializedElementProperties,
 } from './types/types'
+
 export class SpatializedDynamic3DElement extends SpatializedElement {
   children: SpatialEntityOrReality[] = []
+  events: Record<string, (data: any) => void> = {}
+
   constructor(id: string) {
     super(id)
   }
@@ -21,6 +25,21 @@ export class SpatializedDynamic3DElement extends SpatializedElement {
     entity.parent = this
     return ans
   }
+
+  addEvent(type: SpatialEntityEventType, callback: (data: any) => void) {
+    this.events[type] = callback
+  }
+
+  removeEvent(eventName: SpatialEntityEventType) {
+    if (this.events[eventName]) {
+      delete this.events[eventName]
+    }
+  }
+
+  dispatchEvent(evt: CustomEvent) {
+    this.events[evt.type]?.(evt)
+  }
+
   async updateProperties(properties: Partial<SpatializedElementProperties>) {
     return new UpdateSpatializedDynamic3DElementProperties(
       this,

package/src/SpatializedElement.ts

@@ -16,7 +16,6 @@ import {
   SpatialTapEvent,
 } from './types/types'
 import {
-  CubeInfoMsg,
   ObjectDestroyMsg,
   SpatialDragEndMsg,
   SpatialDragMsg,
@@ -27,7 +26,6 @@ import {
   SpatialRotateMsg,
   SpatialTapMsg,
   SpatialWebMsgType,
-  TransformMsg,
 } from './WebMsgCommand'
 
 /**
@@ -115,8 +113,6 @@ export abstract class SpatializedElement extends SpatialObject {
    */
   protected onReceiveEvent(
     data:
-      | CubeInfoMsg
-      | TransformMsg
       | SpatialTapMsg
       | SpatialDragStartMsg
       | SpatialDragMsg
@@ -128,31 +124,6 @@ export abstract class SpatializedElement extends SpatialObject {
     const { type } = data
     if (type === SpatialWebMsgType.objectdestroy) {
       this.isDestroyed = true
-    } else if (type === SpatialWebMsgType.cubeInfo) {
-      // Handle cube info updates (bounding box information)
-      const cubeInfoMsg = data as CubeInfoMsg
-      this._cubeInfo = new CubeInfo(cubeInfoMsg.size, cubeInfoMsg.origin)
-    } else if (type === SpatialWebMsgType.transform) {
-      // Handle transformation matrix updates
-      this._transform = new DOMMatrix([
-        data.detail.column0[0],
-        data.detail.column0[1],
-        data.detail.column0[2],
-        0,
-        data.detail.column1[0],
-        data.detail.column1[1],
-        data.detail.column1[2],
-        0,
-        data.detail.column2[0],
-        data.detail.column2[1],
-        data.detail.column2[2],
-        0,
-        data.detail.column3[0],
-        data.detail.column3[1],
-        data.detail.column3[2],
-        1,
-      ])
-      this._transformInv = this._transform.inverse()
     } else if (type === SpatialWebMsgType.spatialtap) {
       // Handle tap gestures
       const event = createSpatialEvent(

package/src/SpatializedElementCreator.ts

@@ -30,7 +30,7 @@ export async function createSpatializedStatic3DElement(
     throw new Error('createSpatializedStatic3DElement failed')
   } else {
     const { id } = result.data
-    return new SpatializedStatic3DElement(id)
+    return new SpatializedStatic3DElement(id, modelURL)
   }
 }
 

package/src/SpatializedStatic3DElement.test.ts

@@ -0,0 +1,125 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { SpatialWebMsgType } from './WebMsgCommand'
+import { SpatializedStatic3DElement } from './SpatializedStatic3DElement'
+
+// Single mock for the native bridge layer — everything else runs as-is
+vi.mock('./JSBCommand', () => {
+  class OkCommand {
+    execute() {
+      return Promise.resolve({
+        success: true,
+        data: undefined,
+        errorCode: '',
+        errorMessage: '',
+      })
+    }
+  }
+
+  return { UpdateSpatializedStatic3DElementProperties: OkCommand }
+})
+
+describe('SpatializedStatic3DElement', () => {
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('ready starts as a pending promise', () => {
+    const el = new SpatializedStatic3DElement('s1', 'model.glb')
+    expect(el.ready).toBeInstanceOf(Promise)
+  })
+
+  it('ready resolves to true on modelloaded event', async () => {
+    const el = new SpatializedStatic3DElement('s2', 'model.glb')
+    const p = el.ready
+
+    el.onReceiveEvent({ type: SpatialWebMsgType.modelloaded })
+    await expect(p).resolves.toBe(true)
+  })
+
+  it('ready resolves to false on modelloadfailed event', async () => {
+    const el = new SpatializedStatic3DElement('s3', 'model.glb')
+    const p = el.ready
+
+    el.onReceiveEvent({ type: SpatialWebMsgType.modelloadfailed })
+    await expect(p).resolves.toBe(false)
+  })
+
+  it('fires onLoadCallback on modelloaded', () => {
+    const el = new SpatializedStatic3DElement('s4', 'model.glb')
+    const cb = vi.fn()
+    el.onLoadCallback = cb
+
+    el.onReceiveEvent({ type: SpatialWebMsgType.modelloaded })
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+
+  it('fires onLoadFailureCallback on modelloadfailed', () => {
+    const el = new SpatializedStatic3DElement('s5', 'model.glb')
+    const cb = vi.fn()
+    el.onLoadFailureCallback = cb
+
+    el.onReceiveEvent({ type: SpatialWebMsgType.modelloadfailed })
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not fire callbacks when they are not set', () => {
+    const el = new SpatializedStatic3DElement('s6', 'model.glb')
+    // Should not throw when no callbacks are registered
+    expect(() =>
+      el.onReceiveEvent({ type: SpatialWebMsgType.modelloaded }),
+    ).not.toThrow()
+    expect(() =>
+      el.onReceiveEvent({ type: SpatialWebMsgType.modelloadfailed }),
+    ).not.toThrow()
+  })
+
+  it('resets ready when modelURL changes', async () => {
+    const el = new SpatializedStatic3DElement('s7', 'a.glb')
+    const first = el.ready
+
+    await el.updateProperties({ modelURL: 'b.glb' })
+    expect(el.ready).not.toBe(first)
+  })
+
+  it('does not reset ready when modelURL stays the same', async () => {
+    const el = new SpatializedStatic3DElement('s8', 'a.glb')
+    const first = el.ready
+
+    await el.updateProperties({ modelURL: 'a.glb' })
+    expect(el.ready).toBe(first)
+  })
+
+  it('cancels old ready promise with false when modelURL changes', async () => {
+    const el = new SpatializedStatic3DElement('s9', 'a.glb')
+    const first = el.ready
+
+    await el.updateProperties({ modelURL: 'b.glb' })
+    await expect(first).resolves.toBe(false)
+  })
+
+  it('new ready promise works after URL change', async () => {
+    const el = new SpatializedStatic3DElement('s10', 'a.glb')
+
+    await el.updateProperties({ modelURL: 'b.glb' })
+    const second = el.ready
+
+    el.onReceiveEvent({ type: SpatialWebMsgType.modelloaded })
+    await expect(second).resolves.toBe(true)
+  })
+
+  it('handles multiple URL changes in sequence', async () => {
+    const el = new SpatializedStatic3DElement('s11', 'a.glb')
+    const p1 = el.ready
+
+    await el.updateProperties({ modelURL: 'b.glb' })
+    await expect(p1).resolves.toBe(false)
+
+    const p2 = el.ready
+    await el.updateProperties({ modelURL: 'c.glb' })
+    await expect(p2).resolves.toBe(false)
+
+    const p3 = el.ready
+    el.onReceiveEvent({ type: SpatialWebMsgType.modelloaded })
+    await expect(p3).resolves.toBe(true)
+  })
+})

package/src/SpatializedStatic3DElement.ts

@@ -9,6 +9,17 @@ import { SpatialWebMsgType } from './WebMsgCommand'
  * and provides events for load success and failure.
  */
 export class SpatializedStatic3DElement extends SpatializedElement {
+  /**
+   * Creates a new spatialized static 3D element with the specified ID and URL.
+   * Registers the element to receive spatial events.
+   * @param id Unique identifier for this element
+   * @param modelURL URL of the 3D model
+   */
+  constructor(id: string, modelURL: string) {
+    super(id)
+    this.modelURL = modelURL
+  }
+
   /**
    * Promise resolver for the ready state.
    * Used to resolve the ready promise when the model is loaded.
@@ -19,13 +30,15 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * Caches the last model URL to detect changes.
    * Used to reset the ready promise when the model URL changes.
    */
-  private modelURL: string = ''
+  private modelURL: string
 
   /**
    * Creates a new promise for tracking the ready state of the model.
    * @returns Promise that resolves when the model is loaded (true) or fails to load (false)
    */
   private createReadyPromise() {
+    // If there's an existing promise reject it before it's replaced
+    this._readyResolve?.(false)
     return new Promise<boolean>(resolve => {
       this._readyResolve = resolve
     })

package/src/WebMsgCommand.ts

@@ -1,6 +1,4 @@
 import {
-  Vec3,
-  Size3D,
   SpatialDragEventDetail,
   SpatialTapEventDetail,
   SpatialRotateEventDetail,
@@ -10,8 +8,6 @@ import {
 } from './types/types'
 
 export enum SpatialWebMsgType {
-  cubeInfo = 'cubeInfo',
-  transform = 'transform',
   modelloaded = 'modelloaded',
   modelloadfailed = 'modelloadfailed',
   spatialtap = 'spatialtap',
@@ -30,28 +26,6 @@ export interface ObjectDestroyMsg {
   type: SpatialWebMsgType.objectdestroy
 }
 
-export interface CubeInfoMsg {
-  type: SpatialWebMsgType.cubeInfo
-  origin: Vec3
-  size: Size3D
-}
-
-export interface CubeInfoMsg {
-  type: SpatialWebMsgType.cubeInfo
-  origin: Vec3
-  size: Size3D
-}
-
-export interface TransformMsg {
-  type: SpatialWebMsgType.transform
-  detail: {
-    column0: [number, number, number]
-    column1: [number, number, number]
-    column2: [number, number, number]
-    column3: [number, number, number]
-  }
-}
-
 export interface SpatialTapMsg {
   type: SpatialWebMsgType.spatialtap
   detail: SpatialTapEventDetail

package/src/index.ts

@@ -6,6 +6,8 @@ export { SpatializedElement } from './SpatializedElement'
 export { Spatialized2DElement } from './Spatialized2DElement'
 export { SpatializedStatic3DElement } from './SpatializedStatic3DElement'
 export { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
+export * as PhysicalMetrics from './physicalMetrics'
+
 export * from './reality'
 export * from './types/types'
 export * from './types/global.d'

package/src/jsbcommand.coverage.test.ts

@@ -434,49 +434,6 @@ describe('SpatializedElement', () => {
     })
   })
 
-  it('handles transform and cubeInfo events and updates internal state', async () => {
-    const { SpatialWebEvent } = await import('./SpatialWebEvent')
-    const { SpatialWebMsgType } = await import('./WebMsgCommand')
-    const { SpatializedElement } = await import('./SpatializedElement')
-
-    SpatialWebEvent.init()
-
-    class TestElement extends SpatializedElement {
-      updateProperties = vi.fn().mockResolvedValue({
-        success: true,
-        data: undefined,
-        errorCode: '',
-        errorMessage: '',
-      })
-    }
-
-    const e = new TestElement('el2')
-    window.__SpatialWebEvent({
-      id: 'el2',
-      data: {
-        type: SpatialWebMsgType.cubeInfo,
-        size: { width: 1, height: 2, depth: 3 },
-        origin: { x: 4, y: 5, z: 6 },
-      },
-    })
-    expect(e.cubeInfo?.front).toBe(9)
-
-    window.__SpatialWebEvent({
-      id: 'el2',
-      data: {
-        type: SpatialWebMsgType.transform,
-        detail: {
-          column0: [1, 0, 0],
-          column1: [0, 1, 0],
-          column2: [0, 0, 1],
-          column3: [10, 20, 30],
-        },
-      },
-    })
-    expect(e.transform).toBeDefined()
-    expect(e.transformInv).toBeDefined()
-  })
-
   it('updates flags via gesture handler setters and updates transform via JSB', async () => {
     const { SpatialWebEvent } = await import('./SpatialWebEvent')
     const { SpatializedElement } = await import('./SpatializedElement')