rnxsim 0.1.344 → 0.1.346

package/scripts/dev-server-scanner.ts

@@ -22,8 +22,16 @@ import { promisify } from 'util'
 import type { AppSettingsSpecifier } from '@sootsim/globals'
 
 const execP = promisify(exec)
+import {
+  buildLoopbackProbeBaseUrl,
+  LOOPBACK_PROBE_HOSTNAMES,
+  normalizeHostname,
+} from '../src/backend-origin.ts'
 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,
@@ -71,30 +79,42 @@ interface HttpResult {
   statusCode: number
   body: string
   contentType?: string
+  hostname: string
 }
 
 // cheap TCP-connect gate. lsof already says the socket is LISTEN, but the
 // process can be closing, the fd can be a different protocol, or a zombie
 // can linger — none of those cases are worth firing 5 HTTP probes at.
-function tcpPing(port: number, timeout = TCP_GATE_MS): Promise<boolean> {
-  return new Promise((resolve) => {
-    const sock = new net.Socket()
-    let settled = false
-    const done = (ok: boolean) => {
-      if (settled) return
-      settled = true
-      sock.destroy()
-      resolve(ok)
-    }
-    sock.setTimeout(timeout)
-    sock.once('connect', () => done(true))
-    sock.once('timeout', () => done(false))
-    sock.once('error', () => done(false))
-    sock.connect(port, 'localhost')
-  })
+async function tcpPing(port: number, timeout = TCP_GATE_MS): Promise<string | null> {
+  try {
+    return await Promise.any(
+      LOOPBACK_PROBE_HOSTNAMES.map(
+        (hostname) =>
+          new Promise<string>((resolve, reject) => {
+            const sock = new net.Socket()
+            let settled = false
+            const done = (reachable: boolean) => {
+              if (settled) return
+              settled = true
+              sock.destroy()
+              if (reachable) resolve(hostname)
+              else reject(new Error(`unreachable loopback host ${hostname}`))
+            }
+            sock.setTimeout(timeout)
+            sock.once('connect', () => done(true))
+            sock.once('timeout', () => done(false))
+            sock.once('error', () => done(false))
+            sock.connect(port, hostname)
+          }),
+      ),
+    )
+  } catch {
+    return null
+  }
 }
 
 function httpGet(
+  hostname: string,
   port: number,
   path: string,
   method: 'GET' | 'HEAD' = 'GET',
@@ -103,7 +123,7 @@ function httpGet(
 ): Promise<HttpResult | null> {
   return new Promise((resolve) => {
     const req = http.request(
-      { hostname: 'localhost', port, path, method, timeout, headers },
+      { hostname, port, path, method, timeout, headers },
       (res) => {
         let body = ''
         res.on('data', (c: Buffer) => (body += c.toString()))
@@ -114,7 +134,12 @@ function httpGet(
           return undefined
         })()
         res.on('end', () =>
-          resolve({ statusCode: res.statusCode || 0, body, contentType }),
+          resolve({
+            statusCode: res.statusCode || 0,
+            body,
+            contentType,
+            hostname,
+          }),
         )
       },
     )
@@ -339,6 +364,7 @@ export async function resolveProcessCwd(pid: number): Promise<string | null> {
 // ── per-port probe orchestration ────────────────────────────────────────────
 
 function makeResult(
+  hostname: string,
   port: number,
   framework: DiscoveredServer['framework'],
   owner: Pick<DiscoveredServer, 'cwd' | 'pid'>,
@@ -348,10 +374,10 @@ function makeResult(
     framework,
     bundleUrl: withRuntimeConfig(
       port,
-      `http://localhost:${port}/index.bundle?platform=ios&dev=true&hot=true&minify=false`,
+      `${buildLoopbackProbeBaseUrl('http:', hostname, port)}/index.bundle?platform=ios&dev=true&hot=true&minify=false`,
       owner.cwd,
     ),
-    hmrUrl: `ws://localhost:${port}/hot`,
+    hmrUrl: `${buildLoopbackProbeBaseUrl('ws:', hostname, port)}/hot`,
     lastSeen: Date.now(),
     ...owner,
   }
@@ -399,10 +425,17 @@ 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,
+            buildLoopbackProbeBaseUrl('http:', manifestRes.hostname, result.port),
+          )
+        : rawLaunchUrl
     if (launchUrl && !result.patched && !isDirectOneBundleUrl(result.bundleUrl)) {
       result.bundleUrl = withRuntimeConfig(result.port, launchUrl, result.cwd)
     }
@@ -416,14 +449,14 @@ function applyManifest(
         } else {
           const cleanPath = rawIconUrl.replace(/^\.\//, '')
           result.iconUrl = buildIconProxyUrl(
-            `http://localhost:${result.port}/assets/${cleanPath}`,
+            `${buildLoopbackProbeBaseUrl('http:', manifestRes.hostname, result.port)}/assets/${cleanPath}`,
           )
         }
       } else {
         // no proxy requested — use the raw URL
         result.iconUrl = rawIconUrl.startsWith('http')
           ? rawIconUrl
-          : `http://localhost:${result.port}/assets/${rawIconUrl.replace(/^\.\//, '')}`
+          : `${buildLoopbackProbeBaseUrl('http:', manifestRes.hostname, result.port)}/assets/${rawIconUrl.replace(/^\.\//, '')}`
       }
     }
   } catch {}
@@ -434,7 +467,11 @@ export function __applyManifestForTests(
   result: DiscoveredServer,
   manifestBody: string,
 ): DiscoveredServer {
-  return applyManifest(result, { statusCode: 200, body: manifestBody })
+  return applyManifest(result, {
+    statusCode: 200,
+    body: manifestBody,
+    hostname: new URL(result.bundleUrl).hostname,
+  })
 }
 
 // ── name/icon enrichment ────────────────────────────────────────────────────
@@ -483,30 +520,42 @@ function enrichWithManifest(
 
   if (!enrichmentInFlight.has(result.port)) {
     enrichmentInFlight.add(result.port)
-    const port = result.port
-    void fetchManifestEnrichment(port, buildIconProxyUrl).finally(() =>
-      enrichmentInFlight.delete(port),
+    void fetchManifestEnrichment(result, buildIconProxyUrl).finally(() =>
+      enrichmentInFlight.delete(result.port),
     )
   }
   return result
 }
 
 async function fetchManifestEnrichment(
-  port: number,
+  result: DiscoveredServer,
   buildIconProxyUrl?: (externalUrl: string) => string,
 ): Promise<void> {
-  const manifestRes = await httpGet(port, '/', 'GET', ENRICH_TIMEOUT_MS, {
-    'expo-platform': 'ios',
-  })
+  const hostname = normalizeHostname(new URL(result.bundleUrl).hostname)
+  const manifestRes = await httpGet(
+    hostname,
+    result.port,
+    '/',
+    'GET',
+    ENRICH_TIMEOUT_MS,
+    {
+      'expo-platform': 'ios',
+    },
+  )
   if (!manifestRes || manifestRes.statusCode !== 200) return
   // reuse applyManifest's exact field extraction against a throwaway result.
   const parsed = applyManifest(
-    { port, framework: 'one', bundleUrl: '', lastSeen: 0 },
+    {
+      port: result.port,
+      framework: 'one',
+      bundleUrl: `${buildLoopbackProbeBaseUrl('http:', hostname, result.port)}/index.bundle`,
+      lastSeen: 0,
+    },
     manifestRes,
     buildIconProxyUrl,
   )
   if (!parsed.projectName && !parsed.iconUrl) return
-  enrichmentCache.set(port, {
+  enrichmentCache.set(result.port, {
     projectName: parsed.projectName,
     iconUrl: parsed.iconUrl,
     iconPath: parsed.iconPath,
@@ -514,7 +563,7 @@ async function fetchManifestEnrichment(
   })
   // the nameless result cached as a strong entry and won't re-probe on its own;
   // drop it so the next scan re-runs probePort and publishes the enriched name.
-  portCache.delete(port)
+  portCache.delete(result.port)
 }
 
 // ports confirmed to be running a non-sootsim dev server — safe to skip the
@@ -562,7 +611,8 @@ export async function probePort(
   // too, or a cold CLI process can build the known app's bundle url before its
   // runtime config is available.
   await loadOptionalDemoApps()
-  if (!(await tcpPing(port))) return null
+  const probeHostname = await tcpPing(port)
+  if (!probeHostname) return null
 
   const suppliedPid = listeningProcess?.pid
   const ownerPid =
@@ -577,12 +627,18 @@ export async function probePort(
 
   // wave 1 — safe parallel probes. none of these mutate metro state.
   const [sootsimRes, statusRes, manifestRes, expoRes] = await Promise.all([
-    knownNonPatched.has(port) ? Promise.resolve(null) : httpGet(port, '/__soot/'),
-    httpGet(port, '/status'),
+    knownNonPatched.has(port)
+      ? Promise.resolve(null)
+      : httpGet(probeHostname, port, '/__soot/'),
+    httpGet(probeHostname, port, '/status'),
     knownOne.has(port)
       ? Promise.resolve(null)
-      : httpGet(port, '/', 'GET', MANIFEST_TIMEOUT_MS, { 'expo-platform': 'ios' }),
-    knownNonExpo.has(port) ? Promise.resolve(null) : httpGet(port, '/_expo/status'),
+      : httpGet(probeHostname, port, '/', 'GET', MANIFEST_TIMEOUT_MS, {
+          'expo-platform': 'ios',
+        }),
+    knownNonExpo.has(port)
+      ? Promise.resolve(null)
+      : httpGet(probeHostname, port, '/_expo/status'),
   ])
 
   // remember negative /_expo/status responses so we don't keep probing this
@@ -620,7 +676,7 @@ export async function probePort(
     knownNonPatched.add(port)
     const launchUrl =
       manifestLaunchUrl ||
-      `http://localhost:${port}/index.bundle?platform=ios&dev=true&hot=true&minify=false`
+      `${buildLoopbackProbeBaseUrl('http:', probeHostname, port)}/index.bundle?platform=ios&dev=true&hot=true&minify=false`
     // call the framework "one" only when launchAsset clearly points at
     // a One metro entry; otherwise treat it as plain expo so downstream
     // bundle handling uses the right path semantics.
@@ -634,7 +690,7 @@ export async function probePort(
         port,
         framework,
         bundleUrl: withRuntimeConfig(port, launchUrl, owner.cwd),
-        hmrUrl: `ws://localhost:${port}/hot`,
+        hmrUrl: `${buildLoopbackProbeBaseUrl('ws:', probeHostname, port)}/hot`,
         lastSeen: Date.now(),
         ...owner,
       },
@@ -654,7 +710,12 @@ export async function probePort(
     knownNonPatched.add(port)
     return enrichWithManifest(
       applyManifest(
-        makeResult(port, expoRes && expoRes.statusCode === 200 ? 'expo' : 'metro', owner),
+        makeResult(
+          probeHostname,
+          port,
+          expoRes && expoRes.statusCode === 200 ? 'expo' : 'metro',
+          owner,
+        ),
         manifestRes,
         buildIconProxyUrl,
       ),
@@ -677,10 +738,10 @@ export async function probePort(
           framework: 'one',
           bundleUrl: withRuntimeConfig(
             port,
-            `http://localhost:${port}/__soot/bundle.js`,
+            `${buildLoopbackProbeBaseUrl('http:', probeHostname, port)}/__soot/bundle.js`,
             owner.cwd,
           ),
-          hmrUrl: `ws://localhost:${port}/hot`,
+          hmrUrl: `${buildLoopbackProbeBaseUrl('ws:', probeHostname, port)}/hot`,
           lastSeen: Date.now(),
           patched: true,
           ...owner,
@@ -719,7 +780,7 @@ export async function probePort(
     return null
   }
 
-  const oneRes = await httpGet(port, onePath, 'HEAD')
+  const oneRes = await httpGet(probeHostname, port, onePath, 'HEAD')
   if (
     oneRes &&
     oneRes.statusCode > 0 &&
@@ -735,10 +796,10 @@ export async function probePort(
           framework: 'one',
           bundleUrl: withRuntimeConfig(
             port,
-            `http://localhost:${port}${onePath}&minify=false`,
+            `${buildLoopbackProbeBaseUrl('http:', probeHostname, port)}${onePath}&minify=false`,
             owner.cwd,
           ),
-          hmrUrl: `ws://localhost:${port}/hot`,
+          hmrUrl: `${buildLoopbackProbeBaseUrl('ws:', probeHostname, port)}/hot`,
           lastSeen: Date.now(),
           ...owner,
         },

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/backend-origin.ts

@@ -1,9 +1,23 @@
 const DEFAULT_CONTRAST_BACKEND_ORIGIN = 'https://contrast.dev'
 
-function normalizeHostname(hostname: string): string {
+export const LOOPBACK_PROBE_HOSTNAMES = ['::1', '127.0.0.1'] as const
+
+export function normalizeHostname(hostname: string): string {
   return hostname.replace(/^\[|\]$/g, '').toLowerCase()
 }
 
+export function buildLoopbackProbeBaseUrl(
+  protocol: 'http:' | 'ws:',
+  hostname: string,
+  port: number,
+): string {
+  const normalizedHostname = normalizeHostname(hostname)
+  const urlHost = normalizedHostname.includes(':')
+    ? `[${normalizedHostname}]`
+    : normalizedHostname
+  return `${protocol}//${urlHost}:${port}`
+}
+
 export function isLoopbackHost(hostname: string): boolean {
   const normalized = normalizeHostname(hostname)
   return (

package/src/dev-bundle-resolution.ts

@@ -1,5 +1,13 @@
-import { isLoopbackHost } from './backend-origin'
-import { METRO_BUNDLE_PATH, normalizeNativeDevBundleUrl } from './native-dev-bundle-url'
+import {
+  buildLoopbackProbeBaseUrl,
+  isLoopbackHost,
+  LOOPBACK_PROBE_HOSTNAMES,
+} from './backend-origin'
+import {
+  alignLoopbackBundleUrlWithProbe,
+  METRO_BUNDLE_PATH,
+  normalizeNativeDevBundleUrl,
+} from './native-dev-bundle-url'
 
 export const DEFAULT_TEST_DRIVE_PORT = 8081
 
@@ -65,8 +73,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 +117,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),
@@ -123,21 +131,12 @@ async function resolvePortViaServerScan(port: number): Promise<ResolvedDevBundle
   }
 }
 
-async function probeBaseUrlBundle(
+async function probeBaseUrlBundleDirect(
   baseUrl: string,
   port: number,
 ): Promise<ResolvedDevBundle | null> {
   const normalizedBaseUrl = baseUrl.replace(/\/+$/, '')
 
-  // browser/worker loopback targets resolve through the server-side scanner so
-  // they match the dev-server list exactly — see resolvePortViaServerScan.
-  try {
-    if (isLoopbackHost(new URL(normalizedBaseUrl).hostname)) {
-      const viaScan = await resolvePortViaServerScan(port)
-      if (viaScan) return viaScan
-    }
-  } catch {}
-
   try {
     const manifestRes = await fetchDevProbe(`${normalizedBaseUrl}/`, {
       headers: { 'expo-platform': 'ios' },
@@ -145,10 +144,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(
@@ -191,8 +193,30 @@ async function probeBaseUrlBundle(
   return null
 }
 
+async function probeBaseUrlBundle(
+  baseUrl: string,
+  port: number,
+): Promise<ResolvedDevBundle | null> {
+  // browser/worker loopback targets resolve through the server-side scanner so
+  // they match the dev-server list exactly — see resolvePortViaServerScan.
+  try {
+    if (isLoopbackHost(new URL(baseUrl).hostname)) {
+      const viaScan = await resolvePortViaServerScan(port)
+      if (viaScan) return viaScan
+    }
+  } catch {}
+  return probeBaseUrlBundleDirect(baseUrl, port)
+}
+
 export async function probePortBundle(port: number): Promise<ResolvedDevBundle | null> {
-  return probeBaseUrlBundle(buildBaseUrl('http:', 'localhost', port), port)
+  const viaScan = await resolvePortViaServerScan(port)
+  if (viaScan) return viaScan
+  const candidates = await Promise.all(
+    LOOPBACK_PROBE_HOSTNAMES.map((hostname) =>
+      probeBaseUrlBundleDirect(buildLoopbackProbeBaseUrl('http:', hostname, port), port),
+    ),
+  )
+  return candidates.find((candidate) => candidate !== null) ?? null
 }
 
 export async function resolveConnectionInput(input: string): Promise<ResolvedDevBundle> {

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()
+  })
+}