@reactvision/react-viro 2.54.0 → 2.55.0

package/components/Studio/types.ts

@@ -0,0 +1,164 @@
+// 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.
+
+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; // 'AUTOMATIC' | 'MANUAL' | 'NONE'
+  plane_direction: string | null; // 'Horizontal' | 'Vertical'
+  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; // scene asset placement ID
+  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; // radians
+  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; // UUID → look up in functions[]
+  asset_id: string | null; // team asset type UUID
+  created_at: string;
+  updated_at: string;
+  scene_function: StudioSceneFunction | null; // resolved on_click_function inline
+}
+
+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; // ViroAnimations registry key
+  properties: Record<string, unknown>; // Viro keyframe format
+  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/components/Types/ViroEvents.ts

@@ -134,6 +134,7 @@ export type ViroPlatformInfo = {
 export enum ViroPlatformTypes {
   GVR = "gvr",
   GEAR_VR = "ovr-mobile",
+  QUEST = "quest",
 }
 
 export enum ViroHeadsetTypes {
@@ -176,6 +177,58 @@ 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/components/Utilities/VRModuleOpenXR.ts

@@ -0,0 +1,50 @@
+import { useEffect, useState } from "react";
+import { NativeModules } from "react-native";
+import { VRQuestNavigatorBridge } from "./VRQuestNavigatorBridge";
+
+/**
+ * Finishes VRActivity and returns the user to the panel (MainActivity).
+ * Safe to call on any platform — no-op when VRLauncher is unavailable.
+ */
+export function exitVRScene(): void {
+  VRQuestNavigatorBridge.setVRActive(false);
+  (NativeModules.VRLauncher as { exitVRScene?: () => void } | undefined)
+    ?.exitVRScene?.();
+}
+
+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 const VRModuleOpenXR =
+  (NativeModules.VRModuleOpenXR as VRModuleOpenXRType | undefined) ?? 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 function useVRViewTag(): number | null {
+  const [tag, setTag] = useState<number | null>(
+    () => VRQuestNavigatorBridge.getViewTag()
+  );
+  useEffect(() => VRQuestNavigatorBridge.onViewTag(setTag), []);
+  return tag;
+}

package/components/Utilities/VRQuestNavigatorBridge.ts

@@ -0,0 +1,168 @@
+/**
+ * VRQuestNavigatorBridge
+ *
+ * Carries VR "intents" and navigator operations from panel-Activity component
+ * trees to VRActivity. Both activities run in the same process and share the
+ * same Hermes JS engine, so a module-level store is sufficient — no native
+ * round-trip needed.
+ *
+ * Flow:
+ *   Panel (MainActivity)
+ *     ViroXRSceneNavigator mounts
+ *       → setIntent(scene, config)  — stores intent, notifies ViroQuestEntryPoint
+ *       → launchVRScene()           — OS switches to VRActivity
+ *       → ref.push(StudioScene)     — dispatchOp() queues the op
+ *
+ *   VRActivity mounts VRQuestScene → ViroQuestEntryPoint
+ *       → onIntent cb fires      — reads intentKey + initialScene + rendererConfig
+ *       → renders ViroVRSceneNavigator key={intentKey}  (fresh mount per intent)
+ *       → ViroQuestEntryPoint captures viewTag → setViewTag()
+ *       → subscribeOps() drains queued ops  — push(StudioScene) arrives
+ *
+ * Each call to setIntent() generates a new intentKey.  ViroQuestEntryPoint
+ * uses key={intentKey} on ViroVRSceneNavigator, guaranteeing a clean navigator
+ * stack whenever a different panel screen activates VR.
+ */
+
+export type VRNavigatorOp =
+  | { type: "push"; scene: any }
+  | { type: "pop" }
+  | { type: "popN"; n: number }
+  | { type: "replace"; scene: any }
+  | { type: "jump"; scene: any };
+
+/** Renderer flags forwarded from ViroXRSceneNavigator to ViroVRSceneNavigator. */
+export type VRQuestRendererConfig = {
+  hdrEnabled?: boolean;
+  pbrEnabled?: boolean;
+  bloomEnabled?: boolean;
+  shadowsEnabled?: boolean;
+  multisamplingEnabled?: boolean;
+  vrModeEnabled?: boolean;
+  passthroughEnabled?: boolean;
+  handTrackingEnabled?: boolean;
+  debug?: boolean;
+  onExitViro?: () => void;
+};
+
+export type VRQuestIntent = {
+  intentKey: string;
+  initialScene: any;
+  rendererConfig?: VRQuestRendererConfig;
+};
+
+// ── Intent store ────────────────────────────────────────────────────────────
+
+let _intent: VRQuestIntent | null = null;
+const _intentListeners = new Set<(intent: VRQuestIntent) => void>();
+
+// ── Op queue ─────────────────────────────────────────────────────────────────
+
+const _opListeners = new Set<(op: VRNavigatorOp) => void>();
+const _opQueue: VRNavigatorOp[] = [];
+
+let _opCounter = 0;
+
+// ── VR active flag ────────────────────────────────────────────────────────────
+// True while VRActivity is running. Set to true just before launchVRScene(),
+// set to false by exitVRScene(). The AppState-based relaunch in
+// ViroXRSceneNavigator checks this so it only fires for system-level
+// backgrounding (Quest menu / home), not for explicit exits.
+
+let _vrActive = false;
+
+// ── ViewTag store ─────────────────────────────────────────────────────────────
+// ViroQuestEntryPoint populates this after ViroVRSceneNavigator mounts.
+// Panel-side code (e.g. VRModuleOpenXR.recenterTracking) reads it to target
+// the live native view without needing a direct ref to ViroVRSceneNavigator.
+
+let _viewTag: number | null = null;
+const _viewTagListeners = new Set<(tag: number | null) => void>();
+
+export const VRQuestNavigatorBridge = {
+  // ── Called by ViroXRSceneNavigator when mounting on Quest ──────────────────
+
+  /**
+   * Record the scene and renderer config that VRActivity should use, and
+   * return a unique intent key. Call launchVRScene() after this.
+   */
+  setIntent(initialScene: any, rendererConfig?: VRQuestRendererConfig): string {
+    const intentKey = `vr-${Date.now()}-${++_opCounter}`;
+    _intent = { intentKey, initialScene, rendererConfig };
+    // Clear any stale ops from the previous intent.
+    _opQueue.length = 0;
+    _intentListeners.forEach((l) => l(_intent!));
+    return intentKey;
+  },
+
+  /** Current intent (may be null if VR has never been launched). */
+  getIntent(): VRQuestIntent | null {
+    return _intent;
+  },
+
+  /**
+   * Subscribe to intent changes. Fires immediately with the current intent if
+   * one exists so that ViroQuestEntryPoint can render even if it mounts after
+   * setIntent() was called.
+   */
+  onIntent(cb: (intent: VRQuestIntent) => void): () => void {
+    _intentListeners.add(cb);
+    if (_intent) cb(_intent);
+    return () => {
+      _intentListeners.delete(cb);
+    };
+  },
+
+  // ── Called by ViroXRSceneNavigator ref (push / pop / etc.) ────────────────
+
+  dispatchOp(op: VRNavigatorOp): void {
+    if (_opListeners.size > 0) {
+      _opListeners.forEach((l) => l(op));
+    } else {
+      _opQueue.push(op);
+    }
+  },
+
+  // ── Called by ViroQuestEntryPoint after ViroVRSceneNavigator mounts ────────
+
+  subscribeOps(cb: (op: VRNavigatorOp) => void): () => void {
+    _opListeners.add(cb);
+    const pending = _opQueue.splice(0);
+    pending.forEach((op) => cb(op));
+    return () => {
+      _opListeners.delete(cb);
+    };
+  },
+
+  // ── VR active flag ────────────────────────────────────────────────────────
+  setVRActive(active: boolean): void {
+    _vrActive = active;
+  },
+  isVRActive(): boolean {
+    return _vrActive;
+  },
+
+  // ── ViewTag — native node handle of the live ViroVRSceneNavigator ──────────
+
+  setViewTag(tag: number | null): void {
+    _viewTag = tag;
+    _viewTagListeners.forEach((l) => l(tag));
+  },
+
+  getViewTag(): number | null {
+    return _viewTag;
+  },
+
+  /**
+   * Subscribe to viewTag changes. Fires immediately with the current value.
+   * Use this inside VR scenes that need VRModuleOpenXR (recenterTracking,
+   * setPassthroughEnabled) without a direct ref to ViroVRSceneNavigator.
+   */
+  onViewTag(cb: (tag: number | null) => void): () => void {
+    _viewTagListeners.add(cb);
+    cb(_viewTag);
+    return () => {
+      _viewTagListeners.delete(cb);
+    };
+  },
+};

package/components/Utilities/ViroPlatform.ts

@@ -0,0 +1,52 @@
+import { NativeModules, Platform } from "react-native";
+
+type AndroidBuildInfo = {
+  Manufacturer?: string;
+  Brand?: string;
+  Model?: string;
+};
+
+/**
+ * True only on actual Meta Quest hardware (Quest 1/2/Pro/3/3S).
+ *
+ * Detection is based on `Platform.constants` (Android `Build.MANUFACTURER`,
+ * `BRAND`, `MODEL`) — NOT on the presence of `NativeModules.VRModuleOpenXR`.
+ * The OpenXR module ships with any app built against the Quest variant of
+ * react-viro and is therefore present on regular Android phones too when the
+ * same APK targets both phone and Quest. Branding strings are the
+ * authoritative signal for "is the user wearing a Quest right now".
+ *
+ * Quest 1/2/Pro:  Manufacturer="Oculus", Brand="oculus"
+ * Quest 3/3S:     Manufacturer="Meta",   Brand="meta"
+ */
+function detectQuest(): boolean {
+  if (Platform.OS !== "android") return false;
+  const c = (Platform.constants ?? {}) as AndroidBuildInfo;
+  const manufacturer = (c.Manufacturer ?? "").toLowerCase();
+  const brand = (c.Brand ?? "").toLowerCase();
+  const model = (c.Model ?? "").toLowerCase();
+
+  if (
+    manufacturer === "oculus" ||
+    manufacturer === "meta" ||
+    brand === "oculus" ||
+    brand === "meta"
+  ) {
+    return true;
+  }
+  // Defensive: future hardware shipping under new manufacturer strings.
+  return /\bquest\b/.test(model);
+}
+
+export const isQuest: boolean = detectQuest();
+
+/**
+ * True when this app build includes the OpenXR VR native module (i.e. the
+ * Quest variant of react-viro is registered in `MainApplication`). Does NOT
+ * imply the current device is a Quest — for that, use `isQuest`.
+ *
+ * Useful when you need to decide whether `ViroVRSceneNavigator` *could* render
+ * if you forced VR mode (e.g., for in-app build diagnostics).
+ */
+export const hasOpenXRSupport: boolean =
+  NativeModules.VRModuleOpenXR !== undefined;

package/components/Utilities/ViroVersion.ts

@@ -1 +1 @@
-export const VIRO_VERSION = "2.54.0";
+export const VIRO_VERSION = "2.55.0";

package/components/Utilities/useAnySourceHover.ts

@@ -0,0 +1,55 @@
+import { useCallback, useRef, useState } from "react";
+
+import type { Viro3DPoint } from "../Types/ViroUtils";
+
+/**
+ * Aggregate `onHover` state across all input sources.
+ *
+ * On Quest (and any other backend that supports multiple simultaneous
+ * pointers — e.g. left + right controllers, or controller + tracked hand),
+ * Viro fires the node's `onHover` callback **per source**. A second pointer
+ * sweeping over an already-hovered node would otherwise produce spurious
+ * enter/exit toggles in JS even though the visual hover should remain "on".
+ *
+ * This hook tracks each source ID independently and exposes a single
+ * aggregated boolean — `true` whenever **any** source is hovering the node.
+ * Apps that don't care about per-source distinction (the common case for
+ * UI buttons) can just consume the boolean.
+ *
+ * Usage:
+ * ```tsx
+ * function MyButton() {
+ *   const [hovered, onHover] = useAnySourceHover();
+ *   return (
+ *     <ViroNode onHover={onHover}>
+ *       <ViroQuad materials={[hovered ? "btnHover" : "btnIdle"]} ... />
+ *     </ViroNode>
+ *   );
+ * }
+ * ```
+ *
+ * The handler signature matches Viro's `onHover` prop directly — pass it as
+ * `onHover={onHover}` with no wrapper. Internally the hook deduplicates per
+ * source so a sequence of `(true, …, src=A)` events from the same source
+ * produces at most one re-render.
+ */
+export function useAnySourceHover(): readonly [
+  boolean,
+  (isHovering: boolean, position: Viro3DPoint, source: unknown) => void,
+] {
+  const sourcesRef = useRef<Record<string, boolean>>({});
+  const [hovered, setHovered] = useState(false);
+
+  const onHover = useCallback(
+    (isHovering: boolean, _position: Viro3DPoint, source: unknown) => {
+      const key = String(source ?? "default");
+      if (sourcesRef.current[key] === isHovering) return;
+      sourcesRef.current[key] = isHovering;
+      const any = Object.values(sourcesRef.current).some(Boolean);
+      setHovered(any);
+    },
+    []
+  );
+
+  return [hovered, onHover] as const;
+}

package/components/Utilities/useAnySourcePressed.ts

@@ -0,0 +1,70 @@
+import { useCallback, useRef, useState } from "react";
+
+import {
+  ViroClickState,
+  ViroClickStateTypes,
+} from "../Types/ViroEvents";
+import type { Viro3DPoint } from "../Types/ViroUtils";
+
+/**
+ * Aggregate `onClickState` "is being pressed" state across all input sources.
+ *
+ * Mirror of `useAnySourceHover` for clicks. Tracks per-source `CLICK_DOWN` /
+ * `CLICK_UP` events from any input source (right + left controllers / hands)
+ * and returns a single aggregated boolean — `true` whenever **any** source
+ * is currently holding the trigger / pinch on this node.
+ *
+ * The fully-completed `CLICKED` event is intentionally ignored here: it is
+ * informational ("a complete click happened") and shouldn't toggle the
+ * held-state. Apps that need the click event itself can use the regular
+ * `onClick` prop — those callbacks already pass the `source`.
+ *
+ * Usage:
+ * ```tsx
+ * function MyButton() {
+ *   const [pressed, onClickState] = useAnySourcePressed();
+ *   return (
+ *     <ViroNode onClickState={onClickState} onClick={...}>
+ *       <ViroQuad
+ *         scale={pressed ? [0.95, 0.95, 0.95] : [1, 1, 1]}
+ *         materials={[pressed ? "btnPressed" : "btnIdle"]}
+ *       />
+ *     </ViroNode>
+ *   );
+ * }
+ * ```
+ *
+ * Internally deduplicates per source so a sequence of `(CLICK_DOWN, src=A)`
+ * events from the same source produces at most one re-render.
+ */
+export function useAnySourcePressed(): readonly [
+  boolean,
+  (clickState: ViroClickState, position: Viro3DPoint, source: unknown) => void,
+] {
+  const sourcesRef = useRef<Record<string, boolean>>({});
+  const [pressed, setPressed] = useState(false);
+
+  const onClickState = useCallback(
+    (clickState: ViroClickState, _position: Viro3DPoint, source: unknown) => {
+      let next: boolean;
+      if (clickState === ViroClickStateTypes.CLICK_DOWN) {
+        next = true;
+      } else if (clickState === ViroClickStateTypes.CLICK_UP) {
+        next = false;
+      } else {
+        // CLICKED is fired between DOWN and UP for completed clicks —
+        // doesn't change held state, ignore.
+        return;
+      }
+
+      const key = String(source ?? "default");
+      if (sourcesRef.current[key] === next) return;
+      sourcesRef.current[key] = next;
+      const any = Object.values(sourcesRef.current).some(Boolean);
+      setPressed(any);
+    },
+    []
+  );
+
+  return [pressed, onClickState] as const;
+}