@webspatial/core-sdk 1.7.0 → 2.0.0

package/src/JSBCommand.ts

@@ -1,4 +1,10 @@
 import { getPlatform } from './platform-runtime'
+import { pointToPhysical } from './physicalMetrics'
+import {
+  getRuntime,
+  supports,
+  VISIONOS_DEBUG_SHELL_VERSION_PLACEHOLDER,
+} from './runtime/supports'
 import { SpatialComponent } from './reality/component/SpatialComponent'
 import { SpatialEntity } from './reality/entity/SpatialEntity'
 import { SpatialMaterial } from './reality/material/SpatialMaterial'
@@ -27,7 +33,12 @@ import {
   ModelSource,
   SpatialTextureResourceOptions,
 } from './types/types'
+import type { AnimateTransformCommand } from './types/animation'
 import { composeSRT } from './utils'
+import type {
+  ControlSpatializedElementAnimationCommand,
+  CreateSpatializedElementAnimationCommand,
+} from './types/motion/spatializedElementMotion'
 
 abstract class JSBCommand {
   commandType: string = ''
@@ -628,6 +639,64 @@ export class CheckWebViewCanCreateCommand extends JSBCommand {
   }
 }
 
+export class AnimateTransformJSBCommand extends JSBCommand {
+  commandType = 'AnimateTransform'
+
+  constructor(private command: AnimateTransformCommand) {
+    super()
+  }
+
+  protected getParams(): Record<string, any> | undefined {
+    const { type, animationId, entityId } = this.command
+    const params: Record<string, any> = { type, animationId }
+
+    if (entityId !== undefined) params.entityId = entityId
+
+    if (type === 'play') {
+      if (this.command.toTransform) {
+        params.toTransform = Array.from(this.command.toTransform)
+      }
+      if (this.command.fromTransform) {
+        params.fromTransform = Array.from(this.command.fromTransform)
+      }
+      if (this.command.duration !== undefined)
+        params.duration = this.command.duration
+      if (this.command.timingFunction !== undefined)
+        params.timingFunction = this.command.timingFunction
+      if (this.command.delay !== undefined) params.delay = this.command.delay
+      if (this.command.loop !== undefined) params.loop = this.command.loop
+      if (this.command.playbackRate !== undefined)
+        params.playbackRate = this.command.playbackRate
+    }
+
+    return params
+  }
+}
+// TODO(remove): temporary OTA0 compat shim — delete once #1330 lands and
+// attachment JSB always uses the placement-shaped payload.
+function usePlacementProtocol(): boolean {
+  // WS_SHELL_VERSION debug shells claim every capability via supports(), but
+  // the in-repo visionOS runtime still decodes only the legacy attachment
+  // payload — keep sending it there.
+  const rt = getRuntime()
+  if (
+    rt.type === 'visionos' &&
+    rt.shellVersion === VISIONOS_DEBUG_SHELL_VERSION_PLACEHOLDER
+  ) {
+    return false
+  }
+  return supports('AttachmentEntity', ['placement'])
+}
+
+function toPlacementVec3(position?: [number, number, number]): {
+  x: number
+  y: number
+  z: number
+} {
+  const [x, y, z] = position ?? [0, 0, 0]
+  return { x, y, z }
+}
+
 export class InitializeAttachmentCommand extends JSBCommand {
   commandType = 'InitializeAttachment'
   constructor(
@@ -637,12 +706,25 @@ export class InitializeAttachmentCommand extends JSBCommand {
     super()
   }
   protected getParams() {
+    const p = this.options
+    if (!usePlacementProtocol()) {
+      return {
+        id: this.attachmentId,
+        parentEntityId: p.parentEntityId,
+        position: p.position ?? [0, 0, 0],
+        size: p.size,
+        ownerViewId: p.ownerViewId,
+      }
+    }
+    // Runtimes advertising this capability decode a Vec3 position and meter
+    // dimensions instead of the legacy tuple and point size.
     return {
       id: this.attachmentId,
-      parentEntityId: this.options.parentEntityId,
-      position: this.options.position ?? [0, 0, 0],
-      size: this.options.size,
-      ownerViewId: this.options.ownerViewId,
+      placementId: p.parentEntityId,
+      position: toPlacementVec3(p.position),
+      width: pointToPhysical(p.size.width),
+      height: pointToPhysical(p.size.height),
+      ownerViewId: p.ownerViewId,
     }
   }
 }
@@ -656,9 +738,54 @@ export class UpdateAttachmentEntityCommand extends JSBCommand {
     super()
   }
   protected getParams() {
+    if (!usePlacementProtocol()) {
+      return {
+        id: this.attachmentId,
+        ...this.options,
+      }
+    }
+    const { position, size } = this.options
     return {
       id: this.attachmentId,
-      ...this.options,
+      ...(position ? { position: toPlacementVec3(position) } : {}),
+      ...(size
+        ? {
+            width: pointToPhysical(size.width),
+            height: pointToPhysical(size.height),
+          }
+        : {}),
+    }
+  }
+}
+
+export class CreateSpatializedElementAnimationJSBCommand extends JSBCommand {
+  commandType = 'CreateSpatializedElementAnimation'
+
+  constructor(private command: CreateSpatializedElementAnimationCommand) {
+    super()
+  }
+
+  protected getParams() {
+    const { elementId, timeline } = this.command
+    return {
+      elementId,
+      timeline,
+    }
+  }
+}
+
+export class ControlSpatializedElementAnimationJSBCommand extends JSBCommand {
+  commandType = 'ControlSpatializedElementAnimation'
+
+  constructor(private command: ControlSpatializedElementAnimationCommand) {
+    super()
+  }
+
+  protected getParams() {
+    const { animationId, type } = this.command
+    return {
+      animationId,
+      type,
     }
   }
 }

package/src/SpatialObject.ts

@@ -38,6 +38,16 @@ export class SpatialObject {
       return
     }
 
+    const errorMessage =
+      typeof ret.errorMessage === 'string' ? ret.errorMessage.toLowerCase() : ''
+    const isMissingNativeObject = errorMessage.includes('not exsit')
+    if (isMissingNativeObject) {
+      // Treat native pre-teardown as an idempotent destroy during page back navigation.
+      this.onDestroy()
+      this.isDestroyed = true
+      return
+    }
+
     throw new Error(ret.errorMessage)
   }
 

package/src/Spatialized2DElement.ts

@@ -12,6 +12,11 @@ import { Spatialized2DElementProperties } from './types/types'
  * allowing HTML elements to be positioned and interacted with in spatial applications.
  */
 export class Spatialized2DElement extends SpatializedElement {
+  /**
+   * Identifies the motion target kind supported by this element.
+   */
+  override readonly kind = 'spatialized2d' as const
+
   /**
    * Creates a new spatialized 2D element.
    * @param id Unique identifier for this element

package/src/SpatializedDynamic3DElement.ts

@@ -11,6 +11,11 @@ import {
 } from './types/types'
 
 export class SpatializedDynamic3DElement extends SpatializedElement {
+  /**
+   * Identifies the motion target kind supported by this element.
+   */
+  override readonly kind = 'dynamic3d' as const
+
   children: SpatialEntityOrReality[] = []
   events: Record<string, (data: any) => void> = {}
 

package/src/SpatializedElement.ts

@@ -1,8 +1,14 @@
 import { UpdateSpatializedElementTransform } from './JSBCommand'
+import { AnimationObject } from './motion/AnimationObject'
 import { WebSpatialProtocolResult } from './platform-adapter/interface'
 import { SpatialObject } from './SpatialObject'
 import { SpatialWebEvent } from './SpatialWebEvent'
 import { createSpatialEvent } from './SpatialWebEventCreator'
+import {
+  normalizeMotionConfig,
+  validateNormalizedMotionConfig,
+} from './motion/compute'
+import { motionConfigToNativeTimeline } from './motion/native/serializeMotionTimeline'
 import {
   CubeInfo,
   SpatialDragEndEvent,
@@ -27,6 +33,10 @@ import {
   SpatialTapMsg,
   SpatialWebMsgType,
 } from './WebMsgCommand'
+import type {
+  SpatializedMotionConfig,
+  SpatializedMotionKind,
+} from './types/motion/spatializedMotion'
 
 /**
  * Abstract base class for all spatialized elements in the WebSpatial environment.
@@ -34,6 +44,11 @@ import {
  * including transformation handling and gesture event processing.
  */
 export abstract class SpatializedElement extends SpatialObject {
+  /**
+   * Identifies the motion target kind supported by this spatialized element.
+   */
+  abstract readonly kind: SpatializedMotionKind
+
   /**
    * Creates a new spatialized element with the specified ID.
    * Registers the element to receive spatial events.
@@ -55,6 +70,20 @@ export abstract class SpatializedElement extends SpatialObject {
     properties: Partial<SpatializedElementProperties>,
   ): Promise<WebSpatialProtocolResult>
 
+  /**
+   * Creates a native-first AnimationObject bound to this spatialized element.
+   */
+  async createAnimation(
+    config: SpatializedMotionConfig,
+  ): Promise<AnimationObject> {
+    const normalized = normalizeMotionConfig(config)
+    validateNormalizedMotionConfig(normalized)
+    return AnimationObject.create({
+      elementId: this.id,
+      timeline: motionConfigToNativeTimeline(normalized),
+    })
+  }
+
   /**
    * Updates the transformation matrix of this element in 3D space.
    * This affects the position, rotation, and scale of the element.

package/src/SpatializedStatic3DElement.ts

@@ -4,6 +4,7 @@ import {
   ModelLoadingMode,
   ModelSource,
   SpatializedStatic3DElementProperties,
+  StageMode,
 } from './types/types'
 import {
   ModelLoadSuccess,
@@ -11,6 +12,7 @@ import {
   SpatialWebMsgType,
   AnimationStateChangeDetail,
   AnimationStateChangeMsg,
+  EntityTransformChangeMsg,
 } from './WebMsgCommand'
 
 /**
@@ -19,6 +21,11 @@ import {
  * and provides events for load success and failure.
  */
 export class SpatializedStatic3DElement extends SpatializedElement {
+  /**
+   * Identifies the motion target kind supported by this element.
+   */
+  override readonly kind = 'static3d' as const
+
   /**
    * Creates a new spatialized static 3D element with the specified ID and URL.
    * Registers the element to receive spatial events.
@@ -138,6 +145,9 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     if (properties.loading !== undefined) {
       this._loading = properties.loading
     }
+    if (properties.stagemode !== undefined) {
+      this._stagemode = properties.stagemode
+    }
     return new UpdateSpatializedStatic3DElementProperties(
       this,
       properties,
@@ -297,6 +307,8 @@ export class SpatializedStatic3DElement extends SpatializedElement {
       this._currentTime = data.detail.currentTime ?? 0
       this._anchorTimestamp = data.detail.timestamp ?? Date.now()
       this._onAnimationStateChangeCallback?.(data.detail)
+    } else if (data.type === SpatialWebMsgType.entitytransformchange) {
+      this._entityTransform = new DOMMatrixReadOnly(data.detail.transform)
     } else {
       // Handle other spatial events using the base class implementation
       super.onReceiveEvent(data)
@@ -363,9 +375,35 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     this._onLoadFailureCallback = callback
   }
 
-  updateModelTransform(transform: DOMMatrixReadOnly) {
-    const modelTransform = Array.from(transform.toFloat64Array())
-    this.updateProperties({ modelTransform })
+  /**
+   * Built-in interaction mode. In `'orbit'` the native layer drives the
+   * transform and `entityTransform` is read-only.
+   */
+  private _stagemode: StageMode = 'none'
+
+  get stagemode(): StageMode {
+    return this._stagemode
+  }
+
+  /**
+   * Latest transform of the model, including native-driven manipulations such
+   * as orbit interaction.
+   */
+  private _entityTransform: DOMMatrixReadOnly = new DOMMatrixReadOnly()
+
+  get entityTransform(): DOMMatrixReadOnly {
+    return this._entityTransform
+  }
+
+  set entityTransform(transform: DOMMatrixReadOnly) {
+    // In orbit mode the native layer owns the transform, so ignore writes.
+    if (this._stagemode === 'orbit') return
+    this._entityTransform = transform
+    // The public API is `entityTransform`, but the JSB property stays
+    // `modelTransform` so the native side remains backward compatible.
+    this.updateProperties({
+      modelTransform: Array.from(transform.toFloat64Array()),
+    })
   }
 }
 
@@ -379,3 +417,4 @@ type Static3DReceiveEventData =
   | ModelLoadFailure
   | ReceiveEventData
   | AnimationStateChangeMsg
+  | EntityTransformChangeMsg

package/src/WebMsgCommand.ts

@@ -21,6 +21,14 @@ export enum SpatialWebMsgType {
 
   animationstatechange = 'animationstatechange',
 
+  // Native-driven transform updates (e.g. while in `stagemode="orbit"`)
+  entitytransformchange = 'entitytransformchange',
+
+  // Animation terminal events (keyed by animationId, not by this enum)
+  animationcompleted = 'animationcompleted',
+  animationstopped = 'animationstopped',
+  animationfailed = 'animationfailed',
+
   objectdestroy = 'objectdestroy',
 }
 
@@ -97,3 +105,35 @@ export interface AnimationStateChangeMsg {
   type: SpatialWebMsgType.animationstatechange
   detail: AnimationStateChangeDetail
 }
+
+export interface EntityTransformChangeDetail {
+  /** Column-major 4x4 matrix (16 numbers) representing the manipulated transform. */
+  transform: number[]
+}
+
+export interface EntityTransformChangeMsg {
+  type: SpatialWebMsgType.entitytransformchange
+  detail: EntityTransformChangeDetail
+}
+
+// Animation terminal event payloads (delivered via SpatialWebEvent keyed by animationId)
+
+export interface AnimationCompletedEventPayload {
+  type: 'completed'
+  /** Column-major 4x4 matrix (16 numbers) representing the final native transform. */
+  transform: number[]
+}
+
+export interface AnimationCanceledEventPayload {
+  type: 'canceled'
+  /** Column-major 4x4 matrix (16 numbers) representing the restored transform after cancel. */
+  transform: number[]
+}
+
+export interface AnimationFailedEventPayload {
+  type: 'failed'
+  animationId: string
+  command: 'play' | 'pause' | 'resume' | 'cancel'
+  code?: string
+  reason: string
+}