rnxsim 0.1.343 → 0.1.345

package/dist-lib/vite.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.343 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.345 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;
@@ -37,43 +37,119 @@ __export(vite_plugin_one_exports, {
   sootsimPlugin: () => sootsimPlugin
 });
 module.exports = __toCommonJS(vite_plugin_one_exports);
-var import_child_process = require("child_process");
 var import_fs2 = __toESM(require("fs"), 1);
+var import_node_crypto2 = require("node:crypto");
 var import_path2 = __toESM(require("path"), 1);
-var import_url2 = require("url");
 
 // src/bridge-constants.ts
 var DEFAULT_SOOTSIM_BRIDGE_PORT = 7668;
 var DEFAULT_SOOTSIM_BRIDGE_URL = `http://localhost:${DEFAULT_SOOTSIM_BRIDGE_PORT}/`;
 
-// src/home-paths.ts
+// src/dev-server-open.ts
+var import_node_child_process = require("node:child_process");
+var import_node_crypto = require("node:crypto");
 var import_node_fs = __toESM(require("node:fs"), 1);
-var import_node_os = require("node:os");
 var import_node_path = __toESM(require("node:path"), 1);
+var import_node_url = require("node:url");
+function resolveRnxDesktopAppName(open, projectRoot) {
+  if (!open) return null;
+  if (typeof open === "object") {
+    const appName = open.appName.trim();
+    if (!appName) throw new Error("rnx: open.appName must not be empty");
+    return appName;
+  }
+  const packageJsonPath = import_node_path.default.join(projectRoot, "package.json");
+  const packageJson = JSON.parse(import_node_fs.default.readFileSync(packageJsonPath, "utf8"));
+  const packageName = packageJson && typeof packageJson === "object" ? Reflect.get(packageJson, "name") : void 0;
+  if (typeof packageName !== "string" || !packageName.trim()) {
+    throw new Error(`rnx: ${packageJsonPath} must declare a package name`);
+  }
+  return packageName.trim();
+}
+function tagRnxBundleForPlugin(bundleUrl, replacementOrigin, replacementToken, projectRoot, appName) {
+  const absolute = /^[a-z][a-z\d+.-]*:\/\//i.test(bundleUrl);
+  const url = new URL(bundleUrl, absolute ? void 0 : "http://rnx.local");
+  if (appName) {
+    url.searchParams.set("rnxAppName", appName);
+    url.searchParams.set(
+      "rnxProjectId",
+      (0, import_node_crypto.createHash)("sha256").update(import_node_fs.default.realpathSync(projectRoot)).digest("hex").slice(0, 32)
+    );
+  }
+  url.searchParams.set("rnxReplacementOrigin", replacementOrigin);
+  url.searchParams.set("rnxReplacementToken", replacementToken);
+  return absolute ? url.toString() : `${url.pathname}${url.search}${url.hash}`;
+}
+function resolveRnxDesktopLaunchTarget(port, bundleUrl) {
+  return new URL(bundleUrl, `http://localhost:${port}`).toString();
+}
+function buildRnxDesktopOpenArgs(bundleUrl) {
+  return ["open", bundleUrl, "--new", "--driver", "electron", "--no-describe"];
+}
+function observeRnxDesktopLaunch(child, appName) {
+  let stderr = "";
+  let spawnFailed = false;
+  child.stderr?.setEncoding("utf8");
+  child.stderr?.on("data", (chunk) => {
+    stderr = `${stderr}${chunk}`.slice(-16384);
+  });
+  child.once("error", (error) => {
+    spawnFailed = true;
+    console.error(`[rnx] could not open ${appName}: ${error.message}`);
+  });
+  child.once("close", (code, signal) => {
+    if (spawnFailed) return;
+    if (code === 0) {
+      console.log(`[rnx] opened ${appName} in the desktop simulator`);
+      return;
+    }
+    const detail = stderr.trim() || (signal ? `signal ${signal}` : `exit ${code}`);
+    console.error(`[rnx] could not open ${appName}: ${detail}`);
+  });
+}
+function launchRnxDesktop(bundleUrl, appName) {
+  const packageRoot = import_node_path.default.resolve(import_node_path.default.dirname((0, import_node_url.fileURLToPath)(__sootsim_import_meta_url)), "..");
+  const binPath = import_node_path.default.join(packageRoot, "dist-cli", "bin.js");
+  console.log(`[rnx] opening ${appName} in the desktop simulator`);
+  const child = (0, import_node_child_process.spawn)(
+    process.execPath,
+    [binPath, ...buildRnxDesktopOpenArgs(bundleUrl)],
+    {
+      stdio: ["ignore", "ignore", "pipe"],
+      windowsHide: true
+    }
+  );
+  observeRnxDesktopLaunch(child, appName);
+}
+
+// src/home-paths.ts
+var import_node_fs2 = __toESM(require("node:fs"), 1);
+var import_node_os = require("node:os");
+var import_node_path2 = __toESM(require("node:path"), 1);
 var SOOTSIM_HOME_ENV = "SOOTSIM_HOME";
 var ACTIVE_RUNTIME_FILE = "active";
 var DAEMON_LOCKFILE = "daemon.json";
 var DAEMON_HEARTBEAT_STALE_MS = 3e4;
 function sootsimHomeDir() {
   const override = process.env[SOOTSIM_HOME_ENV];
-  if (override && override.length > 0) return import_node_path.default.resolve(override);
-  return import_node_path.default.join((0, import_node_os.homedir)(), ".sootsim");
+  if (override && override.length > 0) return import_node_path2.default.resolve(override);
+  return import_node_path2.default.join((0, import_node_os.homedir)(), ".sootsim");
 }
 function runtimesDir() {
-  return import_node_path.default.join(sootsimHomeDir(), "runtimes");
+  return import_node_path2.default.join(sootsimHomeDir(), "runtimes");
 }
 function runtimeDir(version) {
-  return import_node_path.default.join(runtimesDir(), version);
+  return import_node_path2.default.join(runtimesDir(), version);
 }
 function activeRuntimeFile() {
-  return import_node_path.default.join(runtimesDir(), ACTIVE_RUNTIME_FILE);
+  return import_node_path2.default.join(runtimesDir(), ACTIVE_RUNTIME_FILE);
 }
 function daemonLockfilePath() {
-  return import_node_path.default.join(sootsimHomeDir(), DAEMON_LOCKFILE);
+  return import_node_path2.default.join(sootsimHomeDir(), DAEMON_LOCKFILE);
 }
 function readActiveRuntime() {
   try {
-    const value = import_node_fs.default.readFileSync(activeRuntimeFile(), "utf8").trim();
+    const value = import_node_fs2.default.readFileSync(activeRuntimeFile(), "utf8").trim();
     return value.length > 0 ? value : null;
   } catch {
     return null;
@@ -82,10 +158,10 @@ function readActiveRuntime() {
 var DAEMON_LOCKFILE_MAX_BYTES = 16 * 1024;
 function readDaemonLockfile() {
   try {
-    const fd = import_node_fs.default.openSync(daemonLockfilePath(), "r");
+    const fd = import_node_fs2.default.openSync(daemonLockfilePath(), "r");
     try {
       const buf = Buffer.alloc(DAEMON_LOCKFILE_MAX_BYTES);
-      const bytesRead = import_node_fs.default.readSync(fd, buf, 0, DAEMON_LOCKFILE_MAX_BYTES, 0);
+      const bytesRead = import_node_fs2.default.readSync(fd, buf, 0, DAEMON_LOCKFILE_MAX_BYTES, 0);
       const raw = buf.subarray(0, bytesRead).toString("utf8");
       const parsed = JSON.parse(raw);
       if (parsed && parsed.schema === 1 && typeof parsed.pid === "number" && typeof parsed.bridgePort === "number" && typeof parsed.runtimePort === "number" && typeof parsed.startedAt === "number" && typeof parsed.heartbeatAt === "number" && (parsed.servedRuntimes === void 0 || Array.isArray(parsed.servedRuntimes) && parsed.servedRuntimes.every((version) => typeof version === "string"))) {
@@ -93,7 +169,7 @@ function readDaemonLockfile() {
       }
       return null;
     } finally {
-      import_node_fs.default.closeSync(fd);
+      import_node_fs2.default.closeSync(fd);
     }
   } catch {
     return null;
@@ -112,12 +188,23 @@ function isDaemonLockfileFresh(lock, now = Date.now()) {
 
 // src/host/replacement-module-handler.ts
 var import_promises = __toESM(require("node:fs/promises"), 1);
-var import_node_path2 = __toESM(require("node:path"), 1);
+var import_node_path3 = __toESM(require("node:path"), 1);
 var import_esbuild = require("esbuild");
+
+// src/backend-origin.ts
+function normalizeHostname(hostname) {
+  return hostname.replace(/^\[|\]$/g, "").toLowerCase();
+}
+function isLoopbackHost(hostname) {
+  const normalized = normalizeHostname(hostname);
+  return normalized === "localhost" || normalized.endsWith(".localhost") || normalized === "0.0.0.0" || normalized === "::1" || /^127(?:\.\d{1,3}){3}$/.test(normalized);
+}
+
+// src/host/replacement-module-handler.ts
 var REPLACEMENT_MODULE_ROUTE = "/__sootsim-replacement-module";
 var REPLACEMENT_RUNTIME_PREFIX = "/__sootsim-replacement-runtime";
 function getReplacementLoader(filePath) {
-  const ext = import_node_path2.default.extname(filePath).toLowerCase();
+  const ext = import_node_path3.default.extname(filePath).toLowerCase();
   switch (ext) {
     case ".js":
       return "js";
@@ -214,9 +301,18 @@ export const Appearance = rn.Appearance
 `;
 }
 function sendJavaScript(req, res, source) {
+  const origin = req.headers.origin;
+  let allowedOrigin;
+  if (origin) {
+    try {
+      if (isLoopbackHost(new URL(origin).hostname)) allowedOrigin = origin;
+    } catch {
+    }
+  }
   res.writeHead(200, {
     "Content-Type": "application/javascript; charset=utf-8",
-    "Cache-Control": "no-cache"
+    "Cache-Control": "no-cache",
+    ...allowedOrigin ? { "Access-Control-Allow-Origin": allowedOrigin, Vary: "Origin" } : {}
   });
   res.end(req.method === "HEAD" ? void 0 : source);
 }
@@ -228,6 +324,23 @@ async function handleReplacementModuleRequest(req, res, options = {}) {
   } catch {
     return false;
   }
+  if (options.requireLoopbackOrigin) {
+    const origin = req.headers.origin;
+    const remoteAddress = req.socket.remoteAddress?.replace(/^::ffff:/, "");
+    let allowed = Boolean(remoteAddress && isLoopbackHost(remoteAddress));
+    if (allowed && origin) {
+      try {
+        allowed = isLoopbackHost(new URL(origin).hostname);
+      } catch {
+        allowed = false;
+      }
+    }
+    if (!allowed) {
+      res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("replacement modules are available only to loopback origins");
+      return true;
+    }
+  }
   if (url.pathname === `${REPLACEMENT_RUNTIME_PREFIX}/react`) {
     sendJavaScript(req, res, reactRuntimeSource(options.reactBridgeUrl));
     return true;
@@ -237,6 +350,11 @@ async function handleReplacementModuleRequest(req, res, options = {}) {
     return true;
   }
   if (url.pathname !== REPLACEMENT_MODULE_ROUTE) return false;
+  if (options.requestToken && url.searchParams.get("token") !== options.requestToken) {
+    res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("replacement module request token is invalid");
+    return true;
+  }
   const targetPath = url.searchParams.get("path");
   if (!targetPath) {
     res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
@@ -249,17 +367,42 @@ async function handleReplacementModuleRequest(req, res, options = {}) {
     res.end("replacement files must be .js, .jsx, .ts, or .tsx");
     return true;
   }
+  if (!import_node_path3.default.isAbsolute(targetPath)) {
+    res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("replacement file path must be absolute");
+    return true;
+  }
+  let resolvedProjectRoot;
+  if (options.projectRoot) {
+    const lexicalProjectRoot = import_node_path3.default.resolve(options.projectRoot);
+    resolvedProjectRoot = await import_promises.default.realpath(options.projectRoot);
+    const lexicalTarget = import_node_path3.default.relative(lexicalProjectRoot, targetPath);
+    if (lexicalTarget.startsWith("..") || import_node_path3.default.isAbsolute(lexicalTarget)) {
+      res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("replacement file must be inside the project root");
+      return true;
+    }
+  }
+  let resolvedTargetPath;
   try {
-    await import_promises.default.access(targetPath);
+    resolvedTargetPath = await import_promises.default.realpath(targetPath);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
     res.end(`replacement file not found: ${message}`);
     return true;
   }
+  if (resolvedProjectRoot) {
+    const relativeTarget = import_node_path3.default.relative(resolvedProjectRoot, resolvedTargetPath);
+    if (relativeTarget.startsWith("..") || import_node_path3.default.isAbsolute(relativeTarget)) {
+      res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("replacement file must be inside the project root");
+      return true;
+    }
+  }
   try {
     const result = await (0, import_esbuild.build)({
-      entryPoints: [targetPath],
+      entryPoints: [resolvedTargetPath],
       bundle: true,
       write: false,
       format: "esm",
@@ -446,11 +589,25 @@ function rnxPlugin(options = {}) {
     configureServer(server) {
       if (options.enabled === false) return;
       const bundleUrl = options.bundleUrl || "/node_modules/one/metro-entry.bundle?platform=ios&dev=true&minify=false";
+      const appName = resolveRnxDesktopAppName(options.open, server.config.root);
+      const replacementToken = (0, import_node_crypto2.randomUUID)();
+      const configuredPort = server.config.server.port || 8081;
+      const listeningPort = () => {
+        const address = server.httpServer?.address();
+        return address && typeof address === "object" ? address.port : configuredPort;
+      };
+      const bundleForPort = (port2) => tagRnxBundleForPlugin(
+        bundleUrl,
+        `http://localhost:${port2}`,
+        replacementToken,
+        server.config.root,
+        appName
+      );
       const buildShellHtml = (runtimeRoot) => {
         const html = import_fs2.default.readFileSync(import_path2.default.join(runtimeRoot, "index.html"), "utf8");
         const lock = readDaemonLockfile();
         const bridgePort = lock && isDaemonLockfileFresh(lock) && lock.bridgePort > 0 ? lock.bridgePort : DEFAULT_SOOTSIM_BRIDGE_PORT;
-        const inject = `<script>(function(){var u=new URL(location.href);if(!u.searchParams.has('bundle'))u.searchParams.set('bundle',${JSON.stringify(bundleUrl)});window.__sootsimBridgePort=${bridgePort};history.replaceState(null,'','${prefix}/'+u.search)})()</script>`;
+        const inject = `<script>(function(){var u=new URL(location.href);if(!u.searchParams.has('bundle'))u.searchParams.set('bundle',${JSON.stringify(bundleForPort(listeningPort()))});window.__sootsimBridgePort=${bridgePort};history.replaceState(null,'','${prefix}/'+u.search)})()</script>`;
         return html.replace("</head>", inject + "</head>");
       };
       server.middlewares.use((req, res, next) => {
@@ -471,8 +628,9 @@ function rnxPlugin(options = {}) {
       });
       server.middlewares.use((req, res, next) => {
         if ((req.url || "").split("?")[0] !== "/__server-scan") return next();
-        const scanPort = server.config.server.port || 8081;
-        const absoluteBundleUrl = bundleUrl.startsWith("http") ? bundleUrl : `http://localhost:${scanPort}${bundleUrl}`;
+        const scanPort = listeningPort();
+        const pluginBundleUrl = bundleForPort(scanPort);
+        const absoluteBundleUrl = pluginBundleUrl.startsWith("http") ? pluginBundleUrl : `http://localhost:${scanPort}${pluginBundleUrl}`;
         res.setHeader("content-type", "application/json");
         res.end(
           JSON.stringify([
@@ -480,13 +638,18 @@ function rnxPlugin(options = {}) {
               port: scanPort,
               framework: "one",
               bundleUrl: absoluteBundleUrl,
+              ...appName ? { projectName: appName } : {},
               lastSeen: Date.now()
             }
           ])
         );
       });
       server.middlewares.use((req, res, next) => {
-        void handleReplacementModuleRequest(req, res).then((handled) => {
+        void handleReplacementModuleRequest(req, res, {
+          projectRoot: server.config.root,
+          requestToken: replacementToken,
+          requireLoopbackOrigin: true
+        }).then((handled) => {
           if (!handled) next();
         });
       });
@@ -533,23 +696,16 @@ function rnxPlugin(options = {}) {
         }
         next();
       });
-      const port = server.config.server.port || 8081;
+      const port = configuredPort;
       const sootsimUrl = `http://localhost:${port}${prefix}/`;
       console.log(`[rnx] serving at ${sootsimUrl}`);
-      if (options.open && !process.env.CI && !process.env.SOOTSIM_NO_OPEN) {
+      if (appName && !process.env.CI && !process.env.SOOTSIM_NO_OPEN) {
         server.httpServer?.once("listening", () => {
-          const packageRoot = import_path2.default.resolve(
-            import_path2.default.dirname((0, import_url2.fileURLToPath)(__sootsim_import_meta_url)),
-            ".."
+          const openPort = listeningPort();
+          launchRnxDesktop(
+            resolveRnxDesktopLaunchTarget(openPort, bundleForPort(openPort)),
+            appName
           );
-          const binPath = import_path2.default.join(packageRoot, "dist-cli", "bin.js");
-          const openPort = server.config.server.port || port;
-          console.log(`[rnx] opening simulator for :${openPort}`);
-          (0, import_child_process.spawn)(process.execPath, [binPath, "open", String(openPort)], {
-            detached: true,
-            stdio: "ignore",
-            windowsHide: true
-          }).unref();
         });
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rnxsim",
-  "version": "0.1.343",
+  "version": "0.1.345",
   "description": "rnx CLI, Vite and Metro plugins, and agent skills for driving React Native apps in the browser.",
   "author": "Tamagui LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -200,6 +200,7 @@
     "@expo/plist": "^0.5.4",
     "esbuild": "^0.25.0",
     "jiti": "2.7.0",
+    "playwright-core": "1.61.0",
     "ws": "^8.18.0"
   },
   "peerDependencies": {

package/scripts/dev-server-scanner.ts

@@ -23,7 +23,10 @@ import type { AppSettingsSpecifier } from '@sootsim/globals'
 
 const execP = promisify(exec)
 import { applySootSimConfigToUrl } from '../src/config.ts'
-import { normalizeNativeDevBundleUrl } from '../src/native-dev-bundle-url.ts'
+import {
+  alignLoopbackBundleUrlWithProbe,
+  normalizeNativeDevBundleUrl,
+} from '../src/native-dev-bundle-url.ts'
 import {
   __resetAppSettingsBundleCacheForTests,
   readAppSettingsBundle,
@@ -399,10 +402,14 @@ function applyManifest(
     if (result.framework === 'metro' && client.sdkVersion) result.framework = 'expo'
     // preserve a confirmed direct one/vxrn metro-entry bundle. expo manifests
     // and one/vxrn manifests point at a launchAsset URL with `hot=false`
-    // (hardcoded by @expo/cli — see metroOptions.ts). that's the same URL
-    // real iOS sims load, so sootsim uses it verbatim to share metro's
-    // bundle cache; HMR still works via sootsim's HmrClient.
-    const launchUrl = manifest?.launchAsset?.url
+    // (hardcoded by @expo/cli — see metroOptions.ts). keep its path and query
+    // so metro shares the iOS bundle cache. when both hosts are loopback, keep
+    // the host that answered discovery so address-family drift stays reachable.
+    const rawLaunchUrl = manifest?.launchAsset?.url
+    const launchUrl =
+      typeof rawLaunchUrl === 'string'
+        ? alignLoopbackBundleUrlWithProbe(rawLaunchUrl, `http://localhost:${result.port}`)
+        : rawLaunchUrl
     if (launchUrl && !result.patched && !isDirectOneBundleUrl(result.bundleUrl)) {
       result.bundleUrl = withRuntimeConfig(result.port, launchUrl, result.cwd)
     }

package/skills/rnx-test/SKILL.md

@@ -12,6 +12,10 @@ Detox runs existing imperative Jest suites through the rnx driver.
 > needs a connected, pinned sim. if `rnx describe` errors, load
 > `/rnx-setup` first.
 
+Set `SOOTSIM_NO_OPEN=1` before starting an app dev server for a Detox,
+Maestro, or iOS-only pass. Apps can opt into a named Electron window through
+the official Vite or Metro plugin, and test-only work must not open that window.
+
 ## route in (decision tree)
 
 - have an existing `.maestro/` directory? → [Maestro](#branch--maestro)

package/src/dev-bundle-resolution.ts

@@ -1,5 +1,9 @@
 import { isLoopbackHost } from './backend-origin'
-import { METRO_BUNDLE_PATH, normalizeNativeDevBundleUrl } from './native-dev-bundle-url'
+import {
+  alignLoopbackBundleUrlWithProbe,
+  METRO_BUNDLE_PATH,
+  normalizeNativeDevBundleUrl,
+} from './native-dev-bundle-url'
 
 export const DEFAULT_TEST_DRIVE_PORT = 8081
 
@@ -65,8 +69,8 @@ function isBaseServerUrl(url: URL) {
 
 // resolve a loopback dev-server port through the SAME server-side scanner the
 // dev-server list uses (`/__server-scan`), so an explicit port (`/rn/<port>`, a
-// typed port) gets the EXACT manifest `launchAsset.url` the list resolves —
-// byte-identical, one resolver.
+// typed port) gets the same manifest path and query the list resolves. loopback
+// hosts stay aligned to the address that answered discovery.
 //
 // why this exists: in a browser/worker the direct manifest probe below is
 // cross-origin (shell on :5173, dev server on :<port>), and a dev server
@@ -109,8 +113,8 @@ async function resolvePortViaServerScan(port: number): Promise<ResolvedDevBundle
     if (!match) return null
     return {
       // normalize exactly like the manifest-probe branch below — the scan
-      // returns metro's raw launchAsset url (lazy=true for code-split one/vxrn
-      // apps), but sootsim loads ONE self-contained bundle into the tenant
+      // returns metro's manifest launchAsset url (lazy=true for code-split
+      // one/vxrn apps), but sootsim loads ONE self-contained bundle into the tenant
       // worker, so a deferred React.lazy chunk throws "Requiring unknown module
       // <id>". normalizeNativeDevBundleUrl forces lazy=false + strips bytecode.
       bundleUrl: normalizeNativeDevBundleUrl(match.bundleUrl),
@@ -145,10 +149,13 @@ async function probeBaseUrlBundle(
     if (manifestRes.ok) {
       const manifest = await manifestRes.json()
       const client = manifest?.extra?.expoClient || manifest?.extra || {}
-      const launchUrl =
+      const rawLaunchUrl =
         typeof manifest?.launchAsset?.url === 'string'
           ? manifest.launchAsset.url
           : undefined
+      const launchUrl = rawLaunchUrl
+        ? alignLoopbackBundleUrlWithProbe(rawLaunchUrl, normalizedBaseUrl)
+        : undefined
       if (launchUrl || client.name) {
         return {
           bundleUrl: normalizeNativeDevBundleUrl(

package/src/dev-server-open.ts

@@ -0,0 +1,197 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import http from 'node:http'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export type RnxDesktopOpenOption = boolean | { appName: string }
+
+const scheduledMetroOpens = new Set<string>()
+
+export function resolveRnxDesktopAppName(
+  open: RnxDesktopOpenOption | undefined,
+  projectRoot: string,
+): string | null {
+  if (!open) return null
+  if (typeof open === 'object') {
+    const appName = open.appName.trim()
+    if (!appName) throw new Error('rnx: open.appName must not be empty')
+    return appName
+  }
+
+  const packageJsonPath = path.join(projectRoot, 'package.json')
+  const packageJson: unknown = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+  const packageName =
+    packageJson && typeof packageJson === 'object'
+      ? Reflect.get(packageJson, 'name')
+      : undefined
+  if (typeof packageName !== 'string' || !packageName.trim()) {
+    throw new Error(`rnx: ${packageJsonPath} must declare a package name`)
+  }
+  return packageName.trim()
+}
+
+export function tagRnxBundleForPlugin(
+  bundleUrl: string,
+  replacementOrigin: string,
+  replacementToken: string,
+  projectRoot: string,
+  appName?: string | null,
+): string {
+  const absolute = /^[a-z][a-z\d+.-]*:\/\//i.test(bundleUrl)
+  const url = new URL(bundleUrl, absolute ? undefined : 'http://rnx.local')
+  if (appName) {
+    url.searchParams.set('rnxAppName', appName)
+    url.searchParams.set(
+      'rnxProjectId',
+      createHash('sha256')
+        .update(fs.realpathSync(projectRoot))
+        .digest('hex')
+        .slice(0, 32),
+    )
+  }
+  url.searchParams.set('rnxReplacementOrigin', replacementOrigin)
+  url.searchParams.set('rnxReplacementToken', replacementToken)
+  return absolute ? url.toString() : `${url.pathname}${url.search}${url.hash}`
+}
+
+export function resolveRnxDesktopLaunchTarget(port: number, bundleUrl: string): string {
+  return new URL(bundleUrl, `http://localhost:${port}`).toString()
+}
+
+export function buildRnxDesktopOpenArgs(bundleUrl: string): string[] {
+  return ['open', bundleUrl, '--new', '--driver', 'electron', '--no-describe']
+}
+
+export function observeRnxDesktopLaunch(child: ChildProcess, appName: string): void {
+  let stderr = ''
+  let spawnFailed = false
+  child.stderr?.setEncoding('utf8')
+  child.stderr?.on('data', (chunk: string) => {
+    stderr = `${stderr}${chunk}`.slice(-16_384)
+  })
+  child.once('error', (error) => {
+    spawnFailed = true
+    console.error(`[rnx] could not open ${appName}: ${error.message}`)
+  })
+  child.once('close', (code, signal) => {
+    if (spawnFailed) return
+    if (code === 0) {
+      console.log(`[rnx] opened ${appName} in the desktop simulator`)
+      return
+    }
+    const detail = stderr.trim() || (signal ? `signal ${signal}` : `exit ${code}`)
+    console.error(`[rnx] could not open ${appName}: ${detail}`)
+  })
+}
+
+export function launchRnxDesktop(bundleUrl: string, appName: string): void {
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+  const binPath = path.join(packageRoot, 'dist-cli', 'bin.js')
+  console.log(`[rnx] opening ${appName} in the desktop simulator`)
+  const child = spawn(
+    process.execPath,
+    [binPath, ...buildRnxDesktopOpenArgs(bundleUrl)],
+    {
+      stdio: ['ignore', 'ignore', 'pipe'],
+      windowsHide: true,
+    },
+  )
+  observeRnxDesktopLaunch(child, appName)
+}
+
+interface MetroDesktopOpenOptions {
+  port: number
+  bundleUrl: string
+  appName: string
+  projectRoot: string
+  serverId: string
+  intervalMs?: number
+  timeoutMs?: number
+  launch?: (bundleUrl: string, appName: string) => void
+}
+
+export function openRnxDesktopWhenMetroIsReady({
+  port,
+  bundleUrl,
+  appName,
+  projectRoot,
+  serverId,
+  intervalMs = 100,
+  timeoutMs = 30_000,
+  launch = launchRnxDesktop,
+}: MetroDesktopOpenOptions): Promise<boolean> {
+  const key = `${projectRoot}\0${port}`
+  if (scheduledMetroOpens.has(key)) return Promise.resolve(false)
+  scheduledMetroOpens.add(key)
+  const deadline = Date.now() + timeoutMs
+
+  return new Promise((resolve) => {
+    let finished = false
+    const finish = (opened: boolean) => {
+      if (finished) return
+      finished = true
+      scheduledMetroOpens.delete(key)
+      resolve(opened)
+    }
+    const retry = () => {
+      if (finished) return
+      if (Date.now() >= deadline) {
+        console.error(
+          `[rnx] could not open ${appName}: Metro did not become ready on port ${port}`,
+        )
+        finish(false)
+        return
+      }
+      const timer = setTimeout(check, intervalMs)
+      timer.unref()
+    }
+    const check = () => {
+      const request = http.get(
+        `http://127.0.0.1:${port}/__server-scan`,
+        { headers: { Accept: 'application/json' } },
+        (response) => {
+          let body = ''
+          response.setEncoding('utf8')
+          response.on('data', (chunk: string) => {
+            body = `${body}${chunk}`.slice(0, 65_536)
+          })
+          response.once('end', () => {
+            try {
+              const scan: unknown = JSON.parse(body)
+              const matches =
+                response.statusCode === 200 &&
+                Array.isArray(scan) &&
+                scan.some((entry: unknown) => {
+                  if (!entry || typeof entry !== 'object') return false
+                  const scannedPort = Reflect.get(entry, 'port')
+                  const projectName = Reflect.get(entry, 'projectName')
+                  const scannedServerId = Reflect.get(entry, 'rnxServerId')
+                  const scannedBundle = Reflect.get(entry, 'bundleUrl')
+                  if (
+                    scannedPort !== port ||
+                    projectName !== appName ||
+                    scannedServerId !== serverId ||
+                    typeof scannedBundle !== 'string'
+                  ) {
+                    return false
+                  }
+                  return new URL(scannedBundle).searchParams.get('rnxAppName') === appName
+                })
+              if (matches) {
+                launch(bundleUrl, appName)
+                finish(true)
+                return
+              }
+            } catch {}
+            retry()
+          })
+        },
+      )
+      request.setTimeout(Math.min(1_000, timeoutMs), () => request.destroy())
+      request.once('error', retry)
+    }
+    check()
+  })
+}