peachsim 0.1.1481 → 0.1.1594

package/cli/bridge-flow-runner.ts

@@ -1,5 +1,10 @@
 import * as fs from 'fs'
 import * as path from 'path'
+import {
+  isStorageSnapshot,
+  prepareStorageSnapshotForShare,
+  type ShareableStorageSnapshot,
+} from 'peach-engine/preview/storage-snapshot-contract'
 import { devices, type DeviceModel } from 'peach-engine/settings/devices'
 import { REQUIRED_IDENTICAL_FLOW_FRAMES, framesIdentical } from '../detox/proof-frame.cjs'
 import { flowTimeoutScale } from '../src/flow-timeout-scale'
@@ -128,21 +133,27 @@ function assertSupportedSelector(selector: unknown) {
   }
 }
 
-// the filters whose meaning is defined on the XCTest accessibility hierarchy.
-// ordinary lookups stay on the faster render tree; these read the engine's
-// accessibility projection through captureAccessibilityTree().
+// these filters require the XCTest hierarchy on every lookup. text selectors
+// also use that hierarchy on ios, including text in a nested anchor.
 const ACCESSIBILITY_SELECTOR_KEYS = [
   'containsChild',
   'containsDescendants',
   'focused',
 ] as const
 
-function needsAccessibilityProjection(selector: string | FlowTargetSelector): boolean {
-  if (typeof selector === 'string') return false
+function needsAccessibilityProjection(
+  selector: string | FlowTargetSelector,
+  includeText = false,
+): boolean {
+  if (typeof selector === 'string') return includeText
+  if (includeText && selector.text != null) return true
   if (ACCESSIBILITY_SELECTOR_KEYS.some((key) => selector[key] != null)) return true
   return ['childOf', 'below', 'above', 'leftOf', 'rightOf'].some((key) => {
     const nested: unknown = Reflect.get(selector, key)
-    return isSelectorRecord(nested) && needsAccessibilityProjection(nested)
+    return (
+      (typeof nested === 'string' || isSelectorRecord(nested)) &&
+      needsAccessibilityProjection(nested, includeText)
+    )
   })
 }
 
@@ -719,6 +730,12 @@ export interface MaestroStep {
   copyTextFrom?: string | FlowTargetSelector
   evalScript?: string
   openLink?: string | { link: string; autoVerify?: boolean; browser?: boolean }
+  addMedia?:
+    | string
+    | string[]
+    | {
+        files?: string | string[]
+      }
   // maestro `when:` conditional runs the step only if the predicate holds.
   // supports `visible` / `notVisible` with the same matcher shape used elsewhere.
   when?: {
@@ -936,6 +953,7 @@ export class SootSimBridgeFlowRunner {
   private lastRecordingStartedAtMs: number | null = null
   private lastRecordingDurationMs: number | null = null
   private lastRecordingFrameStats: unknown = null
+  private previewStorageSnapshot: ShareableStorageSnapshot | null = null
   private flowTraceSteps: SootSimFlowTraceStep[] = []
   // when the latest step that acted on the app settled
   private lastInteractionAt = Date.now()
@@ -975,6 +993,9 @@ export class SootSimBridgeFlowRunner {
        *  verifies entitlement before producing a shareable cloud artifact. */
       requireRecordingEntitlement?: boolean
       recordingFormat?: 'webm' | 'mp4'
+      /** a preview upload replays live from the app's storage as it was when
+       *  the video began, so the driver captures it right before recording. */
+      capturePreviewStorage?: boolean
       // fires after every page reload (launchApp clear-state) once the
       // tree is back and simId has been rotated. lets preview mode
       // re-start the event recorder, since `window.location.reload()`
@@ -1101,6 +1122,19 @@ export class SootSimBridgeFlowRunner {
       this.recordingAccessChecked = true
     }
 
+    if (this.opts.capturePreviewStorage && this.recordingStartedAtMs == null) {
+      const dumped: unknown = await this.bridge.send({
+        type: 'storageSnapshot',
+        simId: this.opts.simId,
+      })
+      if (!isStorageSnapshot(dumped)) {
+        throw new Error(
+          'the simulator returned a storage snapshot this build cannot read',
+        )
+      }
+      this.previewStorageSnapshot = prepareStorageSnapshotForShare(dumped)
+    }
+
     const startedAt = Date.now()
     const result = await this.evaluate<{
       ok: boolean
@@ -1112,7 +1146,7 @@ export class SootSimBridgeFlowRunner {
       if (!rec) return { ok: false, error: 'recorder unavailable on this page' }
       const format = ${JSON.stringify(this.opts.recordingFormat ?? 'webm')}
       if (rec.state() === 'recording') return { ok: true, format }
-      return rec.start({ format, fps: 24 })
+      return rec.start({ format, fps: 30 })
     })()`)
 
     if (!result?.ok) {
@@ -1147,6 +1181,10 @@ export class SootSimBridgeFlowRunner {
     return this.lastRecordingFrameStats
   }
 
+  getPreviewStorageSnapshot(): ShareableStorageSnapshot | null {
+    return this.previewStorageSnapshot
+  }
+
   getFlowTraceSteps(): SootSimFlowTraceStep[] {
     return [...this.flowTraceSteps]
   }
@@ -1162,9 +1200,12 @@ export class SootSimBridgeFlowRunner {
     const value = (step as Record<string, unknown>)[stepName]
     if (typeof value === 'string') return value.slice(0, 80)
     if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+    if (Array.isArray(value)) return value.map(String).join(', ').slice(0, 80)
     if (!value || typeof value !== 'object') return undefined
     const record = value as Record<string, unknown>
-    const direct = record.id ?? record.text ?? record.name ?? record.path
+    if (Array.isArray(record.files))
+      return record.files.map(String).join(', ').slice(0, 80)
+    const direct = record.id ?? record.text ?? record.name ?? record.path ?? record.files
     if (typeof direct === 'string' && direct) return direct.slice(0, 80)
     // extendedWaitUntil keeps its target under visible/notVisible and
     // scrollUntilVisible under element, so without this they render bare.
@@ -1213,13 +1254,19 @@ export class SootSimBridgeFlowRunner {
   async stopRecording(): Promise<string | null> {
     if (!this.recordingEnabled || !this.opts.recordingOutputDir) return null
     this.recordingEnabled = false
+    if (this.recordingStartedAtMs == null) {
+      this.lastRecordingStartedAtMs = null
+      this.lastRecordingDurationMs = null
+      this.lastRecordingFrameStats = null
+      return null
+    }
 
-    const stoppedAt = Date.now()
     const stopped = await this.evaluate<{
       ok: boolean
       error?: string
       size?: number
       mime?: string
+      durationMs: number
       frameStats?: unknown
     }>(`window.__sootsimRecorder.stop()`)
     if (!stopped?.ok) {
@@ -1227,10 +1274,11 @@ export class SootSimBridgeFlowRunner {
       this.lastRecordingFrameStats = null
       throw new Error(stopped?.error || 'recording stop failed')
     }
+    if (!Number.isFinite(stopped.durationMs) || stopped.durationMs <= 0) {
+      throw new Error('recording stop returned no playable duration')
+    }
     this.lastRecordingStartedAtMs = this.recordingStartedAtMs
-    this.lastRecordingDurationMs = this.recordingStartedAtMs
-      ? Math.max(1, stoppedAt - this.recordingStartedAtMs)
-      : null
+    this.lastRecordingDurationMs = stopped.durationMs
     this.lastRecordingFrameStats = stopped.frameStats ?? null
     this.recordingStartedAtMs = null
 
@@ -1297,23 +1345,13 @@ export class SootSimBridgeFlowRunner {
 
   private async findElement(opts: FlowTargetSelector) {
     assertSupportedSelector(opts)
-    // the structural filters are defined on the XCTest accessibility
-    // hierarchy, so they resolve against the engine's accessibility
-    // projection instead of the render tree.
-    if (needsAccessibilityProjection(opts)) {
+    if (needsAccessibilityProjection(opts, true)) {
       return this.findElementAccessibilityTree(opts)
     }
     return this.findElementScoped(opts)
   }
 
-  // structural filters (containsChild / containsDescendants / focused) read the
-  // engine's XCTest accessibility projection — one bridge evaluate, then the
-  // same Orchestra.buildFilter semantics the render resolver implements, over
-  // PeachAccessibilityNode instead of the visible semantic tree.
-  private async resolveAccessibilityElement(
-    opts: FlowTargetSelector,
-    command: string,
-  ): Promise<PeachAccessibilityNode | null> {
+  private async captureAccessibilityTree(): Promise<PeachAccessibilityNode[]> {
     const tree = await this.evaluate(`(async () => {
       const test = window.__sootsimTest
       if (!test || typeof test.captureAccessibilityTree !== 'function') throw new Error('engine accessibility snapshot is unavailable')
@@ -1321,6 +1359,16 @@ export class SootSimBridgeFlowRunner {
     })()`)
     if (!isPeachAccessibilityTree(tree))
       throw new Error('engine returned an invalid accessibility snapshot')
+    return tree
+  }
+
+  // one Orchestra resolver for text, structural filters and copyTextFrom.
+  private async resolveAccessibilityElement(
+    opts: FlowTargetSelector,
+    command: string,
+    snapshot?: PeachAccessibilityNode[],
+  ): Promise<PeachAccessibilityNode | null> {
+    const tree = snapshot ?? (await this.captureAccessibilityTree())
     if (tree.length === 0) return null
     if (tree.some((node) => node.platform !== 'ios'))
       throw new Error(`${command} requires the iOS accessibility hierarchy`)
@@ -1328,9 +1376,19 @@ export class SootSimBridgeFlowRunner {
   }
 
   private async findElementAccessibilityTree(opts: FlowTargetSelector) {
+    const tree = await this.captureAccessibilityTree()
+    // the snapshot's platform is the live device contract. android keeps its
+    // existing render-tree text lookup; XCTest-only filters still refuse it.
+    if (
+      !needsAccessibilityProjection(opts) &&
+      tree.some((node) => node.platform === 'android')
+    ) {
+      return this.findElementScoped(opts)
+    }
     const node = await this.resolveAccessibilityElement(
       opts,
-      'containsChild, containsDescendants and focused',
+      'text, containsChild, containsDescendants and focused',
+      tree,
     )
     if (!node) return null
     const frame = node.frame
@@ -1382,6 +1440,14 @@ export class SootSimBridgeFlowRunner {
         }
       }
       const painted = (n) => (n.visibleFrame?.area ?? 0) > 0
+      // one viewport contract, shared with isOffscreen in
+      // commands/inspect/resolve-target.ts: a center on the edge still takes
+      // a tap, so the edge counts as on screen here too.
+      const centerOnScreen = (n) => {
+        const cx = n.absolutePosition.x + n.layout.width / 2
+        const cy = n.absolutePosition.y + n.layout.height / 2
+        return cx >= 0 && cx <= ${screen.width} && cy >= 0 && cy <= ${screen.height}
+      }
       const byPosition = (a, b) =>
         a.absolutePosition.y - b.absolutePosition.y ||
         a.absolutePosition.x - b.absolutePosition.x
@@ -1444,17 +1510,10 @@ export class SootSimBridgeFlowRunner {
           const anchors = pick(matchAll(sel[key]), sel[key].index)
           candidates = candidates.filter((n) => anchors.some((other) => relative[key](n, other)))
         }
-        // prefer painted matches, then on-screen ones (findByTestId's
-        // visible-first behavior); only fall back to off-screen ones when
-        // nothing is on-screen, so index: still resolves a target that needs
-        // scrolling into view. a screen still mounted under the one on top
-        // 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.height}
-        })
-        if (candidates.some(painted)) candidates = candidates.filter(painted)
-        else if (onScreen.length > 0) candidates = onScreen
+        // scope before visibility: childOf narrows the match set first, so a
+        // clipped sliver inside the container survives to resolve (and refuse
+        // honestly) instead of being discarded for a hittable duplicate the
+        // scope then removes.
         if (sel.childOf) {
           const containers = matchAll(sel.childOf)
           const container = containers.find(painted) ?? containers[0]
@@ -1469,6 +1528,26 @@ export class SootSimBridgeFlowRunner {
             return cx >= x0 && cx <= x1 && cy >= y0 && cy <= y1
           })
         }
+        // prefer painted matches, then on-screen ones (findByTestId's
+        // visible-first behavior); only fall back to off-screen ones when
+        // nothing is on-screen, so index: still resolves a target that needs
+        // scrolling into view. a screen still mounted under the one on top
+        // paints nothing, and maestro's hierarchy never holds it.
+        const onScreen = candidates.filter(centerOnScreen)
+        // without an explicit index, prefer a painted match whose center is
+        // on screen: a painted sliver with its center off screen cannot take
+        // a tap at its center, so a duplicate id resolves to the hittable
+        // match. an explicit index keeps the full painted order, and a
+        // clipped-only match still resolves so the tap reports honestly.
+        const paintedCandidates = candidates.filter(painted)
+        if (paintedCandidates.length > 0) {
+          if (sel.index == null) {
+            const hittable = paintedCandidates.filter(centerOnScreen)
+            candidates = hittable.length > 0 ? hittable : paintedCandidates
+          } else {
+            candidates = paintedCandidates
+          }
+        } else if (onScreen.length > 0) candidates = onScreen
         // maestro's index: sorts matches by frame y, then x, and without an
         // index takes the first in the ios hierarchy, which lays siblings out
         // by position rather than subview order (RAN on ios 27: two views with
@@ -2456,10 +2535,14 @@ export class SootSimBridgeFlowRunner {
   }
 
   async back() {
-    try {
-      await this.tapOn('‹')
-    } catch {
-      await this.tapOn('<')
+    const dispatched = await this.bridge.send({
+      type: 'call',
+      simId: this.opts.simId,
+      path: 'SootSim.bridges.mainShell.goBack',
+      args: [],
+    })
+    if (dispatched !== true) {
+      throw new Error('back failed: shell back action was not dispatched')
     }
   }
 
@@ -2797,6 +2880,7 @@ export class SootSimBridgeFlowRunner {
       pollMs: 32,
       stablePolls: 3,
       strict: true,
+      paintStill: true,
     })
     if (!result.settled) {
       throw new Error(
@@ -2968,6 +3052,60 @@ export class SootSimBridgeFlowRunner {
     this.firstLaunchDone = true
   }
 
+  async addMedia(target: NonNullable<MaestroStep['addMedia']>) {
+    const rawFiles =
+      typeof target === 'string'
+        ? [target]
+        : Array.isArray(target)
+          ? target
+          : typeof target.files === 'string'
+            ? [target.files]
+            : Array.isArray(target.files)
+              ? target.files
+              : []
+    if (rawFiles.length === 0) {
+      throw new Error('addMedia requires at least one file path')
+    }
+    for (const fileSpec of rawFiles) {
+      const filePath = path.resolve(this.opts.flowDir, fileSpec)
+      const stat = fs.statSync(filePath)
+      const bytes = fs.readFileSync(filePath)
+      const ext = path.extname(filePath).slice(1).toLowerCase()
+      const mimeType =
+        ext === 'png'
+          ? 'image/png'
+          : ext === 'webp'
+            ? 'image/webp'
+            : ext === 'gif'
+              ? 'image/gif'
+              : ext === 'svg'
+                ? 'image/svg+xml'
+                : ext === 'avif'
+                  ? 'image/avif'
+                  : ext === 'bmp'
+                    ? 'image/bmp'
+                    : ext === 'ico'
+                      ? 'image/x-icon'
+                      : 'image/jpeg'
+      const dataUrl = `data:${mimeType};base64,${bytes.toString('base64')}`
+      const added = await this.evaluate<{ ok: boolean; error?: string }>(
+        `(async () => {
+          const add = window.__sootsimAddPhotoDataUrl
+          if (typeof add !== 'function') {
+            return { ok: false, error: 'photo library bridge unavailable' }
+          }
+          const entry = await add(${JSON.stringify(dataUrl)}, { createdAt: ${JSON.stringify(Math.round(stat.mtimeMs))} })
+          return entry ? { ok: true } : { ok: false, error: 'failed to decode image' }
+        })()`,
+      )
+      if (!added?.ok) {
+        throw new Error(
+          `addMedia(${fileSpec}) failed: ${added?.error || 'unknown error'}`,
+        )
+      }
+    }
+  }
+
   // evaluate a `when:` predicate. returns true if the step should run.
   // `visible:` and `notVisible:` answer the same question assertVisible does,
   // so they read the engine's visibleFrame too. resolving them by mere presence
@@ -3088,6 +3226,18 @@ export class SootSimBridgeFlowRunner {
     }
 
     try {
+      // containers defer to their executed children: a nested launch must finish
+      // resetting the guest before the first playable frame is recorded.
+      if (
+        this.recordingEnabled &&
+        this.recordingStartedAtMs == null &&
+        !step.launchApp &&
+        !step.runFlow &&
+        !step.repeat &&
+        !step.retry
+      ) {
+        await this.ensureRecordingStarted()
+      }
       // simple commands have a wall-clock watchdog. bounded operations keep
       // their own lookup, settle and bridge deadlines, so the watchdog cannot
       // report a completed step while its action continues in the background.
@@ -3118,6 +3268,9 @@ export class SootSimBridgeFlowRunner {
           // meant the watchdog always won that race, reporting "bridge probably
           // hung" for a screen that was merely still animating.
           step.takeScreenshot ||
+          // waitForAnimationToEnd ends at its own timeout, which a flow may set
+          // past 10s, and continues as maestro does on a screen still moving.
+          step.waitForAnimationToEnd ||
           // assertions wait out maestro's lookup window, longer than 10s, and
           // every query they make times out on its own, so they report their
           // own failure instead of the watchdog's guess.
@@ -3377,6 +3530,8 @@ export class SootSimBridgeFlowRunner {
       this.runScript(rs)
     } else if (step.openLink !== undefined) {
       await this.openLink(step.openLink)
+    } else if (step.addMedia !== undefined) {
+      await this.addMedia(step.addMedia)
     } else if (step.runFlow) {
       const rf = step.runFlow
       const file = typeof rf === 'string' ? rf : rf.file

package/cli/cloud-test-tunnel.ts

@@ -137,6 +137,8 @@ export function startCloudTestTokenProxy(
       return
     }
     if (selectedPort !== upstreamPort) headers.host = `127.0.0.1:${selectedPort}`
+    // the recorder's browser origin belongs to its host, not this dev server.
+    if (headers.origin) headers.origin = `http://127.0.0.1:${selectedPort}`
     for (const key of Object.keys(headers)) {
       const lower = key.toLowerCase()
       if (lower.startsWith('x-forwarded-') || lower.startsWith('cf-')) {

package/cli/command-registry.ts

@@ -50,7 +50,7 @@ const NODE_COMMAND_NAMES = [
   'use',
   'claim',
   'close',
-  'compat',
+  'doctor',
   'project-report',
   'support',
   'desktop',
@@ -129,6 +129,7 @@ const VALUE_FLAGS = new Set([
   '--device',
   '--posture',
   '--os-version',
+  '--ios-target',
   '--output',
   '-o',
   '--out',

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

@@ -10,6 +10,7 @@
 
 import {
   PREBUILT_BUNDLE_DEVICE_PATH,
+  PREBUILT_BUNDLE_INITIAL_URL_PATH,
   PREBUILT_BUNDLE_NATIVE_RENDERER_PATH,
   prebuiltAppFontsPartPath,
   PREBUILT_BUNDLE_PART_BYTES,
@@ -25,6 +26,7 @@ export class BundleFilePlane implements ProjectFilePlane {
   constructor(
     bundle: Uint8Array,
     device: string | null,
+    initialUrl: string | null,
     appFonts = '',
     nativeRenderer?: NativeRenderer,
   ) {
@@ -32,6 +34,8 @@ export class BundleFilePlane implements ProjectFilePlane {
     if (appFonts)
       this.recordParts(new TextEncoder().encode(appFonts), prebuiltAppFontsPartPath)
     if (device) this.record(PREBUILT_BUNDLE_DEVICE_PATH, new TextEncoder().encode(device))
+    if (initialUrl)
+      this.record(PREBUILT_BUNDLE_INITIAL_URL_PATH, new TextEncoder().encode(initialUrl))
     if (nativeRenderer !== undefined)
       this.record(
         PREBUILT_BUNDLE_NATIVE_RENDERER_PATH,

package/cli/commands/box.ts

@@ -27,7 +27,6 @@ import {
   cloudBoxConnectUrl,
   createCloudBoxProvider,
   ensureCloudBoxBrowser,
-  heartbeatSession,
   resolveCloudBoxReference,
 } from 'peach-cloud-box/client'
 import { getRuntimePlatform, isDeviceModel } from 'peach-engine/settings/devices'
@@ -361,7 +360,6 @@ async function runCloudBoxConnect(args: string[]): Promise<number> {
   const origin = apiOrigin(args, auth)
 
   let session: BoxShellSession | null = null
-  let heartbeat: { stop: () => void } | null = null
   try {
     const reference = await resolveCloudBoxReference({ apiOrigin: origin, apiKey, boxId })
     const box = await createBoxClient(
@@ -388,11 +386,6 @@ async function runCloudBoxConnect(args: string[]): Promise<number> {
     }
     console.log(`  ...accessing shell\n`)
     session = await box.connect()
-    // the same reason `create` heartbeats: the box holds no account credential,
-    // so the client using it is what keeps its session alive.
-    const sessionId = box.description.sessionId
-    if (!sessionId) throw new BoxClientError('the box service returned no session id')
-    heartbeat = heartbeatSession({ apiOrigin: origin, apiKey, sessionId })
     return await repl(session, '')
   } catch (error) {
     if (error instanceof BoxClientError) {
@@ -401,7 +394,6 @@ async function runCloudBoxConnect(args: string[]): Promise<number> {
     }
     throw error
   } finally {
-    heartbeat?.stop()
     session?.close()
   }
 }
@@ -529,6 +521,8 @@ export async function createPrebuiltBundleBox(options: {
   nativeProjectDir?: string
   // the simulator's device model, or null for the Box page's default
   device: string | null
+  // the link the app launches with, as Linking.getInitialURL reports it
+  initialUrl?: string | null
   name: string
   endpoint: string
   apiOrigin: string
@@ -550,6 +544,7 @@ export async function createPrebuiltBundleBox(options: {
     source: new BundleFilePlane(
       options.bundle,
       options.device,
+      options.initialUrl ?? null,
       options.nativeProjectDir
         ? readNativeLinkedAppFontsWire({
             projectDir: options.nativeProjectDir,
@@ -711,7 +706,6 @@ async function runCloudBoxCreate(
     accountId,
   }
   let session: BoxShellSession | null = null
-  let heartbeat: { stop: () => void } | null = null
   try {
     const box =
       'bundle' in source
@@ -760,16 +754,6 @@ async function runCloudBoxCreate(
     }
     console.log(`  ...accessing shell\n`)
     session = await box.connect()
-    // bank the wall clock while the shell is open. the box holds no account
-    // credential, so the client that is using it is what keeps the session
-    // alive; when this process dies the sweep closes it at the last heartbeat.
-    const sessionId = box.description.sessionId
-    if (!sessionId) throw new BoxClientError('the box service returned no session id')
-    heartbeat = heartbeatSession({
-      apiOrigin: apiOrigin(args, auth),
-      apiKey,
-      sessionId,
-    })
     return await repl(session, '')
   } catch (error) {
     if (error instanceof BoxClientError) {
@@ -778,7 +762,6 @@ async function runCloudBoxCreate(
     }
     throw error
   } finally {
-    heartbeat?.stop()
     session?.close()
   }
 }