@webspatial/core-sdk 1.7.0 → 2.0.0

package/src/coverage-boost.test.ts

@@ -80,15 +80,17 @@ describe('utils', () => {
       { x: 2, y: 3, z: 4 },
     )
 
+    // Use toMatchObject because happy-dom returns a real DOMPoint (which
+    // includes a `w` property) rather than a plain {x,y,z} object.
     const origin = m.transformPoint({ x: 0, y: 0, z: 0 })
-    expect(origin).toEqual({
+    expect(origin).toMatchObject({
       x: 10,
       y: 20,
       z: 30,
     })
 
     const p = m.transformPoint({ x: 1, y: 1, z: 1 })
-    expect(p).toEqual({ x: 12, y: 23, z: 34 })
+    expect(p).toMatchObject({ x: 12, y: 23, z: 34 })
   })
 })
 
@@ -171,20 +173,24 @@ describe('SpatialObject', () => {
   it('inspect returns data when command succeeds', async () => {
     vi.doMock('./JSBCommand', () => {
       return {
-        InspectCommand: vi.fn().mockImplementation(() => ({
-          execute: vi.fn().mockResolvedValue({
-            success: true,
-            data: { a: 1 },
-            errorMessage: '',
-          }),
-        })),
-        DestroyCommand: vi.fn().mockImplementation(() => ({
-          execute: vi.fn().mockResolvedValue({
-            success: true,
-            data: undefined,
-            errorMessage: '',
-          }),
-        })),
+        InspectCommand: vi.fn().mockImplementation(function () {
+          return {
+            execute: vi.fn().mockResolvedValue({
+              success: true,
+              data: { a: 1 },
+              errorMessage: '',
+            }),
+          }
+        }),
+        DestroyCommand: vi.fn().mockImplementation(function () {
+          return {
+            execute: vi.fn().mockResolvedValue({
+              success: true,
+              data: undefined,
+              errorMessage: '',
+            }),
+          }
+        }),
       }
     })
 
@@ -196,20 +202,24 @@ describe('SpatialObject', () => {
   it('inspect throws when command fails', async () => {
     vi.doMock('./JSBCommand', () => {
       return {
-        InspectCommand: vi.fn().mockImplementation(() => ({
-          execute: vi.fn().mockResolvedValue({
-            success: false,
-            data: undefined,
-            errorMessage: 'nope',
-          }),
-        })),
-        DestroyCommand: vi.fn().mockImplementation(() => ({
-          execute: vi.fn().mockResolvedValue({
-            success: true,
-            data: undefined,
-            errorMessage: '',
-          }),
-        })),
+        InspectCommand: vi.fn().mockImplementation(function () {
+          return {
+            execute: vi.fn().mockResolvedValue({
+              success: false,
+              data: undefined,
+              errorMessage: 'nope',
+            }),
+          }
+        }),
+        DestroyCommand: vi.fn().mockImplementation(function () {
+          return {
+            execute: vi.fn().mockResolvedValue({
+              success: true,
+              data: undefined,
+              errorMessage: '',
+            }),
+          }
+        }),
       }
     })
 
@@ -222,20 +232,24 @@ describe('SpatialObject', () => {
     const onDestroy = vi.fn()
     vi.doMock('./JSBCommand', () => {
       return {
-        InspectCommand: vi.fn().mockImplementation(() => ({
-          execute: vi.fn().mockResolvedValue({
-            success: true,
-            data: undefined,
-            errorMessage: '',
-          }),
-        })),
-        DestroyCommand: vi.fn().mockImplementation(() => ({
-          execute: vi.fn().mockResolvedValue({
-            success: true,
-            data: { ok: true },
-            errorMessage: '',
-          }),
-        })),
+        InspectCommand: vi.fn().mockImplementation(function () {
+          return {
+            execute: vi.fn().mockResolvedValue({
+              success: true,
+              data: undefined,
+              errorMessage: '',
+            }),
+          }
+        }),
+        DestroyCommand: vi.fn().mockImplementation(function () {
+          return {
+            execute: vi.fn().mockResolvedValue({
+              success: true,
+              data: { ok: true },
+              errorMessage: '',
+            }),
+          }
+        }),
       }
     })
 
@@ -253,6 +267,45 @@ describe('SpatialObject', () => {
     await expect(obj.destroy()).resolves.toBeUndefined()
     expect(onDestroy).toHaveBeenCalledTimes(1)
   })
+
+  it('treats missing native spatial objects as already destroyed', async () => {
+    const onDestroy = vi.fn()
+    vi.doMock('./JSBCommand', () => {
+      return {
+        InspectCommand: vi.fn().mockImplementation(function () {
+          return {
+            execute: vi.fn().mockResolvedValue({
+              success: true,
+              data: undefined,
+              errorMessage: '',
+            }),
+          }
+        }),
+        DestroyCommand: vi.fn().mockImplementation(function () {
+          return {
+            execute: vi.fn().mockResolvedValue({
+              success: false,
+              data: undefined,
+              errorMessage:
+                'Failed to destroy SpatialObject: invalid inspect spatial object id obj-2 not exsit!',
+            }),
+          }
+        }),
+      }
+    })
+
+    const { SpatialObject } = await import('./SpatialObject')
+    class TestObject extends SpatialObject {
+      protected onDestroy() {
+        onDestroy()
+      }
+    }
+
+    const obj = new TestObject('obj-2')
+    await expect(obj.destroy()).resolves.toBeUndefined()
+    expect(obj.isDestroyed).toBe(true)
+    expect(onDestroy).toHaveBeenCalledTimes(1)
+  })
 })
 
 describe('platform adapters', () => {
@@ -263,18 +316,6 @@ describe('platform adapters', () => {
     vi.unmock('./JSBCommand')
   })
 
-  it('SSRPlatform returns successful no-op results', async () => {
-    const { SSRPlatform } = await import('./platform-adapter/ssr/SSRPlatform')
-    const platform = new SSRPlatform()
-
-    await expect(platform.callJSB('c', '{}')).resolves.toMatchObject({
-      success: true,
-    })
-    expect(platform.openSpatialSceneSync('s', undefined)).toMatchObject({
-      success: true,
-    })
-  })
-
   it('VisionOSPlatform.callJSB returns success and parses failures', async () => {
     ;(window as any).webkit = {
       messageHandlers: {
@@ -326,8 +367,8 @@ describe('platform adapters', () => {
     const r = await platform.createNativeSpatialDiv()
 
     expect(r.success).toBe(true)
-    expect(r.data.id).toBe(uuid)
-    expect(r.data.windowProxy).toBe(windowProxy)
+    expect(r.data?.id).toBe(uuid)
+    expect(r.data?.windowProxy).toBe(windowProxy)
   })
 })
 
@@ -456,6 +497,44 @@ describe('spatialWindowPolyfill', () => {
     expect(updateSpatialProperties).toHaveBeenCalledWith({
       material: 'none',
     })
+
+    await Promise.resolve()
+    await Promise.resolve()
+    updateSpatialProperties.mockClear()
+    ;(document.documentElement.style as any)['--xr-background-material'] =
+      'translucent'
+    expect(updateSpatialProperties).toHaveBeenCalledWith({
+      material: 'translucent',
+    })
+    expect(
+      getComputedStyle(document.documentElement)
+        .getPropertyValue('--xr-background-material')
+        .trim(),
+    ).toBe('translucent')
+    expect(
+      (
+        (document.documentElement.style as any)[
+          '--xr-background-material'
+        ] as string
+      ).trim(),
+    ).toBe('translucent')
+
+    updateSpatialProperties.mockClear()
+    document.documentElement.style.setProperty('border-radius', '80px')
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(updateSpatialProperties).toHaveBeenCalledWith({
+      cornerRadius: {
+        topLeading: 80,
+        topTrailing: 80,
+        bottomLeading: 80,
+        bottomTrailing: 80,
+      },
+    })
+    expect(updateSpatialProperties).not.toHaveBeenCalledWith({
+      material: 'none',
+    })
   })
 })
 
@@ -501,34 +580,42 @@ describe('SpatializedElementCreator', () => {
         UpdateSpatializedDynamic3DElementProperties: OkCommand,
         SetParentForEntityCommand: OkCommand,
         AddEntityToDynamic3DCommand: OkCommand,
-        createSpatialized2DElementCommand: vi.fn().mockImplementation(() => ({
-          execute: vi.fn().mockResolvedValue({
-            success: true,
-            data: { id: 'w1', windowProxy },
-            errorCode: '',
-            errorMessage: '',
+        createSpatialized2DElementCommand: vi
+          .fn()
+          .mockImplementation(function () {
+            return {
+              execute: vi.fn().mockResolvedValue({
+                success: true,
+                data: { id: 'w1', windowProxy },
+                errorCode: '',
+                errorMessage: '',
+              }),
+            }
           }),
-        })),
         CreateSpatializedStatic3DElementCommand: vi
           .fn()
-          .mockImplementation(() => ({
-            execute: vi.fn().mockResolvedValue({
-              success: true,
-              data: { id: 's-default' },
-              errorCode: '',
-              errorMessage: '',
-            }),
-          })),
+          .mockImplementation(function () {
+            return {
+              execute: vi.fn().mockResolvedValue({
+                success: true,
+                data: { id: 's-default' },
+                errorCode: '',
+                errorMessage: '',
+              }),
+            }
+          }),
         CreateSpatializedDynamic3DElementCommand: vi
           .fn()
-          .mockImplementation(() => ({
-            execute: vi.fn().mockResolvedValue({
-              success: true,
-              data: { id: 'd-default' },
-              errorCode: '',
-              errorMessage: '',
-            }),
-          })),
+          .mockImplementation(function () {
+            return {
+              execute: vi.fn().mockResolvedValue({
+                success: true,
+                data: { id: 'd-default' },
+                errorCode: '',
+                errorMessage: '',
+              }),
+            }
+          }),
       }
     })
 
@@ -574,14 +661,18 @@ describe('SpatializedElementCreator', () => {
         UpdateSpatializedDynamic3DElementProperties: OkCommand,
         SetParentForEntityCommand: OkCommand,
         AddEntityToDynamic3DCommand: OkCommand,
-        createSpatialized2DElementCommand: vi.fn().mockImplementation(() => ({
-          execute: vi.fn().mockResolvedValue({
-            success: false,
-            data: undefined,
-            errorCode: 'E',
-            errorMessage: 'bad',
+        createSpatialized2DElementCommand: vi
+          .fn()
+          .mockImplementation(function () {
+            return {
+              execute: vi.fn().mockResolvedValue({
+                success: false,
+                data: undefined,
+                errorCode: 'E',
+                errorMessage: 'bad',
+              }),
+            }
           }),
-        })),
         CreateSpatializedStatic3DElementCommand: vi.fn(),
         CreateSpatializedDynamic3DElementCommand: vi.fn(),
       }
@@ -622,22 +713,26 @@ describe('SpatializedElementCreator', () => {
         CreateSpatializedDynamic3DElementCommand: vi.fn(),
         CreateSpatializedStatic3DElementCommand: vi
           .fn()
-          .mockImplementationOnce(() => ({
-            execute: vi.fn().mockResolvedValue({
-              success: true,
-              data: { id: 's3' },
-              errorCode: '',
-              errorMessage: '',
-            }),
-          }))
-          .mockImplementationOnce(() => ({
-            execute: vi.fn().mockResolvedValue({
-              success: false,
-              data: undefined,
-              errorCode: 'E',
-              errorMessage: 'bad',
-            }),
-          })),
+          .mockImplementationOnce(function () {
+            return {
+              execute: vi.fn().mockResolvedValue({
+                success: true,
+                data: { id: 's3' },
+                errorCode: '',
+                errorMessage: '',
+              }),
+            }
+          })
+          .mockImplementationOnce(function () {
+            return {
+              execute: vi.fn().mockResolvedValue({
+                success: false,
+                data: undefined,
+                errorCode: 'E',
+                errorMessage: 'bad',
+              }),
+            }
+          }),
       }
     })
 
@@ -679,22 +774,26 @@ describe('SpatializedElementCreator', () => {
         CreateSpatializedStatic3DElementCommand: vi.fn(),
         CreateSpatializedDynamic3DElementCommand: vi
           .fn()
-          .mockImplementationOnce(() => ({
-            execute: vi.fn().mockResolvedValue({
-              success: true,
-              data: { id: 'd3' },
-              errorCode: '',
-              errorMessage: '',
-            }),
-          }))
-          .mockImplementationOnce(() => ({
-            execute: vi.fn().mockResolvedValue({
-              success: false,
-              data: undefined,
-              errorCode: 'E',
-              errorMessage: 'bad',
-            }),
-          })),
+          .mockImplementationOnce(function () {
+            return {
+              execute: vi.fn().mockResolvedValue({
+                success: true,
+                data: { id: 'd3' },
+                errorCode: '',
+                errorMessage: '',
+              }),
+            }
+          })
+          .mockImplementationOnce(function () {
+            return {
+              execute: vi.fn().mockResolvedValue({
+                success: false,
+                data: undefined,
+                errorCode: 'E',
+                errorMessage: 'bad',
+              }),
+            }
+          }),
       }
     })
 
@@ -717,72 +816,7 @@ describe('SpatializedStatic3DElement', () => {
     vi.unmock('./JSBCommand')
   })
 
-  it('resets ready when modelURL changes and resolves on load events', async () => {
-    const execute = vi.fn().mockResolvedValue({
-      success: true,
-      data: undefined,
-      errorCode: '',
-      errorMessage: '',
-    })
-    vi.doMock('./JSBCommand', () => {
-      class OkCommand {
-        execute() {
-          return Promise.resolve({
-            success: true,
-            data: undefined,
-            errorCode: '',
-            errorMessage: '',
-          })
-        }
-      }
-
-      return {
-        InspectCommand: OkCommand,
-        DestroyCommand: OkCommand,
-        UpdateSpatializedElementTransform: OkCommand,
-        UpdateSpatialized2DElementProperties: OkCommand,
-        AddSpatializedElementToSpatialized2DElement: OkCommand,
-        UpdateSpatializedDynamic3DElementProperties: OkCommand,
-        SetParentForEntityCommand: OkCommand,
-        AddEntityToDynamic3DCommand: OkCommand,
-        createSpatialized2DElementCommand: vi.fn(),
-        CreateSpatializedStatic3DElementCommand: vi.fn(),
-        CreateSpatializedDynamic3DElementCommand: vi.fn(),
-        UpdateSpatializedStatic3DElementProperties: vi
-          .fn()
-          .mockImplementation(() => ({ execute })),
-      }
-    })
-
-    const { SpatializedStatic3DElement } = await import(
-      './SpatializedStatic3DElement'
-    )
-    const { SpatialWebMsgType } = await import('./WebMsgCommand')
-
-    const el = new SpatializedStatic3DElement('m1')
-    const onLoad = vi.fn()
-    const onFail = vi.fn()
-    el.onLoadCallback = onLoad
-    el.onLoadFailureCallback = onFail
-
-    const p1 = el.ready
-    await el.updateProperties({ modelURL: 'a.glb' } as any)
-    expect(execute).toHaveBeenCalledTimes(1)
-    const p2 = el.ready
-    expect(p2).not.toBe(p1)
-
-    el.onReceiveEvent({ type: SpatialWebMsgType.modelloaded } as any)
-    await expect(p2).resolves.toBe(true)
-    expect(onLoad).toHaveBeenCalledTimes(1)
-
-    await el.updateProperties({ modelURL: 'b.glb' } as any)
-    const p3 = el.ready
-    el.onReceiveEvent({ type: SpatialWebMsgType.modelloadfailed } as any)
-    await expect(p3).resolves.toBe(false)
-    expect(onFail).toHaveBeenCalledTimes(1)
-  })
-
-  it('updateModelTransform passes float64 array to updateProperties', async () => {
+  it('entityTransform setter passes float64 array to updateProperties', async () => {
     const execute = vi.fn().mockResolvedValue({
       success: true,
       data: undefined,
@@ -815,7 +849,9 @@ describe('SpatializedStatic3DElement', () => {
         CreateSpatializedDynamic3DElementCommand: vi.fn(),
         UpdateSpatializedStatic3DElementProperties: vi
           .fn()
-          .mockImplementation(() => ({ execute })),
+          .mockImplementation(function () {
+            return { execute }
+          }),
       }
     })
 
@@ -832,7 +868,7 @@ describe('SpatializedStatic3DElement', () => {
     }
 
     const el = new SpatializedStatic3DElement('m2')
-    el.updateModelTransform(new DOMMatrixWithArray() as any)
+    el.entityTransform = new DOMMatrixWithArray() as any
     expect(execute).toHaveBeenCalledTimes(1)
   })
 })
@@ -875,9 +911,9 @@ describe('SpatializedDynamic3DElement', () => {
         CreateSpatializedStatic3DElementCommand: vi.fn(),
         CreateSpatializedDynamic3DElementCommand: vi.fn(),
         AddEntityToDynamic3DCommand: OkCommand,
-        SetParentForEntityCommand: vi
-          .fn()
-          .mockImplementation(() => ({ execute })),
+        SetParentForEntityCommand: vi.fn().mockImplementation(function () {
+          return { execute }
+        }),
       }
     })
 
@@ -927,7 +963,9 @@ describe('SpatializedDynamic3DElement', () => {
         CreateSpatializedDynamic3DElementCommand: vi.fn(),
         UpdateSpatializedDynamic3DElementProperties: vi
           .fn()
-          .mockImplementation(() => ({ execute })),
+          .mockImplementation(function () {
+            return { execute }
+          }),
       }
     })
 
@@ -940,40 +978,25 @@ describe('SpatializedDynamic3DElement', () => {
   })
 })
 
-describe('ssr-polyfill', () => {
+describe('isSSREnv', () => {
   it('isSSREnv returns false in jsdom', async () => {
-    const { isSSREnv } = await import('./ssr-polyfill')
+    const { isSSREnv } = await import('./isSSREnv')
     expect(isSSREnv()).toBe(false)
   })
 })
 
 describe('platform-adapter', () => {
-  it('createPlatform returns SSRPlatform in SSR env', async () => {
-    vi.resetModules()
-    vi.doMock('./ssr-polyfill', () => {
-      return { isSSREnv: () => true }
-    })
-
-    const { createPlatform } = await import('./platform-adapter')
-    const p = await createPlatform()
-    expect(typeof p.callJSB).toBe('function')
-    expect(typeof p.openSpatialSceneSync).toBe('function')
-    expect(typeof p.createNativeSpatialDiv).toBe('function')
-    expect(typeof p.createNativeAttachment).toBe('function')
-  })
-
-  it('createPlatformSync uses SSR sync noop in SSR env', async () => {
+  it('createPlatform and createPlatformSync throw in SSR env', async () => {
     vi.resetModules()
-    vi.doMock('./ssr-polyfill', () => {
+    vi.doMock('./isSSREnv', () => {
       return { isSSREnv: () => true }
     })
 
-    const { createPlatformSync } = await import(
-      './platform-adapter/createPlatformSync'
+    const { createPlatform, createPlatformSync } = await import(
+      './platform-adapter'
     )
-    const p = createPlatformSync()
-    const r = p.openSpatialSceneSync('https://x', undefined)
-    expect(r.success).toBe(true)
-    expect(r.data).toBeUndefined()
+    const expected = /cannot run during SSR/
+    await expect(createPlatform()).rejects.toThrow(expected)
+    expect(() => createPlatformSync()).toThrow(expected)
   })
 })

package/src/index.ts

@@ -1,3 +1,23 @@
+// =============================================================================
+// `@webspatial/core-sdk` ESM entry — side-effect-free.
+//
+// The previous top-level polyfill installation (`if (UA contains
+// 'WebSpatial/') { injectSceneHook(); spatialWindowPolyfill(); }`) lived
+// here historically and was extracted out per the lazy-load proposal
+// `tasks.md §12.9` ("Pre-v1 budget calibration"). ESM bundlers cannot
+// tree-shake observable top-level side effects, so the runtime UA guard
+// was useless for bundle size — every consumer that imported anything
+// from this package statically bundled `scene-polyfill.ts` + the
+// `spatial-window-polyfill.ts` pair regardless of whether they ran in a
+// WebSpatial browser. After this extraction, consumers opt in:
+//
+//   import '@webspatial/core-sdk/install-polyfills'
+//
+// `@webspatial/react-sdk` does this from inside its spatial chunk so the
+// polyfills install only when `bootSpatial()` resolves, never in the
+// lean default-entry bundle.
+// =============================================================================
+
 export type {} from './types/global'
 
 export { SpatialObject } from './SpatialObject'
@@ -12,16 +32,10 @@ export * as PhysicalMetrics from './physicalMetrics'
 
 export * from './reality'
 export * from './types/types'
+export * from './types/animation'
+export * from './types/motion'
+export { validateSpatializedMotionConfig } from './motion'
 export * from './runtime'
 
-// side effects
-import { injectSceneHook } from './scene-polyfill'
-import { isSSREnv } from './ssr-polyfill'
-import { spatialWindowPolyfill } from './spatial-window-polyfill'
-
-export { isSSREnv }
-
-if (!isSSREnv() && navigator.userAgent.indexOf('WebSpatial/') > 0) {
-  injectSceneHook()
-  spatialWindowPolyfill()
-}
+export { composeSRT, decomposeSRT } from './utils'
+export { isSSREnv } from './isSSREnv'

package/src/install-polyfills.ts

@@ -0,0 +1,38 @@
+// =============================================================================
+// `@webspatial/core-sdk/install-polyfills` — opt-in polyfill installer.
+//
+// Side-effect-only module: installs the spatial scene hook + the
+// `window.spatial` polyfill iff the page is running inside a
+// WebSpatial-capable browser (UA contains `WebSpatial/`) AND we are not
+// in an SSR / non-browser environment.
+//
+// Previously this side effect lived as a top-level `if (...)` block in
+// `src/index.ts`, which forced every consumer of the package — even
+// consumers that only imported pure runtime helpers like `supports()` —
+// to bundle `scene-polyfill.ts` (~636 LoC) and `spatial-window-polyfill.ts`
+// (~182 LoC) statically. ESM bundlers cannot tree-shake observable
+// side effects, so the if-statement guard was useless for bundle size.
+//
+// After this extraction, `src/index.ts` is side-effect-free and consumers
+// who need the polyfills opt in explicitly:
+//
+//   import '@webspatial/core-sdk/install-polyfills'
+//
+// `@webspatial/react-sdk` does this from inside its spatial chunk
+// (`packages/react/src/spatial/index.ts`) so the polyfill installs only
+// when the spatial chunk dynamically loads — never in the SDK's lean
+// default entry.
+//
+// Per the lazy-load proposal `tasks.md §12.9` ("Pre-v1 budget calibration"),
+// extracting these polyfills is one of the named optimization candidates
+// for closing the marginal-delta gap on the 8 KB strict budget.
+// =============================================================================
+
+import { injectSceneHook } from './scene-polyfill'
+import { spatialWindowPolyfill } from './spatial-window-polyfill'
+import { isSSREnv } from './isSSREnv'
+
+if (!isSSREnv() && navigator.userAgent.indexOf('WebSpatial/') > 0) {
+  injectSceneHook()
+  spatialWindowPolyfill()
+}