@webspatial/core-sdk 1.6.0 → 1.7.0

package/dist/index.d.ts

@@ -1,3 +1,50 @@
+type PhysicalMetricsValueShape = {
+    meterToPtUnscaled: number;
+    meterToPtScaled: number;
+};
+type WorldScalingCompensation = 'unscaled' | 'scaled';
+type ConvertOption = {
+    worldScalingCompensation: WorldScalingCompensation;
+};
+/**
+ * Converts scene points (pt) to physical meters (m).
+ *
+ * @param point Points value to convert.
+ * @param options Optional conversion options to select world scaling compensation.
+ * @returns Physical length in meters.
+ */
+declare function pointToPhysical(point: number, options?: ConvertOption): number;
+/**
+ * Converts physical meters (m) to scene points (pt).
+ *
+ * @param physical Physical length in meters to convert.
+ * @param options Optional conversion options to select world scaling compensation.
+ * @returns Points length in the scene.
+ */
+declare function physicalToPoint(physical: number, options?: ConvertOption): number;
+/**
+ * Returns the current physical metrics used for conversions.
+ *
+ * @returns The current metrics snapshot `{ meterToPtUnscaled, meterToPtScaled }`.
+ */
+declare function getValue(): PhysicalMetricsValueShape;
+/**
+ * Subscribes to physical metrics changes.
+ *
+ * @param cb Callback invoked when metrics update is detected.
+ * @returns Unsubscribe function to remove the listener.
+ */
+declare function subscribe(cb: () => void): () => void;
+
+type physicalMetrics_PhysicalMetricsValueShape = PhysicalMetricsValueShape;
+declare const physicalMetrics_getValue: typeof getValue;
+declare const physicalMetrics_physicalToPoint: typeof physicalToPoint;
+declare const physicalMetrics_pointToPhysical: typeof pointToPhysical;
+declare const physicalMetrics_subscribe: typeof subscribe;
+declare namespace physicalMetrics {
+  export { type physicalMetrics_PhysicalMetricsValueShape as PhysicalMetricsValueShape, physicalMetrics_getValue as getValue, physicalMetrics_physicalToPoint as physicalToPoint, physicalMetrics_pointToPhysical as pointToPhysical, physicalMetrics_subscribe as subscribe };
+}
+
 /**
  * @hidden
  * Parent class of spatial objects, should not be used directly
@@ -16,22 +63,6 @@ declare class SpatialObject {
     protected onDestroy(): void;
 }
 
-interface CommandResult {
-    success: boolean;
-    data: any;
-    errorCode: string | undefined;
-    errorMessage: string | undefined;
-}
-interface WebSpatialProtocolResult extends CommandResult {
-    success: boolean;
-    data: {
-        windowProxy: WindowProxy;
-        id: string;
-    } | undefined;
-    errorCode: string | undefined;
-    errorMessage: string | undefined;
-}
-
 declare class SpatialGeometry extends SpatialObject {
     id: string;
     options: SpatialGeometryOptions;
@@ -46,6 +77,142 @@ declare abstract class SpatialMaterial extends SpatialObject {
     abstract updateProperties(properties: any): void;
 }
 
+type SpatialSceneCreationOptionsInternal = SpatialSceneCreationOptions & {
+    type: SpatialSceneType;
+};
+declare enum SpatialSceneState$1 {
+    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>;
+
+declare class SpatialComponent extends SpatialObject {
+    constructor(id: string);
+    private onReceiveEvent;
+}
+
+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>>;
+    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>>;
+}
+
+declare class SpatialModelEntity extends SpatialEntity {
+    id: string;
+    options?: SpatialModelEntityCreationOptions | undefined;
+    userData?: SpatialEntityUserData | undefined;
+    constructor(id: string, options?: SpatialModelEntityCreationOptions | undefined, userData?: SpatialEntityUserData | undefined);
+    setMaterials(materials: SpatialMaterial[]): Promise<CommandResult<any>>;
+}
+
+declare class ModelComponent extends SpatialComponent {
+    options: ModelComponentOptions;
+    constructor(id: string, options: ModelComponentOptions);
+}
+
+declare class SpatialUnlitMaterial extends SpatialMaterial {
+    id: string;
+    options: SpatialUnlitMaterialOptions;
+    constructor(id: string, options: SpatialUnlitMaterialOptions);
+    updateProperties(properties: Partial<SpatialUnlitMaterialOptions>): Promise<CommandResult<any>>;
+}
+
+declare class SpatialBoxGeometry extends SpatialGeometry {
+    id: string;
+    options: SpatialBoxGeometryOptions;
+    static type: SpatialGeometryType;
+    constructor(id: string, options: SpatialBoxGeometryOptions);
+}
+
+declare class SpatialSphereGeometry extends SpatialGeometry {
+    id: string;
+    options: SpatialSphereGeometryOptions;
+    static type: SpatialGeometryType;
+    constructor(id: string, options: SpatialSphereGeometryOptions);
+}
+
+declare class SpatialCylinderGeometry extends SpatialGeometry {
+    id: string;
+    options: SpatialCylinderGeometryOptions;
+    static type: SpatialGeometryType;
+    constructor(id: string, options: SpatialCylinderGeometryOptions);
+}
+
+declare class SpatialPlaneGeometry extends SpatialGeometry {
+    id: string;
+    options: SpatialPlaneGeometryOptions;
+    static type: SpatialGeometryType;
+    constructor(id: string, options: SpatialPlaneGeometryOptions);
+}
+
+declare class SpatialConeGeometry extends SpatialGeometry {
+    id: string;
+    options: SpatialConeGeometryOptions;
+    static type: SpatialGeometryType;
+    constructor(id: string, options: SpatialConeGeometryOptions);
+}
+
+declare class SpatialModelAsset extends SpatialObject {
+    id: string;
+    options: ModelAssetOptions;
+    constructor(id: string, options: ModelAssetOptions);
+}
+
+declare class SpatialTextureResource extends SpatialObject {
+    id: string;
+    options: SpatialTextureResourceOptions;
+    constructor(id: string, options: SpatialTextureResourceOptions);
+    updateProperties(properties: Partial<SpatialTextureResourceOptions>): Promise<CommandResult<any>>;
+}
+
+declare class Attachment extends SpatialObject {
+    private readonly windowProxy;
+    private options;
+    constructor(id: string, windowProxy: WindowProxy, options: AttachmentEntityOptions);
+    getContainer(): HTMLElement;
+    getWindowProxy(): WindowProxy;
+    update(options: AttachmentEntityUpdateOptions): Promise<CommandResult<any> | undefined>;
+}
+declare function createAttachmentEntity(options: AttachmentEntityOptions): Promise<Attachment>;
+
 declare enum SpatialWebMsgType {
     modelloaded = "modelloaded",
     modelloadfailed = "modelloadfailed",
@@ -99,6 +266,16 @@ interface ModelLoadFailure {
 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;
@@ -131,7 +308,7 @@ declare abstract class SpatializedElement extends SpatialObject {
      * @param matrix The new transformation matrix
      * @returns Promise resolving when the transform is updated
      */
-    updateTransform(matrix: DOMMatrix): Promise<CommandResult>;
+    updateTransform(matrix: DOMMatrix): Promise<CommandResult<any>>;
     /**
      * Information about the element's bounding cube.
      * Used for spatial calculations and hit testing.
@@ -195,11 +372,11 @@ declare class SpatializedDynamic3DElement extends SpatializedElement {
     children: SpatialEntityOrReality[];
     events: Record<string, (data: any) => void>;
     constructor(id: string);
-    addEntity(entity: SpatialEntity): Promise<CommandResult>;
+    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>;
+    updateProperties(properties: Partial<SpatializedElementProperties>): Promise<CommandResult<any>>;
 }
 
 interface Vec3 {
@@ -282,6 +459,7 @@ interface ModelSource {
     src: string;
     type?: string;
 }
+type ModelLoadingMode = 'eager' | 'lazy';
 interface SpatializedStatic3DElementProperties extends SpatializedElementProperties {
     modelURL: string;
     sources?: ModelSource[];
@@ -290,8 +468,11 @@ interface SpatializedStatic3DElementProperties extends SpatializedElementPropert
     loop?: boolean;
     animationPaused?: boolean;
     playbackRate?: number;
+    currentTime?: number;
+    posterURL?: string;
+    loading?: ModelLoadingMode;
 }
-interface SpatialSceneCreationOptions$1 {
+interface SpatialSceneCreationOptions {
     defaultSize?: {
         width: number | string;
         height: number | string;
@@ -318,7 +499,7 @@ declare const WorldAlignmentValues: readonly ["adaptive", "automatic", "gravityA
 type WorldAlignmentType = (typeof WorldAlignmentValues)[number];
 declare function isValidWorldAlignmentType(type: string): Boolean;
 declare const SpatialSceneValues: readonly ["window", "volume"];
-type SpatialSceneType$1 = (typeof SpatialSceneValues)[number];
+type SpatialSceneType = (typeof SpatialSceneValues)[number];
 declare function isValidSpatialSceneType(type: string): Boolean;
 /**
  * check px,m and number, number must be >= 0
@@ -362,6 +543,9 @@ interface SpatialUnlitMaterialOptions {
     transparent?: boolean;
     opacity?: number;
 }
+interface SpatialTextureResourceOptions {
+    url: string;
+}
 interface ModelComponentOptions {
     mesh: SpatialGeometry;
     materials: SpatialMaterial[];
@@ -377,7 +561,7 @@ interface SpatialModelEntityCreationOptions {
 interface ModelAssetOptions {
     url: string;
 }
-declare enum SpatialSceneState$1 {
+declare enum SpatialSceneState {
     idle = "idle",
     pending = "pending",
     willVisible = "willVisible",
@@ -479,7 +663,7 @@ interface XRSceneResizability {
     maxHeight?: SceneUnit;
 }
 interface XRMainSceneConfig extends XRSpatialSceneDefaults {
-    type?: SpatialSceneType$1;
+    type?: SpatialSceneType;
 }
 interface XRSpatialSceneDefaults {
     default_size?: XRSceneSize;
@@ -515,126 +699,47 @@ interface PWAManifest extends XRPrdConfig {
     [key: string]: any;
 }
 
-declare class SpatialComponent extends SpatialObject {
-    constructor(id: string);
-    private onReceiveEvent;
-}
-
-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>;
-    removeComponent(component: SpatialComponent): Promise<CommandResult>;
-    setPosition(position: Vec3): Promise<CommandResult>;
-    setRotation(rotation: Vec3): Promise<CommandResult>;
-    setScale(scale: Vec3): Promise<CommandResult>;
-    addEntity(ent: SpatialEntity): Promise<CommandResult>;
-    removeFromParent(): Promise<CommandResult>;
-    updateTransform(properties: Partial<SpatialEntityProperties>): Promise<CommandResult>;
-    addEvent(type: SpatialEntityEventType, callback: (data: any) => void): Promise<void>;
-    removeEvent(eventName: SpatialEntityEventType): Promise<void>;
-    updateEntityEvent(eventName: SpatialEntityEventType, isEnable: boolean): Promise<CommandResult>;
-    private onReceiveEvent;
-    dispatchEvent(evt: CustomEvent): void;
-    protected onDestroy(): void;
-    convertFromEntityToEntity(fromEntityId: string, toEntityId: string, position: Vec3): Promise<CommandResult>;
-    convertFromEntityToScene(fromEntityId: string, position: Vec3): Promise<CommandResult>;
-    convertFromSceneToEntity(entityId: string, position: Vec3): Promise<CommandResult>;
-}
-
-declare class SpatialModelEntity extends SpatialEntity {
-    id: string;
-    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 {
-    options: ModelComponentOptions;
-    constructor(id: string, options: ModelComponentOptions);
-}
-
-declare class SpatialUnlitMaterial extends SpatialMaterial {
-    id: string;
-    options: SpatialUnlitMaterialOptions;
-    constructor(id: string, options: SpatialUnlitMaterialOptions);
-    updateProperties(properties: Partial<SpatialUnlitMaterialOptions>): Promise<CommandResult>;
-}
-
-declare class SpatialBoxGeometry extends SpatialGeometry {
-    id: string;
-    options: SpatialBoxGeometryOptions;
-    static type: SpatialGeometryType;
-    constructor(id: string, options: SpatialBoxGeometryOptions);
-}
-
-declare class SpatialSphereGeometry extends SpatialGeometry {
-    id: string;
-    options: SpatialSphereGeometryOptions;
-    static type: SpatialGeometryType;
-    constructor(id: string, options: SpatialSphereGeometryOptions);
-}
-
-declare class SpatialCylinderGeometry extends SpatialGeometry {
-    id: string;
-    options: SpatialCylinderGeometryOptions;
-    static type: SpatialGeometryType;
-    constructor(id: string, options: SpatialCylinderGeometryOptions);
-}
-
-declare class SpatialPlaneGeometry extends SpatialGeometry {
-    id: string;
-    options: SpatialPlaneGeometryOptions;
-    static type: SpatialGeometryType;
-    constructor(id: string, options: SpatialPlaneGeometryOptions);
-}
-
-declare class SpatialConeGeometry extends SpatialGeometry {
-    id: string;
-    options: SpatialConeGeometryOptions;
-    static type: SpatialGeometryType;
-    constructor(id: string, options: SpatialConeGeometryOptions);
-}
-
-declare class SpatialModelAsset extends SpatialObject {
-    id: string;
-    options: ModelAssetOptions;
-    constructor(id: string, options: ModelAssetOptions);
-}
-
-declare class Attachment extends SpatialObject {
-    private readonly windowProxy;
-    private options;
-    constructor(id: string, windowProxy: WindowProxy, options: AttachmentEntityOptions);
-    getContainer(): HTMLElement;
-    getWindowProxy(): WindowProxy;
-    update(options: AttachmentEntityUpdateOptions): Promise<CommandResult | undefined>;
-}
-declare function createAttachmentEntity(options: AttachmentEntityOptions): Promise<Attachment>;
-
-type SpatialSceneCreationOptionsInternal = SpatialSceneCreationOptions$1 & {
-    type: SpatialSceneType$1;
-};
-declare enum SpatialSceneState {
-    idle = "idle",
-    pending = "pending",
-    willVisible = "willVisible",
-    visible = "visible",
-    fail = "fail"
+declare global {
+    const __WEBSPATIAL_CORE_SDK_VERSION__: string;
+    interface Window {
+        xrCurrentSceneType: SpatialSceneType;
+        xrCurrentSceneDefaults: (defaultConfig: SpatialSceneCreationOptions) => Promise<SpatialSceneCreationOptions>;
+        __WebSpatialData: {
+            androidNativeMessage: Function;
+            getNativeVersion: Function;
+        };
+        __SpatialWebEvent: Function;
+        webkit: any;
+        webspatialBridge: any;
+        webSpatial?: {
+            genToken?: () => string;
+        };
+        __webspatialShell__?: {
+            genToken?: () => string;
+        };
+        WebSpatailNativeVersion: string;
+        __webspatialsdk__?: {
+            XR_ENV?: string;
+            'natvie-version'?: string;
+            'react-sdk-version'?: string;
+            'core-sdk-version'?: string;
+            physicalMetrics?: PhysicalMetricsValueShape;
+        };
+        /** Present when `supports('xrInnerDepth')` is true; otherwise `undefined`. */
+        xrInnerDepth?: number;
+        /** Present when `supports('xrOuterDepth')` is true; otherwise `undefined`. */
+        xrOuterDepth?: number;
+    }
+    interface HTMLElement {
+        /** Present when `supports('xrOffsetBack')` is true for element readbacks. */
+        xrOffsetBack?: number;
+        /** Present when `supports('xrClientDepth')` is true for element readbacks. */
+        xrClientDepth?: number;
+    }
 }
 
-declare function initScene(name: string, callback: (pre: SpatialSceneCreationOptions$1) => SpatialSceneCreationOptions$1, options?: {
-    type: SpatialSceneType$1;
+declare function initScene(name: string, callback: (pre: SpatialSceneCreationOptions) => SpatialSceneCreationOptions, options?: {
+    type: SpatialSceneType;
 }): void;
 
 /**
@@ -656,27 +761,27 @@ declare class SpatialScene extends SpatialObject {
      * @param properties Partial set of properties to update
      * @returns Promise resolving when the update is complete
      */
-    updateSpatialProperties(properties: Partial<SpatialSceneProperties>): Promise<CommandResult>;
+    updateSpatialProperties(properties: Partial<SpatialSceneProperties>): Promise<CommandResult<any>>;
     /**
      * Adds a spatialized element to the scene.
      * This makes the element visible and interactive in the spatial environment.
      * @param element The SpatializedElement to add to the scene
      * @returns Promise resolving when the element is added
      */
-    addSpatializedElement(element: SpatializedElement): Promise<CommandResult>;
+    addSpatializedElement(element: SpatializedElement): Promise<CommandResult<any>>;
     /**
      * Updates the scene creation configuration.
      * This allows changing scene parameters after initial creation.
      * @param config The new scene creation configuration
      * @returns Promise resolving when the update is complete
      */
-    updateSceneCreationConfig(config: SpatialSceneCreationOptionsInternal): Promise<CommandResult>;
+    updateSceneCreationConfig(config: SpatialSceneCreationOptionsInternal): Promise<CommandResult<any>>;
     /**
      * Gets the current state of the spatial scene.
      * This includes information about active elements and scene configuration.
      * @returns Promise resolving to the current SpatialSceneState
      */
-    getState(): Promise<SpatialSceneState>;
+    getState(): Promise<SpatialSceneState$1>;
 }
 
 /**
@@ -698,14 +803,14 @@ declare class Spatialized2DElement extends SpatializedElement {
      * @param properties Partial set of properties to update
      * @returns Promise resolving when the update is complete
      */
-    updateProperties(properties: Partial<Spatialized2DElementProperties>): Promise<CommandResult>;
+    updateProperties(properties: Partial<Spatialized2DElementProperties>): Promise<CommandResult<any>>;
     /**
      * Adds a child spatialized element to this 2D element.
      * This allows for creating hierarchical structures of spatial elements.
      * @param element The child element to add
      * @returns Promise resolving when the element is added
      */
-    addSpatializedElement(element: SpatializedElement): Promise<CommandResult>;
+    addSpatializedElement(element: SpatializedElement): Promise<CommandResult<any>>;
 }
 
 /**
@@ -720,8 +825,9 @@ declare class SpatializedStatic3DElement extends SpatializedElement {
      * @param id Unique identifier for this element
      * @param modelURL URL of the 3D model
      * @param sources Optional fallback model sources
+     * @param loading Initial loading mode (`'eager'` by default)
      */
-    constructor(id: string, modelURL?: string, sources?: ModelSource[]);
+    constructor(id: string, modelURL?: string, sources?: ModelSource[], loading?: ModelLoadingMode);
     /**
      * Promise resolver for the ready state.
      * Used to resolve the ready promise when the model is loaded.
@@ -732,6 +838,7 @@ declare class SpatializedStatic3DElement extends SpatializedElement {
      * Used to reset the ready promise when the model URL changes.
      */
     private modelURL?;
+    get modelUrl(): string | undefined;
     /**
      * Caches the last sources array to detect changes.
      */
@@ -757,7 +864,7 @@ declare class SpatializedStatic3DElement extends SpatializedElement {
      * @param properties Partial set of properties to update
      * @returns Promise resolving when the update is complete
      */
-    updateProperties(properties: Partial<SpatializedStatic3DElementProperties>): Promise<CommandResult>;
+    updateProperties(properties: Partial<SpatializedStatic3DElementProperties>): Promise<CommandResult<any>>;
     /**
      * Total animation duration in seconds, synced from native.
      */
@@ -778,6 +885,28 @@ declare class SpatializedStatic3DElement extends SpatializedElement {
      * Sets the playback rate and sends it to native.
      */
     set playbackRate(value: number);
+    /**
+     * Last playback position sampled from native (seconds).
+     */
+    private _currentTime;
+    /**
+     * Unix epoch time (ms) corresponding to `_currentTime`. Sourced from the
+     * native `timestamp` on samples, or `Date.now()` on local seeks/transitions.
+     */
+    private _anchorTimestamp;
+    private clampTime;
+    /**
+     * Returns the current (un-scaled) playback position in seconds. While
+     * playing, the value is extrapolated from the last anchor using
+     * `playbackRate` and clamped to `[0, duration]`; while paused it returns
+     * the anchor directly.
+     */
+    get currentTime(): number;
+    /**
+     * Seeks the animation to `value` seconds (clamped to `[0, duration]`) and
+     * forwards the request to native.
+     */
+    set currentTime(value: number);
     /**
      * Whether the animation is currently paused.
      */
@@ -818,6 +947,12 @@ declare class SpatializedStatic3DElement extends SpatializedElement {
      * Returns whether autoplay is enabled for this element.
      */
     get autoplay(): boolean;
+    /**
+     * Asset fetch policy. `'lazy'` defers fetching until the host signals the
+     * element is in view; `'eager'` fetches immediately.
+     */
+    private _loading;
+    get loading(): ModelLoadingMode;
     /**
      * Whether the model animation should loop continuously.
      */
@@ -870,9 +1005,11 @@ declare class SpatialSession {
      * Creates a new static 3D element with an optional model URL.
      * Static 3D elements represent pre-built 3D models that can be loaded from a URL.
      * @param modelURL Optional URL to the 3D model to load
+     * @param sources Optional list of fallback model sources
+     * @param loading Whether the asset should fetch eagerly or be deferred (`'lazy'`)
      * @returns Promise resolving to a new SpatializedStatic3DElement instance
      */
-    createSpatializedStatic3DElement(modelURL?: string, sources?: ModelSource[]): Promise<SpatializedStatic3DElement>;
+    createSpatializedStatic3DElement(modelURL?: string, sources?: ModelSource[], loading?: ModelLoadingMode): Promise<SpatializedStatic3DElement>;
     /**
      * Initializes the spatial scene with custom configuration.
      * This is a reference to the initScene function from scene-polyfill.
@@ -935,6 +1072,13 @@ declare class SpatialSession {
      * @returns Promise resolving to a new SpatialUnlitMaterial instance
      */
     createUnlitMaterial(options: SpatialUnlitMaterialOptions): Promise<SpatialUnlitMaterial>;
+    /**
+     * Creates a texture resource from the specified image URL.
+     * Texture resources can be referenced by materials and other spatial content.
+     * @param options Configuration options for the texture resource
+     * @returns Promise resolving to a new SpatialTextureResource instance
+     */
+    createTexture(options: SpatialTextureResourceOptions): Promise<SpatialTextureResource>;
     /**
      * Creates a model asset with the specified configuration.
      * Model assets represent 3D model resources that can be used by entities.
@@ -963,7 +1107,6 @@ declare class SpatialSession {
  * This is the main entry point for the WebSpatial SDK, providing access to spatial capabilities.
  */
 declare class Spatial {
-    private wsAppShellVersionFromUA;
     /**
      * Requests a spatial session object from the browser.
      * This is the primary method to initialize spatial functionality.
@@ -977,7 +1120,6 @@ declare class Spatial {
      * @returns True if running in a spatial web environment, false otherwise
      */
     runInSpatialWeb(): boolean;
-    getShellVersionFromUA(): string | null;
     /** @deprecated
      * Checks if WebSpatial is supported in the current environment.
      * Verifies compatibility between native and client versions.
@@ -998,104 +1140,112 @@ declare class Spatial {
     getClientVersion(): string;
 }
 
-type PhysicalMetricsValueShape = {
-    meterToPtUnscaled: number;
-    meterToPtScaled: number;
-};
-type WorldScalingCompensation = 'unscaled' | 'scaled';
-type ConvertOption = {
-    worldScalingCompensation: WorldScalingCompensation;
+/**
+ * Internal runtime classification (see OpenSpec `review.md`).
+ * `puppeteer`: automation / test harness UA — not a product matrix row; see `supports()`.
+ */
+type WebSpatialRuntimeType = 'visionos' | 'picoos' | 'puppeteer' | null;
+/** Snapshot returned by internal `getRuntime()` (not a public app API). */
+type WebSpatialRuntimeSnapshot = {
+    type: WebSpatialRuntimeType;
+    shellVersion: string | null;
 };
+
 /**
- * Converts scene points (pt) to physical meters (m).
- *
- * @param point Points value to convert.
- * @param options Optional conversion options to select world scaling compensation.
- * @returns Physical length in meters.
+ * Thrown when a runtime-gated JS API is invoked but `supports('<name>')` is false.
+ * See OpenSpec `runtime-capabilities/spec.md` (Unsupported behavior contracts).
  */
-declare function pointToPhysical(point: number, options?: ConvertOption): number;
+declare class WebSpatialRuntimeError extends Error {
+    readonly capability: string;
+    constructor(capability: string, message?: string);
+}
+
 /**
- * Converts physical meters (m) to scene points (pt).
- *
- * @param physical Physical length in meters to convert.
- * @param options Optional conversion options to select world scaling compensation.
- * @returns Points length in the scene.
+ * Canonical `supports(name)` keys (OpenSpec `review.md` §3).
+ * Aliases are normalized before lookup (see `normalizeCapabilityName`).
  */
-declare function physicalToPoint(physical: number, options?: ConvertOption): number;
+declare const COMPONENT_KEYS: readonly ["Model", "Reality", "Entity", "BoxEntity", "SphereEntity", "ConeEntity", "CylinderEntity", "PlaneEntity", "SceneGraph", "ModelAsset", "ModelEntity", "UnlitMaterial", "Material", "AttachmentAsset", "AttachmentEntity"];
+declare const CSS_KEYS: readonly ["-xr-background-material", "-xr-back", "-xr-depth", "-xr-transform"];
+declare const GESTURE_KEYS: readonly ["SpatialTapEvent", "SpatialDragStartEvent", "SpatialDragEvent", "SpatialDragEndEvent", "SpatialRotateEvent", "SpatialRotateEndEvent", "SpatialMagnifyEvent", "SpatialMagnifyEndEvent"];
+declare const JS_SCENE_KEYS: readonly ["useMetrics", "convertCoordinate", "initScene", "WindowScene", "VolumeScene"];
 /**
- * Returns the current physical metrics used for conversions.
- *
- * @returns The current metrics snapshot `{ meterToPtUnscaled, meterToPtScaled }`.
+ * Spatialized container `ref` readbacks (`HTMLElement` / React `useDomProxy` Proxy).
+ * See `global.d.ts` (`HTMLElement`) and `useDomProxy.ts` (`has` / `get` traps).
  */
-declare function getValue(): PhysicalMetricsValueShape;
+declare const ELEMENT_DOM_DEPTH_KEYS: readonly ["xrClientDepth", "xrOffsetBack"];
 /**
- * Subscribes to physical metrics changes.
- *
- * @param cb Callback invoked when metrics update is detected.
- * @returns Unsubscribe function to remove the listener.
+ * Scene / global readbacks on `Window` (`global.d.ts` → `Window`).
  */
-declare function subscribe(cb: () => void): () => void;
-
-type physicalMetrics_PhysicalMetricsValueShape = PhysicalMetricsValueShape;
-declare const physicalMetrics_getValue: typeof getValue;
-declare const physicalMetrics_physicalToPoint: typeof physicalToPoint;
-declare const physicalMetrics_pointToPhysical: typeof pointToPhysical;
-declare const physicalMetrics_subscribe: typeof subscribe;
-declare namespace physicalMetrics {
-  export { type physicalMetrics_PhysicalMetricsValueShape as PhysicalMetricsValueShape, physicalMetrics_getValue as getValue, physicalMetrics_physicalToPoint as physicalToPoint, physicalMetrics_pointToPhysical as pointToPhysical, physicalMetrics_subscribe as subscribe };
-}
-
-declare global {
-  declare const __WEBSPATIAL_CORE_SDK_VERSION__: string
-
-  interface Window {
-    xrCurrentSceneType: SpatialSceneType
-    xrCurrentSceneDefaults: (
-      defaultConfig: SpatialSceneCreationOptions,
-    ) => Promise<SpatialSceneCreationOptions>
-
-    // Location for webspatial custom functions
-    __WebSpatialData: {
-      androidNativeMessage: Function
-      getNativeVersion: Function
-    }
-
-    // Location for webspatial internal callbacks (eg. completion events)
-    __SpatialWebEvent: Function
-
-    // Used to access webkit specific api
-    webkit: any
-    webspatialBridge: any
+declare const WINDOW_DOM_DEPTH_KEYS: readonly ["xrInnerDepth", "xrOuterDepth"];
+declare const DOM_DEPTH_KEYS: readonly ["xrClientDepth", "xrOffsetBack", "xrInnerDepth", "xrOuterDepth"];
+/** Top-level names accepted by `supports(name)` (canonical keys after alias normalization). */
+declare const TOP_LEVEL_KEYS: readonly ["Model", "Reality", "Entity", "BoxEntity", "SphereEntity", "ConeEntity", "CylinderEntity", "PlaneEntity", "SceneGraph", "ModelAsset", "ModelEntity", "UnlitMaterial", "Material", "AttachmentAsset", "AttachmentEntity", "-xr-background-material", "-xr-back", "-xr-depth", "-xr-transform", "SpatialTapEvent", "SpatialDragStartEvent", "SpatialDragEvent", "SpatialDragEndEvent", "SpatialRotateEvent", "SpatialRotateEndEvent", "SpatialMagnifyEvent", "SpatialMagnifyEndEvent", "useMetrics", "convertCoordinate", "initScene", "WindowScene", "VolumeScene", "xrClientDepth", "xrOffsetBack", "xrInnerDepth", "xrOuterDepth"];
+/** Union of documented capability keys; unknown strings may still be passed to `supports` (returns `false`). */
+type CapabilityKey = (typeof TOP_LEVEL_KEYS)[number];
+/** Known sub-tokens per canonical top-level `name` (AND semantics). */
+declare const SUB_TOKENS_BY_NAME: Readonly<Record<string, readonly string[]>>;
 
-    // Project Pico OS browser injects this global object to provide internal capabilities.
-    webSpatial?: {
-      genToken?: () => string
-    }
-    __webspatialShell__?: {
-      genToken?: () => string
-    }
+/**
+ * Unsubstituted shell version placeholder from visionOS manifest / Xcode template
+ * (`manifest.swift`). When still present in `WSAppShell/<version>`, treat as debug
+ * build: {@link supports} returns true for every valid capability query.
+ */
+declare const VISIONOS_DEBUG_SHELL_VERSION_PLACEHOLDER = "WS_SHELL_VERSION";
+/** Test helper: clear cached UA/runtime snapshot between Vitest cases. */
+declare function resetRuntimeCacheForTests(): void;
+/**
+ * Internal runtime snapshot (not part of the public `@webspatial/react-sdk` surface).
+ */
+declare function getRuntime(): WebSpatialRuntimeSnapshot;
+/**
+ * Public capability probe (`WebSpatialRuntime.supports` re-exports this from React SDK).
+ */
+declare function supports(name: CapabilityKey, tokens?: readonly string[]): boolean;
+declare function supports(name: string, tokens?: readonly string[]): boolean;
 
-    // Will be removed in favor of __WebSpatialData
-    WebSpatailNativeVersion: string
+/**
+ * Minimal semver compare for capability table rows (`major.minor.patch`).
+ * Returns negative if a < b, zero if equal, positive if a > b.
+ */
+declare function compareSemver(a: string, b: string): number;
+declare function parseSemverOrNull(v: string): string | null;
 
-    __webspatialsdk__?: {
-      XR_ENV?: string
-      'natvie-version'?: string
-      'react-sdk-version'?: string
-      'core-sdk-version'?: string
-      physicalMetrics?: PhysicalMetricsValueShape
-    }
+/**
+ * Parse shell token from UA:
+ * - packaged/hybrid runtimes use `WSAppShell/<version>`
+ * - browser-mode runtime on Pico OS uses `PicoWebApp/<version>`
+ *
+ * Keep `WSAppShell` precedence when both appear in one UA.
+ */
+declare function parseShellToken(ua: string): {
+    version: string | null;
+    source: 'wsapp' | 'picoapp' | null;
+};
+/**
+ * Resolve internal runtime snapshot from `navigator.userAgent`.
+ * SSR / no navigator → `{ type: null, shellVersion: null }` (no throw).
+ */
+declare function computeRuntimeFromUserAgent(userAgent: string | undefined): WebSpatialRuntimeSnapshot;
 
-    xrInnerDepth: number
-    xrOuterDepth: number
-  }
+/**
+ * Which native JSB / protocol adapter to load in the browser.
+ * Derived from {@link computeRuntimeFromUserAgent} plus legacy fallbacks
+ * (Pico WebSpatial semver gate; otherwise default visionOS shell).
+ */
+type JsbAdapterPlatformKind = 'puppeteer' | 'picoos' | 'visionos';
+declare function resolveJsbAdapterPlatform(userAgent: string): JsbAdapterPlatformKind;
 
-  interface HTMLElement {
-    xrOffsetBack: number
-    xrClientDepth: number
-  }
-}
+type CapabilityVersionRow = {
+    /** Semver string from `WSAppShell` / `PicoWebApp` (see `review.md` §4). */
+    version: string;
+    /** Top-level keys and `name:subToken` compound keys. */
+    flags: Record<string, boolean>;
+};
+declare const CAPABILITY_TABLE: {
+    visionos: CapabilityVersionRow[];
+    picoos: CapabilityVersionRow[];
+};
 
 declare const isSSREnv: () => boolean;
 
-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 };
+export { Attachment, type AttachmentEntityOptions, type AttachmentEntityUpdateOptions, type BackgroundMaterialType, type BaseplateVisibilityType, BaseplateVisibilityValues, CAPABILITY_TABLE, COMPONENT_KEYS, CSS_KEYS, type CapabilityKey, type CapabilityVersionRow, type CornerRadius, CubeInfo, DOM_DEPTH_KEYS, ELEMENT_DOM_DEPTH_KEYS, GESTURE_KEYS, JS_SCENE_KEYS, type JsbAdapterPlatformKind, type ModelAssetOptions, ModelComponent, type ModelComponentOptions, type ModelLoadingMode, type ModelSource, type PWAManifest, physicalMetrics as PhysicalMetrics, type Point3D, type Quaternion, SUB_TOKENS_BY_NAME, 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, type SpatialSceneProperties, SpatialSceneState, type SpatialSceneType, SpatialSceneValues, SpatialSession, SpatialSphereGeometry, type SpatialSphereGeometryOptions, type SpatialTapEvent, type SpatialTapEventDetail, SpatialTextureResource, type SpatialTextureResourceOptions, SpatialUnlitMaterial, type SpatialUnlitMaterialOptions, Spatialized2DElement, type Spatialized2DElementProperties, SpatializedDynamic3DElement, SpatializedElement, type SpatializedElementProperties, SpatializedElementType, SpatializedStatic3DElement, type SpatializedStatic3DElementProperties, TOP_LEVEL_KEYS, VISIONOS_DEBUG_SHELL_VERSION_PLACEHOLDER, type Vec3, WINDOW_DOM_DEPTH_KEYS, WebSpatialRuntimeError, type WebSpatialRuntimeSnapshot, type WebSpatialRuntimeType, type WorldAlignmentType, WorldAlignmentValues, type WorldScalingType, WorldScalingValues, type XRMainSceneConfig, type XRPrdConfig, type XRSceneResizability, type XRSceneSize, type XRSpatialSceneConfig, type XRSpatialSceneDefaults, type XRSpatialSceneOverrides, compareSemver, computeRuntimeFromUserAgent, createAttachmentEntity, getRuntime, isSSREnv, isValidBaseplateVisibilityType, isValidSceneUnit, isValidSpatialSceneType, isValidWorldAlignmentType, isValidWorldScalingType, parseSemverOrNull, parseShellToken, resetRuntimeCacheForTests, resolveJsbAdapterPlatform, supports };