@webspatial/core-sdk 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webspatial/core-sdk",
-  "version": "1.3.0",
+  "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

@@ -502,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()
@@ -627,11 +645,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
+  })
+})

package/src/physicalMetrics.ts

@@ -0,0 +1,101 @@
+import { SpatialWebEvent } from './SpatialWebEvent'
+export type PhysicalMetricsValueShape = {
+  meterToPtUnscaled: number
+  meterToPtScaled: number
+}
+
+type WorldScalingCompensation = 'unscaled' | 'scaled'
+
+type ConvertOption = { worldScalingCompensation: WorldScalingCompensation }
+
+// Fallback calibration: 1 meter ≈ 1360 pt for both scaled and unscaled modes.
+// This baseline ensures pointToPhysical(1360) === 1 and physicalToPoint(1) === 1360
+// until native physical metrics are injected into window.__webspatialsdk__.physicalMetrics
+// and a 'WebSpatialPhysicalMetricsUpdate' event updates the snapshot at runtime.
+let snapshot: PhysicalMetricsValueShape = {
+  meterToPtUnscaled: 1360,
+  meterToPtScaled: 1360,
+}
+
+function getWorldScalingCompensation(options?: ConvertOption) {
+  return options?.worldScalingCompensation ?? 'scaled' // default to scaled
+}
+
+/**
+ * Converts scene points (pt) to physical meters (m).
+ *
+ * @param point Points value to convert.
+ * @param options Optional conversion options to select world scaling compensation.
+ * @returns Physical length in meters.
+ */
+export function pointToPhysical(point: number, options?: ConvertOption) {
+  updateValue()
+  const compensation = getWorldScalingCompensation(options)
+  if (compensation === 'unscaled') {
+    return point / snapshot.meterToPtUnscaled
+  }
+  return point / snapshot.meterToPtScaled
+}
+
+/**
+ * Converts physical meters (m) to scene points (pt).
+ *
+ * @param physical Physical length in meters to convert.
+ * @param options Optional conversion options to select world scaling compensation.
+ * @returns Points length in the scene.
+ */
+export function physicalToPoint(physical: number, options?: ConvertOption) {
+  updateValue()
+  const compensation = getWorldScalingCompensation(options)
+  if (compensation === 'unscaled') {
+    return physical * snapshot.meterToPtUnscaled
+  }
+  return physical * snapshot.meterToPtScaled
+}
+
+function updateValue() {
+  // ssr protected
+  if (typeof window === 'undefined') return
+  const src = window.__webspatialsdk__?.physicalMetrics
+  if (!src) return
+  const next = {
+    meterToPtScaled: src.meterToPtScaled ?? snapshot.meterToPtScaled,
+    meterToPtUnscaled: src.meterToPtUnscaled ?? snapshot.meterToPtUnscaled,
+  }
+  // only update if there is a change
+  if (
+    next.meterToPtScaled !== snapshot.meterToPtScaled ||
+    next.meterToPtUnscaled !== snapshot.meterToPtUnscaled
+  ) {
+    snapshot = next
+  }
+}
+
+/**
+ * Returns the current physical metrics used for conversions.
+ *
+ * @returns The current metrics snapshot `{ meterToPtUnscaled, meterToPtScaled }`.
+ */
+export function getValue(): PhysicalMetricsValueShape {
+  updateValue()
+  return snapshot
+}
+
+/**
+ * Subscribes to physical metrics changes.
+ *
+ * @param cb Callback invoked when metrics update is detected.
+ * @returns Unsubscribe function to remove the listener.
+ */
+export function subscribe(cb: () => void) {
+  // ssr protected
+  if (typeof window === 'undefined') return () => {}
+  const handler = () => {
+    cb()
+  }
+  // receive metrics update from native via SpatialWebEvent, id: "window"
+  SpatialWebEvent.addEventReceiver('window', handler)
+  return () => {
+    SpatialWebEvent.removeEventReceiver('window')
+  }
+}