@reactvision/react-viro 2.56.0 → 2.57.2

package/components/Studio/domain/soundManager.ts

@@ -0,0 +1,141 @@
+import { GlobalListeners, isDev } from "./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.
+ */
+export const SOUND_WAIT_BACKSTOP_MS = 5 * 60 * 1000;
+
+/** 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 class StudioSoundManager {
+  private sounds = new Map<number, StudioSoundEntry>();
+  private listeners = new GlobalListeners();
+  private 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.
+  private finishCallbacks = new Map<number, () => void>();
+  // 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.
+  private finishTimers = new Map<number, ReturnType<typeof setTimeout>>();
+
+  /** Subscribe to any add/remove; returns an unsubscribe fn. */
+  subscribe(listener: () => void): () => void {
+    return this.listeners.subscribe(listener);
+  }
+
+  getActive(): StudioSoundEntry[] {
+    return [...this.sounds.values()];
+  }
+
+  /** Pull and invoke the stored completion callback (if any) for a playId. */
+  private fire(playId: number): void {
+    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: {
+      audioAssetId: string;
+      url: string;
+      position?: [number, number, number];
+      volume: number;
+      loop: boolean;
+      stopOthers: boolean;
+    },
+    onFinish?: () => void
+  ): number {
+    // 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), SOUND_WAIT_BACKSTOP_MS)
+        );
+      }
+    }
+    if (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: string | null): void {
+    const removed: number[] = [];
+    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: number): void {
+    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(): void {
+    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);
+  }
+}

package/components/Studio/domain/utils.ts

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

package/components/Studio/domain/variableStore.ts

@@ -0,0 +1,74 @@
+import { StudioSceneVariable } from "../types";
+import {
+  StudioVariableValue,
+  valueMatchesType,
+} from "./expressionEvaluator";
+import { GlobalListeners, isDev } from "./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.
+ */
+export class StudioVariableStore {
+  private values = new Map<string, StudioVariableValue>();
+  private listeners = new GlobalListeners();
+
+  get(name: string): StudioVariableValue | undefined {
+    return this.values.get(name);
+  }
+
+  /** Subscribe to value changes (set/reset); returns an unsubscribe fn. */
+  subscribe(listener: () => void): () => void {
+    return this.listeners.subscribe(listener);
+  }
+
+  set(name: string, value: StudioVariableValue): void {
+    // 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 (isDev()) {
+      console.log(`[Studio] Variable "${name}" =`, value);
+    }
+    this.listeners.notify();
+  }
+
+  seed(declarations: StudioSceneVariable[]): void {
+    for (const decl of declarations) {
+      if (!decl?.name) continue;
+      if (!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 (!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(): void {
+    this.values.clear();
+    this.listeners.notify();
+  }
+
+  snapshot(): Record<string, StudioVariableValue> {
+    const out: Record<string, StudioVariableValue> = {};
+    this.values.forEach((value, name) => {
+      out[name] = value;
+    });
+    return out;
+  }
+}

package/components/Studio/domain/viroNodeFactory.tsx

@@ -4,11 +4,25 @@ import { Viro3DObject } from "../../Viro3DObject";
 import { ViroImage } from "../../ViroImage";
 import { ViroText } from "../../ViroText";
 import { ViroVideo } from "../../ViroVideo";
-import { StudioAnimation, StudioAsset, StudioSceneMeta, ViroAnimationProp } from "../types";
-import { executeFunctionWithRelations } from "./sceneNavigationHandler";
+import {
+  StudioAnimation,
+  StudioAsset,
+  StudioSceneMeta,
+  ViroAnimationProp,
+} from "../types";
+import {
+  executeFunctionWithRelations,
+  SequenceRuntimeContext,
+} from "./sceneNavigationHandler";
+import {
+  extractPlaceholders,
+  interpolateDisplayTemplate,
+} from "./apiRequestHelpers";
 import { parseMaterialConfig, studioMaterialName } from "./materialConfig";
 import { DragConfiguration } from "./dragConfiguration";
 import { buildViroPhysicsBody, parsePhysicsBodyConfig } from "./physicsConfig";
+import { StudioVariableStore } from "./variableStore";
+import { StudioVisibilityStore } from "./visibilityStore";
 
 type SceneNavigator = any;
 
@@ -16,18 +30,23 @@ 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 };
+  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.
- */
+/** Clamps Z to -2 for non-trigger assets to guarantee visibility. */
 export function createNodeConfig(
   asset: StudioAsset,
   sceneNavigator: SceneNavigator | undefined,
@@ -35,7 +54,8 @@ export function createNodeConfig(
   scene: StudioSceneMeta | null,
   onAnimationTrigger?: (targetAssetId: string, animKey: string) => void,
   animationStates?: Record<string, ViroAnimationProp>,
-  onSceneChange?: (sceneId: string, sceneName: string) => void
+  onSceneChange?: (sceneId: string, sceneName: string) => void,
+  runtimeCtx?: SequenceRuntimeContext
 ): NodeConfig {
   const hasTriggerImage = !!asset.trigger_image_url;
 
@@ -82,12 +102,14 @@ export function createNodeConfig(
   if (dragType === "FixedToPlane") {
     dragPlane = DragConfiguration.getDragPlane(
       scene?.plane_direction ?? "Horizontal",
-      position,
+      position
     );
   }
 
   const parsedPhysics = parsePhysicsBodyConfig(asset.physics_config);
-  const physicsBody = parsedPhysics ? buildViroPhysicsBody(parsedPhysics) : undefined;
+  const physicsBody = parsedPhysics
+    ? buildViroPhysicsBody(parsedPhysics)
+    : undefined;
   const viroTag = parsedPhysics ? asset.id : undefined;
 
   const onClick = createOnClickHandler(
@@ -95,12 +117,23 @@ export function createNodeConfig(
     sceneNavigator,
     animations,
     onAnimationTrigger,
-    onSceneChange
+    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(
@@ -108,13 +141,16 @@ function createOnClickHandler(
   sceneNavigator: SceneNavigator | undefined,
   animations: StudioAnimation[],
   onAnimationTrigger?: (targetAssetId: string, animKey: string) => void,
-  onSceneChange?: (sceneId: string, sceneName: string) => void
+  onSceneChange?: (sceneId: string, sceneName: string) => void,
+  runtimeCtx?: SequenceRuntimeContext
 ): (() => void) | undefined {
   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`);
+    console.warn(
+      `[Studio] Asset "${asset.name}" has NAVIGATION but no target scene`
+    );
     return undefined;
   }
   if (fn.function_type === "ALERT" && !fn.scene_alert) {
@@ -122,22 +158,30 @@ function createOnClickHandler(
     return undefined;
   }
   if (fn.function_type === "ANIMATION" && !fn.scene_animation) {
-    console.warn(`[Studio] Asset "${asset.name}" has ANIMATION but no animation data`);
+    console.warn(
+      `[Studio] Asset "${asset.name}" has ANIMATION but no animation data`
+    );
     return undefined;
   }
 
   return () =>
-    executeFunctionWithRelations(fn, sceneNavigator, animations, onAnimationTrigger, 0, onSceneChange);
+    executeFunctionWithRelations(
+      fn,
+      sceneNavigator,
+      animations,
+      onAnimationTrigger,
+      0,
+      onSceneChange,
+      runtimeCtx
+    );
 }
 
-/** Resolves asset type from asset_type_name. */
 function resolveType(
   asset: StudioAsset
 ): "3D-MODEL" | "TEXT" | "IMAGE" | "VIDEO" | null {
   return asset.asset_type_name ?? null;
 }
 
-/** Infers 3D model format from file extension. */
 function inferModelType(url: string): "GLB" | "GLTF" | "OBJ" | "VRX" {
   const ext = url.toLowerCase().split(".").pop();
   if (ext === "gltf") return "GLTF";
@@ -150,7 +194,11 @@ function create3DObject(
   asset: StudioAsset,
   config: NodeConfig,
   onAssetLoaded?: (id: string) => void,
-  onCollision?: (viroTag: string, collidedPoint: [number, number, number], collidedNormal: [number, number, number]) => void
+  onCollision?: (
+    viroTag: string,
+    collidedPoint: [number, number, number],
+    collidedNormal: [number, number, number]
+  ) => void
 ): React.ReactElement | null {
   if (!asset.file_url) {
     console.warn(`[Studio] 3D model "${asset.name}" has no file_url`);
@@ -170,7 +218,9 @@ function create3DObject(
       : config.scale;
 
   const hasMaterialConfig = parseMaterialConfig(asset.material_config) !== null;
-  const shaderOverrides = hasMaterialConfig ? [studioMaterialName(asset.id)] : undefined;
+  const shaderOverrides = hasMaterialConfig
+    ? [studioMaterialName(asset.id)]
+    : undefined;
 
   return (
     <Viro3DObject
@@ -193,7 +243,9 @@ function create3DObject(
       // the drag recognizer is never attached, even when dragType is set.
       {...(config.dragType ? { onDrag: () => {} } : {})}
       {...(shaderOverrides ? { shaderOverrides } : {})}
-      {...(config.physicsBody ? { physicsBody: config.physicsBody as any, viroTag: config.viroTag } : {})}
+      {...(config.physicsBody
+        ? { physicsBody: config.physicsBody as any, viroTag: config.viroTag }
+        : {})}
       {...(onCollision ? { onCollision: onCollision as any } : {})}
     />
   );
@@ -220,28 +272,51 @@ function createImage(
       animation={config.animation as any}
       onClick={config.onClick}
       onLoadEnd={() => onAssetLoaded?.(asset.id)}
-      onError={(e) =>
-        console.error(`[Studio] Image "${asset.name}" error:`, e)
-      }
+      onError={(e) => console.error(`[Studio] Image "${asset.name}" error:`, e)}
       {...(config.dragType ? { onDrag: () => {} } : {})}
     />
   );
 }
 
-function createText(
-  asset: StudioAsset,
-  config: NodeConfig
-): React.ReactElement {
+/**
+ * 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: React.FC<{
+  asset: StudioAsset;
+  config: NodeConfig;
+  store?: StudioVariableStore;
+  // Injected by VisibleNode via cloneElement; TEXT is the only node type that
+  // is a component wrapper, so it forwards visibility to its ViroText.
+  visible?: boolean;
+}> = ({ asset, config, store, visible }) => {
+  const template = asset.name ?? "";
+  const compute = () =>
+    store
+      ? interpolateDisplayTemplate(template, (n) => store.get(n))
+      : template;
+  const [text, setText] = React.useState(compute);
+
+  React.useEffect(() => {
+    if (!store || 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
-      key={asset.id}
-      text={asset.name ?? ""}
+      text={text}
       position={config.position}
       rotation={config.rotation}
       scale={config.scale}
       dragType={config.dragType}
       animation={config.animation as any}
       onClick={config.onClick}
+      {...(visible === undefined ? {} : { visible })}
       style={{
         fontFamily: "Arial",
         fontSize: 20,
@@ -251,6 +326,42 @@ function createText(
       {...(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: React.FC<{
+  assetId: string;
+  store?: StudioVisibilityStore;
+  // Props typed loosely so cloneElement can inject `visible` (all Viro node
+  // types accept it via ViroCommonProps).
+  children: React.ReactElement<any>;
+}> = ({ 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: StudioAsset,
+  config: NodeConfig,
+  store?: StudioVariableStore
+): React.ReactElement {
+  return (
+    <VariableText key={asset.id} asset={asset} config={config} store={store} />
+  );
 }
 
 function createVideo(
@@ -274,17 +385,12 @@ function createVideo(
       onClick={config.onClick}
       loop={true}
       muted={false}
-      onError={(e) =>
-        console.error(`[Studio] Video "${asset.name}" error:`, e)
-      }
+      onError={(e) => console.error(`[Studio] Video "${asset.name}" error:`, e)}
       {...(config.dragType ? { onDrag: () => {} } : {})}
     />
   );
 }
 
-/**
- * Creates the appropriate Viro component for a StudioAsset.
- */
 export function createNode(
   asset: StudioAsset,
   sceneNavigator: SceneNavigator | undefined,
@@ -293,8 +399,13 @@ export function createNode(
   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
+  onCollision?: (
+    viroTag: string,
+    collidedPoint: [number, number, number],
+    collidedNormal: [number, number, number]
+  ) => void,
+  onSceneChange?: (sceneId: string, sceneName: string) => void,
+  runtimeCtx?: SequenceRuntimeContext
 ): React.ReactElement | null {
   const type = resolveType(asset);
   const config = createNodeConfig(
@@ -304,20 +415,40 @@ export function createNode(
     scene,
     onAnimationTrigger,
     animationStates,
-    onSceneChange
+    onSceneChange,
+    runtimeCtx
   );
 
+  let node: React.ReactElement | null;
   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>
+  );
 }