@webspatial/core-sdk 1.7.0 → 2.0.0

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'

package/src/motion/native/serializeMotionTimeline.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'vitest'
+import { motionConfigToNativeTimeline } from './serializeMotionTimeline'
+
+describe('motionConfigToNativeTimeline', () => {
+  test('builds timeline payload for multi-track', () => {
+    const tl = motionConfigToNativeTimeline({
+      duration: 5,
+      tracks: [
+        {
+          property: 'transform.translate.x',
+          keyframes: [
+            { at: 0, value: 0 },
+            { at: 5, value: 100 },
+          ],
+        },
+        {
+          property: 'opacity',
+          timingFunction: 'easeOut',
+          keyframes: [
+            { at: 3, value: 0 },
+            { at: 5, value: 1 },
+          ],
+        },
+      ],
+    })
+    expect(tl.duration).toBe(5)
+    expect(tl.tracks).toHaveLength(2)
+    expect(tl.tracks[1].timingFunction).toBe('easeOut')
+  })
+
+  test('serializes keyframe and config timingFunction propagation', () => {
+    const tl = motionConfigToNativeTimeline({
+      duration: 4,
+      timingFunction: 'easeInOut',
+      tracks: [
+        {
+          property: 'transform.translate.x',
+          keyframes: [
+            { at: 0, value: 0, timingFunction: 'easeOut' },
+            { at: 2, value: 100 },
+            { at: 4, value: 200 },
+          ],
+        },
+        {
+          property: 'opacity',
+          keyframes: [
+            { at: 0, value: 0 },
+            { at: 4, value: 1 },
+          ],
+        },
+      ],
+    })
+
+    expect(tl.tracks[0].keyframes[0]).toMatchObject({
+      at: 0,
+      value: 0,
+      timingFunction: 'easeOut',
+    })
+    expect(tl.tracks[1].timingFunction).toBe('easeInOut')
+  })
+})

package/src/motion/native/serializeMotionTimeline.ts

@@ -0,0 +1,27 @@
+import type {
+  NormalizedSpatializedMotionConfig,
+  SpatializedMotionTimeline,
+} from '../../types/motion/spatializedMotion'
+
+/** Full timeline payload for native. */
+export function motionConfigToNativeTimeline(
+  config: NormalizedSpatializedMotionConfig,
+): SpatializedMotionTimeline {
+  return {
+    duration: config.duration,
+    delay: config.delay,
+    playbackRate: config.playbackRate,
+    loop: config.loop,
+    tracks: config.tracks.map(track => ({
+      property: track.property,
+      keyframes: track.keyframes.map(k => ({
+        at: k.at,
+        value: k.value,
+        ...(k.timingFunction !== undefined
+          ? { timingFunction: k.timingFunction }
+          : {}),
+      })),
+      timingFunction: track.timingFunction ?? config.timingFunction ?? 'linear',
+    })),
+  }
+}

package/src/platform-adapter/createPlatformSync.ts

@@ -1,11 +1,13 @@
 import { resolveJsbAdapterPlatform } from '../runtime/jsbAdapterPlatform'
-import { isSSREnv } from '../ssr-polyfill'
+import { isSSREnv } from '../isSSREnv'
 import { PlatformAbility } from './interface'
 import { PicoOSPlatform } from './pico-os/PicoOSPlatform'
 import { PuppeteerPlatform } from './puppeteer/PuppeteerPlatform'
-import { SSRPlatform } from './ssr/SSRPlatform'
 import { VisionOSPlatform } from './vision-os/VisionOSPlatform'
 
+const SSR_PLATFORM_ERROR =
+  'WebSpatial platform APIs (JSB / openSpatialScene) cannot run during SSR or without window. Use @webspatial/react-sdk default entry with facades, or CSR-gate spatial UI on the client.'
+
 function assertNever(_: never): never {
   throw new Error('Unhandled jsb adapter platform kind')
 }
@@ -17,7 +19,7 @@ function assertNever(_: never): never {
  */
 export function createPlatformSync(): PlatformAbility {
   if (isSSREnv()) {
-    return new SSRPlatform()
+    throw new Error(SSR_PLATFORM_ERROR)
   }
   const userAgent = window.navigator.userAgent
   const kind = resolveJsbAdapterPlatform(userAgent)

package/src/platform-adapter/pico-os/PicoOSPlatform.ts

@@ -11,6 +11,11 @@ import { buildSpatialSceneQuery } from '../spatialSceneQuery'
 import { SpatialWebEvent } from '../../SpatialWebEvent'
 import type { SpatialSceneCreationOptionsInternal } from '../../types/internal'
 import type { AttachmentEntityOptions } from '../../types/types'
+import {
+  buildSpatialRequestQuery,
+  createSpatialRequestId,
+  DEFAULT_SPATIAL_REQUEST_TIMEOUT_MS,
+} from '../spatialRequestMetadata'
 
 interface JSBResponse {
   success: boolean
@@ -95,26 +100,86 @@ export class PicoOSPlatform implements PlatformAbility {
     command: string,
   ): Promise<WebSpatialProtocolResult> {
     return new Promise(resolve => {
-      const createdId = nextRequestId()
+      const createdId = createSpatialRequestId()
+      let settled = false
+      let timeoutId: ReturnType<typeof setTimeout> | undefined
+      let cleanupDocumentReadyListener: (() => void) | undefined
+
+      // Native creation may respond synchronously, asynchronously, or never.
+      // Funnel every path through one settle() helper so receiver cleanup is
+      // exactly-once.
+      const settle = (result: WebSpatialProtocolResult) => {
+        if (settled) return
+        settled = true
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId)
+        }
+        cleanupDocumentReadyListener?.()
+        cleanupDocumentReadyListener = undefined
+        SpatialWebEvent.removeEventReceiver(createdId)
+        resolve(result)
+      }
+
       try {
         let windowProxy: WindowProxy | null = null
+        const settleWhenDocumentComplete = (spatialId: string) => {
+          const successResult = CommandResultSuccess({
+            windowProxy: windowProxy,
+            id: spatialId,
+          })
+          const childDocument = windowProxy?.document
+
+          if (!childDocument) {
+            settle(
+              CommandResultFailure(
+                'E_SPATIAL_DOCUMENT_UNAVAILABLE',
+                `${command} document is unavailable`,
+              ),
+            )
+            return
+          }
+
+          if (childDocument.readyState === 'complete') {
+            settle(successResult)
+            return
+          }
+
+          const onReadyStateChange = () => {
+            if (childDocument.readyState !== 'complete') return
+            settle(successResult)
+          }
+
+          cleanupDocumentReadyListener = () => {
+            childDocument.removeEventListener(
+              'readystatechange',
+              onReadyStateChange,
+            )
+          }
+          childDocument.addEventListener('readystatechange', onReadyStateChange)
+        }
+
+        timeoutId = setTimeout(() => {
+          settle(
+            CommandResultFailure(
+              'E_SPATIAL_REQUEST_TIMEOUT',
+              `${command} request timed out`,
+            ),
+          )
+        }, DEFAULT_SPATIAL_REQUEST_TIMEOUT_MS)
+
         SpatialWebEvent.addEventReceiver(
           createdId,
           (result: { spatialId: string }) => {
-            resolve(
-              CommandResultSuccess({
-                windowProxy: windowProxy,
-                id: result.spatialId,
-              }),
-            )
-            SpatialWebEvent.removeEventReceiver(createdId)
+            settleWhenDocumentComplete(result.spatialId)
           },
         )
-        windowProxy = this.openWindow(command, 'rid=' + createdId).windowProxy
+        windowProxy = this.openWindow(
+          command,
+          buildSpatialRequestQuery(createdId),
+        ).windowProxy
       } catch (error: unknown) {
         const { code, message } = this.parseJSBError(error)
-        SpatialWebEvent.removeEventReceiver(createdId)
-        resolve(CommandResultFailure(code, message))
+        settle(CommandResultFailure(code, message))
       }
     })
   }