@reactvision/react-viro 2.54.0 → 2.55.0

package/components/Studio/StudioARScene.tsx

@@ -0,0 +1,368 @@
+import * as React from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { Platform } from "react-native";
+import { ViroAmbientLight } from "../ViroAmbientLight";
+import { ViroARImageMarker } from "../AR/ViroARImageMarker";
+import { ViroARPlane } from "../AR/ViroARPlane";
+import { ViroARPlaneSelector } from "../AR/ViroARPlaneSelector";
+import { ViroARScene } from "../AR/ViroARScene";
+import { ViroScene } from "../ViroScene";
+import { ViroText } from "../ViroText";
+import { ViroController } from "../ViroController";
+import { isQuest } from "../Utilities/ViroPlatform";
+import { registerSceneAnimations } from "./domain/animationRegistry";
+import { createPlacementCollisionHandler } from "./domain/collisionBindingsRuntime";
+import { collisionPairKey } from "./domain/collisionPairKey";
+import {
+  cleanupTriggerImageTargets,
+  registerTriggerImageTargets,
+} from "./domain/triggerImageRegistry";
+import { createNode } from "./domain/viroNodeFactory";
+import { executeOnLoadFunction } from "./domain/sceneNavigationHandler";
+import { registerStudioMaterialsForAssets } from "./domain/studioMaterials";
+import { useStudioShaderTimeUniforms } from "./domain/useStudioShaderTimeUniforms";
+import { useStudioShaderViewportUniforms } from "./domain/useStudioShaderViewportUniforms";
+import { buildViroPhysicsWorld, parsePhysicsWorldConfig } from "./domain/physicsConfig";
+import {
+  StudioAnimation,
+  StudioSceneResponse,
+  ViroAnimationProp,
+} from "./types";
+
+const ANDROID_MAX_3D_MODELS = 3;
+const IOS_MAX_3D_MODELS = 10;
+
+type AnimOverride = { key: string; run: boolean };
+
+interface StudioARSceneProps {
+  sceneNavigator?: any;
+  sceneData: StudioSceneResponse | null;
+  onReady?: () => void;
+  onError?: (err: Error) => void;
+  onSceneChange?: (sceneId: string, sceneName: string) => void;
+}
+
+/**
+ * Outer gate: keeps the hooks-bearing inner component out of the tree until
+ * sceneData is available, avoiding a Rules of Hooks violation.
+ */
+export const StudioARScene: React.FC<StudioARSceneProps> = (props) => {
+  if (!props.sceneData) {
+    return isQuest ? <ViroScene /> : <ViroARScene />;
+  }
+  return <StudioARSceneInner {...props} sceneData={props.sceneData} />;
+};
+
+// ─── Inner component (all hooks live here) ────────────────────────────────────
+
+interface StudioARSceneInnerProps extends StudioARSceneProps {
+  sceneData: StudioSceneResponse; // guaranteed non-null by outer gate
+}
+
+const StudioARSceneInner: React.FC<StudioARSceneInnerProps> = (props) => {
+  const { sceneNavigator, sceneData, onReady, onSceneChange } = props;
+  const { scene, assets, animations, collision_bindings, functions } = sceneData;
+
+  // ─── Material registration ────────────────────────────────────────────────
+  const materialsRegisteredRef = useRef(false);
+  if (!materialsRegisteredRef.current) {
+    registerStudioMaterialsForAssets(assets);
+    materialsRegisteredRef.current = true;
+  }
+
+  useStudioShaderTimeUniforms(assets);
+  useStudioShaderViewportUniforms(assets);
+
+  // ─── Animation registration ───────────────────────────────────────────────
+  const registeredKeyRef = useRef<string | null>(null);
+  const animationsKey = animations.map((a) => a.animation_key).join(",");
+  if (animations.length > 0 && registeredKeyRef.current !== animationsKey) {
+    registeredKeyRef.current = animationsKey;
+    registerSceneAnimations(animations);
+  }
+
+  // ─── Animation runtime state ──────────────────────────────────────────────
+  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 });
+  }, []);
+
+  const triggerHandlesRef = useRef<Set<number>>(new Set());
+  useEffect(() => {
+    return () => {
+      triggerHandlesRef.current.forEach((id) => cancelAnimationFrame(id));
+      triggerHandlesRef.current.clear();
+    };
+  }, []);
+
+  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);
+  }, []);
+
+  const triggerAnimationRef = useRef(triggerAnimation);
+  triggerAnimationRef.current = triggerAnimation;
+
+  // ─── Computed animation props per asset ──────────────────────────────────
+  const animationStates = useMemo<Record<string, ViroAnimationProp>>(() => {
+    const states: Record<string, ViroAnimationProp> = {};
+    const animsByAsset = new Map<string, StudioAnimation[]>();
+    for (const anim of animations) {
+      const list = animsByAsset.get(anim.target_asset_id) ?? [];
+      list.push(anim);
+      animsByAsset.set(anim.target_asset_id, list);
+    }
+    for (const [assetId, anims] of animsByAsset) {
+      const override = animOverrides[assetId];
+      let activeAnim: StudioAnimation;
+      let run: boolean;
+      if (override) {
+        const triggered = anims.find((a) => a.animation_key === override.key);
+        if (!triggered) continue;
+        activeAnim = triggered;
+        run = override.run && !!loadedAssetIds[assetId];
+      } else {
+        activeAnim = anims[0];
+        run = false;
+      }
+      states[assetId] = {
+        name: activeAnim.animation_key,
+        run,
+        loop: activeAnim.loop,
+        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))
+          : undefined,
+        onFinish: activeAnim.on_finish_function
+          ? () => executeOnLoadFunction(activeAnim.on_finish_function!, functions, sceneNavigator, animations, (id, key) => triggerAnimationRef.current(id, key))
+          : undefined,
+      };
+    }
+    return states;
+  }, [animations, animOverrides, loadedAssetIds, functions, sceneNavigator]);
+
+  // ─── on_load_function ─────────────────────────────────────────────────────
+  const onLoadExecutedRef = useRef(false);
+  useEffect(() => {
+    if (scene.on_load_function && !onLoadExecutedRef.current) {
+      onLoadExecutedRef.current = true;
+      executeOnLoadFunction(
+        scene.on_load_function,
+        functions,
+        sceneNavigator,
+        animations,
+        (id, key) => triggerAnimationRef.current(id, key),
+        onSceneChange,
+      );
+    }
+  }, [scene.id]);
+
+  // ─── Collision bindings ───────────────────────────────────────────────────
+  const bindingsByPairKey = useMemo(() => {
+    const m = new Map<string, (typeof collision_bindings)[0][]>();
+    for (const b of collision_bindings) {
+      const key = collisionPairKey(b.asset_x_id, b.asset_y_id);
+      const list = m.get(key) ?? [];
+      list.push(b);
+      m.set(key, list);
+    }
+    return m;
+  }, [collision_bindings]);
+
+  const collisionAssetIds = useMemo(() => {
+    const s = new Set<string>();
+    for (const b of collision_bindings) {
+      s.add(b.asset_x_id);
+      s.add(b.asset_y_id);
+    }
+    return s;
+  }, [collision_bindings]);
+
+  const collisionCooldownRef = useRef<Map<string, number>>(new Map());
+
+  const getCollisionHandler = useCallback(
+    (placementId: string) => {
+      if (!collisionAssetIds.has(placementId)) return undefined;
+      return createPlacementCollisionHandler(
+        placementId,
+        bindingsByPairKey,
+        sceneNavigator,
+        animations,
+        collisionCooldownRef,
+        (id, key) => triggerAnimationRef.current(id, key),
+        onSceneChange,
+      );
+    },
+    [bindingsByPairKey, collisionAssetIds, sceneNavigator, animations]
+  );
+
+  // ─── Trigger image targets ────────────────────────────────────────────────
+  const { planeAssets, imageTriggeredAssets } = useMemo(() => {
+    const plane = assets.filter((a) => !a.trigger_image_url);
+    const imgTriggered = assets.filter((a) => !!a.trigger_image_url);
+    return { planeAssets: plane, imageTriggeredAssets: imgTriggered };
+  }, [assets]);
+
+  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.");
+      }
+      return;
+    }
+    if (imageTriggeredAssets.length === 0) {
+      cleanupTriggerImageTargets(prevTargetNamesRef.current);
+      prevTargetNamesRef.current = [];
+      setUrlToTargetName(new Map());
+      return;
+    }
+    const map = registerTriggerImageTargets(imageTriggeredAssets);
+    const targetNames = [...map.values()];
+    prevTargetNamesRef.current = targetNames;
+    setUrlToTargetName(map);
+    return () => {
+      cleanupTriggerImageTargets(targetNames);
+      prevTargetNamesRef.current = [];
+    };
+  }, [imageTriggeredAssets]);
+
+  // ─── Ready callback ───────────────────────────────────────────────────────
+  useEffect(() => { onReady?.(); }, []);
+
+  // ─── Render helpers ───────────────────────────────────────────────────────
+  const maxModels = Platform.OS === "android" ? ANDROID_MAX_3D_MODELS : IOS_MAX_3D_MODELS;
+
+  const renderedPlaneAssets = useMemo(() => {
+    let modelCount = 0;
+    return planeAssets
+      .map((asset) => {
+        if (asset.asset_type_name === "3D-MODEL") {
+          modelCount++;
+          if (modelCount > maxModels) {
+            console.warn(`[Studio] Skipping 3D model "${asset.name}" — ${Platform.OS} limit (${maxModels}) reached`);
+            return null;
+          }
+        }
+        return createNode(
+          asset,
+          sceneNavigator,
+          animations,
+          scene,
+          (id, key) => triggerAnimationRef.current(id, key),
+          animationStates,
+          handleAssetLoaded,
+          getCollisionHandler(asset.id),
+          onSceneChange,
+        );
+      })
+      .filter(Boolean) as React.ReactElement[];
+  }, [planeAssets, sceneNavigator, animations, animationStates, handleAssetLoaded, getCollisionHandler, maxModels, onSceneChange]);
+
+  const renderedImageTriggeredAssets = useMemo(() => {
+    if (isQuest) return [];
+    return imageTriggeredAssets
+      .map((asset) => {
+        const targetName = urlToTargetName.get(asset.trigger_image_url!);
+        if (!targetName) return null;
+        const node = createNode(
+          asset,
+          sceneNavigator,
+          animations,
+          scene,
+          (id, key) => triggerAnimationRef.current(id, key),
+          animationStates,
+          handleAssetLoaded,
+          getCollisionHandler(asset.id),
+          onSceneChange,
+        );
+        if (!node) return null;
+        return (
+          <ViroARImageMarker key={asset.id} target={targetName}>
+            {node}
+          </ViroARImageMarker>
+        );
+      })
+      .filter(Boolean) as React.ReactElement[];
+  }, [urlToTargetName, imageTriggeredAssets, sceneNavigator, animations, animationStates, handleAssetLoaded, getCollisionHandler, onSceneChange]);
+
+  // ─── Plane detection (AR only) ────────────────────────────────────────────
+  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.`);
+      }
+      return <>{renderedPlaneAssets}</>;
+    }
+
+    if (planeDetectionMode === "AUTOMATIC") {
+      return (
+        <ViroARPlane minHeight={0.1} minWidth={0.1} alignment={planeAlignment}>
+          {renderedPlaneAssets}
+        </ViroARPlane>
+      );
+    }
+    if (planeDetectionMode === "MANUAL") {
+      return (
+        <ViroARPlaneSelector minHeight={0.1} minWidth={0.1} alignment={planeAlignment}>
+          {renderedPlaneAssets}
+        </ViroARPlaneSelector>
+      );
+    }
+    return <>{renderedPlaneAssets}</>;
+  };
+
+  // ─── Physics world ────────────────────────────────────────────────────────
+  const physicsWorldConfig = parsePhysicsWorldConfig(scene.physics_world_config);
+  const physicsWorld = physicsWorldConfig?.enabled
+    ? buildViroPhysicsWorld(physicsWorldConfig)
+    : undefined;
+
+  const physicsProps = physicsWorld ? { physicsWorld: physicsWorld as any } : {};
+
+  // ─── Render ───────────────────────────────────────────────────────────────
+  const children = (
+    <>
+      {isQuest && <ViroController controllerVisibility reticleVisibility />}
+      <ViroAmbientLight color="#ffffff" intensity={1000} />
+      {renderAssets()}
+      {renderedImageTriggeredAssets}
+      {assets.length === 0 && (
+        <ViroText
+          text="No assets to display"
+          position={[0, 0, -2]}
+          style={{ fontFamily: "Arial", fontSize: 16, color: "#CCCCCC", textAlign: "center" }}
+        />
+      )}
+    </>
+  );
+
+  if (isQuest) {
+    return <ViroScene {...physicsProps}>{children}</ViroScene>;
+  }
+  return <ViroARScene {...physicsProps}>{children}</ViroARScene>;
+};

package/components/Studio/StudioSceneNavigator.tsx

@@ -0,0 +1,191 @@
+import * as React from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { ActivityIndicator, StyleSheet, View, ViewStyle } from "react-native";
+import { ViroARScene } from "../AR/ViroARScene";
+import { ViroScene } from "../ViroScene";
+import { ViroXRSceneNavigator } from "../ViroXRSceneNavigator";
+import { isQuest } from "../Utilities/ViroPlatform";
+import { registerSceneAnimations } from "./domain/animationRegistry";
+import { registerStudioMaterialsForAssets } from "./domain/studioMaterials";
+import { StudioARScene } from "./StudioARScene";
+import { StudioProjectApiResponse, StudioSceneResponse } from "./types";
+import { VRTStudioModule } from "./VRTStudioModule";
+
+function LoadingARScene() { return <ViroARScene />; }
+function LoadingVRScene() { return <ViroScene />; }
+
+const styles = StyleSheet.create({
+  loader: {
+    position: "absolute",
+    top: 0, left: 0, right: 0, bottom: 0,
+    justifyContent: "center",
+    alignItems: "center",
+    backgroundColor: "#000000",
+  },
+});
+
+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.
+   */
+  sceneId?: string;
+  worldAlignment?: "Gravity" | "GravityAndHeading" | "Camera";
+  autofocus?: boolean;
+  style?: ViewStyle;
+  onSceneReady?: () => void;
+  onError?: (err: Error) => void;
+  onSceneChange?: (sceneId: string, sceneName: string) => void;
+  onExitViro?: () => void;
+}
+
+/**
+ * Cross-reality Studio scene navigator. Renders a Studio-authored scene on
+ * both AR devices (iOS / non-Quest Android) and Meta Quest (VR).
+ *
+ * Opening-scene resolution order:
+ *   1. `sceneId` prop → use it directly
+ *   2. Native project (RVProjectId from manifest) → use `opening_scene.id`
+ *   3. Fallback → first scene in the project's scene list
+ *
+ * On Quest, ViroXRSceneNavigator is not rendered until the scene data is
+ * 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) {
+  const navigatorRef = useRef<any>(null);
+  const loadedSceneIdRef = useRef<string | null>(null);
+
+  const onSceneReadyRef = useRef(onSceneReady);
+  const onErrorRef = useRef(onError);
+  const onSceneChangeRef = useRef(onSceneChange);
+  onSceneReadyRef.current = onSceneReady;
+  onErrorRef.current = onError;
+  onSceneChangeRef.current = onSceneChange;
+
+  // 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 resolveSceneId = useCallback(async (): Promise<string> => {
+    if (sceneId) return sceneId;
+
+    const projectResult = await VRTStudioModule.rvGetProject();
+    if (!projectResult.success) {
+      throw new Error(projectResult.error ?? "rvGetProject failed");
+    }
+    if (typeof projectResult.data !== "string") {
+      throw new Error("rvGetProject returned no data");
+    }
+
+    const { project } = JSON.parse(projectResult.data) as StudioProjectApiResponse;
+
+    if (project.opening_scene?.id) {
+      return project.opening_scene.id;
+    }
+    if (project.scenes.length > 0) {
+      return project.scenes[0].id;
+    }
+    throw new Error(`Project ${project.id} has no scenes`);
+  }, [sceneId]);
+
+  const loadScene = useCallback(
+    async (isCancelled: () => boolean) => {
+      await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+      if (isCancelled()) return;
+
+      const resolvedSceneId = await resolveSceneId();
+      if (isCancelled()) return;
+
+      if (loadedSceneIdRef.current === resolvedSceneId) return;
+
+      const result = await VRTStudioModule.rvGetScene(resolvedSceneId);
+      if (isCancelled()) return;
+      if (!result.success) {
+        throw new Error(result.error ?? "rvGetScene failed");
+      }
+      if (typeof result.data !== "string") {
+        throw new Error("rvGetScene returned no data");
+      }
+
+      const sceneData: StudioSceneResponse = JSON.parse(result.data);
+      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.
+      if (isQuest) {
+        registerSceneAnimations(sceneData.animations);
+        registerStudioMaterialsForAssets(sceneData.assets);
+      }
+
+      const entry = {
+        scene: StudioARScene,
+        passProps: {
+          sceneData,
+          onReady: onSceneReadyRef.current,
+          onSceneChange: onSceneChangeRef.current,
+        },
+      };
+
+      if (isQuest) {
+        // On Quest: setting vrSceneEntry triggers ViroXRSceneNavigator to mount
+        // with StudioARScene as vrInitialScene — VRActivity gets content immediately.
+        setVrSceneEntry(entry);
+      } else {
+        navigatorRef.current?.arSceneNavigator?.push(entry);
+      }
+    },
+    [resolveSceneId]
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    const isCancelled = () => cancelled;
+
+    loadScene(isCancelled).catch((e: unknown) => {
+      if (cancelled) return;
+      const err = e instanceof Error ? e : new Error(String(e));
+      const handler = onErrorRef.current;
+      if (handler) handler(err);
+      else console.error("[Studio] Failed to load scene:", err);
+    });
+
+    return () => { cancelled = true; };
+  }, [sceneId, loadScene]);
+
+  // On Quest: show a spinner until scene data is ready, then mount
+  // ViroXRSceneNavigator (which launches VRActivity with content immediately).
+  if (isQuest && !vrSceneEntry) {
+    return (
+      <View style={styles.loader}>
+        <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}
+    />
+  );
+}

package/components/Studio/VRTStudioModule.ts

@@ -0,0 +1,40 @@
+import { NativeModules } from "react-native";
+
+export interface StudioModuleResult {
+  success: boolean;
+  data?: string;
+  error?: string;
+}
+
+interface StudioNativeModule {
+  rvGetScene(sceneId: string): Promise<StudioModuleResult>;
+  rvGetProject(): Promise<StudioModuleResult>;
+  rvGetProjectId(): Promise<string | null>;
+}
+
+const native = NativeModules.VRTStudio as StudioNativeModule | undefined;
+
+const NOT_AVAILABLE: StudioModuleResult = {
+  success: false,
+  error: "VRTStudio native module not available",
+};
+
+export const VRTStudioModule = {
+  rvGetScene: (sceneId: string): Promise<StudioModuleResult> => {
+    if (!native) return Promise.resolve(NOT_AVAILABLE);
+    return native.rvGetScene(sceneId);
+  },
+  /**
+   * Fetches the project configured in the app manifest (Android: `com.reactvision.RVProjectId`,
+   * iOS: `RVProjectId`). The project ID is baked in by the Expo plugin at build time.
+   */
+  rvGetProject: (): Promise<StudioModuleResult> => {
+    if (!native) return Promise.resolve(NOT_AVAILABLE);
+    return native.rvGetProject();
+  },
+  /** Returns the configured project ID, or null if not set. */
+  rvGetProjectId: (): Promise<string | null> => {
+    if (!native) return Promise.resolve(null);
+    return native.rvGetProjectId();
+  },
+};

package/components/Studio/domain/animationRegistry.ts

@@ -0,0 +1,86 @@
+import { ViroAnimations } from "../../Animation/ViroAnimations";
+import { StudioAnimation } from "../types";
+
+const MAX_CONCURRENT_ANIMATIONS = 10;
+const MAX_DURATION_MS = 30_000;
+const MAX_POSITION_ABS = 1_000;
+const MAX_SCALE = 100;
+const MIN_SCALE = 0.01;
+
+/**
+ * Builds the Viro animation registry object from StudioAnimation rows.
+ * The properties field is already in Viro's native keyframe format.
+ */
+export function buildViroAnimationRegistry(
+  animations: StudioAnimation[]
+): Record<string, unknown> {
+  const registry: Record<string, unknown> = {};
+
+  for (const anim of animations) {
+    warnAnimationPerformance(anim);
+    registry[anim.animation_key] = {
+      properties: anim.properties,
+      duration: anim.duration_ms ?? 1000,
+      delay: anim.delay_ms ?? 0,
+      ...(anim.easing ? { easing: anim.easing } : {}),
+    };
+  }
+
+  return registry;
+}
+
+/**
+ * Registers all scene animations with ViroReact.
+ * Must be called before any animated Viro components mount.
+ */
+export function registerSceneAnimations(animations: StudioAnimation[]): void {
+  if (animations.length === 0) return;
+
+  if (animations.length > MAX_CONCURRENT_ANIMATIONS) {
+    console.warn(
+      `[Studio/Animation] Scene has ${animations.length} animations. ` +
+        `Recommended max is ${MAX_CONCURRENT_ANIMATIONS} for smooth performance.`
+    );
+  }
+
+  const registry = buildViroAnimationRegistry(animations);
+  ViroAnimations.registerAnimations(registry as any);
+
+  console.log(
+    `[Studio/Animation] Registered ${Object.keys(registry).length} animation(s): ${Object.keys(registry).join(", ")}`
+  );
+}
+
+function warnAnimationPerformance(anim: StudioAnimation): void {
+  if ((anim.duration_ms ?? 0) > MAX_DURATION_MS) {
+    console.warn(
+      `[Studio/Animation] "${anim.animation_key}" duration ${anim.duration_ms}ms exceeds ` +
+        `recommended max of ${MAX_DURATION_MS}ms.`
+    );
+  }
+
+  const props = anim.properties as Record<string, unknown>;
+  if (!props || typeof props !== "object") return;
+
+  for (const key of Object.keys(props)) {
+    const val = (props as Record<string, unknown>)[key];
+    if (typeof val !== "number") continue;
+
+    if (key === "scaleX" || key === "scaleY" || key === "scaleZ") {
+      if (val > MAX_SCALE || val < MIN_SCALE) {
+        console.warn(
+          `[Studio/Animation] "${anim.animation_key}" ${key}=${val} is outside ` +
+            `recommended range [${MIN_SCALE}, ${MAX_SCALE}].`
+        );
+      }
+    }
+
+    if (key === "positionX" || key === "positionY" || key === "positionZ") {
+      if (Math.abs(val) > MAX_POSITION_ABS) {
+        console.warn(
+          `[Studio/Animation] "${anim.animation_key}" ${key}=${val} is far from origin.`
+        );
+      }
+    }
+  }
+}