@reactvision/react-viro 2.55.0 → 2.57.0

package/components/ViroObjectDetector.tsx

@@ -0,0 +1,222 @@
+/**
+ * Copyright (c) 2026-present, ReactVision, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import * as React from "react";
+import {
+  NativeSyntheticEvent,
+  requireNativeComponent,
+  ViewProps,
+} from "react-native";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ViroDetectorMode = "prompt-free" | "text" | "visual";
+
+export type ViroDetectionBoundingBox = {
+  /** Left edge, normalized [0, 1] */
+  x: number;
+  /** Top edge, normalized [0, 1] */
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type ViroDetectedObject = {
+  label: string;
+  confidence: number;
+  boundingBox: ViroDetectionBoundingBox;
+  /** 3D world position (metres), from raycasting the bbox centre. Present when `projectToWorld` is true (iOS only). */
+  worldPosition?: { x: number; y: number; z: number };
+  /**
+   * Bounding box in density-independent points (dp), aligned to the on-screen AR
+   * camera preview. Use directly as { left, top, width, height } in an
+   * absolute-positioned View. Present on iOS and Android.
+   */
+  screenBoundingBox?: { x: number; y: number; width: number; height: number };
+};
+
+export type ViroDetectionEvent = {
+  detections: ViroDetectedObject[];
+};
+
+export type ViroDetectorReadyEvent = Record<string, never>;
+
+export type ViroDetectorErrorEvent = {
+  error: string;
+};
+
+type Props = ViewProps & {
+  /**
+   * The YOLOE model to run. Either a bundled model **name** (resolved natively as
+   * `<name>.onnx` in the app bundle / Android assets), or an absolute `/`-path or
+   * `file://` URL to an `.onnx` file. Defaults to "yoloe-26s".
+   */
+  model?: string;
+
+  /**
+   * Inference mode:
+   * - "prompt-free": YOLOE LRPC — detects 4,585 categories with no extra prompt.
+   * - "text":        YOLOE RepRTA — detect only the classes listed in `categories`.
+   * - "visual":      YOLOE SAVPE — detect objects similar to a reference crop
+   *                  (reference image API to be added in a future release).
+   * Defaults to "prompt-free".
+   */
+  mode?: ViroDetectorMode;
+
+  /**
+   * Text categories for "text" mode, e.g. ["chair", "person", "laptop"].
+   * Ignored in other modes.
+   */
+  categories?: string[];
+
+  /**
+   * Minimum confidence score [0, 1] for a detection to be reported.
+   * Defaults to 0.4.
+   */
+  confidenceThreshold?: number;
+
+  /**
+   * IoU threshold used by NMS post-processing.
+   * Defaults to 0.45.
+   */
+  iouThreshold?: number;
+
+  /**
+   * Maximum number of inference calls per second. The camera runs at the
+   * device's native frame rate; this throttle prevents the inference thread
+   * from saturating the CPU/NPU while the AR renderer runs in parallel.
+   * Defaults to 15.
+   */
+  maxFPS?: number;
+
+  /**
+   * Maximum number of detections reported per frame, kept as the top-N by
+   * confidence (after NMS). Lower this to reduce clutter, raise it to surface
+   * more objects.
+   * Defaults to 20.
+   */
+  maxDetections?: number;
+
+  /**
+   * When true, each detection includes a `worldPosition` {x, y, z} obtained by
+   * raycasting the bbox centre against the AR scene. iOS only (Android emits
+   * `screenBoundingBox` but not yet `worldPosition`).
+   * Defaults to true.
+   */
+  projectToWorld?: boolean;
+
+  /**
+   * Called every time the detector produces a new set of detections.
+   * May be called with an empty array if nothing is detected in a frame.
+   */
+  onDetection?: (event: ViroDetectionEvent) => void;
+
+  /**
+   * Called once the model has been loaded and the camera pipeline is running.
+   */
+  onReady?: (event: ViroDetectorReadyEvent) => void;
+
+  /**
+   * Called if the model fails to load or the camera cannot be opened.
+   */
+  onError?: (event: ViroDetectorErrorEvent) => void;
+};
+
+// ---------------------------------------------------------------------------
+// Internal native event types
+// ---------------------------------------------------------------------------
+
+type NativeDetectionEvent = NativeSyntheticEvent<ViroDetectionEvent>;
+type NativeReadyEvent = NativeSyntheticEvent<ViroDetectorReadyEvent>;
+type NativeErrorEvent = NativeSyntheticEvent<ViroDetectorErrorEvent>;
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+const VRTObjectDetectorView = requireNativeComponent<any>("VRTObjectDetectorView");
+
+/**
+ * ViroObjectDetector — on-device open-vocabulary object detection powered by YOLOE.
+ *
+ * Runs **only in AR**: it shares the camera feed of the enclosing
+ * `ViroARSceneNavigator` (no separate camera session, no preview of its own) and
+ * fires `onDetection` with labels, normalized bounding boxes, and an on-screen
+ * `screenBoundingBox` (dp) at up to `maxFPS`. Mount it as a child or sibling of a
+ * `ViroARSceneNavigator`; it renders nothing itself, so give it `width: 0, height: 0`.
+ *
+ * @example
+ * ```tsx
+ * <ViroARSceneNavigator initialScene={{ scene: MyScene }} />
+ * <ViroObjectDetector
+ *   style={{ position: "absolute", width: 0, height: 0 }}
+ *   mode="prompt-free"
+ *   confidenceThreshold={0.4}
+ *   maxFPS={15}
+ *   onDetection={({ detections }) => {
+ *     detections.forEach(d => console.log(d.label, d.confidence, d.screenBoundingBox));
+ *   }}
+ * />
+ * ```
+ */
+export const ViroObjectDetector: React.FC<Props> = ({
+  model = "yoloe-26s",
+  mode = "prompt-free",
+  categories = [],
+  confidenceThreshold = 0.4,
+  iouThreshold = 0.45,
+  maxFPS = 15,
+  maxDetections = 20,
+  projectToWorld = true,
+  onDetection,
+  onReady,
+  onError,
+  style,
+  ...rest
+}) => {
+  const handleDetection = React.useCallback(
+    (event: NativeDetectionEvent) => {
+      onDetection?.(event.nativeEvent);
+    },
+    [onDetection]
+  );
+
+  const handleReady = React.useCallback(
+    (event: NativeReadyEvent) => {
+      onReady?.(event.nativeEvent);
+    },
+    [onReady]
+  );
+
+  const handleError = React.useCallback(
+    (event: NativeErrorEvent) => {
+      onError?.(event.nativeEvent);
+    },
+    [onError]
+  );
+
+  return (
+    <VRTObjectDetectorView
+      {...rest}
+      style={style}
+      model={model}
+      mode={mode}
+      categories={categories}
+      confidenceThreshold={confidenceThreshold}
+      iouThreshold={iouThreshold}
+      maxFPS={maxFPS}
+      maxDetections={maxDetections}
+      projectToWorld={projectToWorld}
+      onDetectionViro={onDetection ? handleDetection : undefined}
+      onReadyViro={onReady ? handleReady : undefined}
+      onErrorViro={onError ? handleError : undefined}
+    />
+  );
+};

package/components/ViroVirtualButton.tsx

@@ -0,0 +1,101 @@
+/**
+ * ViroVirtualButton.tsx
+ *
+ * Copyright © 2026 ReactVision. All rights reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ */
+
+import * as React from "react";
+import {
+  processColor,
+  requireNativeComponent,
+  StyleProp,
+  ViewStyle,
+} from "react-native";
+
+/**
+ * Native virtual-button component. Renders an on-screen circular button labelled
+ * with the button name (e.g. "A", "B"). On press it writes setButton(idx, true)
+ * to a VROInputState in VROVirtualControllerRegistry; on release it writes false.
+ *
+ * Like ViroVirtualJoystick, touch handling is entirely native — no JS bridge
+ * round-trip — so press/release latency stays in the single-digit-milliseconds range.
+ *
+ * Example:
+ *
+ *     <ViroVirtualButton
+ *       controllerId="p1"
+ *       button="A"
+ *       style={{ position: "absolute", bottom: 60, right: 60, width: 60, height: 60 }}
+ *       size={44}
+ *       tintColor="rgba(255,255,255,0.6)"
+ *     />
+ */
+
+export type ViroButtonName =
+  | "A" | "B" | "X" | "Y" | "Z"
+  | "L1" | "R1" | "L2" | "R2"
+  | "Start" | "Select";
+
+export interface ViroVirtualButtonProps {
+  /**
+   * Identifier of the controller this button writes to. Must match the
+   * `controllerId` of any joystick or other adapter sharing the same state.
+   */
+  controllerId: string;
+
+  /**
+   * Which button this view maps to. Determines the index written to
+   * VROInputState::setButton and the label drawn on the circle.
+   */
+  button: ViroButtonName;
+
+  /**
+   * Diameter of the button circle in points. Defaults to 44.
+   */
+  size?: number;
+
+  /**
+   * Fill colour of the circle. Any value accepted by React Native's color prop.
+   * Defaults to `rgba(255, 255, 255, 0.6)`.
+   */
+  tintColor?: number | string;
+
+  /** Fired when the button is pressed down (same tick as C++ VROInputState write). */
+  onPressIn?:  (event: { nativeEvent: { button: string } }) => void;
+  /** Fired when the button is released (same tick as C++ VROInputState write). */
+  onPressOut?: (event: { nativeEvent: { button: string } }) => void;
+
+  /**
+   * Positioning / sizing.
+   */
+  style?: StyleProp<ViewStyle>;
+}
+
+const NativeVirtualButton =
+  requireNativeComponent<any>("VRTVirtualButtonView");
+
+export const ViroVirtualButton: React.FC<ViroVirtualButtonProps> = (props) => {
+  const { tintColor, ...rest } = props;
+  const processedTint =
+    tintColor != null ? processColor(tintColor) : undefined;
+
+  return (
+    <NativeVirtualButton
+      {...rest}
+      tintColor={processedTint}
+    />
+  );
+};
+
+export default ViroVirtualButton;

package/components/ViroVirtualJoystick.tsx

@@ -0,0 +1,126 @@
+/**
+ * ViroVirtualJoystick.tsx
+ *
+ * Copyright © 2026 ReactVision. All rights reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ */
+
+import * as React from "react";
+import {
+  Platform,
+  processColor,
+  requireNativeComponent,
+  StyleProp,
+  ViewStyle,
+} from "react-native";
+
+/**
+ * Native virtual-joystick component. Renders an on-screen analog stick whose
+ * deflection is written to a process-wide controller state identified by
+ * `controllerId`. The touch handling and state update happen entirely on the
+ * native side — events do not cross the JS bridge — so input latency stays in
+ * the single-digit-milliseconds range even under heavy JS load.
+ *
+ * Consumers read the resulting controller state from native code (via a
+ * VROFrameListener that calls VROVirtualControllerRegistry::instance().peek(id))
+ * or from JS via the forthcoming useVirtualController hook.
+ *
+ * Multiple input sources (this joystick, a future MFi-gamepad adapter, a tilt
+ * adapter) can target the same `controllerId`; the controller state aggregates
+ * whichever sources last wrote to each field.
+ *
+ * Example:
+ *
+ *     <ViroVirtualJoystick
+ *       controllerId="p1"
+ *       stickSide="left"
+ *       style={{ position: "absolute", bottom: 40, left: 40, width: 140, height: 140 }}
+ *       radius={60}
+ *       tintColor="rgba(255,255,255,0.6)"
+ *     />
+ */
+
+export type ViroStickSide = "left" | "right";
+
+export interface ViroVirtualJoystickProps {
+  /**
+   * Identifier of the controller this joystick writes to. Matches the id used
+   * by readers (e.g. native simulation adapters) and by other input adapters
+   * targeting the same controller.
+   */
+  controllerId: string;
+
+  /**
+   * Which stick on the controller this joystick drives. Defaults to `"left"`.
+   */
+  stickSide?: ViroStickSide;
+
+  /**
+   * Outer ring radius in points (the knob is clamped to this distance from the
+   * centre). The view's frame should be at least `radius * 2 + knobMargin` on
+   * each axis for the stick to render fully inside its bounds. Defaults to 60.
+   */
+  radius?: number;
+
+  /**
+   * Tint colour applied to both the outer ring stroke and the knob fill. Any
+   * value accepted by React Native's color prop. Defaults to
+   * `rgba(255, 255, 255, 0.6)`.
+   */
+  tintColor?: number | string;
+
+  /**
+   * Fired on every stick movement with { x, y } normalised to [-1, 1].
+   * Called from native synchronously after VROInputState is updated,
+   * so you can drive JS visuals from the same user gesture.
+   */
+  onStickChange?: (event: { nativeEvent: { x: number; y: number } }) => void;
+
+  /**
+   * Positioning / sizing. Same prop as any RN view.
+   */
+  style?: StyleProp<ViewStyle>;
+}
+
+const NativeVirtualJoystick =
+  requireNativeComponent<any>("VRTVirtualJoystickView");
+
+export const ViroVirtualJoystick: React.FC<ViroVirtualJoystickProps> = (
+  props,
+) => {
+  const { tintColor, onStickChange, ...rest } = props;
+  const processedTint =
+    tintColor != null ? processColor(tintColor) : undefined;
+
+  // Native sends x/y as strings to avoid Fabric conversions.h type-check spam.
+  const handleStickChange = onStickChange
+    ? (e: any) => onStickChange({
+        nativeEvent: { x: parseFloat(e.nativeEvent.x), y: parseFloat(e.nativeEvent.y) }
+      })
+    : undefined;
+
+  return (
+    <NativeVirtualJoystick
+      {...rest}
+      tintColor={processedTint}
+      onStickChange={handleStickChange}
+    />
+  );
+};
+
+if (Platform.OS === "web") {
+  // No-op on web; the joystick is a native-only view today.
+  // Tracked as a follow-up: HTML/Canvas equivalent for the wasm path.
+}
+
+export default ViroVirtualJoystick;

package/components/hooks/useGameLoop.ts

@@ -0,0 +1,78 @@
+/**
+ * useGameLoop — convenience hook that wraps <ViroGameLoop />.
+ *
+ * NOTE: This hook does NOT imperatively mount a component. It is designed to
+ * be used alongside a <ViroGameLoop> component in the scene. The component
+ * fires the events; the hook subscribes to them via a shared ref pattern.
+ *
+ * For the most common case — one game loop per scene — use <ViroGameLoop>
+ * directly with onUpdate/onFixedUpdate props. The hook is provided as
+ * syntactic sugar for cases where the callback needs to live deep in the tree.
+ *
+ * Copyright © 2026 ReactVision. All rights reserved.
+ */
+
+import { useEffect, useRef } from "react";
+import type {
+  ViroGameLoopUpdateEvent,
+  ViroGameLoopFixedEvent,
+} from "../ViroGameLoop";
+
+export type UseGameLoopOptions = {
+  /** Fixed simulation frequency in Hz. Requires a ViroGameLoop with matching fixedHz. */
+  fixedHz?: number;
+};
+
+/**
+ * Subscribe to the variable-step update from the nearest <ViroGameLoop>.
+ *
+ * The callback is always current (uses a ref internally) so it is safe to
+ * reference component state without adding it to a dependency array.
+ */
+export function useGameLoop(
+  callback: (event: ViroGameLoopUpdateEvent) => void,
+  _options?: UseGameLoopOptions
+): (event: ViroGameLoopUpdateEvent) => void {
+  const cbRef = useRef(callback);
+  useEffect(() => {
+    cbRef.current = callback;
+  });
+  // Return a stable handler to pass to ViroGameLoop's onUpdate prop
+  const handlerRef = useRef((event: ViroGameLoopUpdateEvent) => {
+    cbRef.current(event);
+  });
+  return handlerRef.current;
+}
+
+/**
+ * Subscribe to the late-update (post-physics) callback.
+ */
+export function useLateUpdate(
+  callback: (event: ViroGameLoopUpdateEvent) => void
+): (event: ViroGameLoopUpdateEvent) => void {
+  const cbRef = useRef(callback);
+  useEffect(() => {
+    cbRef.current = callback;
+  });
+  const handlerRef = useRef((event: ViroGameLoopUpdateEvent) => {
+    cbRef.current(event);
+  });
+  return handlerRef.current;
+}
+
+/**
+ * Subscribe to the fixed-step callback.
+ * Requires a <ViroGameLoop fixedHz={N}> in the scene.
+ */
+export function useFixedUpdate(
+  callback: (event: ViroGameLoopFixedEvent) => void
+): (event: ViroGameLoopFixedEvent) => void {
+  const cbRef = useRef(callback);
+  useEffect(() => {
+    cbRef.current = callback;
+  });
+  const handlerRef = useRef((event: ViroGameLoopFixedEvent) => {
+    cbRef.current(event);
+  });
+  return handlerRef.current;
+}

package/dist/components/AR/ViroARScene.d.ts

@@ -17,6 +17,14 @@ type Props = ViroCommonProps & {
     onTrackingUpdated?: (state: ViroTrackingState, reason: ViroTrackingReason) => void;
     onPlatformUpdate?: (platformInfoViro: ViroPlatformInfo) => void;
     onAmbientLightUpdate?: (update: ViroAmbientLightInfo) => void;
+    /**
+     * Fired once when depth data (LiDAR or monocular depth estimation) first becomes
+     * available for the session — i.e. hit tests can now return DepthPoints. Useful for
+     * hiding an "initializing depth…" state instead of acting on early, inaccurate
+     * feature points. On devices using monocular depth estimation, this can take a few
+     * seconds after the AR screen appears while the model warms up.
+     */
+    onDepthReady?: () => void;
     /**
      * Describes the acoustic properties of the room around the user
      */
@@ -47,6 +55,10 @@ export declare class ViroARScene extends ViroBase<Props> {
      * Returns object w/ "intensity" and "color" keys
      */
     _onAmbientLightUpdate: (event: NativeSyntheticEvent<ViroAmbientLightUpdateEvent>) => void;
+    /**
+     * Fired once when depth data first becomes available for hit testing.
+     */
+    _onDepthReady: (_event: NativeSyntheticEvent<{}>) => void;
     _onAnchorFound: (event: NativeSyntheticEvent<ViroARAnchorFoundEvent>) => void;
     _onAnchorUpdated: (event: NativeSyntheticEvent<ViroARAnchorUpdatedEvent>) => void;
     _onAnchorRemoved: (event: NativeSyntheticEvent<ViroARAnchorRemovedEvent>) => void;

package/dist/components/AR/ViroARScene.js

@@ -176,6 +176,12 @@ class ViroARScene extends ViroBase_1.ViroBase {
         this.props.onAmbientLightUpdate &&
             this.props.onAmbientLightUpdate(event.nativeEvent.ambientLightInfo);
     };
+    /**
+     * Fired once when depth data first becomes available for hit testing.
+     */
+    _onDepthReady = (_event) => {
+        this.props.onDepthReady && this.props.onDepthReady();
+    };
     _onAnchorFound = (event) => {
         // TODO: this is in a different format than the other onAnchorFound methods
         this.props.onAnchorFound &&
@@ -334,7 +340,7 @@ class ViroARScene extends ViroBase_1.ViroBase {
                 },
             }}>
         <VRTARScene {...this.props} canHover={this.props.onHover != undefined} canClick={this.props.onClick != undefined ||
-                this.props.onClickState != undefined} canTouch={this.props.onTouch != undefined} canScroll={this.props.onScroll != undefined} canSwipe={this.props.onSwipe != undefined} canDrag={this.props.onDrag != undefined} canPinch={this.props.onPinch != undefined} canRotate={this.props.onRotate != undefined} canFuse={this.props.onFuse != undefined} canCameraARHitTest={this.props.onCameraARHitTest != undefined} canARPointCloudUpdate={this.props.onARPointCloudUpdate != undefined} canCameraTransformUpdate={this.props.onCameraTransformUpdate != undefined} onHoverViro={this._onHover} onClickViro={this._onClickState} onClick={undefined} onTouchViro={this._onTouch} onScrollViro={this._onScroll} onSwipeViro={this._onSwipe} onDragViro={this._onDrag} onPinchViro={this._onPinch} onRotateViro={this._onRotate} onFuseViro={this._onFuse} onCameraARHitTestViro={this._onCameraARHitTest} onARPointCloudUpdateViro={this._onARPointCloudUpdate} onCameraTransformUpdateViro={this._onCameraTransformUpdate} onPlatformUpdateViro={this._onPlatformUpdate} onTrackingUpdatedViro={this._onTrackingUpdated} onAmbientLightUpdateViro={this._onAmbientLightUpdate} onAnchorFoundViro={this._onAnchorFound} onAnchorUpdatedViro={this._onAnchorUpdated} onAnchorRemovedViro={this._onAnchorRemoved} timeToFuse={timeToFuse} anchorDetectionTypes={anchorDetectionTypes} displayPointCloud={displayPointCloud} pointCloudImage={pointCloudImage} pointCloudScale={pointCloudScale} pointCloudMaxPoints={pointCloudMaxPoints}/>
+                this.props.onClickState != undefined} canTouch={this.props.onTouch != undefined} canScroll={this.props.onScroll != undefined} canSwipe={this.props.onSwipe != undefined} canDrag={this.props.onDrag != undefined} canPinch={this.props.onPinch != undefined} canRotate={this.props.onRotate != undefined} canFuse={this.props.onFuse != undefined} canCameraARHitTest={this.props.onCameraARHitTest != undefined} canARPointCloudUpdate={this.props.onARPointCloudUpdate != undefined} canCameraTransformUpdate={this.props.onCameraTransformUpdate != undefined} onHoverViro={this._onHover} onClickViro={this._onClickState} onClick={undefined} onTouchViro={this._onTouch} onScrollViro={this._onScroll} onSwipeViro={this._onSwipe} onDragViro={this._onDrag} onPinchViro={this._onPinch} onRotateViro={this._onRotate} onFuseViro={this._onFuse} onCameraARHitTestViro={this._onCameraARHitTest} onARPointCloudUpdateViro={this._onARPointCloudUpdate} onCameraTransformUpdateViro={this._onCameraTransformUpdate} onPlatformUpdateViro={this._onPlatformUpdate} onTrackingUpdatedViro={this._onTrackingUpdated} onAmbientLightUpdateViro={this._onAmbientLightUpdate} onDepthReadyViro={this._onDepthReady} onAnchorFoundViro={this._onAnchorFound} onAnchorUpdatedViro={this._onAnchorUpdated} onAnchorRemovedViro={this._onAnchorRemoved} timeToFuse={timeToFuse} anchorDetectionTypes={anchorDetectionTypes} displayPointCloud={displayPointCloud} pointCloudImage={pointCloudImage} pointCloudScale={pointCloudScale} pointCloudMaxPoints={pointCloudMaxPoints}/>
       </ViroSceneContext_1.ViroSceneContext.Provider>);
     }
 }
@@ -368,6 +374,7 @@ ViroARScene, {
         onTrackingInitializedViro: true,
         onTrackingUpdatedViro: true,
         onAmbientLightUpdateViro: true,
+        onDepthReadyViro: true,
         onAnchorFoundViro: true,
         onAnchorUpdatedViro: true,
         onAnchorRemovedViro: true,

package/dist/components/AR/ViroARSceneNavigator.d.ts

@@ -127,6 +127,36 @@ type Props = ViewProps & {
      * @platform ios
      */
     preferMonocularDepth?: boolean;
+    /**
+     * Calibration scale applied to monocular depth values before use in occlusion.
+     * 1.0 (default) = no change. Use < 1.0 if the model overestimates distances
+     * (virtual objects visible through real surfaces). Use > 1.0 if it underestimates.
+     * Typical tuning range: 0.7 – 1.3.
+     *
+     * @default 1.0
+     * @platform ios
+     */
+    monocularDepthScale?: number;
+    /**
+     * Maximum inference rate for monocular depth (default: 5).
+     * Lower values reduce device heat. Thermal state automatically
+     * overrides this downward: Fair→3fps, Serious→2fps, Critical→stopped.
+     * 3fps is barely perceptible for occlusion; 5fps is very smooth.
+     *
+     * @default 5
+     * @platform ios
+     */
+    monocularDepthTargetFPS?: number;
+    /**
+     * Use the front (selfie) camera as the AR session background.
+     * On iOS uses ARFaceTrackingConfiguration (requires TrueDepth camera, iPhone X+).
+     * On Android uses ARCore Augmented Faces mode (front camera).
+     * World tracking, plane detection, and LiDAR are unavailable in this mode.
+     *
+     * @default false
+     * @platform ios, android
+     */
+    frontCameraEnabled?: boolean;
     /**
      * Cloud and geospatial anchor provider.
      * Set to `"reactvision"` (default) for the ReactVision backend,

package/dist/components/Utilities/StreamingAudioManager.d.ts

@@ -0,0 +1,22 @@
+/**
+ * StreamingAudioManager — imperative API for streaming PCM audio.
+ *
+ * Typical TTS flow:
+ *   StreamingAudioManager.create('tts');
+ *   StreamingAudioManager.beginStreaming('tts', 24000, 1);
+ *   StreamingAudioManager.play('tts');
+ *   // on each TTS audio chunk:
+ *   StreamingAudioManager.pushSamples('tts', base64FloatPCM);
+ *   // when done:
+ *   StreamingAudioManager.destroy('tts');
+ */
+export declare const StreamingAudioManager: {
+    create: (id: string) => void;
+    beginStreaming: (id: string, sampleRate: number, channels: number) => void;
+    play: (id: string) => void;
+    pause: (id: string) => void;
+    setVolume: (id: string, volume: number) => void;
+    setMuted: (id: string, muted: boolean) => void;
+    pushSamples: (id: string, base64: string) => void;
+    destroy: (id: string) => void;
+};

package/dist/components/Utilities/StreamingAudioManager.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingAudioManager = void 0;
+const react_native_1 = require("react-native");
+// RCT_EXPORT_MODULE() in newer RN (0.76+) keeps the "Module" suffix in NativeModules.
+const native = (react_native_1.NativeModules.VRTStreamingAudioModule ?? react_native_1.NativeModules.VRTStreamingAudio);
+function noop(..._args) { }
+/**
+ * StreamingAudioManager — imperative API for streaming PCM audio.
+ *
+ * Typical TTS flow:
+ *   StreamingAudioManager.create('tts');
+ *   StreamingAudioManager.beginStreaming('tts', 24000, 1);
+ *   StreamingAudioManager.play('tts');
+ *   // on each TTS audio chunk:
+ *   StreamingAudioManager.pushSamples('tts', base64FloatPCM);
+ *   // when done:
+ *   StreamingAudioManager.destroy('tts');
+ */
+exports.StreamingAudioManager = {
+    create: native
+        ? (id) => native.create(id)
+        : noop,
+    beginStreaming: native
+        ? (id, sampleRate, channels) => native.beginStreaming(id, sampleRate, channels)
+        : noop,
+    play: native
+        ? (id) => native.play(id)
+        : noop,
+    pause: native
+        ? (id) => native.pause(id)
+        : noop,
+    setVolume: native
+        ? (id, volume) => native.setVolume(id, volume)
+        : noop,
+    setMuted: native
+        ? (id, muted) => native.setMuted(id, muted)
+        : noop,
+    pushSamples: native
+        ? (id, base64) => native.pushSamples(id, base64)
+        : noop,
+    destroy: native
+        ? (id) => native.destroy(id)
+        : noop,
+};