peachsim 0.1.1481 → 0.1.1619

package/cli/bridge-flow-runner.ts

@@ -1,5 +1,11 @@
 import * as fs from 'fs'
 import * as path from 'path'
+import { isTextInputEditCommand, type TextInputEditCommand } from '@peach/globals'
+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'
@@ -31,6 +37,7 @@ import type {
   SystemPermissionKind,
   SystemPermissionStatus,
 } from '@peach/globals'
+import type { ProfileFile } from '@peach/globals/profiler'
 
 const DEFAULT_TIMEOUT = 10000
 // how long maestro looks for a required assertion's element, counted from the
@@ -128,21 +135,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)
+    )
   })
 }
 
@@ -174,32 +187,35 @@ function accessibilitySubtreeNodes(
 function accessibilityTextMatcher(
   value: string,
   kind: 'text' | 'id',
-): (candidate: string | null) => boolean {
-  // absolute boundaries preserve Regex.matches with multiline enabled, even
-  // for a final newline. ^ and $ inside the user's pattern still match lines.
-  let pattern: RegExp
+): ((candidate: string | null) => boolean) & Pick<RegExp, 'source' | 'flags'> {
+  let source = value
   try {
-    pattern = new RegExp(`(?<![\\s\\S])(?:${value})(?![\\s\\S])`, 'ism')
+    new RegExp(source, 'ism')
   } catch {
     // upstream StringUtils.toRegexSafe quotes an invalid regex as literal copy.
-    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-    pattern = new RegExp(`(?<![\\s\\S])(?:${escaped})(?![\\s\\S])`, 'ism')
+    source = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
   }
-  return (candidate) => {
-    // IOSDriver emits an empty attribute for absent label, value and id.
-    const native = candidate ?? ''
-    if (kind === 'id')
+  // absolute boundaries preserve Regex.matches with multiline enabled, even
+  // for a final newline. ^ and $ inside the user's pattern still match lines.
+  const pattern = new RegExp(`(?<![\\s\\S])(?:${source})(?![\\s\\S])`, 'ism')
+  return Object.assign(
+    (candidate: string | null) => {
+      // IOSDriver emits an empty attribute for absent label, value and id.
+      const native = candidate ?? ''
+      if (kind === 'id')
+        return (
+          pattern.test(native) || pattern.test(native.slice(native.lastIndexOf('/') + 1))
+        )
+      const stripped = native.replaceAll('\n', ' ')
       return (
-        pattern.test(native) || pattern.test(native.slice(native.lastIndexOf('/') + 1))
+        native === value ||
+        stripped === value ||
+        pattern.test(native) ||
+        pattern.test(stripped)
       )
-    const stripped = native.replaceAll('\n', ' ')
-    return (
-      native === value ||
-      stripped === value ||
-      pattern.test(native) ||
-      pattern.test(stripped)
-    )
-  }
+    },
+    { source: pattern.source, flags: pattern.flags },
+  )
 }
 
 // maestro reads ios frames as integer edges (AXElement.boundsString).
@@ -602,6 +618,7 @@ export interface MaestroStep {
         optional?: boolean
       }
   inputText?: string
+  editText?: TextInputEditCommand
   pressKey?: string
   dispatchKey?: string
   swipe?: {
@@ -719,6 +736,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?: {
@@ -776,6 +799,27 @@ const MAESTRO_PERMISSION_STATUS: Record<string, SystemPermissionStatus> = {
   unset: 'not-determined',
 }
 
+// maestro's ios location permission also takes the CLAuthorizationStatus names:
+// always is authorized always, inuse is authorized when in use and still
+// undetermined for always, never is denied.
+const MAESTRO_LOCATION_STATUS: Record<
+  string,
+  readonly (readonly [SystemPermissionKind, SystemPermissionStatus])[]
+> = {
+  always: [
+    ['location-when-in-use', 'authorized'],
+    ['location-always', 'authorized'],
+  ],
+  inuse: [
+    ['location-when-in-use', 'authorized'],
+    ['location-always', 'not-determined'],
+  ],
+  never: [
+    ['location-when-in-use', 'denied'],
+    ['location-always', 'denied'],
+  ],
+}
+
 function maestroLaunchPermissions(
   permissions: unknown,
 ): Map<SystemPermissionKind, SystemPermissionStatus> {
@@ -785,12 +829,24 @@ function maestroLaunchPermissions(
   const statuses = new Map<SystemPermissionKind, SystemPermissionStatus>()
   // `all` first so a named permission overrides it
   entries.sort(([a], [b]) => Number(b === 'all') - Number(a === 'all'))
-  for (const [name, value] of entries) {
-    const status = MAESTRO_PERMISSION_STATUS[String(value).toLowerCase()]
+  for (const [name, rawValue] of entries) {
+    const permission = name.toLowerCase()
+    const value = String(rawValue).toLowerCase()
+    const locationStatuses =
+      permission === 'location' ? MAESTRO_LOCATION_STATUS[value] : undefined
+    if (locationStatuses) {
+      for (const [kind, status] of locationStatuses) statuses.set(kind, status)
+      continue
+    }
+    const status = MAESTRO_PERMISSION_STATUS[value]
     if (!status) {
-      throw new Error(`launchApp.permissions.${name} must be allow, deny, or unset`)
+      throw new Error(
+        permission === 'location'
+          ? `launchApp.permissions.${name} must be allow, deny, unset, always, inuse, or never`
+          : `launchApp.permissions.${name} must be allow, deny, or unset`,
+      )
     }
-    for (const kind of MAESTRO_PERMISSION_KINDS[name.toLowerCase()] ?? []) {
+    for (const kind of MAESTRO_PERMISSION_KINDS[permission] ?? []) {
       statuses.set(kind, status)
     }
   }
@@ -916,6 +972,13 @@ export function parseFlowSteps(content: string): MaestroStep[] {
   return parseFlowFile(content).steps
 }
 
+class CaptureSetupError extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause })
+    this.name = 'CaptureSetupError'
+  }
+}
+
 export class SootSimBridgeFlowRunner {
   stepDelay = 0
 
@@ -935,7 +998,8 @@ export class SootSimBridgeFlowRunner {
   private recordingStartedAtMs: number | null = null
   private lastRecordingStartedAtMs: number | null = null
   private lastRecordingDurationMs: number | null = null
-  private lastRecordingFrameStats: unknown = null
+  private lastRecordingProfile: ProfileFile | null = 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 +1039,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()`
@@ -1087,7 +1154,17 @@ export class SootSimBridgeFlowRunner {
     throw new Error(`app not ready after ${timeout}ms: ${waitReadyReason(status)}`)
   }
 
+  // capture setup failures are run failures: wrapping them keeps an optional
+  // step or a retry body from consuming them as ordinary action failures.
   private async ensureRecordingStarted() {
+    try {
+      await this.startRecordingOnce()
+    } catch (error) {
+      throw error instanceof CaptureSetupError ? error : new CaptureSetupError(error)
+    }
+  }
+
+  private async startRecordingOnce() {
     if (!this.opts.recordingOutputDir) {
       throw new Error('recording output directory not configured')
     }
@@ -1101,6 +1178,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,17 +1202,32 @@ 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) {
       throw new Error(result?.error || 'recording unavailable on this page')
     }
     if (!this.recordingStartedAtMs) {
-      this.recordingStartedAtMs =
+      const startedAtMs =
         typeof result.startedAtMs === 'number' && Number.isFinite(result.startedAtMs)
           ? result.startedAtMs
           : startedAt
+      // events can start before video setup, even without a launchApp step.
+      // rebase once at the shared first-frame boundary for every start path;
+      // the start is ready only after the rebase lands, so a rejected rebase
+      // stops the recorder and leaves no half-started state to skip past.
+      try {
+        await this.evaluate(`(() => {
+          const recorder = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder
+          if (!recorder?.isRecording?.()) return
+          return recorder.markVisibleStart(${JSON.stringify(startedAtMs)})
+        })()`)
+      } catch (error) {
+        await this.evaluate(`window.__sootsimRecorder.stop()`).catch(() => {})
+        throw error
+      }
+      this.recordingStartedAtMs = startedAtMs
     }
   }
 
@@ -1143,8 +1248,12 @@ export class SootSimBridgeFlowRunner {
     return this.lastRecordingStartedAtMs
   }
 
-  getLastRecordingFrameStats(): unknown {
-    return this.lastRecordingFrameStats
+  getLastRecordingProfile(): ProfileFile | null {
+    return this.lastRecordingProfile
+  }
+
+  getPreviewStorageSnapshot(): ShareableStorageSnapshot | null {
+    return this.previewStorageSnapshot
   }
 
   getFlowTraceSteps(): SootSimFlowTraceStep[] {
@@ -1162,9 +1271,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,25 +1325,32 @@ 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.lastRecordingProfile = null
+      return null
+    }
 
-    const stoppedAt = Date.now()
     const stopped = await this.evaluate<{
       ok: boolean
       error?: string
       size?: number
       mime?: string
-      frameStats?: unknown
+      durationMs: number
+      profile?: ProfileFile | null
     }>(`window.__sootsimRecorder.stop()`)
     if (!stopped?.ok) {
       this.recordingStartedAtMs = null
-      this.lastRecordingFrameStats = null
+      this.lastRecordingProfile = 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.lastRecordingFrameStats = stopped.frameStats ?? null
+    this.lastRecordingDurationMs = stopped.durationMs
+    this.lastRecordingProfile = stopped.profile ?? null
     this.recordingStartedAtMs = null
 
     // drain blob in chunks
@@ -1297,23 +1416,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 +1430,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 +1447,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
@@ -1367,7 +1496,16 @@ export class SootSimBridgeFlowRunner {
       if (!test || !test.queryAll) return null
       const selector = ${JSON.stringify(opts)}
       const compile = ${accessibilityTextMatcher.toString()}
-      const all = ((await test.queryAll({})) || []).filter(
+      // relative filters need their anchors too; other id selectors only
+      // project matching nodes, retaining every duplicate for ordering below.
+      // patterns accepting an absent id also need unidentified nodes.
+      const idMatcher = selector.id == null ? null : compile(selector.id, 'id')
+      const needsAnchors = ['childOf', 'below', 'above', 'leftOf', 'rightOf']
+        .some((key) => selector[key] != null)
+      const query = idMatcher && !idMatcher(null) && !needsAnchors
+        ? { idPattern: { source: idMatcher.source, flags: idMatcher.flags, matchLastSegment: true } }
+        : {}
+      const all = ((await test.queryAll(query)) || []).filter(
         (n) => n && n.absolutePosition && n.layout,
       )
       // maestro reads ios frames as integer edges (AXElement.boundsString)
@@ -1382,6 +1520,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 +1590,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 +1608,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
@@ -1589,11 +1748,22 @@ export class SootSimBridgeFlowRunner {
     })) as { ok?: boolean; value?: boolean } | null
   }
 
+  // the engine's inspect geometry revision: equal readings bracket a span in
+  // which no tree, layout, scroll or prop write could move any element.
+  private async geometryRevision(): Promise<string | null> {
+    const revision = await this.evaluate(
+      `(async () => window.__sootsimTest?.getGeometryRevision?.())()`,
+    )
+    return typeof revision === 'string' ? revision : null
+  }
+
   private async waitForElement(opts: FlowTargetSelector, timeoutMs = 5000) {
     const deadline = Date.now() + timeoutMs
+    let revision = await this.geometryRevision()
     let element = await this.findElement(opts)
     while (!element && Date.now() < deadline) {
       await sleep(150)
+      revision = await this.geometryRevision()
       element = await this.findElement(opts)
     }
     if (!element) return element
@@ -1603,10 +1773,15 @@ export class SootSimBridgeFlowRunner {
     // new-thread title tap opened the photo picker this way (2026-07-10).
     // require two consecutive samples at the same absolute position before
     // interacting, bounded so a perpetually-animating target still proceeds.
+    // a revision unchanged since the last sample began proves the next
+    // sample would read the same frame, so it is not read again.
     const stabilityDeadline = Date.now() + 1200
     let prev = element
-    while (Date.now() < stabilityDeadline) {
+    do {
       await sleep(120)
+      const sampled = await this.geometryRevision()
+      if (sampled !== null && sampled === revision) return element
+      revision = sampled
       const next = await this.findElement(opts)
       if (!next) break
       const moved =
@@ -1617,7 +1792,7 @@ export class SootSimBridgeFlowRunner {
       element = next
       if (!moved) return element
       prev = next
-    }
+    } while (Date.now() < stabilityDeadline)
     return element
   }
 
@@ -1919,6 +2094,19 @@ export class SootSimBridgeFlowRunner {
     await sleep(200)
   }
 
+  async editText(command: TextInputEditCommand) {
+    if (!isTextInputEditCommand(command))
+      throw new Error('editText: invalid range command')
+    if (!(await this.waitForFocusedTextInput()))
+      throw new Error('editText: no focused TextInput')
+    await this.bridge.send({
+      type: 'keyboard',
+      simId: this.opts.simId,
+      action: 'edit',
+      edit: command,
+    })
+  }
+
   // poll for a focused text input. returns true once getFocusedNode reports a
   // node (focus landed), false if the budget elapses. callers use it both as a
   // tap-focus confirmation (tapOn retry) and a pre-type barrier (inputText).
@@ -1952,7 +2140,7 @@ export class SootSimBridgeFlowRunner {
     expected?: FocusedTextInputInfo | null,
   ): Promise<boolean> {
     const deadline = Date.now() + timeoutMs
-    while (Date.now() < deadline) {
+    do {
       try {
         const focused = await this.callTest<FocusedTextInputInfo | null>('getFocusedNode')
         if (focused && this.focusedTextInputMatches(focused, expected)) return true
@@ -1960,7 +2148,7 @@ export class SootSimBridgeFlowRunner {
         // bridge hiccup — keep polling within the budget
       }
       await sleep(50)
-    }
+    } while (Date.now() < deadline)
     return false
   }
 
@@ -2003,7 +2191,7 @@ export class SootSimBridgeFlowRunner {
     })
 
     const deadline = Date.now() + 3000
-    while (Date.now() < deadline) {
+    do {
       // the host test bridge proxies the tenant, so isTextInputFocused
       // resolves a promise; reading it unawaited is always truthy.
       const state = await this.evaluate<{
@@ -2025,7 +2213,7 @@ export class SootSimBridgeFlowRunner {
         return
       }
       await sleep(80)
-    }
+    } while (Date.now() < deadline)
   }
 
   async eraseText(count: number) {
@@ -2045,11 +2233,11 @@ export class SootSimBridgeFlowRunner {
   async waitFor(opts: { text?: string; id?: string; timeout?: number }) {
     const { timeout, ...selector } = opts
     const deadline = Date.now() + scaledTimeout(timeout || DEFAULT_TIMEOUT)
-    while (Date.now() < deadline) {
+    do {
       const element = await this.findElement(selector)
       if (element) return
       await sleep(200)
-    }
+    } while (Date.now() < deadline)
     // surface whether the element existed but was off-screen vs never
     // showed up at all — the two failure modes need different debugging
     // (scroll-position bug vs missing wait-step / wrong screen).
@@ -2456,10 +2644,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')
     }
   }
 
@@ -2486,7 +2678,7 @@ export class SootSimBridgeFlowRunner {
     )
     const deadline = Date.now() + (opts.timeout || 20000)
     const direction = opts.direction?.toUpperCase() || 'DOWN'
-    while (Date.now() < deadline) {
+    do {
       const screen = await this.screenBounds()
       const centerX = screen.width / 2
       const centerY = screen.height / 2
@@ -2525,7 +2717,7 @@ export class SootSimBridgeFlowRunner {
         Math.max(1, Math.round(duration / 16)),
         16,
       )
-    }
+    } while (Date.now() < deadline)
 
     throw new Error(`scrollUntilVisible: ${JSON.stringify(target)} not found`)
   }
@@ -2536,7 +2728,8 @@ export class SootSimBridgeFlowRunner {
     timeout?: number
   }) {
     const deadline = Date.now() + scaledTimeout(opts.timeout || DEFAULT_TIMEOUT)
-    while (Date.now() < deadline) {
+    // sample once even when scheduling consumes the initial lookup window.
+    do {
       const visibleOkay = opts.visible
         ? await this.isElementVisible(
             typeof opts.visible === 'string' ? { text: opts.visible } : opts.visible,
@@ -2551,7 +2744,7 @@ export class SootSimBridgeFlowRunner {
         : true
       if (visibleOkay && notVisibleOkay) return
       await sleep(200)
-    }
+    } while (Date.now() < deadline)
     throw new Error('extendedWaitUntil timed out')
   }
 
@@ -2596,7 +2789,7 @@ export class SootSimBridgeFlowRunner {
     if (!this.recordingEnabled && !this.profilingEnabled) return
     const deadline = Date.now() + 10000
     let lastError: unknown = null
-    while (Date.now() < deadline) {
+    do {
       try {
         if (this.recordingEnabled) await this.ensureRecordingStarted()
         if (this.profilingEnabled) await this.startProfile()
@@ -2605,7 +2798,7 @@ export class SootSimBridgeFlowRunner {
         lastError = err
         await sleep(250)
       }
-    }
+    } while (Date.now() < deadline)
     throw new Error(
       `capture re-arm failed after app reload: ${
         lastError instanceof Error ? lastError.message : String(lastError)
@@ -2710,17 +2903,7 @@ 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)
-      }
     }
   }
 
@@ -2736,22 +2919,6 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
-  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}`,
-      )
-    }
-  }
-
   // maestro waits around taps for the screen to stop changing, up to
   // its ios driver's 3 s settle budget, comparing screenshots, so an action
   // still in flight (a submit spinner, a sheet closing) finishes before the
@@ -2797,8 +2964,18 @@ export class SootSimBridgeFlowRunner {
       pollMs: 32,
       stablePolls: 3,
       strict: true,
+      paintStill: true,
     })
     if (!result.settled) {
+      // an app loop that never ends (a pulsing status dot) leaves only the
+      // pixels moving. maestro on ios captures that frame and continues, so
+      // do the same; any other blocker is real unfinished work and still fails.
+      if (result.blockedBy.startsWith('screen pixels still changing over ')) {
+        console.warn(
+          `  [flow]   screen never became still in ${result.elapsed}ms; capturing as maestro does`,
+        )
+        return
+      }
       throw new Error(
         `visual state did not settle within ${result.elapsed}ms (${result.blockedBy})`,
       )
@@ -2817,7 +2994,7 @@ export class SootSimBridgeFlowRunner {
   private async waitForShellAppLaunched(appId: string, timeoutMs: number) {
     const deadline = Date.now() + timeoutMs
     let lastState: ShellState | null = null
-    while (Date.now() < deadline) {
+    do {
       try {
         lastState = await getShellState(this.bridge)
       } catch {
@@ -2833,7 +3010,7 @@ export class SootSimBridgeFlowRunner {
         return
       }
       await sleep(16)
-    }
+    } while (Date.now() < deadline)
   }
 
   private async launchShellAppFromHomeIfNeeded(opts: unknown): Promise<boolean> {
@@ -2968,6 +3145,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
@@ -3014,7 +3245,11 @@ export class SootSimBridgeFlowRunner {
     )
   }
 
-  async runStep(rawStepInput: MaestroStep | string, stepIndex: number) {
+  async runStep(
+    rawStepInput: MaestroStep | string,
+    stepIndex: number,
+    onStepStart?: () => Promise<void>,
+  ) {
     await this.liveStatus?.waitWhilePaused()
     // maestro allows several commands in BARE-STRING form (`- back`,
     // `- hideKeyboard`, `- waitForAnimationToEnd`, `- scrollUp`, …). yaml parses
@@ -3028,7 +3263,7 @@ export class SootSimBridgeFlowRunner {
     const stepName =
       Object.keys(rawStep).find((k) => k !== 'when') || Object.keys(rawStep)[0]
     console.log(`[flow] step ${stepIndex + 1}: ${stepName}`)
-    const startedAtMs = Date.now()
+    let startedAtMs = Date.now()
     let targetLabel = this.flowStepTargetLabel(rawStep, stepName)
 
     let step: MaestroStep
@@ -3088,6 +3323,22 @@ 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()
+      }
+      // recording is run setup. neither clock starts until its first frame and
+      // storage capture are ready; the run total still includes that setup.
+      await onStepStart?.()
+      startedAtMs = Date.now()
       // 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 +3369,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.
@@ -3174,7 +3428,7 @@ export class SootSimBridgeFlowRunner {
         screenshotPath,
       })
     } catch (error) {
-      if (this.isOptional(step)) {
+      if (!(error instanceof CaptureSetupError) && this.isOptional(step)) {
         console.log(
           `[flow]   (optional, skipped: ${(error as Error).message.slice(0, 80)})`,
         )
@@ -3221,6 +3475,7 @@ export class SootSimBridgeFlowRunner {
     else if (step.assertVisible) await this.assertVisible(step.assertVisible)
     else if (step.assertNotVisible) await this.assertNotVisible(step.assertNotVisible)
     else if (step.inputText) await this.inputText(step.inputText)
+    else if (step.editText) await this.editText(step.editText)
     else if (step.pressKey) await this.pressKey(step.pressKey)
     else if (step.dispatchKey) await this.dispatchKey(step.dispatchKey)
     else if (step.waitFor) await this.waitFor(step.waitFor)
@@ -3337,7 +3592,7 @@ export class SootSimBridgeFlowRunner {
           }
           break
         } catch (error) {
-          if (attempt >= maxRetries) throw error
+          if (error instanceof CaptureSetupError || attempt >= maxRetries) throw error
           console.log(
             `[flow]   retry ${attempt + 1}/${maxRetries} after: ${(error as Error).message.slice(0, 120)}`,
           )
@@ -3377,6 +3632,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
@@ -3554,9 +3811,12 @@ export class SootSimBridgeFlowRunner {
       // devtools pause never interrupts a step mid-gesture.
       if (this.liveStatus) {
         await this.liveStatus.waitWhilePaused()
-        await this.liveStatus.step(i, 'running')
       }
-      const liveStartedAtMs = Date.now()
+      let liveStartedAtMs = Date.now()
+      const onStepStart = async () => {
+        await this.liveStatus?.step(i, 'running')
+        liveStartedAtMs = Date.now()
+      }
       const reportOutcome = async (failed: boolean, error?: unknown) => {
         if (!this.liveStatus) return
         // the last trace entry after runStep settles is the top-level step's
@@ -3572,7 +3832,7 @@ export class SootSimBridgeFlowRunner {
               ? 'skipped'
               : 'success',
           {
-            durationMs: Date.now() - liveStartedAtMs,
+            durationMs: traced ? last.durationMs : Date.now() - liveStartedAtMs,
             error: failed
               ? error instanceof Error
                 ? error.message.slice(0, 300)
@@ -3590,10 +3850,10 @@ export class SootSimBridgeFlowRunner {
         // outer per-step race would kill a launch that's legitimately still
         // booting. let both govern their own timing.
         if (step.runFlow || step.launchApp) {
-          await this.runStep(step, i)
+          await this.runStep(step, i, onStepStart)
         } else {
           await Promise.race([
-            this.runStep(step, i),
+            this.runStep(step, i, onStepStart),
             new Promise<never>((_, reject) =>
               setTimeout(
                 () =>