peachsim 0.1.1620 → 0.1.1625

package/README.md

@@ -231,6 +231,11 @@ actions discover the sim's owning world. Each world probe has one two-second
 wall deadline covering both connection and response. An inferred default port
 does not override the named sim's world.
 
+Bridge sockets use TCP keepalive so a governor-stopped browser can resume an
+in-flight render without losing its connection to an unanswered application
+ping. Command deadlines still bound stalled work; idle leases and abandoned
+sim cleanup remain separate from transport liveness.
+
 **The sim** is a browser/Electron *page* launched by a CLI driver. Inside that
 page run three workers: the **shell worker** owns device and native state, the
 **compositor worker** paints every visible CanvasKit surface, and the **tenant
@@ -279,7 +284,7 @@ therefore runs before assertions in each flow.
 | runtime delivery + Peach home | Versioned engine runtime management. The shared machinery owns manifest fetch, sha256 verification, channels, and auto-update. Peach binds it to `https://contrast.dev` and `~/.peach/runtimes/<version>`. A repo can select `runtimeVersion` without changing the machine default. | `src/runtime-delivery.ts`, `packages/contrast-runtime-delivery/`, `src/home-paths.ts`, `src/runtime-assets.ts` |
 | standalone CLI delivery | Cached stable-version checks, bounded interactive notices, and verified atomic executable replacement. | `cli/cli-update.ts`, `cli/commands/upgrade.ts`, `cli/commands/version.ts`, `src/cli-version.ts` |
 | `peachsim/vite` + `peachsim/metro` (runtime serving) | Published bundler plugins. Both serve the installed engine runtime at `/__peachsim/` from `~/.peach/runtimes/<version>` so an app's own dev server can host the sim shell; the Vite plugin can opt into a named Electron window. | `src/vite-plugin-one.ts`, `src/metro-plugin.ts`, `src/runtime-assets.ts` |
-| `sootsim()` vite resolver plugin (internal) | The large RN-resolution / native-stub vite plugin: aliases `react-native` to the engine shim, native packages to `@sootsim/compat` stubs, applies worklets/babel transforms, and instantiates `SootSimBridgeHost` in its dev server. Distinct from the published `peachsim/vite` export. | `src/vite-plugin.ts`, `src/worklets-babel.ts`, `packages/peach-compat/src/stub-manifest.ts` |
+| `sootsim()` vite resolver plugin (internal) | The large RN-resolution / native-stub vite plugin: aliases `react-native` to the engine shim, native packages to `@sootsim/compat` stubs, and applies worklets/babel transforms. Distinct from the published `peachsim/vite` export. | `src/vite-plugin.ts`, `src/worklets-babel.ts`, `packages/peach-compat/src/stub-manifest.ts` |
 | skills registry | Peach agent skills (`peach-setup`, `peach-debug`, `peach-test`, `peach-visual`, and the generated `contrast` index) installable with `peach skill`. | `skills/*.md`, `src/skills/registry.ts`, `src/skills/types.ts` |
 
 ## Getting started
@@ -510,8 +515,8 @@ a supported input; pass Peach the JavaScript bundle produced before Hermes
 compilation.
 
 If an app has unusual dependencies or fingerprint inference fails, you can
-optionally wrap your Metro configuration with `withPeach(config)`. It takes no
-options and enables two integrations:
+optionally wrap your Metro configuration with `withPeach(config)`. It enables
+two integrations:
 
 1. **Deterministic module identity:** appends Metro's exact module identity map
    as a trailing `globalThis.__sootsimModulePaths = { ... }` footer to every
@@ -521,6 +526,23 @@ options and enables two integrations:
 2. **In-browser dev shell:** serves the Peach simulator shell at `/__peachsim/` on
    the Metro dev server.
 
+Native app identity also travels in the bundle. Android permissions come only
+from a completed app manifest merger output. A sole output under
+`android/<module>/build/intermediates/merged_manifests/` is selected automatically;
+select one explicitly when multiple variants exist:
+
+```js
+module.exports = withPeach(config, {
+  androidMergedManifest:
+    'android/app/build/intermediates/merged_manifests/debug/processDebugManifest/AndroidManifest.xml',
+})
+```
+
+Without resolved merged output, Android permissions contain only the explicit
+Expo `android.permissions` set minus `android.blockedPermissions`. Defaults,
+plugins and linked library additions require completed merged output. See the
+[native identity contract](../../specs/sootsim-engine/native-app-identity.md).
+
 The URL helpers request ordinary Metro graphs: `dev=false&minify=true` for
 production and `dev=true&minify=false` for development.
 
@@ -571,6 +593,12 @@ and video recording create a new browser context; cold launches still use the
 supplied shell URL. When synchronization is enabled, URL delivery waits for
 existing work before dispatch and for navigation and painting afterward.
 
+Element taps finish viewport measurement before resolving the selected node's
+current center, visible frame, and relative offset in the browser task that
+sends the physical tap. Stillness samples do not supply later tap coordinates:
+startup layout can change while other bridge reads finish. A removed node
+rejects the action instead of reusing its old geometry.
+
 See `../../docs/migrating-from-detox.md` for details.
 
 ## Coming from Maestro
@@ -751,8 +779,10 @@ fails instead of loading empty native configuration. Bare Metro, which has no
 Expo manifest project root, uses
 the listening development process's cwd inside that same resolver. The invoking
 CLI's cwd is never an asset/config fallback. Asset wires stay on each opened
-project URL, so one daemon can serve several attached projects without sharing
-font or splash state between them.
+project URL. Font catalogs use content-addressed bridge asset references, so
+the navigation request stays bounded as the number of fonts grows. Recordings
+resolve these references before capturing the catalog and its assets. One daemon
+can serve several attached projects without sharing font or splash state.
 
 Bare iOS projects carry default Firebase options from their selected app
 target's Google services build resource when the app delegate initializes

package/cli/app-fonts.ts

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module'
 import path from 'node:path'
 import {
   encodeAppFontsWire,
+  resolveAppFontsWire,
   expoFontPathsFromPlugins,
   nativeLinkedFontSpecsFromPaths,
   metroFontSpecsFromPaths,
@@ -448,7 +449,7 @@ export async function fetchAppFontFiles(
 ): Promise<FetchedAppFont[]> {
   const out: FetchedAppFont[] = []
   const seen = new Set<string>()
-  for (const url of appFontAssetUrlsFromWire(wire)) {
+  for (const url of appFontAssetUrlsFromWire(await resolveAppFontsWire(wire, fetch))) {
     const urlhash = createHash('sha256').update(url).digest('hex')
     if (seen.has(urlhash)) continue
     seen.add(urlhash)

package/cli/bridge-flow-runner.ts

@@ -22,6 +22,10 @@ import { PERMISSION_KINDS } from './commands/permissions'
 import { saveCurrentSimId } from './current-sim'
 import { parseFlowFile } from './flow-file'
 import { FlowLiveStatusReporter } from './flow-live-status'
+import {
+  accessibilityBounds,
+  sameNativeAccessibilityShape,
+} from './maestro-accessibility'
 import { MaestroJsContext, scriptConditionIsTruthy } from './maestro-js'
 import { ensureCliRecordingEntitlement } from './recording-access'
 import type { PerformResult, PerformStep, ResetResult } from '../src/bridge-contract'
@@ -43,6 +47,23 @@ 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
+// commands Orchestra.executeCommand reports as not mutating the device, so
+// they leave the lookup window running; every other command restarts it. the
+// last four are Peach observations with no device effect.
+const NON_MUTATING_STEPS = [
+  'assertTrue',
+  'assertVisible',
+  'assertNotVisible',
+  'extendedWaitUntil',
+  'takeScreenshot',
+  'setClipboard',
+  'copyTextFrom',
+  'clearKeychain',
+  'waitFor',
+  'wait',
+  'dumpTree',
+  'assertTreeContains',
+] as const satisfies readonly (keyof MaestroStep)[]
 const FLOW_TIMEOUT_SCALE = flowTimeoutScale()
 const scaledTimeout = (ms: number) => Math.round(ms * FLOW_TIMEOUT_SCALE)
 
@@ -235,23 +256,6 @@ function accessibilityTextMatcher(
   )
 }
 
-// maestro reads ios frames as integer edges (AXElement.boundsString).
-function accessibilityBounds(node: PeachAccessibilityNode): {
-  x: number
-  y: number
-  width: number
-  height: number
-} {
-  const left = Math.trunc(node.frame.x)
-  const top = Math.trunc(node.frame.y)
-  return {
-    x: left,
-    y: top,
-    width: Math.trunc(node.frame.x + node.frame.width) - left,
-    height: Math.trunc(node.frame.y + node.frame.height) - top,
-  }
-}
-
 const ACCESSIBILITY_TRAIT_FILTERS: Record<string, AccessibilityNodePredicate> = {
   // IOSDriver sets attributes["text"] on every node, including empty text.
   TEXT: () => true,
@@ -355,7 +359,12 @@ function distinctAccessibilityNodes(
       node.children.length,
     ])
     const bucket = buckets.get(key)
-    if (bucket?.some((other) => sameNativeAccessibilityShape(node, other))) return false
+    if (
+      bucket?.some((other) =>
+        sameNativeAccessibilityShape(node, other, accessibilityBounds),
+      )
+    )
+      return false
     if (bucket) bucket.push(node)
     else buckets.set(key, [node])
     return true
@@ -371,39 +380,6 @@ function accessibilityAnchorSelector(value: unknown): FlowTargetSelector {
   return isSelectorRecord(value) ? value : {}
 }
 
-// upstream Filters.containsChild compares the resolved child TreeNode against
-// a candidate's immediate children by structural equality: the native
-// attribute map, the boolean flags, and the children, recursively. the native
-// hintText attribute is the placeholder (accessibilityHint is not a TreeNode
-// attribute), and engine identity (elementId/nodeId) plus the projection's own
-// metadata (type, role, isAccessibilityElement, state) are not part of that
-// native shape.
-function sameNativeAccessibilityShape(
-  a: PeachAccessibilityNode,
-  b: PeachAccessibilityNode,
-): boolean {
-  if (
-    (a.testID ?? '') !== (b.testID ?? '') ||
-    (a.label ?? '') !== (b.label ?? '') ||
-    (a.placeholder ?? '') !== (b.placeholder ?? '') ||
-    (a.value ?? '') !== (b.value ?? '') ||
-    a.enabled !== b.enabled ||
-    a.selected !== b.selected ||
-    a.checked !== b.checked ||
-    a.clickable !== b.clickable ||
-    (a.hasFocus ?? false) !== (b.hasFocus ?? false) ||
-    JSON.stringify(accessibilityBounds(a)) !== JSON.stringify(accessibilityBounds(b)) ||
-    a.children.length !== b.children.length
-  ) {
-    return false
-  }
-  for (const [index, child] of a.children.entries()) {
-    const other = b.children[index]
-    if (!other || !sameNativeAccessibilityShape(child, other)) return false
-  }
-  return true
-}
-
 // Filters.containsDescendants: every selector must match inside a child
 // subtree; the node itself is excluded. A selector matches a subtree node by
 // the full filter applied to that single node (Filters' `matches`), which for
@@ -490,7 +466,7 @@ function filterAccessibilityNodesIn(
     candidates = child
       ? candidates.filter((node) =>
           node.children.some((candidate) =>
-            sameNativeAccessibilityShape(candidate, child),
+            sameNativeAccessibilityShape(candidate, child, accessibilityBounds),
           ),
         )
       : []
@@ -679,6 +655,14 @@ export interface MaestroStep {
     optional?: boolean
   }
   waitForAnimationToEnd?: boolean | number | { timeout?: number }
+  advanceAnimationClock?:
+    | number
+    | number[]
+    | {
+        steps?: number | number[]
+        ms?: number | number[]
+        fps?: number
+      }
   back?: boolean
   hideKeyboard?: boolean
   launchApp?: any
@@ -1009,6 +993,8 @@ export class SootSimBridgeFlowRunner {
 
   private firstLaunchDone = false
   private appStopped = false
+  private animationClockLocked = false
+  private flowDepth = 0
   private profilingEnabled = false
   private recordingEnabled = false
   private recordingAccessChecked = false
@@ -1901,7 +1887,7 @@ export class SootSimBridgeFlowRunner {
         await this.tap(point.x, point.y, point.target)
         await repeatTaps(tappedAtMs, () => this.tap(point.x, point.y, point.target))
       }
-      await this.settleAfterInput()
+      await this.waitForAppToSettle()
       return
     }
     // auto-wait like real maestro: if the target is not mounted yet, poll
@@ -1955,7 +1941,7 @@ export class SootSimBridgeFlowRunner {
           throw new Error(`tapOn refused: ${JSON.stringify(hit)}`)
         if (hit?.hit === true) {
           await repeatTaps(tappedAtMs, () => this.tap(cx, cy, replayTarget))
-          await this.settleAfterInput()
+          await this.waitForAppToSettle()
           if (!current.isTextInput) return
           // confirm focus landed on THIS text input; retry the tap if a
           // previous field still owns focus.
@@ -1977,7 +1963,7 @@ export class SootSimBridgeFlowRunner {
           )
         : null
     if (direct?.ok) {
-      await this.settleAfterInput()
+      await this.waitForAppToSettle()
       return
     }
     throw new Error(`tapOn: element not found: ${JSON.stringify(opts)}`)
@@ -1991,12 +1977,12 @@ export class SootSimBridgeFlowRunner {
     if (result?.ok === false || result?.value === false) {
       throw new Error(`longPressOn: long press missed: ${JSON.stringify(opts)}`)
     }
-    await this.settleAfterInput()
+    await this.waitForAppToSettle()
   }
 
   async tapAtCoords(x: number, y: number) {
     await this.tap(x, y)
-    await this.settleAfterInput()
+    await this.waitForAppToSettle()
   }
 
   async doubleTapAtCoords(x: number, y: number, gapMs = 80) {
@@ -2008,7 +1994,7 @@ export class SootSimBridgeFlowRunner {
         `doubleTapAtCoords failed at (${x}, ${y}): ${result?.error ?? 'double tap missed'}`,
       )
     }
-    await this.settleAfterInput()
+    await this.waitForAppToSettle()
   }
 
   async assertVisible(target: string | { id?: string; text?: string }) {
@@ -2549,7 +2535,7 @@ export class SootSimBridgeFlowRunner {
     if (!result?.ok) {
       throw new Error(`drag failed: ${result?.error ?? 'drag missed'}`)
     }
-    await this.settleAfterInput()
+    await this.waitForAppToSettle()
   }
 
   async swipeCoords(start: string, end: string, duration = 400) {
@@ -2660,6 +2646,76 @@ export class SootSimBridgeFlowRunner {
     })
   }
 
+  // step peach's lockstep animation clock by one or more explicit millisecond
+  // deltas and hold the clock parked at the final frame so a subsequent
+  // takeScreenshot or assertion reads that exact presentation phase.
+  async advanceAnimationClock(spec: NonNullable<MaestroStep['advanceAnimationClock']>) {
+    const rawSteps =
+      typeof spec === 'number' || Array.isArray(spec) ? spec : (spec.steps ?? spec.ms)
+    const steps = (Array.isArray(rawSteps) ? rawSteps : [rawSteps]).map((value) =>
+      Number(value),
+    )
+    if (steps.length === 0 || steps.some((ms) => !Number.isFinite(ms) || ms <= 0)) {
+      throw new Error(
+        `advanceAnimationClock requires positive millisecond step(s): ${JSON.stringify(spec)}`,
+      )
+    }
+    const fps =
+      typeof spec === 'object' &&
+      !Array.isArray(spec) &&
+      typeof spec.fps === 'number' &&
+      Number.isFinite(spec.fps) &&
+      spec.fps > 0
+        ? spec.fps
+        : 60
+    const result = await this.evaluate<{
+      ok: boolean
+      error?: string
+      virtualTimestampMs?: number
+      frameIndex?: number
+    }>(
+      `(async () => {
+        const lockstep = window.SootSim?.bridges?.lockstepCapture
+        if (!lockstep || typeof lockstep.begin !== 'function') {
+          return { ok: false, error: 'lockstep capture bridge unavailable' }
+        }
+        let controller = window.__peachFlowAnimationClockController
+        if (!controller) {
+          controller = await lockstep.begin(${JSON.stringify(fps)})
+          window.__peachFlowAnimationClockController = controller
+        }
+        let receipt = controller.initialFrame
+        for (const ms of ${JSON.stringify(steps)}) {
+          receipt = await controller.stepFrame(ms)
+        }
+        return {
+          ok: true,
+          virtualTimestampMs: receipt?.virtualTimestampMs,
+          frameIndex: receipt?.frameIndex,
+        }
+      })()`,
+      60_000,
+    )
+    if (!result?.ok) {
+      throw new Error(`advanceAnimationClock failed: ${result?.error ?? 'unknown error'}`)
+    }
+    this.animationClockLocked = true
+  }
+
+  private async releaseAnimationClock() {
+    if (!this.animationClockLocked) return
+    this.animationClockLocked = false
+    await this.evaluate(`(() => {
+      const controller = window.__peachFlowAnimationClockController
+      window.__peachFlowAnimationClockController = null
+      if (controller && typeof controller.end === 'function') {
+        controller.end()
+        return
+      }
+      window.SootSim?.bridges?.lockstepCapture?.end?.()
+    })()`).catch(() => {})
+  }
+
   async back() {
     const dispatched = await this.bridge.send({
       type: 'call',
@@ -2936,14 +2992,8 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
-  // 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
-  // next command resolves its target. compare consecutive screen pixels,
-  // rather than requiring frame publications to stop for half a second:
-  // a focused input keeps repainting its native blinking caret.
-  // a screen that never stops proceeds when the budget runs out, as there,
-  // and names what kept it moving: every such step pays the whole budget.
+  // ios checks pixels for three seconds, then compares native hierarchies.
+  // the observer overlaps those reads to keep this command's existing budget.
   private async waitForAppToSettle() {
     try {
       const result = await waitForSootsimIdle({
@@ -2951,7 +3001,7 @@ export class SootSimBridgeFlowRunner {
         simId: this.opts.simId,
         maxMs: 3000,
         pollMs: 32,
-        strict: true,
+        maestro: true,
         paintStill: true,
       })
       if (!result.settled) {
@@ -2968,11 +3018,6 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
-  private async settleAfterInput() {
-    await this.waitForAppToSettle()
-    this.lastInteractionAt = Date.now()
-  }
-
   private async waitForVisualSettle() {
     const result = await waitForSootsimIdle({
       bridge: this.bridge,
@@ -2980,19 +3025,10 @@ export class SootSimBridgeFlowRunner {
       maxMs: 10_000,
       pollMs: 32,
       stablePolls: 3,
-      strict: true,
+      maestro: 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})`,
       )
@@ -3373,8 +3409,6 @@ export class SootSimBridgeFlowRunner {
           step.extendedWaitUntil ||
           step.waitFor ||
           step.scrollUntilVisible ||
-          // deep links own the same bounded guest launch and tree waits.
-          step.openLink ||
           // runScript http calls are synchronous with a 5-minute upstream
           // timeout — the 10s watchdog would kill legitimate setup scripts.
           step.runScript ||
@@ -3386,6 +3420,7 @@ export class SootSimBridgeFlowRunner {
           // 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 ||
+          step.advanceAnimationClock ||
           // 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.
@@ -3399,7 +3434,9 @@ export class SootSimBridgeFlowRunner {
       // launchApp self-governs with an internal waitForTree (120s on a
       // clearState reload): a cache-cleared reload of a heavy bundle re-fetches
       // every chunk from metro and routinely needs more than the step ceiling.
-      if (isContainer || step.launchApp) {
+      // openLink relaunches the guest through the same bounded reload and tree
+      // wait, so it governs itself the same way.
+      if (isContainer || step.launchApp || step.openLink) {
         const result = await body
         if (typeof result === 'string') screenshotPath = result
       } else {
@@ -3423,6 +3460,11 @@ export class SootSimBridgeFlowRunner {
           if (timer) clearTimeout(timer)
         }
       }
+      // Orchestra.executeCommand restarts the lookup window after every
+      // command that returns mutating; containers leave it to their children.
+      if (!isContainer && !NON_MUTATING_STEPS.some((key) => step[key] !== undefined)) {
+        this.lastInteractionAt = Date.now()
+      }
       const isAssertion = !!(
         step.assertVisible ||
         step.assertNotVisible ||
@@ -3480,6 +3522,25 @@ export class SootSimBridgeFlowRunner {
   }
 
   private async runStepInner(step: MaestroStep) {
+    if (
+      this.animationClockLocked &&
+      !step.advanceAnimationClock &&
+      !step.takeScreenshot &&
+      !step.assertVisible &&
+      !step.assertNotVisible &&
+      step.assertTrue === undefined &&
+      !step.assertTreeContains &&
+      !step.dumpTree &&
+      step.copyTextFrom === undefined &&
+      typeof step.evalScript !== 'string' &&
+      !step.runScript &&
+      step.setClipboard === undefined &&
+      !step.runFlow &&
+      !step.repeat &&
+      !step.retry
+    ) {
+      await this.releaseAnimationClock()
+    }
     if (step.tapOn) await this.tapOn(step.tapOn)
     else if (step.doubleTapOn) {
       // maestro YamlFluentCommand: doubleTapOn is tapOn with TapRepeat(2, delay)
@@ -3534,6 +3595,8 @@ export class SootSimBridgeFlowRunner {
             ? waitSpec.timeout
             : 2000,
       )
+    } else if (step.advanceAnimationClock !== undefined) {
+      await this.advanceAnimationClock(step.advanceAnimationClock)
     } else if (step.back) {
       await this.back()
     } else if (step.hideKeyboard) {
@@ -3766,41 +3829,49 @@ export class SootSimBridgeFlowRunner {
   async runFlow(steps: (MaestroStep | string)[], options: { skipPlan?: boolean } = {}) {
     const { onStart, onComplete, body } = this.extractFlowBody(steps)
     this.lastInteractionAt = Date.now()
+    this.flowDepth++
 
-    if (!options.skipPlan && this.liveStatus) {
-      await this.planFlow(steps)
-    }
+    try {
+      if (!options.skipPlan && this.liveStatus) {
+        await this.planFlow(steps)
+      }
 
-    if (onStart.length > 0) {
-      console.log(`[flow] onFlowStart (${onStart.length} steps)`)
-      for (let i = 0; i < onStart.length; i++) {
-        await this.runStep(onStart[i], i)
+      if (onStart.length > 0) {
+        console.log(`[flow] onFlowStart (${onStart.length} steps)`)
+        for (let i = 0; i < onStart.length; i++) {
+          await this.runStep(onStart[i], i)
+        }
       }
-    }
 
-    let caughtError: Error | null = null
-    try {
-      await this.runFlowBody(body)
-    } catch (err) {
-      caughtError = err instanceof Error ? err : new Error(String(err))
-    }
+      let caughtError: Error | null = null
+      try {
+        await this.runFlowBody(body)
+      } catch (err) {
+        caughtError = err instanceof Error ? err : new Error(String(err))
+      }
 
-    if (onComplete.length > 0) {
-      console.log(`[flow] onFlowComplete (${onComplete.length} steps)`)
-      for (let i = 0; i < onComplete.length; i++) {
-        try {
-          await this.runStep(onComplete[i], i)
-        } catch (hookErr) {
-          console.warn(
-            `[flow]   onFlowComplete step ${i + 1} failed: ${
-              hookErr instanceof Error ? hookErr.message : hookErr
-            }`,
-          )
+      if (onComplete.length > 0) {
+        console.log(`[flow] onFlowComplete (${onComplete.length} steps)`)
+        for (let i = 0; i < onComplete.length; i++) {
+          try {
+            await this.runStep(onComplete[i], i)
+          } catch (hookErr) {
+            console.warn(
+              `[flow]   onFlowComplete step ${i + 1} failed: ${
+                hookErr instanceof Error ? hookErr.message : hookErr
+              }`,
+            )
+          }
         }
       }
-    }
 
-    if (caughtError) throw caughtError
+      if (caughtError) throw caughtError
+    } finally {
+      this.flowDepth = Math.max(0, this.flowDepth - 1)
+      if (this.flowDepth === 0) {
+        await this.releaseAnimationClock()
+      }
+    }
   }
 
   private async runFlowBody(steps: MaestroStep[]) {