peachsim 0.1.527 → 0.1.571

package/README.md

@@ -1,4 +1,4 @@
-# rnx
+# Peach
 
 The source owner for the standalone `rnx` executable and the public `rnxsim`
 integration library used to drive a browser-native React Native simulator.
@@ -33,7 +33,7 @@ What this workspace gives you:
 - `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
+- `peachsim/detox` — a drop-in Detox driver + jest preset
 - `rnxsim/sdk` — the inspect/interact verbs as a programmatic API
 - `rnxsim/bridge-contract-input` — parsers turning untrusted JSON into
   bridge-contract arguments
@@ -202,7 +202,7 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 
 | component | role | key files |
 | --- | --- | --- |
-| rnx CLI (bin + dispatcher) | Short-lived terminal entry point. Parses argv, owns the private-by-default one-time choice, lazy-imports one command per run, and routes direct open/runtime/inspection flows. | `cli/bin.ts`, `cli/main.ts`, `cli/privacy.ts`, `cli/parse-args.ts`, `cli/help.ts`, `cli/commands/setup.ts`, `cli/commands/control.ts` |
+| Peach CLI (bin + dispatcher) | Short-lived terminal entry point. Parses argv, owns the private-by-default one-time choice, lazy-imports one command per run, and routes direct open/runtime/inspection flows. | `cli/bin.ts`, `cli/main.ts`, `cli/privacy.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` |
 | bridge-contract input parsers | Turn untrusted JSON into typed bridge-contract arguments, so a transport in front of a sim validates request bodies once instead of writing a second reader. | `src/bridge-contract-input.ts`, `src/bridge-contract.ts` |
@@ -211,11 +211,11 @@ 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 `~/.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` |
+| runtime delivery + Peach home | Versioned engine runtime management. The shared machinery owns manifest fetch, sha256 verification, channels, and auto-update. Peach 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` |
 | standalone CLI delivery | Cached stable-version checks, bounded interactive notices, and verified atomic executable replacement. | `cli/cli-update.ts`, `cli/commands/upgrade.ts`, `cli/commands/version.ts`, `src/cli-version.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; the Vite 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` |
+| `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/peach-compat/src/stub-manifest.ts` |
+| skills registry | Peach 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
 
@@ -245,7 +245,7 @@ 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
+discovery request and manifest target are loopback addresses, Peach keeps the
 loopback host that answered discovery so an IPv6-only listener is not reopened
 through an unreachable IPv4 address. `rnx open` starts a local bridge when no
 daemon is reachable. The background service is strongly recommended for local
@@ -253,7 +253,7 @@ agent work because inspect, interaction, and test commands reuse one ready bridg
 and runtime. Enable it at any time with `rnx daemon install`; it is never required
 in CI. The packaged Desktop app is optional and available through first-run
 onboarding or `rnx desktop install`. A downloaded app starts its own bundled
-daemon on first launch, then offers **Install the rnx command** over the running
+daemon on first launch, then offers **Install the Peach command** over the running
 simulator. That action installs `~/.local/bin/rnx`, updates shell startup, and
 hands the daemon to launchd or systemd without reloading the window. Windows
 keeps the desktop-owned daemon because it has no daemon service yet. Native Electron windows created by `rnx open` belong to that CLI
@@ -264,7 +264,7 @@ window for a selected device (same device list as the `Window >` menu).
 
 ### Privacy
 
-rnx sends no analytics, crash report, command event, app data, project data, or
+Peach sends no analytics, crash report, command event, app data, project data, or
 identity by default. An unsigned-in interactive run may request the runtime it
 is about to execute and the stable standalone CLI version document. The latter
 runs after the command in a detached process at most once every 20 hours and can
@@ -275,7 +275,7 @@ consuming the later human choice. Legacy browser and Electron telemetry senders
 are removed rather than being enabled by this consent.
 
 Opt-in diagnostics are limited to package name/version/unsupported API or error
-class. rnx never sends source, file paths, project names, app content, commands,
+class. Peach never sends source, file paths, project names, app content, commands,
 identity, screenshots, or recordings as diagnostics. Cloud commands such as
 login, upload, billing, issue reporting, generated flows, and screenshot decks
 contact their documented service only when explicitly invoked. The complete
@@ -317,7 +317,7 @@ preset configures it automatically.
 For One's Rolldown native bundler, use the native transform in `vite.config.ts`:
 
 ```ts
-import { jumpToSourceNativePlugin } from 'rnxsim/jump-to-source-native'
+import { jumpToSourceNativePlugin } from 'peachsim/jump-to-source-native'
 
 one({
   native: {
@@ -335,7 +335,7 @@ For One's `nativeTransformModules`, export
 
 ## CLI
 
-The CLI is the primary debugging surface for rnx — use it first for runtime
+The CLI is the primary debugging surface for Peach — use it first for runtime
 inspection, interaction, animation debugging, shell tracing, screenshots, and
 flow capture, not just as a test runner.
 
@@ -381,11 +381,11 @@ rnx do tap email --then type user@example.com --then tap submit
 
 ## Bundler plugins (`rnxsim/vite` and `rnxsim/metro`)
 
-The Vite plugin serves the installed RNX runtime from your existing dev server.
+The Vite plugin serves the installed Peach runtime from your existing dev server.
 
 ```ts
 // vite.config.ts
-import { rnxPlugin } from 'rnxsim/vite'
+import { rnxPlugin } from 'peachsim/vite'
 
 export default {
   plugins: [rnxPlugin({ open: { appName: 'My App' } })],
@@ -395,17 +395,17 @@ export default {
 ```js
 // metro.config.js
 const { getDefaultConfig } = require('expo/metro-config')
-const { withRNX } = require('rnxsim/metro')
+const { withRNX } = require('peachsim/metro')
 
 const config = getDefaultConfig(__dirname)
 
 module.exports = withRNX(config)
 ```
 
-rnx works directly with regular, unannotated Metro production JavaScript bundles
+Peach works directly with regular, unannotated Metro production JavaScript bundles
 out of the box. It identifies modules by matching package graph fingerprints
 against a separately updated, integrity-checked registry. Hermes bytecode is not
-a supported input; pass rnx the JavaScript bundle produced before Hermes
+a supported input; pass Peach the JavaScript bundle produced before Hermes
 compilation.
 
 If an app has unusual dependencies or fingerprint inference fails, you can
@@ -417,7 +417,7 @@ options and enables two integrations:
    bundle. Resolution, transforms, minification, and source maps stay the app's
    own, so the annotated bundle is the exact bundle you ship: the footer assigns
    one unused global on a device, and Hermes drops it during bytecode compilation.
-2. **In-browser dev shell:** serves the rnx simulator shell at `/__soot/` on
+2. **In-browser dev shell:** serves the Peach simulator shell at `/__soot/` on
    the Metro dev server.
 
 The URL helpers request ordinary Metro graphs: `dev=false&minify=true` for
@@ -427,7 +427,7 @@ production and `dev=true&minify=false` for development.
 const {
   toRNXProductionBundleUrl,
   toRNXDevelopmentBundleUrl,
-} = require('rnxsim/metro')
+} = require('peachsim/metro')
 
 const productionUrl = toRNXProductionBundleUrl(
   'http://localhost:8081/index.bundle?platform=ios',
@@ -439,13 +439,13 @@ const developmentUrl = toRNXDevelopmentBundleUrl(
 
 ## 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
+Peach ships a drop-in Detox driver. Existing Detox test files
+(`import { by, element, expect, device } from 'detox'`) run against Peach with
 no code changes — just add one line to your jest config:
 
 ```js
 // jest config
-{ preset: 'rnxsim/detox' }
+{ preset: 'peachsim/detox' }
 ```
 
 Or use the CLI directly:
@@ -459,7 +459,7 @@ 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 is Peach's single YAML test surface. Point it at your existing
 `.maestro/` directory, generate a test, or author one from live actions:
 
 ```sh
@@ -489,7 +489,7 @@ 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
+`rnx screenshot --with-frame` composes the real Peach 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:
@@ -553,13 +553,13 @@ frame for quick art-direction passes.
 
 ## Skills registry
 
-`rnx skill install` installs rnx agent skills in the standard
+`rnx skill install` installs Peach 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/rnx-skills/`:
 
-- `packages/sootsim/skills/contrast/SKILL.md` is generated from that registry
+- `packages/peachsim/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/rnx-skills/` and run:
@@ -568,10 +568,10 @@ When command docs or examples drift, update `packages/rnx-skills/` and run:
 bun run generate:sootsim-docs
 ```
 
-## Runtime delivery (the rnx home and CDN)
+## Runtime delivery (the Peach home and CDN)
 
 The engine never ships inside this package. `runtime-delivery.ts` names
-rnx's CDN origin (default `https://contrast.dev`, overridable in
+Peach'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

package/cli/app-fonts.ts

@@ -6,7 +6,7 @@ import {
   expoFontPathsFromPlugins,
   metroFontSpecsFromPaths,
   type ConfigPluginFontSpec,
-} from 'sootsim-engine/engine/config-plugin-fonts'
+} from 'peach-engine/engine/config-plugin-fonts'
 import { resolveListeningPid, resolveProcessCwd } from '../scripts/dev-server-scanner'
 import { parsePlistSource } from '../src/plist.ts'
 import { resolveAppProject } from './app-project'

package/cli/app-splash.ts

@@ -5,7 +5,7 @@ import path from 'node:path'
 import {
   configPluginSplashFromExpoConfig,
   type ConfigPluginSplashSpec,
-} from 'sootsim-engine/engine/config-plugin-splash'
+} from 'peach-engine/engine/config-plugin-splash'
 import { resolveAppProject } from './app-project'
 
 const require = createRequire(import.meta.url)

package/cli/bin.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // rnx CLI entry point. the full command and verb surface lives in the
-// registry at `packages/rnx-skills/src/cli/meta.ts` — help output,
+// registry at `packages/peach-skills/src/cli/meta.ts` — help output,
 // website docs, and agent skills all read from there. do not duplicate
 // command listings in this file; run `rnx --help` for the canonical
 // surface.

package/cli/bridge-diagnostics.ts

@@ -1,7 +1,7 @@
 import { MERGED_CONSOLE_COUNT_EVAL, inspectErrors } from './commands/inspect/core'
 import { formatLogTimestamp } from './commands/inspect/shared'
 import type { WsBridge } from './ws-bridge'
-import type { SootSimRequestEntry } from '@rnx/globals'
+import type { SootSimRequestEntry } from '@peach/globals'
 
 interface ConsoleSummaryOptions {
   includeTail?: boolean

package/cli/bridge-flow-runner.ts

@@ -1,6 +1,6 @@
 import * as fs from 'fs'
 import * as path from 'path'
-import { devices, type DeviceModel } from 'sootsim-engine/settings'
+import { devices, type DeviceModel } from 'peach-engine/settings'
 import yaml from 'yaml'
 import { REQUIRED_IDENTICAL_FLOW_FRAMES, framesIdentical } from '../detox/proof-frame.cjs'
 import { flowTimeoutScale } from '../src/flow-timeout-scale'
@@ -14,11 +14,11 @@ import { MaestroJsContext, scriptConditionIsTruthy } from './maestro-js'
 import { ensureCliRecordingEntitlement } from './recording-access'
 import type { PerformResult, PerformStep, ResetResult } from '../src/bridge-contract'
 import type { WsBridge } from './ws-bridge'
-import type { SootSimReplayTarget, SootSimTapResult } from '@rnx/globals'
+import type { SootSimReplayTarget, SootSimTapResult } from '@peach/globals'
 import type {
   SootSimExternalAppLifecycleOptions,
   SootSimLaunchArguments,
-} from '@rnx/globals'
+} from '@peach/globals'
 
 const DEFAULT_TIMEOUT = 10000
 const FLOW_TIMEOUT_SCALE = flowTimeoutScale()
@@ -1163,7 +1163,9 @@ export class SootSimBridgeFlowRunner {
 
   async assertVisible(target: string | { id?: string; text?: string }) {
     const opts = typeof target === 'string' ? { text: target } : target
-    for (let attempt = 0; attempt < 15; attempt++) {
+    // maestro auto-retries assertions for up to 7 seconds before failing; a
+    // shorter window fails flows real maestro passes.
+    for (let attempt = 0; attempt < 35; attempt++) {
       if (await this.isElementVisible(opts)) {
         return
       }
@@ -1184,13 +1186,19 @@ export class SootSimBridgeFlowRunner {
 
   async assertNotVisible(target: string | { id?: string; text?: string }) {
     const opts = typeof target === 'string' ? { text: target } : target
-    if (await this.isElementVisible(opts)) {
-      const found = await this.findElement(opts)
-      const where = found
-        ? ` at (${Math.round(found.absolutePosition.x)},${Math.round(found.absolutePosition.y)})`
-        : ''
-      throw new Error(`assertNotVisible: ${JSON.stringify(opts)} IS visible${where}`)
+    // like assertVisible, maestro waits up to 7 seconds for the element to
+    // disappear rather than failing on the first visible sample.
+    for (let attempt = 0; attempt < 35; attempt++) {
+      if (!(await this.isElementVisible(opts))) {
+        return
+      }
+      await sleep(200)
     }
+    const found = await this.findElement(opts)
+    const where = found
+      ? ` at (${Math.round(found.absolutePosition.x)},${Math.round(found.absolutePosition.y)})`
+      : ''
+    throw new Error(`assertNotVisible: ${JSON.stringify(opts)} IS visible${where}`)
   }
 
   // visibility is the engine's call, not a layout-bounds guess. the old test
@@ -2027,7 +2035,33 @@ export class SootSimBridgeFlowRunner {
       // begin its pixels only after launch has mounted and settled, leaving the
       // loading prelude outside the playable video while its trace stays visible.
       await this.waitForVisualSettle()
+      const videoAlreadyStarted = this.recordingStartedAtMs != null
       await this.ensureRecordingStarted()
+      if (!videoAlreadyStarted && this.recordingStartedAtMs != null) {
+        // the preview event recorder has been running since before launch,
+        // so its clock includes the boot prelude the video just skipped.
+        // rebase it to the video's first frame — without this every event
+        // timestamp overshoots the playable video and preview playback can
+        // never align (play stuck disabled). no-op unless the preview
+        // event recorder is running.
+        await this.rebaseEventRecorderToVideoStart(this.recordingStartedAtMs)
+      }
+    }
+  }
+
+  private async rebaseEventRecorderToVideoStart(videoStartedAtMs: number) {
+    try {
+      await this.evaluate(
+        `(() => {
+          const recorder = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder
+          if (!recorder?.isRecording?.()) return 'not-recording'
+          return recorder.markVisibleStart?.(${JSON.stringify(videoStartedAtMs)}) ?? 'no-mark'
+        })()`,
+      )
+    } catch (err) {
+      console.warn(
+        `  warn: event-recorder rebase to video start failed: ${err instanceof Error ? err.message : err}`,
+      )
     }
   }
 
@@ -2258,6 +2292,7 @@ export class SootSimBridgeFlowRunner {
   }
 
   async runStep(rawStepInput: MaestroStep | string, stepIndex: number) {
+    await this.liveStatus?.waitWhilePaused()
     // maestro allows several commands in BARE-STRING form (`- back`,
     // `- hideKeyboard`, `- waitForAnimationToEnd`, `- scrollUp`, …). yaml parses
     // those to a plain string, so normalize to the `{ verb: true }` object form
@@ -2384,7 +2419,14 @@ export class SootSimBridgeFlowRunner {
         step.waitFor
       )
       if (this.stepDelay > 0 && !isAssertion) {
-        await sleep(this.stepDelay)
+        const chunkMs = 50
+        let elapsed = 0
+        while (elapsed < this.stepDelay) {
+          await this.liveStatus?.waitWhilePaused()
+          const toSleep = Math.min(chunkMs, this.stepDelay - elapsed)
+          await sleep(toSleep)
+          elapsed += toSleep
+        }
       }
       this.recordFlowTraceStep({
         stepIndex,
@@ -2621,7 +2663,12 @@ export class SootSimBridgeFlowRunner {
   // runFlowPlayback; absent for programmatic callers.
   liveStatus: FlowLiveStatusReporter | null = null
 
-  async runFlow(steps: MaestroStep[]) {
+  resetFlowState() {
+    this.flowTraceSteps = []
+    this.lastFailedStep = null
+  }
+
+  extractFlowBody(steps: MaestroStep[]) {
     // maestro `onFlowStart` / `onFlowComplete` lifecycle hooks: if any step
     // in the array is a sole-key entry whose key is one of these names and
     // whose value is a list of sub-steps, pull them out and run them as
@@ -2649,7 +2696,11 @@ export class SootSimBridgeFlowRunner {
       }
       body.push(step)
     }
+    return { onStart, onComplete, body }
+  }
 
+  async planFlow(steps: MaestroStep[], options: { dryRun?: boolean } = {}) {
+    const { body } = this.extractFlowBody(steps)
     if (this.liveStatus) {
       await this.liveStatus.plan(
         body.map((rawStep, index) => {
@@ -2660,8 +2711,17 @@ export class SootSimBridgeFlowRunner {
           const name = Object.keys(step).find((k) => k !== 'when') ?? Object.keys(step)[0]
           return { index, name, target: this.flowStepTargetLabel(step, name) }
         }),
+        options,
       )
     }
+  }
+
+  async runFlow(steps: MaestroStep[], options: { skipPlan?: boolean } = {}) {
+    const { onStart, onComplete, body } = this.extractFlowBody(steps)
+
+    if (!options.skipPlan && this.liveStatus) {
+      await this.planFlow(steps)
+    }
 
     if (onStart.length > 0) {
       console.log(`[flow] onFlowStart (${onStart.length} steps)`)