@reactvision/react-viro 2.54.0 → 2.55.0

package/dist/components/Studio/StudioSceneNavigator.js

@@ -0,0 +1,174 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StudioSceneNavigator = StudioSceneNavigator;
+const React = __importStar(require("react"));
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const ViroARScene_1 = require("../AR/ViroARScene");
+const ViroScene_1 = require("../ViroScene");
+const ViroXRSceneNavigator_1 = require("../ViroXRSceneNavigator");
+const ViroPlatform_1 = require("../Utilities/ViroPlatform");
+const animationRegistry_1 = require("./domain/animationRegistry");
+const studioMaterials_1 = require("./domain/studioMaterials");
+const StudioARScene_1 = require("./StudioARScene");
+const VRTStudioModule_1 = require("./VRTStudioModule");
+function LoadingARScene() { return <ViroARScene_1.ViroARScene />; }
+function LoadingVRScene() { return <ViroScene_1.ViroScene />; }
+const styles = react_native_1.StyleSheet.create({
+    loader: {
+        position: "absolute",
+        top: 0, left: 0, right: 0, bottom: 0,
+        justifyContent: "center",
+        alignItems: "center",
+        backgroundColor: "#000000",
+    },
+});
+/**
+ * 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.
+ */
+function StudioSceneNavigator({ sceneId, worldAlignment = "Gravity", autofocus = true, style, onSceneReady, onError, onSceneChange, onExitViro, }) {
+    const navigatorRef = (0, react_1.useRef)(null);
+    const loadedSceneIdRef = (0, react_1.useRef)(null);
+    const onSceneReadyRef = (0, react_1.useRef)(onSceneReady);
+    const onErrorRef = (0, react_1.useRef)(onError);
+    const onSceneChangeRef = (0, react_1.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] = (0, react_1.useState)(null);
+    const resolveSceneId = (0, react_1.useCallback)(async () => {
+        if (sceneId)
+            return sceneId;
+        const projectResult = await VRTStudioModule_1.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);
+        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 = (0, react_1.useCallback)(async (isCancelled) => {
+        await new Promise((resolve) => requestAnimationFrame(() => resolve()));
+        if (isCancelled())
+            return;
+        const resolvedSceneId = await resolveSceneId();
+        if (isCancelled())
+            return;
+        if (loadedSceneIdRef.current === resolvedSceneId)
+            return;
+        const result = await VRTStudioModule_1.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 = 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 (ViroPlatform_1.isQuest) {
+            (0, animationRegistry_1.registerSceneAnimations)(sceneData.animations);
+            (0, studioMaterials_1.registerStudioMaterialsForAssets)(sceneData.assets);
+        }
+        const entry = {
+            scene: StudioARScene_1.StudioARScene,
+            passProps: {
+                sceneData,
+                onReady: onSceneReadyRef.current,
+                onSceneChange: onSceneChangeRef.current,
+            },
+        };
+        if (ViroPlatform_1.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]);
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        const isCancelled = () => cancelled;
+        loadScene(isCancelled).catch((e) => {
+            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 (ViroPlatform_1.isQuest && !vrSceneEntry) {
+        return (<react_native_1.View style={styles.loader}>
+        <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}/>);
+}

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

@@ -0,0 +1,15 @@
+export interface StudioModuleResult {
+    success: boolean;
+    data?: string;
+    error?: string;
+}
+export declare const VRTStudioModule: {
+    rvGetScene: (sceneId: string) => Promise<StudioModuleResult>;
+    /**
+     * 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>;
+    /** Returns the configured project ID, or null if not set. */
+    rvGetProjectId: () => Promise<string | null>;
+};

package/dist/components/Studio/VRTStudioModule.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VRTStudioModule = void 0;
+const react_native_1 = require("react-native");
+const native = react_native_1.NativeModules.VRTStudio;
+const NOT_AVAILABLE = {
+    success: false,
+    error: "VRTStudio native module not available",
+};
+exports.VRTStudioModule = {
+    rvGetScene: (sceneId) => {
+        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: () => {
+        if (!native)
+            return Promise.resolve(NOT_AVAILABLE);
+        return native.rvGetProject();
+    },
+    /** Returns the configured project ID, or null if not set. */
+    rvGetProjectId: () => {
+        if (!native)
+            return Promise.resolve(null);
+        return native.rvGetProjectId();
+    },
+};

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

@@ -0,0 +1,11 @@
+import { StudioAnimation } from "../types";
+/**
+ * Builds the Viro animation registry object from StudioAnimation rows.
+ * The properties field is already in Viro's native keyframe format.
+ */
+export declare function buildViroAnimationRegistry(animations: StudioAnimation[]): Record<string, unknown>;
+/**
+ * Registers all scene animations with ViroReact.
+ * Must be called before any animated Viro components mount.
+ */
+export declare function registerSceneAnimations(animations: StudioAnimation[]): void;

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

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildViroAnimationRegistry = buildViroAnimationRegistry;
+exports.registerSceneAnimations = registerSceneAnimations;
+const ViroAnimations_1 = require("../../Animation/ViroAnimations");
+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.
+ */
+function buildViroAnimationRegistry(animations) {
+    const registry = {};
+    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.
+ */
+function registerSceneAnimations(animations) {
+    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_1.ViroAnimations.registerAnimations(registry);
+    console.log(`[Studio/Animation] Registered ${Object.keys(registry).length} animation(s): ${Object.keys(registry).join(", ")}`);
+}
+function warnAnimationPerformance(anim) {
+    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;
+    if (!props || typeof props !== "object")
+        return;
+    for (const key of Object.keys(props)) {
+        const val = props[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.`);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,21 @@
+import { MutableRefObject } from "react";
+import { StudioAnimation, StudioCollisionBinding } from "../types";
+/**
+ * Dispatches scene functions for collision bindings matching the canonical pair.
+ * Cooldown prevents per-frame spam while physics contacts overlap.
+ */
+export declare function dispatchCollisionBindingActions(params: {
+    selfPlacementId: string;
+    otherTag: string;
+    bindingsByPairKey: Map<string, StudioCollisionBinding[]>;
+    sceneNavigator?: unknown;
+    animations: StudioAnimation[];
+    onSceneChange?: (sceneId: string, sceneName: string) => void;
+    onAnimationTrigger?: (targetAssetId: string, animationKey: string) => void;
+    cooldownMs?: number;
+    lastFiredRef: MutableRefObject<Map<string, number>>;
+}): void;
+/**
+ * Returns an onCollision handler for a given placement asset ID.
+ */
+export declare function createPlacementCollisionHandler(placementId: string, bindingsByPairKey: Map<string, StudioCollisionBinding[]>, sceneNavigator: unknown, animations: StudioAnimation[], lastFiredRef: MutableRefObject<Map<string, number>>, onAnimationTrigger?: (targetAssetId: string, animationKey: string) => void, onSceneChange?: (sceneId: string, sceneName: string) => void): (viroTag: string, collidedPoint: [number, number, number], collidedNormal: [number, number, number]) => void;

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

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchCollisionBindingActions = dispatchCollisionBindingActions;
+exports.createPlacementCollisionHandler = createPlacementCollisionHandler;
+const collisionPairKey_1 = require("./collisionPairKey");
+const sceneNavigationHandler_1 = require("./sceneNavigationHandler");
+const DEFAULT_COOLDOWN_MS = 750;
+function pairCooldownKey(pairKey, functionId) {
+    return `${pairKey}::${functionId}`;
+}
+/**
+ * Dispatches scene functions for collision bindings matching the canonical pair.
+ * Cooldown prevents per-frame spam while physics contacts overlap.
+ */
+function dispatchCollisionBindingActions(params) {
+    const { selfPlacementId, otherTag, bindingsByPairKey, sceneNavigator, animations, onSceneChange, onAnimationTrigger, cooldownMs = DEFAULT_COOLDOWN_MS, lastFiredRef, } = params;
+    if (!otherTag)
+        return;
+    const { asset_x_id, asset_y_id } = (0, collisionPairKey_1.canonicalizeCollisionAssetIds)(selfPlacementId, otherTag);
+    const pKey = (0, collisionPairKey_1.collisionPairKey)(asset_x_id, asset_y_id);
+    const rows = bindingsByPairKey.get(pKey);
+    if (!rows?.length)
+        return;
+    const now = Date.now();
+    const map = lastFiredRef.current;
+    for (const row of rows) {
+        const fn = row.scene_function;
+        if (!fn)
+            continue;
+        const ck = pairCooldownKey(pKey, row.function_id);
+        const last = map.get(ck) ?? 0;
+        if (now - last < cooldownMs)
+            continue;
+        map.set(ck, now);
+        (0, sceneNavigationHandler_1.executeFunctionWithRelations)(fn, sceneNavigator, animations, onAnimationTrigger, 0, onSceneChange);
+    }
+}
+/**
+ * Returns an onCollision handler for a given placement asset ID.
+ */
+function createPlacementCollisionHandler(placementId, bindingsByPairKey, sceneNavigator, animations, lastFiredRef, onAnimationTrigger, onSceneChange) {
+    return (viroTag) => {
+        dispatchCollisionBindingActions({
+            selfPlacementId: placementId,
+            otherTag: viroTag,
+            bindingsByPairKey,
+            sceneNavigator,
+            animations,
+            onSceneChange,
+            onAnimationTrigger,
+            lastFiredRef,
+        });
+    };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Canonical collision pair — matches DB constraint where asset_x_id < asset_y_id lexicographically.
+ */
+export declare function canonicalizeCollisionAssetIds(a: string, b: string): {
+    asset_x_id: string;
+    asset_y_id: string;
+};
+export declare function collisionPairKey(assetX: string, assetY: string): string;

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

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalizeCollisionAssetIds = canonicalizeCollisionAssetIds;
+exports.collisionPairKey = collisionPairKey;
+/**
+ * Canonical collision pair — matches DB constraint where asset_x_id < asset_y_id lexicographically.
+ */
+function canonicalizeCollisionAssetIds(a, b) {
+    return a < b
+        ? { asset_x_id: a, asset_y_id: b }
+        : { asset_x_id: b, asset_y_id: a };
+}
+function collisionPairKey(assetX, assetY) {
+    return `${assetX}|${assetY}`;
+}

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

@@ -0,0 +1,20 @@
+import { StudioAsset, StudioSceneMeta } from "../types";
+export type DragType = "FixedToWorld" | "FixedToPlane" | undefined;
+export type DragPlane = {
+    planePoint: [number, number, number];
+    planeNormal: [number, number, number];
+    maxDistance: number;
+};
+export declare class DragConfiguration {
+    /**
+     * Chooses FixedToPlane when the scene uses plane detection, FixedToWorld otherwise.
+     * Returns undefined if the asset is not draggable.
+     */
+    static getDragType(asset: StudioAsset, scene: StudioSceneMeta | null): DragType;
+    /**
+     * Returns a drag plane that passes through the object's current position,
+     * preventing objects from jumping on drag start. maxDistance caps how far
+     * objects can travel from the camera.
+     */
+    static getDragPlane(planeAlignment: string, objectPosition: [number, number, number]): DragPlane;
+}

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

@@ -0,0 +1,37 @@
+"use strict";
+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.
+     */
+    static getDragType(asset, scene) {
+        if (!asset.is_draggable)
+            return undefined;
+        const planeDetection = (scene?.plane_detection ?? "NONE").toUpperCase();
+        if (planeDetection === "AUTOMATIC" || planeDetection === "MANUAL") {
+            return "FixedToPlane";
+        }
+        return "FixedToWorld";
+    }
+    /**
+     * Returns a drag plane that passes through the object's current position,
+     * preventing objects from jumping on drag start. maxDistance caps how far
+     * objects can travel from the camera.
+     */
+    static getDragPlane(planeAlignment, objectPosition) {
+        switch (planeAlignment.toLowerCase()) {
+            case "horizontal":
+            case "horizontalupward":
+                return { planePoint: objectPosition, planeNormal: [0, 1, 0], maxDistance: 1.5 };
+            case "horizontaldownward":
+                return { planePoint: objectPosition, planeNormal: [0, -1, 0], maxDistance: 1.5 };
+            case "vertical":
+                return { planePoint: objectPosition, planeNormal: [0, 0, 1], maxDistance: 1.5 };
+            default:
+                return { planePoint: objectPosition, planeNormal: [0, 1, 0], maxDistance: 1.5 };
+        }
+    }
+}
+exports.DragConfiguration = DragConfiguration;

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

@@ -0,0 +1,56 @@
+/**
+ * Studio material_config parsing and Viro material definition building.
+ * Ported from studio-go/domain/materialConfig.ts — no zod dependency.
+ */
+type ShaderModifierStage = {
+    uniforms?: string;
+    body?: string;
+    varyings?: unknown;
+    requiresSceneDepth?: boolean;
+    requiresCameraTexture?: boolean;
+    priority?: unknown;
+};
+export type MaterialConfig = {
+    presetName?: string;
+    lightingModel: "Constant" | "Lambert" | "Blinn" | "Phong" | "PBR";
+    diffuseColor?: string;
+    roughness?: number;
+    metalness?: number;
+    shininess?: number;
+    alpha?: number;
+    blendMode?: string;
+    bloomThreshold?: number | null;
+    wrapS?: "Clamp" | "Repeat" | "Mirror";
+    wrapT?: "Clamp" | "Repeat" | "Mirror";
+    diffuseTexture?: string | null;
+    normalTexture?: string | null;
+    roughnessTexture?: string | null;
+    metalnessTexture?: string | null;
+    ambientOcclusionTexture?: string | null;
+    specularTexture?: string | null;
+    shaderModifiers?: Record<string, ShaderModifierStage | string>;
+    materialUniforms?: Array<{
+        name: string;
+        type: string;
+        value: unknown;
+    }>;
+    transparencyMode?: string;
+    cullMode?: string;
+};
+export type ViroMaterialDefinition = Record<string, unknown>;
+export declare function materialConfigNeedsTimeUniform(config: MaterialConfig): boolean;
+/**
+ * True if the shader uses _rf_vpw/_rf_vph viewport uniforms.
+ * These must be pushed via ViroMaterials.updateShaderUniform on mount and orientation change.
+ */
+export declare function materialConfigNeedsViewportUniforms(config: MaterialConfig): boolean;
+export declare function studioMaterialName(assetId: string): string;
+/**
+ * Parses `scene_assets.material_config` JSON. Returns null if missing or invalid.
+ */
+export declare function parseMaterialConfig(raw: unknown): MaterialConfig | null;
+/**
+ * Maps a validated Studio material_config to Viro's `createMaterials` definition shape.
+ */
+export declare function buildViroMaterialDefinition(config: MaterialConfig): ViroMaterialDefinition;
+export {};