xrblocks 0.4.0 → 0.5.1

package/build/camera/CameraOptions.d.ts

@@ -1,15 +1,46 @@
 import { DeepPartial, DeepReadonly } from '../utils/Types';
+/**
+ * Parameters for RGB to depth UV mapping given different aspect ratios.
+ * These parameters define the distortion model and affine transformations
+ * required to align the RGB camera feed with the depth map.
+ */
+export interface RgbToDepthParams {
+    scale: number;
+    scaleX: number;
+    scaleY: number;
+    translateU: number;
+    translateV: number;
+    k1: number;
+    k2: number;
+    k3: number;
+    p1: number;
+    p2: number;
+    xc: number;
+    yc: number;
+}
+/**
+ * Default parameters for rgb to depth projection.
+ * For RGB and depth, 4:3 and 1:1, respectively.
+ */
+export declare const DEFAULT_RGB_TO_DEPTH_PARAMS: RgbToDepthParams;
+/**
+ * Configuration options for the device camera.
+ */
 export declare class DeviceCameraOptions {
     enabled: boolean;
     /**
      * Constraints for `getUserMedia`. This will guide the initial camera
-     * selection. *
+     * selection.
      */
     videoConstraints?: MediaTrackConstraints;
     /**
      * Hint for performance optimization on frequent captures.
      */
     willCaptureFrequently: boolean;
+    /**
+     * Parameters for RGB to depth UV mapping given different aspect ratios.
+     */
+    rgbToDepthParams: RgbToDepthParams;
     constructor(options?: DeepReadonly<DeepPartial<DeviceCameraOptions>>);
 }
 export declare const xrDeviceCameraEnvironmentOptions: {
@@ -167,6 +198,20 @@ export declare const xrDeviceCameraEnvironmentOptions: {
         } | undefined;
     } | undefined;
     readonly willCaptureFrequently: boolean;
+    readonly rgbToDepthParams: {
+        readonly scale: number;
+        readonly scaleX: number;
+        readonly scaleY: number;
+        readonly translateU: number;
+        readonly translateV: number;
+        readonly k1: number;
+        readonly k2: number;
+        readonly k3: number;
+        readonly p1: number;
+        readonly p2: number;
+        readonly xc: number;
+        readonly yc: number;
+    };
 };
 export declare const xrDeviceCameraUserOptions: {
     readonly enabled: boolean;
@@ -323,6 +368,20 @@ export declare const xrDeviceCameraUserOptions: {
         } | undefined;
     } | undefined;
     readonly willCaptureFrequently: boolean;
+    readonly rgbToDepthParams: {
+        readonly scale: number;
+        readonly scaleX: number;
+        readonly scaleY: number;
+        readonly translateU: number;
+        readonly translateV: number;
+        readonly k1: number;
+        readonly k2: number;
+        readonly k3: number;
+        readonly p1: number;
+        readonly p2: number;
+        readonly xc: number;
+        readonly yc: number;
+    };
 };
 export declare const xrDeviceCameraEnvironmentContinuousOptions: {
     readonly enabled: boolean;
@@ -479,6 +538,20 @@ export declare const xrDeviceCameraEnvironmentContinuousOptions: {
         } | undefined;
     } | undefined;
     readonly willCaptureFrequently: boolean;
+    readonly rgbToDepthParams: {
+        readonly scale: number;
+        readonly scaleX: number;
+        readonly scaleY: number;
+        readonly translateU: number;
+        readonly translateV: number;
+        readonly k1: number;
+        readonly k2: number;
+        readonly k3: number;
+        readonly p1: number;
+        readonly p2: number;
+        readonly xc: number;
+        readonly yc: number;
+    };
 };
 export declare const xrDeviceCameraUserContinuousOptions: {
     readonly enabled: boolean;
@@ -635,4 +708,18 @@ export declare const xrDeviceCameraUserContinuousOptions: {
         } | undefined;
     } | undefined;
     readonly willCaptureFrequently: boolean;
+    readonly rgbToDepthParams: {
+        readonly scale: number;
+        readonly scaleX: number;
+        readonly scaleY: number;
+        readonly translateU: number;
+        readonly translateV: number;
+        readonly k1: number;
+        readonly k2: number;
+        readonly k3: number;
+        readonly p1: number;
+        readonly p2: number;
+        readonly xc: number;
+        readonly yc: number;
+    };
 };

package/build/camera/CameraUtils.d.ts

@@ -5,24 +5,6 @@ export declare const aspectRatios: {
     depth: number;
     RGB: number;
 };
-/**
- * Parameters for RGB to depth UV mapping (manually calibrated for aspect
- * ratios. For RGB and depth, 4:3 and 1:1, respectively.
- */
-export declare const rgbToDepthParams: {
-    scale: number;
-    scaleX: number;
-    scaleY: number;
-    translateU: number;
-    translateV: number;
-    k1: number;
-    k2: number;
-    k3: number;
-    p1: number;
-    p2: number;
-    xc: number;
-    yc: number;
-};
 /**
  * Maps a UV coordinate from a RGB space to a destination depth space,
  * applying Brown-Conrady distortion and affine transformations based on

package/build/camera/XRDeviceCamera.d.ts

@@ -1,7 +1,7 @@
 import { SimulatorCamera } from '../simulator/SimulatorCamera';
 import { SimulatorMediaDeviceInfo } from '../simulator/SimulatorMediaDeviceInfo';
 import { VideoStream, VideoStreamDetails } from '../video/VideoStream';
-import { DeviceCameraOptions } from './CameraOptions';
+import { DeviceCameraOptions, RgbToDepthParams } from './CameraOptions';
 export type MediaOrSimulatorMediaDeviceInfo = MediaDeviceInfo | SimulatorMediaDeviceInfo;
 type XRDeviceCameraDetails = VideoStreamDetails & {
     width?: number;
@@ -15,6 +15,7 @@ type XRDeviceCameraDetails = VideoStreamDetails & {
  */
 export declare class XRDeviceCamera extends VideoStream<XRDeviceCameraDetails> {
     simulatorCamera?: SimulatorCamera;
+    rgbToDepthParams: RgbToDepthParams;
     protected videoConstraints_: MediaTrackConstraints;
     private isInitializing_;
     private availableDevices_;
@@ -23,7 +24,7 @@ export declare class XRDeviceCamera extends VideoStream<XRDeviceCameraDetails> {
     /**
      * @param options - The configuration options.
      */
-    constructor({ videoConstraints, willCaptureFrequently, }?: Partial<DeviceCameraOptions>);
+    constructor({ videoConstraints, willCaptureFrequently, rgbToDepthParams, }?: Partial<DeviceCameraOptions>);
     /**
      * Retrieves the list of available video input devices.
      * @returns A promise that resolves with an
@@ -43,7 +44,7 @@ export declare class XRDeviceCamera extends VideoStream<XRDeviceCameraDetails> {
     /**
      * Sets the active camera by its device ID. Removes potentially conflicting
      * constraints such as facingMode.
-     * @param deviceId - Device id.
+     * @param deviceId - Device ID
      */
     setDeviceId(deviceId: string): Promise<void>;
     /**

package/build/core/Core.d.ts

@@ -21,6 +21,7 @@ import { XREffects } from './components/XREffects';
 import { XRTransition } from './components/XRTransition';
 import { Options } from './Options';
 import { User } from './User';
+import { PermissionsManager } from './components/PermissionsManager';
 /**
  * Core is the central engine of the XR Blocks framework, acting as a
  * singleton manager for all XR subsystems. Its primary goal is to abstract
@@ -84,6 +85,7 @@ export declare class Core {
     scriptsManager: ScriptsManager;
     renderSceneOverride?: (renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera) => void;
     webXRSessionManager?: WebXRSessionManager;
+    permissionsManager: PermissionsManager;
     /**
      * Core is a singleton manager that manages all XR "blocks".
      * It initializes core components and abstractions like the scene, camera,

package/build/core/Options.d.ts

@@ -108,6 +108,14 @@ export declare class Options {
         showEnterSimulatorButton: boolean;
         alwaysAutostartSimulator: boolean;
     };
+    /**
+     * Which permissions to request before entering the XR session.
+     */
+    permissions: {
+        geolocation: boolean;
+        camera: boolean;
+        microphone: boolean;
+    };
     /**
      * Constructs the Options object by merging default values with provided
      * custom options.
@@ -161,11 +169,6 @@ export declare class Options {
      * @returns The instance for chaining.
      */
     enableHandRays(): this;
-    /**
-     * Enables the Gemini Live feature.
-     * @returns The instance for chaining.
-     */
-    enableGeminiLive(): this;
     /**
      * Enables a standard set of AI features, including Gemini Live.
      * @returns The instance for chaining.

package/build/core/components/PermissionsManager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Interface representing the result of a permission request.
+ */
+export interface PermissionResult {
+    granted: boolean;
+    status: PermissionState | 'unknown' | 'error';
+    error?: string;
+}
+/**
+ * A utility class to manage and request browser permissions for
+ * Location, Camera, and Microphone.
+ */
+export declare class PermissionsManager {
+    /**
+     * Requests permission to access the user's geolocation.
+     * Note: This actually attempts to fetch the position to trigger the prompt.
+     */
+    requestLocationPermission(): Promise<PermissionResult>;
+    /**
+     * Requests permission to access the microphone.
+     * Opens a stream to trigger the prompt, then immediately closes it.
+     */
+    requestMicrophonePermission(): Promise<PermissionResult>;
+    /**
+     * Requests permission to access the camera.
+     * Opens a stream to trigger the prompt, then immediately closes it.
+     */
+    requestCameraPermission(): Promise<PermissionResult>;
+    /**
+     * Requests permission for both camera and microphone simultaneously.
+     */
+    requestAVPermission(): Promise<PermissionResult>;
+    /**
+     * Internal helper to handle getUserMedia requests.
+     * Crucially, this stops the tracks immediately after permission is granted
+     * so the hardware doesn't remain active.
+     */
+    private requestMediaPermission;
+    /**
+     * Requests multiple permissions sequentially.
+     * Returns a single result: granted is true only if ALL requested permissions are granted.
+     */
+    checkAndRequestPermissions({ geolocation, camera, microphone, }: {
+        geolocation?: boolean;
+        camera?: boolean;
+        microphone?: boolean;
+    }): Promise<PermissionResult>;
+    /**
+     * Checks the current status of a permission without triggering a prompt.
+     * Useful for UI state (e.g., disabling buttons if already denied).
+     * * @param permissionName - 'geolocation', 'camera', or 'microphone'
+     */
+    checkPermissionStatus(permissionName: 'geolocation' | 'camera' | 'microphone'): Promise<PermissionState | 'unknown'>;
+}

package/build/core/components/XRButton.d.ts

@@ -1,15 +1,22 @@
+import { PermissionsManager } from './PermissionsManager';
 import { WebXRSessionManager } from './WebXRSessionManager';
 export declare class XRButton {
     private sessionManager;
+    private permissionsManager;
     private startText;
     private endText;
     private invalidText;
     private startSimulatorText;
     startSimulator: () => void;
+    private permissions;
     domElement: HTMLDivElement;
     simulatorButtonElement: HTMLButtonElement;
     xrButtonElement: HTMLButtonElement;
-    constructor(sessionManager: WebXRSessionManager, startText?: string, endText?: string, invalidText?: string, startSimulatorText?: string, showEnterSimulatorButton?: boolean, startSimulator?: () => void);
+    constructor(sessionManager: WebXRSessionManager, permissionsManager: PermissionsManager, startText?: string, endText?: string, invalidText?: string, startSimulatorText?: string, showEnterSimulatorButton?: boolean, startSimulator?: () => void, permissions?: {
+        geolocation: boolean;
+        camera: boolean;
+        microphone: boolean;
+    });
     private createSimulatorButton;
     private createXRButtonElement;
     private onSessionReady;

package/build/depth/DepthOptions.d.ts

@@ -28,6 +28,8 @@ export declare class DepthOptions {
         enabled: boolean;
     };
     useFloat32: boolean;
+    depthTypeRequest: XRDepthType[];
+    matchDepthView: boolean;
     constructor(options?: DeepReadonly<DeepPartial<DepthOptions>>);
 }
 export declare const xrDepthMeshOptions: {
@@ -58,6 +60,8 @@ export declare const xrDepthMeshOptions: {
         readonly enabled: boolean;
     };
     readonly useFloat32: boolean;
+    readonly depthTypeRequest: readonly XRDepthType[];
+    readonly matchDepthView: boolean;
 };
 export declare const xrDepthMeshVisualizationOptions: {
     readonly debugging: boolean;
@@ -87,6 +91,8 @@ export declare const xrDepthMeshVisualizationOptions: {
         readonly enabled: boolean;
     };
     readonly useFloat32: boolean;
+    readonly depthTypeRequest: readonly XRDepthType[];
+    readonly matchDepthView: boolean;
 };
 export declare const xrDepthMeshPhysicsOptions: {
     readonly debugging: boolean;
@@ -116,4 +122,6 @@ export declare const xrDepthMeshPhysicsOptions: {
         readonly enabled: boolean;
     };
     readonly useFloat32: boolean;
+    readonly depthTypeRequest: readonly XRDepthType[];
+    readonly matchDepthView: boolean;
 };

package/build/simulator/Simulator.d.ts

@@ -42,6 +42,8 @@ export declare class Simulator extends Script {
     effects?: XREffects;
     virtualSceneRenderTarget?: THREE.WebGLRenderTarget;
     virtualSceneFullScreenQuad?: FullScreenQuad;
+    backgroundVideoQuad?: FullScreenQuad;
+    videoElement?: HTMLVideoElement;
     camera?: SimulatorCamera;
     options: SimulatorOptions;
     renderer: THREE.WebGLRenderer;

package/build/simulator/SimulatorOptions.d.ts

@@ -23,6 +23,7 @@ export declare class SimulatorOptions {
         z: number;
     };
     scenePath: string;
+    videoPath?: string;
     initialScenePosition: {
         x: number;
         y: number;
@@ -43,7 +44,10 @@ export declare class SimulatorOptions {
         enabled: boolean;
         element: string;
     };
-    geminilive: boolean;
+    geminiLivePanel: {
+        enabled: boolean;
+        element: string;
+    };
     stereo: {
         enabled: boolean;
     };

package/build/ui/components/TextButton.d.ts

@@ -9,6 +9,8 @@ export type TextButtonOptions = TextViewOptions & {
     maxWidth?: number;
     radius?: number;
     boxSize?: number;
+    hoverColor?: string | number;
+    selectedFontColor?: string | number;
 };
 export declare class TextButton extends TextView {
     /** Default description of this view in Three.js DevTools. */

package/build/ui/components/TextView.d.ts

@@ -140,7 +140,7 @@ export declare class TextView extends View<TextViewEventMap> {
      */
     protected _initializeText(): void;
     protected syncTextObj(): void;
-    protected setTextColor(color: number): void;
+    protected setTextColor(color: number | string): void;
     /**
      * Disposes of resources used by the TextView, such as event listeners.
      */

package/build/world/objects/ObjectDetector.d.ts

@@ -61,7 +61,7 @@ export declare class ObjectDetector extends Script {
      * Retrieves a list of currently detected objects.
      *
      * @param label - The semantic label to filter by (e.g., 'chair'). If null,
-     *     all objects are returned.
+     * all objects are returned.
      * @returns An array of `Object` instances.
      */
     get(label?: null): DetectedObject[];
@@ -79,10 +79,15 @@ export declare class ObjectDetector extends Script {
      * Draws the detected bounding boxes on the input image and triggers a
      * download for debugging.
      * @param base64Image - The base64 encoded input image.
-     * @param detections - The array of detected objects from the
-     * AI response.
+     * @param detections - The array of detected objects from the AI response.
      */
     private _visualizeBoundingBoxesOnImage;
+    /**
+     * Generates a visual representation of the depth map, normalized to 0-1 range,
+     * and triggers a download for debugging.
+     * @param depthArray - The raw depth data array.
+     */
+    private _visualizeDepthMap;
     /**
      * Creates a simple debug visualization for an object based on its position
      * (center of its 2D detection bounding box).