@webspatial/core-sdk 1.2.1 → 1.4.0

package/dist/index.d.ts

@@ -47,8 +47,6 @@ declare abstract class SpatialMaterial extends SpatialObject {
 }
 
 declare enum SpatialWebMsgType {
-    cubeInfo = "cubeInfo",
-    transform = "transform",
     modelloaded = "modelloaded",
     modelloadfailed = "modelloadfailed",
     spatialtap = "spatialtap",
@@ -64,25 +62,6 @@ declare enum SpatialWebMsgType {
 interface ObjectDestroyMsg {
     type: SpatialWebMsgType.objectdestroy;
 }
-interface CubeInfoMsg {
-    type: SpatialWebMsgType.cubeInfo;
-    origin: Vec3;
-    size: Size3D;
-}
-interface CubeInfoMsg {
-    type: SpatialWebMsgType.cubeInfo;
-    origin: Vec3;
-    size: Size3D;
-}
-interface TransformMsg {
-    type: SpatialWebMsgType.transform;
-    detail: {
-        column0: [number, number, number];
-        column1: [number, number, number];
-        column2: [number, number, number];
-        column3: [number, number, number];
-    };
-}
 interface SpatialTapMsg {
     type: SpatialWebMsgType.spatialtap;
     detail: SpatialTapEventDetail;
@@ -144,7 +123,7 @@ declare abstract class SpatializedElement extends SpatialObject {
      * Gets the current cube information for this element.
      * @returns The current CubeInfo or undefined if not set
      */
-    get cubeInfo(): CubeInfo$1 | undefined;
+    get cubeInfo(): CubeInfo | undefined;
     /**
      * The current transformation matrix of this element.
      */
@@ -169,7 +148,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: CubeInfoMsg | TransformMsg | SpatialTapMsg | SpatialDragStartMsg | SpatialDragMsg | SpatialDragEndMsg | SpatialRotateMsg | SpatialRotateEndMsg | ObjectDestroyMsg): void;
+    protected onReceiveEvent(data: SpatialTapMsg | SpatialDragStartMsg | SpatialDragMsg | SpatialDragEndMsg | SpatialRotateMsg | SpatialRotateEndMsg | ObjectDestroyMsg): void;
     private _onSpatialTap?;
     set onSpatialTap(value: (event: SpatialTapEvent) => void | undefined);
     private _onSpatialDragStart?;
@@ -195,8 +174,12 @@ declare abstract class SpatializedElement extends SpatialObject {
 
 declare class SpatializedDynamic3DElement extends SpatializedElement {
     children: SpatialEntityOrReality[];
+    events: Record<string, (data: any) => void>;
     constructor(id: string);
     addEntity(entity: SpatialEntity): Promise<CommandResult>;
+    addEvent(type: SpatialEntityEventType, callback: (data: any) => void): void;
+    removeEvent(eventName: SpatialEntityEventType): void;
+    dispatchEvent(evt: CustomEvent): void;
     updateProperties(properties: Partial<SpatializedElementProperties>): Promise<CommandResult>;
 }
 
@@ -264,6 +247,11 @@ interface SpatializedElementProperties {
     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;
@@ -291,6 +279,7 @@ interface SpatialSceneCreationOptions$1 {
     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;
@@ -313,7 +302,6 @@ interface SpatialEntityProperties {
     rotation: Vec3;
     scale: Vec3;
 }
-type SpatialEntityEventType = 'spatialtap';
 type SpatialGeometryType = 'BoxGeometry' | 'PlaneGeometry' | 'SphereGeometry' | 'CylinderGeometry' | 'ConeGeometry';
 interface SpatialBoxGeometryOptions {
     width?: number;
@@ -383,7 +371,7 @@ interface Size {
 interface Size3D extends Size {
     depth: number;
 }
-declare class CubeInfo$1 {
+declare class CubeInfo {
     size: Size3D;
     origin: Vec3;
     constructor(size: Size3D, origin: Vec3);
@@ -402,10 +390,12 @@ declare class CubeInfo$1 {
 }
 interface SpatialTapEventDetail {
     location3D: Point3D;
+    globalLocation3D?: Point3D;
 }
 type SpatialTapEvent = CustomEvent<SpatialTapEventDetail>;
 interface SpatialDragStartEventDetail {
     startLocation3D: Point3D;
+    globalLocation3D?: Point3D;
 }
 interface SpatialDragEventDetail {
     translation3D: Vec3;
@@ -430,6 +420,22 @@ 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;
+    };
+}
 
 declare class SpatialComponent extends SpatialObject {
     constructor(id: string);
@@ -444,6 +450,9 @@ declare class SpatialEntity extends SpatialObject {
     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>;
     setPosition(position: Vec3): Promise<CommandResult>;
@@ -523,6 +532,16 @@ declare class SpatialModelAsset extends SpatialObject {
     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>;
+
 declare function initScene(name: string, callback: (pre: SpatialSceneCreationOptions$1) => SpatialSceneCreationOptions$1, options?: {
     type: SpatialSceneType$1;
 }): void;
@@ -550,6 +569,7 @@ declare class SpatialScene extends SpatialObject {
      * @returns The singleton SpatialScene instance
      */
     static getInstance(): SpatialScene;
+    convertCoordinate(position: Vec3, fromId: string, toId: string): Promise<Vec3>;
     /**
      * Updates the properties of the spatial scene.
      * This can include background settings, lighting, and other scene-wide properties.
@@ -614,6 +634,13 @@ declare class Spatialized2DElement extends SpatializedElement {
  * and provides events for load success and failure.
  */
 declare class SpatializedStatic3DElement extends SpatializedElement {
+    /**
+     * Creates a new spatialized static 3D element with the specified ID and URL.
+     * Registers the element to receive spatial events.
+     * @param id Unique identifier for this element
+     * @param modelURL URL of the 3D model
+     */
+    constructor(id: string, modelURL: string);
     /**
      * Promise resolver for the ready state.
      * Used to resolve the ready promise when the model is loaded.
@@ -694,7 +721,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): Promise<SpatializedStatic3DElement>;
     /**
      * Initializes the spatial scene with custom configuration.
      * This is a reference to the initScene function from scene-polyfill.
@@ -771,6 +798,13 @@ declare class SpatialSession {
      * @returns Promise resolving to a new SpatialModelEntity instance
      */
     createSpatialModelEntity(options: SpatialModelEntityCreationOptions, userData?: SpatialEntityUserData): Promise<SpatialModelEntity>;
+    /**
+     * Creates an attachment entity that renders 2D HTML content as a child
+     * of a 3D entity in the scene graph.
+     * @param options Configuration options including parent entity ID, position, and size
+     * @returns Promise resolving to a new Attachment instance
+     */
+    createAttachmentEntity(options: AttachmentEntityOptions): Promise<Attachment>;
 }
 
 /**
@@ -778,6 +812,7 @@ 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.
@@ -791,6 +826,7 @@ 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.
@@ -811,6 +847,53 @@ declare class Spatial {
     getClientVersion(): string;
 }
 
+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 };
+}
+
 declare global {
   declare const __WEBSPATIAL_CORE_SDK_VERSION__: string
 
@@ -841,19 +924,19 @@ declare global {
       'natvie-version'?: string
       'react-sdk-version'?: string
       'core-sdk-version'?: string
+      physicalMetrics?: PhysicalMetricsValueShape
     }
 
-    innerDepth: number
-    outerDepth: number
+    xrInnerDepth: number
+    xrOuterDepth: number
   }
 
   interface HTMLElement {
-    offsetBack: number
-    clientDepth: number
-    getBoundingClientCube: () => CubeInfo | undefined
+    xrOffsetBack: number
+    xrClientDepth: number
   }
 }
 
 declare const isSSREnv: () => boolean;
 
-export { type BackgroundMaterialType, type BaseplateVisibilityType, BaseplateVisibilityValues, type CornerRadius, CubeInfo$1 as CubeInfo, type ModelAssetOptions, ModelComponent, type ModelComponentOptions, 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, 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, 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 };