peachsim 0.1.626 → 0.1.628

package/LICENSE

@@ -3,7 +3,7 @@ Proprietary Software License
 Copyright (c) Tamagui LLC. All rights reserved.
 
 This package (peachsim) is proprietary software of Tamagui LLC, licensed under
-the rnx Software License Agreement: https://peachsim.com/legal/license
+the Peach Software License Agreement: https://peachsim.com/legal/license
 
 In summary (the agreement governs): personal, non-commercial use is free;
 commercial use requires an active Pro subscription after a single 30-day

package/README.md

@@ -8,7 +8,8 @@ integration library used to drive a browser-native React Native simulator.
 The CLI and library are separate public artifacts. The recommended installer
 downloads one Bun-compiled `peach` executable that needs no Node.js, npm, or Bun
 installation. The `peachsim` npm package contains bundler plugins, testing
-drivers, and library exports, with no command-line binary.
+drivers, and library exports; its only command, `npx peachsim`, runs that same
+installer from the copy of `install.sh` it ships.
 
 The executable updates itself with `peach upgrade`. Successful interactive human
 commands refresh a cached stable CLI version in a detached process at most once
@@ -220,7 +221,7 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 ## Getting started
 
 ```sh
-curl -fsSL https://peachsim.com/install.sh | sh
+curl -fsSL https://peachsim.com/install.sh | sh   # or: npx peachsim
 peach                 # open ConnectRN and choose a running app in the simulator
 peach open /settings  # dispatch a React Native deep link into that app
 ```

package/cli/bin.ts

@@ -10,7 +10,7 @@
 // whole process, so the CLI itself lives in `./main` and is imported only once
 // none of them has claimed the run.
 
-import { RNX_INTERNAL_COMMAND } from './internal-child'
+import { RNX_FORKED_SCRIPT_ENV, RNX_INTERNAL_COMMAND } from './internal-child'
 
 if (process.argv[2] === '__shell-init') {
   const { renderRnxShellInit } = await import('./shell-init')
@@ -51,7 +51,11 @@ if (process.argv[2] === '__cloud-confirm') {
 // are still working when their handler returns, and the process ends when that
 // work does. so this is the branch that must skip the CLI rather than the CLI
 // that must skip it.
-if (process.argv[2] === RNX_INTERNAL_COMMAND) {
+const forkedScript = process.argv[2]
+if (process.env[RNX_FORKED_SCRIPT_ENV] === '1' && forkedScript?.endsWith('.js')) {
+  const { runScript } = await import('./internal-child')
+  runScript(forkedScript, process.argv.slice(3))
+} else if (process.argv[2] === RNX_INTERNAL_COMMAND) {
   const { runInternalChild } = await import('./internal-child')
   await runInternalChild(process.argv.slice(3))
 } else {

package/cli/bridge-flow-runner.ts

@@ -30,8 +30,6 @@ const DEFAULT_TIMEOUT = 10000
 const ASSERTION_LOOKUP_MS = 17_000
 const FLOW_TIMEOUT_SCALE = flowTimeoutScale()
 const scaledTimeout = (ms: number) => Math.round(ms * FLOW_TIMEOUT_SCALE)
-const SCREEN_W = 393
-const SCREEN_H = 852
 type FlowScreenshotPathMode = 'dir' | 'flow'
 type ReplayTapTarget = SootSimReplayTarget
 
@@ -472,18 +470,16 @@ export function normalizeFlowScreenshotSpec(
 
 function parsePoint(
   value: string,
-  bounds?: { x: number; y: number; width: number; height: number },
+  bounds: { x: number; y: number; width: number; height: number },
 ) {
   const [rawX, rawY] = value.split(',').map((part) => part.trim())
   const parseCoord = (coord: string, max: number) =>
     coord.endsWith('%')
       ? (Number.parseFloat(coord) / 100) * max
       : Number.parseFloat(coord)
-  const originX = bounds?.x ?? 0
-  const originY = bounds?.y ?? 0
   return {
-    x: originX + parseCoord(rawX, bounds?.width ?? SCREEN_W),
-    y: originY + parseCoord(rawY, bounds?.height ?? SCREEN_H),
+    x: bounds.x + parseCoord(rawX, bounds.width),
+    y: bounds.y + parseCoord(rawY, bounds.height),
   }
 }
 
@@ -624,6 +620,28 @@ export class SootSimBridgeFlowRunner {
     }) as Promise<T>
   }
 
+  private async screenBounds() {
+    const snapshot = await this.callTest<Record<string, unknown> | null>(
+      'getSurfaceMetricsSnapshot',
+    )
+    const window = snapshot?.window
+    if (
+      !window ||
+      typeof window !== 'object' ||
+      !('width' in window) ||
+      !('height' in window) ||
+      typeof window.width !== 'number' ||
+      typeof window.height !== 'number' ||
+      !Number.isFinite(window.width) ||
+      !Number.isFinite(window.height) ||
+      window.width <= 0 ||
+      window.height <= 0
+    ) {
+      throw new Error('live screen dimensions are unavailable')
+    }
+    return { x: 0, y: 0, width: window.width, height: window.height }
+  }
+
   // ordered input batch executed inside the page in one round-trip; the
   // engine emits agent-cursor actions for every step natively.
   private async perform(steps: PerformStep[]): Promise<PerformResult> {
@@ -939,6 +957,7 @@ export class SootSimBridgeFlowRunner {
   // (match scoped to a container). a nested selector resolves the same way,
   // and a relative filter holds when ANY match of its anchor satisfies it.
   private async findElementScoped(opts: FlowTargetSelector) {
+    const screen = await this.screenBounds()
     const needsEveryNode =
       !opts.id ||
       opts.childOf != null ||
@@ -1045,7 +1064,7 @@ export class SootSimBridgeFlowRunner {
         // paints nothing, and maestro's hierarchy never holds it.
         const onScreen = candidates.filter((n) => {
           const cy = n.absolutePosition.y + n.layout.height / 2
-          return cy > 0 && cy < ${SCREEN_H}
+          return cy > 0 && cy < ${screen.height}
         })
         if (candidates.some(painted)) candidates = candidates.filter(painted)
         else if (onScreen.length > 0) candidates = onScreen
@@ -1263,7 +1282,7 @@ export class SootSimBridgeFlowRunner {
       !opts.childOf
     ) {
       return {
-        ...parsePoint(opts.point),
+        ...parsePoint(opts.point, await this.screenBounds()),
         element: null,
         target: undefined,
       }
@@ -1903,34 +1922,21 @@ export class SootSimBridgeFlowRunner {
     return outputDir
   }
 
-  async swipe(direction: string = 'UP', duration: number = 300) {
-    const centerX = SCREEN_W / 2
-    const centerY = SCREEN_H / 2
-    const distance = 200
-    let fromX = centerX
-    let fromY = centerY
-    let toX = centerX
-    let toY = centerY
-
-    switch (direction.toUpperCase()) {
-      case 'UP':
-        fromY += distance
-        toY -= distance
-        break
-      case 'DOWN':
-        fromY -= distance
-        toY += distance
-        break
-      case 'LEFT':
-        fromX += distance
-        toX -= distance
-        break
-      case 'RIGHT':
-        fromX -= distance
-        toX += distance
-        break
-    }
-
+  // maestro's ios driver: a directional swipe spans the screen, from 90% to
+  // 10% for UP, 20% to 90% for DOWN, and 10% to 90% across for LEFT/RIGHT,
+  // over the command's 400ms default.
+  async swipe(direction: string = 'UP', duration: number = 400) {
+    const screen = await this.screenBounds()
+    const midX = screen.width / 2
+    const midY = screen.height / 2
+    const [fromX, fromY, toX, toY] =
+      direction.toUpperCase() === 'DOWN'
+        ? [midX, screen.height * 0.2, midX, screen.height * 0.9]
+        : direction.toUpperCase() === 'LEFT'
+          ? [screen.width * 0.9, midY, screen.width * 0.1, midY]
+          : direction.toUpperCase() === 'RIGHT'
+            ? [screen.width * 0.1, midY, screen.width * 0.9, midY]
+            : [midX, screen.height * 0.9, midX, screen.height * 0.1]
     const steps = Math.max(10, Math.round(duration / 16))
     await this.drag(fromX, fromY, toX, toY, steps, 16)
   }
@@ -1960,39 +1966,34 @@ export class SootSimBridgeFlowRunner {
     await this.settleAfterInput()
   }
 
-  async swipeCoords(start: string, end: string, duration = 300) {
-    const from = parsePoint(start)
-    const to = parsePoint(end)
+  async swipeCoords(start: string, end: string, duration = 400) {
+    const screen = await this.screenBounds()
+    const from = parsePoint(start, screen)
+    const to = parsePoint(end, screen)
     const steps = Math.max(10, Math.round(duration / 16))
     await this.drag(from.x, from.y, to.x, to.y, steps, 16)
   }
 
+  // maestro's ios driver swipes from the element's center to the 10% or 90%
+  // edge in the swipe's direction.
   async swipeFrom(
     from: { id?: string; text?: string },
     direction: string = 'UP',
-    duration = 300,
+    duration = 400,
   ) {
     const element = await this.findElement(from)
     if (!element) throw new Error(`swipeFrom: element not found: ${JSON.stringify(from)}`)
     const startX = element.absolutePosition.x + element.layout.width / 2
     const startY = element.absolutePosition.y + element.layout.height / 2
-    const distance = 180
-    let endX = startX
-    let endY = startY
-    switch (direction.toUpperCase()) {
-      case 'UP':
-        endY -= distance
-        break
-      case 'DOWN':
-        endY += distance
-        break
-      case 'LEFT':
-        endX -= distance
-        break
-      case 'RIGHT':
-        endX += distance
-        break
-    }
+    const screen = await this.screenBounds()
+    const [endX, endY] =
+      direction.toUpperCase() === 'DOWN'
+        ? [startX, screen.height * 0.9]
+        : direction.toUpperCase() === 'LEFT'
+          ? [screen.width * 0.1, startY]
+          : direction.toUpperCase() === 'RIGHT'
+            ? [screen.width * 0.9, startY]
+            : [startX, screen.height * 0.1]
     const steps = Math.max(10, Math.round(duration / 16))
     await this.drag(startX, startY, endX, endY, steps, 16)
   }
@@ -2103,24 +2104,24 @@ export class SootSimBridgeFlowRunner {
     )
     const deadline = Date.now() + (opts.timeout || 20000)
     const direction = opts.direction?.toUpperCase() || 'DOWN'
-    const centerX = SCREEN_W / 2
-    const centerY = SCREEN_H / 2
-    const swipeEnd =
-      direction === 'UP'
-        ? { x: centerX, y: SCREEN_H * 0.9 }
-        : direction === 'LEFT'
-          ? { x: SCREEN_W * 0.9, y: centerY }
-          : direction === 'RIGHT'
-            ? { x: SCREEN_W * 0.1, y: centerY }
-            : { x: centerX, y: SCREEN_H * 0.1 }
-
     while (Date.now() < deadline) {
+      const screen = await this.screenBounds()
+      const centerX = screen.width / 2
+      const centerY = screen.height / 2
+      const swipeEnd =
+        direction === 'UP'
+          ? { x: centerX, y: screen.height * 0.9 }
+          : direction === 'LEFT'
+            ? { x: screen.width * 0.9, y: centerY }
+            : direction === 'RIGHT'
+              ? { x: screen.width * 0.1, y: centerY }
+              : { x: centerX, y: screen.height * 0.1 }
       const element = await this.findElement(target)
       if (element) {
         const { x, y } = element.absolutePosition
         const { width, height } = element.layout
-        const shownX = Math.max(0, Math.min(x + width, SCREEN_W) - Math.max(x, 0))
-        const shownY = Math.max(0, Math.min(y + height, SCREEN_H) - Math.max(y, 0))
+        const shownX = Math.max(0, Math.min(x + width, screen.width) - Math.max(x, 0))
+        const shownY = Math.max(0, Math.min(y + height, screen.height) - Math.max(y, 0))
         const share = width * height > 0 ? (shownX * shownY) / (width * height) : 0
         if (share >= required) {
           if (opts.centerElement) {
@@ -2839,7 +2840,13 @@ export class SootSimBridgeFlowRunner {
         await this.swipe(step.swipe.direction, step.swipe.duration)
       }
     } else if (step.scroll) {
-      await this.swipe(step.scroll.direction === 'DOWN' ? 'UP' : 'DOWN')
+      // maestro's scrollVertical drags 50% to 10% of the screen over 333ms;
+      // scrollUp mirrors it
+      const screen = await this.screenBounds()
+      const midX = screen.width / 2
+      const toY =
+        step.scroll.direction === 'UP' ? screen.height * 0.9 : screen.height * 0.1
+      await this.drag(midX, screen.height / 2, midX, toY, Math.round(333 / 16), 16)
     } else if (step.scrollTo) {
       const target =
         typeof step.scrollTo.nodeId === 'number'

package/cli/commands/box/bundle-plane.ts

@@ -8,15 +8,20 @@
 // the bundle is split here rather than by the caller, so the one place that
 // decides where the parts go is the one place that decides how big they are.
 
-import { PREBUILT_BUNDLE_PART_BYTES, prebuiltBundlePartPath } from '@peach/box/template'
+import {
+  PREBUILT_BUNDLE_DEVICE_PATH,
+  PREBUILT_BUNDLE_PART_BYTES,
+  prebuiltBundlePartPath,
+} from '@peach/box/template'
 import type { ProjectFileMeta, ProjectFilePlane } from '@peach/box/plane'
 
 export class BundleFilePlane implements ProjectFilePlane {
   private readonly parts = new Map<string, Uint8Array>()
   private readonly entries = new Map<string, ProjectFileMeta>()
 
-  constructor(bundle: Uint8Array) {
+  constructor(bundle: Uint8Array, device: string | null) {
     if (bundle.byteLength === 0) throw new Error('a Box bundle cannot be empty')
+    if (device) this.record(PREBUILT_BUNDLE_DEVICE_PATH, new TextEncoder().encode(device))
     for (
       let offset = 0, index = 0;
       offset < bundle.byteLength;

package/cli/commands/box.ts

@@ -527,6 +527,8 @@ function cloudBoxClient(options: {
  */
 export async function createPrebuiltBundleBox(options: {
   bundle: Uint8Array
+  // the simulator's device model, or null for the Box page's default
+  device: string | null
   name: string
   endpoint: string
   apiOrigin: string
@@ -537,7 +539,7 @@ export async function createPrebuiltBundleBox(options: {
     name: options.name,
     stack: prebuiltBundleBoxTemplate.stack,
     template: BOX_TEMPLATES.resolve({ name: prebuiltBundleBoxTemplate.name }).provenance,
-    source: new BundleFilePlane(options.bundle),
+    source: new BundleFilePlane(options.bundle, options.device),
   })
 }
 
@@ -653,7 +655,12 @@ async function runCloudBoxCreate(
   try {
     const box =
       'bundle' in source
-        ? await createPrebuiltBundleBox({ ...connection, bundle: source.bundle, name })
+        ? await createPrebuiltBundleBox({
+            ...connection,
+            bundle: source.bundle,
+            device: null,
+            name,
+          })
         : await cloudBoxClient(connection).create({
             name,
             stack: template.stack,

package/cli/commands/cleanup.ts

@@ -58,13 +58,13 @@ export async function runCleanup(args: string[]): Promise<number> {
   if (args.length === 1 && args[0] === '--automatic-worker') {
     try {
       const result = applyAutomaticSootsimCleanup()
-      if (result.status === 'complete') {
+      // a run that found nothing stays silent: this worker writes to the
+      // user's terminal after the command that spawned it has returned.
+      if (result.status === 'complete' && result.reclaimedBytes > 0) {
         process.stderr.write(
-          result.reclaimedBytes > 0
-            ? `  peach automatic cleanup reclaimed ${formatSootsimBytes(
-                result.reclaimedBytes,
-              )}; active runtimes and app data were kept.\n`
-            : '  peach automatic cleanup found no obsolete local data.\n',
+          `  peach automatic cleanup reclaimed ${formatSootsimBytes(
+            result.reclaimedBytes,
+          )}; active runtimes and app data were kept.\n`,
         )
       } else if (result.status === 'deferred') {
         process.stderr.write(

package/cli/commands/control.ts

@@ -835,11 +835,15 @@ export interface BuildShellUrlOptions {
   // host page URL at boot (syncProofModeFromInitUrl) and pin everything that
   // would otherwise differ frame to frame: the TextInput caret stops blinking
   // and stays visible, and notifications stop auto-dismissing. capture-frame
-  // also reads the raw param and stops clipping the device corners, so a
+  // also reads the raw param and stops clipping the device corners, and the
+  // shell leaves out the Dynamic Island, which is hardware, so a
   // capture matches simctl's rectangular framebuffer. without it a
   // screen holding a focused text field never reaches three identical idle
   // frames, so the screenshot guard burns all 12 attempts and then fails.
   proof?: boolean
+  // launch-time environment variables, stamped as repeated ?env=KEY%3DVALUE.
+  // see the --env flag above.
+  env?: string[]
 }
 
 function bundleUrlOf(urlStr: string): string | undefined {
@@ -867,12 +871,20 @@ export async function buildShellUrl(
     await stampAppSplash(await stampAppFonts(resolved, project), project),
     project,
   )
-  if (!opts.device && !opts.proof && !opts.posture && !opts.osVersion) return stamped
+  if (
+    !opts.device &&
+    !opts.proof &&
+    !opts.posture &&
+    !opts.osVersion &&
+    !opts.env?.length
+  )
+    return stamped
   const url = new URL(stamped)
   if (opts.device) url.searchParams.set('device', opts.device)
   if (opts.posture) url.searchParams.set('posture', opts.posture)
   if (opts.osVersion) url.searchParams.set('osVersion', opts.osVersion)
   if (opts.proof) url.searchParams.set('proof', '1')
+  for (const entry of opts.env ?? []) url.searchParams.append('env', entry)
   return url.toString()
 }
 
@@ -1412,6 +1424,7 @@ export async function runOpenCommand(
       '--posture',
       '--os-version',
       '--viewport',
+      '--env',
     ],
   })
   const requestedProfileId = args.find((_, i) => args[i - 1] === '--profile')
@@ -1599,16 +1612,14 @@ export async function runOpenCommand(
     rnxExit(1)
   }
   // the window fits the box the browser stage fits the device into, which for
-  // a foldable spans every posture and orientation, so the device draws at its
-  // natural size in the pose it opens in instead of shrinking into a window
-  // sized for one pose.
+  // a foldable spans both postures, so the device draws at its natural size in
+  // the posture it opens in instead of shrinking into a window sized for one.
   const deviceFitBox = deviceArg
     ? resolveDeviceFitBox(
         deviceArg as DeviceModel,
         false,
         undefined,
         postureArg === 'open' ? 'open' : 'closed',
-        true,
       )
     : undefined
 
@@ -1621,6 +1632,24 @@ export async function runOpenCommand(
     rnxExit(1)
   }
 
+  // --env <KEY=VALUE> (repeatable) sets a launch-time environment variable,
+  // the peach analogue of an Xcode scheme env var or SIMCTL_CHILD_<VAR>:
+  // stamped as repeated ?env=, carried on AppLoadRequest, and read into a
+  // Swift guest's ProcessInfo.environment (WASI environ) exactly as it would
+  // read a real launch env. the guest app opts in by reading the key itself;
+  // no other surface is affected.
+  const envArgs: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== '--env') continue
+    const raw = args[i + 1]
+    const eqIndex = raw ? raw.indexOf('=') : -1
+    if (!raw || eqIndex <= 0) {
+      console.error(`  peach open: --env expects KEY=VALUE, got "${raw ?? ''}"`)
+      rnxExit(1)
+    }
+    envArgs.push(raw)
+  }
+
   // --viewport <WxH> sizes the driver-launched page explicitly (film and
   // promo captures frame the 3d stage in landscape). takes precedence over
   // the device-derived window; without either, the driver keeps its own
@@ -1645,6 +1674,7 @@ export async function runOpenCommand(
     resolvedBundle,
     project,
     proof: args.includes('--proof'),
+    env: envArgs.length ? envArgs : undefined,
   }
 
   // resolve the shell base URL from the bridge port we settled on, so the page

package/cli/commands/detox.ts

@@ -13,7 +13,6 @@ import {
   unlinkSync,
 } from 'fs'
 import { createRequire } from 'module'
-import { fileURLToPath } from 'node:url'
 import { tmpdir } from 'os'
 import { dirname, resolve, join, relative } from 'path'
 import { rnxPublicBrand } from '../../src/public-brand'
@@ -34,15 +33,17 @@ peach detox — run detox-style tests against a peach shell
 
 usage:
   peach detox [testFiles...]        run all tests under e2e/, test/e2e/, or detox/
+  peach detox --app <port|url>      the app each device.launchApp() opens
   peach detox --config <path>       use a specific jest config
   peach detox init                  scaffold rnx-detox.config.cjs + sample test
   peach detox --watch               jest watch mode
   peach detox --headed              keep the peach shell window visible
   peach detox -t <pattern>          pass a jest --testNamePattern
-  peach detox --no-launch           skip auto-launching a peach shell
+  peach detox --no-launch           skip the running-shell check
 
-peach detox auto-launches a peach shell if none is running on the
-expected port. disable with --no-launch if you're managing the shell yourself.
+peach detox needs a running peach shell: start your app and run
+\`peach open <app-port>\` first (the background service keeps one ready).
+it warns when none is reachable; --no-launch skips that check.
 `
 
 export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise<void> {
@@ -140,9 +141,25 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
   }
   testDir ??= process.cwd()
 
-  // auto-launch: make sure a peach shell is reachable before running jest.
-  // Reuse the Maestro discovery path: scan local dev servers.
-  // and `peach open` the first match.
+  // jest runs from the project, so the preset must resolve from it too; the
+  // standalone binary has no package directory of its own to point at.
+  let presetPath = ''
+  if (!localConfig) {
+    try {
+      presetPath = createRequire(join(process.cwd(), 'package.json')).resolve(
+        `${rnxPublicBrand.packageName}/detox/jest-preset`,
+      )
+    } catch {
+      console.error(
+        `  error: ${rnxPublicBrand.commandName} detox runs Jest from this project, which needs its dev dependencies:\n` +
+          `    npm i -D ${rnxPublicBrand.packageName} jest`,
+      )
+      rnxExit(1)
+    }
+  }
+
+  // the driver navigates to a running peach shell; warn before jest starts
+  // when none is reachable.
   if (!noLaunch) {
     await ensureShellRunning(port)
   }
@@ -162,9 +179,6 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
     // subpath exports, so we generate a real config file instead.
     // scope roots + testMatch to the discovered test dir so jest doesn't
     // scan the entire repo (which causes haste collisions in monorepos).
-    const presetPath = fileURLToPath(
-      import.meta.resolve(`${rnxPublicBrand.packageName}/detox/jest-preset`),
-    )
     // an external suite may optionally declare its own ignore patterns via e2e/jest-ignore.cjs
     const suiteIgnoreFile = testDir ? join(testDir, 'e2e', 'jest-ignore.cjs') : null
     let suiteIgnorePatterns: string[] = []
@@ -483,7 +497,7 @@ describe('example', () => {
   }
 
   console.log(`\n  next:`)
-  console.log(`    peach detox        # run the sample`)
+  console.log(`    peach detox --app <dev-server-port>   # run the sample`)
   console.log(`    peach detox --watch`)
   rnxExit(0)
 }

package/cli/commands/flow.ts

@@ -21,7 +21,7 @@ import { parseFlowFile, validateFlowFile } from '../flow-file'
 import { FlowLiveStatusReporter } from '../flow-live-status'
 import { finalizeFlowSession, keepFlowCandidate, startFlowSession } from '../flow-session'
 import { GLOBAL_FLAG_TAKES_VALUE } from '../parse-args'
-import { rnxExit } from '../run-rnx'
+import { PeachExit, rnxExit } from '../run-rnx'
 import {
   BRIDGE_VALUE_FLAGS,
   createBridge,
@@ -155,6 +155,13 @@ export function getLastFlowPreviewUploadResult(): UploadResult | null {
   return lastPreviewUploadResult
 }
 
+// why the last flow's preview upload failed, as the upload printed it
+let lastPreviewUploadError: string | null = null
+
+export function getLastFlowPreviewUploadError(): string | null {
+  return lastPreviewUploadError
+}
+
 // per-step trace of the most recent playback, preview or not — callers
 // Maestro callers fold this into their run registration.
 let lastFlowTraceSteps: SootSimFlowTraceStep[] = []
@@ -211,6 +218,7 @@ export async function runFlowPlayback(
   hooks: { beforeSteps?: () => Promise<void> } = {},
 ): Promise<number> {
   lastPreviewUploadResult = null
+  lastPreviewUploadError = null
   lastFlowTraceSteps = []
   if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
     console.log(`
@@ -260,8 +268,9 @@ options:
                        headless or stale
   --proof              deterministic-capture mode: pin the TextInput caret
                        visible instead of blinking, stop notifications
-                       auto-dismissing, and leave the device corners unclipped
-                       to match a native simctl framebuffer. a screen holding a
+                       auto-dismissing, leave the device corners unclipped and
+                       leave out the Dynamic Island, to match a
+                       native simctl framebuffer. a screen holding a
                        focused text field cannot reach three identical idle
                        frames without this, so its screenshot fails after 12
                        tries. use it for any run whose screenshots get
@@ -278,7 +287,8 @@ options:
                        public link origin for --preview (default: peachsim.com
                        for prod uploads)
   --billing-kind test_run
-                       meter the chained preview upload as a test run
+                       the chained upload is a hosted test job's recording,
+                       covered by the job's minutes (set by the hosted recorder)
   --owner <org>        associate preview upload with a linked org repo
   --repo <repo>        repo name for --owner; user must belong to the team
 
@@ -631,9 +641,9 @@ flow extension:
     // pr-preview run, so allow it for preview uploads. local flow recording
     // writes a file and matches `peach record --mode video`.
     allowGitHubRecording: preview,
-    // a test_run bills its recording from balance at finalize (preflighted
-    // at upload init), not from a plan entitlement: the plan gate would
-    // refuse every pay-as-you-go hosted test.
+    // a test_run recording is covered by its hosted job's minutes, not by a
+    // plan entitlement: the plan gate would refuse every pay-as-you-go
+    // hosted test.
     requireRecordingEntitlement: preview && previewBillingKind !== 'test_run',
     // re-arm the event recorder after every launchApp-with-reload. the
     // recorder lives in-page state and gets wiped by window.location.reload.
@@ -947,7 +957,9 @@ flow extension:
       const { runUpload } = await import('./upload')
       lastPreviewUploadResult = await runUpload(uploadArgs, {})
     } catch (err: any) {
-      console.error(`  preview upload failed: ${err?.message || err}`)
+      lastPreviewUploadError =
+        err instanceof PeachExit && err.reason ? err.reason : String(err?.message || err)
+      console.error(`  preview upload failed: ${lastPreviewUploadError}`)
       exitCode = 1
     }
   }