@reactvision/react-viro 2.53.1 → 2.55.0

package/dist/plugins/withViroAndroid.js

@@ -46,9 +46,9 @@ const withBranchAndroid = (config) => {
                 const viroPlugin = config?.plugins?.find((plugin) => Array.isArray(plugin) && plugin[0] === "@reactvision/react-viro");
                 if (Array.isArray(viroPlugin)) {
                     if (Array.isArray(viroPlugin[1].android?.xRMode)) {
-                        viroPluginConfig = (viroPlugin[1].android?.xRMode).filter((mode) => ["AR", "GVR", "OVR_MOBILE"].includes(mode));
+                        viroPluginConfig = (viroPlugin[1].android?.xRMode).filter((mode) => ["AR", "GVR", "OVR_MOBILE", "QUEST"].includes(mode));
                     }
-                    else if (["AR", "GVR", "OVR_MOBILE"].includes(viroPlugin[1]?.android?.xRMode)) {
+                    else if (["AR", "GVR", "OVR_MOBILE", "QUEST"].includes(viroPlugin[1]?.android?.xRMode)) {
                         viroPluginConfig = [viroPlugin[1]?.android.xRMode];
                     }
                 }
@@ -197,6 +197,14 @@ const withViroManifest = (config) => (0, config_plugins_1.withAndroidManifest)(c
                 },
             });
         }
+        if (pluginOptions.rvEndpoint) {
+            contents?.manifest?.application?.[0]["meta-data"]?.push({
+                $: {
+                    "android:name": "com.reactvision.RVEndpoint",
+                    "android:value": pluginOptions.rvEndpoint,
+                },
+            });
+        }
         // Add location permissions when geospatial provider is active
         if (geospatialAnchorProvider === "arcore" || geospatialAnchorProvider === "reactvision") {
             const existingPermissions = (contents.manifest["uses-permission"] || [])
@@ -281,14 +289,311 @@ const withViroManifest = (config) => (0, config_plugins_1.withAndroidManifest)(c
             "tools:replace": "required",
         },
     });
+    // Quest-specific features and permissions — after uses-feature is initialized
+    if (viroPluginConfig.includes("QUEST")) {
+        contents.manifest["uses-feature"].push({
+            $: {
+                "android:name": "android.hardware.vr.headtracking",
+                "android:required": "true",
+                "android:version": "1",
+            },
+        });
+        contents.manifest["uses-feature"].push({
+            $: {
+                "android:name": "oculus.software.handtracking",
+                "android:required": "false",
+            },
+        });
+        // XR_FB_passthrough requires this uses-feature; without it the OpenXR
+        // runtime silently strips the extension. required=false so apps that
+        // only render fully-virtual scenes still install on Quest 2 etc.
+        contents.manifest["uses-feature"].push({
+            $: {
+                "android:name": "com.oculus.feature.PASSTHROUGH",
+                "android:required": "false",
+            },
+        });
+        const existingPermissions = (contents.manifest["uses-permission"] || [])
+            .map((p) => p.$?.["android:name"]);
+        if (!existingPermissions.includes("com.oculus.permission.HAND_TRACKING")) {
+            contents.manifest["uses-permission"].push({
+                $: { "android:name": "com.oculus.permission.HAND_TRACKING" },
+            });
+        }
+        if (!existingPermissions.includes("com.oculus.permission.EYE_TRACKING")) {
+            contents.manifest["uses-permission"].push({
+                $: { "android:name": "com.oculus.permission.EYE_TRACKING" },
+            });
+        }
+    }
     return newConfig;
 });
+// ── Quest VRActivity generation ────────────────────────────────────────────────
+/**
+ * When QUEST mode is active, generate VRActivity.kt in the app's android source
+ * and register it in AndroidManifest with com.oculus.intent.category.VR.
+ *
+ * VRActivity is a ReactActivity that mounts "VRQuestScene" — a root component
+ * the app must register via AppRegistry. Running in a separate Activity with the
+ * VR intent category causes Horizon OS to grant exclusive OpenXR display access.
+ */
+const withViroQuestActivity = (config, props) => {
+    // Read xRMode directly from config.plugins. We cannot rely on the
+    // module-level `viroPluginConfig` here: that variable is only updated
+    // when `withBranchAndroid`'s withDangerousMod callback runs (mod-apply
+    // time), which is *after* this chain-time check executes. On the first
+    // prebuild of a new project, viroPluginConfig still holds the default
+    // ["AR", "GVR"] when this plugin is composed, and QUEST mods would be
+    // silently skipped — no VRActivity.kt and no manifest entry.
+    const viroPluginEntry = config?.plugins?.find((plugin) => Array.isArray(plugin) && plugin[0] === "@reactvision/react-viro");
+    let xrModes = ["AR", "GVR"];
+    if (Array.isArray(viroPluginEntry)) {
+        const xrMode = viroPluginEntry[1]?.android?.xRMode;
+        if (Array.isArray(xrMode)) {
+            xrModes = xrMode.filter((m) => ["AR", "GVR", "OVR_MOBILE", "QUEST"].includes(m));
+        }
+        else if (typeof xrMode === "string" &&
+            ["AR", "GVR", "OVR_MOBILE", "QUEST"].includes(xrMode)) {
+            xrModes = [xrMode];
+        }
+    }
+    if (!xrModes.includes("QUEST"))
+        return config;
+    // 1. Generate VRActivity.kt
+    config = (0, config_plugins_1.withDangerousMod)(config, [
+        "android",
+        async (config) => {
+            const packageName = config?.android?.package ?? "";
+            const packagePath = packageName.split(".");
+            const activityDir = path_1.default.join(config.modRequest.platformProjectRoot, "app", "src", "main", "java", ...packagePath);
+            if (!fs_1.default.existsSync(activityDir)) {
+                fs_1.default.mkdirSync(activityDir, { recursive: true });
+            }
+            const activityPath = path_1.default.join(activityDir, "VRActivity.kt");
+            // Only write if not already present (preserve manual edits)
+            if (!fs_1.default.existsSync(activityPath)) {
+                const kotlinContent = `package ${packageName}
+
+import android.app.Activity
+import android.app.Application
+import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
+import com.facebook.react.ReactActivity
+import com.facebook.react.ReactActivityDelegate
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
+import com.facebook.react.defaults.DefaultReactActivityDelegate
+import com.facebook.react.runtime.ReactHostImpl
+
+/**
+ * VRActivity — generated by @reactvision/react-viro Expo plugin.
+ * Carries com.oculus.intent.category.VR so Horizon OS grants exclusive
+ * OpenXR display access. Mounts the "VRQuestScene" React root component.
+ * Launch via NativeModules.VRLauncher.launchVRScene().
+ *
+ * Lifecycle (requires React Native >= 0.83 / Expo >= 55):
+ *   VRActivity and MainActivity share one ReactHostImpl singleton. On Quest,
+ *   VRActivity launches into a separate task (FLAG_ACTIVITY_NEW_TASK), so
+ *   MainActivity.onPause is dispatched *later* via ActivityManager IPC —
+ *   often after VRActivity.onResume has already promoted the host to RESUMED
+ *   with currentActivity = VRActivity. When that delayed onPause arrives,
+ *   the standard delegate calls onHostPause(MainActivity); the identity-
+ *   mismatch assertion is downgraded to a warning by
+ *   skipActivityIdentityAssertionOnHostPause (set in VRLauncherModule before
+ *   startActivity), but the rest of onHostPause runs unconditionally:
+ *   devSupport is disabled and JavaTimerManager clears its TIMERS_EVENTS
+ *   callback. Result: timers / requestAnimationFrame stop, Metro Fast Refresh
+ *   dies.
+ *
+ *   We catch this by listening for that delayed MainActivity.onPause via
+ *   Application.ActivityLifecycleCallbacks.onActivityPaused(other) and re-
+ *   promoting the host on the main looper. A Handler.post inside our own
+ *   onResume would fire too early (the ActivityManager hasn't queued
+ *   MainActivity.onPause yet), which is why we hook the actual pause event.
+ *
+ *   On exit, VRActivity.onPause runs while currentActivity == this, so the
+ *   identity assertion passes; MainActivity.onResume then re-promotes via
+ *   its standard delegate. We do *not* re-promote on a self-pause — the
+ *   onActivityPaused callback skips when other === this.
+ *
+ * Mutual exclusion with MainActivity:
+ *   Quest will happily run MainActivity (panel) and VRActivity (immersive) at
+ *   the same time if the user taps the app icon in the dock while VR is
+ *   running. The same Application.ActivityLifecycleCallbacks finishes self
+ *   when any other Activity in this app resumes — returning the user cleanly
+ *   to the panel.
+ *
+ * Surface cleanup on destroy:
+ *   When VRActivity is destroyed we unload its React surface (reactSurface.stop()
+ *   in bridgeless arch) so its component tree — including all VRT* components
+ *   — is unmounted. Without this, the React surface stayed alive in the shared
+ *   ReactHost across VR re-entries, and on the second/third VR launch each
+ *   stale surface remounted alongside the fresh one. The C++ scene-graph
+ *   resolves a click hit to a single viewTag, but multiple VRTComponents
+ *   claimed it across surfaces — most with a ReactContext bound to a
+ *   destroyed VRActivity. Click events to the stale ReactContexts crashed in
+ *   ComponentEventDelegate as IllegalArgumentException SoftExceptions and were
+ *   silently dropped, so onClick took dozens of presses to register.
+ *   We still no-op the *delegate* onDestroy() so MainActivity keeps its
+ *   ReactHost; we only stop the surface explicitly.
+ */
+class VRActivity : ReactActivity() {
+
+    private val mainHandler = Handler(Looper.getMainLooper())
+    private var lifecycleCallbacks: Application.ActivityLifecycleCallbacks? = null
+
+    // Set true on every VRActivity.onResume; consumed by the first
+    // onActivityPaused(other) that follows. One-shot — defends against the
+    // single MainActivity.onPause that the NEW_TASK ordering schedules late.
+    // Without one-shot semantics, every subsequent foreign pause would re-fire
+    // ReactHostImpl.onHostResume, which re-fires every LifecycleEventListener
+    // (AppState → "active" → ViroXRSceneNavigator's AppState handler calls
+    // launchVRScene() again → visible scene flicker).
+    private var expectingForeignPause = false
+
+    override fun getMainComponentName(): String = "VRQuestScene"
+
+    override fun createReactActivityDelegate(): ReactActivityDelegate =
+        object : DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled) {
+            // VRActivity destruction MUST NOT tear down the shared ReactHost.
+            // MainActivity is still alive (and re-foreground after VR exit) and
+            // depends on the same ReactContext. The standard delegate's
+            // onDestroy forwards to ReactHostImpl.onHostDestroy(VR), which
+            // fires LifecycleEventListener.onHostDestroy on every native module
+            // — releasing native resources MainActivity still uses. The next
+            // Cmd+R reload then runs the JS bundle re-init against a partially
+            // destroyed native side and fails with
+            //   [runtime not ready]: TypeError: Cannot read property
+            //   'EventEmitter' of undefined
+            // followed by AppRegistryBinding::stopSurface failed and the
+            // surface never recovers. By no-op'ing onDestroy here, host
+            // destruction is left to MainActivity's standard delegate (the real
+            // last activity). The surface itself is stopped explicitly in
+            // VRActivity.onDestroy() below.
+            override fun onDestroy() {
+                // intentionally no-op — see comment above
+            }
+        }
+
+    override fun onResume() {
+        super.onResume()  // delegate.onResume() -> reactHost.onHostResume(this)
+        expectingForeignPause = true
+    }
+
+    // onPause not overridden: the default delegate forwards to
+    // reactHost.onHostPause(this) while currentActivity matches us, which is
+    // what we want.
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val callbacks = object : Application.ActivityLifecycleCallbacks {
+            override fun onActivityResumed(other: Activity) {
+                if (other !== this@VRActivity && !isFinishing && !isDestroyed) {
+                    finish()
+                }
+            }
+            override fun onActivityPaused(other: Activity) {
+                if (other === this@VRActivity || isFinishing || isDestroyed) return
+                if (!expectingForeignPause) return
+                expectingForeignPause = false
+                // MainActivity.onPause was dispatched after our onResume (the
+                // NEW_TASK race). The standard delegate already called
+                // onHostPause(MainActivity), demoting the host to PAUSED and
+                // disabling devSupport / clearing JavaTimerManager's frame
+                // callback. Re-promote so VR keeps timers + Fast Refresh.
+                mainHandler.post {
+                    if (isFinishing || isDestroyed) return@post
+                    (reactHost as? ReactHostImpl)?.onHostResume(this@VRActivity)
+                }
+            }
+            override fun onActivityCreated(a: Activity, b: Bundle?) {}
+            override fun onActivityStarted(a: Activity) {}
+            override fun onActivityStopped(a: Activity) {}
+            override fun onActivitySaveInstanceState(a: Activity, b: Bundle) {}
+            override fun onActivityDestroyed(a: Activity) {}
+        }
+        application.registerActivityLifecycleCallbacks(callbacks)
+        lifecycleCallbacks = callbacks
+    }
+
+    override fun onDestroy() {
+        // Stop the React surface attached to this VRActivity so its component
+        // tree unmounts cleanly. In bridgeless arch this calls
+        // reactSurface.stop() + reactSurface = null, leaving the shared
+        // ReactHost intact for MainActivity. Without this the React tree from
+        // each VR session piles up across re-entries and stale VRTComponents
+        // intercept hit-tested viewTags with dead ReactContexts, breaking
+        // onClick / onHover until you press dozens of times.
+        try {
+            reactDelegate?.unloadApp()
+        } catch (t: Throwable) {
+            android.util.Log.w("VRActivity", "reactDelegate.unloadApp() failed", t)
+        }
+        lifecycleCallbacks?.let { application.unregisterActivityLifecycleCallbacks(it) }
+        lifecycleCallbacks = null
+        mainHandler.removeCallbacksAndMessages(null)
+        super.onDestroy()
+    }
+}
+`;
+                fs_1.default.writeFileSync(activityPath, kotlinContent, "utf-8");
+            }
+            return config;
+        },
+    ]);
+    // 2. Add VRActivity to AndroidManifest
+    config = (0, config_plugins_1.withAndroidManifest)(config, async (config) => {
+        const app = config.modResults.manifest.application?.[0];
+        if (!app)
+            return config;
+        if (!app.activity)
+            app.activity = [];
+        const alreadyAdded = app.activity.some((a) => a.$?.["android:name"] === ".VRActivity");
+        if (!alreadyAdded) {
+            app.activity.push({
+                $: {
+                    "android:name": ".VRActivity",
+                    "android:screenOrientation": "landscape",
+                    "android:exported": "false",
+                    "android:configChanges": "keyboard|keyboardHidden|orientation|screenSize|uiMode",
+                    "android:launchMode": "singleTask",
+                },
+                "intent-filter": [
+                    {
+                        action: [{ $: { "android:name": "android.intent.action.MAIN" } }],
+                        category: [
+                            { $: { "android:name": "com.oculus.intent.category.VR" } },
+                        ],
+                    },
+                ],
+            });
+        }
+        // Inject com.oculus.app_id into <application> for Meta Quest App Name
+        const questAppId = props?.android?.questAppId;
+        if (questAppId) {
+            if (!app["meta-data"])
+                app["meta-data"] = [];
+            const alreadyHasAppId = app["meta-data"].some((m) => m.$?.["android:name"] === "com.oculus.app_id");
+            if (!alreadyHasAppId) {
+                app["meta-data"].push({
+                    $: {
+                        "android:name": "com.oculus.app_id",
+                        "android:value": questAppId,
+                    },
+                });
+            }
+        }
+        return config;
+    });
+    return config;
+};
 const withViroAndroid = (config, props) => {
-    (0, config_plugins_1.withPlugins)(config, [[withBranchAndroid, props]]);
-    withViroProjectBuildGradle(config);
-    withViroManifest(config);
-    withViroSettingsGradle(config);
-    withViroAppBuildGradle(config);
+    config = withBranchAndroid(config, props);
+    config = withViroProjectBuildGradle(config);
+    config = withViroManifest(config);
+    config = withViroSettingsGradle(config);
+    config = withViroAppBuildGradle(config);
+    config = withViroQuestActivity(config, props);
     return config;
 };
 exports.withViroAndroid = withViroAndroid;

package/dist/plugins/withViroIos.js

@@ -18,6 +18,7 @@ const withViroPods = (config) => {
             let geospatialAnchorProvider;
             let iosLinkage;
             let includeARCore;
+            let includeSemantics;
             if (Array.isArray(config.plugins)) {
                 const pluginConfig = config?.plugins?.find((plugin) => Array.isArray(plugin) && plugin[0] === "@reactvision/react-viro");
                 if (Array.isArray(pluginConfig) && pluginConfig.length > 1) {
@@ -30,6 +31,7 @@ const withViroPods = (config) => {
                     geospatialAnchorProvider = legacyOpts.geospatialAnchorProvider ?? options.provider ?? defaultProvider;
                     iosLinkage = options.iosLinkage;
                     includeARCore = options.ios?.includeARCore;
+                    includeSemantics = options.ios?.includeSemantics;
                 }
             }
             fs_1.default.readFile(`${root}/Podfile`, "utf-8", (err, data) => {
@@ -44,36 +46,38 @@ const withViroPods = (config) => {
                     `  # Automatically includes Fabric components when RCT_NEW_ARCH_ENABLED=1\n` +
                     `  pod 'ViroReact', :path => '../node_modules/@reactvision/react-viro/ios'\n` +
                     `  pod 'ViroKit', :path => '../node_modules/@reactvision/react-viro/ios/dist/ViroRenderer/'`;
-                // Add ARCore pods if enabled (explicitly via includeARCore or implicitly via cloud/geospatial providers)
+                // Add ARCore pods if enabled (explicitly via includeARCore/includeSemantics or implicitly via providers)
                 // ViroKit.podspec declares these as weak_frameworks, making ARCore optional at runtime
                 const needsARCoreForFeatures = cloudAnchorProvider === "arcore" || geospatialAnchorProvider === "arcore";
                 const shouldIncludeARCore = includeARCore === true || needsARCoreForFeatures;
-                if (shouldIncludeARCore) {
+                const shouldIncludeSemantics = shouldIncludeARCore || includeSemantics === true;
+                if (shouldIncludeSemantics) {
                     viroPods +=
                         `\n\n  # ARCore SDK - Cloud Anchors, Geospatial, and Scene Semantics API\n` +
                             `  # ViroKit uses weak linking for these frameworks, making ARCore optional at runtime.\n` +
                             `  # ViroKit checks availability using NSClassFromString and gracefully degrades if not present.\n` +
                             `  pod 'ARCore/CloudAnchors', '~> 1.51.0'`;
-                    // Add Geospatial pod if geospatial is enabled or explicit ARCore inclusion
+                    // Add Geospatial pod if geospatial is enabled or full ARCore inclusion
                     if (geospatialAnchorProvider === "arcore" || includeARCore === true) {
                         viroPods +=
                             `\n  pod 'ARCore/Geospatial', '~> 1.51.0'`;
                     }
                     // Add Semantics pod for Scene Semantics API (ML-based scene understanding)
+                    // Included whenever ARCore is present OR includeSemantics: true
                     viroPods +=
                         `\n  pod 'ARCore/Semantics', '~> 1.51.0'`;
                 }
                 // Add use_frameworks! if configured
-                // User's iosLinkage setting is respected; if not set and ARCore is enabled, default to dynamic
-                const effectiveLinkage = iosLinkage || (shouldIncludeARCore ? "dynamic" : undefined);
+                // User's iosLinkage setting is respected; if not set and ARCore/Semantics is enabled, default to dynamic
+                const effectiveLinkage = iosLinkage || (shouldIncludeSemantics ? "dynamic" : undefined);
                 if (effectiveLinkage) {
                     // Insert use_frameworks! before the target block
                     let linkageComment;
-                    if (shouldIncludeARCore && effectiveLinkage === "static") {
+                    if (shouldIncludeSemantics && effectiveLinkage === "static") {
                         // Warn user that static linkage may not work with ARCore
                         linkageComment = `# WARNING: ARCore SDK typically requires dynamic frameworks.\n# Static linkage is set but may cause build issues with ARCore pods.`;
                     }
-                    else if (shouldIncludeARCore) {
+                    else if (shouldIncludeSemantics) {
                         linkageComment = `# Framework linkage: ${effectiveLinkage} (ARCore requires dynamic frameworks)`;
                     }
                     else {
@@ -167,6 +171,7 @@ const withDefaultInfoPlist = (config, _props) => {
     let googleCloudApiKey;
     let rvApiKey;
     let rvProjectId;
+    let rvEndpoint;
     let cloudAnchorProvider;
     let geospatialAnchorProvider;
     let includeARCore;
@@ -186,6 +191,7 @@ const withDefaultInfoPlist = (config, _props) => {
             googleCloudApiKey = pluginOptions.googleCloudApiKey;
             rvApiKey = pluginOptions.rvApiKey;
             rvProjectId = pluginOptions.rvProjectId;
+            rvEndpoint = pluginOptions.rvEndpoint;
             // Resolve unified provider prop; old props override for backward compat.
             // Default to "reactvision" only when rvApiKey is present (implies RV intent).
             const defaultProvider2 = pluginOptions.rvApiKey ? "reactvision" : undefined;
@@ -220,6 +226,9 @@ const withDefaultInfoPlist = (config, _props) => {
     if (rvProjectId) {
         config.ios.infoPlist.RVProjectId = rvProjectId;
     }
+    if (rvEndpoint) {
+        config.ios.infoPlist.RVEndpoint = rvEndpoint;
+    }
     // Add location permissions for Geospatial API
     if (geospatialAnchorProvider === "arcore" || geospatialAnchorProvider === "reactvision" || includeARCore === true) {
         config.ios.infoPlist.NSLocationWhenInUseUsageDescription =
@@ -231,7 +240,7 @@ const withDefaultInfoPlist = (config, _props) => {
 };
 exports.withDefaultInfoPlist = withDefaultInfoPlist;
 const withViroIos = (config, props) => {
-    (0, config_plugins_1.withPlugins)(config, [[withViroPods, props]]);
+    config = (0, config_plugins_1.withPlugins)(config, [[withViroPods, props]]);
     (0, exports.withDefaultInfoPlist)(config, props);
     withEnabledBitcode(config);
     withExcludedSimulatorArchitectures(config);

package/dist/plugins/withViroVisionOS.d.ts

@@ -0,0 +1,24 @@
+/**
+ * withViroVisionOS.ts
+ *
+ * Expo config plugin that adds a visionOS target to your app's Xcode project.
+ *
+ * What it does:
+ *   1. Writes the SwiftUI App entry point (ViroVisionApp.swift) into the target folder
+ *   2. Adds a visionOS pod target to the Podfile
+ *   3. Creates a visionOS Xcode target in the .pbxproj with correct SDK + build settings
+ *
+ * Usage in app.json:
+ *   {
+ *     "plugins": [
+ *       ["@reactvision/react-viro", { ... }],
+ *       "@reactvision/react-viro/plugins/withViroVisionOS"
+ *     ]
+ *   }
+ *
+ * After running `expo prebuild`, run `pod install` in ios/ then build the
+ * <AppName>Vision target in Xcode targeting the visionOS simulator.
+ */
+import { ConfigPlugin } from "@expo/config-plugins";
+export declare const withViroVisionOS: ConfigPlugin;
+export default withViroVisionOS;