@reactvision/react-viro 2.55.0 → 2.57.0

package/README.md

@@ -45,6 +45,14 @@ For Expo projects, the easiest way to start is to clone the official starter kit
 
 For step-by-step setup instructions, including platform-specific permissions and build configuration, see the full installation guide in the docs: <https://viro-community.readme.io/docs/installation-instructions>
 
+## MCP Server
+
+If you're building AR, VR or XR apps with ViroReact, our MCP server is the fastest way to get moving. Think of it as a living guide to ViroReact, always current, that plugs straight into the tools you already use.
+
+Connect it to Claude, Codex, Cursor or any other coding agent, and your agent instantly understands how to work with ViroReact's cross-platform rendering. No hunting through docs, no guesswork. (Our documentation is still a great companion, but the MCP is the most up to date source there is.)
+
+[MCP Setup Instructions](https://viro-community.readme.io/docs/viroreact-mcp-server)
+
 ## Features
 
 ViroReact ships with a complete spatial computing toolkit out of the box — no third-party plugins, no paid add-ons.
@@ -84,6 +92,25 @@ You can get a Studio account, which includes Platform access, for free at <https
 - Cloud Anchors guide: <https://viro-community.readme.io/docs/cloud-anchors>
 - Geospatial Anchors guide: <https://viro-community.readme.io/docs/geospatial-anchors>
 
+## Studio
+
+[ReactVision Studio](https://studio.reactvision.xyz) is our browser-based visual scene editor for AR and VR. Build scenes visually in Studio, then embed them inside your own ViroReact app with a single component. Designers and developers can iterate on a scene in Studio and have it update in production without a new app build.
+
+**Build scenes visually**
+
+- **Placement** — drag-and-drop 3D objects, images, video, text, and primitives into a scene with visual gizmos for position, rotation, and scale. No JSX required to lay out a scene.
+- **AI asset generation** — generate 3D models from a text prompt or reference image directly inside the editor, powered by ReactVision Platform.
+- **Animations** — author keyframe and property animations on a timeline, chain them into sequences, and trigger them from interactions or scene events.
+- **Physics** — assign dynamic, static, or kinematic bodies to objects, configure mass, friction, and restitution, and wire up collision callbacks — the same physics engine ViroReact ships with, exposed visually.
+
+**Embed Studio scenes in your app**
+
+Drop the `StudioSceneNavigator` component into your ViroReact app, point it at a Studio scene, and your app picks up whatever your team is editing in Studio without a new native build.
+
+**Getting started**
+
+Full walkthrough — including Studio setup, exporting a scene, and wiring `StudioSceneNavigator` into a React Native app — is in our blog: <https://updates.reactvision.xyz/how-to-build-your-first-ar-vr-app-with-studio-and-react-native-f2421ecce9ae>
+
 ## Documentation
 
 - Full API reference and guides: <https://viro-community.readme.io/docs/overview>

package/components/AR/ViroARScene.tsx

@@ -72,6 +72,14 @@ type Props = ViroCommonProps & {
   ) => 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
    */
@@ -237,6 +245,13 @@ export class ViroARScene extends ViroBase<Props> {
       this.props.onAmbientLightUpdate(event.nativeEvent.ambientLightInfo);
   };
 
+  /**
+   * Fired once when depth data first becomes available for hit testing.
+   */
+  _onDepthReady = (_event: NativeSyntheticEvent<{}>) => {
+    this.props.onDepthReady && this.props.onDepthReady();
+  };
+
   _onAnchorFound = (event: NativeSyntheticEvent<ViroARAnchorFoundEvent>) => {
     // TODO: this is in a different format than the other onAnchorFound methods
     this.props.onAnchorFound &&
@@ -527,6 +542,7 @@ export class ViroARScene extends ViroBase<Props> {
           onPlatformUpdateViro={this._onPlatformUpdate}
           onTrackingUpdatedViro={this._onTrackingUpdated}
           onAmbientLightUpdateViro={this._onAmbientLightUpdate}
+          onDepthReadyViro={this._onDepthReady}
           onAnchorFoundViro={this._onAnchorFound}
           onAnchorUpdatedViro={this._onAnchorUpdated}
           onAnchorRemovedViro={this._onAnchorRemoved}
@@ -573,6 +589,7 @@ var VRTARScene = requireNativeComponent<any>(
       onTrackingInitializedViro: true,
       onTrackingUpdatedViro: true,
       onAmbientLightUpdateViro: true,
+      onDepthReadyViro: true,
       onAnchorFoundViro: true,
       onAnchorUpdatedViro: true,
       onAnchorRemovedViro: true,

package/components/AR/ViroARSceneNavigator.tsx

@@ -184,6 +184,39 @@ type Props = ViewProps & {
    */
   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/components/Utilities/StreamingAudioManager.ts

@@ -0,0 +1,73 @@
+import { NativeModules } from "react-native";
+
+interface StreamingAudioNative {
+  create(playerId: string): void;
+  beginStreaming(playerId: string, sampleRate: number, channels: number): void;
+  play(playerId: string): void;
+  pause(playerId: string): void;
+  setVolume(playerId: string, volume: number): void;
+  setMuted(playerId: string, muted: boolean): void;
+  /**
+   * Push interleaved float32 PCM samples encoded as base64 (little-endian IEEE 754).
+   *
+   * JS encoding:
+   *   const bytes = new Uint8Array(float32Array.buffer);
+   *   const b64   = btoa(String.fromCharCode(...bytes));
+   */
+  pushSamples(playerId: string, base64Samples: string): void;
+  destroy(playerId: string): void;
+}
+
+// RCT_EXPORT_MODULE() in newer RN (0.76+) keeps the "Module" suffix in NativeModules.
+const native = (NativeModules.VRTStreamingAudioModule ?? NativeModules.VRTStreamingAudio) as
+  | StreamingAudioNative
+  | undefined;
+
+function noop(..._args: unknown[]): void {}
+
+/**
+ * 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 const StreamingAudioManager = {
+  create: native
+    ? (id: string) => native.create(id)
+    : (noop as (id: string) => void),
+
+  beginStreaming: native
+    ? (id: string, sampleRate: number, channels: number) =>
+        native.beginStreaming(id, sampleRate, channels)
+    : (noop as (id: string, sr: number, ch: number) => void),
+
+  play: native
+    ? (id: string) => native.play(id)
+    : (noop as (id: string) => void),
+
+  pause: native
+    ? (id: string) => native.pause(id)
+    : (noop as (id: string) => void),
+
+  setVolume: native
+    ? (id: string, volume: number) => native.setVolume(id, volume)
+    : (noop as (id: string, v: number) => void),
+
+  setMuted: native
+    ? (id: string, muted: boolean) => native.setMuted(id, muted)
+    : (noop as (id: string, m: boolean) => void),
+
+  pushSamples: native
+    ? (id: string, base64: string) => native.pushSamples(id, base64)
+    : (noop as (id: string, b64: string) => void),
+
+  destroy: native
+    ? (id: string) => native.destroy(id)
+    : (noop as (id: string) => void),
+};

package/components/Utilities/ViroVersion.ts

@@ -1 +1 @@
-export const VIRO_VERSION = "2.55.0";
+export const VIRO_VERSION = "2.57.0";

package/components/ViroCameraTexture.tsx

@@ -0,0 +1,230 @@
+/**
+ * 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 {
+  findNodeHandle,
+  NativeModules,
+  NativeSyntheticEvent,
+  requireNativeComponent,
+  ViewProps,
+} from "react-native";
+import { ViroErrorEvent } from "./Types/ViroEvents";
+import { ViroNativeRef } from "./Types/ViroUtils";
+
+const { VRTCameraTextureModule } = NativeModules;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ViroCameraPosition = "front" | "back";
+
+export type ViroCameraReadyEvent = Record<string, never>;
+
+/**
+ * Result returned by capturePhoto / startRecording / stopRecording.
+ * Mirrors the response shape from both iOS and Android NativeModules.
+ */
+export type ViroCaptureResult =
+  | { success: true; url: string }
+  | { success: false; error: string };
+
+export type ViroCapturePhotoOptions = {
+  /** Absolute file path for the JPEG. Defaults to a cache-dir path. */
+  outputPath?: string;
+};
+
+export type ViroCaptureVideoOptions = {
+  /** Absolute file path for the MP4. Defaults to a cache-dir path. */
+  outputPath?: string;
+};
+
+type Props = ViewProps & {
+  /**
+   * Name of the material (created via ViroMaterials.createMaterials) to bind
+   * the live camera feed to as its diffuse texture. Unlike ViroMaterialVideo,
+   * this component creates the camera texture internally and sets it on the
+   * named material — the material only needs a lightingModel defined.
+   */
+  material: string;
+
+  /**
+   * Which device camera to use. Front camera feed is automatically mirrored
+   * for a natural selfie effect. Defaults to "front".
+   */
+  cameraPosition?: ViroCameraPosition;
+
+  /**
+   * Whether camera capture is paused. When true the last captured frame is
+   * held and battery usage drops to near zero. Defaults to false.
+   */
+  paused?: boolean;
+
+  /**
+   * Called once when the first camera frame is available and the texture is
+   * ready to be rendered. Fires from the native AVFoundation / Camera2 callback,
+   * not immediately on mount.
+   */
+  onCameraReady?: () => void;
+
+  /**
+   * Called when the camera fails to initialise (permission denied, hardware
+   * error, invalid material name, etc.).
+   */
+  onError?: (event: NativeSyntheticEvent<ViroErrorEvent>) => void;
+};
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/**
+ * ViroCameraTexture binds a live device camera feed to a named material texture.
+ *
+ * The component creates the camera texture internally and sets it on the material,
+ * so the material only needs a lightingModel. The texture is updated every frame.
+ *
+ * **Usage:**
+ * ```tsx
+ * import { ViroMaterials, ViroQuad, ViroCameraTexture } from '@reactvision/react-viro';
+ *
+ * ViroMaterials.createMaterials({
+ *   selfieMat: { lightingModel: 'Constant' },
+ * });
+ *
+ * <ViroARScene>
+ *   <ViroQuad position={[0, 0, -2]} width={1.6} height={2.4} materials={["selfieMat"]} />
+ *   <ViroCameraTexture
+ *     material="selfieMat"
+ *     cameraPosition="front"
+ *     onCameraReady={() => console.log('Camera ready')}
+ *     onError={(e) => console.error(e.nativeEvent.error)}
+ *   />
+ * </ViroARScene>
+ * ```
+ */
+export class ViroCameraTexture extends React.Component<Props> {
+  _component: ViroNativeRef = null;
+
+  _onCameraReady = () => {
+    this.props.onCameraReady && this.props.onCameraReady();
+  };
+
+  _onError = (event: NativeSyntheticEvent<ViroErrorEvent>) => {
+    this.props.onError && this.props.onError(event);
+  };
+
+  // ---------------------------------------------------------------------------
+  // Capture API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Capture a single JPEG still from the camera feed.
+   *
+   * @param options.outputPath  Absolute path for the output JPEG.
+   *                            Omit to let the native layer choose a default
+   *                            cache-directory path.
+   * @returns  Promise resolving to `{ success: true, url }` on success or
+   *           `{ success: false, error }` on failure.
+   *
+   * @example
+   * ```ts
+   * const result = await cameraRef.current?.capturePhoto();
+   * if (result?.success) console.log('Saved to', result.url);
+   * ```
+   */
+  async capturePhoto(
+    options: ViroCapturePhotoOptions = {}
+  ): Promise<ViroCaptureResult> {
+    const tag = findNodeHandle(this._component);
+    if (tag == null) {
+      return { success: false, error: "ViroCameraTexture is not mounted" };
+    }
+    return VRTCameraTextureModule.capturePhoto(
+      tag,
+      options.outputPath ?? null
+    ) as Promise<ViroCaptureResult>;
+  }
+
+  /**
+   * Start recording the camera feed to an MP4 file.
+   *
+   * The promise resolves once the recording session has successfully started.
+   * Call {@link stopRecording} to finalise the file.
+   *
+   * @param options.outputPath  Absolute path for the output MP4.
+   *                            Omit to let the native layer choose a default.
+   * @returns  Promise resolving to `{ success: true, url }` (the path that
+   *           will be written) or `{ success: false, error }`.
+   *
+   * @example
+   * ```ts
+   * await cameraRef.current?.startRecording();
+   * // … some time later …
+   * const result = await cameraRef.current?.stopRecording();
+   * if (result?.success) console.log('Video saved to', result.url);
+   * ```
+   */
+  async startRecording(
+    options: ViroCaptureVideoOptions = {}
+  ): Promise<ViroCaptureResult> {
+    const tag = findNodeHandle(this._component);
+    if (tag == null) {
+      return { success: false, error: "ViroCameraTexture is not mounted" };
+    }
+    return VRTCameraTextureModule.startRecording(
+      tag,
+      options.outputPath ?? null
+    ) as Promise<ViroCaptureResult>;
+  }
+
+  /**
+   * Stop an in-progress recording and finalise the MP4 file.
+   *
+   * @returns  Promise resolving to `{ success: true, url }` with the path of
+   *           the written file, or `{ success: false, error }`.
+   */
+  async stopRecording(): Promise<ViroCaptureResult> {
+    const tag = findNodeHandle(this._component);
+    if (tag == null) {
+      return { success: false, error: "ViroCameraTexture is not mounted" };
+    }
+    return VRTCameraTextureModule.stopRecording(
+      tag
+    ) as Promise<ViroCaptureResult>;
+  }
+
+  render() {
+    const nativeProps = Object.assign({} as any, this.props);
+    nativeProps.cameraPosition = this.props.cameraPosition ?? "front";
+    nativeProps.paused = this.props.paused ?? false;
+    nativeProps.onCameraReadyViro = this._onCameraReady;
+    nativeProps.onErrorViro = this._onError;
+    nativeProps.ref = (component: ViroNativeRef) => {
+      this._component = component;
+    };
+    return <VRTCameraTexture {...nativeProps} />;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Native component binding
+// ---------------------------------------------------------------------------
+
+const VRTCameraTexture = requireNativeComponent<any>(
+  "VRTCameraTexture",
+  // @ts-ignore
+  ViroCameraTexture,
+  {
+    nativeOnly: {
+      onCameraReadyViro: true,
+      onErrorViro: true,
+    },
+  }
+);

package/components/ViroGameLoop.tsx

@@ -0,0 +1,74 @@
+/**
+ * ViroGameLoop.tsx — headless component that fires per-frame JS callbacks.
+ *
+ * Mount anywhere inside a ViroARScene or ViroScene to start the loop.
+ * The loop automatically stops when the component unmounts.
+ *
+ * Usage:
+ *   <ViroGameLoop onUpdate={(dt, elapsed) => { ... }} />
+ *   <ViroGameLoop fixedHz={30} onFixedUpdate={(dt) => { ... }} />
+ *
+ * Copyright © 2026 ReactVision. All rights reserved.
+ */
+
+import React from "react";
+import { requireNativeComponent, ViewStyle } from "react-native";
+
+const VRTGameLoopView = requireNativeComponent<ViroGameLoopNativeProps>(
+  "VRTGameLoopView"
+);
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export type ViroGameLoopUpdateEvent = {
+  dt: number;       // delta time in seconds since last frame
+  elapsed: number;  // total elapsed seconds since component mounted
+};
+
+export type ViroGameLoopFixedEvent = {
+  dt: number;       // fixed delta (1 / fixedHz)
+};
+
+export type ViroGameLoopProps = {
+  /** Called every rendered frame. dt = seconds since last frame. */
+  onUpdate?: (event: ViroGameLoopUpdateEvent) => void;
+  /** Called after physics + rendering each frame (useLateUpdate equivalent). */
+  onLateUpdate?: (event: ViroGameLoopUpdateEvent) => void;
+  /** Fixed simulation frequency in Hz. When set, onFixedUpdate fires at this rate. */
+  fixedHz?: number;
+  /** Called at a fixed rate determined by fixedHz. */
+  onFixedUpdate?: (event: ViroGameLoopFixedEvent) => void;
+};
+
+type ViroGameLoopNativeProps = {
+  onUpdate?: (e: { nativeEvent: ViroGameLoopUpdateEvent }) => void;
+  onLateUpdate?: (e: { nativeEvent: ViroGameLoopUpdateEvent }) => void;
+  onFixedUpdate?: (e: { nativeEvent: ViroGameLoopFixedEvent }) => void;
+  fixedHz?: number;
+  style?: ViewStyle;
+};
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+export function ViroGameLoop({
+  onUpdate,
+  onLateUpdate,
+  onFixedUpdate,
+  fixedHz,
+}: ViroGameLoopProps) {
+  // Native sends dt/elapsed as strings to avoid Fabric conversions.h type-check spam.
+  const parse = (e: any) => ({
+    dt:      parseFloat(e.nativeEvent.dt),
+    elapsed: parseFloat(e.nativeEvent.elapsed ?? "0"),
+  });
+  const parseFixed = (e: any) => ({ dt: parseFloat(e.nativeEvent.dt) });
+
+  return (
+    <VRTGameLoopView
+      onUpdate={onUpdate ? (e) => onUpdate(parse(e)) : undefined}
+      onLateUpdate={onLateUpdate ? (e) => onLateUpdate(parse(e)) : undefined}
+      onFixedUpdate={onFixedUpdate ? (e) => onFixedUpdate(parseFixed(e)) : undefined}
+      fixedHz={fixedHz}
+    />
+  );
+}

package/components/ViroGameLoopUtils.ts

@@ -0,0 +1,52 @@
+/**
+ * ViroGameLoopUtils — direct node manipulation that bypasses the React reconciler.
+ *
+ * Call these from inside useGameLoop / onUpdate callbacks for zero-setState
+ * positional updates. The native NodeModule methods dispatch directly to the
+ * render thread via the existing VRONode::setPositionAtomic() infrastructure.
+ *
+ * Copyright © 2026 ReactVision. All rights reserved.
+ */
+
+import { findNodeHandle, UIManager } from "react-native";
+import type React from "react";
+
+export const ViroGameLoopUtils = {
+  /**
+   * Set the node's position without going through React state.
+   * Equivalent to <ViroNode position={[x,y,z]} /> but synchronous
+   * and reconciler-free — safe to call every frame.
+   */
+  setPosition(
+    nodeRef: React.RefObject<any>,
+    position: [number, number, number]
+  ): void {
+    const handle = findNodeHandle(nodeRef.current);
+    if (handle == null) return;
+    UIManager.dispatchViewManagerCommand(handle, "setPosition", position);
+  },
+
+  /**
+   * Set Euler rotation (degrees) without going through React state.
+   */
+  setRotation(
+    nodeRef: React.RefObject<any>,
+    rotation: [number, number, number]
+  ): void {
+    const handle = findNodeHandle(nodeRef.current);
+    if (handle == null) return;
+    UIManager.dispatchViewManagerCommand(handle, "setRotationEuler", rotation);
+  },
+
+  /**
+   * Set uniform or non-uniform scale without going through React state.
+   */
+  setScale(
+    nodeRef: React.RefObject<any>,
+    scale: [number, number, number]
+  ): void {
+    const handle = findNodeHandle(nodeRef.current);
+    if (handle == null) return;
+    UIManager.dispatchViewManagerCommand(handle, "setScale", scale);
+  },
+};