rnxsim 0.1.354 → 0.1.356

package/cli/bridge-flow-runner.ts

@@ -2,8 +2,11 @@ import * as fs from 'fs'
 import * as path from 'path'
 import { devices, type DeviceModel } from 'sootsim-engine/settings'
 import yaml from 'yaml'
+import {
+  REQUIRED_IDENTICAL_PROOF_FRAMES,
+  framesIdentical,
+} from '../detox/proof-frame.cjs'
 import { composeFramedScreenshot } from '../src/screenshots/frame-compose'
-import { resetGuestAppStateEval } from './app-state-reset'
 import {
   READY_NODE_STABLE_MS,
   READY_PROBE_POLL_MS,
@@ -19,6 +22,10 @@ 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 {
+  SootSimExternalAppLifecycleOptions,
+  SootSimLaunchArguments,
+} from '@sootsim/globals'
 
 const DEFAULT_TIMEOUT = 10000
 // hosted-runner previews reach first-render much slower than local dev: the
@@ -407,6 +414,8 @@ export class SootSimBridgeFlowRunner {
   })
 
   private firstLaunchDone = false
+  private appStopped = false
+  private launchArgumentsActive = false
   private profilingEnabled = false
   private recordingEnabled = false
   private recordingAccessChecked = false
@@ -415,7 +424,6 @@ export class SootSimBridgeFlowRunner {
   private lastRecordingDurationMs: number | null = null
   private lastRecordingFrameStats: unknown = null
   private flowTraceSteps: SootSimFlowTraceStep[] = []
-  private lastVisualSettledAtMs = 0
   private simRouteHint: string | null = null
   // set by runStep when a step throws — lets the outer flow command
   // dump a rich per-step failure bundle (screenshot + describe.json +
@@ -1489,23 +1497,6 @@ export class SootSimBridgeFlowRunner {
           layers?: 'full' | 'tenant' | 'shell'
         },
   ): Promise<string> {
-    // give transitions + last-moment data paint a brief settle window before
-    // freezing the frame. screenshot flows care more about visual completeness
-    // than minimum latency. waitForVisualSettle drains in-flight animations
-    // (it returns immediately if nothing is animating), then we hold for an
-    // additional 250ms paint window for fade-ins / image decodes / etc.
-    // before this change, a 250ms sleep was the *only* settle window — flows
-    // that took a screenshot at the tail of a screen transition would catch
-    // a half-finished frame on slow machines.
-    if (!this.hasFreshVisualSettle()) {
-      try {
-        await this.waitForVisualSettle()
-        await sleep(250)
-      } catch {
-        // settling helper can throw on disconnected sims; fall through so a
-        // stale sim still produces *some* screenshot.
-      }
-    }
     // flow `takeScreenshot: <name>` may be a plain name ("hero") or a full
     // relative path with slashes ("apps/foo/screenshots/en/02-forum") —
     // maestro flows commonly use the latter. mkdir the parent of the
@@ -1531,9 +1522,32 @@ export class SootSimBridgeFlowRunner {
       simId: this.opts.simId,
     }
     if (layers && layers !== 'full') screenshotRequest.layers = layers
-    const dataUrl: string = await this.bridge.send(screenshotRequest)
-    const base64 = dataUrl.replace(/^data:image\/png;base64,/, '')
-    const rawBuffer = Buffer.from(base64, 'base64')
+    let previousBuffer: Buffer | null = null
+    let identicalFrames = 1
+    let rawBuffer: Buffer | null = null
+    for (let attempt = 0; attempt < 12; attempt++) {
+      await this.waitForVisualSettle()
+      const dataUrl: string = await this.bridge.send(screenshotRequest)
+      const current = Buffer.from(
+        dataUrl.replace(/^data:image\/png;base64,/, ''),
+        'base64',
+      )
+      if (framesIdentical(previousBuffer, current)) {
+        identicalFrames++
+        if (identicalFrames >= REQUIRED_IDENTICAL_PROOF_FRAMES) {
+          rawBuffer = current
+          break
+        }
+      } else {
+        identicalFrames = 1
+      }
+      previousBuffer = current
+    }
+    if (!rawBuffer) {
+      throw new Error(
+        `screenshot did not reach ${REQUIRED_IDENTICAL_PROOF_FRAMES} identical idle frames`,
+      )
+    }
     if (spec.withFrame) {
       const model = await this.readCurrentDeviceModel()
       if (!model) {
@@ -1563,13 +1577,7 @@ export class SootSimBridgeFlowRunner {
   }
 
   async captureScreenshot(outputPath: string) {
-    fs.mkdirSync(path.dirname(outputPath), { recursive: true })
-    const dataUrl: string = await this.bridge.send({
-      type: 'screenshot',
-      simId: this.opts.simId,
-    })
-    const base64 = dataUrl.replace(/^data:image\/png;base64,/, '')
-    fs.writeFileSync(outputPath, Buffer.from(base64, 'base64'))
+    await this.takeScreenshot({ path: outputPath })
   }
 
   // writes a per-failure debug bundle: screenshot + structured describe
@@ -1880,7 +1888,9 @@ export class SootSimBridgeFlowRunner {
       stablePolls: 2,
       strict: true,
     })
-    if (result.settled) this.markVisualSettled()
+    if (!result.settled) {
+      throw new Error(`animation did not settle within ${maxMs}ms`)
+    }
   }
 
   async back() {
@@ -1962,12 +1972,17 @@ export class SootSimBridgeFlowRunner {
     await this.refreshSimId()
   }
 
-  private async resetGuestAppData() {
+  private async resetGuestAppData(
+    launchOptions?: Pick<
+      SootSimExternalAppLifecycleOptions,
+      'initialUrl' | 'launchArguments'
+    >,
+  ) {
     const reset: ResetResult = await this.bridge.send(
       {
         type: 'reset',
         simId: this.opts.simId,
-        resetOptions: { strategy: 'data' },
+        resetOptions: { strategy: 'data', ...launchOptions },
       },
       { timeoutMs: 120000 },
     )
@@ -1982,14 +1997,16 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
-  private async softReloadGuestApp(resetStorage: boolean) {
-    const reloaded = await this.evaluate<boolean>(
-      resetGuestAppStateEval(resetStorage),
-      120000,
+  private async reloadGuestAppRuntime(options: SootSimExternalAppLifecycleOptions) {
+    await this.bridge.send(
+      {
+        type: 'call',
+        simId: this.opts.simId,
+        path: 'SootSim.bridges.hotRemount.reloadExternalApp',
+        args: [options],
+      },
+      { timeoutMs: 120000 },
     )
-    if (!reloaded) {
-      throw new Error('guest app soft reload bridge unavailable')
-    }
   }
 
   private async rearmCaptureAfterRuntimeReload() {
@@ -2016,12 +2033,14 @@ export class SootSimBridgeFlowRunner {
 
   async launchApp(opts: any) {
     await this.refreshSimId()
-    if (opts && typeof opts === 'object' && opts.arguments) {
-      // real maestro passes process launch arguments to the native app.
-      // sootsim has no native process — the bundle boots in-page — so
-      // launch arguments have nothing to attach to. say so instead of
-      // silently dropping them.
-      console.log('[flow]   launchApp.arguments ignored (rnx has no native process)')
+    let hasLaunchArguments = false
+    let launchArguments: SootSimLaunchArguments | undefined
+    if (isObjectRecord(opts) && Object.prototype.hasOwnProperty.call(opts, 'arguments')) {
+      if (!isObjectRecord(opts.arguments)) {
+        throw new Error('launchApp.arguments must be a JSON object')
+      }
+      hasLaunchArguments = true
+      launchArguments = opts.arguments
     }
     const wantsClear = !!(opts && typeof opts === 'object' && opts.clearState)
     const wantsResetRuntime = readBooleanKey(opts, 'resetRuntime')
@@ -2031,7 +2050,15 @@ export class SootSimBridgeFlowRunner {
       // Maestro's "launch the app" boundary through the shell. Otherwise the
       // guest app is already booting from the initial sim open, so just wait.
       this.firstLaunchDone = true
-      if (wantsResetRuntime) {
+      if (hasLaunchArguments) {
+        const launched = await this.launchShellAppFromHomeIfNeeded(opts)
+        if (launched) await this.waitForTree(120000)
+        await this.reloadGuestAppRuntime({
+          launchArguments,
+          initialUrl: null,
+        })
+        await this.waitForTree(120000)
+      } else if (wantsResetRuntime) {
         // SootSim benchmark flows need app auth/storage kept warm while the
         // guest React runtime starts fresh inside the timed/recorded boundary.
         // the reload re-runs the app entry inside the mounted app surface, so
@@ -2045,7 +2072,14 @@ export class SootSimBridgeFlowRunner {
         // second readiness wait would only pad the measured reset.
         const launched = await this.launchShellAppFromHomeIfNeeded(opts)
         if (launched) await this.waitForTree(120000)
-        await this.softReloadGuestApp(false)
+        await this.reloadGuestAppRuntime({})
+        await this.waitForTree(120000)
+      } else if (this.appStopped) {
+        await this.launchShellAppFromHomeIfNeeded(opts)
+        await this.reloadGuestAppRuntime({
+          launchArguments: null,
+          initialUrl: null,
+        })
         await this.waitForTree(120000)
       } else {
         await this.launchShellAppFromHomeIfNeeded(opts)
@@ -2054,7 +2088,15 @@ export class SootSimBridgeFlowRunner {
     } else {
       this.firstLaunchDone = true
       if (wantsClear) {
-        await this.resetGuestAppData()
+        await this.resetGuestAppData({
+          launchArguments: hasLaunchArguments ? launchArguments : null,
+          initialUrl: null,
+        })
+      } else if (hasLaunchArguments || this.launchArgumentsActive || this.appStopped) {
+        await this.reloadGuestAppRuntime({
+          launchArguments: hasLaunchArguments ? launchArguments : null,
+          initialUrl: null,
+        })
       } else {
         await this.reloadGuestApp()
       }
@@ -2072,6 +2114,9 @@ export class SootSimBridgeFlowRunner {
       }
     }
 
+    this.appStopped = false
+    this.launchArgumentsActive = hasLaunchArguments
+
     if (this.profilingEnabled) {
       await this.startProfile()
     }
@@ -2082,31 +2127,19 @@ export class SootSimBridgeFlowRunner {
   }
 
   private async waitForVisualSettle() {
-    try {
-      await this.evaluate(`new Promise((resolve) => {
-        requestAnimationFrame(() => {
-          requestAnimationFrame(() => {
-            requestAnimationFrame(() => {
-              setTimeout(resolve, 180)
-            })
-          })
-        })
-      })`)
-      this.markVisualSettled()
-    } catch {
-      await sleep(180)
-      this.markVisualSettled()
+    const result = await waitForSootsimIdle({
+      bridge: this.bridge,
+      simId: this.opts.simId,
+      maxMs: 10_000,
+      pollMs: 32,
+      stablePolls: 3,
+      strict: true,
+    })
+    if (!result.settled) {
+      throw new Error(`visual state did not settle within ${result.elapsed}ms`)
     }
   }
 
-  private markVisualSettled() {
-    this.lastVisualSettledAtMs = Date.now()
-  }
-
-  private hasFreshVisualSettle() {
-    return Date.now() - this.lastVisualSettledAtMs < 750
-  }
-
   private resolveShellLaunchAppId(opts: unknown, state: ShellState | null): string {
     if (typeof opts === 'string' && opts.length > 0) return opts
     if (isObjectRecord(opts)) {
@@ -2188,12 +2221,10 @@ export class SootSimBridgeFlowRunner {
   }
 
   // maestro stopApp: tear down the current app runtime without clearing app
-  // data. sootsim has no separate native process, so a hard page reload is the
-  // nearest equivalent to killing and later re-launching the tenant runtime.
-  // State clearing belongs to clearState / launchApp({ clearState: true }).
+  // data. the next launchApp or openLink creates its replacement worker.
   async stopApp() {
-    await this.reloadGuestApp()
-    await this.rearmCaptureAfterRuntimeReload()
+    await this.reloadGuestAppRuntime({ relaunch: false })
+    this.appStopped = true
   }
 
   // maestro clearState: wipe app-owned storage and relaunch fresh.
@@ -2265,6 +2296,17 @@ export class SootSimBridgeFlowRunner {
   async openLink(target: string | { link: string }) {
     const link = typeof target === 'string' ? target : target.link
     if (!link) throw new Error('openLink: missing link')
+    if (this.appStopped) {
+      await this.reloadGuestAppRuntime({
+        initialUrl: link,
+        launchArguments: null,
+      })
+      await this.waitForTree(120000)
+      this.appStopped = false
+      this.launchArgumentsActive = false
+      this.firstLaunchDone = true
+      return
+    }
     const result = await this.callTest<{ ok: boolean; error?: string }>(
       'openDeepLink',
       link,

package/cli/commands/inspect/settling.ts

@@ -58,16 +58,21 @@ export async function waitForSootsimIdle({
 
       const readSnapshot = async () => {
         let animating = false
+        let layoutDirty = false
         let pendingFetches = 0
         let requestTotal = 0
         let requestInFlight = 0
+        let renderStatsAvailable = false
         try {
           const stats = await window.__sootsimRenderHost?.queryStats?.()
           if (stats) {
+            renderStatsAvailable = true
             animating =
               stats.hasActiveAnims === true ||
               stats.hasActiveNativeAnimations === true ||
               stats.hasPendingAnimationFrames === true
+            layoutDirty =
+              stats.layoutDirty === true && stats.renderRequested === true
             // a freshly-pushed screen showing a skeleton is layout-stable
             // but not actually settled — its data/images are still in
             // flight. treat bounded image-loader fetches as not-idle so
@@ -94,7 +99,7 @@ export async function waitForSootsimIdle({
           }
           walk(root)
         }
-        return { layout: nodes.join(';'), animating, pendingFetches, requestTotal, requestInFlight }
+        return { layout: nodes.join(';'), animating, layoutDirty, pendingFetches, renderStatsAvailable, requestTotal, requestInFlight }
       }
 
       // how long generic background network is allowed to keep us waiting AFTER
@@ -114,7 +119,9 @@ export async function waitForSootsimIdle({
       let visuallyStillSince = 0
       while (Date.now() < deadline) {
         const snapshot = await readSnapshot()
-        const strictOk = !strict || !snapshot.animating
+        const strictOk =
+          !strict ||
+          (snapshot.renderStatsAvailable && !snapshot.animating && !snapshot.layoutDirty)
         // visually settled: no animations, no image content loading, layout
         // unchanged since the last poll.
         const visuallyStill =

package/cli/commands/maestro.ts

@@ -73,7 +73,7 @@ function printCompatMatrix() {
 rnx maestro — compatibility matrix
 
 supported verbs:
-  launchApp, stopApp, clearState, clearKeychain (warn-only),
+  launchApp (including arguments), stopApp, clearState, clearKeychain (warn-only),
   tapOn, tapAtCoords, longPressOn,
   inputText, pressKey, dispatchKey, hideKeyboard, eraseText,
   assertVisible, assertNotVisible, assertTreeContains,
@@ -92,12 +92,17 @@ workspace mode (directory runs):
   config.yaml / config.yml discovery, flows: inclusion globs,
   includeTags / excludeTags against flow frontmatter tags.
 
+launch behavior:
+  launchApp.arguments: a JSON object available before guest app entry through
+    react-native-launch-arguments and NativeModules.SettingsManager.settings.
+  stopApp: keeps the guest stopped until launchApp or openLink starts it.
+  openLink: cold-starts a stopped guest with the initial URL; a running guest
+    receives the URL through React Native Linking.
+
 partial:
   clearKeychain — warn-only, rnx has no keychain surface.
   when.platform — rnx reports iOS for this runner.
-  openLink — dispatched into the app via the Linking emulation
-    (react-navigation deep links work); no OS-level Safari fallback.
-  launchApp.arguments — ignored; rnx has no native process.
+  openLink: app routing works; no OS-level Safari fallback.
   launchApp.resetRuntime — sootsim-only extension for recorded benchmarks:
     keep tenant storage/auth, but soft-reload the guest app inside launchApp.
   takeScreenshot — maestro string form works unchanged; rnx also accepts

package/cli/outbound-endpoints.ts

@@ -125,7 +125,7 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     count: 3,
   },
   'packages/sootsim-engine/src/components/native-ui/LottieHost.tsx :: fetch :: descriptor.value':
-    { category: 'guest_app_network', count: 1 },
+    { category: 'guest_app_network', count: 2 },
   'packages/sootsim-engine/src/demo/demo-share-register.ts :: fetch :: shareUrl': {
     category: 'guest_app_network',
     count: 1,