@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/index.ts

@@ -1,3 +1,25 @@
+// =============================================================================
+// `@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'
 export { Spatial } from './Spatial'
 export { SpatialSession } from './SpatialSession'
@@ -10,16 +32,10 @@ export * as PhysicalMetrics from './physicalMetrics'
 
 export * from './reality'
 export * from './types/types'
-export * from './types/global.d'
-
-// side effects
-import { injectSceneHook } from './scene-polyfill'
-import { isSSREnv } from './ssr-polyfill'
-import { spatialWindowPolyfill } from './spatial-window-polyfill'
-
-export { isSSREnv }
+export * from './types/animation'
+export * from './types/motion'
+export { validateSpatializedMotionConfig } from './motion'
+export * from './runtime'
 
-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()
+}

package/src/jsbcommand.coverage.test.ts

@@ -55,12 +55,14 @@ class DOMMatrixPolyfill {
 
 const platformSpy = {
   callJSB: vi.fn(),
-  callWebSpatialProtocol: vi.fn(),
-  callWebSpatialProtocolSync: vi.fn(),
+  openSpatialSceneSync: vi.fn(),
+  createNativeSpatialDiv: vi.fn(),
+  createNativeAttachment: vi.fn(),
 }
 
 vi.mock('./platform-adapter', () => ({
-  createPlatform: () => platformSpy,
+  createPlatform: () => Promise.resolve(platformSpy),
+  createPlatformSync: () => platformSpy,
 }))
 
 function ok(data: any = {}) {
@@ -72,23 +74,20 @@ function ok(data: any = {}) {
   })
 }
 
-function parseQuery(q?: string) {
-  const sp = new URLSearchParams(q ?? '')
-  const out: Record<string, string> = {}
-  for (const [k, v] of sp.entries()) out[k] = v
-  return out
-}
-
 describe('JSBCommand', () => {
   beforeEach(() => {
     platformSpy.callJSB.mockReset()
-    platformSpy.callWebSpatialProtocol.mockReset()
-    platformSpy.callWebSpatialProtocolSync.mockReset()
+    platformSpy.openSpatialSceneSync.mockReset()
+    platformSpy.createNativeSpatialDiv.mockReset()
+    platformSpy.createNativeAttachment.mockReset()
     platformSpy.callJSB.mockImplementation(() => ok({ id: 'id-1' }))
-    platformSpy.callWebSpatialProtocol.mockImplementation(() =>
+    platformSpy.createNativeSpatialDiv.mockImplementation(() =>
+      ok({ windowProxy: {}, id: 'spatial-1' }),
+    )
+    platformSpy.createNativeAttachment.mockImplementation(() =>
       ok({ windowProxy: {}, id: 'spatial-1' }),
     )
-    platformSpy.callWebSpatialProtocolSync.mockImplementation(() => ({
+    platformSpy.openSpatialSceneSync.mockImplementation(() => ({
       success: true,
       data: { windowProxy: {}, id: 'spatial-1' },
       errorCode: '',
@@ -129,6 +128,7 @@ describe('JSBCommand', () => {
   it('builds element commands payloads', async () => {
     const mod = await import('./JSBCommand')
     const {
+      CreateSpatializedElementAnimationJSBCommand,
       UpdateSpatializedElementTransform,
       UpdateSpatialized2DElementProperties,
       UpdateSpatializedDynamic3DElementProperties,
@@ -186,46 +186,24 @@ describe('JSBCommand', () => {
       JSON.stringify({ id: 'so-1', spatializedElementId: 'ele-1' }),
     )
 
+    await new CreateSpatializedElementAnimationJSBCommand({
+      elementId: 'ele-1',
+      timeline: { duration: 1, tracks: [] },
+    } as any).execute()
+    expect(platformSpy.callJSB).toHaveBeenCalledWith(
+      'CreateSpatializedElementAnimation',
+      JSON.stringify({
+        elementId: 'ele-1',
+        timeline: { duration: 1, tracks: [] },
+      }),
+    )
+
     await new UpdateUnlitMaterialProperties(obj, { color: '#fff' }).execute()
     expect(platformSpy.callJSB).toHaveBeenCalledWith(
       'UpdateUnlitMaterialProperties',
       JSON.stringify({ id: 'so-1', color: '#fff' }),
     )
   })
-
-  it('creates query string and calls WebSpatialProtocol', async () => {
-    const mod = await import('./JSBCommand')
-    const { createSpatialSceneCommand, createSpatialized2DElementCommand } = mod
-
-    await new createSpatialized2DElementCommand().execute()
-    expect(platformSpy.callWebSpatialProtocol).toHaveBeenCalledWith(
-      'createSpatialized2DElement',
-      '',
-      undefined,
-      undefined,
-    )
-
-    const cmd = new createSpatialSceneCommand(
-      'https://example.com/a?b=c',
-      { type: 'window', defaultSize: { width: 1, height: 2 } } as any,
-      '_self',
-      'popup=1',
-    )
-    await cmd.execute()
-    const call = platformSpy.callWebSpatialProtocol.mock.calls.at(-1)
-    expect(call?.[0]).toBe('createSpatialScene')
-    expect(call?.[2]).toBe('_self')
-    expect(call?.[3]).toBe('popup=1')
-    const q = parseQuery(call?.[1])
-    expect(q.url).toBe('https://example.com/a?b=c')
-    expect(JSON.parse(q.config)).toEqual({
-      type: 'window',
-      defaultSize: { width: 1, height: 2 },
-    })
-
-    cmd.executeSync()
-    expect(platformSpy.callWebSpatialProtocolSync).toHaveBeenCalled()
-  })
 })
 
 describe('SpatialObject', () => {
@@ -272,6 +250,7 @@ describe('realityCreator', () => {
       if (cmd === 'CreateModelComponent') return ok({ id: 'cmp-1' })
       if (cmd === 'CreateSpatialModelEntity') return ok({ id: 'ment-1' })
       if (cmd === 'CreateModelAsset') return ok({ id: 'asset-1' })
+      if (cmd === 'CreateTexture') return ok({ id: 'tex-1' })
       return ok({ id: 'id-1' })
     })
   })
@@ -282,6 +261,7 @@ describe('realityCreator', () => {
     const mat = await import('./reality/material/SpatialUnlitMaterial')
     const cmp = await import('./reality/component/ModelComponent')
     const asset = await import('./reality/resource/SpatialModelAsset')
+    const tex = await import('./reality/resource/SpatialTextureResource')
     const ent = await import('./reality/entity/SpatialEntity')
     const modelEnt = await import('./reality/entity/SpatialModelEntity')
 
@@ -311,6 +291,10 @@ describe('realityCreator', () => {
       creator.createModelAsset({ url: 'https://example.com/a.glb' }),
     ).resolves.toBeInstanceOf(asset.SpatialModelAsset)
 
+    await expect(
+      creator.createSpatialTexture({ url: 'https://example.com/tex.png' }),
+    ).resolves.toBeInstanceOf(tex.SpatialTextureResource)
+
     await expect(
       creator.createSpatialModelEntity(
         { modelAssetId: 'asset-1' },
@@ -441,12 +425,17 @@ describe('SpatializedElement', () => {
     SpatialWebEvent.init()
 
     class TestElement extends SpatializedElement {
+      /** Identifies the supported motion target kind for this test element. */
+      readonly kind = 'spatialized2d' as const
+
       updateProperties = vi.fn().mockResolvedValue({
         success: true,
         data: undefined,
         errorCode: '',
         errorMessage: '',
       })
+
+      motion = vi.fn()
     }
 
     const e = new TestElement('el3')
@@ -469,12 +458,17 @@ describe('SpatializedElement', () => {
     SpatialWebEvent.init()
 
     class TestElement extends SpatializedElement {
+      /** Identifies the supported motion target kind for this test element. */
+      readonly kind = 'spatialized2d' as const
+
       updateProperties = vi.fn().mockResolvedValue({
         success: true,
         data: undefined,
         errorCode: '',
         errorMessage: '',
       })
+
+      motion = vi.fn()
     }
 
     const e = new TestElement('el4')

package/src/motion/AnimationObject.test.ts

@@ -0,0 +1,421 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { SpatialWebMsgType } from '../WebMsgCommand'
+import { SpatialWebEvent } from '../SpatialWebEvent'
+import type { SpatialAnimationStateChangedMsg } from '../types/motion/spatializedElementMotion'
+
+const spatialAnimationStateChangedType: SpatialAnimationStateChangedMsg['type'] =
+  SpatialWebMsgType.animationstatechange
+
+const spies = vi.hoisted(() => ({
+  createCommandSpy: vi.fn(),
+  controlCommandSpy: vi.fn(),
+  destroyCommandSpy: vi.fn(),
+  failNextControlType: undefined as string | undefined,
+}))
+
+vi.mock('../JSBCommand', () => {
+  const ok = (data: any = {}) => ({
+    success: true,
+    data,
+    errorCode: '',
+    errorMessage: '',
+  })
+
+  class CreateSpatializedElementAnimationJSBCommand {
+    constructor(public command: any) {
+      spies.createCommandSpy(command)
+    }
+    execute = vi.fn().mockResolvedValue(ok({ id: 'native-anim-1' }))
+  }
+
+  class ControlSpatializedElementAnimationJSBCommand {
+    constructor(public command: any) {
+      spies.controlCommandSpy(command)
+    }
+    execute = vi.fn().mockImplementation(() => {
+      if (spies.failNextControlType === this.command.type) {
+        spies.failNextControlType = undefined
+        return Promise.resolve({
+          success: false,
+          data: undefined,
+          errorCode: 'E_CONTROL',
+          errorMessage: `${this.command.type} failed`,
+        })
+      }
+      return Promise.resolve(ok())
+    })
+  }
+
+  class DestroyCommand {
+    constructor(public id: string) {
+      spies.destroyCommandSpy(id)
+    }
+    execute = vi.fn().mockResolvedValue(ok({ destroyed: true }))
+  }
+
+  class InspectCommand {
+    constructor(public id: string = '') {}
+    execute = vi.fn().mockResolvedValue(ok({ inspected: true }))
+  }
+
+  return {
+    CreateSpatializedElementAnimationJSBCommand,
+    ControlSpatializedElementAnimationJSBCommand,
+    DestroyCommand,
+    InspectCommand,
+  }
+})
+
+describe('AnimationObject', () => {
+  beforeEach(() => {
+    spies.createCommandSpy.mockClear()
+    spies.controlCommandSpy.mockClear()
+    spies.destroyCommandSpy.mockClear()
+    spies.failNextControlType = undefined
+    SpatialWebEvent.eventReceiver = {}
+  })
+
+  async function createAnimation() {
+    const { SpatializedElement } = await import('../SpatializedElement')
+
+    class TestSpatializedElement extends SpatializedElement {
+      /** Identifies the supported motion target kind for this test element. */
+      readonly kind = 'static3d' as const
+
+      async updateProperties() {
+        return {
+          success: true,
+          data: undefined,
+          errorCode: '',
+          errorMessage: '',
+        }
+      }
+    }
+
+    const element = new TestSpatializedElement('element-1')
+    return element.createAnimation({
+      duration: 1,
+      from: {
+        transform: { translate: { x: 0 } },
+      },
+      to: {
+        transform: { translate: { x: 10 } },
+      },
+    })
+  }
+
+  it('types native state events with the shared animationstatechange discriminant', () => {
+    expect(spatialAnimationStateChangedType).toBe(
+      SpatialWebMsgType.animationstatechange,
+    )
+  })
+
+  it('creates from the native create command and tracks native state directly', async () => {
+    const { AnimationObject } = await import('./AnimationObject')
+
+    const animation = await createAnimation()
+
+    expect(animation).toBeInstanceOf(AnimationObject)
+    expect(animation.id).toBe('native-anim-1')
+    expect('uuid' in animation).toBe(false)
+    expect(spies.createCommandSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        elementId: 'element-1',
+        timeline: expect.any(Object),
+      }),
+    )
+
+    const receiver = SpatialWebEvent.eventReceiver[animation.id]
+    expect(receiver).toEqual(expect.any(Function))
+
+    const onValuesChange = vi.fn()
+    const onStateChange = vi.fn()
+    const onComplete = vi.fn()
+    animation.setCallbacks({
+      onValuesChange,
+      onStateChange,
+      onComplete,
+    })
+
+    receiver?.({
+      detail: {
+        animationId: 'other-animation',
+        action: 'play',
+        playState: 'running',
+        finished: false,
+        values: { transform: { translate: { x: 2.5 } } },
+      },
+    })
+
+    expect(animation.playState).toBe('idle')
+    expect(onValuesChange).not.toHaveBeenCalled()
+    expect(onStateChange).not.toHaveBeenCalled()
+
+    receiver?.({
+      detail: {
+        animationId: animation.id,
+        action: 'play',
+        playState: 'running',
+        finished: false,
+        values: { transform: { translate: { x: 5 } } },
+      },
+    })
+
+    expect(animation.playState).toBe('running')
+    expect(animation.isAnimating).toBe(true)
+    expect(animation.isPaused).toBe(false)
+    expect(animation.finished).toBe(false)
+    expect(onValuesChange).toHaveBeenCalledWith({
+      transform: { translate: { x: 5 } },
+    })
+    expect(onStateChange).toHaveBeenCalledTimes(1)
+
+    receiver?.({
+      detail: {
+        animationId: animation.id,
+        action: 'complete',
+        playState: 'finished',
+        finished: true,
+        values: { transform: { translate: { x: 10 } } },
+      },
+    })
+
+    expect(animation.playState).toBe('finished')
+    expect(animation.finished).toBe(true)
+    expect(onComplete).toHaveBeenCalledWith({
+      transform: { translate: { x: 10 } },
+    })
+    expect(onStateChange).toHaveBeenCalledTimes(2)
+  })
+
+  it('uses the inherited destroy path and unregisters its native WebMsg receiver', async () => {
+    const animation = await createAnimation()
+
+    expect(SpatialWebEvent.eventReceiver[animation.id]).toEqual(
+      expect.any(Function),
+    )
+
+    await animation.destroy()
+
+    expect(spies.destroyCommandSpy).toHaveBeenCalledWith(animation.id)
+    expect(spies.controlCommandSpy).not.toHaveBeenCalledWith(
+      expect.objectContaining({ type: 'destroy' }),
+    )
+    expect(animation.isDestroyed).toBe(true)
+    expect(SpatialWebEvent.eventReceiver[animation.id]).toBeUndefined()
+  })
+
+  it('cleans up local lifecycle when native reports destroy', async () => {
+    const animation = await createAnimation()
+    const receiver = SpatialWebEvent.eventReceiver[animation.id]
+
+    expect(receiver).toEqual(expect.any(Function))
+
+    receiver?.({
+      detail: {
+        animationId: animation.id,
+        action: 'destroy',
+        playState: 'idle',
+        finished: false,
+      },
+    })
+
+    expect(animation.isDestroyed).toBe(true)
+    expect(SpatialWebEvent.eventReceiver[animation.id]).toBeUndefined()
+
+    await animation.play()
+    expect(spies.controlCommandSpy).not.toHaveBeenCalled()
+  })
+
+  it('fires onStart only after the native start event arrives', async () => {
+    const animation = await createAnimation()
+    const onStart = vi.fn()
+    animation.setCallbacks({ onStart })
+    const receiver = SpatialWebEvent.eventReceiver[animation.id]
+
+    await animation.play()
+    expect(onStart).not.toHaveBeenCalled()
+
+    receiver?.({
+      detail: {
+        animationId: animation.id,
+        action: 'play',
+        playState: 'running',
+        finished: false,
+        values: { transform: { translate: { x: 1 } } },
+      },
+    })
+    expect(onStart).not.toHaveBeenCalled()
+
+    receiver?.({
+      detail: {
+        animationId: animation.id,
+        action: 'start',
+        playState: 'running',
+        finished: false,
+        values: { transform: { translate: { x: 1 } } },
+      },
+    })
+    expect(onStart).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not fire onStart when play control fails and retries only start after native start', async () => {
+    const animation = await createAnimation()
+    const onStart = vi.fn()
+    const onError = vi.fn()
+    animation.setCallbacks({ onStart, onError })
+    const receiver = SpatialWebEvent.eventReceiver[animation.id]
+
+    spies.failNextControlType = 'play'
+
+    await expect(animation.play()).rejects.toThrow('play failed')
+    expect(onStart).not.toHaveBeenCalled()
+    expect(onError).not.toHaveBeenCalled()
+
+    await animation.play()
+    expect(onStart).not.toHaveBeenCalled()
+
+    receiver?.({
+      detail: {
+        animationId: animation.id,
+        action: 'start',
+        playState: 'running',
+        finished: false,
+        values: { transform: { translate: { x: 2 } } },
+      },
+    })
+    expect(onStart).toHaveBeenCalledTimes(1)
+  })
+
+  it('normalizes native playback errors without exposing animation id', async () => {
+    const animation = await createAnimation()
+    const onError = vi.fn()
+    animation.setCallbacks({ onError })
+    const receiver = SpatialWebEvent.eventReceiver[animation.id]
+
+    receiver?.({
+      detail: {
+        animationId: animation.id,
+        action: 'error',
+        playState: 'idle',
+        finished: false,
+        error: {
+          code: 'mask-conflict',
+          message: 'Another animation is already writing this target',
+        },
+      },
+    })
+
+    expect(onError).toHaveBeenCalledWith({
+      command: 'play',
+      code: 'mask-conflict',
+      reason: 'Another animation is already writing this target',
+    })
+  })
+
+  it.each(['stop', 'reset', 'finish'] as const)(
+    'does not re-fire onStart after %s until native terminal event arrives',
+    async controlType => {
+      const animation = await createAnimation()
+      const onStart = vi.fn()
+      animation.setCallbacks({ onStart })
+      const receiver = SpatialWebEvent.eventReceiver[animation.id]
+
+      receiver?.({
+        detail: {
+          animationId: animation.id,
+          action: 'start',
+          playState: 'running',
+          finished: false,
+          values: { transform: { translate: { x: 1 } } },
+        },
+      })
+      expect(onStart).toHaveBeenCalledTimes(1)
+
+      await animation[controlType]()
+
+      receiver?.({
+        detail: {
+          animationId: animation.id,
+          action: 'start',
+          playState: 'running',
+          finished: false,
+          values: { transform: { translate: { x: 2 } } },
+        },
+      })
+      expect(onStart).toHaveBeenCalledTimes(1)
+
+      receiver?.({
+        detail: {
+          animationId: animation.id,
+          action: controlType,
+          playState: controlType === 'finish' ? 'finished' : 'idle',
+          finished: controlType === 'finish',
+          values: { transform: { translate: { x: 3 } } },
+        },
+      })
+
+      receiver?.({
+        detail: {
+          animationId: animation.id,
+          action: 'start',
+          playState: 'running',
+          finished: false,
+          values: { transform: { translate: { x: 4 } } },
+        },
+      })
+      expect(onStart).toHaveBeenCalledTimes(2)
+    },
+  )
+
+  it('sends all playback controls to the same native animation id without recreating', async () => {
+    const animation = await createAnimation()
+    spies.createCommandSpy.mockClear()
+
+    await animation.play()
+    await animation.pause()
+    await animation.play()
+    await animation.stop()
+    await animation.reset()
+    await animation.finish()
+
+    expect(spies.createCommandSpy).not.toHaveBeenCalled()
+    expect(spies.controlCommandSpy.mock.calls.map(call => call[0])).toEqual([
+      { animationId: animation.id, type: 'play' },
+      { animationId: animation.id, type: 'pause' },
+      { animationId: animation.id, type: 'play' },
+      { animationId: animation.id, type: 'stop' },
+      { animationId: animation.id, type: 'reset' },
+      { animationId: animation.id, type: 'finish' },
+    ])
+  })
+})
+
+describe('Core exports', () => {
+  it('keeps internal motion architecture objects out of the public Core export surface', async () => {
+    const mod = await import('../index')
+
+    expect((mod as any).AnimationObject).toBeUndefined()
+    expect((mod as any).AnimationObjectChannel).toBeUndefined()
+    expect((mod as any).AnimationObjectBridge).toBeUndefined()
+    expect((mod as any).SpatialObjectBridge).toBeUndefined()
+  })
+
+  it('exports AnimationObject from the motion entrypoint', async () => {
+    const mod = await import('./index')
+
+    expect(mod.AnimationObject).toBeDefined()
+  })
+
+  it('removes legacy animateMotion entry points from spatialized elements', async () => {
+    const mod = await import('../index')
+
+    expect('animateMotion' in mod.Spatialized2DElement.prototype).toBe(false)
+    expect('animateMotion' in mod.SpatializedStatic3DElement.prototype).toBe(
+      false,
+    )
+    expect('animateMotion' in mod.SpatializedDynamic3DElement.prototype).toBe(
+      false,
+    )
+  })
+})