@reactvision/react-viro 2.54.0 → 2.55.0

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTriggerImageTargets = registerTriggerImageTargets;
+exports.cleanupTriggerImageTargets = cleanupTriggerImageTargets;
+const ViroARTrackingTargets_1 = require("../../AR/ViroARTrackingTargets");
+const DEFAULT_PHYSICAL_WIDTH = 0.2; // meters
+const DEFAULT_ORIENTATION = "Up";
+/**
+ * Registers trigger image targets with ViroReact for image recognition.
+ * One target per asset with trigger_image_url.
+ * Must be called before rendering ViroARImageMarker components.
+ *
+ * @returns Map from trigger_image_url → target name for lookup in ViroARImageMarker
+ */
+function registerTriggerImageTargets(assets) {
+    const assetsWithTrigger = assets.filter((a) => !!a.trigger_image_url);
+    if (assetsWithTrigger.length === 0) {
+        return new Map();
+    }
+    const urlToTargetName = new Map();
+    const targets = {};
+    assetsWithTrigger.forEach((asset, index) => {
+        const targetName = `studio-trigger-${index}`;
+        urlToTargetName.set(asset.trigger_image_url, targetName);
+        targets[targetName] = {
+            source: { uri: asset.trigger_image_url },
+            orientation: asset.trigger_image_orientation ?? DEFAULT_ORIENTATION,
+            physicalWidth: asset.trigger_image_physical_width_m ?? DEFAULT_PHYSICAL_WIDTH,
+            type: "Image",
+        };
+    });
+    ViroARTrackingTargets_1.ViroARTrackingTargets.createTargets(targets);
+    return urlToTargetName;
+}
+/**
+ * Cleans up trigger image targets when the scene unmounts.
+ */
+function cleanupTriggerImageTargets(targetNames) {
+    targetNames.forEach((name) => {
+        try {
+            ViroARTrackingTargets_1.ViroARTrackingTargets.deleteTarget(name);
+        }
+        catch (error) {
+            console.warn(`[Studio] Failed to delete trigger target "${name}":`, error);
+        }
+    });
+}

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

@@ -0,0 +1,6 @@
+import { StudioAsset } from "../types";
+/**
+ * Drives the `time` shader uniform for materials that use animated presets.
+ * Uses `setInterval(16)` and `Date.now() % 1000000` like working Viro starter kits.
+ */
+export declare function useStudioShaderTimeUniforms(assets: StudioAsset[]): void;

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useStudioShaderTimeUniforms = useStudioShaderTimeUniforms;
+const react_1 = require("react");
+const ViroMaterials_1 = require("../../Material/ViroMaterials");
+const materialConfig_1 = require("./materialConfig");
+/** ~60fps — matches Viro starter kit / shader docs. */
+const TIME_TICK_MS = 16;
+function computeTimeUniformPayload(assets) {
+    const names = [];
+    for (const asset of assets) {
+        if (asset.asset_type_name !== "3D-MODEL")
+            continue;
+        if (asset.material_config == null)
+            continue;
+        const config = (0, materialConfig_1.parseMaterialConfig)(asset.material_config);
+        if (!config || !(0, materialConfig_1.materialConfigNeedsTimeUniform)(config))
+            continue;
+        names.push((0, materialConfig_1.studioMaterialName)(asset.id));
+    }
+    names.sort();
+    return { key: names.join("|"), names };
+}
+/**
+ * Drives the `time` shader uniform for materials that use animated presets.
+ * Uses `setInterval(16)` and `Date.now() % 1000000` like working Viro starter kits.
+ */
+function useStudioShaderTimeUniforms(assets) {
+    const payload = (0, react_1.useMemo)(() => computeTimeUniformPayload(assets), [assets]);
+    const payloadRef = (0, react_1.useRef)(payload);
+    payloadRef.current = payload;
+    const applyTimeUniforms = (0, react_1.useCallback)(() => {
+        const { names } = payloadRef.current;
+        if (names.length === 0)
+            return;
+        const time = Date.now() % 1_000_000;
+        for (const name of names) {
+            ViroMaterials_1.ViroMaterials.updateShaderUniform(name, "time", "float", time);
+        }
+    }, []);
+    (0, react_1.useEffect)(() => {
+        if (payload.names.length === 0)
+            return;
+        const id = setInterval(applyTimeUniforms, TIME_TICK_MS);
+        applyTimeUniforms();
+        return () => clearInterval(id);
+    }, [payload.key, applyTimeUniforms]);
+}

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

@@ -0,0 +1,6 @@
+import { StudioAsset } from "../types";
+/**
+ * Pushes _rf_vpw / _rf_vph (physical pixel dimensions) to materials that sample the camera
+ * feed via gl_FragCoord. Called on mount and whenever the screen dimensions change.
+ */
+export declare function useStudioShaderViewportUniforms(assets: StudioAsset[]): void;

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useStudioShaderViewportUniforms = useStudioShaderViewportUniforms;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const ViroMaterials_1 = require("../../Material/ViroMaterials");
+const materialConfig_1 = require("./materialConfig");
+function computeViewportPayload(assets) {
+    const names = [];
+    for (const asset of assets) {
+        if (asset.asset_type_name !== "3D-MODEL")
+            continue;
+        if (asset.material_config == null)
+            continue;
+        const config = (0, materialConfig_1.parseMaterialConfig)(asset.material_config);
+        if (!config || !(0, materialConfig_1.materialConfigNeedsViewportUniforms)(config))
+            continue;
+        names.push((0, materialConfig_1.studioMaterialName)(asset.id));
+    }
+    names.sort();
+    return { key: names.join("|"), names };
+}
+/**
+ * Pushes _rf_vpw / _rf_vph (physical pixel dimensions) to materials that sample the camera
+ * feed via gl_FragCoord. Called on mount and whenever the screen dimensions change.
+ */
+function useStudioShaderViewportUniforms(assets) {
+    const payload = (0, react_1.useMemo)(() => computeViewportPayload(assets), [assets]);
+    const pushViewport = (0, react_1.useCallback)(() => {
+        if (payload.names.length === 0)
+            return;
+        const { width, height } = react_native_1.Dimensions.get("screen");
+        const pr = react_native_1.PixelRatio.get();
+        const pw = width * pr;
+        const ph = height * pr;
+        for (const name of payload.names) {
+            ViroMaterials_1.ViroMaterials.updateShaderUniform(name, "_rf_vpw", "float", pw);
+            ViroMaterials_1.ViroMaterials.updateShaderUniform(name, "_rf_vph", "float", ph);
+        }
+    }, [payload]);
+    (0, react_1.useEffect)(() => {
+        if (payload.names.length === 0)
+            return;
+        pushViewport();
+        const sub = react_native_1.Dimensions.addEventListener("change", pushViewport);
+        return () => sub.remove();
+    }, [payload.key, pushViewport]);
+}

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

@@ -0,0 +1,28 @@
+import * as React from "react";
+import { StudioAnimation, StudioAsset, StudioSceneMeta, ViroAnimationProp } from "../types";
+type SceneNavigator = any;
+export type NodeConfig = {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+    dragType?: "FixedDistance" | "FixedDistanceOrigin" | "FixedToWorld" | "FixedToPlane";
+    dragPlane?: {
+        planePoint: [number, number, number];
+        planeNormal: [number, number, number];
+        maxDistance: number;
+    };
+    physicsBody?: Record<string, unknown>;
+    viroTag?: string;
+    onClick?: () => void;
+    animation?: ViroAnimationProp;
+};
+/**
+ * Derives the transform config for an asset.
+ * Clamps Z to -2 for non-trigger assets to guarantee visibility.
+ */
+export declare function createNodeConfig(asset: StudioAsset, sceneNavigator: SceneNavigator | undefined, animations: StudioAnimation[], scene: StudioSceneMeta | null, onAnimationTrigger?: (targetAssetId: string, animKey: string) => void, animationStates?: Record<string, ViroAnimationProp>, onSceneChange?: (sceneId: string, sceneName: string) => void): NodeConfig;
+/**
+ * Creates the appropriate Viro component for a StudioAsset.
+ */
+export declare function createNode(asset: StudioAsset, sceneNavigator: SceneNavigator | undefined, animations: StudioAnimation[], scene: StudioSceneMeta | null, onAnimationTrigger?: (targetAssetId: string, animKey: string) => void, animationStates?: Record<string, ViroAnimationProp>, onAssetLoaded?: (id: string) => void, onCollision?: (viroTag: string, collidedPoint: [number, number, number], collidedNormal: [number, number, number]) => void, onSceneChange?: (sceneId: string, sceneName: string) => void): React.ReactElement | null;
+export {};

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

@@ -0,0 +1,193 @@
+"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.createNodeConfig = createNodeConfig;
+exports.createNode = createNode;
+const React = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const Viro3DObject_1 = require("../../Viro3DObject");
+const ViroImage_1 = require("../../ViroImage");
+const ViroText_1 = require("../../ViroText");
+const ViroVideo_1 = require("../../ViroVideo");
+const sceneNavigationHandler_1 = require("./sceneNavigationHandler");
+const materialConfig_1 = require("./materialConfig");
+const dragConfiguration_1 = require("./dragConfiguration");
+const physicsConfig_1 = require("./physicsConfig");
+/**
+ * Derives the transform config for an asset.
+ * Clamps Z to -2 for non-trigger assets to guarantee visibility.
+ */
+function createNodeConfig(asset, sceneNavigator, animations, scene, onAnimationTrigger, animationStates, onSceneChange) {
+    const hasTriggerImage = !!asset.trigger_image_url;
+    let posZ = asset.position_z ?? -2;
+    if (!hasTriggerImage && posZ > -0.5) {
+        console.warn(`[Studio/NodeFactory] Asset "${asset.name}" Z=${posZ} too close, clamping to -2`);
+        posZ = -2;
+    }
+    const position = [
+        asset.position_x ?? 0,
+        asset.position_y ?? 0,
+        posZ,
+    ];
+    // Apply trigger image orientation offset to rotation Z
+    let rotationZ = asset.rotation_z ?? 0;
+    if (hasTriggerImage && asset.trigger_image_orientation) {
+        const offsets = {
+            Left: -90,
+            Right: 90,
+            Down: 180,
+            Up: 0,
+        };
+        rotationZ += offsets[asset.trigger_image_orientation] ?? 0;
+    }
+    const rotation = [
+        asset.rotation_x ?? 0,
+        asset.rotation_y ?? 0,
+        rotationZ,
+    ];
+    let scaleValue = asset.scale ?? 1;
+    if (scaleValue < 0.01)
+        scaleValue = 0.1;
+    if (scaleValue > 10)
+        scaleValue = 2;
+    const scale = [scaleValue, scaleValue, scaleValue];
+    const dragType = dragConfiguration_1.DragConfiguration.getDragType(asset, scene);
+    let dragPlane;
+    if (dragType === "FixedToPlane") {
+        dragPlane = dragConfiguration_1.DragConfiguration.getDragPlane(scene?.plane_direction ?? "Horizontal", position);
+    }
+    const parsedPhysics = (0, physicsConfig_1.parsePhysicsBodyConfig)(asset.physics_config);
+    const physicsBody = parsedPhysics ? (0, physicsConfig_1.buildViroPhysicsBody)(parsedPhysics) : undefined;
+    const viroTag = parsedPhysics ? asset.id : undefined;
+    const onClick = createOnClickHandler(asset, sceneNavigator, animations, onAnimationTrigger, onSceneChange);
+    const animation = animationStates?.[asset.id];
+    return { position, rotation, scale, dragType, dragPlane, physicsBody, viroTag, onClick, animation };
+}
+function createOnClickHandler(asset, sceneNavigator, animations, onAnimationTrigger, onSceneChange) {
+    const fn = asset.scene_function;
+    if (!fn)
+        return undefined;
+    if (fn.function_type === "NAVIGATION" && !fn.scene_navigation?.navigate_to) {
+        console.warn(`[Studio] Asset "${asset.name}" has NAVIGATION but no target scene`);
+        return undefined;
+    }
+    if (fn.function_type === "ALERT" && !fn.scene_alert) {
+        console.warn(`[Studio] Asset "${asset.name}" has ALERT but no alert data`);
+        return undefined;
+    }
+    if (fn.function_type === "ANIMATION" && !fn.scene_animation) {
+        console.warn(`[Studio] Asset "${asset.name}" has ANIMATION but no animation data`);
+        return undefined;
+    }
+    return () => (0, sceneNavigationHandler_1.executeFunctionWithRelations)(fn, sceneNavigator, animations, onAnimationTrigger, 0, onSceneChange);
+}
+/** Resolves asset type from asset_type_name. */
+function resolveType(asset) {
+    return asset.asset_type_name ?? null;
+}
+/** Infers 3D model format from file extension. */
+function inferModelType(url) {
+    const ext = url.toLowerCase().split(".").pop();
+    if (ext === "gltf")
+        return "GLTF";
+    if (ext === "obj")
+        return "OBJ";
+    if (ext === "vrx")
+        return "VRX";
+    return "GLB";
+}
+function create3DObject(asset, config, onAssetLoaded, onCollision) {
+    if (!asset.file_url) {
+        console.warn(`[Studio] 3D model "${asset.name}" has no file_url`);
+        return null;
+    }
+    const modelType = inferModelType(asset.file_url);
+    // Android: slightly reduce scale for stability
+    const scale = react_native_1.Platform.OS === "android"
+        ? [
+            config.scale[0] * 0.8,
+            config.scale[1] * 0.8,
+            config.scale[2] * 0.8,
+        ]
+        : config.scale;
+    const hasMaterialConfig = (0, materialConfig_1.parseMaterialConfig)(asset.material_config) !== null;
+    const shaderOverrides = hasMaterialConfig ? [(0, materialConfig_1.studioMaterialName)(asset.id)] : undefined;
+    return (<Viro3DObject_1.Viro3DObject key={asset.id} source={{ uri: asset.file_url }} position={config.position} rotation={config.rotation} scale={scale} type={modelType} dragType={config.dragType} dragPlane={config.dragPlane} animation={config.animation} onClick={config.onClick} renderingOrder={react_native_1.Platform.OS === "android" ? 1 : 0} onLoadEnd={() => onAssetLoaded?.(asset.id)} onError={(e) => console.error(`[Studio] 3D model "${asset.name}" error:`, e)} 
+    // Viro derives native canDrag from `onDrag != undefined`; without this prop
+    // the drag recognizer is never attached, even when dragType is set.
+    {...(config.dragType ? { onDrag: () => { } } : {})} {...(shaderOverrides ? { shaderOverrides } : {})} {...(config.physicsBody ? { physicsBody: config.physicsBody, viroTag: config.viroTag } : {})} {...(onCollision ? { onCollision: onCollision } : {})}/>);
+}
+function createImage(asset, config, onAssetLoaded) {
+    if (!asset.file_url) {
+        console.warn(`[Studio] Image "${asset.name}" has no file_url`);
+        return null;
+    }
+    return (<ViroImage_1.ViroImage key={asset.id} source={{ uri: asset.file_url }} position={config.position} rotation={config.rotation} scale={config.scale} dragType={config.dragType} animation={config.animation} onClick={config.onClick} onLoadEnd={() => onAssetLoaded?.(asset.id)} onError={(e) => console.error(`[Studio] Image "${asset.name}" error:`, e)} {...(config.dragType ? { onDrag: () => { } } : {})}/>);
+}
+function createText(asset, config) {
+    return (<ViroText_1.ViroText key={asset.id} text={asset.name ?? ""} position={config.position} rotation={config.rotation} scale={config.scale} dragType={config.dragType} animation={config.animation} onClick={config.onClick} style={{
+            fontFamily: "Arial",
+            fontSize: 20,
+            color: "#FFFFFF",
+            textAlign: "center",
+        }} {...(config.dragType ? { onDrag: () => { } } : {})}/>);
+}
+function createVideo(asset, config) {
+    if (!asset.file_url) {
+        console.warn(`[Studio] Video "${asset.name}" has no file_url`);
+        return null;
+    }
+    return (<ViroVideo_1.ViroVideo key={asset.id} source={{ uri: asset.file_url }} position={config.position} rotation={config.rotation} scale={config.scale} dragType={config.dragType} animation={config.animation} onClick={config.onClick} loop={true} muted={false} onError={(e) => console.error(`[Studio] Video "${asset.name}" error:`, e)} {...(config.dragType ? { onDrag: () => { } } : {})}/>);
+}
+/**
+ * Creates the appropriate Viro component for a StudioAsset.
+ */
+function createNode(asset, sceneNavigator, animations, scene, onAnimationTrigger, animationStates, onAssetLoaded, onCollision, onSceneChange) {
+    const type = resolveType(asset);
+    const config = createNodeConfig(asset, sceneNavigator, animations, scene, onAnimationTrigger, animationStates, onSceneChange);
+    switch (type) {
+        case "3D-MODEL":
+            return create3DObject(asset, config, onAssetLoaded, onCollision);
+        case "IMAGE":
+            return createImage(asset, config, onAssetLoaded);
+        case "TEXT":
+            return createText(asset, config);
+        case "VIDEO":
+            return createVideo(asset, config);
+        default:
+            console.warn(`[Studio] Unknown asset type "${type}" for "${asset.name}"`);
+            return null;
+    }
+}

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

@@ -0,0 +1,3 @@
+export { StudioARScene } from "./StudioARScene";
+export { StudioSceneNavigator } from "./StudioSceneNavigator";
+export type { StudioAnimation, StudioAsset, StudioCollisionBinding, StudioProjectApiResponse, StudioProjectAsset, StudioProjectMeta, StudioProjectOpeningScene, StudioProjectOverview, StudioProjectSceneSummary, StudioSceneCreatedBy, StudioSceneFunction, StudioSceneMeta, StudioSceneResponse, ViroAnimationProp, } from "./types";

package/dist/components/Studio/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StudioSceneNavigator = exports.StudioARScene = void 0;
+var StudioARScene_1 = require("./StudioARScene");
+Object.defineProperty(exports, "StudioARScene", { enumerable: true, get: function () { return StudioARScene_1.StudioARScene; } });
+var StudioSceneNavigator_1 = require("./StudioSceneNavigator");
+Object.defineProperty(exports, "StudioSceneNavigator", { enumerable: true, get: function () { return StudioSceneNavigator_1.StudioSceneNavigator; } });

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

@@ -0,0 +1,149 @@
+export interface StudioSceneCreatedBy {
+    id: string;
+    first_name: string | null;
+    last_name: string | null;
+}
+export interface StudioSceneMeta {
+    id: string;
+    name: string | null;
+    belongs_to_project: string;
+    plane_detection: string | null;
+    plane_direction: string | null;
+    on_load_function: string | null;
+    physics_world_config: Record<string, unknown> | null;
+    created_at: string;
+    created_by: StudioSceneCreatedBy | null;
+}
+export interface StudioProjectMeta {
+    id: string;
+    occlusion_mode: "NONE" | "PEOPLEONLY" | "DEPTHBASED";
+}
+export interface StudioSceneFunction {
+    id: string;
+    scene: string;
+    function_type: "NAVIGATION" | "ALERT" | "ANIMATION";
+    navigation: string | null;
+    alert: string | null;
+    animation: string | null;
+    scene_navigation: {
+        id: string;
+        navigate_to: string;
+    } | null;
+    scene_alert: {
+        id: string;
+        alert_title: string | null;
+        alert_message: string | null;
+    } | null;
+    scene_animation: {
+        id: string;
+        animation_key: string;
+        duration_ms: number | null;
+        delay_ms: number | null;
+        properties: Record<string, unknown>;
+    } | null;
+}
+export interface StudioAsset {
+    id: string;
+    name: string | null;
+    description: string | null;
+    file_url: string | null;
+    file_size: number | null;
+    asset_type_name: "3D-MODEL" | "TEXT" | "IMAGE" | "VIDEO" | null;
+    position_x: number | null;
+    position_y: number | null;
+    position_z: number | null;
+    rotation_x: number | null;
+    rotation_y: number | null;
+    rotation_z: number | null;
+    scale: number | null;
+    latitude: number | null;
+    longitude: number | null;
+    is_draggable: boolean;
+    trigger_image_url: string | null;
+    trigger_image_orientation: "Up" | "Down" | "Left" | "Right" | null;
+    trigger_image_physical_width_m: number | null;
+    material_config: Record<string, unknown> | null;
+    physics_config: Record<string, unknown> | null;
+    on_click_function: string | null;
+    asset_id: string | null;
+    created_at: string;
+    updated_at: string;
+    scene_function: StudioSceneFunction | null;
+}
+export interface StudioCollisionBinding {
+    id: string;
+    scene_id: string;
+    function_id: string;
+    asset_x_id: string;
+    asset_y_id: string;
+    scene_function: StudioSceneFunction;
+}
+export interface StudioAnimation {
+    id: string;
+    scene_id: string;
+    target_asset_id: string;
+    animation_key: string;
+    properties: Record<string, unknown>;
+    duration_ms: number | null;
+    delay_ms: number | null;
+    easing: "Linear" | "EaseIn" | "EaseOut" | "EaseInEaseOut" | "Bounce" | null;
+    loop: boolean;
+    interruptible: boolean;
+    on_start_function: string | null;
+    on_finish_function: string | null;
+}
+export interface StudioProjectAsset {
+    id: string;
+    name: string | null;
+    url: string | null;
+}
+export interface StudioProjectSceneSummary {
+    id: string;
+    name: string | null;
+    created_at: string;
+    created_by: StudioSceneCreatedBy | null;
+    assets: StudioProjectAsset[];
+}
+export interface StudioProjectOpeningScene {
+    id: string;
+    name: string | null;
+}
+export interface StudioProjectOverview {
+    id: string;
+    name: string;
+    thumbnail: string | null;
+    occlusion_mode: "NONE" | "PEOPLEONLY" | "DEPTHBASED";
+    created_at: string;
+    created_by: StudioSceneCreatedBy | null;
+    opening_scene: StudioProjectOpeningScene | null;
+    scenes: StudioProjectSceneSummary[];
+}
+/** Top-level response from GET /functions/v1/projects/{project_id} (after JSON.parse) */
+export interface StudioProjectApiResponse {
+    project: StudioProjectOverview;
+    meta: {
+        request_id: string;
+    };
+}
+/** Top-level response from GET /functions/v1/scenes/{scene_id} (after JSON.parse) */
+export interface StudioSceneResponse {
+    scene: StudioSceneMeta;
+    project: StudioProjectMeta;
+    assets: StudioAsset[];
+    collision_bindings: StudioCollisionBinding[];
+    animations: StudioAnimation[];
+    functions: StudioSceneFunction[];
+    meta: {
+        request_id: string;
+    };
+}
+/** Viro animation prop shape passed to Viro components */
+export type ViroAnimationProp = {
+    name: string;
+    run: boolean;
+    loop: boolean;
+    interruptible: boolean;
+    delay: number;
+    onStart?: () => void;
+    onFinish?: () => void;
+};

package/dist/components/Studio/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// Types mirror the actual server response from GET /functions/v1/scenes/{scene_id}.
+// Field names are snake_case as returned by the Supabase Edge Function / Postgres RPC.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/components/Types/ViroEvents.d.ts

@@ -100,7 +100,8 @@ export type ViroPlatformInfo = {
 };
 export declare enum ViroPlatformTypes {
     GVR = "gvr",
-    GEAR_VR = "ovr-mobile"
+    GEAR_VR = "ovr-mobile",
+    QUEST = "quest"
 }
 export declare enum ViroHeadsetTypes {
     CARDBOARD = "cardboard",
@@ -135,6 +136,53 @@ export type ViroExitViroEvent = {};
 export type ViroErrorEvent = {
     error: Error;
 };
+/** ===========================================================================
+ * Quest / OpenXR Hand Tracking Types (M4)
+ * ============================================================================ */
+export type ViroJoint = {
+    position: Viro3DPoint;
+    /** Sphere radius representing finger pad size (meters). */
+    radius: number;
+};
+export type ViroHandJoints = {
+    wrist: ViroJoint;
+    thumbMetacarpal: ViroJoint;
+    thumbProximal: ViroJoint;
+    thumbDistal: ViroJoint;
+    thumbTip: ViroJoint;
+    indexMetacarpal: ViroJoint;
+    indexProximal: ViroJoint;
+    indexIntermediate: ViroJoint;
+    indexDistal: ViroJoint;
+    indexTip: ViroJoint;
+    middleMetacarpal: ViroJoint;
+    middleProximal: ViroJoint;
+    middleIntermediate: ViroJoint;
+    middleDistal: ViroJoint;
+    middleTip: ViroJoint;
+    ringMetacarpal: ViroJoint;
+    ringProximal: ViroJoint;
+    ringIntermediate: ViroJoint;
+    ringDistal: ViroJoint;
+    ringTip: ViroJoint;
+    littleMetacarpal: ViroJoint;
+    littleProximal: ViroJoint;
+    littleIntermediate: ViroJoint;
+    littleDistal: ViroJoint;
+    littleTip: ViroJoint;
+};
+export type ViroHandPinchEvent = {
+    hand: "left" | "right";
+    /** World-space position of the pinch point (midpoint between thumb tip and index tip). */
+    position: Viro3DPoint;
+    /** Pinch strength [0..1] from XR_FB_hand_tracking_aim, or 1.0 on pinch-complete fallback. */
+    pinchStrength: number;
+};
+/** Per-frame skeletal hand data dispatched via onHandUpdate. null when hand is not tracked. */
+export type ViroHandUpdateEvent = {
+    left: ViroHandJoints | null;
+    right: ViroHandJoints | null;
+};
 /** ===========================================================================
  * Viro Animation Events
  * ============================================================================ */

package/dist/components/Types/ViroEvents.js

@@ -35,6 +35,7 @@ var ViroPlatformTypes;
 (function (ViroPlatformTypes) {
     ViroPlatformTypes["GVR"] = "gvr";
     ViroPlatformTypes["GEAR_VR"] = "ovr-mobile";
+    ViroPlatformTypes["QUEST"] = "quest";
 })(ViroPlatformTypes || (exports.ViroPlatformTypes = ViroPlatformTypes = {}));
 var ViroHeadsetTypes;
 (function (ViroHeadsetTypes) {

package/dist/components/Utilities/VRModuleOpenXR.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Finishes VRActivity and returns the user to the panel (MainActivity).
+ * Safe to call on any platform — no-op when VRLauncher is unavailable.
+ */
+export declare function exitVRScene(): void;
+export type VRModuleOpenXRType = {
+    recenterTracking?: (viewTag: number) => void;
+    setPassthroughEnabled?: (viewTag: number, enabled: boolean) => void;
+};
+/**
+ * Typed reference to the VRModuleOpenXR native module.
+ * undefined when not running on Meta Quest (no-op calls are safe via optional chaining).
+ */
+export declare const VRModuleOpenXR: VRModuleOpenXRType | undefined;
+/**
+ * Returns the live viewTag of the ViroVRSceneNavigator running in VRActivity,
+ * kept in sync via VRQuestNavigatorBridge.  null until ViroQuestEntryPoint has
+ * mounted and published the tag.
+ *
+ * Use this inside VR scenes when you need to call VRModuleOpenXR methods:
+ *
+ * ```tsx
+ * function MyVRScene() {
+ *   const viewTag = useVRViewTag();
+ *   const recenter = () => {
+ *     if (viewTag != null) VRModuleOpenXR?.recenterTracking?.(viewTag);
+ *   };
+ *   return <ViroScene>...</ViroScene>;
+ * }
+ * ```
+ */
+export declare function useVRViewTag(): number | null;