peachsim 0.1.578 → 0.1.580

package/cli/bridge-flow-runner.ts

@@ -5,9 +5,11 @@ import yaml from 'yaml'
 import { REQUIRED_IDENTICAL_FLOW_FRAMES, framesIdentical } from '../detox/proof-frame.cjs'
 import { flowTimeoutScale } from '../src/flow-timeout-scale'
 import { composeFramedScreenshot } from '../src/screenshots/frame-compose'
+import { sleep } from '../src/sleep'
 import { inspectWaitReady, waitReadyReason } from './commands/inspect/core'
 import { waitForSootsimIdle } from './commands/inspect/settling'
 import { callShellCommandWhenReady, getShellState } from './commands/inspect/shared'
+import { PERMISSION_KINDS } from './commands/permissions'
 import { saveCurrentSimId } from './current-sim'
 import { FlowLiveStatusReporter } from './flow-live-status'
 import { MaestroJsContext, scriptConditionIsTruthy } from './maestro-js'
@@ -18,9 +20,14 @@ import type { SootSimReplayTarget, SootSimTapResult } from '@peach/globals'
 import type {
   SootSimExternalAppLifecycleOptions,
   SootSimLaunchArguments,
+  SystemPermissionKind,
+  SystemPermissionStatus,
 } from '@peach/globals'
 
 const DEFAULT_TIMEOUT = 10000
+// how long maestro looks for a required assertion's element, counted from the
+// latest interaction (Orchestra lookupTimeoutMs and adjustedToLatestInteraction)
+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
@@ -28,14 +35,101 @@ const SCREEN_H = 852
 type FlowScreenshotPathMode = 'dir' | 'flow'
 type ReplayTapTarget = SootSimReplayTarget
 
+// maestro YamlElementSelector; a nested selector is a map or bare text.
 type FlowTargetSelector = {
   id?: string
   text?: string
-  index?: number
-  childOf?: { id?: string; text?: string }
+  index?: number | string
+  childOf?: FlowTargetSelector
+  width?: number
+  height?: number
+  tolerance?: number
+  traits?: string
+  enabled?: boolean
+  selected?: boolean
+  checked?: boolean
+  below?: string | FlowTargetSelector
+  above?: string | FlowTargetSelector
+  leftOf?: string | FlowTargetSelector
+  rightOf?: string | FlowTargetSelector
 }
 type FlowPointTarget = FlowTargetSelector & {
   point?: string
+  // maestro TapRepeat: `repeat` taps, each padded out to `delay` ms
+  repeat?: number
+  delay?: number
+}
+// every key maestro's YamlElementSelector parses; maestro rejects any other
+// key when it reads the flow ("Unknown Property"), so a typo never widens a
+// match into a passing assertion.
+const MAESTRO_SELECTOR_KEYS = new Set([
+  'text',
+  'id',
+  'width',
+  'height',
+  'tolerance',
+  'optional',
+  'retryTapIfNoChange',
+  'waitUntilVisible',
+  'point',
+  'start',
+  'end',
+  'below',
+  'above',
+  'leftOf',
+  'rightOf',
+  'containsChild',
+  'containsDescendants',
+  'traits',
+  'index',
+  'enabled',
+  'selected',
+  'checked',
+  'focused',
+  'repeat',
+  'delay',
+  'waitToSettleTimeoutMs',
+  'childOf',
+  'label',
+  'css',
+])
+// maestro filters the runner resolves beyond id and text
+const SELECTOR_FILTER_KEYS = [
+  'childOf',
+  'width',
+  'height',
+  'traits',
+  'enabled',
+  'selected',
+  'checked',
+  'below',
+  'above',
+  'leftOf',
+  'rightOf',
+] as const
+// maestro filters without a verified ios reading here yet: `containsChild` and
+// `containsDescendants` walk the ios accessibility hierarchy, which hides the
+// children of an accessible element; `focused` is XCUIElement.hasFocus; `css`
+// is web only.
+const UNSUPPORTED_SELECTOR_KEYS = [
+  'containsChild',
+  'containsDescendants',
+  'focused',
+  'css',
+]
+// ignoring a key widens the match, so an assertion passes that maestro fails.
+function assertSupportedSelector(selector: unknown) {
+  if (!selector || typeof selector !== 'object') return
+  const keys = Object.keys(selector)
+  const unknown = keys.filter((key) => !MAESTRO_SELECTOR_KEYS.has(key))
+  if (unknown.length > 0) throw new Error(`Unknown Property: ${unknown.join(', ')}`)
+  const unsupported = UNSUPPORTED_SELECTOR_KEYS.filter((key) => keys.includes(key))
+  if (unsupported.length > 0) {
+    throw new Error(`selector ${unsupported.join(', ')} is not supported by peach yet`)
+  }
+  for (const key of ['childOf', 'below', 'above', 'leftOf', 'rightOf']) {
+    assertSupportedSelector(Reflect.get(selector, key))
+  }
 }
 type FocusedTextInputInfo = {
   nodeId?: number | null
@@ -91,8 +185,14 @@ export interface MaestroStep {
         index?: number
         point?: string
         childOf?: { id?: string; text?: string }
+        repeat?: number
+        delay?: number
         optional?: boolean
       }
+  doubleTapOn?: NonNullable<MaestroStep['tapOn']>
+  assertTrue?: string | { condition: string; label?: string; optional?: boolean }
+  setClipboard?: string
+  pasteText?: boolean
   longPressOn?:
     | string
     | {
@@ -205,10 +305,12 @@ export interface MaestroStep {
     commands: MaestroStep[]
   }
   scrollUntilVisible?: {
-    element: string
+    element: string | FlowTargetSelector
     centerElement?: boolean
     direction?: string
     timeout?: number
+    speed?: number
+    visibilityPercentage?: number
     optional?: boolean
   }
   extendedWaitUntil?: {
@@ -242,10 +344,6 @@ export interface MaestroStep {
   onFlowComplete?: MaestroStep[]
 }
 
-function sleep(ms: number) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
 function isObjectRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value))
 }
@@ -261,6 +359,55 @@ function readBooleanKey(value: unknown, key: string): boolean {
   return value[key] === true
 }
 
+// maestro's launchApp sets the app's permissions before launching it: every
+// permission allowed unless the step names its own. names are maestro's ios
+// names; one with no simulated permission (health, homekit) changes nothing.
+const MAESTRO_PERMISSION_KINDS: Record<string, readonly SystemPermissionKind[]> = {
+  all: PERMISSION_KINDS,
+  bluetooth: ['bluetooth'],
+  calendar: ['calendars'],
+  camera: ['camera'],
+  contacts: ['contacts'],
+  faceid: ['face-id'],
+  location: ['location-when-in-use', 'location-always'],
+  medialibrary: ['media-library'],
+  microphone: ['microphone'],
+  motion: ['motion'],
+  notifications: ['notifications'],
+  photos: ['photo-library', 'photo-library-add-only'],
+  reminders: ['reminders'],
+  siri: ['siri'],
+  speech: ['speech-recognition'],
+  usertracking: ['app-tracking-transparency'],
+}
+
+const MAESTRO_PERMISSION_STATUS: Record<string, SystemPermissionStatus> = {
+  allow: 'authorized',
+  deny: 'denied',
+  unset: 'not-determined',
+}
+
+function maestroLaunchPermissions(
+  permissions: unknown,
+): Map<SystemPermissionKind, SystemPermissionStatus> {
+  const entries = isObjectRecord(permissions)
+    ? Object.entries(permissions)
+    : [['all', 'allow'] as const]
+  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()]
+    if (!status) {
+      throw new Error(`launchApp.permissions.${name} must be allow, deny, or unset`)
+    }
+    for (const kind of MAESTRO_PERMISSION_KINDS[name.toLowerCase()] ?? []) {
+      statuses.set(kind, status)
+    }
+  }
+  return statuses
+}
+
 function readRecentShellAppId(state: ShellState | null): string | null {
   if (!state) return null
   const recentApps = state.recentApps
@@ -274,12 +421,6 @@ function readRecentShellAppId(state: ShellState | null): string | null {
   return readStringKey(bindings, 'app:one') || readStringKey(bindings, 'app:two') || null
 }
 
-export function resolveFlowScreenshotPath(screenshotDir: string, name: string): string {
-  return resolveFlowScreenshotPathWithMode(screenshotDir, name, {
-    mode: 'dir',
-  })
-}
-
 function resolveProjectRelativeFlowBase(flowDir?: string): string {
   if (!flowDir) return process.cwd()
   return path.basename(flowDir) === '.maestro' ? path.dirname(flowDir) : flowDir
@@ -364,6 +505,8 @@ function normalizeBareStringStep(verb: string): MaestroStep {
       return { clearState: true }
     case 'clearKeychain':
       return { clearKeychain: true }
+    case 'pasteText':
+      return { pasteText: true }
     case 'eraseText':
       return { eraseText: 50 }
     case 'scroll':
@@ -411,6 +554,8 @@ export class SootSimBridgeFlowRunner {
   private lastRecordingDurationMs: number | null = null
   private lastRecordingFrameStats: unknown = null
   private flowTraceSteps: SootSimFlowTraceStep[] = []
+  // when the latest step that acted on the app settled
+  private lastInteractionAt = Date.now()
   // set by runStep when a step throws — lets the outer flow command
   // dump a rich per-step failure bundle (screenshot + describe.json +
   // console + network) keyed by the failing step.
@@ -616,9 +761,9 @@ export class SootSimBridgeFlowRunner {
     const record = value as Record<string, unknown>
     const direct = record.id ?? record.text ?? record.name ?? record.path
     if (typeof direct === 'string' && direct) return direct.slice(0, 80)
-    // extendedWaitUntil keeps its target under visible/notVisible, so without
-    // this the step every flow waits on renders as a bare "Wait".
-    const awaited = record.visible ?? record.notVisible
+    // extendedWaitUntil keeps its target under visible/notVisible and
+    // scrollUntilVisible under element, so without this they render bare.
+    const awaited = record.visible ?? record.notVisible ?? record.element
     if (typeof awaited === 'string' && awaited) return awaited.slice(0, 80)
     if (awaited && typeof awaited === 'object') {
       const target = awaited as Record<string, unknown>
@@ -746,13 +891,15 @@ export class SootSimBridgeFlowRunner {
   }
 
   private async findElement(opts: FlowTargetSelector) {
-    // patterns and combined selectors need the full candidate set so id and
-    // text constrain the same node. literal single selectors keep the direct lookup.
+    assertSupportedSelector(opts)
+    // id selectors, patterns and filtered selectors resolve over the full
+    // candidate set in maestro's order, so a repeated id (one per list row)
+    // means the top row. a literal text selector keeps the direct lookup.
     if (
-      opts.childOf != null ||
-      typeof opts.index === 'number' ||
-      (opts.id && opts.text) ||
-      [opts.id, opts.text].some((value) => value && /[.*+?^$()[\]{}|\\]/.test(value))
+      opts.id != null ||
+      opts.index != null ||
+      (opts.text != null && /[.*+?^$()[\]{}|\\]/.test(opts.text)) ||
+      SELECTOR_FILTER_KEYS.some((key) => opts[key] != null)
     ) {
       return this.findElementScoped(opts)
     }
@@ -786,70 +933,156 @@ export class SootSimBridgeFlowRunner {
     })()`)
   }
 
-  // maestro `index:` (nth match) and `childOf:` (match scoped to a container)
-  // resolver. queryAll returns every matching node in tree order; childOf keeps
-  // only candidates whose center sits inside the container's bounds.
+  // maestro's selector resolver (Orchestra.buildFilter over Filters.kt):
+  // id and text patterns, size, traits, enabled/selected, the relative
+  // below/above/leftOf/rightOf filters, `index:` (nth match) and `childOf:`
+  // (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 index = typeof opts.index === 'number' ? opts.index : 0
+    const needsEveryNode =
+      !opts.id ||
+      opts.childOf != null ||
+      SELECTOR_FILTER_KEYS.some((key) => opts[key] != null)
     return this.evaluate<any>(`(async () => {
       const test = window.__sootsimTest
       if (!test || !test.queryAll) return null
+      const selector = ${JSON.stringify(opts)}
+      // maestro matches the whole id or text against the selector's regex
       const compile = (value) => {
         if (!value) return null
         let pattern = null
-        try { pattern = new RegExp(value) } catch {}
+        try { pattern = new RegExp('^(?:' + value + ')$') } catch {}
         return (candidate) => typeof candidate === 'string' &&
           (candidate === value || !!pattern?.test(candidate))
       }
-      const matchesId = compile(${JSON.stringify(opts.id)})
-      const matchesText = compile(${JSON.stringify(opts.text)})
       const all = ((await test.queryAll(${JSON.stringify(
-        opts.id && !opts.childOf ? { idPattern: opts.id } : {},
+        needsEveryNode ? {} : { idPattern: opts.id },
       )})) || []).filter(
         (n) => n && n.absolutePosition && n.layout,
       )
-      let candidates = all.filter((n) =>
-        (!matchesId || matchesId(n.testID) || matchesId(n.id)) &&
-        (!matchesText || matchesText(n.text) || matchesText(n.accessibilityLabel)),
-      )
-      const literalText = candidates.filter((n) =>
-        n.text === ${JSON.stringify(opts.text)} ||
-        n.accessibilityLabel === ${JSON.stringify(opts.text)},
-      )
-      if (matchesText && literalText.length > 0) candidates = literalText
-      // prefer on-screen matches (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.
-      const onScreen = candidates.filter((n) => {
-        const cy = n.absolutePosition.y + n.layout.height / 2
-        return cy > 0 && cy < ${SCREEN_H}
-      })
-      if (onScreen.length > 0) candidates = onScreen
-      ${
-        opts.childOf
-          ? `
-      const matchesContainerId = compile(${JSON.stringify(opts.childOf.id)})
-      const matchesContainerText = compile(${JSON.stringify(opts.childOf.text)})
-      const container = all.find((n) =>
-        (!matchesContainerId || matchesContainerId(n.testID) || matchesContainerId(n.id)) &&
-        (!matchesContainerText || matchesContainerText(n.text) || matchesContainerText(n.accessibilityLabel)),
-      )
-      if (!container || !container.absolutePosition || !container.layout) return null
-      const x0 = container.absolutePosition.x
-      const y0 = container.absolutePosition.y
-      const x1 = x0 + container.layout.width
-      const y1 = y0 + container.layout.height
-      candidates = candidates.filter((n) => {
-        const cx = n.absolutePosition.x + n.layout.width / 2
-        const cy = n.absolutePosition.y + n.layout.height / 2
-        return cx >= x0 && cx <= x1 && cy >= y0 && cy <= y1
-      })`
-          : ''
-      }
-      if (${JSON.stringify(opts.index === undefined && !!opts.text && !opts.id)}) {
-        candidates.sort((a, b) => (a.text || '').length - (b.text || '').length)
-      }
-      const node = candidates[${index}]
+      // maestro reads ios frames as integer edges (AXElement.boundsString)
+      const bounds = (n) => {
+        const left = Math.trunc(n.absolutePosition.x)
+        const top = Math.trunc(n.absolutePosition.y)
+        return {
+          x: left,
+          y: top,
+          width: Math.trunc(n.absolutePosition.x + n.layout.width) - left,
+          height: Math.trunc(n.absolutePosition.y + n.layout.height) - top,
+        }
+      }
+      const painted = (n) => (n.visibleFrame?.area ?? 0) > 0
+      const byPosition = (a, b) =>
+        a.absolutePosition.y - b.absolutePosition.y ||
+        a.absolutePosition.x - b.absolutePosition.x
+      const relative = {
+        below: (n, other) => bounds(n).y > bounds(other).y,
+        above: (n, other) => bounds(n).y < bounds(other).y,
+        leftOf: (n, other) => bounds(n).x < bounds(other).x,
+        rightOf: (n, other) => bounds(n).x > bounds(other).x,
+      }
+      const traitFilters = {
+        TEXT: (n) => n.text != null,
+        SQUARE: (n) => {
+          const b = bounds(n)
+          return Math.abs(1 - b.width / b.height) < 0.03
+        },
+        LONG_TEXT: (n) => (n.text?.length ?? 0) > 200,
+      }
+      const matchAll = (raw) => {
+        const sel = typeof raw === 'string' ? { text: raw } : raw
+        const matchesId = compile(sel.id)
+        const matchesText = compile(sel.text)
+        let candidates = all.filter((n) =>
+          (!matchesId || matchesId(n.testID) || matchesId(n.id)) &&
+          (!matchesText || matchesText(n.text) || matchesText(n.accessibilityLabel)),
+        )
+        const literalText = candidates.filter((n) =>
+          n.text === sel.text || n.accessibilityLabel === sel.text,
+        )
+        if (matchesText && literalText.length > 0) candidates = literalText
+        if (sel.width != null || sel.height != null) {
+          const tolerance = sel.tolerance ?? 0
+          candidates = candidates.filter((n) => {
+            const b = bounds(n)
+            return (sel.width == null || Math.abs(b.width - sel.width) <= tolerance) &&
+              (sel.height == null || Math.abs(b.height - sel.height) <= tolerance)
+          })
+        }
+        for (const trait of sel.traits ? String(sel.traits).split(' ') : []) {
+          const filter = traitFilters[trait.replaceAll('-', '_').toUpperCase()]
+          if (!filter) throw new Error('unknown selector trait: ' + trait)
+          candidates = candidates.filter(filter)
+        }
+        // ios reports isEnabled / isSelected from the accessibility traits
+        // react native derives from accessibilityState
+        if (sel.enabled != null) {
+          candidates = candidates.filter((n) => !n.accessibilityState?.disabled === sel.enabled)
+        }
+        if (sel.selected != null) {
+          candidates = candidates.filter((n) => !!n.accessibilityState?.selected === sel.selected)
+        }
+        // maestro's ios checked: a switch whose value is "1". react native
+        // gives the switch role that trait and reports "1" from
+        // accessibilityState.checked; a checkbox role gets no trait, so ios
+        // never reads it as checked.
+        if (sel.checked != null) {
+          candidates = candidates.filter(
+            (n) =>
+              (n.accessibilityRole === 'switch' && n.accessibilityState?.checked === true) ===
+              sel.checked,
+          )
+        }
+        for (const key of Object.keys(relative)) {
+          if (sel[key] == null) continue
+          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_H}
+        })
+        if (candidates.some(painted)) candidates = candidates.filter(painted)
+        else if (onScreen.length > 0) candidates = onScreen
+        if (sel.childOf) {
+          const containers = matchAll(sel.childOf)
+          const container = containers.find(painted) ?? containers[0]
+          if (!container) return []
+          const x0 = container.absolutePosition.x
+          const y0 = container.absolutePosition.y
+          const x1 = x0 + container.layout.width
+          const y1 = y0 + container.layout.height
+          candidates = candidates.filter((n) => {
+            const cx = n.absolutePosition.x + n.layout.width / 2
+            const cy = n.absolutePosition.y + n.layout.height / 2
+            return cx >= x0 && cx <= x1 && cy >= y0 && cy <= y1
+          })
+        }
+        // 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
+        // one identifier, the first subview moved below by a transform, maestro
+        // takes the upper one). a list that renders rows in key order and
+        // places them by transform still resolves its top row.
+        candidates.sort(byPosition)
+        if (sel.index == null && sel.text && !sel.id) {
+          candidates.sort((a, b) => (a.text || '').length - (b.text || '').length)
+        }
+        return candidates
+      }
+      // maestro Filters.index: a negative index counts from the end
+      const pick = (candidates, rawIndex) => {
+        if (rawIndex == null) return candidates
+        const index = Math.trunc(Number(rawIndex))
+        const resolved = index >= 0 ? index : candidates.length + index
+        return candidates[resolved] ? [candidates[resolved]] : []
+      }
+      const node = pick(matchAll(selector), selector.index)[0]
       if (!node) return null
       return {
         nodeId: typeof node.nodeId === 'number' ? node.nodeId : null,
@@ -1062,14 +1295,30 @@ export class SootSimBridgeFlowRunner {
 
   async tapOn(target: string | FlowPointTarget) {
     const opts = typeof target === 'string' ? { text: target } : target
+    const repeat = Math.max(1, Math.trunc(opts.repeat ?? 1))
+    const repeatDelay = opts.delay !== undefined && opts.delay >= 0 ? opts.delay : 100
+    // maestro Maestro.hierarchyBasedTap with a TapRepeat: every tap is padded
+    // out to `delay` ms (a single tap waits for nothing). the first tap is
+    // already delivered at `tappedAtMs`; this delivers the rest.
+    const repeatTaps = async (tappedAtMs: number, tapAgain: () => Promise<unknown>) => {
+      if (repeat === 1) return
+      for (let i = 1; i <= repeat; i++) {
+        await sleep(Math.max(0, repeatDelay - (Date.now() - tappedAtMs)))
+        if (i === repeat) return
+        tappedAtMs = Date.now()
+        await tapAgain()
+      }
+    }
     if (opts.point) {
       const point = await this.resolveInteractionPoint(opts)
       if (!point) throw new Error(`tapOn: element not found: ${JSON.stringify(opts)}`)
-      const direct = await this.activatePressAt(point.x, point.y)
+      const tappedAtMs = Date.now()
+      const direct = repeat === 1 ? await this.activatePressAt(point.x, point.y) : null
       if (!direct?.ok) {
         await this.tap(point.x, point.y, point.target)
+        await repeatTaps(tappedAtMs, () => this.tap(point.x, point.y, point.target))
       }
-      await sleep(300)
+      await this.settleAfterInput()
       return
     }
     // auto-wait like real maestro: if the target is not mounted yet, poll
@@ -1093,10 +1342,7 @@ export class SootSimBridgeFlowRunner {
       // command uses. non-text-input taps keep the single-tap path.
       const tapInputAttempts = element.isTextInput ? 4 : 1
       for (let attempt = 0; attempt < tapInputAttempts; attempt++) {
-        const current =
-          attempt === 0
-            ? element
-            : await this.findElement({ text: opts.text, id: opts.id })
+        const current = attempt === 0 ? element : await this.findElement(opts)
         if (!current) break
         const tapTarget =
           typeof current.nodeId === 'number'
@@ -1104,15 +1350,29 @@ export class SootSimBridgeFlowRunner {
             : null
         const cx = tapTarget?.cx ?? current.absolutePosition.x + current.layout.width / 2
         const cy = tapTarget?.cy ?? current.absolutePosition.y + current.layout.height / 2
-        const hit = await this.tap(
-          cx,
-          cy,
-          this.replayTargetForElement(opts, current, tapTarget),
+        let replayTarget: ReplayTapTarget | undefined = this.replayTargetForElement(
+          opts,
+          current,
+          tapTarget,
         )
+        let tappedAtMs = Date.now()
+        let hit = await this.tap(cx, cy, replayTarget)
+        // maestro taps the element's center and whatever sits on top there
+        // takes it, as a finger would: a label under a text input's hitSlop
+        // focuses the input. name the cover, then deliver that same tap.
+        if (hit?.requestedTargetMatched === false && hit.reason === 'target-covered') {
+          console.warn(
+            `[flow]   tapOn ${JSON.stringify(opts)}: covered by ${JSON.stringify(hit.coordinateTarget)}, tapping it as maestro does`,
+          )
+          replayTarget = undefined
+          tappedAtMs = Date.now()
+          hit = await this.tap(cx, cy)
+        }
         if (hit?.requestedTargetMatched === false)
           throw new Error(`tapOn refused: ${JSON.stringify(hit)}`)
         if (hit?.hit === true) {
-          await sleep(300)
+          await repeatTaps(tappedAtMs, () => this.tap(cx, cy, replayTarget))
+          await this.settleAfterInput()
           if (!current.isTextInput) return
           // confirm focus landed on THIS text input; retry the tap if a
           // previous field still owns focus.
@@ -1124,10 +1384,14 @@ export class SootSimBridgeFlowRunner {
     }
     // fallback: bypass hit-testing by activating press handlers directly.
     // skips the cursor animation, but keeps the flow running on targets the
-    // canvas hit-test missed (e.g. clipped or zero-area hit regions).
-    const direct = await this.activatePressTarget(opts)
+    // canvas hit-test missed (e.g. clipped or zero-area hit regions). it
+    // looks up by id or text alone, so a selector that narrows further only
+    // takes it for an element its own match already found.
+    const narrowed =
+      opts.index != null || SELECTOR_FILTER_KEYS.some((key) => opts[key] != null)
+    const direct = element || !narrowed ? await this.activatePressTarget(opts) : null
     if (direct?.ok) {
-      await sleep(300)
+      await this.settleAfterInput()
       return
     }
     throw new Error(`tapOn: element not found: ${JSON.stringify(opts)}`)
@@ -1141,12 +1405,12 @@ export class SootSimBridgeFlowRunner {
     if (result?.ok === false || result?.value === false) {
       throw new Error(`longPressOn: long press missed: ${JSON.stringify(opts)}`)
     }
-    await sleep(300)
+    await this.settleAfterInput()
   }
 
   async tapAtCoords(x: number, y: number) {
     await this.tap(x, y)
-    await sleep(300)
+    await this.settleAfterInput()
   }
 
   async doubleTapAtCoords(x: number, y: number, gapMs = 80) {
@@ -1158,19 +1422,21 @@ export class SootSimBridgeFlowRunner {
         `doubleTapAtCoords failed at (${x}, ${y}): ${result?.error ?? 'double tap missed'}`,
       )
     }
-    await sleep(300)
+    await this.settleAfterInput()
   }
 
   async assertVisible(target: string | { id?: string; text?: string }) {
     const opts = typeof target === 'string' ? { text: target } : target
-    // maestro auto-retries assertions for up to 7 seconds before failing; a
-    // shorter window fails flows real maestro passes.
-    for (let attempt = 0; attempt < 35; attempt++) {
+    // maestro retries until its lookup window after the latest interaction
+    // closes, in wall time: counting attempts stretched the window with every
+    // slow query, and a shorter one fails flows real maestro passes.
+    const deadline = this.assertionDeadline()
+    do {
       if (await this.isElementVisible(opts)) {
         return
       }
       await sleep(200)
-    }
+    } while (Date.now() < deadline)
     // report the geometry rather than a guess at the cause. a zero visibleFrame
     // says the node paints nothing; it cannot on its own separate scrolled-away
     // from painted-over, so print the frame and let the reader judge. a missing
@@ -1186,14 +1452,15 @@ export class SootSimBridgeFlowRunner {
 
   async assertNotVisible(target: string | { id?: string; text?: string }) {
     const opts = typeof target === 'string' ? { text: target } : target
-    // like assertVisible, maestro waits up to 7 seconds for the element to
+    // like assertVisible, maestro waits out the same window for the element to
     // disappear rather than failing on the first visible sample.
-    for (let attempt = 0; attempt < 35; attempt++) {
+    const deadline = this.assertionDeadline()
+    do {
       if (!(await this.isElementVisible(opts))) {
         return
       }
       await sleep(200)
-    }
+    } while (Date.now() < deadline)
     const found = await this.findElement(opts)
     const where = found
       ? ` at (${Math.round(found.absolutePosition.x)},${Math.round(found.absolutePosition.y)})`
@@ -1201,6 +1468,10 @@ export class SootSimBridgeFlowRunner {
     throw new Error(`assertNotVisible: ${JSON.stringify(opts)} IS visible${where}`)
   }
 
+  private assertionDeadline(): number {
+    return this.lastInteractionAt + scaledTimeout(ASSERTION_LOOKUP_MS)
+  }
+
   // visibility is the engine's call, not a layout-bounds guess. the old test
   // here was a vertical band (`y + height > 0 && y < SCREEN_H`), so a node
   // sealed under an opaque overlay, pushed off the left or right edge, or
@@ -1378,21 +1649,22 @@ export class SootSimBridgeFlowRunner {
   }
 
   async waitFor(opts: { text?: string; id?: string; timeout?: number }) {
-    const deadline = Date.now() + scaledTimeout(opts.timeout || DEFAULT_TIMEOUT)
+    const { timeout, ...selector } = opts
+    const deadline = Date.now() + scaledTimeout(timeout || DEFAULT_TIMEOUT)
     while (Date.now() < deadline) {
-      const element = await this.findElement(opts)
+      const element = await this.findElement(selector)
       if (element) return
       await sleep(200)
     }
     // 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).
-    const final = await this.findElement(opts)
+    const final = await this.findElement(selector)
     const detail = final
       ? ` (matched node y=${Math.round(final.absolutePosition.y)} — still off-screen at deadline)`
       : ''
     throw new Error(
-      `waitFor: ${JSON.stringify(opts)} not found after ${opts.timeout || DEFAULT_TIMEOUT}ms${detail}`,
+      `waitFor: ${JSON.stringify(opts)} not found after ${timeout || DEFAULT_TIMEOUT}ms${detail}`,
     )
   }
 
@@ -1685,7 +1957,7 @@ export class SootSimBridgeFlowRunner {
     if (!result?.ok) {
       throw new Error(`drag failed: ${result?.error ?? 'drag missed'}`)
     }
-    await sleep(300)
+    await this.settleAfterInput()
   }
 
   async swipeCoords(start: string, end: string, duration = 300) {
@@ -1809,40 +2081,70 @@ export class SootSimBridgeFlowRunner {
   }
 
   async scrollUntilVisible(opts: {
-    element: string
+    element: string | FlowTargetSelector
     centerElement?: boolean
     direction?: string
     timeout?: number
+    speed?: number
+    visibilityPercentage?: number
   }) {
-    const deadline = Date.now() + (opts.timeout || 15000)
+    // as maestro's orchestra does: `element` is a selector map or bare text;
+    // the element counts once its bounds clipped to the screen cover the
+    // required share (the percentage is integer-divided by 100 there, so 100
+    // means whole and anything lower means any); otherwise swipe from the
+    // screen center toward the far edge for 1000 * (100 - speed) / 100 + 1 ms
+    // (speed 40 by default), settle, and look again until the 20 s timeout.
+    const target =
+      typeof opts.element === 'string' ? { text: opts.element } : opts.element
+    const required = Math.trunc((opts.visibilityPercentage ?? 100) / 100)
+    const duration = Math.max(
+      1,
+      Math.trunc((1000 * (100 - (opts.speed ?? 40))) / 100) + 1,
+    )
+    const deadline = Date.now() + (opts.timeout || 20000)
     const direction = opts.direction?.toUpperCase() || 'DOWN'
-    const swipeDirection =
-      direction === 'DOWN' ? 'UP' : direction === 'UP' ? 'DOWN' : direction
+    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 element = await this.findElement({ text: opts.element })
-      if (
-        element &&
-        element.absolutePosition.y >= 0 &&
-        element.absolutePosition.y + element.layout.height > 0 &&
-        element.absolutePosition.y < SCREEN_H - 50
-      ) {
-        if (opts.centerElement) {
-          const targetY = SCREEN_H / 2
-          const diff = element.absolutePosition.y - targetY
-          if (Math.abs(diff) > 100) {
-            const distance = Math.min(150, Math.abs(diff) * 0.5)
-            const endY = diff > 0 ? targetY - distance : targetY + distance
-            await this.drag(SCREEN_W / 2, targetY, SCREEN_W / 2, endY, 10, 16)
+      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 share = width * height > 0 ? (shownX * shownY) / (width * height) : 0
+        if (share >= required) {
+          if (opts.centerElement) {
+            const diff = y - centerY
+            if (Math.abs(diff) > 100) {
+              const distance = Math.min(150, Math.abs(diff) * 0.5)
+              const endY = diff > 0 ? centerY - distance : centerY + distance
+              await this.drag(centerX, centerY, centerX, endY, 10, 16)
+            }
           }
+          return
         }
-        return
       }
-      await this.swipe(swipeDirection, 250)
-      await sleep(500)
+      await this.drag(
+        centerX,
+        centerY,
+        swipeEnd.x,
+        swipeEnd.y,
+        Math.max(1, Math.round(duration / 16)),
+        16,
+      )
     }
 
-    throw new Error(`scrollUntilVisible: "${opts.element}" not found`)
+    throw new Error(`scrollUntilVisible: ${JSON.stringify(target)} not found`)
   }
 
   async extendedWaitUntil(opts: {
@@ -1956,6 +2258,7 @@ export class SootSimBridgeFlowRunner {
     }
     const wantsClear = !!(opts && typeof opts === 'object' && opts.clearState)
     const wantsResetRuntime = readBooleanKey(opts, 'resetRuntime')
+    await this.setLaunchPermissions(isObjectRecord(opts) ? opts.permissions : undefined)
 
     if (!this.firstLaunchDone) {
       this.firstLaunchDone = true
@@ -2049,6 +2352,16 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
+  private async setLaunchPermissions(permissions: unknown) {
+    const statuses = maestroLaunchPermissions(permissions)
+    const state = await getShellState(this.bridge)
+    const appId = readStringKey(state, 'activeApp') || readRecentShellAppId(state)
+    if (!appId) throw new Error('launchApp: no simulator app to set permissions for')
+    for (const [kind, status] of statuses) {
+      await this.callTest('permissionSetAppPermission', appId, kind, { status })
+    }
+  }
+
   private async rebaseEventRecorderToVideoStart(videoStartedAtMs: number) {
     try {
       await this.evaluate(
@@ -2065,6 +2378,26 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
+  // maestro waits after every input 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
+  // next command resolves its target. an app can take a few hundred ms to
+  // react to a press, so stillness must hold about half a second, and it
+  // counts painted frames because a spinner repaints without moving layout.
+  // a screen that never stops proceeds when the budget runs out, as there.
+  private async settleAfterInput() {
+    await waitForSootsimIdle({
+      bridge: this.bridge,
+      simId: this.opts.simId,
+      maxMs: 3000,
+      pollMs: 32,
+      stablePolls: 16,
+      strict: true,
+      paintStill: true,
+    })
+    this.lastInteractionAt = Date.now()
+  }
+
   private async waitForVisualSettle() {
     const result = await waitForSootsimIdle({
       bridge: this.bridge,
@@ -2175,7 +2508,9 @@ export class SootSimBridgeFlowRunner {
   // sandbox. log loudly so the author notices, then continue — matching the
   // "loud warning, not silent skip" policy in the plan.
   clearKeychain() {
-    console.warn('[flow]   clearKeychain: peach has no keychain surface — no-op (warning)')
+    console.warn(
+      '[flow]   clearKeychain: peach has no keychain surface — no-op (warning)',
+    )
   }
 
   // maestro copyTextFrom: find an element and capture its text for use in
@@ -2251,27 +2586,29 @@ export class SootSimBridgeFlowRunner {
   // `visible:` and `notVisible:` answer the same question assertVisible does,
   // so they read the engine's visibleFrame too. resolving them by mere presence
   // in the tree let a guarded step fire on a node painted over by an overlay.
+  // every key present must hold, in maestro's evaluateCondition order.
   private async evaluateWhen(when: NonNullable<MaestroStep['when']>): Promise<boolean> {
+    if (
+      when.platform !== undefined &&
+      // peach emulates iOS — match against the context's platform the way
+      // upstream compares against cachedDeviceInfo.platform. keeps
+      // cross-platform maestro flows running without stripping guards.
+      when.platform.toLowerCase() !== this.js.maestro.platform.toLowerCase()
+    ) {
+      return false
+    }
+    // the `true:` script string was template-evaluated with the step;
+    // apply upstream's falsy rules (blank/false/undefined/null/0).
+    if (when.true !== undefined && !scriptConditionIsTruthy(when.true)) return false
     if (when.visible !== undefined) {
       const opts =
         typeof when.visible === 'string' ? { text: when.visible } : when.visible
-      return this.isElementVisible(opts)
+      if (!(await this.isElementVisible(opts))) return false
     }
     if (when.notVisible !== undefined) {
       const opts =
         typeof when.notVisible === 'string' ? { text: when.notVisible } : when.notVisible
-      return !(await this.isElementVisible(opts))
-    }
-    if (when.platform !== undefined) {
-      // peach emulates iOS — match against the context's platform the way
-      // upstream compares against cachedDeviceInfo.platform. keeps
-      // cross-platform maestro flows running without stripping guards.
-      return when.platform.toLowerCase() === this.js.maestro.platform.toLowerCase()
-    }
-    if (when.true !== undefined) {
-      // the `true:` script string was template-evaluated with the step;
-      // apply upstream's falsy rules (blank/false/undefined/null/0).
-      return scriptConditionIsTruthy(when.true)
+      if (await this.isElementVisible(opts)) return false
     }
     return true
   }
@@ -2386,7 +2723,12 @@ export class SootSimBridgeFlowRunner {
         // already fails with its own reason. sharing the watchdog's 10s budget
         // meant the watchdog always won that race, reporting "bridge probably
         // hung" for a screen that was merely still animating.
-        step.takeScreenshot
+        step.takeScreenshot ||
+        // 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.
+        step.assertVisible ||
+        step.assertNotVisible
       )
       const STEP_WATCHDOG_MS = 10_000
       const body = this.runStepInner(step)
@@ -2470,7 +2812,14 @@ export class SootSimBridgeFlowRunner {
 
   private async runStepInner(step: MaestroStep) {
     if (step.tapOn) await this.tapOn(step.tapOn)
-    else if (step.longPressOn) await this.longPressOn(step.longPressOn)
+    else if (step.doubleTapOn) {
+      // maestro YamlFluentCommand: doubleTapOn is tapOn with TapRepeat(2, delay)
+      const target =
+        typeof step.doubleTapOn === 'string'
+          ? { text: step.doubleTapOn }
+          : step.doubleTapOn
+      await this.tapOn({ ...target, repeat: 2 })
+    } else if (step.longPressOn) await this.longPressOn(step.longPressOn)
     else if (step.scrollUntilVisible)
       await this.scrollUntilVisible(step.scrollUntilVisible)
     else if (step.extendedWaitUntil) await this.extendedWaitUntil(step.extendedWaitUntil)
@@ -2599,6 +2948,22 @@ export class SootSimBridgeFlowRunner {
       this.clearKeychain()
     } else if (step.copyTextFrom !== undefined) {
       await this.copyTextFrom(step.copyTextFrom)
+    } else if (step.assertTrue !== undefined) {
+      // maestro assertConditionCommand on an already-interpolated scriptCondition
+      const assertTrue =
+        typeof step.assertTrue === 'object'
+          ? step.assertTrue
+          : { condition: step.assertTrue }
+      if (!scriptConditionIsTruthy(assertTrue.condition)) {
+        throw new Error(
+          `Assertion is false: ${assertTrue.label ?? `${assertTrue.condition} is true`}`,
+        )
+      }
+    } else if (step.setClipboard !== undefined) {
+      this.js.setCopiedText(step.setClipboard)
+    } else if (step.pasteText) {
+      const copied = this.js.maestro.copiedText
+      if (copied !== null) await this.inputText(copied)
     } else if (typeof step.evalScript === 'string') {
       this.evalScript(step.evalScript)
     } else if (step.runScript) {
@@ -2718,6 +3083,7 @@ export class SootSimBridgeFlowRunner {
 
   async runFlow(steps: MaestroStep[], options: { skipPlan?: boolean } = {}) {
     const { onStart, onComplete, body } = this.extractFlowBody(steps)
+    this.lastInteractionAt = Date.now()
 
     if (!options.skipPlan && this.liveStatus) {
       await this.planFlow(steps)