rnxsim 0.1.376 → 0.1.377

package/cli/commands/upgrade.ts

@@ -1,57 +1,43 @@
-// sootsim upgrade — one command to get current.
-//
-// the sootsim CLI (the `sootsim` npm package) and the engine runtime (the
-// versioned tarball served to the browser/electron shell) are versioned
-// independently. that split is a frequent source of "I ran upgrade but the
-// version didn't change" confusion — the user upgraded one half. this
-// command checks and updates both:
-//
-//   1. CLI     — query the npm registry; if behind, self-update the global
-//                install with the same package manager that installed it
-//                (bun/pnpm/npm, detected from the running binary's path).
-//                npx-cache runs can't self-update in place, so those get
-//                the exact command to run instead.
-//   2. runtime — delegate to `sootsim runtime install`, which resolves the
-//                channel's latest, downloads + verifies
-//                it, and activates.
-//
-// each half is a no-op when already current, so the command is safe to
-// run anytime.
-
-import { spawn } from 'node:child_process'
+// rnx upgrade updates the separately delivered runtime first, then atomically
+// replaces the standalone cli executable. runtime stays first because replacing
+// the running cli's files before later dynamic imports can strand the command.
+
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
 import fs from 'node:fs'
-import os from 'node:os'
 import path from 'node:path'
 import { compareSemver } from '@contrast/runtime-delivery'
 import { getCliVersion } from '../../src/cli-version'
-import {
-  isSootsimDevCheckout,
-  readActiveRuntime,
-  runtimeDir,
-  sootsimHomeDir,
-} from '../../src/home-paths'
-import { resolveSootSimAppConfig } from '../app-config'
+import { isSootsimDevCheckout, readActiveRuntime, runtimeDir } from '../../src/home-paths'
+import { resolveRNXAppConfig } from '../app-config'
 import { fetchRuntimeReleaseNotes, formatRuntimeReleaseNotes } from '../runtime-notes'
+import { IS_STANDALONE } from '../standalone'
 import { runRuntime } from './runtime'
 
-const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/rnxsim/latest'
+const DEFAULT_CLI_RELEASE_ORIGIN = 'https://r2.rnxsim.com/rnx-cli'
+const CLI_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+const SHA256_PATTERN = /^[a-f0-9]{64}$/
+
+export interface UpgradeOptions {
+  cliExecutablePath?: string
+  cliReleaseOrigin?: string
+  standalone?: boolean
+  includeReleaseNotes?: boolean
+}
 
-export async function runUpgrade(args: string[]): Promise<void> {
-  // `--help` is handled upstream in bin.ts via the CLI registry (meta.ts) —
-  // it never reaches here.
+export async function runUpgrade(
+  args: string[],
+  options: UpgradeOptions = {},
+): Promise<void> {
   const channelIdx = args.indexOf('--channel')
   const channel =
     channelIdx >= 0 && args[channelIdx + 1] ? args[channelIdx + 1] : undefined
 
   console.log('rnx upgrade\n')
 
-  // --- 1. engine runtime --------------------------------------------------
-  // runtime first, CLI last: the CLI self-update replaces this process's
-  // own dist files on disk, and any dynamic import after the swap resolves
-  // against renamed chunk hashes and crashes (observed in a container run).
   console.log('runtime:')
   const beforeRuntime = readActiveRuntime()
-  const { config } = await resolveSootSimAppConfig()
+  const { config } = await resolveRNXAppConfig()
   const configuredRuntime = config?.runtimeVersion
   const configuredRuntimeWasInstalled = configuredRuntime
     ? fs.existsSync(path.join(runtimeDir(configuredRuntime), 'index.html'))
@@ -84,125 +70,124 @@ export async function runUpgrade(args: string[]): Promise<void> {
             : `  result:  v${installedRuntime} already current`,
     )
   }
-  const releaseNotes = installedRuntime
-    ? await fetchRuntimeReleaseNotes(installedRuntime)
-    : null
+  const releaseNotes =
+    installedRuntime && options.includeReleaseNotes !== false
+      ? await fetchRuntimeReleaseNotes(installedRuntime)
+      : null
 
-  // --- 2. CLI npm package -------------------------------------------------
   console.log('\ncli:')
-  await upgradeCli()
+  await upgradeCli(options)
 
-  if (installedRuntime) {
+  if (installedRuntime && options.includeReleaseNotes !== false) {
     console.log(`\n${formatRuntimeReleaseNotes(installedRuntime, releaseNotes)}`)
   }
 }
 
-type CliInstallKind =
-  | { kind: 'dev' }
-  | { kind: 'npx' }
-  | { kind: 'global'; command: string; args: string[] }
-
-// how is this CLI process installed? keyed off the real path of the running
-// entry script — global installs land under each manager's global root,
-// npx/bunx runs land in their throwaway caches, and the Contrast monorepo dev
-// checkout runs from packages/sootsim.
-function detectCliInstall(): CliInstallKind {
-  if (isSootsimDevCheckout()) return { kind: 'dev' }
-  let real = process.argv[1] ?? ''
-  try {
-    real = fs.realpathSync(real)
-  } catch {}
-  const sep = path.sep
-  if (real.includes(`${sep}_npx${sep}`) || real.includes(`${sep}.bunx${sep}`)) {
-    return { kind: 'npx' }
-  }
-  if (real.includes(`${sep}.bun${sep}`)) {
-    return { kind: 'global', command: 'bun', args: ['add', '-g', 'rnxsim@latest'] }
-  }
-  if (real.includes(`${sep}pnpm${sep}`)) {
-    return { kind: 'global', command: 'pnpm', args: ['add', '-g', 'rnxsim@latest'] }
-  }
-  // the desktop splash installs the CLI into a user-writable prefix under the
-  // sootsim home (`~/.sootsim/cli`) to dodge the EACCES a plain `npm i -g` hits
-  // when npm's global prefix is a system-owned dir. self-update into that same
-  // prefix so upgrade doesn't fall back to the unwritable global prefix.
-  const cliPrefix = path.join(sootsimHomeDir(), 'cli')
-  if (real.startsWith(`${cliPrefix}${sep}`)) {
-    return {
-      kind: 'global',
-      command: 'npm',
-      args: ['i', '-g', '--prefix', cliPrefix, 'rnxsim@latest'],
-    }
-  }
-  const installerPrefix = path.resolve(
-    process.env.SOOTSIM_CLI_PREFIX || path.join(os.homedir(), '.local'),
-  )
-  if (real.startsWith(`${installerPrefix}${sep}`)) {
-    return {
-      kind: 'global',
-      command: 'npm',
-      args: ['i', '-g', '--prefix', installerPrefix, 'rnxsim@latest'],
+export async function upgradeCli(options: UpgradeOptions = {}): Promise<void> {
+  const standalone = options.standalone ?? IS_STANDALONE
+  if (!standalone) {
+    if (isSootsimDevCheckout()) {
+      console.log('  running from the Contrast checkout; pull instead of upgrading')
+      return
     }
+    throw new Error(
+      'this is not the standalone rnx executable; reinstall from https://rnxsim.com/install.sh',
+    )
   }
-  return { kind: 'global', command: 'npm', args: ['i', '-g', 'rnxsim@latest'] }
-}
 
-async function upgradeCli(): Promise<void> {
+  const releaseOrigin = (options.cliReleaseOrigin ?? DEFAULT_CLI_RELEASE_ORIGIN).replace(
+    /\/+$/,
+    '',
+  )
   const current = getCliVersion()
-  const latest = await fetchLatestCliVersion()
-
-  if (!latest) {
-    console.log(`  v${current} — couldn't reach the npm registry, skipped`)
-    return
+  const latest = (await fetchRequired(`${releaseOrigin}/channels/stable`, 8_000))
+    .toString('utf8')
+    .trim()
+  if (!CLI_VERSION_PATTERN.test(latest)) {
+    throw new Error(
+      `rnx update service returned an invalid version: ${latest || '(empty)'}`,
+    )
   }
   if (compareSemver(latest, current) <= 0) {
     console.log(`  v${current} (latest)`)
     return
   }
 
-  const install = detectCliInstall()
-  console.log(`  v${current} → v${latest}`)
-
-  if (install.kind === 'dev') {
-    console.log(`  running from the Contrast dev checkout — pull instead of upgrading`)
-    return
+  const artifact = cliArtifactName()
+  const artifactUrl = `${releaseOrigin}/${latest}/${artifact}`
+  const expectedSha = (await fetchRequired(`${artifactUrl}.sha256`, 8_000))
+    .toString('utf8')
+    .trim()
+  if (!SHA256_PATTERN.test(expectedSha)) {
+    throw new Error('rnx update service returned an invalid executable checksum')
   }
-  if (install.kind === 'npx') {
-    console.log(`  running from the npx cache — get the latest with:`)
-    console.log(`    npx rnxsim@latest`)
-    return
+
+  console.log(`  v${current} → v${latest}`)
+  console.log(`  downloading ${artifact}...`)
+  const executable = await fetchRequired(artifactUrl, 120_000)
+  const actualSha = createHash('sha256').update(executable).digest('hex')
+  if (actualSha !== expectedSha) {
+    throw new Error(
+      `downloaded rnx executable failed verification (expected ${expectedSha}, got ${actualSha})`,
+    )
   }
 
-  const printed = `${install.command} ${install.args.join(' ')}`
-  console.log(`  updating global install (${printed})…`)
-  const ok = await runInherit(install.command, install.args)
-  if (ok) {
-    console.log(`  updated to v${latest}`)
-  } else {
-    console.log(`  update failed — run it yourself:`)
-    console.log(`    ${printed}`)
+  const executablePath = path.resolve(options.cliExecutablePath ?? process.execPath)
+  const tempDir = fs.mkdtempSync(path.join(path.dirname(executablePath), '.rnx-update-'))
+  const candidatePath = path.join(tempDir, path.basename(executablePath))
+  try {
+    fs.writeFileSync(candidatePath, executable, { mode: 0o755 })
+    fs.chmodSync(candidatePath, 0o755)
+    verifyCandidate(candidatePath, latest)
+    fs.renameSync(candidatePath, executablePath)
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true })
   }
+  console.log(`  updated to v${latest}`)
 }
 
-function runInherit(command: string, args: string[]): Promise<boolean> {
-  return new Promise((resolve) => {
-    const child = spawn(command, args, { stdio: 'inherit' })
-    child.on('error', () => resolve(false))
-    child.on('exit', (code) => resolve(code === 0))
-  })
+function cliArtifactName(): string {
+  const platform = process.platform === 'darwin' ? 'darwin' : process.platform
+  if (platform !== 'darwin' && platform !== 'linux') {
+    throw new Error('standalone rnx self-update currently supports macOS and Linux')
+  }
+  if (process.arch !== 'arm64' && process.arch !== 'x64') {
+    throw new Error(`standalone rnx does not support ${process.arch}`)
+  }
+  return `rnx-${platform}-${process.arch}`
 }
 
-async function fetchLatestCliVersion(): Promise<string | null> {
+async function fetchRequired(url: string, timeoutMs: number): Promise<Buffer> {
+  let response: Response
   try {
-    // cap the registry lookup so a hung npm registry can't stall upgrade.
-    const res = await fetch(REGISTRY_LATEST_URL, {
-      headers: { accept: 'application/json' },
-      signal: AbortSignal.timeout(8000),
+    response = await fetch(url, {
+      headers: { accept: 'application/octet-stream' },
+      signal: AbortSignal.timeout(timeoutMs),
     })
-    if (!res.ok) return null
-    const json = (await res.json()) as { version?: unknown }
-    return typeof json.version === 'string' && json.version ? json.version : null
-  } catch {
-    return null
+  } catch (error) {
+    throw new Error(
+      `could not reach the rnx update service: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
+  }
+  if (!response.ok) {
+    throw new Error(
+      `rnx update download failed: ${response.status} ${response.statusText}`,
+    )
+  }
+  return Buffer.from(await response.arrayBuffer())
+}
+
+function verifyCandidate(candidatePath: string, expectedVersion: string): void {
+  const result = spawnSync(candidatePath, ['--version'], {
+    encoding: 'utf8',
+    timeout: 15_000,
+  })
+  const reported = result.stdout.match(/^rnx v([^\s]+)/m)?.[1]
+  if (result.status !== 0 || reported !== expectedVersion) {
+    throw new Error(
+      `downloaded rnx executable reported ${reported ? `v${reported}` : 'no version'}; expected v${expectedVersion}`,
+    )
   }
 }

package/cli/commands/upload.ts

@@ -1,4 +1,4 @@
-// sootsim record upload — capture the currently-loaded bundle + device spec from
+// rnx record upload — capture the currently-loaded bundle + device spec from
 // a running sootsim sim and POST it to the Contrast upload endpoint. returns a
 // /preview/<id> url that anyone can open to load this bundle in a frame.
 //
@@ -108,16 +108,16 @@ function readSnapshotManifest(manifestPath: string): AttachedInteractionSnapshot
   })
 }
 
-const REMOTE_DEFAULT_ORIGIN = process.env.SOOTSIM_UPLOAD_ORIGIN || 'https://contrast.dev'
+const REMOTE_DEFAULT_ORIGIN = process.env.RNX_UPLOAD_ORIGIN || 'https://contrast.dev'
 // the canonical public preview link. Uploads go to the contrast backend, but
 // reviewers/users open SootSim preview pages on sootsim.com.
 const REMOTE_DEFAULT_PUBLIC_PREVIEW_ORIGIN =
-  process.env.SOOTSIM_PREVIEW_ORIGIN || rnxPublicBrand.origin
+  process.env.RNX_PREVIEW_ORIGIN || rnxPublicBrand.origin
 export async function resolveDefaultUploadOrigin(
   explicitOrigin?: string,
 ): Promise<string> {
   if (explicitOrigin) return explicitOrigin
-  if (process.env.SOOTSIM_UPLOAD_ORIGIN) return process.env.SOOTSIM_UPLOAD_ORIGIN
+  if (process.env.RNX_UPLOAD_ORIGIN) return process.env.RNX_UPLOAD_ORIGIN
   return REMOTE_DEFAULT_ORIGIN
 }
 
@@ -155,8 +155,8 @@ export function resolvePublicPreviewOrigin(
   explicitOrigin?: string,
 ): string {
   if (explicitOrigin) return normalizeOrigin(explicitOrigin)
-  if (process.env.SOOTSIM_PREVIEW_ORIGIN) {
-    return normalizeOrigin(process.env.SOOTSIM_PREVIEW_ORIGIN)
+  if (process.env.RNX_PREVIEW_ORIGIN) {
+    return normalizeOrigin(process.env.RNX_PREVIEW_ORIGIN)
   }
   if (isLoopbackOrigin(uploadOrigin)) return normalizeOrigin(uploadOrigin)
   if (isContrastOrigin(uploadOrigin)) {
@@ -174,11 +174,11 @@ usage:
 
 options:
   --origin <url>     upload target (default: ${REMOTE_DEFAULT_ORIGIN})
-                     override with SOOTSIM_UPLOAD_ORIGIN env var
+                     override with RNX_UPLOAD_ORIGIN env var
   --public-origin <url>
                      public /preview link origin (default: ${REMOTE_DEFAULT_PUBLIC_PREVIEW_ORIGIN}
                      for prod uploads, upload origin for localhost/custom origins).
-                     override with SOOTSIM_PREVIEW_ORIGIN env var
+                     override with RNX_PREVIEW_ORIGIN env var
   --events <path>    path to a gzipped events .jsonl.gz file to attach
                      required unless --video is present; previews must
                      have replay or recording playback data
@@ -216,7 +216,7 @@ options:
 examples:
   rnx record upload --events ./my-session.jsonl.gz
   rnx record upload --origin https://contrast.localhost:3000 --events ./my-session.jsonl.gz --open
-  rnx record upload --video /tmp/sootsim-flow.mp4 --video-duration-ms 12000
+  rnx record upload --video /tmp/rnx-flow.mp4 --video-duration-ms 12000
 `)
 }
 
@@ -911,7 +911,7 @@ export async function runUpload(
   // asset-registry and are fetched once at engine boot — before the recorder
   // starts — so neither the manifest re-fetch nor recordedFetches captures
   // them and the /preview replay 404s. backfill them here via the shared
-  // fetcher (same code path as the build's `sootsim app-fonts stage`) so both
+  // fetcher (same code path as the build's `rnx app-fonts stage`) so both
   // pipelines store identical bytes keyed by sha256(url).
   const appFontFiles: PreparedFile[] = []
   const appFontsWire = appFontsWireFromPageHref(snapshot.pageHref) || ''
@@ -1015,11 +1015,11 @@ export async function runUpload(
     bundleMinified: false,
     bundleOrigin,
     runtimeVersion: snapshot.runtimeVersion ?? undefined,
-    // config-only fonts resolved by `sootsim open` and carried on the engine
+    // config-only fonts resolved by `rnx open` and carried on the engine
     // URL. persist them onto the share meta so /preview/<id> re-applies
     // `?appFonts=` and registers the same typefaces.
     appFonts: appFontsWire || undefined,
-    // configured splash (image + bg) resolved by `sootsim open`. persist it so
+    // configured splash (image + bg) resolved by `rnx open`. persist it so
     // /preview/<id> re-applies `?appSplash=` and paints the same splash; the
     // image bytes are staged above so the engine's <img> resolves in preview.
     appSplash: appSplashWire || undefined,

package/cli/commands/version.ts

@@ -1,4 +1,4 @@
-// sootsim version — one overview of both halves you're running.
+// rnx version — one overview of both halves you're running.
 //
 // the `sootsim` CLI (npm package) and the engine runtime (versioned tarball
 // rendered in the browser/electron shell) are versioned independently, which
@@ -10,8 +10,8 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { getCliVersion } from '../../src/cli-version'
 import { runtimeDir } from '../../src/home-paths'
-import { SOOTSIM_CHANGELOG_URL, sootsimRuntime } from '../../src/runtime-delivery'
-import { resolveSootSimAppConfig } from '../app-config'
+import { RNX_CHANGELOG_URL, rnxRuntime } from '../../src/runtime-delivery'
+import { resolveRNXAppConfig } from '../app-config'
 import { getRuntimeSummary } from '../runtime-summary'
 
 export async function runVersion(_args: string[]): Promise<void> {
@@ -20,7 +20,7 @@ export async function runVersion(_args: string[]): Promise<void> {
   console.log(`rnx v${getCliVersion()}${suffix}`)
 
   const runtime = getRuntimeSummary()
-  const channel = sootsimRuntime.resolveChannel()
+  const channel = rnxRuntime.resolveChannel()
   if (runtime.isDevBridge) {
     console.log(runtime.primary)
     if (runtime.installedRuntime) console.log(`${runtime.installedRuntime} · ${channel}`)
@@ -30,7 +30,7 @@ export async function runVersion(_args: string[]): Promise<void> {
     console.log(`${runtime.primary} · ${channel}`)
   }
 
-  const { config } = await resolveSootSimAppConfig()
+  const { config } = await resolveRNXAppConfig()
   if (config?.runtimeVersion) {
     const installed = fs.existsSync(
       path.join(runtimeDir(config.runtimeVersion), 'index.html'),
@@ -43,10 +43,10 @@ export async function runVersion(_args: string[]): Promise<void> {
   }
 
   // best-effort network check; never fail the command on a flaky network.
-  const check = await sootsimRuntime.checkUpToDate({ channel })
+  const check = await rnxRuntime.checkUpToDate({ channel })
   if (check.outdated && check.latest) {
     console.log(`\n  ↑ default runtime v${check.latest} available; run \`rnx upgrade\``)
   }
 
-  console.log(`\n  what's new: ${SOOTSIM_CHANGELOG_URL}`)
+  console.log(`\n  what's new: ${RNX_CHANGELOG_URL}`)
 }

package/cli/commands/what-happened.ts

@@ -1,4 +1,4 @@
-// sootsim what-happened — show recent events from the semantic timeline
+// rnx what-happened — show recent events from the semantic timeline
 //
 // the agent-facing read verb for SootSim.bridges.timeline. by default
 // shows everything since the previous CLI call from the same agent
@@ -6,13 +6,13 @@
 // the events it displayed so the next call shows only new events.
 //
 // usage:
-//   sootsim what-happened                      # since last call
-//   sootsim what-happened --summary            # one-line counts
-//   sootsim what-happened --all                # full ring (no cursor)
-//   sootsim what-happened --since 5s           # absolute window
-//   sootsim what-happened --kinds toast,fetch  # filter
-//   sootsim what-happened --json               # structured
-//   sootsim what-happened --limit 50           # cap (default 200)
+//   rnx what-happened                      # since last call
+//   rnx what-happened --summary            # one-line counts
+//   rnx what-happened --all                # full ring (no cursor)
+//   rnx what-happened --since 5s           # absolute window
+//   rnx what-happened --kinds toast,fetch  # filter
+//   rnx what-happened --json               # structured
+//   rnx what-happened --limit 50           # cap (default 200)
 
 import { getCliIdentityKey } from '../current-sim'
 import { rnxExit } from '../run-rnx'
@@ -157,7 +157,7 @@ export async function runWhatHappened(args: string[], opts: WhatHappenedOptions)
       '--flow',
       // by default we hide high-frequency render/layout/scroll noise so
       // a single tap doesn't get buried under 1000+ rows. enable
-      // `react-commit` with `sootsim timeline start react-commit`, then pass
+      // `react-commit` with `rnx timeline start react-commit`, then pass
       // `--noisy` (or an explicit `--kinds react-commit,…` filter) when you
       // actually want to see them.
       '--noisy',

package/cli/current-sim.ts

@@ -16,7 +16,7 @@ interface CurrentSimState {
 // checked in order — the first one present wins. anything further down is a
 // progressively weaker signal of "same caller across invocations".
 const IDENTITY_ENV_VARS = [
-  'SOOTSIM_CLI_IDENTITY', // explicit override — fastest path, skips all pid lookups
+  'RNX_CLI_IDENTITY', // explicit override — fastest path, skips all pid lookups
   'TM_SESSION', // Team Machine session id; routes prompt-bar followups back to this agent
   'CLAUDE_CODE_SESSION_ID', // claude code, if ever set
   'CODEX_THREAD_ID', // codex / openai agent thread, stable across tool invocations
@@ -54,7 +54,7 @@ export interface CliIdentity {
 // pids drift across invocations:
 //   - claude code's bash tool spawns a fresh shell per call, so the
 //     immediate gppid (the shell's parent) can change
-//   - shell pipelines (`sootsim list | grep`) wrap the command in a
+//   - shell pipelines (`rnx list | grep`) wrap the command in a
 //     subshell, adding an extra ppid layer that shifts gppid down by one
 // the topmost user process (just below init/launchd) is stable across
 // all of these — same agent / login shell / terminal across calls.
@@ -145,7 +145,7 @@ export function getCurrentSimPath() {
     return resolve(process.env[CURRENT_SIM_PATH_ENV])
   }
   const key = getCliIdentityKey()
-  return join(tmpdir(), `sootsim-current-sim-${key}.json`)
+  return join(tmpdir(), `rnx-current-sim-${key}.json`)
 }
 
 export function readCurrentSim(): CurrentSimState | null {

package/cli/desktop-companion.ts

@@ -240,7 +240,7 @@ export interface LaunchCompanionOptions {
   device?: string
   profileId?: string
   ephemeralProfile?: boolean
-  // set by `sootsim open`, whose native window belongs to the launching
+  // set by `rnx open`, whose native window belongs to the launching
   // session. `sootsim desktop` omits it and remains a persistent desktop app.
   ownerPid?: number
 }

package/cli/drivers/playwright.ts

@@ -5,7 +5,7 @@
 // CLI invoked from a directory with no node_modules).
 //
 // the browser runs in a *detached* node subprocess (see PLAYWRIGHT_SIM_HOST)
-// rather than in this CLI process. that is load-bearing: `sootsim open`
+// rather than in this CLI process. that is load-bearing: `rnx open`
 // returns the moment the sim connects, and playwright tears its browser
 // down when the launching process exits. an in-process launch would mean
 // the sim vanished the instant `open` finished. the detached host keeps the
@@ -49,7 +49,7 @@ const callerUserDataDir = process.env.SOOTSIM_PW_USERDATADIR || '';
 const ownerPid = Number(process.env.SOOTSIM_PW_OWNER_PID || 0);
 const ownerPollMs = Number(process.env.SOOTSIM_PW_OWNER_POLL_MS || 5000);
 // optional CDP port — exposes Chrome's remote-debugging endpoint so a
-// bridge-driven sim can also be cpu-profiled (sootsim perf cpu --cdp-port).
+// bridge-driven sim can also be cpu-profiled (rnx perf cpu --cdp-port).
 // playwright keeps its own pipe connection; the port is an additional endpoint.
 const cdpPort = process.env.SOOTSIM_PW_CDP_PORT || '';
 // extra chromium launch args, space-separated. a linux GPU runner injects
@@ -93,7 +93,7 @@ const { join } = require('path');
 //
 // the prior approach was \`pgrep -f ms-playwright/[c]hromium\`. it never matched
 // system Chrome, so the reaper was a no-op in the common case and every
-// aborted/closed \`sootsim open\` leaked a renderer + gpu helper burning 100%+
+// aborted/closed \`rnx open\` leaked a renderer + gpu helper burning 100%+
 // CPU until manually killed (multiple incidents 2026-06).
 //
 // fix: identify our chrome tree by its UNIQUE user-data-dir. every helper a
@@ -106,13 +106,13 @@ const reapEnabled = process.platform !== 'win32';
 let profileDir = callerUserDataDir;
 let ephemeralProfile = false;
 if (!profileDir) {
-  profileDir = mkdtempSync(join(tmpdir(), 'sootsim-playwright-host-'));
+  profileDir = mkdtempSync(join(tmpdir(), 'rnx-playwright-host-'));
   ephemeralProfile = true;
 }
 // browser HTTP caches are acceleration data, not profile identity. give each
 // host a bounded temporary cache so persistent named profiles retain cookies
 // and storage without multiplying a private cache for every profile.
-const diskCacheDir = mkdtempSync(join(tmpdir(), 'sootsim-playwright-cache-'));
+const diskCacheDir = mkdtempSync(join(tmpdir(), 'rnx-playwright-cache-'));
 const chromePidsByProfile = () => {
   if (!reapEnabled) return [];
   try {
@@ -283,7 +283,7 @@ const cleanupProfile = () => {
   // through shutdown(); the exit hook (sync sweep) still reaps the tree.
   process.on('exit', () => { reapChrome(); cleanupProfile(); });
   // owner-liveness watchdog — the load-bearing fix for leaked Chrome hosts.
-  // we are spawned detached + unref'd so \`sootsim open\` returns immediately,
+  // we are spawned detached + unref'd so \`rnx open\` returns immediately,
   // which means nothing in the OS process tree ties Chrome's lifetime to the
   // session that asked for it. once the sim connects, the connect-timeout
   // safety net is cleared, so absent an explicit \`sootsim close\` (or the
@@ -312,7 +312,7 @@ const cleanupProfile = () => {
   // com.google.chrome.for.testing identity cannot intercept open/quit events for
   // the user's com.google.Chrome browser. CI may use chromium_headless_shell;
   // local rendering fails closed because that shell has no GPU and silently
-  // chooses SwiftShader. NOTE: this is NOT enough to make \`sootsim perf cpu\`
+  // chooses SwiftShader. NOTE: this is NOT enough to make \`rnx perf cpu\`
   // work — that profiles the tenant *worker*, and the JS Self-Profiler API
   // cannot be constructed in a dedicated worker (see
   // worker-handlers/cpu-profile.ts). cpu-profile needs a CDP-based profiler
@@ -559,7 +559,7 @@ function resolveUserDataDir(opts: DriverLaunchOptions): string {
     return playwrightProfileUserDataDir(ensureProfile(opts.profileId).id)
   }
   if (opts.ephemeralProfile) {
-    return mkdtempSync(join(tmpdir(), 'sootsim-playwright-profile-'))
+    return mkdtempSync(join(tmpdir(), 'rnx-playwright-profile-'))
   }
   return ''
 }
@@ -596,7 +596,7 @@ async function launch(opts: DriverLaunchOptions): Promise<DriverLaunchResult> {
 
   const errLog = join(
     tmpdir(),
-    `sootsim-playwright-host-${Date.now().toString(36)}-${process.pid}.log`,
+    `rnx-playwright-host-${Date.now().toString(36)}-${process.pid}.log`,
   )
   const connectAckFile = `${errLog}.connected`
   const errFd = openSync(errLog, 'a')

package/cli/drivers/registry.ts

@@ -37,7 +37,7 @@ export function resolveDriver(
   return null
 }
 
-// utility for the `sootsim list --drivers` view. returns a rich row per
+// utility for the `rnx list --drivers` view. returns a rich row per
 // driver with availability + kind + description, suitable for a table.
 export interface DriverListRow {
   id: DriverId

package/cli/drivers/types.ts

@@ -85,7 +85,7 @@ export interface DriverLaunchResult {
 
 export interface Driver {
   id: DriverId
-  // short human name shown in `sootsim list --drivers`.
+  // short human name shown in `rnx list --drivers`.
   name: string
   // one-line description. keep under 80 chars so the list command reads
   // nicely at default terminal width.

package/cli/flow-file.ts

@@ -2,7 +2,7 @@ import * as fs from 'fs'
 import yaml from 'yaml'
 
 export interface FlowFrontmatter {
-  // raw `sootsim open` target: port, dev-server URL, bundle URL, or shell URL
+  // raw `rnx open` target: port, dev-server URL, bundle URL, or shell URL
   app?: string | number
   device?: string
   // pin the sim color scheme for this flow run (screenshot baselines are
@@ -116,7 +116,7 @@ export function validateFlowSteps(steps: any[]): string[] {
 // structural-only validator used by CI runners before uploading the flow
 // artifact. we only check: file exists, parseable yaml, has at least one
 // real interaction step. playback validation is a separate concern handled
-// by `sootsim maestro end --validate` during the authoring session.
+// by `rnx maestro end --validate` during the authoring session.
 export function validateFlowFile(flowPath: string): string[] {
   if (!fs.existsSync(flowPath)) {
     return [`file not found: ${flowPath}`]

package/cli/flow-session.ts

@@ -25,7 +25,7 @@ const FLOW_SESSION_VERSION = 1 as const
 
 export function getFlowSessionPath() {
   return resolve(
-    process.env.SOOTSIM_FLOW_SESSION_PATH || join(tmpdir(), 'sootsim-flow-session.json'),
+    process.env.RNX_FLOW_SESSION_PATH || join(tmpdir(), 'rnx-flow-session.json'),
   )
 }