rnxsim 0.1.376 → 0.1.378

package/README.md

@@ -10,7 +10,7 @@ React Native simulator.
 contains **no rendering code**. The canvas engine (CanvasKit renderer, Yoga
 layout, iOS/Android shell chrome, Electron shell) lives in the private
 `sootsim-engine` workspace package and is shipped at runtime as a versioned
-tarball, fetched from the contrast.dev CDN and unpacked into `~/.sootsim`.
+tarball, fetched from the contrast.dev CDN and unpacked into `~/.rnx`.
 
 What this package gives you:
 
@@ -87,7 +87,7 @@ graph TD
     ENGINESHIM["sootsim-engine react-native shim"]
   end
   SKILLS["rnxsim/skills registry.ts (builtin skills)"]
-  subgraph fs["~/.sootsim (home-paths.ts)"]
+  subgraph fs["~/.rnx (home-paths.ts)"]
     RTDIR["runtimes/<version>/ (engine assets)"]
     LOCK["daemon.json lockfile"]
     CFG["config.json"]
@@ -149,7 +149,7 @@ Electron is the native desktop surface.
 
 **The daemon is one process** — `SootSimBridgeHost` (`src/host/bridge-host.ts`).
 `rnx serve` runs it in the foreground; the background daemon is the *same
-process* wrapped with autostart and the `~/.sootsim/daemon.json` lockfile. It is
+process* wrapped with autostart and the `~/.rnx/daemon.json` lockfile. It is
 an HTTP+WS hub: sims register over WS, CLI clients connect to drive them, and
 the host forwards each command to the targeted sim and relays the reply back. It
 also serves the engine runtime over HTTP (with a self-update route), exposes
@@ -159,7 +159,7 @@ localhost. The `AgentHost` extension owns one FIFO reader per agent session and
 fans agent events out to every subscriber.
 
 During source development, each Vite bridge owns one
-`~/.sootsim/dev-bridges/<port>.json` heartbeat record. CLI defaults select the
+`~/.rnx/dev-bridges/<port>.json` heartbeat record. CLI defaults select the
 current `PORT_OFFSET`, then the current checkout, then the canonical `:7668`
 bridge, so concurrent worktrees cannot replace or delete one another's address.
 
@@ -175,7 +175,7 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
   and **`rnxsim/metro`** plugins do one thing: serve the installed runtime at
   `/__soot/` so an app's own dev server can host the sim shell. Both accept an
   opt-in `open` option that launches a named Electron window when the dev server
-  starts (skipped when `CI` or `SOOTSIM_NO_OPEN` is set).
+  starts (skipped when `CI` or `RNX_NO_OPEN` is set).
 - The internal **`sootsim()`** plugin (`src/vite-plugin.ts`) is a separate, much
   larger RN-resolution / native-stub plugin: it aliases `react-native` to the
   engine shim and native packages to `@sootsim/compat` stubs, applies worklets
@@ -196,20 +196,21 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 | SootSimBridgeHost (serve/daemon) | The bridge process (`rnx serve`, or autostarted as the daemon via launchd/systemd). HTTP+WS hub on `:7668`: relays commands between CLI clients and registered sims; also serves runtime HTTP, `/__server-scan`, and fetch/WS proxies. | `src/host/bridge-host.ts`, `cli/commands/serve.ts`, `cli/commands/daemon.ts`, `src/home-paths.ts` |
 | AgentHost + sessions | Agent-routing extension of the host: owns the single FIFO reader per agent session and fans `agent:event`/`session-status` pushes to every WS subscriber. Backed by agent-sessions + attached-projects stores. | `src/host/agent-host.ts`, `src/agent-sessions.ts`, `src/attached-projects.ts`, `src/agent-daemon-client.ts` |
 | host proxies + dev-server scan | Host-side helpers so a cross-origin tenant worker can reach local dev servers and same-origin APIs: `/__server-scan` discovers running metro/expo/vxrn/one servers; fetch + websocket proxies relay guest-app network through the daemon. | `src/host/fetch-proxy-handler.ts`, `src/host/websocket-proxy.ts`, `scripts/dev-server-scanner.ts`, `src/dev-bundle-resolution.ts` |
-| runtime delivery + rnx home | Versioned engine runtime management. The shared machinery owns manifest fetch, sha256 verification, channels, and auto-update. rnx binds it to `https://contrast.dev` and `~/.sootsim/runtimes/<version>`. A repo can select `runtimeVersion` without changing the machine default. | `src/runtime-delivery.ts`, `packages/contrast-runtime-delivery/`, `src/home-paths.ts`, `src/runtime-assets.ts`, `scripts/postinstall.cjs` |
-| `rnxsim/vite` + `rnxsim/metro` (runtime serving) | Published bundler plugins. Both serve the installed engine runtime at `/__soot/` from `~/.sootsim/runtimes/<version>` so an app's own dev server can host the sim shell; either plugin can opt into a named Electron window. | `src/vite-plugin-one.ts`, `src/metro-plugin.ts`, `src/runtime-assets.ts` |
+| runtime delivery + rnx home | Versioned engine runtime management. The shared machinery owns manifest fetch, sha256 verification, channels, and auto-update. rnx binds it to `https://contrast.dev` and `~/.rnx/runtimes/<version>`. A repo can select `runtimeVersion` without changing the machine default. | `src/runtime-delivery.ts`, `packages/contrast-runtime-delivery/`, `src/home-paths.ts`, `src/runtime-assets.ts` |
+| `rnxsim/vite` + `rnxsim/metro` (runtime serving) | Published bundler plugins. Both serve the installed engine runtime at `/__soot/` from `~/.rnx/runtimes/<version>` so an app's own dev server can host the sim shell; either plugin can opt into a named Electron window. | `src/vite-plugin-one.ts`, `src/metro-plugin.ts`, `src/runtime-assets.ts` |
 | `sootsim()` vite resolver plugin (internal) | The large RN-resolution / native-stub vite plugin: aliases `react-native` to the engine shim, native packages to `@sootsim/compat` stubs, applies worklets/babel transforms, and instantiates `SootSimBridgeHost` in its dev server. Distinct from the published `rnxsim/vite` export. | `src/vite-plugin.ts`, `src/worklets-babel.ts`, `packages/compat/src/stub-manifest.ts` |
 | skills registry | rnx agent skills (`rnx-setup`, `rnx-debug`, `rnx-test`, `rnx-visual`, and the generated `contrast` index) installable with `rnx skill`. | `skills/*.md`, `src/skills/registry.ts`, `src/skills/types.ts` |
 
 ## Getting started
 
 ```sh
-npx rnxsim          # open ConnectRN and choose a running app in the simulator
+curl -fsSL https://rnxsim.com/install.sh | sh
+rnx                 # open ConnectRN and choose a running app in the simulator
 rnx open /settings  # dispatch a React Native deep link into that app
 ```
 
 Start Metro, Expo, One, or another supported React Native development server
-the way you normally do, then run `npx rnxsim` from any directory. The simulator
+the way you normally do, then run `rnx` from any directory. The simulator
 opens ConnectRN, which shows the available local apps and lets you connect one.
 Pass a target to `rnx open <port-or-url>` when a script or agent needs an explicit
 selection.
@@ -223,10 +224,10 @@ requested target. Use `rnx do reload` when the target has not changed.
 Reserve `--new` for a genuinely concurrent sim; repeated new browser trees
 consume memory and CPU on shared machines.
 
-There is no required global or per-app install. Optional global installs can
-use `npm install --global rnxsim`, `bun add --global rnxsim`, or
-`pnpm add --global rnxsim`. Start your Metro, Expo, or One dev server the way you
-already do, then open it from the CLI. There is no iOS native build in the inner loop; Metro alone is
+The public installer places one standalone `rnx` executable in `~/.local/bin`.
+The `rnxsim` npm package contains bundler plugins and library exports, not a CLI
+binary. Start your Metro, Expo, or One dev server the way you already do, then
+open it from the CLI. There is no iOS native build in the inner loop; Metro alone is
 enough. The manifest bundle path and query remain authoritative. When both the
 discovery request and manifest target are loopback addresses, RNX keeps the
 loopback host that answered discovery so an IPv6-only listener is not reopened
@@ -259,7 +260,7 @@ enforced network contract is in [`specs/rnx-privacy.md`](../../specs/rnx-privacy
 
 To uninstall the machine daemon and cached runtimes, run
 `rnx daemon uninstall`. It stops current and legacy launchd / systemd
-services, removes daemon logs, and removes `~/.sootsim/` (runtimes, profiles,
+services, removes daemon logs, and removes `~/.rnx/` (runtimes, profiles,
 recordings, and lockfiles). It does not remove the optional
 `/Applications/rnx.app` desktop bundle or macOS preference plist. To inspect
 existing disk usage before uninstalling, run `rnx cleanup`; add `--apply`
@@ -366,7 +367,7 @@ uses about 267 MiB, so the browser remains the recommended first-run path and
 Electron is an opt-in desktop upgrade. The notarized CLI install did not produce
 a Gatekeeper prompt on a clean profile. A Mac that previously ran an unsigned
 development Electron build against the same user-data directory may ask for
-one-time Keychain approval. `SOOTSIM_NO_OPEN=1` keeps the server headless. The
+one-time Keychain approval. `RNX_NO_OPEN=1` keeps the server headless. The
 Metro wrapper also has two independent non-window opt-ins.
 `devServer` serves the RNX shell from the Metro process. `productionBundles`
 lets explicitly marked production bundle requests use the RNX host
@@ -442,8 +443,8 @@ rnx debug snapshot before
 # reproduce the transition
 rnx debug snapshot after
 rnx debug diff before after
-rnx screenshot --with-frame --output /tmp/sootsim-framed.png
-rnx record --duration 5 --output /tmp/sootsim-anim.mp4
+rnx screenshot --with-frame --output /tmp/rnx-framed.png
+rnx record --duration 5 --output /tmp/rnx-anim.mp4
 ```
 
 `rnx screenshot --with-frame` composes the real rnx shell device chrome
@@ -486,7 +487,7 @@ compose:
 ```
 
 ```sh
-rnx screenshot appstore --plan .sootsim/app-store.yaml
+rnx screenshot appstore --plan .rnx/app-store.yaml
 ```
 
 The plan runner can reuse a visible sim for capture (`--sim a9`), stop after
@@ -533,10 +534,10 @@ rnx's CDN origin (default `https://contrast.dev`, overridable in
 them to the shared delivery machinery in `@contrast/runtime-delivery` — an
 internal workspace package the CLI bundles, so a published install has it
 inlined. That machinery fetches `runtimes/manifest.json` + the runtime tarball,
-verifies its sha256, and unpacks it under `~/.sootsim`:
+verifies its sha256, and unpacks it under `~/.rnx`:
 
 ```
-~/.sootsim/
+~/.rnx/
 ├── runtimes/
 │   ├── <active>/         unpacked engine assets (served at /__soot/)
 │   └── <rollback>/       previous version for rollback
@@ -561,7 +562,7 @@ Per-repo configuration is optional. Every installed-runtime `rnx open`
 serves its selected version from a version-specific localhost origin, so a
 background activation cannot mix an already loaded shell with chunks from the
 next runtime. Without config, each new open selects the active stable version.
-When `sootsim.config.ts` sets `runtimeVersion`, `rnx open` installs that
+When `rnx.config.ts` sets `runtimeVersion`, `rnx open` installs that
 version without changing the machine default. App config, native-linked fonts,
 and splash assets all resolve from the project root advertised by the selected
 development server. Bare Metro, which has no Expo manifest project root, uses
@@ -582,13 +583,15 @@ recordings.
 
 ## Development and building
 
-This package is part of the Contrast monorepo. To build the published CLI bundle:
+This package is part of the Contrast monorepo. To build the standalone executable
+for the current platform:
 
 ```sh
-bun run build:cli
+bun run build:cli-binary
 ```
 
-The output is `dist-cli/bin.js` — a single esbuild output published as the
-`rnx` (and `rnxsim`) npm bin. Library exports build to `dist-lib/` (consumed via the
+The output is `dist-bin/rnx-<platform>-<arch>`. `dist-cli/bin.js` remains a
+repository build artifact for tests and internal tooling and is not published
+as an npm executable. Library exports build to `dist-lib/` (consumed via the
 `exports` map: `.`, `./vite`, `./metro`, `./sdk`, `./skills`, `./detox`, and the
 host/agent helpers). `bun run pack:smoke` validates the publishable tarball.

package/cli/app-config.ts

@@ -4,7 +4,7 @@ import { isValidRuntimeVersion } from '@contrast/runtime-delivery'
 import { createJiti } from 'jiti'
 import { rnxPublicBrand } from '../src/public-brand'
 import { resolveAppProject, type ResolvedAppProject } from './app-project'
-import type { SootSimConfig } from '../src/config'
+import type { RNXConfig } from '../src/config'
 
 const require = createRequire(import.meta.url)
 
@@ -15,7 +15,7 @@ function isOptionalRecord(value: unknown): boolean {
   )
 }
 
-function isSootSimConfig(value: unknown): value is SootSimConfig {
+function isRNXConfig(value: unknown): value is RNXConfig {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false
   const runtimeVersion = Reflect.get(value, 'runtimeVersion')
   const network = Reflect.get(value, 'network')
@@ -34,10 +34,7 @@ function isSootSimConfig(value: unknown): value is SootSimConfig {
   )
 }
 
-function resolveConfigReplacementFiles(
-  config: SootSimConfig,
-  configPath: string,
-): SootSimConfig {
+function resolveConfigReplacementFiles(config: RNXConfig, configPath: string): RNXConfig {
   if (!config.modules) return config
   const configDir = path.dirname(configPath)
   return {
@@ -53,9 +50,9 @@ function resolveConfigReplacementFiles(
   }
 }
 
-export async function loadSootSimAppConfig(
+export async function loadRNXAppConfig(
   project: ResolvedAppProject | null,
-): Promise<SootSimConfig | undefined> {
+): Promise<RNXConfig | undefined> {
   if (!project?.configPath) return undefined
   try {
     const jiti = createJiti(import.meta.url, {
@@ -67,7 +64,7 @@ export async function loadSootSimAppConfig(
       },
     })
     const loaded: unknown = await jiti.import(project.configPath, { default: true })
-    if (!isSootSimConfig(loaded)) {
+    if (!isRNXConfig(loaded)) {
       throw new Error('the default export must be an rnx config object')
     }
     return resolveConfigReplacementFiles(loaded, project.configPath)
@@ -77,9 +74,9 @@ export async function loadSootSimAppConfig(
   }
 }
 
-export async function resolveSootSimAppConfig(
+export async function resolveRNXAppConfig(
   startDir: string = process.cwd(),
-): Promise<{ project: ResolvedAppProject | null; config: SootSimConfig | undefined }> {
+): Promise<{ project: ResolvedAppProject | null; config: RNXConfig | undefined }> {
   const project = resolveAppProject(startDir)
-  return { project, config: await loadSootSimAppConfig(project) }
+  return { project, config: await loadRNXAppConfig(project) }
 }

package/cli/app-fonts.ts

@@ -260,9 +260,9 @@ export function discoverNativeLinkedAppFonts(opts: {
 
 // resolve a metro dev server's project root. expo serves a manifest at the
 // server origin carrying `extra.expoClient._internal.projectRoot` — the absolute
-// dir of the app being served. the local `sootsim open <port>` path runs from the
+// dir of the app being served. the local `rnx open <port>` path runs from the
 // CLI's cwd, which almost never owns the bundle being opened (e.g.
-// `sootsim open 8081` run from ~/soot against a 3pc metro), so scanning cwd for
+// `rnx open 8081` run from ~/soot against a 3pc metro), so scanning cwd for
 // font declarations finds nothing.
 //
 // a bare react-native packager serves no such manifest, so the same resolver
@@ -355,7 +355,7 @@ export type FetchedAppFont = {
 // fetch every config-plugin font declared on an engine `?appFonts=` wire.
 // these typefaces live in the native binary, never in the metro bundle's
 // __packager_asset graph, so neither asset capture nor recorded fetches see
-// them — both the preview (`sootsim record upload`) and build (`sootsim app-fonts
+// them — both the preview (`rnx record upload`) and build (`rnx app-fonts
 // stage`) paths backfill by re-fetching the declared urls off the still-live
 // metro. one implementation so both pipelines store identical bytes + keys.
 export async function fetchAppFontFiles(

package/cli/app-project.ts

@@ -9,11 +9,11 @@ export const EXPO_APP_CONFIG_NAMES = [
   'app.json',
 ] as const
 
-export const SOOTSIM_APP_CONFIG_NAMES = [
-  'sootsim.config.ts',
-  'sootsim.config.js',
-  'sootsim.config.mjs',
-  'sootsim.config.cjs',
+export const RNX_APP_CONFIG_NAMES = [
+  'rnx.config.ts',
+  'rnx.config.js',
+  'rnx.config.mjs',
+  'rnx.config.cjs',
 ] as const
 
 export interface ResolvedAppProject {
@@ -35,8 +35,8 @@ export function findExpoAppConfig(dir: string): string | null {
   return firstNamedFile(dir, EXPO_APP_CONFIG_NAMES)
 }
 
-export function findSootSimAppConfig(dir: string): string | null {
-  return firstNamedFile(dir, SOOTSIM_APP_CONFIG_NAMES)
+export function findRNXAppConfig(dir: string): string | null {
+  return firstNamedFile(dir, RNX_APP_CONFIG_NAMES)
 }
 
 export function resolveAppProject(projectRoot: string): ResolvedAppProject | null {
@@ -47,7 +47,7 @@ export function resolveAppProject(projectRoot: string): ResolvedAppProject | nul
     return null
   }
 
-  const configPath = findSootSimAppConfig(appDir)
+  const configPath = findRNXAppConfig(appDir)
   if (
     !configPath &&
     !findExpoAppConfig(appDir) &&

package/cli/auth.ts

@@ -1,7 +1,7 @@
-// sootsim cli auth resolution for cloud-hitting commands.
+// rnx cli auth resolution for cloud-hitting commands.
 //
 // priority order (first match wins):
-//   1. RNX_API_KEY, or SOOTSIM_API_KEY if that is unset — ci path
+//   1. RNX_API_KEY — ci path
 //   2. CONTRAST_INSTALLATION_TOKEN/GITHUB_TOKEN + repo env — github action
 //      preview uploads from the Contrast runner, no extra secret
 //   3. desktop session token from shared desktop auth (`rnx login`)
@@ -11,7 +11,7 @@
 import { readSharedDesktopAuthSession } from '../src/auth/shared-session'
 import { rnxExit } from './run-rnx'
 
-export type CliApiKeyEnvName = 'RNX_API_KEY' | 'SOOTSIM_API_KEY'
+export type CliApiKeyEnvName = 'RNX_API_KEY'
 
 export type CliAuth =
   | { kind: 'api-key'; secret: string; source: 'env'; envName: CliApiKeyEnvName }
@@ -93,15 +93,13 @@ function resolveGitHubActionsAuth(): CliAuth | null {
 }
 
 function isCliApiKeySecret(secret: string): boolean {
-  return secret.startsWith('sk_rnx_') || secret.startsWith('sk_sootsim_')
+  return secret.startsWith('sk_rnx_')
 }
 
 function readApiKeyFromEnv(): { secret: string; envName: CliApiKeyEnvName } | null {
-  for (const envName of ['RNX_API_KEY', 'SOOTSIM_API_KEY'] as const) {
-    const secret = process.env[envName]?.trim()
-    if (secret && isCliApiKeySecret(secret)) return { secret, envName }
-  }
-  return null
+  const envName = 'RNX_API_KEY'
+  const secret = process.env[envName]?.trim()
+  return secret && isCliApiKeySecret(secret) ? { secret, envName } : null
 }
 
 export function resolveCliAuth(): CliAuth | null {

package/cli/bin.ts

@@ -9,6 +9,7 @@
 import { rnxPublicBrand } from '../src/public-brand'
 import { parseArgs, TOP_LEVEL_RUNTIME_COMMANDS } from './parse-args'
 import { RnxExit } from './run-rnx'
+import { IS_STANDALONE } from './standalone'
 
 // `./help` is loaded lazily (only on help paths) — it statically pulls the full
 // CLI registry renderers and engine settings, which would otherwise add ~400ms
@@ -54,28 +55,8 @@ function handleTopLevelError(err: unknown): never {
 process.on('unhandledRejection', handleTopLevelError)
 process.on('uncaughtException', handleTopLevelError)
 
-// set to `true` by build-cli-binary.ts via esbuild define. in the standalone
-// binary, commands that rely on vite / electron / playwright from the user's
-// node_modules can't run — gate them with a friendly message rather than
-// letting the dynamic import fail with a confusing module-not-found error.
-declare const __SOOTSIM_STANDALONE__: boolean | undefined
-const IS_STANDALONE =
-  typeof __SOOTSIM_STANDALONE__ !== 'undefined' && __SOOTSIM_STANDALONE__
-
-const STANDALONE_BLOCKED_COMMANDS = new Set(['desktop'])
-
-function exitIfStandaloneBlocked(cmd: string): void {
-  if (!IS_STANDALONE || !STANDALONE_BLOCKED_COMMANDS.has(cmd)) return
-  process.stderr.write(
-    `  ${rnxPublicBrand.commandName} ${cmd} isn't available in the standalone binary —\n` +
-      `  it needs vite / electron / playwright from a project's node_modules.\n` +
-      `  run the npm package instead:\n` +
-      `    ${rnxPublicBrand.commandName} ${cmd}\n`,
-  )
-  process.exit(1)
-}
-
 let parsed = parseArgs(process.argv)
+for (const warning of parsed.warnings) process.stderr.write(`${warning}\n`)
 
 // runtime actions and reads also work as hidden root aliases. resolve only
 // after the normal parser declined the token, so a real top-level command
@@ -90,6 +71,8 @@ const isAutomaticCleanupWorker =
   parsed.commandArgs.length === 1 &&
   parsed.commandArgs[0] === '--automatic-worker'
 const isBareWelcome = !parsed.command && parsed.commandArgs.length === 0
+const isReadOnlyInvocation =
+  parsed.version || parsed.help || parsed.commandArgs.includes('--dry-run')
 
 if (
   !isAutomaticCleanupWorker &&
@@ -109,7 +92,7 @@ if (
 // interactive command runs next prints it once (stderr, so --json stdout
 // stays parseable) and deletes it. the daemon/serve processes skip it so a
 // background process can't eat the notice before a human sees it.
-if (parsed.command !== 'serve' && parsed.command !== 'daemon') {
+if (!isReadOnlyInvocation && parsed.command !== 'serve' && parsed.command !== 'daemon') {
   const { consumeRuntimeUpgradeNotice } = await import('../src/home-paths')
   const notice = consumeRuntimeUpgradeNotice()
   if (notice) {
@@ -126,6 +109,7 @@ async function scheduleAutomaticCleanup(): Promise<void> {
   if (automaticCleanupFinished) return
   automaticCleanupFinished = true
   if (
+    isReadOnlyInvocation ||
     parsed.command === 'cleanup' ||
     parsed.command === 'serve' ||
     parsed.command === 'agent-wrapper' ||
@@ -193,7 +177,7 @@ if (parsed.version) {
   console.log(`${rnxPublicBrand.commandName} v${getCliVersion()}${suffix}`)
   // runtime version on its own line — keeps the first line parseable while
   // surfacing the (independently-versioned) engine runtime users actually
-  // render with. see `sootsim upgrade`.
+  // render with. see `rnx upgrade`.
   const { readActiveRuntime } = await import('../src/home-paths')
   const runtime = readActiveRuntime()
   console.log(runtime ? `runtime v${runtime}` : 'runtime not installed')
@@ -281,8 +265,8 @@ if (
     await exitWithFlush(await runReset(commandArgsWithSim, { port }))
   }
   // for grouping verbs, try to resolve per-verb help from the first
-  // positional arg. e.g. `sootsim do tap --help` shows tap's help page,
-  // not the generic `do` grouping page. bare `sootsim do --help` falls
+  // positional arg. e.g. `rnx do tap --help` shows tap's help page,
+  // not the generic `do` grouping page. bare `rnx do --help` falls
   // through to runInspect which has the full verb group listing.
   const isGroupingVerb =
     command === 'do' ||
@@ -312,12 +296,6 @@ if (
   }
 }
 
-// gate heavy commands in the standalone binary before any dynamic imports
-// fire. the imports themselves would also fail (vite / electron etc. are
-// kept external from the bundle), but the resulting module-not-found error
-// is much harder to act on than this targeted message.
-exitIfStandaloneBlocked(command)
-
 // the command modules stop by throwing RnxExit rather than ending the
 // process, because the same command has to run in a box shell and in
 // workerd, where process.exit() cancels the whole request. this is the
@@ -453,6 +431,13 @@ try {
         await exitWithFlush(typeof code === 'number' ? code : 0)
       }
 
+      case 'web': {
+        const { getRnxCommandAvailability } = await import('./command-registry')
+        const availability = getRnxCommandAvailability('web', parsed.commandArgs, 'node')
+        console.error(`  ${availability.reason ?? 'rnx web is unavailable'}`)
+        await exitWithFlush(1)
+      }
+
       case 'box': {
         const { runBox } = await import('./commands/box')
         await exitWithFlush(await runBox(commandArgsWithSim, { port, verbose }))

package/cli/bridge-flow-runner.ts

@@ -432,7 +432,7 @@ export class SootSimBridgeFlowRunner {
       screenshotPathMode?: FlowScreenshotPathMode
       // flow-wide default for screenshot layers — applied to every
       // takeScreenshot step unless that step has its own `layers:`. set by
-      // `sootsim maestro test --no-shell` to produce clean tenant-only captures
+      // `rnx maestro test --no-shell` to produce clean tenant-only captures
       // (useful when a stuck shell overlay would otherwise pollute the
       // demo asset set).
       screenshotLayers?: 'full' | 'tenant' | 'shell'
@@ -688,7 +688,7 @@ export class SootSimBridgeFlowRunner {
     const extension = videoMime.includes('mp4') ? 'mp4' : 'webm'
     const outputPath = path.join(
       this.opts.recordingOutputDir,
-      `sootsim-${Date.now()}.${extension}`,
+      `rnx-${Date.now()}.${extension}`,
     )
     fs.writeFileSync(outputPath, Buffer.concat(chunks))
     return outputPath
@@ -1573,7 +1573,7 @@ export class SootSimBridgeFlowRunner {
     if (typeof tree === 'string') write('tree.txt', tree)
 
     // 6. console buffer + failed requests (captured by sootsim's native-globals
-    // hook / request recorder; same shape as `sootsim get errors` etc.).
+    // hook / request recorder; same shape as `rnx get errors` etc.).
     const consoleBuf = await safeEval<{
       errors: unknown[]
       warnings: unknown[]

package/cli/browser-backend.ts

@@ -0,0 +1,44 @@
+import type {
+  RnxBrowserOperations,
+  RnxCommandBackend,
+  RnxCommandInvocation,
+  RnxExecutionContext,
+} from './command-contract'
+
+export function createRnxBrowserBackend(
+  operations: RnxBrowserOperations,
+): RnxCommandBackend {
+  return {
+    kind: 'browser',
+    execute(invocation: RnxCommandInvocation, context: RnxExecutionContext) {
+      switch (invocation.family) {
+        case 'preview':
+          return operations.selectPreview(invocation, context)
+        case 'runtime':
+          return operations.readRuntime(invocation, context)
+        case 'tree':
+          return operations.inspectTree(invocation, context)
+        case 'layout':
+          return operations.inspectLayout(invocation, context)
+        case 'find':
+          return operations.find(invocation, context)
+        case 'wait':
+          return operations.wait(invocation, context)
+        case 'action':
+          return operations.act(invocation, context)
+        case 'screenshot':
+          return operations.screenshot(invocation, context)
+        case 'logs':
+          return operations.readLogs(invocation, context)
+        case 'network':
+          return operations.readNetwork(invocation, context)
+        case 'storage':
+          return operations.accessStorage(invocation, context)
+        case 'history':
+          return operations.readHistory(invocation, context)
+        case 'evidence':
+          return operations.collectEvidence(invocation, context)
+      }
+    },
+  }
+}