@webspatial/core-sdk 1.3.0 → 1.5.0

package/package.json

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

package/src/JSBCommand.ts

@@ -2,6 +2,7 @@ import { createPlatform } from './platform-adapter'
 import { WebSpatialProtocolResult } from './platform-adapter/interface'
 import { SpatialComponent } from './reality/component/SpatialComponent'
 import { SpatialEntity } from './reality/entity/SpatialEntity'
+import { SpatialMaterial } from './reality/material/SpatialMaterial'
 import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
 import { SpatializedElement } from './SpatializedElement'
 import { SpatialObject } from './SpatialObject'
@@ -386,6 +387,38 @@ export class AddComponentToEntityCommand extends JSBCommand {
   commandType = 'AddComponentToEntity'
 }
 
+export class RemoveComponentFromEntityCommand extends JSBCommand {
+  constructor(
+    public entity: SpatialEntity,
+    public comp: SpatialComponent,
+  ) {
+    super()
+  }
+  protected getParams(): Record<string, any> | undefined {
+    return {
+      entityId: this.entity.id,
+      componentId: this.comp.id,
+    }
+  }
+  commandType = 'RemoveComponentFromEntity'
+}
+
+export class SetMaterialsOnEntityCommand extends JSBCommand {
+  constructor(
+    public entityId: string,
+    public materials: SpatialMaterial[],
+  ) {
+    super()
+  }
+  protected getParams(): Record<string, any> | undefined {
+    return {
+      entityId: this.entityId,
+      materialIds: this.materials.map(m => m.id),
+    }
+  }
+  commandType = 'SetMaterialsOnEntity'
+}
+
 export class AddEntityToDynamic3DCommand extends JSBCommand {
   constructor(
     public d3dEle: SpatializedDynamic3DElement,
@@ -502,6 +535,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()
@@ -627,11 +678,26 @@ export class CreateAttachmentEntityCommand extends WebSpatialProtocolCommand {
   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,
     }
   }
 }

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/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/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

@@ -37,6 +37,8 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * @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')

package/src/physicalMetrics.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test, vi } from 'vitest'
+
+async function loadModule() {
+  vi.resetModules()
+  return await import('./physicalMetrics')
+}
+
+describe('physicalMetrics', () => {
+  test('default scaled conversion', async () => {
+    const { pointToPhysical, physicalToPoint, getValue } = await loadModule()
+    const v = getValue()
+    expect(v.meterToPtScaled).toBe(1360)
+    expect(v.meterToPtUnscaled).toBe(1360)
+    expect(pointToPhysical(1360)).toBe(1)
+    expect(physicalToPoint(1)).toBe(1360)
+  })
+
+  test('unscaled compensation uses unscaled metrics', async () => {
+    const { pointToPhysical, physicalToPoint } = await loadModule()
+    expect(
+      pointToPhysical(1360, { worldScalingCompensation: 'unscaled' }),
+    ).toBe(1)
+    expect(physicalToPoint(1, { worldScalingCompensation: 'unscaled' })).toBe(
+      1360,
+    )
+  })
+
+  test('updateValue applies window metrics', async () => {
+    const m = await loadModule()
+    const { SpatialWebEvent } = await import('./SpatialWebEvent')
+    SpatialWebEvent.init()
+    ;(window as any).__webspatialsdk__ = {
+      physicalMetrics: {
+        meterToPtScaled: 2000,
+        meterToPtUnscaled: 1500,
+      },
+    }
+    const unsubscribe = m.subscribe(() => {})
+    window.__SpatialWebEvent({ id: 'window', data: {} })
+    const v = m.getValue()
+    expect(v.meterToPtScaled).toBe(2000)
+    expect(v.meterToPtUnscaled).toBe(1500)
+    expect(m.pointToPhysical(2000)).toBe(1)
+    expect(
+      m.pointToPhysical(1500, { worldScalingCompensation: 'unscaled' }),
+    ).toBe(1)
+    unsubscribe()
+    ;(window as any).__webspatialsdk__ = undefined
+  })
+
+  test('updateValue applies partial metrics', async () => {
+    const m = await loadModule()
+    const { SpatialWebEvent } = await import('./SpatialWebEvent')
+    SpatialWebEvent.init()
+    ;(window as any).__webspatialsdk__ = {
+      physicalMetrics: { meterToPtScaled: 1000 },
+    }
+    const unsubscribe = m.subscribe(() => {})
+    window.__SpatialWebEvent({ id: 'window', data: {} })
+    expect(m.getValue().meterToPtScaled).toBe(1000)
+    expect(m.getValue().meterToPtUnscaled).toBe(1360)
+    expect(m.pointToPhysical(1000)).toBe(1)
+    expect(m.physicalToPoint(1, { worldScalingCompensation: 'unscaled' })).toBe(
+      1360,
+    )
+    unsubscribe()
+    ;(window as any).__webspatialsdk__ = undefined
+  })
+
+  test('subscribe listens to event and supports unsubscribe', async () => {
+    const m = await loadModule()
+    const { SpatialWebEvent } = await import('./SpatialWebEvent')
+    SpatialWebEvent.init()
+    const cb = vi.fn()
+    const unsubscribe = m.subscribe(cb)
+    ;(window as any).__webspatialsdk__ = {
+      physicalMetrics: {
+        meterToPtScaled: 900,
+        meterToPtUnscaled: 800,
+      },
+    }
+    window.__SpatialWebEvent({ id: 'window', data: {} })
+    expect(cb).toHaveBeenCalledTimes(1)
+    expect(m.getValue().meterToPtScaled).toBe(900)
+    expect(m.getValue().meterToPtUnscaled).toBe(800)
+    ;(window as any).__webspatialsdk__ = {
+      physicalMetrics: {
+        meterToPtScaled: 700,
+        meterToPtUnscaled: 600,
+      },
+    }
+    window.__SpatialWebEvent({ id: 'window', data: {} })
+    expect(cb).toHaveBeenCalledTimes(2)
+    expect(m.getValue().meterToPtScaled).toBe(700)
+    expect(m.getValue().meterToPtUnscaled).toBe(600)
+
+    unsubscribe()
+    ;(window as any).__webspatialsdk__ = {
+      physicalMetrics: {
+        meterToPtScaled: 500,
+        meterToPtUnscaled: 400,
+      },
+    }
+    window.__SpatialWebEvent({ id: 'window', data: {} })
+    expect(cb).toHaveBeenCalledTimes(2)
+    expect(m.getValue().meterToPtScaled).toBe(500)
+    expect(m.getValue().meterToPtUnscaled).toBe(400)
+    ;(window as any).__webspatialsdk__ = undefined
+  })
+})