@reactvision/react-viro 2.56.0 → 2.57.2

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.

package/components/AR/ViroARPlane.tsx

@@ -59,10 +59,7 @@ export class ViroARPlane extends ViroBase<Props> {
   };
 
   render() {
-    if (isQuest) {
-      console.warn("[Viro] ViroARPlane is not supported on Quest and will not render.");
-      return null;
-    }
+    // Supported on Quest via XR_FB_scene plane anchors (room model). No longer gated.
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARPlane", this.props);
 

package/components/AR/ViroARPlaneSelector.tsx

@@ -417,10 +417,7 @@ export class ViroARPlaneSelector extends React.Component<Props, State> {
   // ---------------------------------------------------------------------------
 
   render() {
-    if (isQuest) {
-      console.warn("[Viro] ViroARPlaneSelector is not supported on Quest and will not render.");
-      return null;
-    }
+    // Supported on Quest via XR_FB_scene plane anchors (room model). No longer gated.
     return <ViroNode>{this._renderPlanes()}</ViroNode>;
   }
 
@@ -541,6 +538,14 @@ ViroMaterials.createMaterials({
     diffuseColor: "rgba(0, 122, 255, 0.5)",
     blendMode: "Alpha",
     cullMode: "None",
-    writesToDepthBuffer: false,
+    // Phone: don't write depth, so overlapping/coplanar overlays blend cleanly.
+    // Quest: WRITE depth. On Quest's tiled GPU, many non-depth-writing transparent
+    // draws break the second (right) eye's render entirely — the whole eye goes
+    // black/garbage. Writing depth avoids that path and renders correctly in both
+    // eyes (device-confirmed). The plane overlays don't overlap, so depth-writing
+    // has no visible downside here. (Engine-level bug — non-depth-writing
+    // transparency at quantity breaking stereo — tracked in virocore
+    // VROGeometry::updateSubstrate notes / QUEST_SETUP.md.)
+    writesToDepthBuffer: isQuest,
   },
 });

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 &&
@@ -414,10 +429,8 @@ export class ViroARScene extends ViroBase<Props> {
   };
 
   render() {
-    if (isQuest) {
-      console.warn("[Viro] ViroARScene is not supported on Quest and will not render. Use ViroScene instead.");
-      return null;
-    }
+    // On Meta Quest, ViroARScene renders as a mixed-reality scene through the
+    // OpenXR renderer (passthrough + XR_FB_scene plane anchors). No longer gated.
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARScene", this.props);
 
@@ -527,6 +540,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 +587,7 @@ var VRTARScene = requireNativeComponent<any>(
       onTrackingInitializedViro: true,
       onTrackingUpdatedViro: true,
       onAmbientLightUpdateViro: true,
+      onDepthReadyViro: true,
       onAnchorFoundViro: true,
       onAnchorUpdatedViro: true,
       onAnchorRemovedViro: true,

package/components/Studio/StudioARScene.tsx

@@ -1,11 +1,5 @@
 import * as React from "react";
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Platform } from "react-native";
 import { ViroAmbientLight } from "../ViroAmbientLight";
 import { ViroARImageMarker } from "../AR/ViroARImageMarker";
@@ -24,11 +18,22 @@ import {
   registerTriggerImageTargets,
 } from "./domain/triggerImageRegistry";
 import { createNode } from "./domain/viroNodeFactory";
-import { executeOnLoadFunction } from "./domain/sceneNavigationHandler";
+import { defaultApiRequestExecutor } from "./domain/defaultApiRequestExecutor";
+import {
+  executeOnLoadFunction,
+  SequenceScheduler,
+} from "./domain/sceneNavigationHandler";
+import { StudioVariableStore } from "./domain/variableStore";
+import { StudioVisibilityStore } from "./domain/visibilityStore";
+import { StudioSoundManager } from "./domain/soundManager";
+import { StudioSounds } from "./domain/StudioSounds";
 import { registerStudioMaterialsForAssets } from "./domain/studioMaterials";
 import { useStudioShaderTimeUniforms } from "./domain/useStudioShaderTimeUniforms";
 import { useStudioShaderViewportUniforms } from "./domain/useStudioShaderViewportUniforms";
-import { buildViroPhysicsWorld, parsePhysicsWorldConfig } from "./domain/physicsConfig";
+import {
+  buildViroPhysicsWorld,
+  parsePhysicsWorldConfig,
+} from "./domain/physicsConfig";
 import {
   StudioAnimation,
   StudioSceneResponse,
@@ -46,6 +51,8 @@ interface StudioARSceneProps {
   onReady?: () => void;
   onError?: (err: Error) => void;
   onSceneChange?: (sceneId: string, sceneName: string) => void;
+  /** Session-scoped store owned by the navigator; survives scene pushes. */
+  variableStore?: StudioVariableStore;
 }
 
 /**
@@ -66,8 +73,99 @@ interface StudioARSceneInnerProps extends StudioARSceneProps {
 }
 
 const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
-  const { sceneNavigator, sceneData, onReady, onSceneChange } = props;
-  const { scene, assets, animations, collision_bindings, functions } = sceneData;
+  const { sceneNavigator, sceneData, onReady, onSceneChange, 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
+  // a pending WAIT never fires into a torn-down or replaced scene.
+  const schedulerRef = useRef<SequenceScheduler | null>(null);
+  if (schedulerRef.current === null) {
+    schedulerRef.current = new SequenceScheduler();
+  }
+  useEffect(() => {
+    return () => {
+      schedulerRef.current?.dispose();
+      schedulerRef.current = null;
+      // dispose() bumps the scheduler generation first; reset() then clears any
+      // pending sound backstop timers and fires their callbacks, which now
+      // no-op via the generation guard so unmount can't advance a waited step.
+      soundManagerRef.current?.reset();
+    };
+  }, []);
+
+  // ─── Variable store ───────────────────────────────────────────────────────
+  // Normally passed down by the navigator (session-scoped); hosts mounting this
+  // scene directly get a scene-local fallback. Seeding happens here, at instance
+  // init, so values exist before any effect dispatches on_load. seed() is
+  // initialize-if-absent, hence idempotent and strict-mode safe.
+  const variableStoreRef = useRef<StudioVariableStore | null>(null);
+  if (variableStoreRef.current === null) {
+    variableStoreRef.current = variableStore ?? new StudioVariableStore();
+    variableStoreRef.current.seed(sceneData.variables ?? []);
+  }
+
+  // ─── Visibility store ─────────────────────────────────────────────────────
+  // Scene-scoped (asset placements are per-scene), keyed by asset id. Seeded
+  // from each asset's author-time hidden_on_load default; Set Visibility
+  // actions flip it at runtime. Re-seeded on scene change so a persisted
+  // instance doesn't carry stale visibility across a navigation.
+  const visibilityStoreRef = useRef<StudioVisibilityStore | null>(null);
+  if (visibilityStoreRef.current === null) {
+    visibilityStoreRef.current = new StudioVisibilityStore();
+    visibilityStoreRef.current.seed(assets);
+  }
+  useEffect(() => {
+    visibilityStoreRef.current?.reseed(assets);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scene.id]);
+
+  // ─── Sound manager ────────────────────────────────────────────────────────
+  // Per-scene. PLAY/STOP scene-function actions drive it; <StudioSounds> renders
+  // the active list. Reset on scene change so sounds don't leak across a
+  // navigation (sounds, unlike variables, are not session-scoped).
+  const soundManagerRef = useRef<StudioSoundManager | null>(null);
+  if (soundManagerRef.current === null) {
+    soundManagerRef.current = new StudioSoundManager();
+  }
+  useEffect(() => {
+    soundManagerRef.current?.reset();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scene.id]);
+
+  // Position for a spatial PLAY: look up the placed target asset (matches the
+  // node factory's position derivation, position_z defaulting to -2).
+  const getAssetPosition = useCallback(
+    (assetId: string): [number, number, number] | undefined => {
+      const a = assets.find((x) => x.id === assetId);
+      if (!a) return undefined;
+      return [a.position_x ?? 0, a.position_y ?? 0, a.position_z ?? -2];
+    },
+    [assets]
+  );
+
+  const runtimeCtx = useMemo(
+    () => ({
+      scheduler: schedulerRef.current!,
+      variableStore: variableStoreRef.current!,
+      apiRequestExecutor: defaultApiRequestExecutor,
+      visibilityStore: visibilityStoreRef.current!,
+      soundManager: soundManagerRef.current!,
+      getAssetPosition,
+    }),
+    [getAssetPosition]
+  );
+
+  // Cancel this scene's pending WAITs before handing off to the next scene.
+  const handleSceneChange = useCallback(
+    (sceneId: string, sceneName: string) => {
+      schedulerRef.current?.cancelAll();
+      onSceneChange?.(sceneId, sceneName);
+    },
+    [onSceneChange]
+  );
 
   // ─── Material registration ────────────────────────────────────────────────
   const materialsRegisteredRef = useRef(false);
@@ -88,11 +186,17 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
   }
 
   // ─── Animation runtime state ──────────────────────────────────────────────
-  const [animOverrides, setAnimOverrides] = useState<Record<string, AnimOverride>>({});
-  const [loadedAssetIds, setLoadedAssetIds] = useState<Record<string, true>>({});
+  const [animOverrides, setAnimOverrides] = useState<
+    Record<string, AnimOverride>
+  >({});
+  const [loadedAssetIds, setLoadedAssetIds] = useState<Record<string, true>>(
+    {}
+  );
 
   const handleAssetLoaded = useCallback((assetId: string) => {
-    setLoadedAssetIds((prev) => prev[assetId] ? prev : { ...prev, [assetId]: true });
+    setLoadedAssetIds((prev) =>
+      prev[assetId] ? prev : { ...prev, [assetId]: true }
+    );
   }, []);
 
   const triggerHandlesRef = useRef<Set<number>>(new Set());
@@ -103,20 +207,27 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
     };
   }, []);
 
-  const triggerAnimation = useCallback((targetAssetId: string, animationKey: string) => {
-    // Viro's animation prop is edge-triggered on false→true. Force false first,
-    // then flip to true on the next frame so a re-trigger of the same key fires.
-    setAnimOverrides((prev) => ({ ...prev, [targetAssetId]: { key: animationKey, run: false } }));
-    const handle = requestAnimationFrame(() => {
-      triggerHandlesRef.current.delete(handle);
-      setAnimOverrides((prev) => {
-        const current = prev[targetAssetId];
-        if (!current || current.key !== animationKey || current.run) return prev;
-        return { ...prev, [targetAssetId]: { key: animationKey, run: true } };
+  const triggerAnimation = useCallback(
+    (targetAssetId: string, animationKey: string) => {
+      // Viro's animation prop is edge-triggered on false→true. Force false first,
+      // then flip to true on the next frame so a re-trigger of the same key fires.
+      setAnimOverrides((prev) => ({
+        ...prev,
+        [targetAssetId]: { key: animationKey, run: false },
+      }));
+      const handle = requestAnimationFrame(() => {
+        triggerHandlesRef.current.delete(handle);
+        setAnimOverrides((prev) => {
+          const current = prev[targetAssetId];
+          if (!current || current.key !== animationKey || current.run)
+            return prev;
+          return { ...prev, [targetAssetId]: { key: animationKey, run: true } };
+        });
       });
-    });
-    triggerHandlesRef.current.add(handle);
-  }, []);
+      triggerHandlesRef.current.add(handle);
+    },
+    []
+  );
 
   const triggerAnimationRef = useRef(triggerAnimation);
   triggerAnimationRef.current = triggerAnimation;
@@ -150,15 +261,41 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
         interruptible: activeAnim.interruptible,
         delay: activeAnim.delay_ms ?? 0,
         onStart: activeAnim.on_start_function
-          ? () => executeOnLoadFunction(activeAnim.on_start_function!, functions, sceneNavigator, animations, (id, key) => triggerAnimationRef.current(id, key))
+          ? () =>
+              executeOnLoadFunction(
+                activeAnim.on_start_function!,
+                functions,
+                sceneNavigator,
+                animations,
+                (id, key) => triggerAnimationRef.current(id, key),
+                handleSceneChange,
+                runtimeCtx
+              )
           : undefined,
         onFinish: activeAnim.on_finish_function
-          ? () => executeOnLoadFunction(activeAnim.on_finish_function!, functions, sceneNavigator, animations, (id, key) => triggerAnimationRef.current(id, key))
+          ? () =>
+              executeOnLoadFunction(
+                activeAnim.on_finish_function!,
+                functions,
+                sceneNavigator,
+                animations,
+                (id, key) => triggerAnimationRef.current(id, key),
+                handleSceneChange,
+                runtimeCtx
+              )
           : undefined,
       };
     }
     return states;
-  }, [animations, animOverrides, loadedAssetIds, functions, sceneNavigator]);
+  }, [
+    animations,
+    animOverrides,
+    loadedAssetIds,
+    functions,
+    sceneNavigator,
+    handleSceneChange,
+    runtimeCtx,
+  ]);
 
   // ─── on_load_function ─────────────────────────────────────────────────────
   const onLoadExecutedRef = useRef(false);
@@ -171,7 +308,8 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
         sceneNavigator,
         animations,
         (id, key) => triggerAnimationRef.current(id, key),
-        onSceneChange,
+        handleSceneChange,
+        runtimeCtx
       );
     }
   }, [scene.id]);
@@ -209,10 +347,18 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
         animations,
         collisionCooldownRef,
         (id, key) => triggerAnimationRef.current(id, key),
-        onSceneChange,
+        handleSceneChange,
+        runtimeCtx
       );
     },
-    [bindingsByPairKey, collisionAssetIds, sceneNavigator, animations]
+    [
+      bindingsByPairKey,
+      collisionAssetIds,
+      sceneNavigator,
+      animations,
+      handleSceneChange,
+      runtimeCtx,
+    ]
   );
 
   // ─── Trigger image targets ────────────────────────────────────────────────
@@ -222,13 +368,17 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
     return { planeAssets: plane, imageTriggeredAssets: imgTriggered };
   }, [assets]);
 
-  const [urlToTargetName, setUrlToTargetName] = useState<Map<string, string>>(() => new Map());
+  const [urlToTargetName, setUrlToTargetName] = useState<Map<string, string>>(
+    () => new Map()
+  );
   const prevTargetNamesRef = useRef<string[]>([]);
 
   useEffect(() => {
     if (isQuest) {
       if (imageTriggeredAssets.length > 0) {
-        console.warn("[Studio] Image-triggered assets are not supported on Quest — skipping.");
+        console.warn(
+          "[Studio] Image-triggered assets are not supported on Quest — skipping."
+        );
       }
       return;
     }
@@ -249,10 +399,13 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
   }, [imageTriggeredAssets]);
 
   // ─── Ready callback ───────────────────────────────────────────────────────
-  useEffect(() => { onReady?.(); }, []);
+  useEffect(() => {
+    onReady?.();
+  }, []);
 
   // ─── Render helpers ───────────────────────────────────────────────────────
-  const maxModels = Platform.OS === "android" ? ANDROID_MAX_3D_MODELS : IOS_MAX_3D_MODELS;
+  const maxModels =
+    Platform.OS === "android" ? ANDROID_MAX_3D_MODELS : IOS_MAX_3D_MODELS;
 
   const renderedPlaneAssets = useMemo(() => {
     let modelCount = 0;
@@ -261,7 +414,9 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
         if (asset.asset_type_name === "3D-MODEL") {
           modelCount++;
           if (modelCount > maxModels) {
-            console.warn(`[Studio] Skipping 3D model "${asset.name}" — ${Platform.OS} limit (${maxModels}) reached`);
+            console.warn(
+              `[Studio] Skipping 3D model "${asset.name}" — ${Platform.OS} limit (${maxModels}) reached`
+            );
             return null;
           }
         }
@@ -274,11 +429,22 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
           animationStates,
           handleAssetLoaded,
           getCollisionHandler(asset.id),
-          onSceneChange,
+          handleSceneChange,
+          runtimeCtx
         );
       })
       .filter(Boolean) as React.ReactElement[];
-  }, [planeAssets, sceneNavigator, animations, animationStates, handleAssetLoaded, getCollisionHandler, maxModels, onSceneChange]);
+  }, [
+    planeAssets,
+    sceneNavigator,
+    animations,
+    animationStates,
+    handleAssetLoaded,
+    getCollisionHandler,
+    maxModels,
+    handleSceneChange,
+    runtimeCtx,
+  ]);
 
   const renderedImageTriggeredAssets = useMemo(() => {
     if (isQuest) return [];
@@ -295,7 +461,8 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
           animationStates,
           handleAssetLoaded,
           getCollisionHandler(asset.id),
-          onSceneChange,
+          handleSceneChange,
+          runtimeCtx
         );
         if (!node) return null;
         return (
@@ -305,16 +472,30 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
         );
       })
       .filter(Boolean) as React.ReactElement[];
-  }, [urlToTargetName, imageTriggeredAssets, sceneNavigator, animations, animationStates, handleAssetLoaded, getCollisionHandler, onSceneChange]);
+  }, [
+    urlToTargetName,
+    imageTriggeredAssets,
+    sceneNavigator,
+    animations,
+    animationStates,
+    handleAssetLoaded,
+    getCollisionHandler,
+    handleSceneChange,
+    runtimeCtx,
+  ]);
 
   // ─── Plane detection (AR only) ────────────────────────────────────────────
-  const planeDetectionMode = ((scene.plane_detection as string) ?? "NONE").toUpperCase();
+  const planeDetectionMode = (
+    (scene.plane_detection as string) ?? "NONE"
+  ).toUpperCase();
   const planeAlignment = (scene.plane_direction ?? "Horizontal") as any;
 
   const renderAssets = () => {
     if (isQuest) {
       if (planeDetectionMode !== "NONE") {
-        console.warn(`[Studio] Plane detection (${planeDetectionMode}) is not supported on Quest — rendering assets without plane anchor.`);
+        console.warn(
+          `[Studio] Plane detection (${planeDetectionMode}) is not supported on Quest — rendering assets without plane anchor.`
+        );
       }
       return <>{renderedPlaneAssets}</>;
     }
@@ -328,7 +509,11 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
     }
     if (planeDetectionMode === "MANUAL") {
       return (
-        <ViroARPlaneSelector minHeight={0.1} minWidth={0.1} alignment={planeAlignment}>
+        <ViroARPlaneSelector
+          minHeight={0.1}
+          minWidth={0.1}
+          alignment={planeAlignment}
+        >
           {renderedPlaneAssets}
         </ViroARPlaneSelector>
       );
@@ -337,12 +522,16 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
   };
 
   // ─── Physics world ────────────────────────────────────────────────────────
-  const physicsWorldConfig = parsePhysicsWorldConfig(scene.physics_world_config);
+  const physicsWorldConfig = parsePhysicsWorldConfig(
+    scene.physics_world_config
+  );
   const physicsWorld = physicsWorldConfig?.enabled
     ? buildViroPhysicsWorld(physicsWorldConfig)
     : undefined;
 
-  const physicsProps = physicsWorld ? { physicsWorld: physicsWorld as any } : {};
+  const physicsProps = physicsWorld
+    ? { physicsWorld: physicsWorld as any }
+    : {};
 
   // ─── Render ───────────────────────────────────────────────────────────────
   const children = (
@@ -351,11 +540,17 @@ const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
       <ViroAmbientLight color="#ffffff" intensity={1000} />
       {renderAssets()}
       {renderedImageTriggeredAssets}
+      <StudioSounds manager={soundManagerRef.current!} />
       {assets.length === 0 && (
         <ViroText
           text="No assets to display"
           position={[0, 0, -2]}
-          style={{ fontFamily: "Arial", fontSize: 16, color: "#CCCCCC", textAlign: "center" }}
+          style={{
+            fontFamily: "Arial",
+            fontSize: 16,
+            color: "#CCCCCC",
+            textAlign: "center",
+          }}
         />
       )}
     </>

package/components/Studio/StudioSceneNavigator.tsx

@@ -7,6 +7,7 @@ import { ViroXRSceneNavigator } from "../ViroXRSceneNavigator";
 import { isQuest } from "../Utilities/ViroPlatform";
 import { registerSceneAnimations } from "./domain/animationRegistry";
 import { registerStudioMaterialsForAssets } from "./domain/studioMaterials";
+import { StudioVariableStore } from "./domain/variableStore";
 import { StudioARScene } from "./StudioARScene";
 import { StudioProjectApiResponse, StudioSceneResponse } from "./types";
 import { VRTStudioModule } from "./VRTStudioModule";
@@ -65,6 +66,19 @@ export function StudioSceneNavigator({
   const navigatorRef = useRef<any>(null);
   const loadedSceneIdRef = useRef<string | null>(null);
 
+  // Session-scoped variable store: outlives every scene push, resets when the
+  // navigator (= the AR/VR session) unmounts.
+  const variableStoreRef = useRef<StudioVariableStore | null>(null);
+  if (variableStoreRef.current === null) {
+    variableStoreRef.current = new StudioVariableStore();
+  }
+  useEffect(() => {
+    return () => {
+      variableStoreRef.current?.reset();
+      variableStoreRef.current = null;
+    };
+  }, []);
+
   const onSceneReadyRef = useRef(onSceneReady);
   const onErrorRef = useRef(onError);
   const onSceneChangeRef = useRef(onSceneChange);
@@ -138,6 +152,7 @@ export function StudioSceneNavigator({
           sceneData,
           onReady: onSceneReadyRef.current,
           onSceneChange: onSceneChangeRef.current,
+          variableStore: variableStoreRef.current,
         },
       };
 

package/components/Studio/VRTStudioModule.ts

@@ -10,6 +10,7 @@ interface StudioNativeModule {
   rvGetScene(sceneId: string): Promise<StudioModuleResult>;
   rvGetProject(): Promise<StudioModuleResult>;
   rvGetProjectId(): Promise<string | null>;
+  rvStudioApiRequest(bodyJson: string): Promise<StudioModuleResult>;
 }
 
 const native = NativeModules.VRTStudio as StudioNativeModule | undefined;
@@ -37,4 +38,13 @@ export const VRTStudioModule = {
     if (!native) return Promise.resolve(null);
     return native.rvGetProjectId();
   },
+  /**
+   * POSTs a pre-serialised scene-api-request body ({function_id, variables})
+   * to the egress proxy, authenticated with the app's RVApiKey. The resolved
+   * `data` is the proxy's outcome envelope JSON.
+   */
+  rvStudioApiRequest: (bodyJson: string): Promise<StudioModuleResult> => {
+    if (!native) return Promise.resolve(NOT_AVAILABLE);
+    return native.rvStudioApiRequest(bodyJson);
+  },
 };

package/components/Studio/domain/StudioSounds.tsx

@@ -0,0 +1,46 @@
+import * as React from "react";
+import { NativeSyntheticEvent } from "react-native";
+import { ViroErrorEvent } from "../../Types/ViroEvents";
+import { ViroSound } from "../../ViroSound";
+import { ViroSpatialSound } from "../../ViroSpatialSound";
+import { StudioSoundManager } from "./soundManager";
+
+/**
+ * Renders every actively-playing sound from the manager, re-painting the whole
+ * list on any change (like the reactive variable-text nodes). Non-looping sounds
+ * remove themselves on finish; any sound removes itself on error so a clip that
+ * fails to load releases a waiting step instead of stalling the sequence.
+ */
+export const StudioSounds: React.FC<{ manager: StudioSoundManager }> = ({
+  manager,
+}) => {
+  const [, force] = React.useReducer((n) => n + 1, 0);
+  React.useEffect(() => manager.subscribe(force), [manager]);
+  return (
+    <>
+      {manager.getActive().map((s) => {
+        const shared = {
+          source: { uri: s.url },
+          volume: s.volume,
+          loop: s.loop,
+          paused: false,
+          onFinish: () => {
+            if (!s.loop) manager.remove(s.playId);
+          },
+          onError: (e: NativeSyntheticEvent<ViroErrorEvent>) => {
+            console.warn(
+              `[Studio] Sound failed: ${s.audioAssetId} (#${s.playId})`,
+              e?.nativeEvent?.error
+            );
+            manager.remove(s.playId);
+          },
+        };
+        return s.position ? (
+          <ViroSpatialSound key={s.playId} position={s.position} {...shared} />
+        ) : (
+          <ViroSound key={s.playId} {...shared} />
+        );
+      })}
+    </>
+  );
+};