rnxsim 0.0.0 → 0.1.312

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Tamagui LLC and sootsim contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,512 @@
+# rnx
+
+The public, publishable face of rnx: a CLI, two pairs of bundler plugins, a
+Detox/Maestro test surface, and a skills registry for driving a browser-native
+React Native simulator.
+
+## Overview
+
+`rnxsim` is everything you install to *talk to* an rnx instance — it
+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`.
+
+What this package gives you:
+
+- the `rnxsim` CLI — the primary debugging and automation surface (inspect the
+  UI tree, tap elements, capture flows, screenshot, record, run agents)
+- `rnxsim/vite` and `rnxsim/metro` — bundler plugins that serve the installed
+  engine runtime from your own dev server
+- `rnxsim/jump-to-source-babel` — an optional Babel plugin that annotates JSX
+  with source locations so inspect mode can open the selected element in your
+  editor
+- `rnxsim/detox` — a drop-in Detox driver + jest preset
+- `rnxsim/sdk` — the inspect/interact verbs as a programmatic API
+- `rnxsim/skills` — a registry of Contrast-flavored automation skills
+
+Platform status: iOS is the parity baseline. Android is bootstrapped and usable
+for focused conformance slices (bundle/runtime identity, device profiles, shell
+chrome, gesture + three-button nav, system UI/window metrics with cutout-safe
+insets) but is not full parity until the Android launch gates in the Contrast
+repo plan pass.
+
+## What's in this package (and what's not)
+
+| in `rnxsim` | in `sootsim-engine` (private, not published) |
+| --- | --- |
+| CLI, bridge client, drivers | CanvasKit renderer, Yoga layout |
+| bridge daemon host (`SootSimBridgeHost`) | iOS/Android shell chrome, home grid, app switcher |
+| vite/metro plugins, RN resolver, native stubs | Electron shell, wasm |
+| Detox/Maestro runners, screenshots, skills | the actual pixels |
+
+The engine is delivered at runtime, never bundled into this package. A
+committed-but-unbuilt engine fix has no effect on a running sim until the
+runtime tarball is rebuilt and re-fetched.
+
+## Architecture
+
+The architecture is a **three-tier relay**: a short-lived CLI process, a single
+persistent bridge daemon, and the sim itself — a browser/Electron *page* that
+internally splits into shell, compositor, and tenant workers.
+
+```mermaid
+graph TD
+  subgraph cli["rnxsim CLI process (short-lived, cli/)"]
+    BIN["bin.ts (dispatcher + telemetry)"]
+    SETUP["commands/setup.ts (guided daemon setup)"]
+    RUNTIMECMD["commands/runtime.ts (runtime install/use)"]
+    INSPECT["commands/inspect/* (describe/find/do/get/wait)"]
+    FLOW["bridge-flow-runner.ts (Maestro YAML)"]
+    DETOXCMD["commands/detox.ts + detox/ driver"]
+    SHOTS["commands/screenshot + record"]
+    AGENTCMD["commands/agent.ts"]
+    WSB["ws-bridge.ts (WsBridge client)"]
+    DRIVERS["drivers/* (chromium/electron/playwright/system)"]
+  end
+  subgraph daemon["bridge daemon process (persistent :7668)"]
+    HOST["SootSimBridgeHost (host/bridge-host.ts, HTTP+WS)"]
+    AGENTHOST["AgentHost (host/agent-host.ts, FIFO fan-out)"]
+    AGENTSESS["agent-sessions.ts + attached-projects.ts"]
+    SCAN["/__server-scan (dev-server-scanner.ts)"]
+    PROXY["fetch-proxy-handler + websocket-proxy"]
+    RTHTTP["runtime HTTP + self-update (runtime-delivery.ts)"]
+  end
+  subgraph sim["sim page (browser / Electron, launched by a driver)"]
+    SHELLW["shell worker (iOS chrome, home grid, app switcher)"]
+    COMPOSITORW["compositor worker (app canvases + independent rAF)"]
+    TENANTW["tenant worker (guest RN app tree)"]
+  end
+  subgraph build["build-time plugins (src/)"]
+    VITEONE["rnxsim/vite = vite-plugin-one.ts (serve runtime at /__soot/)"]
+    VITERN["sootsim() = vite-plugin.ts (RN resolver + native stubs)"]
+    METRO["rnxsim/metro = metro-plugin.ts"]
+    COMPAT["@sootsim/compat stub-manifest (native seams)"]
+    ENGINESHIM["sootsim-engine react-native shim"]
+  end
+  SKILLS["rnxsim/skills registry.ts (builtin skills)"]
+  subgraph fs["~/.sootsim (home-paths.ts)"]
+    RTDIR["runtimes/<version>/ (engine assets)"]
+    LOCK["daemon.json lockfile"]
+    CFG["config.json"]
+  end
+  CDN["contrast.dev CDN (runtimes/manifest.json + tarballs)"]
+  BIN --> SETUP
+  BIN --> RUNTIMECMD
+  BIN --> INSPECT
+  BIN --> FLOW
+  BIN --> DETOXCMD
+  BIN --> SHOTS
+  BIN --> AGENTCMD
+  SETUP --> LOCK
+  SETUP -->|"register launchd/systemd"| HOST
+  RUNTIMECMD --> RTDIR
+  RUNTIMECMD -->|"fetch runtime"| CDN
+  INSPECT --> WSB
+  FLOW --> WSB
+  SHOTS --> WSB
+  AGENTCMD --> WSB
+  DETOXCMD --> DRIVERS
+  DETOXCMD --> WSB
+  WSB -->|"JSON WS cmds"| HOST
+  HOST -->|"forward to registered sim"| SHELLW
+  SHELLW -->|"replies + pushes"| HOST
+  HOST -->|"relayed results"| WSB
+  HOST --> AGENTHOST
+  AGENTHOST --> AGENTSESS
+  AGENTCMD --> AGENTHOST
+  HOST --> SCAN
+  HOST --> PROXY
+  HOST --> RTHTTP
+  RTHTTP --> RTDIR
+  RTHTTP -->|"manifest + tarball"| CDN
+  DRIVERS -->|"open sim page URL"| SHELLW
+  SHELLW -->|"NativeUIRequest"| TENANTW
+  VITEONE -->|"serve /__soot/ from"| RTDIR
+  METRO -->|"serve /__soot/ from"| RTDIR
+  VITEONE -.->|"launch electron app"| SHELLW
+  VITERN -->|"alias react-native"| ENGINESHIM
+  VITERN -->|"alias native pkgs"| COMPAT
+  VITERN -->|"dev server hosts"| HOST
+  SKILLS --> INSPECT
+```
+
+**The CLI process** (`cli/bin.ts`) parses argv, emits invocation telemetry, and
+lazy-imports exactly one command module per run. Bare `rnxsim` and
+`rnxsim setup` own guided one-time machine work: ask which package manager you
+use for app commands, explain repo-pinned Node versions, recommend a global
+`rnxsim` install, and install the faster background daemon when it is
+missing. `rnxsim open`
+ensures the engine runtime exists and starts a local foreground bridge when no
+daemon is reachable, then opens a `WsBridge` (`cli/ws-bridge.ts`) on **port
+7668** and sends JSON commands. Inspection/interaction verbs live in
+`cli/commands/inspect/*` and are re-exported as the programmatic `rnxsim/sdk`;
+the Maestro runner is `cli/bridge-flow-runner.ts`; the Detox compat driver
+is in `detox/`. Test and screenshot paths additionally use `cli/drivers/*`.
+Browser sims launch in an isolated Playwright Chrome for Testing profile;
+Electron is the native desktop surface.
+
+**The daemon is one process** — `SootSimBridgeHost` (`src/host/bridge-host.ts`).
+`rnxsim serve` runs it in the foreground; the background daemon is the *same
+process* wrapped with autostart and the `~/.sootsim/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
+`/__server-scan` to discover local metro/expo/vxrn/one dev servers, and proxies
+guest-app fetch/WebSocket traffic so the cross-origin tenant worker can reach
+localhost. The `AgentHost` extension owns one FIFO reader per agent session and
+fans agent events out to every subscriber.
+
+**The sim** is a browser/Electron *page* launched by a CLI driver. Inside that
+page run three workers: the **shell worker** owns device and native state, the
+**compositor worker** paints every visible CanvasKit surface, and the **tenant
+worker** runs the guest RN tree and sends native-UI requests to the shell. The
+bridge always addresses the **shell worker**, never an undifferentiated sim.
+
+**Two distinct plugin families** round it out, and they must not be conflated:
+
+- The published **`rnxsim/vite`** (`src/vite-plugin-one.ts`, `sootsimPlugin`)
+  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 (the vite plugin
+  can also launch the Electron app).
+- 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
+  transforms, and is the one that instantiates `SootSimBridgeHost` inside its
+  own dev server. It is used to build the engine/shell and to load external RN
+  apps — it is **not** the published `rnxsim/vite` export.
+
+## Key components
+
+| component | role | key files |
+| --- | --- | --- |
+| rnxsim CLI (bin + dispatcher) | Short-lived terminal entry point. Parses argv, emits telemetry, lazy-imports one command per run, and routes guided setup/open/runtime/inspection flows without a hidden bootstrap path. | `cli/bin.ts`, `cli/parse-args.ts`, `cli/help.ts`, `cli/commands/setup.ts`, `cli/commands/control.ts` |
+| WsBridge client | Client side of the CLI→daemon link. Resolves the daemon port from the lockfile, opens a WS to `:7668`, sends JSON commands and awaits `{id,result}`/`{id,error}`. Used by every interactive command. | `cli/ws-bridge.ts`, `src/bridge-constants.ts`, `cli/current-sim.ts` |
+| inspect / SDK command surface | Runtime inspection + interaction verbs (describe, find, do tap, get errors, wait, layout, settle). Re-exported as `rnxsim/sdk` so programmatic callers drive a sim the same way the CLI does. | `cli/commands/inspect/core.ts`, `cli/commands/inspect/actions.ts`, `cli/commands/inspect.ts`, `src/sdk.ts` |
+| Maestro / Detox runners | Drop-in test compatibility. `bridge-flow-runner.ts` runs Maestro YAML and recorded flows over the bridge; `detox/` provides a `by`/`element`/`expect`/`device` driver + jest preset so existing Detox suites run unchanged. | `cli/bridge-flow-runner.ts`, `cli/commands/maestro.ts`, `cli/commands/detox.ts`, `detox/index.ts`, `detox/jest-preset.cjs` |
+| sim drivers | Launch or attach the actual sim page. Playwright owns isolated browser profiles; Electron owns the native desktop surface. The current sim is reused unless `--new`, `--profile`, or `--ephemeral` requests a separate one. | `cli/drivers/index.ts`, `cli/drivers/registry.ts`, `cli/drivers/electron.ts`, `cli/drivers/playwright.ts` |
+| SootSimBridgeHost (serve/daemon) | The bridge process (`rnxsim 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; the vite plugin can also launch the Electron app. | `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 `rnxsim skill`. | `skills/*.md`, `src/skills/registry.ts`, `src/skills/types.ts` |
+
+## Getting started
+
+```sh
+curl -fsSL https://rnxsim.com/install.sh | sh
+rnxsim setup           # guided one-time machine setup
+rnxsim open 8081       # load a running metro/expo dev server
+rnxsim open /settings  # dispatch a React Native deep link into that app
+```
+
+The first `sootsim open` launches an isolated Chrome for Testing sim. The CLI
+resolves Playwright from the app or CLI install, asks that exact package for
+its required browser executable, and runs that package's installer once when
+the executable is absent. It never substitutes another revision found in the
+shared Playwright cache. Later opens reuse that sim and reload it at the
+requested target. Use `sootsim 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.
+
+The public shell script is the recommended, inspectable bootstrap path;
+`rnxsim` is the normal path afterward. Manual installs can use `npm install
+--global rnxsim`, `bun add --global rnxsim`, or `pnpm add --global rnxsim`,
+followed by `rnxsim setup`. There is no per-app install:
+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. `rnxsim open` starts a local bridge when no daemon is reachable; the
+guided setup installs the faster background daemon so later CLI commands reuse
+one server. A desktop GUI (Electron) is optional on top, via `rnxsim desktop
+install`. Native Electron windows created by `rnxsim open` belong to that CLI
+session and close when the session exits; `rnxsim desktop` keeps the persistent
+desktop-app lifecycle. In Electron, `File > New Window`
+duplicates the focused simulator, while `File > New Simulator >` opens a new
+window for a selected device (same device list as the `Window >` menu).
+
+To uninstall the machine daemon and cached runtimes, run
+`rnxsim daemon uninstall`. It stops current and legacy launchd / systemd
+services, removes daemon logs, and removes `~/.sootsim/` (runtimes, profiles,
+recordings, and lockfiles). It does not remove the optional
+`/Applications/sootsim.app` desktop bundle or macOS preference plist. To inspect
+existing disk usage before uninstalling, run `rnxsim cleanup`; add `--apply`
+only after reviewing the preview.
+
+## Jump to source in inspect mode
+
+Inspect mode can open a selected React Native element in your editor when the
+bundle includes source metadata. Add the optional Babel plugin to your app's
+Metro/Babel config:
+
+```js
+plugins: [
+  [
+    'rnxsim/jump-to-source-babel',
+    {
+      include: [__dirname],
+    },
+  ],
+  'react-native-worklets/plugin',
+]
+```
+
+The plugin adds an `srcloc="/absolute/path/App.tsx:12:3"` prop to JSX elements
+outside `node_modules`, `dist`, and `build`. Keep it before
+`react-native-worklets/plugin` in a custom Babel stack that lists both plugins.
+Apps using `babel-preset-expo` omit the explicit Worklets plugin because the
+preset configures it automatically.
+
+## CLI
+
+The CLI is the primary debugging surface for rnx — use it first for runtime
+inspection, interaction, animation debugging, shell tracing, screenshots, and
+flow capture, not just as a test runner.
+
+```sh
+rnxsim list              # connected tabs
+rnxsim open 8081         # load a running metro/expo dev server
+rnxsim open /settings    # route via React Native Linking
+rnxsim describe          # dump UI tree
+rnxsim get errors 5      # recent runtime failures
+rnxsim compat            # scan native package compatibility
+rnxsim report-issue "…"  # preview an opt-in compatibility report
+rnxsim find --testid cta # inspect one node deeply
+rnxsim debug enable animated,layout
+rnxsim debug trace shell on 240
+rnxsim do tap-text "..." # interact
+rnxsim debug snapshot before
+rnxsim debug snapshot after
+rnxsim debug diff before after
+rnxsim maestro start     # begin a Maestro draft
+rnxsim maestro keep      # persist the last action
+rnxsim maestro end --output .maestro/login.yaml --validate
+rnxsim detox             # run Detox/Jest suites against rnx
+```
+
+See the full command reference via `rnxsim --help` or at
+`src/features/site/docs/rnx/cli/` in the Contrast repo.
+
+Sim-scoped commands use the primary fallback only when one driveable sim is
+connected. With multiple driveable sims, the bridge lists their ids and refuses
+to choose. Run `rnxsim use <id>` to pin later commands, or pass `--sim <id>` to
+target one command.
+
+## Bundler plugins (`rnxsim/vite` and `rnxsim/metro`)
+
+These serve the installed engine runtime from your own dev server. They do
+**not** resolve React Native or stub native modules — that is the internal
+`sootsim()` plugin's job (see Architecture).
+
+```ts
+// vite.config.ts
+import { sootsimPlugin } from 'rnxsim/vite'
+
+export default {
+  plugins: [sootsimPlugin()],
+}
+```
+
+```js
+// metro.config.js
+const { withSootsim } = require('rnxsim/metro')
+
+module.exports = withSootsim({ /* your metro config */ })
+```
+
+## Coming from Detox
+
+rnx ships a drop-in Detox driver. Existing Detox test files
+(`import { by, element, expect, device } from 'detox'`) run against rnx with
+no code changes — just add one line to your jest config:
+
+```js
+// jest config
+{ preset: 'rnxsim/detox/jest-preset' }
+```
+
+Or use the CLI directly:
+
+```sh
+rnxsim detox            # auto-discovers e2e/ tests and launches a shell
+rnxsim detox init       # scaffold a config + sample test
+```
+
+See `../../docs/migrating-from-detox.md` for details.
+
+## Coming from Maestro
+
+Maestro is rnx's single YAML test surface. Point it at your existing
+`.maestro/` directory, generate a test, or author one from live actions:
+
+```sh
+rnxsim maestro                      # discover .maestro/ and run all flows
+rnxsim maestro test .maestro/       # explicit
+rnxsim maestro generate "verify login"
+rnxsim maestro --list-compat        # see the verb support matrix
+```
+
+Most Maestro verbs work out of the box (`tapOn`, `assertVisible`, `inputText`,
+`scrollUntilVisible`, `launchApp`, `when:`, `repeat`, `runFlow`, …). Verbs that
+need real device hardware (GPS, radio, photo library) throw a clear error. See
+`../../docs/migrating-from-maestro.md` for the full compat matrix.
+
+## Screenshots and recordings
+
+For animation-heavy debugging, the useful path is usually:
+
+```sh
+rnxsim debug enable animated
+rnxsim debug trace shell on 240
+rnxsim debug snapshot before
+# reproduce the transition
+rnxsim debug snapshot after
+rnxsim debug diff before after
+rnxsim screenshot --with-frame --output /tmp/sootsim-framed.png
+rnxsim record --duration 5 --output /tmp/sootsim-anim.mp4
+```
+
+`rnxsim screenshot --with-frame` composes the real rnx shell device chrome
+around the raw screen bitmap (reusing the shell bezel/button geometry, excluding
+the Electron top bar, rail gutter, and other window chrome). Flows can request
+the framed export inline without changing Maestro syntax:
+
+`rnxsim wait ready` and the screenshot readiness guard accept inspectable
+native content, a populated node tree, or a live-frame channel whose publish
+count advances across probes. Canvas-only GL, WebGPU, and video surfaces can
+therefore prove that they are painting without weakening the boot-card guard.
+
+```yaml
+- takeScreenshot: hero
+- takeScreenshot:
+    path: marketing/hero
+    withFrame: true
+```
+
+For plan-driven app-store exports, use `rnxsim screenshot appstore`:
+
+```yaml
+app: 8081
+device: iphone-14
+
+capture:
+  flow: .maestro/capture-app-store-screenshots.yaml
+  mode: raw+framed
+
+compose:
+  canvases: [iphone-6-9, iphone-6-1]
+  background: cyan
+  text:
+    preset: bold-top
+  slides:
+    - id: splash-hero
+      screenshot: apple/iphone/en/01-splash.png
+      headline: First punch.
+      subheadline: Every pick in one place.
+```
+
+```sh
+rnxsim screenshot appstore --plan .sootsim/app-store.yaml
+```
+
+The plan runner can reuse a visible sim for capture (`--sim a9`), stop after
+raw/framed intermediates (`--capture-only`), or rerender final marketing
+canvases from an existing raw directory (`--compose-only`). If your flow already
+writes screenshots to explicit project paths, set `from:` + `pathMode: flow` so
+`rnxsim screenshot appstore` respects the flow's own `takeScreenshot` paths
+instead of prepending `--screenshots <rawDir>`:
+
+```yaml
+capture:
+  flow: .maestro/capture-app-store-screenshots.yaml
+  from: ./apps/app-store-screenshots/public/screenshots/apple/iphone/en
+  pathMode: flow
+```
+
+In the browser shell, `Screenshot Mode` turns the live shell into a simple DOM
+composition surface: the rail + mac menu bar disappear, the device shifts down
+with a short transition, and editable title/subtitle fields appear above the
+frame for quick art-direction passes.
+
+## Skills registry
+
+`rnxsim skill install` installs rnx agent skills in the standard
+`<skill-name>/SKILL.md` layout used by Codex and Claude Code. The bundled
+skills cover setup, debugging/perf/accessibility, testing, visual review, and
+the generated `contrast` command index. The published CLI registry and generated
+website docs both come from `packages/sootsim-skills/`:
+
+- `packages/sootsim/skills/contrast/SKILL.md` is generated from that registry
+- `src/features/site/docs/rnx/cli/*` is generated output, not hand-edited
+
+When command docs or examples drift, update `packages/sootsim-skills/` and run:
+
+```sh
+bun run generate:sootsim-docs
+```
+
+## Runtime delivery (the rnx home and CDN)
+
+The engine never ships inside this package. `runtime-delivery.ts` names
+rnx's CDN origin (default `https://contrast.dev`, overridable in
+`config.json`), its `SOOTSIM_*` env overrides, and its hosted paths, then hands
+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`:
+
+```
+~/.sootsim/
+├── runtimes/
+│   ├── <active>/         unpacked engine assets (served at /__soot/)
+│   └── <rollback>/       previous version for rollback
+├── cache/                legacy downloads; empty after cleanup
+├── profiles/             persistent named app storage, without browser caches
+├── electron/userData/    desktop app storage, with bounded browser caches
+├── daemon.json           lockfile: pid, ports, active runtime, heartbeat
+├── automatic-cleanup-v1.json  completed legacy cleanup generation
+└── config.json           user prefs: update channel, cdn origin override
+```
+
+The bridge daemon serves these assets over HTTP and exposes a self-update route;
+`rnxsim upgrade` / `rnxsim runtime` drive explicit version changes from the
+CLI side. Installation retains the active runtime plus one rollback and removes
+the downloaded archive after extraction. Disposable Playwright caches live in a
+bounded per-session temporary directory; Electron's persistent HTTP cache is
+disabled for simulator profiles and globally capped for app chrome. Cookies,
+localStorage, IndexedDB, service workers, recordings, and captured frames are
+user-owned data and are not removed by the default cleanup command.
+
+Per-repo configuration is optional. Every installed-runtime `rnxsim 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`, `rnxsim open` installs that
+version without changing the machine default. Running from a monorepo root
+resolves the only React Native app from package workspaces, then shares that app
+root across config, font, and splash discovery. The fallback scan is bounded and
+prunes dependency, build, native, fixture, and example trees.
+
+The first interactive CLI command after this cleanup generation finishes its
+requested work, then launches the same safe default plan in a detached
+maintenance process. The app and terminal command are usable before the legacy
+filesystem scan begins. The worker prints the reclaimed size to stderr, records
+completion, and does not run the scan again. Open browser profiles and a runtime
+served by a live daemon or development bridge are left untouched. The automatic
+pass retries on a later command after they close. The explicit `rnxsim cleanup --aggressive`
+command remains the only path that removes the rollback runtime or user-created
+recordings.
+
+## Development and building
+
+This package is part of the Contrast monorepo. To build the published CLI bundle:
+
+```sh
+bun run build:cli
+```
+
+The output is `dist-cli/bin.js` — a single esbuild output published as the
+`rnxsim` npm bin. 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/detox/colors.ts

@@ -0,0 +1,54 @@
+// re-export color utilities from kitchen-sink for convenience
+// these are the same implementations used in detox tests
+
+import * as fs from 'fs'
+import { PNG } from 'pngjs'
+
+export type RGB = { r: number; g: number; b: number }
+
+export function getDominantColor(screenshotPath: string): RGB {
+  const data = fs.readFileSync(screenshotPath)
+  const png = PNG.sync.read(data)
+
+  const startX = Math.floor(png.width * 0.25)
+  const endX = Math.floor(png.width * 0.75)
+  const startY = Math.floor(png.height * 0.25)
+  const endY = Math.floor(png.height * 0.75)
+
+  let totalR = 0,
+    totalG = 0,
+    totalB = 0,
+    count = 0
+
+  for (let y = startY; y < endY; y++) {
+    for (let x = startX; x < endX; x++) {
+      const idx = (png.width * y + x) * 4
+      totalR += png.data[idx]
+      totalG += png.data[idx + 1]
+      totalB += png.data[idx + 2]
+      count++
+    }
+  }
+
+  return {
+    r: Math.round(totalR / count),
+    g: Math.round(totalG / count),
+    b: Math.round(totalB / count),
+  }
+}
+
+export function isBlueish(color: RGB): boolean {
+  return color.b > 100 && color.b > color.r && color.b > color.g
+}
+
+export function isReddish(color: RGB): boolean {
+  return color.r > 100 && color.r > color.b && color.r > color.g
+}
+
+export function isGreenish(color: RGB): boolean {
+  return color.g > 100 && color.g > color.r && color.g > color.b
+}
+
+export function formatRGB(color: RGB): string {
+  return `RGB(${color.r}, ${color.g}, ${color.b})`
+}