@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/types/animation.ts

@@ -0,0 +1,224 @@
+import type { Vec3 } from './types'
+
+// ---- Timing function ----
+
+export type TimingFunction = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut'
+
+// ---- Transform values ----
+
+/**
+ * Transform values used in animation callbacks (`onComplete`, `onCancel`).
+ * Rotation values are Euler angles in **degrees**, matching the input convention
+ * of `AnimationConfig` and the entity `rotation` prop.
+ */
+export interface TransformValues {
+  position?: Vec3
+  rotation?: Vec3
+  scale?: Vec3
+}
+
+// ---- Play state ----
+
+/**
+ * Represents the current state of an animation session as exposed by
+ * `api.playState`. The internal `delaying` state maps to `'running'`
+ * because from the developer's perspective the session is actively progressing.
+ */
+export type AnimationPlayState =
+  | 'idle'
+  | 'queued'
+  | 'running'
+  | 'paused'
+  | 'finished'
+
+// ---- Animation config ----
+
+/**
+ * Configuration for `useAnimation`.
+ *
+ * `to` is required and declares which transform fields are animated.
+ * `from` is optional; omitting it causes the native layer to snapshot
+ * the entity's current transform at playback time.
+ */
+export interface AnimationConfig {
+  /**
+   * Target transform values (required).
+   * Rotation values are Euler angles in degrees.
+   * Single-axis rotation > 180 deg may produce unexpected results (shortest-path SLERP).
+   */
+  to: TransformValues
+
+  /** Starting transform values. Omit to animate from the entity's current state. */
+  from?: TransformValues
+
+  /** Duration in seconds. Default: 0.3 */
+  duration?: number
+
+  /**
+   * Easing curve. Default: 'easeInOut'
+   * Only these four values are valid; other strings will throw at validation time.
+   */
+  timingFunction?: TimingFunction
+
+  /** Delay before playback starts, in seconds. Default: 0 */
+  delay?: number
+
+  /** Start automatically when the entity mounts. Default: true */
+  autoStart?: boolean
+
+  /**
+   * Loop behavior.
+   * - true: reset to `from` and replay (infinite reset loop)
+   * - { reverse: true }: alternate direction each cycle (infinite reverse loop)
+   * - undefined / false: play once
+   */
+  loop?: boolean | { reverse?: boolean }
+
+  /**
+   * Playback speed multiplier. Default: 1
+   * Values > 1 speed up; values between 0 and 1 slow down.
+   * Must be a positive finite number (> 0).
+   * Applied at session creation time and remains constant for the session.
+   * Maps to AnimationView.speed on the native (AVP) side.
+   */
+  playbackRate?: number
+
+  /** Called when the session is established successfully. */
+  onStart?: () => void
+
+  /** Called when a non-looping animation finishes naturally. */
+  onComplete?: (finalValues: TransformValues) => void
+
+  /** Called when playback is canceled via api.cancel(). Receives the restored transform. */
+  onCancel?: (currentValues: TransformValues) => void
+
+  /**
+   * Called when an asynchronous error occurs during a bridge or native operation.
+   * If not provided, the SDK logs the error via console.error.
+   */
+  onError?: (error: AnimationError) => void
+}
+
+// ---- Animation error ----
+
+export interface AnimationError {
+  /** The session that encountered the error. */
+  animationId: string
+  /** The command that failed. */
+  command: 'play' | 'pause' | 'resume' | 'cancel'
+  /** Optional machine-readable error code. */
+  code?: string
+  /** Human-readable failure reason. */
+  reason: string
+}
+
+// ---- Animation API (returned by useAnimation) ----
+
+export interface AnimationApi {
+  /** Start the animation, or continue it from paused progress. */
+  play(): void
+
+  /** Pause the animation at the current progress. */
+  pause(): void
+
+  /** Cancel the animation and restore `from`, or the start snapshot when `from` is omitted. */
+  cancel(): void
+
+  /** Whether the session is currently queued, delaying, or running (false while paused or idle). */
+  readonly isAnimating: boolean
+
+  /** Whether the animation is currently paused. */
+  readonly isPaused: boolean
+
+  /** Current session state. */
+  readonly playState: AnimationPlayState
+
+  /** Whether the most recent current session completed naturally. */
+  readonly finished: boolean
+}
+
+// ---- Animated props (opaque, passed to entity `animation` prop) ----
+
+/**
+ * Opaque object returned as the first tuple element of `useAnimation`.
+ * Pass it directly to the entity's `animation` prop.
+ * Application code should not read or modify its internal fields.
+ */
+export interface AnimatedProps {
+  /** @internal Unique identifier for this animation object. */
+  readonly __animationObjectId: string
+  /** @internal Transform fields targeted by this animation. */
+  readonly __animatedFields: readonly ('position' | 'rotation' | 'scale')[]
+  /** @internal Whether the animation currently has an alive session. */
+  readonly __animating: boolean
+}
+
+// ---- Cross-layer command / result ----
+
+/**
+ * Float4x4 is a 16-element column-major matrix stored in a Float64Array,
+ * matching `DOMMatrix.toFloat64Array()`.
+ */
+export type Float4x4 = Float64Array
+
+/**
+ * Unified command sent from React SDK -> Core SDK -> native.
+ */
+export interface AnimateTransformCommand {
+  /**
+   * Unique session identifier. A new `animationId` is generated for each
+   * `play` command; `pause`, `resume`, and `stop` reuse the session's id.
+   */
+  animationId: string
+  type: 'play' | 'pause' | 'resume' | 'cancel'
+  /** Required when type is 'play'; ignored otherwise. */
+  entityId?: string
+  toTransform?: Float4x4
+  fromTransform?: Float4x4
+  duration?: number
+  timingFunction?: TimingFunction
+  delay?: number
+  loop?: boolean | { reverse?: boolean }
+  /** Playback speed multiplier. Default: 1. Must be positive (> 0). Maps to AnimationView.speed on AVP. */
+  playbackRate?: number
+}
+
+/**
+ * Result returned by `SpatialEntity.animateTransform({ type: 'play' })`.
+ */
+export interface AnimateTransformResult {
+  animationId: string
+  /** Resolves when a non-looping animation completes naturally. */
+  finished: Promise<TransformValues>
+  /**
+   * Resolves when the animation is canceled and restored to `from`.
+   * After cancel, `finished` MUST remain pending (not rejected).
+   */
+  canceled: Promise<TransformValues>
+  /**
+   * Resolves when the animation fails due to a native or bridge error.
+   * Optional because older native runtimes may not emit the failed event.
+   */
+  failed?: Promise<AnimationError>
+}
+
+// ---- Internal animated props (cross-layer communication) ----
+
+/**
+ * @internal
+ * Extended interface for `AnimatedProps` used internally by the entity layer
+ * to bind/unbind animations and query suppressed transform fields.
+ * Application code should never use this interface directly.
+ */
+export interface AnimatedPropsInternal extends AnimatedProps {
+  /** Called by the entity layer when the entity instance becomes available. */
+  __bind: (
+    entity: import('../reality/entity/SpatialEntity').SpatialEntity,
+  ) => void
+  /** Called by the entity layer when the entity is destroyed or animation prop changes. */
+  __unbind: () => void
+  /** Returns the transform fields currently suppressed by an alive animation session. */
+  __getSuppressedFields: () =>
+    | readonly ('position' | 'rotation' | 'scale')[]
+    | null
+}

package/src/types/{global.d.ts → global.ts}

@@ -1,14 +1,8 @@
 import type { PhysicalMetricsValueShape } from '../physicalMetrics'
-
 declare global {
-  declare const __WEBSPATIAL_CORE_SDK_VERSION__: string
+  const __WEBSPATIAL_CORE_SDK_VERSION__: string
 
   interface Window {
-    xrCurrentSceneType: SpatialSceneType
-    xrCurrentSceneDefaults: (
-      defaultConfig: SpatialSceneCreationOptions,
-    ) => Promise<SpatialSceneCreationOptions>
-
     // Location for webspatial custom functions
     __WebSpatialData: {
       androidNativeMessage: Function
@@ -34,20 +28,24 @@ declare global {
     WebSpatailNativeVersion: string
 
     __webspatialsdk__?: {
-      XR_ENV?: string
       'natvie-version'?: string
       'react-sdk-version'?: string
       'core-sdk-version'?: string
       physicalMetrics?: PhysicalMetricsValueShape
+      pageEpoch?: string | number
     }
 
-    xrInnerDepth: number
-    xrOuterDepth: number
+    /** Present when `supports('xrInnerDepth')` is true; otherwise `undefined`. */
+    xrInnerDepth?: number
+    /** Present when `supports('xrOuterDepth')` is true; otherwise `undefined`. */
+    xrOuterDepth?: number
   }
 
   interface HTMLElement {
-    xrOffsetBack: number
-    xrClientDepth: number
+    /** Present when `supports('xrOffsetBack')` is true for element readbacks. */
+    xrOffsetBack?: number
+    /** Present when `supports('xrClientDepth')` is true for element readbacks. */
+    xrClientDepth?: number
   }
 }
 

package/src/types/motion/index.ts

@@ -0,0 +1,10 @@
+export * from './spatializedVisual'
+export * from './spatializedPlayback'
+export type {
+  SpatializedMotionKind,
+  SpatializedMotionSegmentConfig,
+  SpatializedMotionTimelineConfig,
+  SpatializedMotionConfig,
+  SpatializedMotionPlayState,
+  SpatializedPlaybackApi,
+} from './spatializedMotion'

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

@@ -100,15 +100,23 @@ export interface ModelSource {
   type?: string
 }
 
+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
   playbackRate?: number
+  currentTime?: number
+  posterURL?: string
+  loading?: ModelLoadingMode
 }
 
 export interface SpatialSceneCreationOptions {
@@ -262,6 +270,10 @@ export interface SpatialUnlitMaterialOptions {
   opacity?: number
 }
 
+export interface SpatialTextureResourceOptions {
+  url: string
+}
+
 export interface ModelComponentOptions {
   mesh: SpatialGeometry
   materials: SpatialMaterial[]

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 }
+}