@webspatial/core-sdk 1.7.0 → 2.0.0

package/src/types/motion/spatializedElementMotion.ts

@@ -0,0 +1,49 @@
+import type { SpatializedMotionTimeline } from './spatializedMotion'
+import type { SpatializedMotionPlayState } from './spatializedMotion'
+import type { SpatializedVisualValues } from './spatializedVisual'
+import type { SpatialWebMsgType } from '../../WebMsgCommand'
+
+/** Native playback error payload carried by the bridge event. */
+interface SpatializedElementAnimationErrorDetail {
+  /** Machine-readable native error code. */
+  code: string
+  /** Human-readable native error message. */
+  message: string
+}
+
+export interface CreateSpatializedElementAnimationCommand {
+  elementId: string
+  timeline: SpatializedMotionTimeline
+}
+
+export type SpatializedElementAnimationControlType =
+  | 'play'
+  | 'pause'
+  | 'resume'
+  | 'stop'
+  | 'reset'
+  | 'finish'
+  | 'destroy'
+
+export interface ControlSpatializedElementAnimationCommand {
+  animationId: string
+  type: SpatializedElementAnimationControlType
+}
+
+export interface SpatialAnimationStateChangedDetail {
+  animationId: string
+  action:
+    | SpatializedElementAnimationControlType
+    | 'start'
+    | 'complete'
+    | 'error'
+  playState: SpatializedMotionPlayState
+  finished: boolean
+  values?: SpatializedVisualValues
+  error?: SpatializedElementAnimationErrorDetail
+}
+
+export interface SpatialAnimationStateChangedMsg {
+  type: SpatialWebMsgType.animationstatechange
+  detail: SpatialAnimationStateChangedDetail
+}

package/src/types/motion/spatializedMotion.ts

@@ -0,0 +1,147 @@
+import type { TimingFunction } from '../animation'
+import type { SpatializedPlaybackError } from './spatializedPlayback'
+import type { SpatializedVisualValues } from './spatializedVisual'
+
+/** Spatialized container kinds with declarative timeline motion. */
+export type SpatializedMotionKind = 'spatialized2d' | 'static3d' | 'dynamic3d'
+
+/** Scalar property path on the spatialized visual whitelist. */
+export const SPATIALIZED_MOTION_PROPERTIES = [
+  'opacity',
+  'transform.translate.x',
+  'transform.translate.y',
+  'transform.translate.z',
+  'transform.rotate.x',
+  'transform.rotate.y',
+  'transform.rotate.z',
+  'transform.scale.x',
+  'transform.scale.y',
+  'transform.scale.z',
+] as const
+
+export type SpatializedMotionProperty =
+  (typeof SPATIALIZED_MOTION_PROPERTIES)[number]
+
+export interface SpatializedMotionKeyframe {
+  /** Time in seconds from timeline start, in `[0, duration]`. */
+  at: number
+  value: number
+  timingFunction?: TimingFunction
+}
+
+export type SpatializedMotionKeyframeValues = SpatializedVisualValues & {
+  timingFunction?: TimingFunction
+}
+
+/** One animatable property path and its keyframes (config-only, not a runtime handle). */
+export interface SpatializedMotionTrack {
+  property: SpatializedMotionProperty
+  keyframes: SpatializedMotionKeyframe[]
+  timingFunction?: TimingFunction
+}
+
+/** Single-segment motion: `from` → `to` over `duration`. */
+export interface SpatializedMotionSegmentConfig {
+  to: SpatializedVisualValues
+  from: SpatializedVisualValues
+  tracks?: never
+  timeline?: never
+  duration?: number
+  timingFunction?: TimingFunction
+  delay?: number
+  autoStart?: boolean
+  loop?: boolean | { reverse?: boolean }
+  playbackRate?: number
+  onStart?: () => void
+  onComplete?: (values: SpatializedVisualValues) => void
+  onStop?: (values: SpatializedVisualValues) => void
+  onReset?: (values: SpatializedVisualValues) => void
+  onError?: (error: SpatializedPlaybackError) => void
+}
+
+/** Percentage-keyframe timeline authoring shape before desugaring. */
+export interface SpatializedMotionTimelineConfig {
+  duration?: number
+  timeline: Record<string, SpatializedMotionKeyframeValues>
+  /** Ignored when timeline authoring is present. */
+  from?: SpatializedVisualValues
+  /** Ignored when timeline authoring is present. */
+  to?: SpatializedVisualValues
+  tracks?: never
+  timingFunction?: TimingFunction
+  delay?: number
+  autoStart?: boolean
+  loop?: boolean | { reverse?: boolean }
+  playbackRate?: number
+  onStart?: () => void
+  onComplete?: (values: SpatializedVisualValues) => void
+  onStop?: (values: SpatializedVisualValues) => void
+  onReset?: (values: SpatializedVisualValues) => void
+  onError?: (error: SpatializedPlaybackError) => void
+}
+
+/** Public authoring accepted by spatialized container motion. */
+export type SpatializedMotionConfig =
+  | SpatializedMotionSegmentConfig
+  | SpatializedMotionTimelineConfig
+
+/** Canonical internal track document produced before native create. */
+export interface NormalizedSpatializedMotionConfig {
+  /** Timeline duration in seconds. */
+  duration: number
+  /** Canonical per-property numeric tracks. */
+  tracks: SpatializedMotionTrack[]
+  /** Default interpolation for tracks without an override. */
+  timingFunction?: TimingFunction
+  /** Playback delay in seconds. */
+  delay?: number
+  /** Whether playback starts automatically after binding. */
+  autoStart?: boolean
+  /** Loop behavior for the animation session. */
+  loop?: boolean | { reverse?: boolean }
+  /** Playback speed multiplier. */
+  playbackRate?: number
+  /** Called when playback starts. */
+  onStart?: () => void
+  /** Called when playback completes. */
+  onComplete?: (values: SpatializedVisualValues) => void
+  /** Called when playback stops. */
+  onStop?: (values: SpatializedVisualValues) => void
+  /** Called when playback resets. */
+  onReset?: (values: SpatializedVisualValues) => void
+  /** Called when asynchronous playback fails. */
+  onError?: (error: SpatializedPlaybackError) => void
+}
+
+/** Normalized timeline wire payload for native playback. */
+export interface SpatializedMotionTimeline {
+  duration: number
+  delay?: number
+  playbackRate?: number
+  loop?: boolean | { reverse?: boolean }
+  tracks: Array<{
+    property: SpatializedMotionProperty
+    keyframes: SpatializedMotionKeyframe[]
+    timingFunction: TimingFunction
+  }>
+}
+
+export type SpatializedMotionPlayState =
+  | 'idle'
+  | 'queued'
+  | 'running'
+  | 'paused'
+  | 'finished'
+
+/** Public imperative playback controls exposed to spatialized motion consumers. */
+export interface SpatializedPlaybackApi {
+  play(): void
+  pause(): void
+  stop(): void
+  reset(): void
+  finish(): void
+  readonly isAnimating: boolean
+  readonly isPaused: boolean
+  readonly finished: boolean
+  readonly playState: SpatializedMotionPlayState
+}

package/src/types/motion/spatializedPlayback.ts

@@ -0,0 +1,17 @@
+/** Async playback failure from native bridge. */
+export interface SpatializedPlaybackError {
+  /** Operation that failed. */
+  command:
+    | 'create'
+    | 'play'
+    | 'pause'
+    | 'resume'
+    | 'stop'
+    | 'reset'
+    | 'finish'
+    | 'destroy'
+  /** Native or SDK error code when available. */
+  code?: string
+  /** Human-readable failure reason. */
+  reason: string
+}

package/src/types/motion/spatializedVisual.ts

@@ -0,0 +1,24 @@
+// ---- Spatialized element visual value model (segment + timeline motion) ----
+
+/**
+ * Structured visual transform for a spatialized container element.
+ * Composed in fixed order: translate → rotate → scale.
+ * Does NOT support arbitrary CSS transform strings, skew, perspective, or matrix interpolation.
+ */
+export interface SpatializedVisualTransform {
+  /** Translation in CSS pixels. */
+  translate?: { x?: number; y?: number; z?: number }
+  /** Rotation in degrees, aligning with CSS rotateX/Y/Z(). */
+  rotate?: { x?: number; y?: number; z?: number }
+  /** Scale as unitless multipliers, aligning with CSS scaleX/Y/Z(). */
+  scale?: { x?: number; y?: number; z?: number }
+}
+
+/**
+ * Whitelisted visual fields on a spatialized element at an instant in time.
+ * Does not include layout/size fields (width, height, back, depth).
+ */
+export interface SpatializedVisualValues {
+  transform?: SpatializedVisualTransform
+  opacity?: number
+}

package/src/types/types.ts

@@ -102,11 +102,14 @@ export interface ModelSource {
 
 export type ModelLoadingMode = 'eager' | 'lazy'
 
+export type StageMode = 'orbit' | 'none'
+
 export interface SpatializedStatic3DElementProperties
   extends SpatializedElementProperties {
   modelURL: string
   sources?: ModelSource[]
   modelTransform?: number[]
+  stagemode?: StageMode
   autoplay?: boolean
   loop?: boolean
   animationPaused?: boolean

package/src/utils.ts

@@ -1,4 +1,5 @@
 import { Vec3 } from './types/types'
+import type { TransformValues } from './types/animation'
 
 function parseBorderRadius(borderProperty: string, width: number) {
   if (borderProperty === '') {
@@ -80,3 +81,56 @@ export function deepCloneJSON<T>(value: T): T {
   }
   return JSON.parse(JSON.stringify(value))
 }
+
+/**
+ * Decompose a column-major 4x4 matrix (16 numbers) back into
+ * position, rotation (Euler degrees), and scale Vec3 values.
+ *
+ * This is the inverse of `composeSRT`. It extracts:
+ * - Translation from the last column
+ * - Scale from the lengths of the first three column vectors
+ * - Rotation from the normalised upper-3x3 → Euler XYZ in degrees
+ */
+export function decomposeSRT(m: number[]): TransformValues {
+  // Translation
+  const position: Vec3 = { x: m[12], y: m[13], z: m[14] }
+
+  // Scale — column vector lengths
+  const sx = Math.sqrt(m[0] * m[0] + m[1] * m[1] + m[2] * m[2])
+  const sy = Math.sqrt(m[4] * m[4] + m[5] * m[5] + m[6] * m[6])
+  const sz = Math.sqrt(m[8] * m[8] + m[9] * m[9] + m[10] * m[10])
+  const scale: Vec3 = { x: sx, y: sy, z: sz }
+
+  // Normalise columns to get rotation matrix
+  const r00 = sx !== 0 ? m[0] / sx : 0
+  const r10 = sx !== 0 ? m[1] / sx : 0
+  const r20 = sx !== 0 ? m[2] / sx : 0
+  const r11 = sy !== 0 ? m[5] / sy : 0
+  const r21 = sy !== 0 ? m[6] / sy : 0
+  const r12 = sz !== 0 ? m[9] / sz : 0
+  const r22 = sz !== 0 ? m[10] / sz : 0
+
+  // DOMMatrix.rotate(rx, ry, rz) uses ZYX intrinsic order which maps to
+  // extrinsic XYZ. The decomposition below extracts Euler angles that
+  // match this convention.
+  const RAD2DEG = 180 / Math.PI
+  let rx: number, ry: number, rz: number
+
+  // clamp to avoid NaN from asin
+  const sinY = -r20
+  const clampedSinY = Math.max(-1, Math.min(1, sinY))
+  ry = Math.asin(clampedSinY) * RAD2DEG
+
+  if (Math.abs(sinY) < 0.9999999) {
+    rx = Math.atan2(r21, r22) * RAD2DEG
+    rz = Math.atan2(r10, r00) * RAD2DEG
+  } else {
+    // Gimbal lock
+    rx = Math.atan2(-r12, r11) * RAD2DEG
+    rz = 0
+  }
+
+  const rotation: Vec3 = { x: rx, y: ry, z: rz }
+
+  return { position, rotation, scale }
+}

package/tsup.config.ts

@@ -1,51 +1,76 @@
 // tsup.config.ts
+import { readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
 import { defineConfig, Options } from 'tsup'
 import { version } from './package.json'
+
+// `bundle: false` makes tsup transpile each source file to its own
+// output file (the ESM module graph is preserved 1-to-1). This is a
+// precondition for fine-grained downstream tree-shaking: with the
+// previous `bundle: true` (tsup's default) every source file collapsed
+// into a single `dist/index.js` (or with `splitting: true`, into one
+// shared chunk per entry) whose internal `__export` helper for wildcard
+// re-exports (`export * from './reality'`, etc.) **defeated** consumer
+// tree-shaking — Rollup / Vite / esbuild could not statically determine
+// which named exports were reachable from a given consumer call site,
+// so consumers ended up bundling `Spatial`, `SpatialSession`, all
+// geometry creators, `scene-polyfill`, etc. even when they only imported
+// a single helper like `isSSREnv` or `supports`. Per the lazy-load
+// proposal `tasks.md §12.9` ("Pre-v1 budget calibration"), this is a
+// precondition for react-sdk's marginal-delta budget to hold against
+// typical consumers.
 const baseConfig: Options = {
-  splitting: false,
+  bundle: false,
   sourcemap: true,
   clean: true,
   dts: true,
-  banner: {
-    js: `
-    (function(){
-      if(typeof window === 'undefined') return;
-      if(!window.__webspatialsdk__) window.__webspatialsdk__ = {}
-      window.__webspatialsdk__['core-sdk-version'] = ${JSON.stringify(version)}
-  })()
-    `,
-  },
 }
 
 const versionDefine = {
   __WEBSPATIAL_CORE_SDK_VERSION__: JSON.stringify(version),
 }
 
-export default defineConfig([
-  {
-    ...baseConfig,
-    entry: ['src/index.ts'],
-    format: ['esm'],
-    outDir: 'dist',
-    esbuildOptions(options) {
-      options.define = {
-        ...options.define,
-        ...versionDefine,
-      }
-    },
+// Diagnostic version stamp. This is intentionally NOT a tsup `banner`: with
+// `bundle: false` a banner is injected into EVERY emitted `dist/*.js` file,
+// turning each one into a top-level `window.__webspatialsdk__` write. That
+// (a) contradicts the `package.json` `sideEffects` allowlist (which declares
+// only `install-polyfills.js` as side-effectful) and (b) multiplies the stamp
+// across a consumer's bundle (one copy per source file pulled in). Instead we
+// post-build stamp ONLY the single ESM file that legitimately already has a
+// side effect — `dist/install-polyfills.js` — so a bundled WebSpatial consumer
+// still reports `core-sdk-version` when the polyfill installs, and every other
+// ESM module stays side-effect-free.
+const versionStamp = `
+(function(){
+  if(typeof window === 'undefined') return;
+  if(!window.__webspatialsdk__) window.__webspatialsdk__ = {}
+  window.__webspatialsdk__['core-sdk-version'] = ${JSON.stringify(version)}
+})()
+`.trim()
+
+const prependVersionStamp = (filePath: string): void => {
+  const current = readFileSync(filePath, 'utf8')
+  if (current.includes("__webspatialsdk__['core-sdk-version']")) return
+  writeFileSync(filePath, `${versionStamp}\n${current}`)
+}
+
+export default defineConfig({
+  ...baseConfig,
+  // ESM build: emit one output file per source file (`bundle: false`
+  // above) so consumer bundlers can tree-shake at file granularity.
+  // The entry points to the entire `src/` tree; `**/*.test.ts` is
+  // excluded so Vitest fixtures don't ship in the published package.
+  entry: ['src/**/*.ts', '!src/**/*.test.ts'],
+  format: ['esm'],
+  outDir: 'dist',
+  esbuildOptions(options) {
+    options.define = {
+      ...options.define,
+      ...versionDefine,
+    }
   },
-  {
-    ...baseConfig,
-    entry: ['src/index.ts'],
-    format: ['iife'],
-    outDir: 'dist/iife',
-    globalName: 'webspatialCore',
-    esbuildOptions(options) {
-      options.define = {
-        ...options.define,
-        ...versionDefine,
-      }
-    },
-    minify: true,
+  onSuccess: async () => {
+    // Stamp only the side-effectful ESM entry (see `versionStamp` rationale).
+    prependVersionStamp(resolve(__dirname, 'dist/install-polyfills.js'))
   },
-])
+})

package/vitest.config.ts

@@ -3,6 +3,10 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
   test: {
     globals: true,
-    environment: 'jsdom', // provide window / document
+    // Use happy-dom instead of jsdom because jsdom does not implement
+    // W3C Geometry Interfaces (DOMMatrix, DOMPoint, etc.).
+    // composeSRT in utils.ts relies on `new DOMMatrix()` which is only
+    // available in happy-dom's environment.
+    environment: 'happy-dom',
   },
 })