@webspatial/core-sdk 1.7.0 → 2.0.0

package/dist/spatializedElementMotion-_0XWPQCE.d.ts

@@ -0,0 +1,1009 @@
+import { SpatializedVisualValues } from './types/motion/spatializedVisual.js';
+import { SpatializedPlaybackError } from './types/motion/spatializedPlayback.js';
+import './types/global.js';
+import { SpatialObject } from './SpatialObject.js';
+import { SpatialComponent } from './reality/component/SpatialComponent.js';
+
+declare abstract class SpatialMaterial extends SpatialObject {
+    id: string;
+    type: SpatialMaterialType;
+    constructor(id: string, type: SpatialMaterialType);
+    abstract updateProperties(properties: any): void;
+}
+
+declare class SpatialGeometry extends SpatialObject {
+    id: string;
+    options: SpatialGeometryOptions;
+    static type: SpatialGeometryType;
+    constructor(id: string, options: SpatialGeometryOptions);
+}
+
+interface AnimationObjectCreateOptions {
+    elementId: string;
+    timeline: SpatializedMotionTimeline;
+}
+interface AnimationObjectCallbacks {
+    onStart?: () => void;
+    onComplete?: (values: SpatializedVisualValues) => void;
+    onStop?: (values: SpatializedVisualValues) => void;
+    onReset?: (values: SpatializedVisualValues) => void;
+    onError?: (error: SpatializedPlaybackError) => void;
+    onValuesChange?: (values: SpatializedVisualValues) => void;
+    onStateChange?: () => void;
+}
+declare class AnimationObject extends SpatialObject implements SpatializedPlaybackApi {
+    readonly elementId: string;
+    readonly timeline: SpatializedMotionTimeline;
+    private callbacks;
+    private _playState;
+    private _finished;
+    private started;
+    constructor(id: string, options: AnimationObjectCreateOptions);
+    static create(options: AnimationObjectCreateOptions): Promise<AnimationObject>;
+    setCallbacks(callbacks: AnimationObjectCallbacks): void;
+    get playState(): SpatializedMotionPlayState;
+    get isAnimating(): boolean;
+    get isPaused(): boolean;
+    get finished(): boolean;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    stop(): Promise<void>;
+    reset(): Promise<void>;
+    finish(): Promise<void>;
+    protected onDestroy(): void;
+    private control;
+    onReceiveEvent(data: SpatialAnimationStateChangedMsg | {
+        detail?: unknown;
+    }): void;
+    private isSpatialAnimationStateChangedDetail;
+}
+
+declare enum SpatialWebMsgType {
+    modelloaded = "modelloaded",
+    modelloadfailed = "modelloadfailed",
+    spatialtap = "spatialtap",
+    spatialdragstart = "spatialdragstart",
+    spatialdrag = "spatialdrag",
+    spatialdragend = "spatialdragend",
+    spatialrotate = "spatialrotate",
+    spatialrotateend = "spatialrotateend",
+    spatialmagnify = "spatialmagnify",
+    spatialmagnifyend = "spatialmagnifyend",
+    animationstatechange = "animationstatechange",
+    entitytransformchange = "entitytransformchange",
+    animationcompleted = "animationcompleted",
+    animationstopped = "animationstopped",
+    animationfailed = "animationfailed",
+    objectdestroy = "objectdestroy"
+}
+interface ObjectDestroyMsg {
+    type: SpatialWebMsgType.objectdestroy;
+}
+interface SpatialTapMsg {
+    type: SpatialWebMsgType.spatialtap;
+    detail: SpatialTapEventDetail;
+}
+interface SpatialDragStartMsg {
+    type: SpatialWebMsgType.spatialdragstart;
+    detail: SpatialDragStartEventDetail;
+}
+interface SpatialDragMsg {
+    type: SpatialWebMsgType.spatialdrag;
+    detail: SpatialDragEventDetail;
+}
+interface SpatialDragEndMsg {
+    type: SpatialWebMsgType.spatialdragend;
+    detail: SpatialDragEndEventDetail;
+}
+interface SpatialRotateMsg {
+    type: SpatialWebMsgType.spatialrotate;
+    detail: SpatialRotateEventDetail;
+}
+interface SpatialRotateEndMsg {
+    type: SpatialWebMsgType.spatialrotateend;
+    detail: SpatialRotateEventDetail;
+}
+interface SpatialMagnifyMsg {
+    type: SpatialWebMsgType.spatialmagnify;
+    detail: SpatialMagnifyEventDetail;
+}
+interface SpatialMagnifyEndMsg {
+    type: SpatialWebMsgType.spatialmagnifyend;
+    detail: SpatialMagnifyEventDetail;
+}
+interface ModelLoadSuccess {
+    type: SpatialWebMsgType.modelloaded;
+    detail?: {
+        src: string;
+    };
+}
+interface ModelLoadFailure {
+    type: SpatialWebMsgType.modelloadfailed;
+}
+interface AnimationStateChangeDetail {
+    paused: boolean;
+    duration: number;
+    /**
+     * Sampled animation playback position in seconds at `timestamp`.
+     * Optional for compatibility with older native runtimes.
+     */
+    currentTime?: number;
+    /**
+     * Unix epoch time in milliseconds at which `currentTime` was sampled.
+     * Used to extrapolate `currentTime` between samples while playing.
+     */
+    timestamp?: number;
+}
+interface AnimationStateChangeMsg {
+    type: SpatialWebMsgType.animationstatechange;
+    detail: AnimationStateChangeDetail;
+}
+interface EntityTransformChangeDetail {
+    /** Column-major 4x4 matrix (16 numbers) representing the manipulated transform. */
+    transform: number[];
+}
+interface EntityTransformChangeMsg {
+    type: SpatialWebMsgType.entitytransformchange;
+    detail: EntityTransformChangeDetail;
+}
+interface AnimationCompletedEventPayload {
+    type: 'completed';
+    /** Column-major 4x4 matrix (16 numbers) representing the final native transform. */
+    transform: number[];
+}
+interface AnimationCanceledEventPayload {
+    type: 'canceled';
+    /** Column-major 4x4 matrix (16 numbers) representing the restored transform after cancel. */
+    transform: number[];
+}
+interface AnimationFailedEventPayload {
+    type: 'failed';
+    animationId: string;
+    command: 'play' | 'pause' | 'resume' | 'cancel';
+    code?: string;
+    reason: string;
+}
+
+/**
+ * Abstract base class for all spatialized elements in the WebSpatial environment.
+ * Provides common functionality for elements that can exist in 3D space,
+ * including transformation handling and gesture event processing.
+ */
+declare abstract class SpatializedElement extends SpatialObject {
+    readonly id: string;
+    /**
+     * 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.
+     * @param id Unique identifier for this element
+     */
+    constructor(id: string);
+    /**
+     * Updates the properties of this spatialized element.
+     * Must be implemented by derived classes to handle specific property updates.
+     * @param properties Partial set of properties to update
+     * @returns Promise resolving to the result of the update operation
+     */
+    abstract updateProperties(properties: Partial<SpatializedElementProperties>): Promise<WebSpatialProtocolResult>;
+    /**
+     * Creates a native-first AnimationObject bound to this spatialized element.
+     */
+    createAnimation(config: SpatializedMotionConfig): Promise<AnimationObject>;
+    /**
+     * Updates the transformation matrix of this element in 3D space.
+     * This affects the position, rotation, and scale of the element.
+     * @param matrix The new transformation matrix
+     * @returns Promise resolving when the transform is updated
+     */
+    updateTransform(matrix: DOMMatrix): Promise<CommandResult<any>>;
+    /**
+     * Information about the element's bounding cube.
+     * Used for spatial calculations and hit testing.
+     */
+    private _cubeInfo?;
+    /**
+     * Gets the current cube information for this element.
+     * @returns The current CubeInfo or undefined if not set
+     */
+    get cubeInfo(): CubeInfo | undefined;
+    /**
+     * The current transformation matrix of this element.
+     */
+    private _transform?;
+    /**
+     * The inverse of the current transformation matrix.
+     * Used for converting world coordinates to local coordinates.
+     */
+    private _transformInv?;
+    /**
+     * Gets the current transformation matrix.
+     * @returns The current transformation matrix or undefined if not set
+     */
+    get transform(): DOMMatrix | undefined;
+    /**
+     * Gets the inverse of the current transformation matrix.
+     * @returns The inverse transformation matrix or undefined if not set
+     */
+    get transformInv(): DOMMatrix | undefined;
+    /**
+     * Processes events received from the WebSpatial environment.
+     * Handles various spatial events like transforms, gestures, and interactions.
+     * @param data The event data received from the WebSpatial system
+     */
+    protected onReceiveEvent(data: ReceiveEventData): void;
+    private _onSpatialTap?;
+    set onSpatialTap(value: (event: SpatialTapEvent) => void | undefined);
+    private _onSpatialDragStart?;
+    set onSpatialDragStart(value: (event: SpatialDragStartEvent) => void | undefined);
+    private _onSpatialDrag?;
+    set onSpatialDrag(value: (event: SpatialDragEvent) => void | undefined);
+    private _onSpatialDragEnd?;
+    set onSpatialDragEnd(value: ((event: SpatialDragEndEvent) => void) | undefined);
+    private _onSpatialRotate?;
+    set onSpatialRotate(value: ((event: SpatialRotateEvent) => void) | undefined);
+    private _onSpatialRotateEnd?;
+    set onSpatialRotateEnd(value: ((event: SpatialRotateEndEvent) => void) | undefined);
+    private _onSpatialMagnify?;
+    set onSpatialMagnify(value: ((event: SpatialMagnifyEvent) => void) | undefined);
+    private _onSpatialMagnifyEnd?;
+    set onSpatialMagnifyEnd(value: ((event: SpatialMagnifyEndEvent) => void) | undefined);
+    /**
+     * Cleans up resources when this element is destroyed.
+     * Removes event receivers to prevent memory leaks.
+     */
+    onDestroy(): void;
+}
+type ReceiveEventData = SpatialTapMsg | SpatialDragStartMsg | SpatialDragMsg | SpatialDragEndMsg | SpatialRotateMsg | SpatialRotateEndMsg | ObjectDestroyMsg;
+
+declare class SpatializedDynamic3DElement extends SpatializedElement {
+    /**
+     * Identifies the motion target kind supported by this element.
+     */
+    readonly kind: "dynamic3d";
+    children: SpatialEntityOrReality[];
+    events: Record<string, (data: any) => void>;
+    constructor(id: string);
+    addEntity(entity: SpatialEntity): Promise<CommandResult<any>>;
+    addEvent(type: SpatialEntityEventType, callback: (data: any) => void): void;
+    removeEvent(eventName: SpatialEntityEventType): void;
+    dispatchEvent(evt: CustomEvent): void;
+    updateProperties(properties: Partial<SpatializedElementProperties>): Promise<CommandResult<any>>;
+}
+
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+type Point3D = Vec3;
+interface Quaternion {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+/**
+ * Material type for SpatialDiv or HTML document.
+ *
+ * This type defines the background material options for both SpatialDiv elements and HTML documents.
+ *
+ * - `'none'`: This is the default value.
+ *   - For HTML documents, the web page window will have the default native background.
+ *   - For SpatialDiv, the window will have a transparent background.
+ * - `'translucent'`: Represents a glass-like material in AVP (Apple Vision Pro).
+ * - `'thick'`: Represents a thick material in AVP.
+ * - `'regular'`: Represents a regular material in AVP.
+ * - `'thin'`: Represents a thin material in AVP.
+ * - `'transparent'`: Represents a fully transparent background.
+ */
+type BackgroundMaterialType = 'none' | 'translucent' | 'thick' | 'regular' | 'thin' | 'transparent';
+type CornerRadius = {
+    topLeading: number;
+    bottomLeading: number;
+    topTrailing: number;
+    bottomTrailing: number;
+};
+interface SpatialSceneProperties {
+    cornerRadius: CornerRadius;
+    material: BackgroundMaterialType;
+    opacity: number;
+}
+declare enum SpatializedElementType {
+    Spatialized2DElement = 0,
+    SpatializedStatic3DElement = 1,
+    SpatializedDynamic3DElement = 2
+}
+interface SpatializedElementProperties {
+    name: string;
+    clientX: number;
+    clientY: number;
+    width: number;
+    height: number;
+    depth: number;
+    opacity: number;
+    visible: boolean;
+    scrollWithParent: boolean;
+    zIndex: number;
+    backOffset: number;
+    rotationAnchor: Point3D;
+    enableTapGesture: boolean;
+    enableDragStartGesture: boolean;
+    enableDragGesture: boolean;
+    enableDragEndGesture: boolean;
+    enableRotateGesture: boolean;
+    enableRotateEndGesture: boolean;
+    enableMagnifyGesture: boolean;
+    enableMagnifyEndGesture: boolean;
+    /**
+     * Optional world-space axis for spatial rotate gesture. Omitted or zero vector
+     * means unconstrained rotation (platform default).
+     */
+    rotateConstrainedToAxis?: Vec3;
+}
+interface Spatialized2DElementProperties extends SpatializedElementProperties {
+    scrollPageEnabled: boolean;
+    cornerRadius: CornerRadius;
+    material: BackgroundMaterialType;
+    scrollEdgeInsetsMarginRight: number;
+}
+interface ModelSource {
+    src: string;
+    type?: string;
+}
+type ModelLoadingMode = 'eager' | 'lazy';
+type StageMode = 'orbit' | 'none';
+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;
+}
+interface SpatialSceneCreationOptions {
+    defaultSize?: {
+        width: number | string;
+        height: number | string;
+        depth?: number | string;
+    };
+    resizability?: {
+        minWidth?: number | string;
+        minHeight?: number | string;
+        maxWidth?: number | string;
+        maxHeight?: number | string;
+    };
+    worldScaling?: WorldScalingType;
+    worldAlignment?: WorldAlignmentType;
+    baseplateVisibility?: BaseplateVisibilityType;
+}
+type SpatialEntityEventType = 'spatialtap' | 'spatialdragstart' | 'spatialdrag' | 'spatialdragend' | 'spatialrotate' | 'spatialrotateend' | 'spatialmagnify' | 'spatialmagnifyend';
+declare const BaseplateVisibilityValues: readonly ["automatic", "visible", "hidden"];
+type BaseplateVisibilityType = (typeof BaseplateVisibilityValues)[number];
+declare function isValidBaseplateVisibilityType(type: string): Boolean;
+declare const WorldScalingValues: readonly ["automatic", "dynamic"];
+type WorldScalingType = (typeof WorldScalingValues)[number];
+declare function isValidWorldScalingType(type: string): Boolean;
+declare const WorldAlignmentValues: readonly ["adaptive", "automatic", "gravityAligned"];
+type WorldAlignmentType = (typeof WorldAlignmentValues)[number];
+declare function isValidWorldAlignmentType(type: string): Boolean;
+declare const SpatialSceneValues: readonly ["window", "volume"];
+type SpatialSceneType = (typeof SpatialSceneValues)[number];
+declare function isValidSpatialSceneType(type: string): Boolean;
+/**
+ * check px,m and number, number must be >= 0
+ *
+ * */
+declare function isValidSceneUnit(val: string | number): boolean;
+interface SpatialEntityProperties {
+    position: Vec3;
+    rotation: Vec3;
+    scale: Vec3;
+}
+type SpatialGeometryType = 'BoxGeometry' | 'PlaneGeometry' | 'SphereGeometry' | 'CylinderGeometry' | 'ConeGeometry';
+interface SpatialBoxGeometryOptions {
+    width?: number;
+    height?: number;
+    depth?: number;
+    cornerRadius?: number;
+    splitFaces?: boolean;
+}
+interface SpatialPlaneGeometryOptions {
+    width?: number;
+    height?: number;
+    cornerRadius?: number;
+}
+interface SpatialSphereGeometryOptions {
+    radius?: number;
+}
+interface SpatialConeGeometryOptions {
+    radius?: number;
+    height?: number;
+}
+interface SpatialCylinderGeometryOptions {
+    radius?: number;
+    height?: number;
+}
+type SpatialGeometryOptions = SpatialBoxGeometryOptions | SpatialPlaneGeometryOptions | SpatialSphereGeometryOptions | SpatialCylinderGeometryOptions | SpatialConeGeometryOptions;
+type SpatialMaterialType = 'unlit';
+interface SpatialUnlitMaterialOptions {
+    color?: string;
+    textureId?: string;
+    transparent?: boolean;
+    opacity?: number;
+}
+interface SpatialTextureResourceOptions {
+    url: string;
+}
+interface ModelComponentOptions {
+    mesh: SpatialGeometry;
+    materials: SpatialMaterial[];
+}
+interface SpatialEntityUserData {
+    id?: string;
+    name?: string;
+}
+interface SpatialModelEntityCreationOptions {
+    modelAssetId: string;
+    name?: string;
+}
+interface ModelAssetOptions {
+    url: string;
+}
+declare enum SpatialSceneState$1 {
+    idle = "idle",
+    pending = "pending",
+    willVisible = "willVisible",
+    visible = "visible",
+    fail = "fail"
+}
+/**
+ * Translate event, matching similar behavior to https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/drag_event
+ */
+type SpatialModelDragEvent = {
+    eventType: 'dragstart' | 'dragend' | 'drag';
+    translation3D: Vec3;
+    startLocation3D: Vec3;
+};
+interface Size {
+    width: number;
+    height: number;
+}
+interface Size3D extends Size {
+    depth: number;
+}
+declare class CubeInfo {
+    size: Size3D;
+    origin: Vec3;
+    constructor(size: Size3D, origin: Vec3);
+    get x(): number;
+    get y(): number;
+    get z(): number;
+    get width(): number;
+    get height(): number;
+    get depth(): number;
+    get left(): number;
+    get top(): number;
+    get right(): number;
+    get bottom(): number;
+    get back(): number;
+    get front(): number;
+}
+interface SpatialTapEventDetail {
+    location3D: Point3D;
+    globalLocation3D?: Point3D;
+}
+type SpatialTapEvent = CustomEvent<SpatialTapEventDetail>;
+interface SpatialDragStartEventDetail {
+    startLocation3D: Point3D;
+    globalLocation3D?: Point3D;
+}
+interface SpatialDragEventDetail {
+    translation3D: Vec3;
+}
+interface SpatialDragEndEventDetail {
+}
+type SpatialDragStartEvent = CustomEvent<SpatialDragStartEventDetail>;
+type SpatialDragEvent = CustomEvent<SpatialDragEventDetail>;
+type SpatialDragEndEvent = CustomEvent<SpatialDragEndEventDetail>;
+interface SpatialRotateEventDetail {
+    quaternion: Quaternion;
+}
+interface SpatialRotateEndEventDetail {
+}
+type SpatialRotateEvent = CustomEvent<SpatialRotateEventDetail>;
+type SpatialRotateEndEvent = CustomEvent<SpatialRotateEndEventDetail>;
+interface SpatialMagnifyEventDetail {
+    magnification: number;
+}
+interface SpatialMagnifyEndEventDetail {
+}
+type SpatialMagnifyEvent = CustomEvent<SpatialMagnifyEventDetail>;
+type SpatialMagnifyEndEvent = CustomEvent<SpatialMagnifyEndEventDetail>;
+type SpatialEntityOrReality = SpatialEntity | SpatializedDynamic3DElement;
+interface AttachmentEntityOptions {
+    parentEntityId: string;
+    position?: [number, number, number];
+    size: {
+        width: number;
+        height: number;
+    };
+    ownerViewId: string;
+}
+interface AttachmentEntityUpdateOptions {
+    position?: [number, number, number];
+    size?: {
+        width: number;
+        height: number;
+    };
+}
+type SceneUnitPx = `${number}px`;
+type SceneUnitM = `${number}m`;
+type SceneUnit = number | SceneUnitPx | SceneUnitM;
+interface XRSceneSize {
+    width: SceneUnit;
+    height: SceneUnit;
+    depth?: SceneUnit;
+}
+interface XRSceneResizability {
+    minWidth?: SceneUnit;
+    minHeight?: SceneUnit;
+    maxWidth?: SceneUnit;
+    maxHeight?: SceneUnit;
+}
+interface XRMainSceneConfig extends XRSpatialSceneDefaults {
+    type?: SpatialSceneType;
+}
+interface XRSpatialSceneDefaults {
+    default_size?: XRSceneSize;
+    resizability?: XRSceneResizability;
+    worldScaling?: WorldScalingType;
+    worldAlignment?: WorldAlignmentType;
+    baseplateVisibility?: BaseplateVisibilityType;
+}
+interface XRSpatialSceneOverrides {
+    window_scene?: XRSpatialSceneDefaults;
+    volume_scene?: XRSpatialSceneDefaults;
+}
+interface XRSpatialSceneConfig extends XRSpatialSceneDefaults {
+    overrides?: XRSpatialSceneOverrides;
+}
+interface XRPrdConfig {
+    xr_main_scene?: XRMainSceneConfig;
+    xr_spatial_scene?: XRSpatialSceneConfig;
+}
+interface PWAManifest extends XRPrdConfig {
+    name?: string;
+    short_name?: string;
+    start_url?: string;
+    display?: string;
+    icons?: Array<{
+        src: string;
+        sizes?: string;
+        type?: string;
+        purpose?: string;
+    }>;
+    id?: string;
+    scope?: string;
+    [key: string]: any;
+}
+
+type SpatialSceneCreationOptionsInternal = SpatialSceneCreationOptions & {
+    type: SpatialSceneType;
+};
+declare enum SpatialSceneState {
+    idle = "idle",
+    pending = "pending",
+    willVisible = "willVisible",
+    visible = "visible",
+    fail = "fail"
+}
+
+interface CommandResult<TData = any> {
+    success: boolean;
+    data: TData;
+    errorCode: string | undefined;
+    errorMessage: string | undefined;
+}
+type WebSpatialProtocolResult = CommandResult<{
+    windowProxy: any;
+    id: string;
+} | undefined>;
+/**
+ * Host/runtime bridge: JSB plus explicit spatial host capabilities.
+ * Implementations may use webspatial://, iframes, native events, etc.
+ */
+interface PlatformAbility {
+    callJSB(cmd: string, msg: string): Promise<CommandResult>;
+    /**
+     * Open a spatial scene synchronously (e.g. window.open polyfill).
+     * Implementations may use webspatial://createSpatialScene under the hood.
+     */
+    openSpatialSceneSync(url: string, config: SpatialSceneCreationOptionsInternal | undefined, target?: string, features?: string): WebSpatialProtocolResult;
+    /** Create a native-backed spatial 2D surface (spatial div). */
+    createNativeSpatialDiv(): Promise<WebSpatialProtocolResult>;
+    /** Create a native attachment surface; options reserved for future protocol fields. */
+    createNativeAttachment(options?: AttachmentEntityOptions): Promise<WebSpatialProtocolResult>;
+}
+
+declare class SpatialEntity extends SpatialObject {
+    userData?: SpatialEntityUserData | undefined;
+    position: Vec3;
+    rotation: Vec3;
+    scale: Vec3;
+    events: Record<string, (data: any) => void>;
+    children: SpatialEntity[];
+    parent: SpatialEntityOrReality | null;
+    private _enableInput;
+    get enableInput(): boolean;
+    set enableInput(value: boolean);
+    constructor(id: string, userData?: SpatialEntityUserData | undefined);
+    addComponent(component: SpatialComponent): Promise<CommandResult<any>>;
+    removeComponent(component: SpatialComponent): Promise<CommandResult<any>>;
+    setPosition(position: Vec3): Promise<CommandResult<any>>;
+    setRotation(rotation: Vec3): Promise<CommandResult<any>>;
+    setScale(scale: Vec3): Promise<CommandResult<any>>;
+    addEntity(ent: SpatialEntity): Promise<CommandResult<any>>;
+    removeFromParent(): Promise<CommandResult<any>>;
+    updateTransform(properties: Partial<SpatialEntityProperties>): Promise<CommandResult<any>>;
+    /**
+     * Send an animation command to the native layer.
+     *
+     * For `play`: registers event listeners for completion / stop / failure,
+     * sends the JSB command, and returns an `AnimateTransformResult` with
+     * `finished` and `stopped` promises.
+     *
+     * For `pause`, `resume`, `cancel``: sends the command and resolves when
+     * the bridge acknowledges it.
+     */
+    animateTransform(command: AnimateTransformCommand & {
+        type: 'play';
+    }): Promise<AnimateTransformResult>;
+    animateTransform(command: AnimateTransformCommand): Promise<void>;
+    /**
+     * Remove all animation event receivers for a given animationId.
+     * Called on entity unmount to prevent leaked listeners.
+     */
+    cleanupAnimationListeners(animationId: string): void;
+    addEvent(type: SpatialEntityEventType, callback: (data: any) => void): Promise<void>;
+    removeEvent(eventName: SpatialEntityEventType): Promise<void>;
+    updateEntityEvent(eventName: SpatialEntityEventType, isEnable: boolean): Promise<CommandResult<any>>;
+    private onReceiveEvent;
+    dispatchEvent(evt: CustomEvent): void;
+    protected onDestroy(): void;
+    convertFromEntityToEntity(fromEntityId: string, toEntityId: string, position: Vec3): Promise<CommandResult<any>>;
+    convertFromEntityToScene(fromEntityId: string, position: Vec3): Promise<CommandResult<any>>;
+    convertFromSceneToEntity(entityId: string, position: Vec3): Promise<CommandResult<any>>;
+}
+
+type TimingFunction = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+/**
+ * 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.
+ */
+interface TransformValues {
+    position?: Vec3;
+    rotation?: Vec3;
+    scale?: Vec3;
+}
+/**
+ * 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.
+ */
+type AnimationPlayState = 'idle' | 'queued' | 'running' | 'paused' | 'finished';
+/**
+ * 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.
+ */
+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;
+}
+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;
+}
+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;
+}
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * Float4x4 is a 16-element column-major matrix stored in a Float64Array,
+ * matching `DOMMatrix.toFloat64Array()`.
+ */
+type Float4x4 = Float64Array;
+/**
+ * Unified command sent from React SDK -> Core SDK -> native.
+ */
+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' })`.
+ */
+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
+ * 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.
+ */
+interface AnimatedPropsInternal extends AnimatedProps {
+    /** Called by the entity layer when the entity instance becomes available. */
+    __bind: (entity: 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;
+}
+
+/** Spatialized container kinds with declarative timeline motion. */
+type SpatializedMotionKind = 'spatialized2d' | 'static3d' | 'dynamic3d';
+/** Scalar property path on the spatialized visual whitelist. */
+declare const SPATIALIZED_MOTION_PROPERTIES: readonly ["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"];
+type SpatializedMotionProperty = (typeof SPATIALIZED_MOTION_PROPERTIES)[number];
+interface SpatializedMotionKeyframe {
+    /** Time in seconds from timeline start, in `[0, duration]`. */
+    at: number;
+    value: number;
+    timingFunction?: TimingFunction;
+}
+type SpatializedMotionKeyframeValues = SpatializedVisualValues & {
+    timingFunction?: TimingFunction;
+};
+/** One animatable property path and its keyframes (config-only, not a runtime handle). */
+interface SpatializedMotionTrack {
+    property: SpatializedMotionProperty;
+    keyframes: SpatializedMotionKeyframe[];
+    timingFunction?: TimingFunction;
+}
+/** Single-segment motion: `from` → `to` over `duration`. */
+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. */
+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. */
+type SpatializedMotionConfig = SpatializedMotionSegmentConfig | SpatializedMotionTimelineConfig;
+/** Canonical internal track document produced before native create. */
+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. */
+interface SpatializedMotionTimeline {
+    duration: number;
+    delay?: number;
+    playbackRate?: number;
+    loop?: boolean | {
+        reverse?: boolean;
+    };
+    tracks: Array<{
+        property: SpatializedMotionProperty;
+        keyframes: SpatializedMotionKeyframe[];
+        timingFunction: TimingFunction;
+    }>;
+}
+type SpatializedMotionPlayState = 'idle' | 'queued' | 'running' | 'paused' | 'finished';
+/** Public imperative playback controls exposed to spatialized motion consumers. */
+interface SpatializedPlaybackApi {
+    play(): void;
+    pause(): void;
+    stop(): void;
+    reset(): void;
+    finish(): void;
+    readonly isAnimating: boolean;
+    readonly isPaused: boolean;
+    readonly finished: boolean;
+    readonly playState: SpatializedMotionPlayState;
+}
+
+/** 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;
+}
+interface CreateSpatializedElementAnimationCommand {
+    elementId: string;
+    timeline: SpatializedMotionTimeline;
+}
+type SpatializedElementAnimationControlType = 'play' | 'pause' | 'resume' | 'stop' | 'reset' | 'finish' | 'destroy';
+interface ControlSpatializedElementAnimationCommand {
+    animationId: string;
+    type: SpatializedElementAnimationControlType;
+}
+interface SpatialAnimationStateChangedDetail {
+    animationId: string;
+    action: SpatializedElementAnimationControlType | 'start' | 'complete' | 'error';
+    playState: SpatializedMotionPlayState;
+    finished: boolean;
+    values?: SpatializedVisualValues;
+    error?: SpatializedElementAnimationErrorDetail;
+}
+interface SpatialAnimationStateChangedMsg {
+    type: SpatialWebMsgType.animationstatechange;
+    detail: SpatialAnimationStateChangedDetail;
+}
+
+export { type SpatialPlaneGeometryOptions as $, type AnimateTransformCommand as A, type BackgroundMaterialType as B, type CornerRadius as C, type SpatialDragEventDetail as D, type SpatialDragStartEvent as E, type Float4x4 as F, type SpatialDragStartEventDetail as G, SpatialEntity as H, type SpatialEntityEventType as I, type SpatialEntityOrReality as J, type SpatialEntityProperties as K, type SpatialEntityUserData as L, type ModelAssetOptions as M, SpatialGeometry as N, type SpatialGeometryOptions as O, type PWAManifest as P, type Quaternion as Q, type SpatialGeometryType as R, type SceneUnit as S, type SpatialMagnifyEndEvent as T, type SpatialMagnifyEndEventDetail as U, type SpatialMagnifyEvent as V, type SpatialMagnifyEventDetail as W, SpatialMaterial as X, type SpatialMaterialType as Y, type SpatialModelDragEvent as Z, type SpatialModelEntityCreationOptions as _, type AnimateTransformResult as a, type NormalizedSpatializedMotionConfig as a$, type SpatialRotateEndEvent as a0, type SpatialRotateEndEventDetail as a1, type SpatialRotateEvent as a2, type SpatialRotateEventDetail as a3, type SpatialSceneCreationOptions as a4, type SpatialSceneProperties as a5, SpatialSceneState$1 as a6, type SpatialSceneType as a7, SpatialSceneValues as a8, type SpatialSphereGeometryOptions as a9, type XRSceneResizability as aA, type XRSceneSize as aB, type XRSpatialSceneConfig as aC, type XRSpatialSceneDefaults as aD, type XRSpatialSceneOverrides as aE, isValidBaseplateVisibilityType as aF, isValidSceneUnit as aG, isValidSpatialSceneType as aH, isValidWorldAlignmentType as aI, isValidWorldScalingType as aJ, type CommandResult as aK, type ControlSpatializedElementAnimationCommand as aL, type SpatializedElementAnimationControlType as aM, type CreateSpatializedElementAnimationCommand as aN, type SpatializedMotionTimeline as aO, SpatialWebMsgType as aP, type SpatialSceneCreationOptionsInternal as aQ, SpatialSceneState as aR, type AnimationStateChangeDetail as aS, type ModelLoadSuccess as aT, type ModelLoadFailure as aU, type ReceiveEventData as aV, type AnimationStateChangeMsg as aW, type EntityTransformChangeMsg as aX, type PlatformAbility as aY, type WebSpatialProtocolResult as aZ, type SpatializedMotionProperty as a_, type SpatialTapEvent as aa, type SpatialTapEventDetail as ab, type SpatialTextureResourceOptions as ac, type SpatialUnlitMaterialOptions as ad, type Spatialized2DElementProperties as ae, SpatializedDynamic3DElement as af, SpatializedElement as ag, type SpatializedElementProperties as ah, SpatializedElementType as ai, type SpatializedMotionConfig as aj, type SpatializedMotionKind as ak, type SpatializedMotionPlayState as al, type SpatializedMotionSegmentConfig as am, type SpatializedMotionTimelineConfig as an, type SpatializedPlaybackApi as ao, type SpatializedStatic3DElementProperties as ap, type StageMode as aq, type TimingFunction as ar, type TransformValues as as, type Vec3 as at, type WorldAlignmentType as au, WorldAlignmentValues as av, type WorldScalingType as aw, WorldScalingValues as ax, type XRMainSceneConfig as ay, type XRPrdConfig as az, type AnimatedProps as b, AnimationObject as b0, type AnimationObjectCallbacks as b1, type AnimationObjectCreateOptions as b2, type AnimationCanceledEventPayload as b3, type AnimationCompletedEventPayload as b4, type AnimationFailedEventPayload as b5, type EntityTransformChangeDetail as b6, type ObjectDestroyMsg as b7, type SpatialDragEndMsg as b8, type SpatialDragMsg as b9, type SpatialDragStartMsg as ba, type SpatialMagnifyEndMsg as bb, type SpatialMagnifyMsg as bc, type SpatialRotateEndMsg as bd, type SpatialRotateMsg as be, type SpatialTapMsg as bf, SPATIALIZED_MOTION_PROPERTIES as bg, type SpatializedMotionKeyframe as bh, type SpatializedMotionKeyframeValues as bi, type SpatializedMotionTrack as bj, type SpatialAnimationStateChangedDetail as bk, type SpatialAnimationStateChangedMsg as bl, type AnimatedPropsInternal as c, type AnimationApi as d, type AnimationConfig as e, type AnimationError as f, type AnimationPlayState as g, type AttachmentEntityOptions as h, type AttachmentEntityUpdateOptions as i, type BaseplateVisibilityType as j, BaseplateVisibilityValues as k, CubeInfo as l, type ModelComponentOptions as m, type ModelLoadingMode as n, type ModelSource as o, type Point3D as p, type SceneUnitM as q, type SceneUnitPx as r, type Size as s, type Size3D as t, type SpatialBoxGeometryOptions as u, type SpatialConeGeometryOptions as v, type SpatialCylinderGeometryOptions as w, type SpatialDragEndEvent as x, type SpatialDragEndEventDetail as y, type SpatialDragEvent as z };