@reactvision/react-viro 2.57.2 → 2.57.4

package/README.md

@@ -92,6 +92,14 @@ 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>
 
+## Optional Packages
+
+Two capabilities are shipped as separate, opt-in packages rather than in core — install them only if you need them:
+
+- **[`@reactvision/react-viro-onnx`](https://www.npmjs.com/package/@reactvision/react-viro-onnx)** — on-device object detection. It provides the ONNX Runtime inference engine behind [`ViroObjectDetector`](https://github.com/ReactVision/viro/blob/main/docs/ViroObjectDetector.md) (model inference, NMS, class-name decoding). Without it, `ViroObjectDetector` returns no detections. Keeping it separate avoids bundling ONNX Runtime (~tens of MB) into apps that don't use detection.
+
+- **[`@reactvision/react-viro-face-tracking`](https://www.npmjs.com/package/@reactvision/react-viro-face-tracking)** — front-camera (ARKit face-tracking) AR. It backs the `frontCameraEnabled` prop on `ViroARSceneNavigator`. On iOS ARKit reaches the front camera only through the **TrueDepth** API, which Apple statically scans for under App Store review Guideline 2.5.1 — so it's kept out of the core binary. Apps that don't use front-camera AR stay TrueDepth-free and pass review with no configuration; install this package (and declare TrueDepth) only when you need it. For a selfie *feed* without face tracking, use [`ViroCameraTexture`](https://github.com/ReactVision/viro/blob/main/docs/ViroCameraTexture.md) with `cameraPosition="front"` — that's in core and uses AVFoundation, no TrueDepth.
+
 ## 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.

package/components/AR/ViroARSceneNavigator.tsx

@@ -208,9 +208,17 @@ type Props = ViewProps & {
 
   /**
    * 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.
+   *
+   * Requires the optional `@reactvision/react-viro-face-tracking` package to be
+   * installed — it provides the native front-camera AR configuration and, on
+   * iOS, declares TrueDepth usage. Without it, this prop has no effect.
+   *
+   * On iOS the package uses the front TrueDepth camera; on Android it uses
+   * ARCore Augmented Faces mode. World tracking, plane detection, and LiDAR are
+   * unavailable in this mode.
+   *
+   * For a plain selfie feed without face tracking (no TrueDepth), use
+   * `ViroCameraTexture` with `cameraPosition="front"` instead.
    *
    * @default false
    * @platform ios, android

package/components/Studio/StudioARScene.tsx

@@ -10,6 +10,7 @@ import { ViroScene } from "../ViroScene";
 import { ViroText } from "../ViroText";
 import { ViroController } from "../ViroController";
 import { isQuest } from "../Utilities/ViroPlatform";
+import type { ViroAnchor } from "../Types/ViroEvents";
 import { registerSceneAnimations } from "./domain/animationRegistry";
 import { createPlacementCollisionHandler } from "./domain/collisionBindingsRuntime";
 import { collisionPairKey } from "./domain/collisionPairKey";
@@ -51,6 +52,12 @@ interface StudioARSceneProps {
   onReady?: () => void;
   onError?: (err: Error) => void;
   onSceneChange?: (sceneId: string, sceneName: string) => void;
+  /** Fired on first AR plane detection (AUTOMATIC) / plane accept (MANUAL). */
+  onPlaneDetected?: () => void;
+  /** Fired when the user taps to select a plane (MANUAL mode). */
+  onPlaneSelected?: () => void;
+  /** Text shown when the scene has no assets. Defaults to "No assets to display". */
+  noAssetsMessage?: string;
   /** Session-scoped store owned by the navigator; survives scene pushes. */
   variableStore?: StudioVariableStore;
 }
@@ -73,8 +80,16 @@ interface StudioARSceneInnerProps extends StudioARSceneProps {
 }
 
 const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
-  const { sceneNavigator, sceneData, onReady, onSceneChange, variableStore } =
-    props;
+  const {
+    sceneNavigator,
+    sceneData,
+    onReady,
+    onSceneChange,
+    onPlaneDetected,
+    onPlaneSelected,
+    noAssetsMessage,
+    variableStore,
+  } = props;
   const { scene, assets, animations, collision_bindings, functions } =
     sceneData;
 
@@ -193,6 +208,49 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
     {}
   );
 
+  // ─── Drag-active state (debounced) ────────────────────────────────────────
+  // Viro's onDrag fires per-frame. Track a Record<assetId, true> cleared 220ms
+  // after the last drag event; the node factory reads isDragActive to pass
+  // kinematicDragOverride so Dynamic-physics bodies don't fight the gesture.
+  // The onDrag callback's mere presence is also what unlocks native drag.
+  const [dragActiveByAssetId, setDragActiveByAssetId] = useState<
+    Record<string, true>
+  >({});
+  const dragTimersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(
+    new Map()
+  );
+
+  const notifyPhysicsDrag = useCallback((assetId: string) => {
+    setDragActiveByAssetId((prev) =>
+      prev[assetId] ? prev : { ...prev, [assetId]: true }
+    );
+    const existing = dragTimersRef.current.get(assetId);
+    if (existing) clearTimeout(existing);
+    const t = setTimeout(() => {
+      setDragActiveByAssetId((prev) => {
+        if (!prev[assetId]) return prev;
+        const next = { ...prev };
+        delete next[assetId];
+        return next;
+      });
+      dragTimersRef.current.delete(assetId);
+    }, 220);
+    dragTimersRef.current.set(assetId, t);
+  }, []);
+
+  const isDragActive = useCallback(
+    (assetId: string) => !!dragActiveByAssetId[assetId],
+    [dragActiveByAssetId]
+  );
+
+  useEffect(() => {
+    const timers = dragTimersRef.current;
+    return () => {
+      timers.forEach((timer) => clearTimeout(timer));
+      timers.clear();
+    };
+  }, []);
+
   const handleAssetLoaded = useCallback((assetId: string) => {
     setLoadedAssetIds((prev) =>
       prev[assetId] ? prev : { ...prev, [assetId]: true }
@@ -429,6 +487,8 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
           animationStates,
           handleAssetLoaded,
           getCollisionHandler(asset.id),
+          isDragActive,
+          notifyPhysicsDrag,
           handleSceneChange,
           runtimeCtx
         );
@@ -441,6 +501,8 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
     animationStates,
     handleAssetLoaded,
     getCollisionHandler,
+    isDragActive,
+    notifyPhysicsDrag,
     maxModels,
     handleSceneChange,
     runtimeCtx,
@@ -461,6 +523,8 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
           animationStates,
           handleAssetLoaded,
           getCollisionHandler(asset.id),
+          isDragActive,
+          notifyPhysicsDrag,
           handleSceneChange,
           runtimeCtx
         );
@@ -480,6 +544,8 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
     animationStates,
     handleAssetLoaded,
     getCollisionHandler,
+    isDragActive,
+    notifyPhysicsDrag,
     handleSceneChange,
     runtimeCtx,
   ]);
@@ -490,6 +556,76 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
   ).toUpperCase();
   const planeAlignment = (scene.plane_direction ?? "Horizontal") as any;
 
+  // Native plane anchor types for ViroARScene (lowercase matches Viro defaults).
+  const anchorDetectionTypes = useMemo((): string[] | undefined => {
+    if (planeDetectionMode !== "AUTOMATIC" && planeDetectionMode !== "MANUAL") {
+      return undefined;
+    }
+    const dir = (scene.plane_direction ?? "Horizontal").toLowerCase();
+    if (dir === "vertical") return ["planesVertical"];
+    if (dir.includes("horizontal")) return ["planesHorizontal"];
+    return ["planesHorizontal", "planesVertical"];
+  }, [planeDetectionMode, scene.plane_direction]);
+
+  // ViroARPlaneSelector (react-viro 2.54+) no longer receives scene anchors
+  // automatically; ViroARScene forwards them here via ref. Also surfaces
+  // onPlaneDetected / onPlaneSelected to the host.
+  const planeSelectorRef = useRef<InstanceType<
+    typeof ViroARPlaneSelector
+  > | null>(null);
+
+  const handleAnchorFound = useCallback(
+    (anchor: ViroAnchor) => {
+      try {
+        if (planeDetectionMode === "MANUAL") {
+          planeSelectorRef.current?.handleAnchorFound(anchor);
+        }
+        if (planeDetectionMode === "AUTOMATIC" && anchor?.type === "plane") {
+          onPlaneDetected?.();
+        }
+      } catch (error) {
+        console.error("[Studio] handleAnchorFound failed:", error);
+      }
+    },
+    [planeDetectionMode, onPlaneDetected]
+  );
+
+  const handleAnchorUpdated = useCallback(
+    (anchor: ViroAnchor) => {
+      try {
+        if (planeDetectionMode === "MANUAL") {
+          planeSelectorRef.current?.handleAnchorUpdated(anchor);
+        }
+      } catch (error) {
+        console.error("[Studio] handleAnchorUpdated failed:", error);
+      }
+    },
+    [planeDetectionMode]
+  );
+
+  const handleAnchorRemoved = useCallback(
+    (anchor?: ViroAnchor) => {
+      try {
+        if (planeDetectionMode === "MANUAL" && anchor) {
+          planeSelectorRef.current?.handleAnchorRemoved(anchor);
+        }
+      } catch (error) {
+        console.error("[Studio] handleAnchorRemoved failed:", error);
+      }
+    },
+    [planeDetectionMode]
+  );
+
+  const handlePlaneSelected = useCallback(() => {
+    onPlaneSelected?.();
+  }, [onPlaneSelected]);
+
+  // ViroARPlaneSelector.onPlaneDetected must return a boolean (accept the plane).
+  const handlePlaneDetectedForSelector = useCallback(() => {
+    onPlaneDetected?.();
+    return true;
+  }, [onPlaneDetected]);
+
   const renderAssets = () => {
     if (isQuest) {
       if (planeDetectionMode !== "NONE") {
@@ -510,9 +646,12 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
     if (planeDetectionMode === "MANUAL") {
       return (
         <ViroARPlaneSelector
+          ref={planeSelectorRef}
           minHeight={0.1}
           minWidth={0.1}
           alignment={planeAlignment}
+          onPlaneDetected={handlePlaneDetectedForSelector}
+          onPlaneSelected={handlePlaneSelected}
         >
           {renderedPlaneAssets}
         </ViroARPlaneSelector>
@@ -543,7 +682,7 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
       <StudioSounds manager={soundManagerRef.current!} />
       {assets.length === 0 && (
         <ViroText
-          text="No assets to display"
+          text={noAssetsMessage ?? "No assets to display"}
           position={[0, 0, -2]}
           style={{
             fontFamily: "Arial",
@@ -559,5 +698,15 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
   if (isQuest) {
     return <ViroScene {...physicsProps}>{children}</ViroScene>;
   }
-  return <ViroARScene {...physicsProps}>{children}</ViroARScene>;
+  return (
+    <ViroARScene
+      {...physicsProps}
+      {...(anchorDetectionTypes != null ? { anchorDetectionTypes } : {})}
+      onAnchorFound={handleAnchorFound}
+      onAnchorUpdated={handleAnchorUpdated}
+      onAnchorRemoved={handleAnchorRemoved}
+    >
+      {children}
+    </ViroARScene>
+  );
 };

package/components/Studio/StudioSceneErrorBoundary.tsx

@@ -0,0 +1,48 @@
+import { Component, ErrorInfo, ReactNode } from "react";
+
+interface Props {
+  children: ReactNode;
+  onError?: (error: Error) => void;
+  renderError?: (error: Error) => ReactNode;
+  sceneId?: string;
+}
+
+interface State {
+  hasError: boolean;
+  error: Error | null;
+}
+
+/**
+ * Catches render/lifecycle errors in the Studio scene tree so a bad asset or a
+ * node-factory throw can't take down the host app. Always reports via onError;
+ * renders renderError(error) if provided, else nothing (no built-in UI).
+ *
+ * AR-only in effect: on Quest, ViroXRSceneNavigator forwards to a separate
+ * React root (VRActivity), so scene errors there are outside this boundary.
+ * Native and async errors are also out of a React boundary's reach; async
+ * scene-load failures route through onError in StudioSceneNavigator instead.
+ */
+export class StudioSceneErrorBoundary extends Component<Props, State> {
+  public state: State = { hasError: false, error: null };
+
+  public static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  public componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    this.props.onError?.(error);
+    console.error(
+      "[Studio] Scene render error:",
+      error,
+      this.props.sceneId,
+      errorInfo.componentStack
+    );
+  }
+
+  public render() {
+    if (this.state.hasError && this.state.error) {
+      return this.props.renderError?.(this.state.error) ?? null;
+    }
+    return this.props.children;
+  }
+}

package/components/Studio/StudioSceneNavigator.tsx

@@ -1,5 +1,12 @@
 import * as React from "react";
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from "react";
 import { ActivityIndicator, StyleSheet, View, ViewStyle } from "react-native";
 import { ViroARScene } from "../AR/ViroARScene";
 import { ViroScene } from "../ViroScene";
@@ -9,23 +16,55 @@ import { registerSceneAnimations } from "./domain/animationRegistry";
 import { registerStudioMaterialsForAssets } from "./domain/studioMaterials";
 import { StudioVariableStore } from "./domain/variableStore";
 import { StudioARScene } from "./StudioARScene";
+import { StudioSceneErrorBoundary } from "./StudioSceneErrorBoundary";
 import { StudioProjectApiResponse, StudioSceneResponse } from "./types";
 import { VRTStudioModule } from "./VRTStudioModule";
 
-function LoadingARScene() { return <ViroARScene />; }
-function LoadingVRScene() { return <ViroScene />; }
+function LoadingARScene() {
+  return <ViroARScene />;
+}
+function LoadingVRScene() {
+  return <ViroScene />;
+}
+
+type ViroOcclusionMode = "peopleOnly" | "depthBased" | undefined;
+
+function mapOcclusionMode(
+  dbValue: string | null | undefined
+): ViroOcclusionMode {
+  switch (dbValue) {
+    case "PEOPLEONLY":
+      return "peopleOnly";
+    case "DEPTHBASED":
+      return "depthBased";
+    default:
+      return undefined;
+  }
+}
 
 const styles = StyleSheet.create({
   loader: {
     position: "absolute",
-    top: 0, left: 0, right: 0, bottom: 0,
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
     justifyContent: "center",
     alignItems: "center",
     backgroundColor: "#000000",
   },
 });
 
-interface StudioSceneNavigatorProps {
+/** Imperative handle exposed via ref. */
+export interface StudioSceneNavigatorHandle {
+  /** Screenshots the AR renderer. Resolves `{ success: false }` (no-op) on Quest. */
+  takeScreenshot: (
+    fileName: string,
+    saveToCameraRoll: boolean
+  ) => Promise<{ success: boolean; url?: string; errorCode?: string }>;
+}
+
+export interface StudioSceneNavigatorProps {
   /**
    * UUID of a specific scene to load. If omitted, the navigator fetches the
    * project configured in the app manifest and uses its opening scene.
@@ -38,6 +77,22 @@ interface StudioSceneNavigatorProps {
   onError?: (err: Error) => void;
   onSceneChange?: (sceneId: string, sceneName: string) => void;
   onExitViro?: () => void;
+  /** Fired after the scene is fetched and parsed, before it is pushed. */
+  onSceneLoaded?: (sceneData: StudioSceneResponse) => void;
+  /** Threaded to the initial scene's StudioARScene (initial scene only). */
+  onPlaneDetected?: () => void;
+  onPlaneSelected?: () => void;
+  noAssetsMessage?: string;
+  /**
+   * Opt-in overlay shown until the scene mounts. Omit to render nothing on AR
+   * during load (the camera feed); Quest falls back to a built-in spinner.
+   */
+  loadingView?: React.ReactNode;
+  /**
+   * Opt-in UI for a caught render error. The boundary always catches and calls
+   * `onError`; when this is omitted it renders nothing.
+   */
+  renderError?: (error: Error) => React.ReactNode;
 }
 
 /**
@@ -53,19 +108,33 @@ interface StudioSceneNavigatorProps {
  * ready. This means VRActivity always launches with the actual content scene
  * as its initial scene, avoiding the LoadingVRScene → replace timing race.
  */
-export function StudioSceneNavigator({
-  sceneId,
-  worldAlignment = "Gravity",
-  autofocus = true,
-  style,
-  onSceneReady,
-  onError,
-  onSceneChange,
-  onExitViro,
-}: StudioSceneNavigatorProps) {
+export const StudioSceneNavigator = forwardRef<
+  StudioSceneNavigatorHandle,
+  StudioSceneNavigatorProps
+>(function StudioSceneNavigator(
+  {
+    sceneId,
+    worldAlignment = "Gravity",
+    autofocus = true,
+    style,
+    onSceneReady,
+    onError,
+    onSceneChange,
+    onExitViro,
+    onSceneLoaded,
+    onPlaneDetected,
+    onPlaneSelected,
+    noAssetsMessage,
+    loadingView,
+    renderError,
+  },
+  ref
+) {
   const navigatorRef = useRef<any>(null);
   const loadedSceneIdRef = useRef<string | null>(null);
 
+  const [isSceneReady, setIsSceneReady] = useState(false);
+
   // Session-scoped variable store: outlives every scene push, resets when the
   // navigator (= the AR/VR session) unmounts.
   const variableStoreRef = useRef<StudioVariableStore | null>(null);
@@ -82,13 +151,55 @@ export function StudioSceneNavigator({
   const onSceneReadyRef = useRef(onSceneReady);
   const onErrorRef = useRef(onError);
   const onSceneChangeRef = useRef(onSceneChange);
+  const onSceneLoadedRef = useRef(onSceneLoaded);
+  const onPlaneDetectedRef = useRef(onPlaneDetected);
+  const onPlaneSelectedRef = useRef(onPlaneSelected);
+  const noAssetsMessageRef = useRef(noAssetsMessage);
   onSceneReadyRef.current = onSceneReady;
   onErrorRef.current = onError;
   onSceneChangeRef.current = onSceneChange;
+  onSceneLoadedRef.current = onSceneLoaded;
+  onPlaneDetectedRef.current = onPlaneDetected;
+  onPlaneSelectedRef.current = onPlaneSelected;
+  noAssetsMessageRef.current = noAssetsMessage;
+
+  // Stable so passProps stays referentially steady across renders. Idempotent,
+  // so StrictMode's dev double-invoke of StudioARScene's onReady effect is safe.
+  const handleSceneReady = useCallback(() => {
+    setIsSceneReady(true);
+    onSceneReadyRef.current?.();
+  }, []);
 
   // On Quest: holds the resolved scene entry. ViroXRSceneNavigator is not
   // rendered until this is non-null, so VRActivity always launches into content.
-  const [vrSceneEntry, setVrSceneEntry] = useState<{ scene: any; passProps?: any } | null>(null);
+  const [vrSceneEntry, setVrSceneEntry] = useState<{
+    scene: any;
+    passProps?: any;
+  } | null>(null);
+
+  // Host config derived from the loaded scene; native setters apply post-mount,
+  // so setting these after the navigator mounts is fine.
+  const [occlusionMode, setOcclusionMode] =
+    useState<ViroOcclusionMode>(undefined);
+  const [numberOfTrackedImages, setNumberOfTrackedImages] = useState<
+    number | undefined
+  >(undefined);
+
+  useImperativeHandle(
+    ref,
+    (): StudioSceneNavigatorHandle => ({
+      takeScreenshot: (fileName, saveToCameraRoll) => {
+        // On AR the handle is the ViroARSceneNavigator instance (has
+        // arSceneNavigator.takeScreenshot); on Quest it's a bridge without it.
+        const nav = navigatorRef.current?.arSceneNavigator;
+        if (typeof nav?.takeScreenshot !== "function") {
+          return Promise.resolve({ success: false });
+        }
+        return nav.takeScreenshot(fileName, saveToCameraRoll);
+      },
+    }),
+    []
+  );
 
   const resolveSceneId = useCallback(async (): Promise<string> => {
     if (sceneId) return sceneId;
@@ -101,7 +212,9 @@ export function StudioSceneNavigator({
       throw new Error("rvGetProject returned no data");
     }
 
-    const { project } = JSON.parse(projectResult.data) as StudioProjectApiResponse;
+    const { project } = JSON.parse(
+      projectResult.data
+    ) as StudioProjectApiResponse;
 
     if (project.opening_scene?.id) {
       return project.opening_scene.id;
@@ -114,7 +227,9 @@ export function StudioSceneNavigator({
 
   const loadScene = useCallback(
     async (isCancelled: () => boolean) => {
-      await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+      await new Promise<void>((resolve) =>
+        requestAnimationFrame(() => resolve())
+      );
       if (isCancelled()) return;
 
       const resolvedSceneId = await resolveSceneId();
@@ -136,11 +251,20 @@ export function StudioSceneNavigator({
 
       loadedSceneIdRef.current = resolvedSceneId;
 
-      // On Quest: pre-register animations and materials before VRActivity launches.
-      // This mirrors the module-level registration pattern used by XRSceneContent —
-      // native registrations complete before any Viro components mount, eliminating
-      // the race between registerAnimations/createMaterials native calls and the
-      // Fabric commit that creates those components.
+      const triggerImageCount = sceneData.assets.filter(
+        (a) => !!a.trigger_image_url
+      ).length;
+      setNumberOfTrackedImages(
+        triggerImageCount > 0 ? Math.min(triggerImageCount, 5) : undefined
+      );
+      setOcclusionMode(mapOcclusionMode(sceneData.project?.occlusion_mode));
+
+      onSceneLoadedRef.current?.(sceneData);
+
+      // On Quest, pre-register animations and materials before VRActivity
+      // launches so the native registrations land before any Viro component
+      // mounts; otherwise registerAnimations/createMaterials races the Fabric
+      // commit that creates those components.
       if (isQuest) {
         registerSceneAnimations(sceneData.animations);
         registerStudioMaterialsForAssets(sceneData.assets);
@@ -150,21 +274,24 @@ export function StudioSceneNavigator({
         scene: StudioARScene,
         passProps: {
           sceneData,
-          onReady: onSceneReadyRef.current,
+          onReady: handleSceneReady,
           onSceneChange: onSceneChangeRef.current,
+          onPlaneDetected: onPlaneDetectedRef.current,
+          onPlaneSelected: onPlaneSelectedRef.current,
+          noAssetsMessage: noAssetsMessageRef.current,
           variableStore: variableStoreRef.current,
         },
       };
 
       if (isQuest) {
-        // On Quest: setting vrSceneEntry triggers ViroXRSceneNavigator to mount
-        // with StudioARScene as vrInitialScene — VRActivity gets content immediately.
+        // Setting vrSceneEntry mounts ViroXRSceneNavigator with StudioARScene as
+        // vrInitialScene, so VRActivity launches straight into content.
         setVrSceneEntry(entry);
       } else {
         navigatorRef.current?.arSceneNavigator?.push(entry);
       }
     },
-    [resolveSceneId]
+    [resolveSceneId, handleSceneReady]
   );
 
   useEffect(() => {
@@ -179,28 +306,46 @@ export function StudioSceneNavigator({
       else console.error("[Studio] Failed to load scene:", err);
     });
 
-    return () => { cancelled = true; };
+    return () => {
+      cancelled = true;
+    };
   }, [sceneId, loadScene]);
 
-  // On Quest: show a spinner until scene data is ready, then mount
-  // ViroXRSceneNavigator (which launches VRActivity with content immediately).
+  // Quest has no camera passthrough, so during load it always needs something
+  // on screen: the caller's loadingView, else a built-in spinner. (AR shows the
+  // live camera, so its overlay stays opt-in.)
   if (isQuest && !vrSceneEntry) {
     return (
       <View style={styles.loader}>
-        <ActivityIndicator size="large" color="#ffffff" />
+        {loadingView ?? <ActivityIndicator size="large" color="#ffffff" />}
       </View>
     );
   }
 
   return (
-    <ViroXRSceneNavigator
-      ref={navigatorRef}
-      arInitialScene={{ scene: LoadingARScene }}
-      vrInitialScene={vrSceneEntry ?? { scene: LoadingVRScene }}
-      worldAlignment={worldAlignment}
-      autofocus={autofocus}
-      onExitViro={onExitViro}
-      style={style ?? StyleSheet.absoluteFill}
-    />
+    <StudioSceneErrorBoundary
+      sceneId={sceneId}
+      onError={onError}
+      renderError={renderError}
+    >
+      <View style={style ?? StyleSheet.absoluteFill}>
+        <ViroXRSceneNavigator
+          ref={navigatorRef}
+          arInitialScene={{ scene: LoadingARScene }}
+          vrInitialScene={vrSceneEntry ?? { scene: LoadingVRScene }}
+          worldAlignment={worldAlignment}
+          autofocus={autofocus}
+          numberOfTrackedImages={numberOfTrackedImages}
+          occlusionMode={occlusionMode}
+          onExitViro={onExitViro}
+          style={StyleSheet.absoluteFill}
+        />
+        {/* Absolutely filled so the overlay covers the navigator instead of
+            taking flow space beneath it. */}
+        {!isSceneReady && loadingView && (
+          <View style={StyleSheet.absoluteFill}>{loadingView}</View>
+        )}
+      </View>
+    </StudioSceneErrorBoundary>
   );
-}
+});