@webspatial/core-sdk 0.1.6 → 0.1.7

package/dist/index.d.ts

@@ -1,2 +1,712 @@
-export * from './core/index';
-//# sourceMappingURL=index.d.ts.map
+type WindowStyle = 'Plain' | 'Volumetric';
+interface WindowContainerOptions {
+    defaultSize?: {
+        width: number;
+        height: number;
+    };
+    resizability?: 'automatic' | 'contentSize' | 'contentMinSize';
+}
+type LoadingMethodKind = 'show' | 'hide';
+interface sceneDataShape {
+    method?: 'createRoot' | 'showRoot';
+    sceneConfig?: WindowContainerOptions;
+    url?: string;
+    window: Window;
+}
+interface sceneDataJSBShape {
+    method?: 'createRoot' | 'showRoot';
+    sceneConfig?: WindowContainerOptions;
+    url?: string;
+    windowID?: string;
+    windowContainerID?: string;
+}
+
+declare class WindowContainer {
+    id: string;
+}
+declare class WebSpatialResource {
+    id: string;
+    windowContainerId: string;
+    data: any;
+    receiveEvent(): void;
+}
+
+/**
+ * @hidden
+ * Parent class of spatial objects, should not be used directly
+ */
+declare class SpatialObject {
+    /** @hidden */
+    _resource: WebSpatialResource;
+    /** @hidden */
+    constructor(
+    /** @hidden */
+    _resource: WebSpatialResource);
+    /**
+     * Marks resource to be released (it should no longer be used)
+     */
+    destroy(): Promise<void>;
+    name: string;
+    protected onDestroy(): Promise<void>;
+}
+
+declare class Vec3 {
+    x: number;
+    y: number;
+    z: number;
+    constructor(x?: number, y?: number, z?: number);
+}
+declare class Vec4 {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+    constructor(x?: number, y?: number, z?: number, w?: number);
+}
+/**
+ * Transform containing position, orientation and scale
+ */
+declare class SpatialTransform {
+    position: Vec3;
+    /** Quaternion value for x,y,z,w */
+    orientation: Vec4;
+    scale: Vec3;
+}
+
+/**
+ * Anchored window managed by the OS
+ */
+declare class SpatialWindowContainer {
+    /** @hidden */
+    _wg: WindowContainer;
+    /** @hidden */
+    constructor(
+    /** @hidden */
+    _wg: WindowContainer);
+    /**
+     * @hidden
+     * Sets sets the open configuration for opening new window containers
+     * @param options style options
+     */
+    _setOpenSettings(options: {
+        resolution: {
+            width: number;
+            height: number;
+        };
+    }): Promise<void>;
+    /**
+     * Retrieves the root entity of the windowContainer
+     * @returns the root entity of the windowContainer if one exists
+     */
+    getRootEntity(): Promise<SpatialEntity | null>;
+    setRootEntity(entity: SpatialEntity): Promise<void>;
+}
+
+/**
+ * Entity used to describe an object that can be added to the scene
+ */
+declare class SpatialEntity extends SpatialObject {
+    /**
+     * Transform corresponding to the entity
+     * note: updateTransform must be called for transform to be synced to rendering
+     */
+    transform: SpatialTransform;
+    /** @hidden */
+    private _destroyed;
+    /** @hidden */
+    private get _entity();
+    /**
+     * Syncs the transform with the renderer, must be called to observe updates
+     */
+    updateTransform(): Promise<void>;
+    /**
+     * Syncs the zIndex with the renderer
+     */
+    updateZIndex(zIndex: number): Promise<void>;
+    private components;
+    /**
+     * Attaches a component to the entity to be displayed
+     * [TODO] review pass by value vs ref and ownership model for this
+     */
+    setComponent(component: SpatialComponent): Promise<void>;
+    /**
+     * Removes a component from the entity
+     */
+    removeComponent<T extends SpatialComponent>(type: new (...args: any[]) => T): Promise<void>;
+    /**
+     * Gets a component from the entity
+     */
+    getComponent<T extends SpatialComponent>(type: new (...args: any[]) => T): T | undefined;
+    /**
+     * @hidden
+     * Sets the window container that this entity should be rendered by (this does not effect resource ownership)
+     * @param wg the window container that should render this entity
+     */
+    _setParentWindowContainer(wg: SpatialWindowContainer): Promise<void>;
+    /**
+     * Sets a parent entity, if that entity or its parents are attached to a window container, this entity will be displayed
+     * @param e parent entity or null to remove current parent
+     */
+    setParent(e: SpatialEntity | null): Promise<void>;
+    /**
+     * Sets the coordinate space of this entity (Default: App)
+     * "App" = game engine style coordinates in meters
+     * "Dom" = Windowing coordinates in dom units (eg. 0,0,0 is top left of window)
+     * "Root" = Coordinate space is ignored and content is displayed and updated as window container's root object, window containers can only have one root entity
+     * [TODO] review this api
+     * @param space coordinate space mode
+     */
+    setCoordinateSpace(space: 'App' | 'Dom' | 'Root'): Promise<void>;
+    /**
+     * Query the 3d boudning box of the entity
+     * @returns The bounding box of the entity
+     */
+    getBoundingBox(): Promise<{
+        center: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        extents: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }>;
+    /**
+     * Sets if the entity should be visible (default: True)
+     * @param visible
+     */
+    setVisible(visible: boolean): Promise<void>;
+    /**
+     * Removes a reference to the entity by the renderer and this object should no longer be used. [TODO] Attached components will not be destroyed
+     */
+    destroy(): Promise<void>;
+    /**
+     * Check if destroy has been called
+     */
+    isDestroyed(): boolean;
+    /** @hidden */
+    _setName(name: string): Promise<unknown>;
+}
+
+/** @hidden */
+declare class SpatialComponent extends SpatialObject {
+    /**
+     * Gets the entity this component is attached to
+     * @returns entity or null
+     */
+    getEntity(): Promise<SpatialEntity | null>;
+}
+
+/**
+ * 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;
+};
+type StyleParam = {
+    material?: {
+        type: BackgroundMaterialType;
+    };
+    cornerRadius?: number | CornerRadius;
+};
+/**
+ * Used to position an web window in 3D space
+ */
+declare class SpatialWindowComponent extends SpatialComponent {
+    /**
+     * Loads a url page in the window
+     * @param url url to load
+     */
+    loadURL(url: string): Promise<void>;
+    setFromWindow(window: any): Promise<void>;
+    /**
+     * Sets the resolution of the window, the resulting dimensions when rendered will be equal to 1/1360 units
+     * eg. if the resolution is set to 1360x1360 it will be a 1x1 plane
+     * See 1360 in spatialViewUI.swift for how this ratio works
+     * @param width width in pixels
+     * @param height height in pixels
+     */
+    setResolution(width: number, height: number): Promise<void>;
+    /**
+     * [Experimental] Sets the anchor which the entity this is attached to will rotate around
+     * @param rotationAnchor
+     */
+    setRotationAnchor(rotationAnchor: Vec3): Promise<void>;
+    /**
+     * [Experimental] Sets the opacity of the window after apply material
+     * @param opacity
+     */
+    setOpacity(opacity: number): Promise<void>;
+    /**
+     * Sets the style that should be applied to the window
+     * @param options style options
+     */
+    setStyle(styleParam: StyleParam): Promise<void>;
+    /**
+     * Modifies the amount the spatial window can be scrolled
+     * Should only be used internally
+     * See https://developer.apple.com/documentation/uikit/1624475-uiedgeinsetsmake?language=objc
+     * @param insets margin to modify scroll distances by
+     */
+    setScrollEdgeInsets(insets: {
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    }): Promise<void>;
+    /**
+     * Enable/Disable scrolling in the window (defaults to enabled), if disabled, scrolling will be applied to the root page
+     * @param enabled value to set
+     */
+    setScrollEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Defaults to false. If set to true, scrolling the parent page will also scroll this window with it like other dom elements
+     * @param scrollWithParent value to set
+     */
+    setScrollWithParent(scrollWithParent: boolean): Promise<void>;
+}
+
+/**
+ * @description
+ * Represents a spatial component that handles events related to spatial interactions.
+ * This class extends `SpatialComponent` and provides additional functionality for managing
+ * event-driven spatial behaviors.
+ *
+ * @hidden
+ * This class is intended for internal use and should not be exposed in the public API.
+ */
+declare abstract class EventSpatialComponent extends SpatialComponent {
+    constructor(_resource: WebSpatialResource);
+    /**
+     * @description
+     * Abstract method to be implemented by subclasses. Called when a spatial event is received.
+     * @param data The data associated with the received event.
+     */
+    protected abstract onRecvEvent(data: any): void;
+    protected onDestroy(): Promise<void>;
+}
+
+/**
+ * Translate event, matching similar behavior to https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/drag_event
+ */
+type TranslateEvent = {
+    eventType: 'dragstart' | 'dragend' | 'drag';
+    translate?: Vec3;
+};
+/**
+ * Used to handle input events on an entity
+ */
+declare class SpatialInputComponent extends EventSpatialComponent {
+    protected onRecvEvent(data: any): void;
+    /**
+     * Callback fired when a translate event occurs
+     * @param data translate event data
+     */
+    onTranslate(data: TranslateEvent): void;
+}
+
+/**
+ * Mesh asset containing geometry
+ */
+declare class SpatialMeshResource extends SpatialObject {
+}
+
+/**
+ * PBR material which can be set on a SpatialModelComponent
+ */
+declare class SpatialPhysicallyBasedMaterialResource extends SpatialObject {
+    /**
+     * Base color of the material containing rgba between 0 and 1
+     */
+    baseColor: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /**
+     * PBR metalic value between 0 and 1
+     */
+    metallic: {
+        value: number;
+    };
+    /**
+     * PBR roughness value between 0 and 1
+     */
+    roughness: {
+        value: number;
+    };
+    _modelComponentAttachedTo: {
+        [key: string]: SpatialModelComponent;
+    };
+    _addToComponent(c: SpatialModelComponent): void;
+    /**
+     * Syncs state of color, metallic, roupghness to the renderer
+     */
+    update(): Promise<void>;
+}
+
+/**
+ * Used to position a model in 3D space, made up of a mesh and materials to be applied to the mesh
+ */
+declare class SpatialModelComponent extends SpatialComponent {
+    private cachedMaterials;
+    /**
+     * Sets the mesh to be displayed by the component
+     * @param mesh mesh to set
+     */
+    setMesh(mesh: SpatialMeshResource): Promise<void>;
+    /**
+     * Sets the materials that should be applied to the mesh
+     * @param materials array of materials to set
+     */
+    setMaterials(materials: Array<SpatialPhysicallyBasedMaterialResource>): Promise<void>;
+    /** @hidden */
+    _syncMaterials(): Promise<void>;
+}
+
+/**
+ * Represenets a volume that can be added to the webpage
+ * Child entities will be added within this volume's space
+ * Defaults to having 1x1x1 meter dimensions
+ * Resolution defaults to 100x100 pixels
+ * Only will be displayed on entities in "ROOT" or "DOM" space
+ * If the resolution of the spatial view is not a square, the volume will be larger based on the ratio with the shortest side being 1 meter.
+ * (eg. 200x100 = 2m x 1m x 1m volume)
+ */
+declare class SpatialViewComponent extends SpatialComponent {
+    /**
+     * Sets the resolution of the spatial view in dom pixels
+     */
+    setResolution(width: number, height: number): Promise<void>;
+    /**
+     * Sets if content of the spatialView should be within a portal
+     * If true, volume will be behind the page, if false, it will be in front of the page
+     */
+    setIsPortal(isPortal: Boolean): Promise<void>;
+}
+
+/**
+ * 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;
+};
+/**
+ * Used to position a model3d in 3D space
+ */
+declare class SpatialModel3DComponent extends EventSpatialComponent {
+    protected onRecvEvent(data: any): void;
+    /**
+     * Sets the resolution of the spatial view in dom pixels
+     */
+    setResolution(width: number, height: number): Promise<void>;
+    setRotationAnchor(rotationAnchor: Vec3): Promise<void>;
+    /**
+     * Sets the opacity of the model
+     * @param opacity
+     */
+    setOpacity(opacity: number): Promise<void>;
+    /**
+     * Sets how the model fill the rect
+     * @param contentMode
+     */
+    setContentMode(contentMode: 'fill' | 'fit'): Promise<void>;
+    /**
+     * Constrains this model dimensions to the specified aspect ratio.
+     * with a value of 0, the model will use the original aspect ratio.
+     *
+     * @param aspectRatio number
+     */
+    setAspectRatio(aspectRatio: number): Promise<void>;
+    /**
+     * Defaults to false. If set to true, scrolling the parent page will also scroll this window with it like other dom elements
+     * @param scrollWithParent value to set
+     */
+    setScrollWithParent(scrollWithParent: boolean): Promise<void>;
+    /**
+     * Sets whether the model appear in original size or fit the rect
+     * @param resizable
+     */
+    setResizable(resizable: boolean): Promise<void>;
+    /**
+     * Callback fired when model load success
+     */
+    onSuccess?: () => void;
+    /**
+     * Callback fired when model load failure
+     * @param errorReason
+     */
+    onFailure?: (errorReason: string) => void;
+    /**
+     * Callback fired when model was dragged at the beginning
+     * @param dragEvent
+     */
+    private _onDragStart?;
+    set onDragStart(callback: ((dragEvent: SpatialModelDragEvent) => void) | undefined);
+    /**
+     * Callback fired when model was dragged
+     * @param dragEvent
+     */
+    private _onDrag?;
+    set onDrag(callback: ((dragEvent: SpatialModelDragEvent) => void) | undefined);
+    /**
+     * Callback fired when model was dragged at the ending
+     * @param dragEvent
+     */
+    private _onDragEnd?;
+    set onDragEnd(callback: ((dragEvent: SpatialModelDragEvent) => void) | undefined);
+    private get enableDragEvent();
+    /**
+     * Callback fired when model was tapped
+     */
+    private _onTap?;
+    set onTap(callback: (() => void) | undefined);
+    /** Callback fired when model was double tapped */
+    private _onDoubleTap?;
+    set onDoubleTap(callback: (() => void) | undefined);
+    /** Callback fired when model was long pressed */
+    private _onLongPress?;
+    set onLongPress(callback: (() => void) | undefined);
+}
+
+type CreateResourceOptions = {
+    windowContainer?: SpatialWindowContainer | null;
+    windowComponent?: SpatialWindowComponent | null;
+};
+/**
+ * Animation callback with timestamp
+ */
+type animCallback = (time: DOMHighResTimeStamp) => Promise<any>;
+/**
+ * Session use to establish a connection to the spatial renderer of the system. All resources must be created by the session
+ */
+declare class SpatialSession {
+    /** @hidden */
+    _engineUpdateListeners: animCallback[];
+    /** @hidden */
+    _frameLoopStarted: boolean;
+    /**
+     * Add event listener callback to be called each frame
+     * @param callback callback to be called each update
+     */
+    addOnEngineUpdateEventListener(callback: animCallback): void;
+    /**
+     * Creates a Entity
+     * @returns Entity
+     */
+    createEntity(options?: CreateResourceOptions): Promise<SpatialEntity>;
+    /**
+     * Creates a WindowComponent
+     * [TODO] should creation of components be moved to entity? and these made private?
+     * @returns WindowComponent
+     */
+    createWindowComponent(options?: CreateResourceOptions): Promise<SpatialWindowComponent>;
+    /**
+     * Creates a ViewComponent used to display 3D content within the entity
+     * @returns SpatialViewComponent
+     */
+    createViewComponent(options?: CreateResourceOptions): Promise<SpatialViewComponent>;
+    /**
+     * Creates a ModelComponent used to display geometry + material of a 3D model
+     * @returns ModelComponent
+     */
+    createModelComponent(options?: {
+        url: string;
+    } & CreateResourceOptions): Promise<SpatialModelComponent>;
+    /**
+     * Creates a Model3DComponent
+     * @returns Model3DComponent
+     */
+    createModel3DComponent(options?: {
+        url: string;
+    } & CreateResourceOptions): Promise<SpatialModel3DComponent>;
+    /**
+     * Creates a InputComponent
+     * [Experimental] Creates a InputComponent used to handle click and drag events of the entity containing a model
+     * @returns InputComponent
+     */
+    createInputComponent(options?: CreateResourceOptions): Promise<SpatialInputComponent>;
+    /**
+     * Creates a MeshResource containing geometry data
+     * @returns MeshResource
+     */
+    createMeshResource(options?: {
+        shape?: string;
+    } & CreateResourceOptions): Promise<SpatialMeshResource>;
+    /**
+     * Creates a PhysicallyBasedMaterial containing PBR material data
+     * @returns PhysicallyBasedMaterial
+     */
+    createPhysicallyBasedMaterialResource(options?: {} & CreateResourceOptions): Promise<SpatialPhysicallyBasedMaterialResource>;
+    /**
+     * Creates a WindowContainer
+     * @returns SpatialWindowContainer
+     * */
+    createWindowContainer(options?: {
+        style: WindowStyle;
+    } & CreateResourceOptions): Promise<SpatialWindowContainer>;
+    /**
+     * Creates a Scene to display content within an anchored area managed by the OS
+     * @hidden
+     * @param {WindowStyle} [style='Plain'] - The style of the Scene container to be created with. Defaults to 'Plain'.
+     * @param {Object} [cfg={}] - Configuration object for the Scene.
+     * @returns Boolean
+     */
+    _createScene(style: WindowStyle | undefined, cfg: {
+        sceneData: sceneDataShape;
+    }): Promise<boolean>;
+    /**
+     * Retrieves the window for this page
+     * @returns the window component corresponding to the js running on this page
+     * [TODO] discuss implications of this not being async
+     */
+    getCurrentWindowComponent(): SpatialWindowComponent;
+    /**
+     * Retrieves the parent window for this page or null if this is the root page
+     * @returns the window component or null
+     */
+    getParentWindowComponent(): Promise<SpatialWindowComponent | null>;
+    /**
+     * Logs a message to the native apps console
+     * @param msg mesage to log
+     */
+    log(...msg: any[]): Promise<void>;
+    /**
+     * @hidden
+     * Debugging only, used to ping the native renderer
+     */
+    _ping(msg: string): Promise<unknown>;
+    /**
+     * @hidden
+     * Debugging to get internal state from native code
+     * @returns data as a js object
+     */
+    _getStats(): Promise<{
+        objects: any;
+        refObjects: any;
+    }>;
+    /**
+     * @hidden
+     */
+    _inspect(spatialObjectId?: string): Promise<any>;
+    /**
+     * @hidden
+     */
+    _inspectRootWindowContainer(): Promise<any>;
+    /** Opens the immersive space */
+    openImmersiveSpace(): Promise<void>;
+    /** Closes the immersive space */
+    dismissImmersiveSpace(): Promise<void>;
+    private static _immersiveWindowContainer;
+    /**
+     * Retreives the window container corresponding to the Immersive space
+     * @returns the immersive window container
+     */
+    getImmersiveWindowContainer(): Promise<SpatialWindowContainer>;
+    private static _currentWindowContainer;
+    /**
+     * Gets the current window container for the window
+     * [TODO] discuss what happens if it doesnt yet have a window container
+     * @returns the current window container for the window
+     */
+    getCurrentWindowContainer(): SpatialWindowContainer;
+    /**
+     * Start a transaction that queues up commands to submit them all at once to reduce ipc overhead
+     * @param fn function to be run, within this function, promises will not resolve
+     * @returns promise for the entire transaction completion
+     */
+    transaction(fn: Function): Promise<unknown>;
+    /**
+     * Creates a window context object that is compatable with SpatialWindowComponent's setFromWindow API
+     * @returns window context
+     */
+    createWindowContext(): Promise<Window | null>;
+    /** @hidden */
+    _getEntity(id: string): Promise<SpatialEntity>;
+    /** @hidden */
+    setLoading(method: LoadingMethodKind, style?: string): Promise<unknown>;
+}
+
+/**
+ * Base object designed to be placed on navigator.spatial to mirror navigator.xr for webxr
+ */
+declare class Spatial {
+    /**
+     * Requests a session object from the browser
+     * @returns The session or null if not availible in the current browser
+     * [TODO] discuss implications of this not being async
+     */
+    requestSession(): SpatialSession | null;
+    /**
+     * @returns true if web spatial is supported by this webpage
+     */
+    isSupported(): any;
+    /**
+     * Gets the native version, format is "x.x.x"
+     * @returns native version string
+     */
+    getNativeVersion(): any;
+    /**
+     * Gets the client version, format is "x.x.x"
+     * @returns client version string
+     */
+    getClientVersion(): string;
+}
+
+/**
+ * Helper class used to quickly add spatial content to standard web pages
+ * [Experimental] expect APIs to potentially change in future versions
+ */
+declare class SpatialHelper {
+    session: SpatialSession;
+    private static _instance;
+    static get instance(): SpatialHelper | null;
+    constructor(session: SpatialSession);
+    shape: {
+        createShapeEntity: (shape?: string) => Promise<SpatialEntity>;
+        createModelEntity: (url: string) => Promise<SpatialEntity>;
+        wrapInBoundingBoxEntity: (entityToWrap: SpatialEntity) => Promise<SpatialEntity>;
+    };
+    navigation: {
+        openPanel: (url: string, options?: {
+            resolution: {
+                width: number;
+                height: number;
+            };
+        }) => Promise<void>;
+        openVolume: (url: string, options?: {
+            resolution: {
+                width: number;
+                height: number;
+            };
+        }) => Promise<void>;
+    };
+    dom: {
+        attachSpatialView: (divOnPage: HTMLElement) => Promise<{
+            entity: SpatialEntity;
+        }>;
+    };
+    setBackgroundStyle: (style: StyleParam, backgroundColor?: string) => Promise<void>;
+}
+
+export { type BackgroundMaterialType, type CornerRadius, type LoadingMethodKind, Spatial, SpatialComponent, SpatialEntity, SpatialHelper, SpatialInputComponent, SpatialMeshResource, SpatialModel3DComponent, SpatialModelComponent, type SpatialModelDragEvent, SpatialPhysicallyBasedMaterialResource, SpatialSession, SpatialTransform, SpatialViewComponent, SpatialWindowComponent, SpatialWindowContainer, type StyleParam, Vec3, Vec4, type WindowContainerOptions, type WindowStyle, type sceneDataJSBShape, type sceneDataShape };