@webspatial/core-sdk 1.4.0 → 1.6.0

package/dist/index.d.ts

@@ -57,6 +57,7 @@ declare enum SpatialWebMsgType {
     spatialrotateend = "spatialrotateend",
     spatialmagnify = "spatialmagnify",
     spatialmagnifyend = "spatialmagnifyend",
+    animationstatechange = "animationstatechange",
     objectdestroy = "objectdestroy"
 }
 interface ObjectDestroyMsg {
@@ -86,6 +87,23 @@ interface SpatialRotateEndMsg {
     type: SpatialWebMsgType.spatialrotateend;
     detail: SpatialRotateEventDetail;
 }
+interface ModelLoadSuccess {
+    type: SpatialWebMsgType.modelloaded;
+    detail?: {
+        src: string;
+    };
+}
+interface ModelLoadFailure {
+    type: SpatialWebMsgType.modelloadfailed;
+}
+interface AnimationStateChangeDetail {
+    paused: boolean;
+    duration: number;
+}
+interface AnimationStateChangeMsg {
+    type: SpatialWebMsgType.animationstatechange;
+    detail: AnimationStateChangeDetail;
+}
 
 /**
  * Abstract base class for all spatialized elements in the WebSpatial environment.
@@ -148,7 +166,7 @@ declare abstract class SpatializedElement extends SpatialObject {
      * Handles various spatial events like transforms, gestures, and interactions.
      * @param data The event data received from the WebSpatial system
      */
-    protected onReceiveEvent(data: SpatialTapMsg | SpatialDragStartMsg | SpatialDragMsg | SpatialDragEndMsg | SpatialRotateMsg | SpatialRotateEndMsg | ObjectDestroyMsg): void;
+    protected onReceiveEvent(data: ReceiveEventData): void;
     private _onSpatialTap?;
     set onSpatialTap(value: (event: SpatialTapEvent) => void | undefined);
     private _onSpatialDragStart?;
@@ -171,6 +189,7 @@ declare abstract class SpatializedElement extends SpatialObject {
      */
     onDestroy(): void;
 }
+type ReceiveEventData = SpatialTapMsg | SpatialDragStartMsg | SpatialDragMsg | SpatialDragEndMsg | SpatialRotateMsg | SpatialRotateEndMsg | ObjectDestroyMsg;
 
 declare class SpatializedDynamic3DElement extends SpatializedElement {
     children: SpatialEntityOrReality[];
@@ -259,9 +278,18 @@ interface Spatialized2DElementProperties extends SpatializedElementProperties {
     material: BackgroundMaterialType;
     scrollEdgeInsetsMarginRight: number;
 }
+interface ModelSource {
+    src: string;
+    type?: string;
+}
 interface SpatializedStatic3DElementProperties extends SpatializedElementProperties {
     modelURL: string;
+    sources?: ModelSource[];
     modelTransform?: number[];
+    autoplay?: boolean;
+    loop?: boolean;
+    animationPaused?: boolean;
+    playbackRate?: number;
 }
 interface SpatialSceneCreationOptions$1 {
     defaultSize?: {
@@ -436,6 +464,56 @@ interface AttachmentEntityUpdateOptions {
         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$1;
+}
+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;
+}
 
 declare class SpatialComponent extends SpatialObject {
     constructor(id: string);
@@ -455,6 +533,7 @@ declare class SpatialEntity extends SpatialObject {
     set enableInput(value: boolean);
     constructor(id: string, userData?: SpatialEntityUserData | undefined);
     addComponent(component: SpatialComponent): Promise<CommandResult>;
+    removeComponent(component: SpatialComponent): Promise<CommandResult>;
     setPosition(position: Vec3): Promise<CommandResult>;
     setRotation(rotation: Vec3): Promise<CommandResult>;
     setScale(scale: Vec3): Promise<CommandResult>;
@@ -477,6 +556,7 @@ declare class SpatialModelEntity extends SpatialEntity {
     options?: SpatialModelEntityCreationOptions | undefined;
     userData?: SpatialEntityUserData | undefined;
     constructor(id: string, options?: SpatialModelEntityCreationOptions | undefined, userData?: SpatialEntityUserData | undefined);
+    setMaterials(materials: SpatialMaterial[]): Promise<CommandResult>;
 }
 
 declare class ModelComponent extends SpatialComponent {
@@ -542,10 +622,6 @@ declare class Attachment extends SpatialObject {
 }
 declare function createAttachmentEntity(options: AttachmentEntityOptions): Promise<Attachment>;
 
-declare function initScene(name: string, callback: (pre: SpatialSceneCreationOptions$1) => SpatialSceneCreationOptions$1, options?: {
-    type: SpatialSceneType$1;
-}): void;
-
 type SpatialSceneCreationOptionsInternal = SpatialSceneCreationOptions$1 & {
     type: SpatialSceneType$1;
 };
@@ -557,6 +633,10 @@ declare enum SpatialSceneState {
     fail = "fail"
 }
 
+declare function initScene(name: string, callback: (pre: SpatialSceneCreationOptions$1) => SpatialSceneCreationOptions$1, options?: {
+    type: SpatialSceneType$1;
+}): void;
+
 /**
  * Represents the spatial scene that contains all spatialized elements.
  * This class follows the singleton pattern - only one instance exists per application.
@@ -639,8 +719,9 @@ declare class SpatializedStatic3DElement extends SpatializedElement {
      * Registers the element to receive spatial events.
      * @param id Unique identifier for this element
      * @param modelURL URL of the 3D model
+     * @param sources Optional fallback model sources
      */
-    constructor(id: string, modelURL: string);
+    constructor(id: string, modelURL?: string, sources?: ModelSource[]);
     /**
      * Promise resolver for the ready state.
      * Used to resolve the ready promise when the model is loaded.
@@ -650,7 +731,16 @@ declare class SpatializedStatic3DElement extends SpatializedElement {
      * Caches the last model URL to detect changes.
      * Used to reset the ready promise when the model URL changes.
      */
-    private modelURL;
+    private modelURL?;
+    /**
+     * Caches the last sources array to detect changes.
+     */
+    private sources?;
+    /**
+     * The model URL that was successfully loaded by the native runtime.
+     */
+    private _currentSrc;
+    get currentSrc(): string;
     /**
      * Creates a new promise for tracking the ready state of the model.
      * @returns Promise that resolves when the model is loaded (true) or fails to load (false)
@@ -668,14 +758,74 @@ declare class SpatializedStatic3DElement extends SpatializedElement {
      * @returns Promise resolving when the update is complete
      */
     updateProperties(properties: Partial<SpatializedStatic3DElementProperties>): Promise<CommandResult>;
+    /**
+     * Total animation duration in seconds, synced from native.
+     */
+    private _duration;
+    /**
+     * Returns the total animation duration in seconds.
+     */
+    get duration(): number;
+    /**
+     * Playback speed multiplier.
+     */
+    private _playbackRate;
+    /**
+     * Returns the current playback rate.
+     */
+    get playbackRate(): number;
+    /**
+     * Sets the playback rate and sends it to native.
+     */
+    set playbackRate(value: number);
+    /**
+     * Whether the animation is currently paused.
+     */
+    private _paused;
+    /**
+     * Returns whether the animation is currently paused.
+     */
+    get paused(): boolean;
+    /**
+     * Callback for animation state changes.
+     */
+    private _onAnimationStateChangeCallback?;
+    /**
+     * Sets the callback for animation state changes.
+     */
+    set onAnimationStateChangeCallback(callback: undefined | ((detail: AnimationStateChangeDetail) => void));
+    /**
+     * Starts or resumes animation playback.
+     * @returns Promise resolving when the command is sent
+     */
+    play(): Promise<void>;
+    /**
+     * Pauses animation playback.
+     * @returns Promise resolving when the command is sent
+     */
+    pause(): Promise<void>;
     /**
      * Processes events received from the WebSpatial environment.
      * Handles model loading events in addition to base spatial events.
      * @param data The event data received from the WebSpatial system
      */
-    onReceiveEvent(data: {
-        type: SpatialWebMsgType;
-    }): void;
+    onReceiveEvent(data: Static3DReceiveEventData): void;
+    /**
+     * Whether the model should automatically play its first animation on load.
+     */
+    private _autoplay;
+    /**
+     * Returns whether autoplay is enabled for this element.
+     */
+    get autoplay(): boolean;
+    /**
+     * Whether the model animation should loop continuously.
+     */
+    private _loop;
+    /**
+     * Returns whether loop is enabled for this element.
+     */
+    get loop(): boolean;
     /**
      * Callback function for successful model loading.
      */
@@ -696,6 +846,7 @@ declare class SpatializedStatic3DElement extends SpatializedElement {
     set onLoadFailureCallback(callback: undefined | (() => void));
     updateModelTransform(transform: DOMMatrixReadOnly): void;
 }
+type Static3DReceiveEventData = ModelLoadSuccess | ModelLoadFailure | ReceiveEventData | AnimationStateChangeMsg;
 
 /**
  * Session used to establish a connection to the spatial renderer of the system.
@@ -721,7 +872,7 @@ declare class SpatialSession {
      * @param modelURL Optional URL to the 3D model to load
      * @returns Promise resolving to a new SpatializedStatic3DElement instance
      */
-    createSpatializedStatic3DElement(modelURL: string): Promise<SpatializedStatic3DElement>;
+    createSpatializedStatic3DElement(modelURL?: string, sources?: ModelSource[]): Promise<SpatializedStatic3DElement>;
     /**
      * Initializes the spatial scene with custom configuration.
      * This is a reference to the initScene function from scene-polyfill.
@@ -916,6 +1067,14 @@ declare global {
     webkit: any
     webspatialBridge: any
 
+    // Project Pico OS browser injects this global object to provide internal capabilities.
+    webSpatial?: {
+      genToken?: () => string
+    }
+    __webspatialShell__?: {
+      genToken?: () => string
+    }
+
     // Will be removed in favor of __WebSpatialData
     WebSpatailNativeVersion: string
 
@@ -939,4 +1098,4 @@ declare global {
 
 declare const isSSREnv: () => boolean;
 
-export { Attachment, type AttachmentEntityOptions, type AttachmentEntityUpdateOptions, type BackgroundMaterialType, type BaseplateVisibilityType, BaseplateVisibilityValues, type CornerRadius, CubeInfo, type ModelAssetOptions, ModelComponent, type ModelComponentOptions, physicalMetrics as PhysicalMetrics, type Point3D, type Quaternion, type Size, type Size3D, Spatial, SpatialBoxGeometry, type SpatialBoxGeometryOptions, SpatialComponent, SpatialConeGeometry, type SpatialConeGeometryOptions, SpatialCylinderGeometry, type SpatialCylinderGeometryOptions, type SpatialDragEndEvent, type SpatialDragEndEventDetail, type SpatialDragEvent, type SpatialDragEventDetail, type SpatialDragStartEvent, type SpatialDragStartEventDetail, SpatialEntity, type SpatialEntityEventType, type SpatialEntityOrReality, type SpatialEntityProperties, type SpatialEntityUserData, SpatialGeometry, type SpatialGeometryOptions, type SpatialGeometryType, type SpatialMagnifyEndEvent, type SpatialMagnifyEndEventDetail, type SpatialMagnifyEvent, type SpatialMagnifyEventDetail, SpatialMaterial, type SpatialMaterialType, SpatialModelAsset, type SpatialModelDragEvent, SpatialModelEntity, type SpatialModelEntityCreationOptions, SpatialObject, SpatialPlaneGeometry, type SpatialPlaneGeometryOptions, type SpatialRotateEndEvent, type SpatialRotateEndEventDetail, type SpatialRotateEvent, type SpatialRotateEventDetail, SpatialScene, type SpatialSceneCreationOptions$1 as SpatialSceneCreationOptions, type SpatialSceneProperties, SpatialSceneState$1 as SpatialSceneState, type SpatialSceneType$1 as SpatialSceneType, SpatialSceneValues, SpatialSession, SpatialSphereGeometry, type SpatialSphereGeometryOptions, type SpatialTapEvent, type SpatialTapEventDetail, SpatialUnlitMaterial, type SpatialUnlitMaterialOptions, Spatialized2DElement, type Spatialized2DElementProperties, SpatializedDynamic3DElement, SpatializedElement, type SpatializedElementProperties, SpatializedElementType, SpatializedStatic3DElement, type SpatializedStatic3DElementProperties, type Vec3, type WorldAlignmentType, WorldAlignmentValues, type WorldScalingType, WorldScalingValues, createAttachmentEntity, isSSREnv, isValidBaseplateVisibilityType, isValidSceneUnit, isValidSpatialSceneType, isValidWorldAlignmentType, isValidWorldScalingType };
+export { Attachment, type AttachmentEntityOptions, type AttachmentEntityUpdateOptions, type BackgroundMaterialType, type BaseplateVisibilityType, BaseplateVisibilityValues, type CornerRadius, CubeInfo, type ModelAssetOptions, ModelComponent, type ModelComponentOptions, type ModelSource, type PWAManifest, physicalMetrics as PhysicalMetrics, type Point3D, type Quaternion, type SceneUnit, type SceneUnitM, type SceneUnitPx, type Size, type Size3D, Spatial, SpatialBoxGeometry, type SpatialBoxGeometryOptions, SpatialComponent, SpatialConeGeometry, type SpatialConeGeometryOptions, SpatialCylinderGeometry, type SpatialCylinderGeometryOptions, type SpatialDragEndEvent, type SpatialDragEndEventDetail, type SpatialDragEvent, type SpatialDragEventDetail, type SpatialDragStartEvent, type SpatialDragStartEventDetail, SpatialEntity, type SpatialEntityEventType, type SpatialEntityOrReality, type SpatialEntityProperties, type SpatialEntityUserData, SpatialGeometry, type SpatialGeometryOptions, type SpatialGeometryType, type SpatialMagnifyEndEvent, type SpatialMagnifyEndEventDetail, type SpatialMagnifyEvent, type SpatialMagnifyEventDetail, SpatialMaterial, type SpatialMaterialType, SpatialModelAsset, type SpatialModelDragEvent, SpatialModelEntity, type SpatialModelEntityCreationOptions, SpatialObject, SpatialPlaneGeometry, type SpatialPlaneGeometryOptions, type SpatialRotateEndEvent, type SpatialRotateEndEventDetail, type SpatialRotateEvent, type SpatialRotateEventDetail, SpatialScene, type SpatialSceneCreationOptions$1 as SpatialSceneCreationOptions, type SpatialSceneProperties, SpatialSceneState$1 as SpatialSceneState, type SpatialSceneType$1 as SpatialSceneType, SpatialSceneValues, SpatialSession, SpatialSphereGeometry, type SpatialSphereGeometryOptions, type SpatialTapEvent, type SpatialTapEventDetail, SpatialUnlitMaterial, type SpatialUnlitMaterialOptions, Spatialized2DElement, type Spatialized2DElementProperties, SpatializedDynamic3DElement, SpatializedElement, type SpatializedElementProperties, SpatializedElementType, SpatializedStatic3DElement, type SpatializedStatic3DElementProperties, type Vec3, type WorldAlignmentType, WorldAlignmentValues, type WorldScalingType, WorldScalingValues, type XRMainSceneConfig, type XRPrdConfig, type XRSceneResizability, type XRSceneSize, type XRSpatialSceneConfig, type XRSpatialSceneDefaults, type XRSpatialSceneOverrides, createAttachmentEntity, isSSREnv, isValidBaseplateVisibilityType, isValidSceneUnit, isValidSpatialSceneType, isValidWorldAlignmentType, isValidWorldScalingType };