@reactvision/react-viro 2.56.0 → 2.57.2

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

@@ -0,0 +1,52 @@
+/**
+ * Last-resort cap on how long a step waits for a non-looping PLAY to finish. A
+ * clip that fails to load fires onError (released at once); a clip whose native
+ * finish/error event is dropped or never arrives would otherwise stall the walk
+ * forever, so the manager force-releases the waiter after this many ms.
+ * Generous on purpose: it must outlast any realistic single clip so it never
+ * cuts one short, only catches a genuine stall.
+ */
+export declare const SOUND_WAIT_BACKSTOP_MS: number;
+/** One actively-playing sound, keyed in the manager by its monotonic playId. */
+export type StudioSoundEntry = {
+    playId: number;
+    audioAssetId: string;
+    url: string;
+    position?: [number, number, number];
+    volume: number;
+    loop: boolean;
+};
+/**
+ * Per-scene sound store. PLAY adds an entry under a fresh playId; STOP removes
+ * by audio asset id (null = all). The whole <StudioSounds> list re-renders on
+ * any change, so subscribers are GLOBAL like StudioVariableStore (not per-key).
+ */
+export declare class StudioSoundManager {
+    private sounds;
+    private listeners;
+    private nextPlayId;
+    private finishCallbacks;
+    private finishTimers;
+    /** Subscribe to any add/remove; returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    getActive(): StudioSoundEntry[];
+    /** Pull and invoke the stored completion callback (if any) for a playId. */
+    private fire;
+    /**
+     * Adds a sound and returns its playId. onFinish (when given) resolves a step
+     * waiting on a non-looping PLAY; it fires on natural finish or early stop.
+     */
+    play(entry: {
+        audioAssetId: string;
+        url: string;
+        position?: [number, number, number];
+        volume: number;
+        loop: boolean;
+        stopOthers: boolean;
+    }, onFinish?: () => void): number;
+    /** null = stop all sounds; otherwise stop every entry for this audio asset. */
+    stop(audioAssetId: string | null): void;
+    /** Drop one entry; onFinish calls this for non-looping sounds. */
+    remove(playId: number): void;
+    reset(): void;
+}

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

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StudioSoundManager = exports.SOUND_WAIT_BACKSTOP_MS = void 0;
+const utils_1 = require("./utils");
+/**
+ * Last-resort cap on how long a step waits for a non-looping PLAY to finish. A
+ * clip that fails to load fires onError (released at once); a clip whose native
+ * finish/error event is dropped or never arrives would otherwise stall the walk
+ * forever, so the manager force-releases the waiter after this many ms.
+ * Generous on purpose: it must outlast any realistic single clip so it never
+ * cuts one short, only catches a genuine stall.
+ */
+exports.SOUND_WAIT_BACKSTOP_MS = 5 * 60 * 1000;
+/**
+ * Per-scene sound store. PLAY adds an entry under a fresh playId; STOP removes
+ * by audio asset id (null = all). The whole <StudioSounds> list re-renders on
+ * any change, so subscribers are GLOBAL like StudioVariableStore (not per-key).
+ */
+class StudioSoundManager {
+    sounds = new Map();
+    listeners = new utils_1.GlobalListeners();
+    nextPlayId = 1;
+    // Per-playId completion callback for a step waiting on a non-looping PLAY.
+    // Fired on natural finish (via remove) AND when the sound is cut short by a
+    // stop/stopOthers/reset, so a waited-on sound never stalls the walk.
+    finishCallbacks = new Map();
+    // Backstop timer per waited playId; cleared whenever its callback fires so a
+    // sound whose native finish/error event never arrives can't stall the walk.
+    finishTimers = new Map();
+    /** Subscribe to any add/remove; returns an unsubscribe fn. */
+    subscribe(listener) {
+        return this.listeners.subscribe(listener);
+    }
+    getActive() {
+        return [...this.sounds.values()];
+    }
+    /** Pull and invoke the stored completion callback (if any) for a playId. */
+    fire(playId) {
+        const timer = this.finishTimers.get(playId);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            this.finishTimers.delete(playId);
+        }
+        const cb = this.finishCallbacks.get(playId);
+        if (!cb)
+            return;
+        this.finishCallbacks.delete(playId);
+        cb();
+    }
+    /**
+     * Adds a sound and returns its playId. onFinish (when given) resolves a step
+     * waiting on a non-looping PLAY; it fires on natural finish or early stop.
+     */
+    play(entry, onFinish) {
+        // stopOthers clears the live list; fire any pending waiters for the cleared
+        // entries so a displaced waited-on sound resolves instead of stalling.
+        if (entry.stopOthers) {
+            const cleared = [...this.sounds.keys()];
+            this.sounds.clear();
+            for (const id of cleared)
+                this.fire(id);
+        }
+        const playId = this.nextPlayId++;
+        this.sounds.set(playId, {
+            playId,
+            audioAssetId: entry.audioAssetId,
+            url: entry.url,
+            position: entry.position,
+            volume: entry.volume,
+            loop: entry.loop,
+        });
+        if (onFinish) {
+            this.finishCallbacks.set(playId, onFinish);
+            // Non-looping waited sound: arm the stall backstop. A looping sound is
+            // never awaited, so it gets no timer.
+            if (!entry.loop) {
+                this.finishTimers.set(playId, setTimeout(() => this.remove(playId), exports.SOUND_WAIT_BACKSTOP_MS));
+            }
+        }
+        if ((0, utils_1.isDev)()) {
+            console.log(`[Studio] Sound play "${entry.audioAssetId}" (#${playId})`);
+        }
+        this.listeners.notify();
+        return playId;
+    }
+    /** null = stop all sounds; otherwise stop every entry for this audio asset. */
+    stop(audioAssetId) {
+        const removed = [];
+        for (const [id, e] of this.sounds) {
+            if (audioAssetId === null || e.audioAssetId === audioAssetId) {
+                this.sounds.delete(id);
+                removed.push(id);
+            }
+        }
+        this.listeners.notify();
+        // Resolve any waiters cut short by the stop.
+        for (const id of removed)
+            this.fire(id);
+    }
+    /** Drop one entry; onFinish calls this for non-looping sounds. */
+    remove(playId) {
+        if (this.sounds.delete(playId))
+            this.listeners.notify();
+        // Fire the stored callback whether or not the entry was still present
+        // (natural finish path: resolves the waiting step).
+        this.fire(playId);
+    }
+    reset() {
+        const pending = [...this.finishCallbacks.keys()];
+        this.sounds.clear();
+        this.listeners.notify();
+        // Belt-and-suspenders: the runtime's generation guard no-ops these after a
+        // scene-change cancelAll, but fire so nothing leaks on bare resets.
+        for (const id of pending)
+            this.fire(id);
+    }
+}
+exports.StudioSoundManager = StudioSoundManager;

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

@@ -0,0 +1,16 @@
+/** True only in a dev build; gates verbose runtime logging in the Studio stores. */
+export declare const isDev: () => boolean;
+/** A set of subscribers notified together (variable + sound stores). */
+export declare class GlobalListeners {
+    private listeners;
+    subscribe(listener: () => void): () => void;
+    notify(): void;
+}
+/** Subscribers partitioned by key; notify(key) wakes only that key's set
+ * (the visibility store's per-asset variant). */
+export declare class KeyedListeners {
+    private listeners;
+    subscribe(key: string, listener: () => void): () => void;
+    notify(key: string): void;
+    notifyAll(): void;
+}

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

@@ -0,0 +1,48 @@
+"use strict";
+// Small shared helpers for the Studio runtime domain.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyedListeners = exports.GlobalListeners = exports.isDev = void 0;
+/** True only in a dev build; gates verbose runtime logging in the Studio stores. */
+const isDev = () => typeof __DEV__ !== "undefined" && __DEV__;
+exports.isDev = isDev;
+/** A set of subscribers notified together (variable + sound stores). */
+class GlobalListeners {
+    listeners = new Set();
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify() {
+        // Snapshot first: a listener may (un)subscribe during its own callback.
+        [...this.listeners].forEach((fn) => fn());
+    }
+}
+exports.GlobalListeners = GlobalListeners;
+/** Subscribers partitioned by key; notify(key) wakes only that key's set
+ * (the visibility store's per-asset variant). */
+class KeyedListeners {
+    listeners = new Map();
+    subscribe(key, listener) {
+        let set = this.listeners.get(key);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(key, set);
+        }
+        set.add(listener);
+        return () => {
+            set?.delete(listener);
+        };
+    }
+    notify(key) {
+        // Snapshot first: a listener may (un)subscribe during its own callback.
+        const set = this.listeners.get(key);
+        if (set)
+            [...set].forEach((fn) => fn());
+    }
+    notifyAll() {
+        this.listeners.forEach((set) => [...set].forEach((fn) => fn()));
+    }
+}
+exports.KeyedListeners = KeyedListeners;

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

@@ -0,0 +1,21 @@
+import { StudioSceneVariable } from "../types";
+import { StudioVariableValue } from "./expressionEvaluator";
+/**
+ * Per-session variable store. One instance is owned by the navigator and
+ * survives scene pushes; it resets only when the AR/VR session ends.
+ *
+ * Identity is by NAME: scenes declaring the same name share one value, and
+ * seed() only initialises names not already present (initialize-if-absent),
+ * so values carry across scene transitions.
+ */
+export declare class StudioVariableStore {
+    private values;
+    private listeners;
+    get(name: string): StudioVariableValue | undefined;
+    /** Subscribe to value changes (set/reset); returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    set(name: string, value: StudioVariableValue): void;
+    seed(declarations: StudioSceneVariable[]): void;
+    reset(): void;
+    snapshot(): Record<string, StudioVariableValue>;
+}

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

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StudioVariableStore = void 0;
+const expressionEvaluator_1 = require("./expressionEvaluator");
+const utils_1 = require("./utils");
+/**
+ * Per-session variable store. One instance is owned by the navigator and
+ * survives scene pushes; it resets only when the AR/VR session ends.
+ *
+ * Identity is by NAME: scenes declaring the same name share one value, and
+ * seed() only initialises names not already present (initialize-if-absent),
+ * so values carry across scene transitions.
+ */
+class StudioVariableStore {
+    values = new Map();
+    listeners = new utils_1.GlobalListeners();
+    get(name) {
+        return this.values.get(name);
+    }
+    /** Subscribe to value changes (set/reset); returns an unsubscribe fn. */
+    subscribe(listener) {
+        return this.listeners.subscribe(listener);
+    }
+    set(name, value) {
+        // Values are primitives; skip the no-op write so unchanged values don't
+        // log or wake subscribers.
+        if (Object.is(this.values.get(name), value))
+            return;
+        this.values.set(name, value);
+        if ((0, utils_1.isDev)()) {
+            console.log(`[Studio] Variable "${name}" =`, value);
+        }
+        this.listeners.notify();
+    }
+    seed(declarations) {
+        for (const decl of declarations) {
+            if (!decl?.name)
+                continue;
+            if (!(0, expressionEvaluator_1.valueMatchesType)(decl.initial_value, decl.type)) {
+                console.warn(`[Studio] Variable "${decl.name}": initial value does not match type ${decl.type}; skipping seed.`);
+                continue;
+            }
+            const existing = this.values.get(decl.name);
+            if (existing !== undefined) {
+                if (!(0, expressionEvaluator_1.valueMatchesType)(existing, decl.type)) {
+                    console.warn(`[Studio] Variable "${decl.name}" already holds a ${typeof existing} this session, but this scene declares ${decl.type}; keeping the existing value.`);
+                }
+                continue;
+            }
+            this.values.set(decl.name, decl.initial_value);
+        }
+    }
+    reset() {
+        this.values.clear();
+        this.listeners.notify();
+    }
+    snapshot() {
+        const out = {};
+        this.values.forEach((value, name) => {
+            out[name] = value;
+        });
+        return out;
+    }
+}
+exports.StudioVariableStore = StudioVariableStore;

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

@@ -1,5 +1,6 @@
 import * as React from "react";
 import { StudioAnimation, StudioAsset, StudioSceneMeta, ViroAnimationProp } from "../types";
+import { SequenceRuntimeContext } from "./sceneNavigationHandler";
 type SceneNavigator = any;
 export type NodeConfig = {
     position: [number, number, number];
@@ -16,13 +17,7 @@ export type NodeConfig = {
     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;
+/** 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, runtimeCtx?: SequenceRuntimeContext): NodeConfig;
+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, runtimeCtx?: SequenceRuntimeContext): React.ReactElement | null;
 export {};

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

@@ -42,14 +42,12 @@ const ViroImage_1 = require("../../ViroImage");
 const ViroText_1 = require("../../ViroText");
 const ViroVideo_1 = require("../../ViroVideo");
 const sceneNavigationHandler_1 = require("./sceneNavigationHandler");
+const apiRequestHelpers_1 = require("./apiRequestHelpers");
 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) {
+/** Clamps Z to -2 for non-trigger assets to guarantee visibility. */
+function createNodeConfig(asset, sceneNavigator, animations, scene, onAnimationTrigger, animationStates, onSceneChange, runtimeCtx) {
     const hasTriggerImage = !!asset.trigger_image_url;
     let posZ = asset.position_z ?? -2;
     if (!hasTriggerImage && posZ > -0.5) {
@@ -89,13 +87,25 @@ function createNodeConfig(asset, sceneNavigator, animations, scene, onAnimationT
         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 physicsBody = parsedPhysics
+        ? (0, physicsConfig_1.buildViroPhysicsBody)(parsedPhysics)
+        : undefined;
     const viroTag = parsedPhysics ? asset.id : undefined;
-    const onClick = createOnClickHandler(asset, sceneNavigator, animations, onAnimationTrigger, onSceneChange);
+    const onClick = createOnClickHandler(asset, sceneNavigator, animations, onAnimationTrigger, onSceneChange, runtimeCtx);
     const animation = animationStates?.[asset.id];
-    return { position, rotation, scale, dragType, dragPlane, physicsBody, viroTag, onClick, animation };
+    return {
+        position,
+        rotation,
+        scale,
+        dragType,
+        dragPlane,
+        physicsBody,
+        viroTag,
+        onClick,
+        animation,
+    };
 }
-function createOnClickHandler(asset, sceneNavigator, animations, onAnimationTrigger, onSceneChange) {
+function createOnClickHandler(asset, sceneNavigator, animations, onAnimationTrigger, onSceneChange, runtimeCtx) {
     const fn = asset.scene_function;
     if (!fn)
         return undefined;
@@ -111,13 +121,11 @@ function createOnClickHandler(asset, sceneNavigator, animations, onAnimationTrig
         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);
+    return () => (0, sceneNavigationHandler_1.executeFunctionWithRelations)(fn, sceneNavigator, animations, onAnimationTrigger, 0, onSceneChange, runtimeCtx);
 }
-/** 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")
@@ -143,11 +151,15 @@ function create3DObject(asset, config, onAssetLoaded, onCollision) {
         ]
         : config.scale;
     const hasMaterialConfig = (0, materialConfig_1.parseMaterialConfig)(asset.material_config) !== null;
-    const shaderOverrides = hasMaterialConfig ? [(0, materialConfig_1.studioMaterialName)(asset.id)] : undefined;
+    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 } : {})}/>);
+    {...(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) {
@@ -156,13 +168,51 @@ function createImage(asset, config, onAssetLoaded) {
     }
     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={{
+/**
+ * TEXT node whose content is a {{variable}} template (the asset name). It
+ * re-interpolates and repaints whenever a referenced variable changes (and only
+ * subscribes when the template actually has placeholders). Resolution is
+ * fail-soft: unknown names stay literal.
+ */
+const VariableText = ({ asset, config, store, visible }) => {
+    const template = asset.name ?? "";
+    const compute = () => store
+        ? (0, apiRequestHelpers_1.interpolateDisplayTemplate)(template, (n) => store.get(n))
+        : template;
+    const [text, setText] = React.useState(compute);
+    React.useEffect(() => {
+        if (!store || (0, apiRequestHelpers_1.extractPlaceholders)(template).length === 0)
+            return;
+        // Resync any write that landed between first render and subscribe.
+        setText(compute());
+        return store.subscribe(() => setText(compute()));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store, template]);
+    return (<ViroText_1.ViroText text={text} position={config.position} rotation={config.rotation} scale={config.scale} dragType={config.dragType} animation={config.animation} onClick={config.onClick} {...(visible === undefined ? {} : { visible })} style={{
             fontFamily: "Arial",
             fontSize: 20,
             color: "#FFFFFF",
             textAlign: "center",
         }} {...(config.dragType ? { onDrag: () => { } } : {})}/>);
+};
+/**
+ * Wraps a created node and drives its `visible` prop from the per-scene
+ * visibility store, subscribing to its own asset so a Set Visibility action
+ * repaints only this node. Without a store, the node stays visible.
+ */
+const VisibleNode = ({ assetId, store, children }) => {
+    const [visible, setVisible] = React.useState(() => store?.isVisible(assetId) ?? true);
+    React.useEffect(() => {
+        if (!store)
+            return;
+        // Resync any write that landed between first render and subscribe.
+        setVisible(store.isVisible(assetId));
+        return store.subscribe(assetId, () => setVisible(store.isVisible(assetId)));
+    }, [store, assetId]);
+    return React.cloneElement(children, { visible });
+};
+function createText(asset, config, store) {
+    return (<VariableText key={asset.id} asset={asset} config={config} store={store}/>);
 }
 function createVideo(asset, config) {
     if (!asset.file_url) {
@@ -171,23 +221,32 @@ function createVideo(asset, config) {
     }
     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) {
+function createNode(asset, sceneNavigator, animations, scene, onAnimationTrigger, animationStates, onAssetLoaded, onCollision, onSceneChange, runtimeCtx) {
     const type = resolveType(asset);
-    const config = createNodeConfig(asset, sceneNavigator, animations, scene, onAnimationTrigger, animationStates, onSceneChange);
+    const config = createNodeConfig(asset, sceneNavigator, animations, scene, onAnimationTrigger, animationStates, onSceneChange, runtimeCtx);
+    let node;
     switch (type) {
         case "3D-MODEL":
-            return create3DObject(asset, config, onAssetLoaded, onCollision);
+            node = create3DObject(asset, config, onAssetLoaded, onCollision);
+            break;
         case "IMAGE":
-            return createImage(asset, config, onAssetLoaded);
+            node = createImage(asset, config, onAssetLoaded);
+            break;
         case "TEXT":
-            return createText(asset, config);
+            node = createText(asset, config, runtimeCtx?.variableStore);
+            break;
         case "VIDEO":
-            return createVideo(asset, config);
+            node = createVideo(asset, config);
+            break;
         default:
             console.warn(`[Studio] Unknown asset type "${type}" for "${asset.name}"`);
             return null;
     }
+    if (!node)
+        return null;
+    // Drive show/hide/toggle from the visibility store (Set Visibility actions);
+    // seeded from the asset's author-time hidden_on_load default.
+    return (<VisibleNode key={asset.id} assetId={asset.id} store={runtimeCtx?.visibilityStore}>
+      {node}
+    </VisibleNode>);
 }

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

@@ -0,0 +1,33 @@
+import { StudioAsset } from "../types";
+/**
+ * Per-scene visibility store, keyed by scene asset placement id. Seeded from
+ * each asset's author-time `hidden_on_load` default at scene load; Set
+ * Visibility actions then flip the live value. Toggle reads the current value
+ * here, never the author default.
+ *
+ * Listeners are per-asset (unlike the global variable store) so a Set
+ * Visibility on one object repaints only that node, not the whole scene. Node
+ * factories subscribe to their own asset id.
+ */
+export declare class StudioVisibilityStore {
+    private visible;
+    private listeners;
+    /** Current visibility; defaults to visible for assets never seeded/set. */
+    isVisible(assetId: string): boolean;
+    /** Subscribe to changes for one asset; returns an unsubscribe fn. */
+    subscribe(assetId: string, listener: () => void): () => void;
+    /** Initialise-if-absent from author-time defaults (idempotent, strict-mode safe). */
+    seed(assets: StudioAsset[]): void;
+    /**
+     * Apply a Set Visibility action. TOGGLE flips the live value; VISIBLE/HIDDEN
+     * set it absolutely. No-op writes don't wake subscribers.
+     */
+    apply(assetId: string, state: "VISIBLE" | "HIDDEN" | "TOGGLE"): void;
+    /**
+     * Re-initialise for a new scene: replace all values from author-time
+     * defaults, THEN notify every subscribed asset so mounted nodes re-read.
+     * Order matters — notifying before re-seeding would briefly surface the
+     * visible default for an asset that starts hidden.
+     */
+    reseed(assets: StudioAsset[]): void;
+}

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

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StudioVisibilityStore = void 0;
+const utils_1 = require("./utils");
+/**
+ * Per-scene visibility store, keyed by scene asset placement id. Seeded from
+ * each asset's author-time `hidden_on_load` default at scene load; Set
+ * Visibility actions then flip the live value. Toggle reads the current value
+ * here, never the author default.
+ *
+ * Listeners are per-asset (unlike the global variable store) so a Set
+ * Visibility on one object repaints only that node, not the whole scene. Node
+ * factories subscribe to their own asset id.
+ */
+class StudioVisibilityStore {
+    visible = new Map();
+    listeners = new utils_1.KeyedListeners();
+    /** Current visibility; defaults to visible for assets never seeded/set. */
+    isVisible(assetId) {
+        return this.visible.get(assetId) ?? true;
+    }
+    /** Subscribe to changes for one asset; returns an unsubscribe fn. */
+    subscribe(assetId, listener) {
+        return this.listeners.subscribe(assetId, listener);
+    }
+    /** Initialise-if-absent from author-time defaults (idempotent, strict-mode safe). */
+    seed(assets) {
+        for (const asset of assets) {
+            if (!asset?.id)
+                continue;
+            if (this.visible.has(asset.id))
+                continue;
+            this.visible.set(asset.id, !asset.hidden_on_load);
+        }
+    }
+    /**
+     * Apply a Set Visibility action. TOGGLE flips the live value; VISIBLE/HIDDEN
+     * set it absolutely. No-op writes don't wake subscribers.
+     */
+    apply(assetId, state) {
+        const next = state === "TOGGLE" ? !this.isVisible(assetId) : state === "VISIBLE";
+        if (this.visible.get(assetId) === next)
+            return;
+        this.visible.set(assetId, next);
+        if ((0, utils_1.isDev)()) {
+            console.log(`[Studio] Visibility "${assetId}" =`, next);
+        }
+        this.listeners.notify(assetId);
+    }
+    /**
+     * Re-initialise for a new scene: replace all values from author-time
+     * defaults, THEN notify every subscribed asset so mounted nodes re-read.
+     * Order matters — notifying before re-seeding would briefly surface the
+     * visible default for an asset that starts hidden.
+     */
+    reseed(assets) {
+        this.visible.clear();
+        for (const asset of assets) {
+            if (!asset?.id)
+                continue;
+            this.visible.set(asset.id, !asset.hidden_on_load);
+        }
+        this.listeners.notifyAll();
+    }
+}
+exports.StudioVisibilityStore = StudioVisibilityStore;

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

@@ -1,3 +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";
+export type { StudioAnimation, StudioAsset, StudioCollisionBinding, StudioProjectApiResponse, StudioProjectAsset, StudioProjectMeta, StudioProjectOpeningScene, StudioProjectOverview, StudioProjectSceneSummary, StudioSceneCreatedBy, StudioSceneFunction, StudioSceneMeta, StudioSceneResponse, StudioSceneVariable, ViroAnimationProp, } from "./types";