@webspatial/core-sdk 1.7.0 → 2.0.0

package/src/jsbcommand.coverage.test.ts

@@ -128,6 +128,7 @@ describe('JSBCommand', () => {
   it('builds element commands payloads', async () => {
     const mod = await import('./JSBCommand')
     const {
+      CreateSpatializedElementAnimationJSBCommand,
       UpdateSpatializedElementTransform,
       UpdateSpatialized2DElementProperties,
       UpdateSpatializedDynamic3DElementProperties,
@@ -185,6 +186,18 @@ 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',
@@ -412,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')
@@ -440,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,
+    )
+  })
+})

package/src/motion/AnimationObject.ts

@@ -0,0 +1,208 @@
+import {
+  ControlSpatializedElementAnimationJSBCommand,
+  CreateSpatializedElementAnimationJSBCommand,
+} from '../JSBCommand'
+import { SpatialObject } from '../SpatialObject'
+import { SpatialWebEvent } from '../SpatialWebEvent'
+import type {
+  ControlSpatializedElementAnimationCommand,
+  SpatialAnimationStateChangedDetail,
+  SpatialAnimationStateChangedMsg,
+} from '../types/motion/spatializedElementMotion'
+import type { SpatializedPlaybackError } from '../types/motion/spatializedPlayback'
+import type { SpatializedVisualValues } from '../types/motion/spatializedVisual'
+import type {
+  SpatializedMotionTimeline,
+  SpatializedPlaybackApi,
+  SpatializedMotionPlayState,
+} from '../types/motion/spatializedMotion'
+
+export interface AnimationObjectCreateOptions {
+  elementId: string
+  timeline: SpatializedMotionTimeline
+}
+
+export interface AnimationObjectCallbacks {
+  onStart?: () => void
+  onComplete?: (values: SpatializedVisualValues) => void
+  onStop?: (values: SpatializedVisualValues) => void
+  onReset?: (values: SpatializedVisualValues) => void
+  onError?: (error: SpatializedPlaybackError) => void
+  onValuesChange?: (values: SpatializedVisualValues) => void
+  onStateChange?: () => void
+}
+
+export class AnimationObject
+  extends SpatialObject
+  implements SpatializedPlaybackApi
+{
+  readonly elementId: string
+  readonly timeline: SpatializedMotionTimeline
+
+  private callbacks: AnimationObjectCallbacks = {}
+  private _playState: SpatializedMotionPlayState = 'idle'
+  private _finished = false
+  private started = false
+
+  constructor(id: string, options: AnimationObjectCreateOptions) {
+    super(id)
+    this.elementId = options.elementId
+    this.timeline = options.timeline
+
+    SpatialWebEvent.addEventReceiver(id, data => this.onReceiveEvent(data))
+  }
+
+  static async create(options: AnimationObjectCreateOptions) {
+    const ret = await new CreateSpatializedElementAnimationJSBCommand({
+      elementId: options.elementId,
+      timeline: options.timeline,
+    }).execute()
+    if (!ret.success) {
+      throw new Error(
+        ret.errorMessage ?? 'CreateSpatializedElementAnimation command failed',
+      )
+    }
+
+    const data = ret.data as { id?: string } | undefined
+    const id = data?.id
+    if (!id) {
+      throw new Error('CreateSpatializedElementAnimation did not return an id')
+    }
+
+    return new AnimationObject(id, options)
+  }
+
+  setCallbacks(callbacks: AnimationObjectCallbacks): void {
+    this.callbacks = callbacks
+  }
+
+  get playState() {
+    return this._playState
+  }
+
+  get isAnimating() {
+    return this._playState === 'running' || this._playState === 'queued'
+  }
+
+  get isPaused() {
+    return this._playState === 'paused'
+  }
+
+  get finished() {
+    return this._finished
+  }
+
+  play(): Promise<void> {
+    return this.control('play')
+  }
+
+  pause(): Promise<void> {
+    return this.control('pause')
+  }
+
+  stop(): Promise<void> {
+    return this.control('stop')
+  }
+
+  reset(): Promise<void> {
+    return this.control('reset')
+  }
+
+  finish(): Promise<void> {
+    return this.control('finish')
+  }
+
+  protected override onDestroy(): void {
+    SpatialWebEvent.removeEventReceiver(this.id)
+  }
+
+  private async control(
+    type: ControlSpatializedElementAnimationCommand['type'],
+  ): Promise<void> {
+    if (this.isDestroyed) return
+
+    const ret = await new ControlSpatializedElementAnimationJSBCommand({
+      animationId: this.id,
+      type,
+    }).execute()
+
+    if (!ret.success) {
+      throw new Error(
+        ret.errorMessage ??
+          `ControlSpatializedElementAnimation(${type}) command failed`,
+      )
+    }
+  }
+
+  onReceiveEvent(data: SpatialAnimationStateChangedMsg | { detail?: unknown }) {
+    const detail = data?.detail ?? data
+    if (!this.isSpatialAnimationStateChangedDetail(detail)) return
+    if (detail.animationId !== this.id) return
+
+    this._playState = detail.playState
+    this._finished = detail.finished
+
+    if (detail.values) {
+      this.callbacks.onValuesChange?.(detail.values)
+    }
+    if (detail.action !== 'start') {
+      this.callbacks.onStateChange?.()
+    }
+
+    if (detail.error) {
+      this.started = false
+      // Native currently emits asynchronous errors only when play cannot acquire the ownership mask.
+      this.callbacks.onError?.({
+        command: 'play',
+        code: detail.error.code,
+        reason: detail.error.message,
+      })
+      return
+    }
+
+    if (detail.action === 'start') {
+      if (!this.started) {
+        this.started = true
+        this.callbacks.onStart?.()
+      }
+      return
+    }
+
+    if (detail.action === 'complete' || detail.action === 'finish') {
+      this.started = false
+      this.callbacks.onComplete?.(detail.values ?? {})
+      return
+    }
+
+    if (detail.action === 'stop') {
+      this.started = false
+      this.callbacks.onStop?.(detail.values ?? {})
+      return
+    }
+
+    if (detail.action === 'reset') {
+      this.started = false
+      this.callbacks.onReset?.(detail.values ?? {})
+      return
+    }
+
+    if (detail.action === 'destroy') {
+      this.started = false
+      this.isDestroyed = true
+      this.onDestroy()
+    }
+  }
+
+  private isSpatialAnimationStateChangedDetail(
+    detail: unknown,
+  ): detail is SpatialAnimationStateChangedDetail {
+    if (!detail || typeof detail !== 'object') return false
+    const candidate = detail as Partial<SpatialAnimationStateChangedDetail>
+    return (
+      typeof candidate.animationId === 'string' &&
+      typeof candidate.action === 'string' &&
+      typeof candidate.playState === 'string' &&
+      typeof candidate.finished === 'boolean'
+    )
+  }
+}

package/src/motion/compute/index.ts

@@ -0,0 +1,10 @@
+export { setMotionPropertyValue } from './motionPropertyValues'
+export {
+  validateNormalizedMotionConfig,
+  validateSpatializedMotionConfig,
+} from './validate'
+export {
+  desugarTimelineConfig,
+  normalizeMotionConfig,
+  segmentConfigToMotionConfig,
+} from './normalize'