@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/motion/compute/normalize.ts

@@ -0,0 +1,289 @@
+import type { SpatializedVisualValues } from '../../types/motion/spatializedVisual'
+import type { TimingFunction } from '../../types/animation'
+import type {
+  NormalizedSpatializedMotionConfig,
+  SpatializedMotionConfig,
+  SpatializedMotionProperty,
+  SpatializedMotionSegmentConfig,
+  SpatializedMotionTrack,
+  SpatializedMotionTimelineConfig,
+} from '../../types/motion/spatializedMotion'
+
+/**
+ * Flattens visual values into motion-property/value pairs.
+ *
+ * @param values Visual values to inspect.
+ * @param out Collector for discovered motion property samples.
+ */
+function collectScalars(
+  values: SpatializedVisualValues,
+  out: Array<{ property: SpatializedMotionProperty; value: number }>,
+): void {
+  if (values.opacity !== undefined) {
+    out.push({ property: 'opacity', value: values.opacity })
+  }
+  const tr = values.transform
+  if (!tr) return
+  for (const group of ['translate', 'rotate', 'scale'] as const) {
+    const part = tr[group]
+    if (!part) continue
+    for (const axis of ['x', 'y', 'z'] as const) {
+      const v = part[axis]
+      if (v !== undefined) {
+        out.push({
+          property: `transform.${group}.${axis}` as SpatializedMotionProperty,
+          value: v,
+        })
+      }
+    }
+  }
+}
+
+/**
+ * Converts `0%`-style timeline keys into [0, 1] ratios.
+ *
+ * @param key Percentage key from the timeline config.
+ * @returns The normalized ratio represented by the key.
+ */
+function parsePercentageKey(key: string): number {
+  if (!/^\d+(\.\d+)?%$/.test(key)) {
+    throw new Error(`[SpatializedMotion] invalid timeline key "${key}"`)
+  }
+  const ratio = Number(key.slice(0, -1))
+  if (!Number.isFinite(ratio) || ratio < 0 || ratio > 100) {
+    throw new Error(`[SpatializedMotion] invalid timeline key "${key}"`)
+  }
+  return ratio / 100
+}
+
+/**
+ * Desugars shorthand from/to motion config into canonical tracks.
+ *
+ * @param simple Shorthand segment config.
+ * @returns Canonical track-based motion config.
+ */
+export function segmentConfigToMotionConfig(
+  simple: SpatializedMotionSegmentConfig,
+): NormalizedSpatializedMotionConfig {
+  if (!simple.from || !simple.to) {
+    throw new Error(
+      '[SpatializedMotion] top-level from and to are both required',
+    )
+  }
+  const duration = simple.duration ?? 0.3
+  const fromScalars: Array<{
+    property: SpatializedMotionProperty
+    value: number
+  }> = []
+  const toScalars: Array<{
+    property: SpatializedMotionProperty
+    value: number
+  }> = []
+
+  collectScalars(simple.from, fromScalars)
+  collectScalars(simple.to, toScalars)
+
+  const trackMap = new Map<SpatializedMotionProperty, SpatializedMotionTrack>()
+  const properties = new Set([
+    ...fromScalars.map(entry => entry.property),
+    ...toScalars.map(entry => entry.property),
+  ])
+
+  for (const property of properties) {
+    const fromEntry = fromScalars.find(f => f.property === property)
+    const toEntry = toScalars.find(f => f.property === property)
+    if (!fromEntry) {
+      throw new Error(
+        `[SpatializedMotion] missing start boundary for "${property}"`,
+      )
+    }
+    if (!toEntry) {
+      throw new Error(
+        `[SpatializedMotion] missing end boundary for "${property}"`,
+      )
+    }
+    trackMap.set(property, {
+      property,
+      timingFunction: simple.timingFunction,
+      keyframes: [
+        { at: 0, value: fromEntry.value },
+        { at: duration, value: toEntry.value },
+      ],
+    })
+  }
+
+  const tracks = [...trackMap.values()]
+  if (tracks.length === 0) {
+    throw new Error(
+      '[SpatializedMotion.simple] to must include at least one animatable field',
+    )
+  }
+
+  return {
+    duration,
+    tracks,
+    timingFunction: simple.timingFunction,
+    delay: simple.delay,
+    autoStart: simple.autoStart,
+    loop: simple.loop,
+    playbackRate: simple.playbackRate,
+    onStart: simple.onStart,
+    onComplete: simple.onComplete,
+    onStop: simple.onStop,
+    onReset: simple.onReset,
+    onError: simple.onError,
+  }
+}
+
+/**
+ * Desugars percentage-key timeline config into canonical tracks.
+ *
+ * @param config Timeline config using percentage keys.
+ * @returns Canonical track-based motion config.
+ */
+export function desugarTimelineConfig(
+  config: SpatializedMotionTimelineConfig,
+): NormalizedSpatializedMotionConfig {
+  if (Array.isArray(config.timeline) || !config.timeline) {
+    throw new Error('[SpatializedMotion] timeline must be an object')
+  }
+
+  const entries = Object.entries(config.timeline)
+  let hasPercentageKey = false
+  const frames = entries
+    .map(([key, values]) => {
+      if (!values || typeof values !== 'object' || Array.isArray(values)) {
+        throw new Error(`[SpatializedMotion] invalid timeline frame "${key}"`)
+      }
+      if (key === 'from') return { key, atRatio: 0, values }
+      if (key === 'to') return { key, atRatio: 1, values }
+      hasPercentageKey = true
+      return { key, atRatio: parsePercentageKey(key), values }
+    })
+    .sort((a, b) => a.atRatio - b.atRatio)
+
+  // Dev warn: top-level from/to are ignored once a timeline is present.
+  if (config.from !== undefined || config.to !== undefined) {
+    console.warn(
+      '[SpatializedMotion] top-level from/to are ignored because timeline is present',
+    )
+  }
+
+  // Start/end boundary frames are required; this change does not fill missing
+  // boundaries from underlying element style.
+  const hasStartFrame = frames.some(frame => frame.atRatio === 0)
+  const hasEndFrame = frames.some(frame => frame.atRatio === 1)
+  if (!hasStartFrame) {
+    throw new Error(
+      '[SpatializedMotion] timeline must define a start frame (from or 0%)',
+    )
+  }
+  if (!hasEndFrame) {
+    throw new Error(
+      '[SpatializedMotion] timeline must define an end frame (to or 100%)',
+    )
+  }
+
+  if (hasPercentageKey && config.duration === undefined) {
+    throw new Error(
+      '[SpatializedMotion] duration is required when timeline uses percentage keys',
+    )
+  }
+  const duration = config.duration ?? 0.3
+
+  const trackMap = new Map<
+    SpatializedMotionProperty,
+    Array<{
+      at: number
+      value: number
+      timingFunction?: TimingFunction
+    }>
+  >()
+  const fromProperties = new Set<SpatializedMotionProperty>()
+  const zeroProperties = new Set<SpatializedMotionProperty>()
+  const toProperties = new Set<SpatializedMotionProperty>()
+  const hundredProperties = new Set<SpatializedMotionProperty>()
+
+  for (const frame of frames) {
+    const at = frame.atRatio * duration
+    const scalars: Array<{
+      property: SpatializedMotionProperty
+      value: number
+    }> = []
+    collectScalars(frame.values, scalars)
+    for (const scalar of scalars) {
+      if (frame.key === 'from') fromProperties.add(scalar.property)
+      if (frame.key !== 'from' && frame.atRatio === 0) {
+        zeroProperties.add(scalar.property)
+      }
+      if (frame.key === 'to') toProperties.add(scalar.property)
+      if (frame.key !== 'to' && frame.atRatio === 1) {
+        hundredProperties.add(scalar.property)
+      }
+      const keyframes = trackMap.get(scalar.property) ?? []
+      const keyframe = {
+        at,
+        value: scalar.value,
+        ...(frame.values.timingFunction !== undefined
+          ? { timingFunction: frame.values.timingFunction }
+          : {}),
+      }
+      keyframes.push(keyframe)
+      trackMap.set(scalar.property, keyframes)
+    }
+  }
+
+  const tracks = [...trackMap.entries()].map(([property, keyframes]) => {
+    const startCount =
+      Number(fromProperties.has(property)) +
+      Number(zeroProperties.has(property))
+    const endCount =
+      Number(toProperties.has(property)) +
+      Number(hundredProperties.has(property))
+    if (startCount > 1) {
+      throw new Error(
+        `[SpatializedMotion] duplicate start boundary for "${property}"`,
+      )
+    }
+    if (endCount > 1) {
+      throw new Error(
+        `[SpatializedMotion] duplicate end boundary for "${property}"`,
+      )
+    }
+    return {
+      property,
+      timingFunction: config.timingFunction,
+      keyframes,
+    }
+  })
+
+  return {
+    duration,
+    tracks,
+    timingFunction: config.timingFunction,
+    delay: config.delay,
+    autoStart: config.autoStart,
+    loop: config.loop,
+    playbackRate: config.playbackRate,
+    onStart: config.onStart,
+    onComplete: config.onComplete,
+    onStop: config.onStop,
+    onReset: config.onReset,
+    onError: config.onError,
+  }
+}
+
+/**
+ * Normalizes any supported motion config shape into canonical tracks.
+ *
+ * @param config Motion config in shorthand, timeline, or canonical form.
+ * @returns Canonical track-based motion config.
+ */
+export function normalizeMotionConfig(
+  config: SpatializedMotionConfig,
+): NormalizedSpatializedMotionConfig {
+  if (config.timeline !== undefined) {
+    return desugarTimelineConfig(config as SpatializedMotionTimelineConfig)
+  }
+  return segmentConfigToMotionConfig(config as SpatializedMotionSegmentConfig)
+}

package/src/motion/compute/validate.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, test, vi } from 'vitest'
+import {
+  validateNormalizedMotionConfig,
+  validateSpatializedMotionConfig,
+} from './validate'
+
+describe('validateNormalizedMotionConfig', () => {
+  test('accepts a canonical track-based motion config', () => {
+    expect(() =>
+      validateNormalizedMotionConfig({
+        duration: 1,
+        tracks: [
+          {
+            property: 'transform.translate.x',
+            keyframes: [
+              { at: 0, value: 0 },
+              { at: 1, value: 10 },
+            ],
+          },
+        ],
+      }),
+    ).not.toThrow()
+  })
+
+  test('accepts opacity tracks', () => {
+    expect(() =>
+      validateNormalizedMotionConfig({
+        duration: 1,
+        tracks: [
+          {
+            property: 'opacity',
+            keyframes: [
+              { at: 0, value: 0 },
+              { at: 1, value: 1 },
+            ],
+          },
+        ],
+      }),
+    ).not.toThrow()
+  })
+})
+
+describe('validateSpatializedMotionConfig', () => {
+  test('accepts complete top-level segment authoring', () => {
+    expect(() =>
+      validateSpatializedMotionConfig({
+        from: { opacity: 0 },
+        to: { opacity: 1 },
+      }),
+    ).not.toThrow()
+  })
+
+  test.each([{ to: { opacity: 1 } }, { from: { opacity: 0 } }])(
+    'rejects incomplete top-level segment authoring',
+    config => {
+      expect(() => validateSpatializedMotionConfig(config as never)).toThrow(
+        /top-level from and to are both required/,
+      )
+    },
+  )
+
+  test('accepts a timeline without top-level boundaries', () => {
+    expect(() =>
+      validateSpatializedMotionConfig({
+        duration: 1,
+        timeline: {
+          from: { opacity: 0 },
+          '50%': { opacity: 0.5 },
+          to: { opacity: 1 },
+        },
+      }),
+    ).not.toThrow()
+  })
+
+  test('accepts decimal spellings of percentage boundaries', () => {
+    expect(() =>
+      validateSpatializedMotionConfig({
+        duration: 1,
+        timeline: {
+          '0.0%': { opacity: 0 },
+          '100.0%': { opacity: 1 },
+        },
+      }),
+    ).not.toThrow()
+  })
+
+  test('ignores top-level boundaries when timeline is present', () => {
+    expect(() =>
+      validateSpatializedMotionConfig({
+        duration: 1,
+        from: { opacity: Number.NaN },
+        to: { opacity: Number.NaN },
+        timeline: {
+          '0%': { opacity: 0 },
+          '100%': { opacity: 1 },
+        },
+      }),
+    ).not.toThrow()
+  })
+
+  test('rejects a timeline missing the start frame', () => {
+    expect(() =>
+      validateSpatializedMotionConfig({
+        duration: 1,
+        timeline: { '50%': { opacity: 0.5 }, to: { opacity: 1 } },
+      }),
+    ).toThrow(/must define a start frame/)
+  })
+
+  test('rejects a timeline missing the end frame', () => {
+    expect(() =>
+      validateSpatializedMotionConfig({
+        duration: 1,
+        timeline: { from: { opacity: 0 }, '50%': { opacity: 0.5 } },
+      }),
+    ).toThrow(/must define an end frame/)
+  })
+
+  test('warns when top-level from/to coexist with a timeline', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    validateSpatializedMotionConfig({
+      duration: 1,
+      from: { opacity: 0.25 },
+      to: { opacity: 0.75 },
+      timeline: {
+        '0%': { opacity: 0 },
+        '100%': { opacity: 1 },
+      },
+    })
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('top-level from/to are ignored'),
+    )
+    warnSpy.mockRestore()
+  })
+
+  test('rejects a property with only one keyframe', () => {
+    // Timeline has overall start/end frames (opacity at 0% and 100%), but the
+    // rotate.z property appears only once at 50%, which is fewer than two keyframes.
+    expect(() =>
+      validateSpatializedMotionConfig({
+        duration: 1,
+        timeline: {
+          '0%': { opacity: 0 },
+          '50%': { transform: { rotate: { z: 45 } } },
+          '100%': { opacity: 1 },
+        },
+      }),
+    ).toThrow(/track "transform.rotate.z" needs at least 2 keyframes/)
+  })
+
+  test.each([
+    {
+      duration: 1,
+      timeline: {
+        from: { opacity: 0 },
+        '0%': { opacity: 0 },
+        to: { opacity: 1 },
+      },
+      expected: /duplicate start boundary.*opacity/,
+    },
+    {
+      duration: 1,
+      timeline: {
+        from: { opacity: 0 },
+        to: { opacity: 1 },
+        '100%': { opacity: 1 },
+      },
+      expected: /duplicate end boundary.*opacity/,
+    },
+  ])('rejects duplicate property boundaries', config => {
+    expect(() => validateSpatializedMotionConfig(config as never)).toThrow(
+      config.expected,
+    )
+  })
+
+  test.each([
+    ['0%', '00%'],
+    ['0%', '0.0%'],
+    ['50%', '050.0%'],
+  ])(
+    'rejects equivalent percentage keys %s and %s for the same property',
+    (firstKey, secondKey) => {
+      expect(() =>
+        validateSpatializedMotionConfig({
+          duration: 1,
+          timeline: {
+            '0%': { opacity: 0 },
+            [firstKey]: { opacity: 0.25 },
+            [secondKey]: { opacity: 0.25 },
+            '100%': { opacity: 1 },
+          },
+        }),
+      ).toThrow(/keyframe times must be strictly increasing.*opacity/)
+    },
+  )
+
+  test('accepts equivalent percentage keys for different properties', () => {
+    expect(() =>
+      validateSpatializedMotionConfig({
+        duration: 1,
+        timeline: {
+          '0%': { opacity: 0 },
+          '0.0%': { transform: { translate: { x: 0 } } },
+          '100%': {
+            opacity: 1,
+            transform: { translate: { x: 1 } },
+          },
+        },
+      }),
+    ).not.toThrow()
+  })
+
+  test('rejects public tracks authoring', () => {
+    expect(() =>
+      validateSpatializedMotionConfig({
+        duration: 1,
+        tracks: [
+          {
+            property: 'opacity',
+            keyframes: [
+              { at: 0, value: 0 },
+              { at: 1, value: 1 },
+            ],
+          },
+        ],
+      } as never),
+    ).toThrow(/tracks authoring is internal/)
+  })
+})

package/src/motion/compute/validate.ts

@@ -0,0 +1,156 @@
+import { SPATIALIZED_MOTION_PROPERTIES } from '../../types/motion/spatializedMotion'
+import type {
+  NormalizedSpatializedMotionConfig,
+  SpatializedMotionProperty,
+  SpatializedMotionConfig,
+  SpatializedMotionTrack,
+} from '../../types/motion/spatializedMotion'
+import { normalizeMotionConfig } from './normalize'
+const ALLOWED_PROPERTIES = new Set<SpatializedMotionProperty>(
+  SPATIALIZED_MOTION_PROPERTIES,
+)
+
+const FORBIDDEN_PREFIXES = [
+  'width',
+  'height',
+  'back',
+  'backOffset',
+  'depth',
+] as const
+
+/**
+ * Validates any supported motion config shape before playback or serialization.
+ *
+ * @param config Motion config in any supported input shape.
+ */
+export function validateSpatializedMotionConfig(
+  config: SpatializedMotionConfig,
+): void {
+  if (config.tracks !== undefined) {
+    throw new Error('[SpatializedMotion] tracks authoring is internal')
+  }
+  const normalized = normalizeMotionConfig(config)
+  validateNormalizedMotionConfig(normalized)
+}
+
+/**
+ * Validates the canonical track-based motion config form.
+ *
+ * @param config Canonical motion config to validate.
+ */
+export function validateNormalizedMotionConfig(
+  config: NormalizedSpatializedMotionConfig,
+): void {
+  const { duration, tracks } = config
+
+  if (
+    typeof duration !== 'number' ||
+    !Number.isFinite(duration) ||
+    duration <= 0
+  ) {
+    throw new Error('[SpatializedMotion] duration must be a finite number > 0')
+  }
+
+  if (!Array.isArray(tracks) || tracks.length === 0) {
+    throw new Error('[SpatializedMotion] tracks must be a non-empty array')
+  }
+
+  const seen = new Set<string>()
+  for (const track of tracks) {
+    validateTrack(track, duration, seen)
+  }
+
+  if (config.delay !== undefined) {
+    const d = config.delay
+    if (typeof d !== 'number' || !Number.isFinite(d) || d < 0) {
+      throw new Error('[SpatializedMotion] delay must be >= 0 and finite')
+    }
+  }
+
+  if (config.playbackRate !== undefined) {
+    const r = config.playbackRate
+    if (typeof r !== 'number' || !Number.isFinite(r) || r <= 0) {
+      throw new Error('[SpatializedMotion] playbackRate must be > 0 and finite')
+    }
+  }
+}
+
+/**
+ * Validates a single track against property and keyframe invariants.
+ *
+ * @param track Motion track to validate.
+ * @param duration Parent motion duration.
+ * @param seen Track-property set used to detect duplicates.
+ */
+function validateTrack(
+  track: SpatializedMotionTrack,
+  duration: number,
+  seen: Set<string>,
+): void {
+  const prop = track.property as string
+  for (const forbidden of FORBIDDEN_PREFIXES) {
+    if (prop === forbidden || prop.startsWith(`${forbidden}.`)) {
+      throw new Error(
+        `[SpatializedMotion] property "${prop}" is not animatable`,
+      )
+    }
+  }
+
+  if (!ALLOWED_PROPERTIES.has(track.property)) {
+    throw new Error(`[SpatializedMotion] unknown property "${prop}"`)
+  }
+
+  if (seen.has(prop)) {
+    throw new Error(`[SpatializedMotion] duplicate track for "${prop}"`)
+  }
+  seen.add(prop)
+
+  const kf = track.keyframes
+  if (!Array.isArray(kf) || kf.length < 2) {
+    throw new Error(
+      `[SpatializedMotion] track "${prop}" needs at least 2 keyframes`,
+    )
+  }
+
+  let prevAt = -Infinity
+  for (const frame of kf) {
+    if (typeof frame.at !== 'number' || !Number.isFinite(frame.at)) {
+      throw new Error(
+        `[SpatializedMotion] keyframe.at must be finite for "${prop}"`,
+      )
+    }
+    if (frame.at < 0 || frame.at > duration) {
+      throw new Error(
+        `[SpatializedMotion] keyframe.at must be within [0, duration] for "${prop}"`,
+      )
+    }
+    if (frame.at <= prevAt) {
+      throw new Error(
+        `[SpatializedMotion] keyframe times must be strictly increasing for "${prop}"`,
+      )
+    }
+    prevAt = frame.at
+    validateScalar(frame.value, track.property)
+  }
+}
+
+/**
+ * Validates a numeric sample for a specific motion property.
+ *
+ * @param value Numeric sample value to validate.
+ * @param property Motion property the value belongs to.
+ */
+function validateScalar(
+  value: number,
+  property: SpatializedMotionProperty,
+): void {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`[SpatializedMotion] invalid value for ${property}`)
+  }
+  if (property === 'opacity' && (value < 0 || value > 1)) {
+    throw new Error('[SpatializedMotion] opacity must be in [0, 1]')
+  }
+  if (property.startsWith('transform.scale.') && value < 0) {
+    throw new Error('[SpatializedMotion] scale must be >= 0')
+  }
+}

package/src/motion/index.ts

@@ -0,0 +1,2 @@
+export * from './AnimationObject'
+export { validateSpatializedMotionConfig } from './compute/validate'