@reactvision/react-viro 2.57.2 → 2.57.4

package/components/Studio/types.ts

@@ -149,7 +149,7 @@ export interface StudioApiRequestOutcome {
  */
 export type StudioApiRequestExecutor = (
   functionId: string,
-  variables: Record<string, boolean | number | string>,
+  variables: Record<string, boolean | number | string>
 ) => Promise<StudioApiRequestOutcome>;
 
 export interface StudioSceneFunction {
@@ -267,13 +267,7 @@ export interface StudioAnimation {
   properties: Record<string, unknown>; // Viro keyframe format
   duration_ms: number | null;
   delay_ms: number | null;
-  easing:
-    | "Linear"
-    | "EaseIn"
-    | "EaseOut"
-    | "EaseInEaseOut"
-    | "Bounce"
-    | null;
+  easing: "Linear" | "EaseIn" | "EaseOut" | "EaseInEaseOut" | "Bounce" | null;
   loop: boolean;
   interruptible: boolean;
   on_start_function: string | null;
@@ -326,6 +320,7 @@ export interface StudioSceneResponse {
   functions: StudioSceneFunction[];
   /** Absent in responses from backends predating the Variables feature. */
   variables?: StudioSceneVariable[];
+  is_free_tier?: boolean;
   meta: { request_id: string };
 }
 

package/components/Utilities/ViroVersion.ts

@@ -1 +1 @@
-export const VIRO_VERSION = "2.57.2";
+export const VIRO_VERSION = "2.57.4";

package/components/ViroXRSceneNavigator.tsx

@@ -75,6 +75,8 @@ type Props = ViewProps & {
   autofocus?: boolean;
   videoQuality?: "High" | "Low";
   numberOfTrackedImages?: number;
+  /** AR depth/people occlusion. Flows via ...rest to ViroARSceneNavigator. */
+  occlusionMode?: "peopleOnly" | "depthBased";
 
   // ── Forwarded to ViroVRSceneNavigator (Quest path via bridge) ──────────────
   vrModeEnabled?: boolean;

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

@@ -149,9 +149,17 @@ type Props = ViewProps & {
     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.
+     *
+     * 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/dist/components/Studio/StudioARScene.d.ts

@@ -7,6 +7,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;
 }

package/dist/components/Studio/StudioARScene.js

@@ -75,7 +75,7 @@ const StudioARScene = (props) => {
 };
 exports.StudioARScene = StudioARScene;
 const StudioARSceneInner = (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;
     // ─── Sequence scheduler ───────────────────────────────────────────────────
     // One per scene. Drives WAIT steps; cancelled on unmount and on navigation so
@@ -169,6 +169,38 @@ const StudioARSceneInner = (props) => {
     // ─── Animation runtime state ──────────────────────────────────────────────
     const [animOverrides, setAnimOverrides] = (0, react_1.useState)({});
     const [loadedAssetIds, setLoadedAssetIds] = (0, react_1.useState)({});
+    // ─── 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] = (0, react_1.useState)({});
+    const dragTimersRef = (0, react_1.useRef)(new Map());
+    const notifyPhysicsDrag = (0, react_1.useCallback)((assetId) => {
+        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 = (0, react_1.useCallback)((assetId) => !!dragActiveByAssetId[assetId], [dragActiveByAssetId]);
+    (0, react_1.useEffect)(() => {
+        const timers = dragTimersRef.current;
+        return () => {
+            timers.forEach((timer) => clearTimeout(timer));
+            timers.clear();
+        };
+    }, []);
     const handleAssetLoaded = (0, react_1.useCallback)((assetId) => {
         setLoadedAssetIds((prev) => prev[assetId] ? prev : { ...prev, [assetId]: true });
     }, []);
@@ -334,7 +366,7 @@ const StudioARSceneInner = (props) => {
                     return null;
                 }
             }
-            return (0, viroNodeFactory_1.createNode)(asset, sceneNavigator, animations, scene, (id, key) => triggerAnimationRef.current(id, key), animationStates, handleAssetLoaded, getCollisionHandler(asset.id), handleSceneChange, runtimeCtx);
+            return (0, viroNodeFactory_1.createNode)(asset, sceneNavigator, animations, scene, (id, key) => triggerAnimationRef.current(id, key), animationStates, handleAssetLoaded, getCollisionHandler(asset.id), isDragActive, notifyPhysicsDrag, handleSceneChange, runtimeCtx);
         })
             .filter(Boolean);
     }, [
@@ -344,6 +376,8 @@ const StudioARSceneInner = (props) => {
         animationStates,
         handleAssetLoaded,
         getCollisionHandler,
+        isDragActive,
+        notifyPhysicsDrag,
         maxModels,
         handleSceneChange,
         runtimeCtx,
@@ -356,7 +390,7 @@ const StudioARSceneInner = (props) => {
             const targetName = urlToTargetName.get(asset.trigger_image_url);
             if (!targetName)
                 return null;
-            const node = (0, viroNodeFactory_1.createNode)(asset, sceneNavigator, animations, scene, (id, key) => triggerAnimationRef.current(id, key), animationStates, handleAssetLoaded, getCollisionHandler(asset.id), handleSceneChange, runtimeCtx);
+            const node = (0, viroNodeFactory_1.createNode)(asset, sceneNavigator, animations, scene, (id, key) => triggerAnimationRef.current(id, key), animationStates, handleAssetLoaded, getCollisionHandler(asset.id), isDragActive, notifyPhysicsDrag, handleSceneChange, runtimeCtx);
             if (!node)
                 return null;
             return (<ViroARImageMarker_1.ViroARImageMarker key={asset.id} target={targetName}>
@@ -372,12 +406,71 @@ const StudioARSceneInner = (props) => {
         animationStates,
         handleAssetLoaded,
         getCollisionHandler,
+        isDragActive,
+        notifyPhysicsDrag,
         handleSceneChange,
         runtimeCtx,
     ]);
     // ─── Plane detection (AR only) ────────────────────────────────────────────
     const planeDetectionMode = (scene.plane_detection ?? "NONE").toUpperCase();
     const planeAlignment = (scene.plane_direction ?? "Horizontal");
+    // Native plane anchor types for ViroARScene (lowercase matches Viro defaults).
+    const anchorDetectionTypes = (0, react_1.useMemo)(() => {
+        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 = (0, react_1.useRef)(null);
+    const handleAnchorFound = (0, react_1.useCallback)((anchor) => {
+        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 = (0, react_1.useCallback)((anchor) => {
+        try {
+            if (planeDetectionMode === "MANUAL") {
+                planeSelectorRef.current?.handleAnchorUpdated(anchor);
+            }
+        }
+        catch (error) {
+            console.error("[Studio] handleAnchorUpdated failed:", error);
+        }
+    }, [planeDetectionMode]);
+    const handleAnchorRemoved = (0, react_1.useCallback)((anchor) => {
+        try {
+            if (planeDetectionMode === "MANUAL" && anchor) {
+                planeSelectorRef.current?.handleAnchorRemoved(anchor);
+            }
+        }
+        catch (error) {
+            console.error("[Studio] handleAnchorRemoved failed:", error);
+        }
+    }, [planeDetectionMode]);
+    const handlePlaneSelected = (0, react_1.useCallback)(() => {
+        onPlaneSelected?.();
+    }, [onPlaneSelected]);
+    // ViroARPlaneSelector.onPlaneDetected must return a boolean (accept the plane).
+    const handlePlaneDetectedForSelector = (0, react_1.useCallback)(() => {
+        onPlaneDetected?.();
+        return true;
+    }, [onPlaneDetected]);
     const renderAssets = () => {
         if (ViroPlatform_1.isQuest) {
             if (planeDetectionMode !== "NONE") {
@@ -391,7 +484,7 @@ const StudioARSceneInner = (props) => {
         </ViroARPlane_1.ViroARPlane>);
         }
         if (planeDetectionMode === "MANUAL") {
-            return (<ViroARPlaneSelector_1.ViroARPlaneSelector minHeight={0.1} minWidth={0.1} alignment={planeAlignment}>
+            return (<ViroARPlaneSelector_1.ViroARPlaneSelector ref={planeSelectorRef} minHeight={0.1} minWidth={0.1} alignment={planeAlignment} onPlaneDetected={handlePlaneDetectedForSelector} onPlaneSelected={handlePlaneSelected}>
           {renderedPlaneAssets}
         </ViroARPlaneSelector_1.ViroARPlaneSelector>);
         }
@@ -412,7 +505,7 @@ const StudioARSceneInner = (props) => {
       {renderAssets()}
       {renderedImageTriggeredAssets}
       <StudioSounds_1.StudioSounds manager={soundManagerRef.current}/>
-      {assets.length === 0 && (<ViroText_1.ViroText text="No assets to display" position={[0, 0, -2]} style={{
+      {assets.length === 0 && (<ViroText_1.ViroText text={noAssetsMessage ?? "No assets to display"} position={[0, 0, -2]} style={{
                 fontFamily: "Arial",
                 fontSize: 16,
                 color: "#CCCCCC",
@@ -422,5 +515,7 @@ const StudioARSceneInner = (props) => {
     if (ViroPlatform_1.isQuest) {
         return <ViroScene_1.ViroScene {...physicsProps}>{children}</ViroScene_1.ViroScene>;
     }
-    return <ViroARScene_1.ViroARScene {...physicsProps}>{children}</ViroARScene_1.ViroARScene>;
+    return (<ViroARScene_1.ViroARScene {...physicsProps} {...(anchorDetectionTypes != null ? { anchorDetectionTypes } : {})} onAnchorFound={handleAnchorFound} onAnchorUpdated={handleAnchorUpdated} onAnchorRemoved={handleAnchorRemoved}>
+      {children}
+    </ViroARScene_1.ViroARScene>);
 };

package/dist/components/Studio/StudioSceneErrorBoundary.d.ts

@@ -0,0 +1,28 @@
+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 declare class StudioSceneErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};

package/dist/components/Studio/StudioSceneErrorBoundary.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StudioSceneErrorBoundary = void 0;
+const react_1 = require("react");
+/**
+ * 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.
+ */
+class StudioSceneErrorBoundary extends react_1.Component {
+    state = { hasError: false, error: null };
+    static getDerivedStateFromError(error) {
+        return { hasError: true, error };
+    }
+    componentDidCatch(error, errorInfo) {
+        this.props.onError?.(error);
+        console.error("[Studio] Scene render error:", error, this.props.sceneId, errorInfo.componentStack);
+    }
+    render() {
+        if (this.state.hasError && this.state.error) {
+            return this.props.renderError?.(this.state.error) ?? null;
+        }
+        return this.props.children;
+    }
+}
+exports.StudioSceneErrorBoundary = StudioSceneErrorBoundary;

package/dist/components/Studio/StudioSceneNavigator.d.ts

@@ -1,6 +1,16 @@
 import * as React from "react";
 import { ViewStyle } from "react-native";
-interface StudioSceneNavigatorProps {
+import { StudioSceneResponse } from "./types";
+/** 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.
@@ -13,6 +23,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;
 }
 /**
  * Cross-reality Studio scene navigator. Renders a Studio-authored scene on
@@ -27,5 +53,4 @@ interface StudioSceneNavigatorProps {
  * ready. This means VRActivity always launches with the actual content scene
  * as its initial scene, avoiding the LoadingVRScene → replace timing race.
  */
-export declare function StudioSceneNavigator({ sceneId, worldAlignment, autofocus, style, onSceneReady, onError, onSceneChange, onExitViro, }: StudioSceneNavigatorProps): React.JSX.Element;
-export {};
+export declare const StudioSceneNavigator: React.ForwardRefExoticComponent<StudioSceneNavigatorProps & React.RefAttributes<StudioSceneNavigatorHandle>>;

package/dist/components/Studio/StudioSceneNavigator.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StudioSceneNavigator = StudioSceneNavigator;
+exports.StudioSceneNavigator = void 0;
 const React = __importStar(require("react"));
 const react_1 = require("react");
 const react_native_1 = require("react-native");
@@ -45,13 +45,31 @@ const animationRegistry_1 = require("./domain/animationRegistry");
 const studioMaterials_1 = require("./domain/studioMaterials");
 const variableStore_1 = require("./domain/variableStore");
 const StudioARScene_1 = require("./StudioARScene");
+const StudioSceneErrorBoundary_1 = require("./StudioSceneErrorBoundary");
 const VRTStudioModule_1 = require("./VRTStudioModule");
-function LoadingARScene() { return <ViroARScene_1.ViroARScene />; }
-function LoadingVRScene() { return <ViroScene_1.ViroScene />; }
+function LoadingARScene() {
+    return <ViroARScene_1.ViroARScene />;
+}
+function LoadingVRScene() {
+    return <ViroScene_1.ViroScene />;
+}
+function mapOcclusionMode(dbValue) {
+    switch (dbValue) {
+        case "PEOPLEONLY":
+            return "peopleOnly";
+        case "DEPTHBASED":
+            return "depthBased";
+        default:
+            return undefined;
+    }
+}
 const styles = react_native_1.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",
@@ -70,9 +88,10 @@ const styles = react_native_1.StyleSheet.create({
  * ready. This means VRActivity always launches with the actual content scene
  * as its initial scene, avoiding the LoadingVRScene → replace timing race.
  */
-function StudioSceneNavigator({ sceneId, worldAlignment = "Gravity", autofocus = true, style, onSceneReady, onError, onSceneChange, onExitViro, }) {
+exports.StudioSceneNavigator = (0, react_1.forwardRef)(function StudioSceneNavigator({ sceneId, worldAlignment = "Gravity", autofocus = true, style, onSceneReady, onError, onSceneChange, onExitViro, onSceneLoaded, onPlaneDetected, onPlaneSelected, noAssetsMessage, loadingView, renderError, }, ref) {
     const navigatorRef = (0, react_1.useRef)(null);
     const loadedSceneIdRef = (0, react_1.useRef)(null);
+    const [isSceneReady, setIsSceneReady] = (0, react_1.useState)(false);
     // Session-scoped variable store: outlives every scene push, resets when the
     // navigator (= the AR/VR session) unmounts.
     const variableStoreRef = (0, react_1.useRef)(null);
@@ -88,12 +107,41 @@ function StudioSceneNavigator({ sceneId, worldAlignment = "Gravity", autofocus =
     const onSceneReadyRef = (0, react_1.useRef)(onSceneReady);
     const onErrorRef = (0, react_1.useRef)(onError);
     const onSceneChangeRef = (0, react_1.useRef)(onSceneChange);
+    const onSceneLoadedRef = (0, react_1.useRef)(onSceneLoaded);
+    const onPlaneDetectedRef = (0, react_1.useRef)(onPlaneDetected);
+    const onPlaneSelectedRef = (0, react_1.useRef)(onPlaneSelected);
+    const noAssetsMessageRef = (0, react_1.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 = (0, react_1.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] = (0, react_1.useState)(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] = (0, react_1.useState)(undefined);
+    const [numberOfTrackedImages, setNumberOfTrackedImages] = (0, react_1.useState)(undefined);
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        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 = (0, react_1.useCallback)(async () => {
         if (sceneId)
             return sceneId;
@@ -135,11 +183,14 @@ function StudioSceneNavigator({ sceneId, worldAlignment = "Gravity", autofocus =
         if (isCancelled())
             return;
         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 (ViroPlatform_1.isQuest) {
             (0, animationRegistry_1.registerSceneAnimations)(sceneData.animations);
             (0, studioMaterials_1.registerStudioMaterialsForAssets)(sceneData.assets);
@@ -148,20 +199,23 @@ function StudioSceneNavigator({ sceneId, worldAlignment = "Gravity", autofocus =
             scene: StudioARScene_1.StudioARScene,
             passProps: {
                 sceneData,
-                onReady: onSceneReadyRef.current,
+                onReady: handleSceneReady,
                 onSceneChange: onSceneChangeRef.current,
+                onPlaneDetected: onPlaneDetectedRef.current,
+                onPlaneSelected: onPlaneSelectedRef.current,
+                noAssetsMessage: noAssetsMessageRef.current,
                 variableStore: variableStoreRef.current,
             },
         };
         if (ViroPlatform_1.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]);
     (0, react_1.useEffect)(() => {
         let cancelled = false;
         const isCancelled = () => cancelled;
@@ -175,14 +229,24 @@ function StudioSceneNavigator({ sceneId, worldAlignment = "Gravity", autofocus =
             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 (ViroPlatform_1.isQuest && !vrSceneEntry) {
         return (<react_native_1.View style={styles.loader}>
-        <react_native_1.ActivityIndicator size="large" color="#ffffff"/>
+        {loadingView ?? <react_native_1.ActivityIndicator size="large" color="#ffffff"/>}
       </react_native_1.View>);
     }
-    return (<ViroXRSceneNavigator_1.ViroXRSceneNavigator ref={navigatorRef} arInitialScene={{ scene: LoadingARScene }} vrInitialScene={vrSceneEntry ?? { scene: LoadingVRScene }} worldAlignment={worldAlignment} autofocus={autofocus} onExitViro={onExitViro} style={style ?? react_native_1.StyleSheet.absoluteFill}/>);
-}
+    return (<StudioSceneErrorBoundary_1.StudioSceneErrorBoundary sceneId={sceneId} onError={onError} renderError={renderError}>
+      <react_native_1.View style={style ?? react_native_1.StyleSheet.absoluteFill}>
+        <ViroXRSceneNavigator_1.ViroXRSceneNavigator ref={navigatorRef} arInitialScene={{ scene: LoadingARScene }} vrInitialScene={vrSceneEntry ?? { scene: LoadingVRScene }} worldAlignment={worldAlignment} autofocus={autofocus} numberOfTrackedImages={numberOfTrackedImages} occlusionMode={occlusionMode} onExitViro={onExitViro} style={react_native_1.StyleSheet.absoluteFill}/>
+        {/* Absolutely filled so the overlay covers the navigator instead of
+            taking flow space beneath it. */}
+        {!isSceneReady && loadingView && (<react_native_1.View style={react_native_1.StyleSheet.absoluteFill}>{loadingView}</react_native_1.View>)}
+      </react_native_1.View>
+    </StudioSceneErrorBoundary_1.StudioSceneErrorBoundary>);
+});

package/dist/components/Studio/VRTStudioModule.d.ts

@@ -3,6 +3,16 @@ export interface StudioModuleResult {
     data?: string;
     error?: string;
 }
+/**
+ * @internal — session auth for first-party apps (e.g. StudioGo). Deliberately
+ * not exported from the package root; the server's org-membership check is the
+ * real boundary.
+ */
+export interface StudioSessionConfig {
+    baseUrl: string;
+    accessToken: string;
+    clientTag?: string;
+}
 export declare const VRTStudioModule: {
     rvGetScene: (sceneId: string) => Promise<StudioModuleResult>;
     /**
@@ -18,4 +28,11 @@ export declare const VRTStudioModule: {
      * `data` is the proxy's outcome envelope JSON.
      */
     rvStudioApiRequest: (bodyJson: string) => Promise<StudioModuleResult>;
+    /**
+     * @internal — sets/clears an internal session so the fetch methods use
+     * `${baseUrl}/functions/v1/...` with `Authorization: Bearer` (and no
+     * `x-api-key`) instead of the manifest RVApiKey. Pass null to revert to
+     * API-key mode. Session auth wins over any manifest key.
+     */
+    rvSetStudioSession: (config: StudioSessionConfig | null) => Promise<void>;
 };

package/dist/components/Studio/VRTStudioModule.js

@@ -38,4 +38,18 @@ exports.VRTStudioModule = {
             return Promise.resolve(NOT_AVAILABLE);
         return native.rvStudioApiRequest(bodyJson);
     },
+    /**
+     * @internal — sets/clears an internal session so the fetch methods use
+     * `${baseUrl}/functions/v1/...` with `Authorization: Bearer` (and no
+     * `x-api-key`) instead of the manifest RVApiKey. Pass null to revert to
+     * API-key mode. Session auth wins over any manifest key.
+     */
+    rvSetStudioSession: (config) => {
+        // Method-level guard, not just `!native`: JS can OTA ahead of the native
+        // binary, so an older build has VRTStudio present but without this (newer)
+        // method. No-op then, and viro stays in manifest API-key mode.
+        if (typeof native?.rvSetStudioSession !== "function")
+            return Promise.resolve();
+        return native.rvSetStudioSession(config);
+    },
 };

package/dist/components/Studio/domain/dragConfiguration.d.ts

@@ -1,5 +1,5 @@
 import { StudioAsset, StudioSceneMeta } from "../types";
-export type DragType = "FixedToWorld" | "FixedToPlane" | undefined;
+export type DragType = "FixedToPlane" | "FixedDistance" | undefined;
 export type DragPlane = {
     planePoint: [number, number, number];
     planeNormal: [number, number, number];
@@ -7,8 +7,10 @@ export type DragPlane = {
 };
 export declare class DragConfiguration {
     /**
-     * Chooses FixedToPlane when the scene uses plane detection, FixedToWorld otherwise.
-     * Returns undefined if the asset is not draggable.
+     * FixedToPlane when the scene uses plane detection; otherwise FixedDistance,
+     * which keeps the object at its grab distance and follows the finger.
+     * (FixedToWorld raycast-snapped objects toward the camera on drag start, so
+     * they appeared to grow and were hard to place.) undefined if not draggable.
      */
     static getDragType(asset: StudioAsset, scene: StudioSceneMeta | null): DragType;
     /**

package/dist/components/Studio/domain/dragConfiguration.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DragConfiguration = void 0;
 class DragConfiguration {
     /**
-     * Chooses FixedToPlane when the scene uses plane detection, FixedToWorld otherwise.
-     * Returns undefined if the asset is not draggable.
+     * FixedToPlane when the scene uses plane detection; otherwise FixedDistance,
+     * which keeps the object at its grab distance and follows the finger.
+     * (FixedToWorld raycast-snapped objects toward the camera on drag start, so
+     * they appeared to grow and were hard to place.) undefined if not draggable.
      */
     static getDragType(asset, scene) {
         if (!asset.is_draggable)
@@ -13,7 +15,7 @@ class DragConfiguration {
         if (planeDetection === "AUTOMATIC" || planeDetection === "MANUAL") {
             return "FixedToPlane";
         }
-        return "FixedToWorld";
+        return "FixedDistance";
     }
     /**
      * Returns a drag plane that passes through the object's current position,

package/dist/components/Studio/domain/materialConfig.d.ts

@@ -1,6 +1,5 @@
 /**
  * Studio material_config parsing and Viro material definition building.
- * Ported from studio-go/domain/materialConfig.ts — no zod dependency.
  */
 type ShaderModifierStage = {
     uniforms?: string;