peachsim 0.1.1635 → 0.1.1641

package/detox/index.ts

@@ -14,7 +14,11 @@ import {
   type ChromiumLaunchAdmission,
 } from '../../../scripts/lib/reap-browser'
 import { automateWebAuthenticationSessions } from '../../peach-engine/src/web-authentication-automation-host'
-import type { LockstepInputReceipt, SootSimLockstepFrameReceipt } from '@peach/globals'
+import type {
+  LockstepInputReceipt,
+  LockstepScheduledInput,
+  SootSimLockstepFrameReceipt,
+} from '@peach/globals'
 export { reserveChromiumAdmission } from '../../../scripts/lib/reap-browser'
 import {
   readBrowserCompositeCaptureRequest,
@@ -72,6 +76,8 @@ import type { DiscreteProofContext } from './attempt-events.cjs'
 import type { SootSimElement } from './element-types'
 import type { Browser, BrowserContext, Page } from 'playwright-core'
 
+const WORKLET_FRAME_TRACE_LIMIT = 16384
+
 type DiscreteStageFrame = {
   label: string
   offsetMs: number
@@ -127,6 +133,7 @@ let _browserLaunch: Promise<void> | null = null
 let _browserLaunchAbort: AbortController | null = null
 let _reapBrowserNow: (() => void) | null = null
 let _context: BrowserContext | null = null
+let _appStorageState: Awaited<ReturnType<BrowserContext['storageState']>> | undefined
 let _page: Page | null = null
 let _synchronizationEnabled = false
 let _proofFrameObservationActive = false
@@ -402,6 +409,7 @@ async function waitForSootsimWorkletsIdle(page: Page, timeout = 3000): Promise<v
       let readStartedAt: number | null = null
       let tenantAtRead = window.__sootsimRenderHost
       let shellAtRead = window.SootSim?.bridges?.shellHost
+      let peerProgress: import('@peach/globals').PeachPeerStatsProgress | null = null
       let deadlineTimerLateMs: number | null = null
 
       while (Date.now() < deadline) {
@@ -409,8 +417,13 @@ async function waitForSootsimWorkletsIdle(page: Page, timeout = 3000): Promise<v
         tenantAtRead = window.__sootsimRenderHost
         shellAtRead = window.SootSim?.bridges?.shellHost
         let timer: ReturnType<typeof setTimeout> | undefined
+        const peerRead = getPeerStats(false)
+        peerProgress =
+          peerRead && 'peachPeerProgress' in peerRead
+            ? (peerRead.peachPeerProgress ?? null)
+            : null
         const stats = await Promise.race([
-          getPeerStats(false),
+          peerRead,
           new Promise<undefined>((resolve) => {
             timer = setTimeout(
               () => {
@@ -459,6 +472,7 @@ async function waitForSootsimWorkletsIdle(page: Page, timeout = 3000): Promise<v
             : {
                 startedAtMs: readStartedAt - start,
                 elapsedMs: Date.now() - readStartedAt,
+                peerProgress: peerProgress ? { ...peerProgress } : null,
                 testBridgeChanged: window.__sootsimTest !== testBridge,
                 tenant: {
                   presentAtRequest: !!tenantAtRead,
@@ -484,8 +498,12 @@ async function waitForSootsimWorkletsIdle(page: Page, timeout = 3000): Promise<v
   )
   if (!result?.settled) {
     const pending = result?.pending ?? 'no peer stats reply'
-    throw new Error(
-      `sootsim worklet runtime did not settle after ${result?.elapsed ?? timeout}ms (pending=${pending}; observation=${JSON.stringify(result?.observation)})`,
+    throw await describeSootsimBridgeFailure(
+      page,
+      new Error(
+        `sootsim worklet runtime did not settle after ${result?.elapsed ?? timeout}ms (pending=${pending}; observation=${JSON.stringify(result?.observation)})`,
+      ),
+      'sootsim worklet runtime did not settle',
     )
   }
 }
@@ -553,7 +571,8 @@ async function quiesceContextMedia(context: BrowserContext): Promise<void> {
   }
 }
 
-async function closeContext() {
+async function closeContext(preserveStorage: boolean) {
+  if (!preserveStorage) _appStorageState = undefined
   if (_browserCompromised) {
     throw new Error(`sootsim browser is compromised: ${_browserCompromised}`)
   }
@@ -561,6 +580,15 @@ async function closeContext() {
   const context = _context
   const closingContextId = contextIdentity
   try {
+    // process termination clears the app runtime, while its persistent stores
+    // remain installed until launchApp({ delete: true }) requests a fresh app.
+    if (preserveStorage) {
+      _appStorageState = await withLifecycleTimeout(
+        'context.storageState()',
+        closingContextId,
+        () => context.storageState({ indexedDB: true }),
+      )
+    }
     await quiesceContextMedia(context)
     await withLifecycleTimeout('context.close()', closingContextId, () => context.close())
     _context = null
@@ -575,7 +603,8 @@ async function closeContext() {
   }
 }
 
-async function closeBrowser() {
+async function closeBrowser(preserveStorage: boolean) {
+  if (!preserveStorage) _appStorageState = undefined
   if (!_browser) return
   const browser = _browser
   const reapBrowserNow = _reapBrowserNow
@@ -585,7 +614,7 @@ async function closeBrowser() {
 
   let closeError: Error | null = null
   try {
-    await closeContext()
+    await closeContext(preserveStorage)
   } catch (error) {
     closeError = error instanceof Error ? error : new Error(String(error))
   }
@@ -897,7 +926,7 @@ async function focusElementForTextEntry(el: SootSimElement): Promise<void> {
   // would edit around a caret the tap then moves, so wait for its focus.
   await pollUntil(
     () => page.evaluate(async () => window.__sootsimTest!.getFocusedNode()),
-    (focused) => focused !== null && focusIsWithin(focused, node.nodeId),
+    (focused) => focused !== null && focusIsWithin(focused, node),
     {
       timeoutMs: 5000,
       label: `SootSim text input ${node.nodeId} to focus`,
@@ -1441,11 +1470,12 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
       normalizedStartingPointX = 0.5,
       normalizedStartingPointY = 0.5,
     ) {
+      const page = getPage()
+      if (_synchronizationEnabled) await waitForSootsimIdle(page, 3000, false, 0)
       const node = await findStableNodeByMatcher(matcher, 'swipe')
       if (!node)
         throw new Error(`element not found for swipe: ${JSON.stringify(matcher)}`)
 
-      const page = getPage()
       const { absolutePosition, layout } = node
 
       const startSootSimX = absolutePosition.x + layout.width * normalizedStartingPointX
@@ -1972,10 +2002,11 @@ export const device = {
     }
 
     if (!_page || newInstance || opts?.delete || opts?.recordVideoDir) {
-      await closeContext()
+      await closeContext(!opts?.delete)
       const contextOpts: Parameters<NonNullable<typeof _browser>['newContext']>[0] = {
         hasTouch: true,
         viewport: { width: 500, height: 900 },
+        storageState: _appStorageState,
       }
       if (opts?.recordVideoDir) {
         fs.mkdirSync(opts.recordVideoDir, { recursive: true })
@@ -2090,7 +2121,7 @@ export const device = {
   },
 
   async terminateApp() {
-    await closeBrowser()
+    await closeBrowser(true)
   },
 
   async installApp() {
@@ -2098,7 +2129,7 @@ export const device = {
   },
 
   async uninstallApp() {
-    // no-op
+    await closeBrowser(false)
   },
 
   async openURL(url: { url: string; sourceApp?: string }) {
@@ -2617,22 +2648,26 @@ export const device = {
     }>,
     options: {
       detectionTimeoutMs?: number
+      workletFrameTimestampsSeconds?: number[]
+      workletFrameTracePath?: string
       frame?: { height: number; width: number; x: number; y: number } | null
       // a pointer the capture itself presses at the trigger point and releases
       // once durationMs of lockstep time has elapsed, so held states (a lifted
       // control thumb, a pressed row) are painted mid-hold. moves drag the
       // held pointer to each point once afterMs of lockstep time has elapsed
-      // since the press, and the release lands at the last point reached.
+      // since the press. an explicit release position preserves witnessed up coordinates.
       hold?: {
         durationMs: number
-        moves?: Array<{ afterMs: number; x: number; y: number }>
+        eventDurationMs?: number
+        release?: { x: number; y: number }
+        moves?: Array<{ afterMs: number; eventAfterMs?: number; x: number; y: number }>
         x: number
         y: number
       } | null
-      // stages measure from the frame that delivers the hold's release rather
-      // than from the first visible change, the delivered touch-up anchor the
-      // native lane uses.
-      anchorAtRelease?: boolean
+      // stages measure from the hold's press ('down') or the frame that
+      // delivers its release ('up') rather than from the first visible
+      // change, the delivered touch anchor the native lane uses.
+      anchorAtTouch?: 'down' | 'up'
       rootFrame?: { height: number; width: number; x: number; y: number } | null
       settleMs?: number
       trigger?: () => unknown
@@ -2681,6 +2716,14 @@ export const device = {
       definition: MOTION_CHANGE_DEFINITION,
       installGlobal: true,
     })
+    if (options.workletFrameTracePath) {
+      await page.evaluate(async (limit) => {
+        const enable = window.SootSim?.bridges?.test?.setShellReanimatedTraceEnabled
+        if (typeof enable !== 'function')
+          throw new Error('worklet trace bridge is absent')
+        await enable(true, true, limit)
+      }, WORKLET_FRAME_TRACE_LIMIT)
+    }
     const capturePromise: Promise<{
       inputReceipts: LockstepInputReceipt[]
       anchors: Array<{
@@ -2843,82 +2886,94 @@ export const device = {
         if (input.hold && (!interact || typeof interact.touchDown !== 'function')) {
           throw new Error('peach interact bridge is not installed')
         }
-        const controller = await lockstep.begin(60)
-        // the hold's pointer goes down before the first stepped frame, so its
-        // start is one frame before the first receipt; each move and the release
-        // land on the first stepped frame at or past their time from there. the
-        // deadlines are frame indexes: comparing summed virtual timestamps
-        // against a duration lets rounding push an event past its frame.
-        const moves = input.hold?.moves ?? []
-        const holdState = {
-          nextMove: 0,
-          pressFrameIndex: null as number | null,
-          releaseReceipt: null as SootSimLockstepFrameReceipt | null,
-          released: false,
-          x: input.hold?.x ?? 0,
-          y: input.hold?.y ?? 0,
-        }
-        const holdEventFrameIndex = (afterMs: number) =>
-          (holdState.pressFrameIndex ?? 0) + controller.framesForOffset(afterMs)
-        const nextHoldEventFrameIndex = () => {
-          if (!input.hold || holdState.released || holdState.pressFrameIndex === null) {
-            return null
-          }
-          const move = moves[holdState.nextMove]
-          return holdEventFrameIndex(move ? move.afterMs : input.hold.durationMs)
-        }
-        const advanceHold = async (receipt: SootSimLockstepFrameReceipt) => {
-          if (!input.hold || !interact || holdState.released) return
-          if (holdState.pressFrameIndex === null) {
-            holdState.pressFrameIndex = receipt.frameIndex - 1
-          }
-          for (
-            let move = moves[holdState.nextMove];
-            move && receipt.frameIndex >= holdEventFrameIndex(move.afterMs);
-            move = moves[holdState.nextMove]
-          ) {
-            holdState.nextMove++
-            holdState.x = move.x
-            holdState.y = move.y
-            // event time remains on the replay clock when delivery ceilings
-            // to a display tick or several native samples share one frame.
-            await interact.touchMove(
-              move.x,
-              move.y,
-              999,
-              controller.initialFrame.virtualTimestampMs + move.afterMs,
+        const pairedPeerStats = async (reset = false) => {
+          const stats = await captureWindow.SootSim?.bridges?.test?.getPeerStats?.(reset)
+          if (!stats || !Number.isSafeInteger(stats.replayedFrameCallbacks))
+            throw new Error(
+              'paired worklets clock needs native frame delivery diagnostics',
             )
-          }
-          if (receipt.frameIndex < holdEventFrameIndex(input.hold.durationMs)) return
-          holdState.released = true
-          holdState.releaseReceipt = receipt
-          await interact.touchUp(
-            holdState.x,
-            holdState.y,
-            999,
-            controller.initialFrame.virtualTimestampMs + input.hold.durationMs,
-          )
+          return stats
         }
+        if (input.workletFrameTimestampsSeconds) await pairedPeerStats(true)
+        const controller = await lockstep.begin(60, {
+          workletFrameTimestampsSeconds: input.workletFrameTimestampsSeconds,
+        })
+        let heldInput: Promise<void> | null = null
+        const releaseReceipt = () =>
+          controller.inputReceipts.find((receipt) => receipt.phase === 'up')
         // an anchor is its visible-change frame; its bitmap is kept so a 0ms
         // stage can still capture the anchor frame itself.
-        const keptFrames = new Map<number, ImageBitmap>()
+        const keptFrames = new Map<
+          number,
+          { bitmap: ImageBitmap; receipt: SootSimLockstepFrameReceipt }
+        >()
+        const keepFrame = (receipt: SootSimLockstepFrameReceipt, bitmap: ImageBitmap) => {
+          keptFrames.get(receipt.frameIndex)?.bitmap.close()
+          keptFrames.set(receipt.frameIndex, { bitmap, receipt })
+        }
         try {
+          if (input.anchorAtTouch && !input.hold) {
+            throw new Error('peach touch anchoring needs a hold')
+          }
           const baselineBitmap = await captureBitmap()
           const baseline = regionPixels(baselineBitmap)
-          baselineBitmap.close()
+          // the press lands before the first stepped frame, so the screen it
+          // lands on is the baseline itself
+          if (input.anchorAtTouch === 'down')
+            keepFrame(controller.initialFrame, baselineBitmap)
+          else baselineBitmap.close()
+          if (
+            input.workletFrameTimestampsSeconds &&
+            (await pairedPeerStats()).replayedFrameCallbacks > 0
+          )
+            throw new Error('paired worklets callback preceded the Peach trigger')
           state.ready = true
           if (input.hold && interact) {
-            const hit = await interact.touchDown(
-              input.hold.x,
-              input.hold.y,
-              999,
-              controller.initialFrame.virtualTimestampMs,
-            )
-            if (!hit) {
-              throw new Error(
-                `peach motion hold missed at ${input.hold.x},${input.hold.y}`,
-              )
-            }
+            const hold = input.hold
+            const moves = hold.moves ?? []
+            const release = hold.release ?? moves.at(-1) ?? hold
+            const events: LockstepScheduledInput[] = [
+              {
+                phase: 'down',
+                x: hold.x,
+                y: hold.y,
+                pointerId: 999,
+                afterMs: 0,
+                async deliver(timestamp) {
+                  const hit = await interact.touchDown(hold.x, hold.y, 999, timestamp)
+                  if (!hit)
+                    throw new Error(`peach motion hold missed at ${hold.x},${hold.y}`)
+                },
+              },
+              ...moves.map(
+                (move): LockstepScheduledInput => ({
+                  phase: 'move',
+                  x: move.x,
+                  y: move.y,
+                  pointerId: 999,
+                  afterMs: move.afterMs,
+                  eventAfterMs: move.eventAfterMs,
+                  async deliver(timestamp: number) {
+                    await interact.touchMove(move.x, move.y, 999, timestamp)
+                  },
+                }),
+              ),
+              {
+                phase: 'up',
+                x: release.x,
+                y: release.y,
+                pointerId: 999,
+                afterMs: hold.durationMs,
+                eventAfterMs: hold.eventDurationMs,
+                async deliver(timestamp) {
+                  await interact.touchUp(release.x, release.y, 999, timestamp)
+                },
+              },
+            ]
+            heldInput = controller.scheduleInput(events)
+            // rendering propagates delivery errors; also observe cancellation rejection.
+            heldInput.catch(() => {})
+            await controller.flushFrame()
           } else {
             while (!state.triggerStarted) {
               if (state.cancelled) throw new Error('peach motion capture was cancelled')
@@ -2947,7 +3002,7 @@ export const device = {
             if (measurement.passedMinimum) {
               visibleStart = receipt
               detectedMeasurement = measurement
-              keptFrames.set(visibleStart.frameIndex, candidateBitmap)
+              keepFrame(visibleStart, candidateBitmap)
             } else {
               candidateBitmap.close()
             }
@@ -2956,11 +3011,14 @@ export const device = {
           for (let frame = 0; !visibleStart && frame < detectionFrameLimit; frame++) {
             if (state.cancelled) throw new Error('peach motion capture was cancelled')
             const receipt = await controller.stepFrame()
-            await advanceHold(receipt)
             const candidateBitmap = await captureBitmap()
-            // a release anchor's frame may precede the first visible change
-            if (input.anchorAtRelease && holdState.releaseReceipt === receipt) {
-              keptFrames.set(receipt.frameIndex, await createImageBitmap(candidateBitmap))
+            // a touch anchor's stages may precede the first visible change
+            if (
+              input.anchorAtTouch === 'down' ||
+              (input.anchorAtTouch === 'up' &&
+                releaseReceipt()?.frameIndex === receipt.frameIndex)
+            ) {
+              keepFrame(receipt, await createImageBitmap(candidateBitmap))
             }
             const bounds = boundsFor(candidateBitmap)
             const measurement = measureChange({
@@ -2976,8 +3034,7 @@ export const device = {
               previousBitmap = null
               visibleStart = receipt
               detectedMeasurement = measurement
-              keptFrames.get(receipt.frameIndex)?.close()
-              keptFrames.set(receipt.frameIndex, candidateBitmap)
+              keepFrame(receipt, candidateBitmap)
               break
             }
             previousBitmap?.close()
@@ -2992,27 +3049,24 @@ export const device = {
           // stages on every platform measure from the first frame that
           // differs from baseline: native extraction anchors at its
           // detection frame's pts, so the drive starts here too. the
-          // preceding tick is still baseline on both legs. a release anchor
-          // instead starts the drive at the frame that delivers the touch-up.
+          // preceding tick is still baseline on both legs. a touch anchor
+          // instead starts the drive at the press or at the frame that
+          // delivers the touch-up.
           let driveStart = visibleStart
           let currentReceipt = visibleStart
-          if (input.anchorAtRelease) {
-            if (!input.hold) {
-              throw new Error('peach release anchoring needs a hold')
-            }
-            while (!holdState.released) {
+          if (input.anchorAtTouch === 'down') driveStart = controller.initialFrame
+          if (input.anchorAtTouch === 'up') {
+            while (!releaseReceipt()) {
               if (state.cancelled) throw new Error('peach motion capture was cancelled')
               const receipt = await controller.stepFrame()
-              await advanceHold(receipt)
               currentReceipt = receipt
-              if (holdState.released) {
-                keptFrames.set(receipt.frameIndex, await captureBitmap())
-              }
+              if (releaseReceipt()) keepFrame(receipt, await captureBitmap())
             }
-            if (!holdState.releaseReceipt) {
+            const released = releaseReceipt()
+            if (!released) {
               throw new Error('peach release anchoring found no release frame')
             }
-            driveStart = holdState.releaseReceipt
+            driveStart = { ...released, tenantFrame: null }
           }
           const resolvedAnchors = new Map<string, SootSimLockstepFrameReceipt>()
           const anchorRecords: Array<{
@@ -3056,7 +3110,6 @@ export const device = {
             while (searchReceipt.virtualTimestampMs < searchStartVts) {
               if (state.cancelled) throw new Error('peach motion capture was cancelled')
               searchReceipt = await controller.stepFrame()
-              await advanceHold(searchReceipt)
             }
             currentReceipt = searchReceipt
             let anchorBitmap = await captureBitmap()
@@ -3072,7 +3125,6 @@ export const device = {
             for (let frame = 0; frame < detectionFrameLimit; frame++) {
               if (state.cancelled) throw new Error('peach motion capture was cancelled')
               const receipt = await controller.stepFrame()
-              await advanceHold(receipt)
               const candidateBitmap = await captureBitmap()
               const bounds = boundsFor(candidateBitmap)
               const candidate = regionPixels(candidateBitmap)
@@ -3109,8 +3161,7 @@ export const device = {
                 `peach motion anchor ${anchor.id} found no onset past ${onsetThresholdPercent}% within ${input.detectionTimeoutMs}ms of ${anchor.notBeforeMs}ms (pan peak ${panPeakPercent.toFixed(2)}%, later peak ${latePeakPercent.toFixed(2)}%): the gate or the search start is wrong for this surface`,
               )
             }
-            keptFrames.get(anchorReceipt.frameIndex)?.close()
-            keptFrames.set(anchorReceipt.frameIndex, anchorBitmap)
+            keepFrame(anchorReceipt, anchorBitmap)
             resolvedAnchors.set(anchor.id, anchorReceipt)
             anchorRecords.push({
               changedPixelPercent: onsetMeasurement.changePercent,
@@ -3126,33 +3177,23 @@ export const device = {
           for (const stage of input.stages) {
             if (state.cancelled) throw new Error('peach motion capture was cancelled')
             const { anchorId, receipt: anchorReceipt } = await resolveAnchor(stage)
-            // step through every hold move and the release that fall before
-            // this stage one frame at a time, so the stage paints the pointer
-            // where it belongs rather than a hold the jump skipped past.
             const stageFrameIndex =
               anchorReceipt.frameIndex + controller.framesForOffset(stage.offsetMs)
             const kept = keptFrames.get(stageFrameIndex)
             if (kept && stageFrameIndex <= currentReceipt.frameIndex) {
               snapshots.push({
-                actualMs: 0,
+                actualMs:
+                  kept.receipt.virtualTimestampMs - anchorReceipt.virtualTimestampMs,
                 anchorId,
-                bitmap: await createImageBitmap(kept),
-                frameIndex: anchorReceipt.frameIndex,
+                bitmap: await createImageBitmap(kept.bitmap),
+                frameIndex: kept.receipt.frameIndex,
                 label: stage.label,
                 offsetMs: stage.offsetMs,
-                virtualTimestampMs: anchorReceipt.virtualTimestampMs,
+                virtualTimestampMs: kept.receipt.virtualTimestampMs,
               })
               continue
             }
-            for (
-              let eventFrameIndex = nextHoldEventFrameIndex();
-              eventFrameIndex !== null && stageFrameIndex > eventFrameIndex;
-              eventFrameIndex = nextHoldEventFrameIndex()
-            ) {
-              await advanceHold(await controller.stepFrame())
-            }
             const receipt = await controller.stepToOffset(anchorReceipt, stage.offsetMs)
-            await advanceHold(receipt)
             currentReceipt = receipt
             snapshots.push({
               actualMs: receipt.virtualTimestampMs - anchorReceipt.virtualTimestampMs,
@@ -3164,15 +3205,18 @@ export const device = {
               virtualTimestampMs: receipt.virtualTimestampMs,
             })
           }
+          // the native receipt was recorded through the last stage, not the
+          // release and settle frames that follow it.
+          if (input.workletFrameTimestampsSeconds) controller.endWorkletFrameReceipt()
           // a hold that outlasts the last stage still moves and releases on its
           // own frames; the settle jump below would carry the pointer past them
           // and leave it down. the settle then runs from that release.
           let releasedOffsetMs = 0
-          while (nextHoldEventFrameIndex() !== null) {
+          while (input.hold && !releaseReceipt()) {
             const receipt = await controller.stepFrame()
-            await advanceHold(receipt)
             releasedOffsetMs = receipt.virtualTimestampMs - driveStart.virtualTimestampMs
           }
+          await heldInput
           if (input.settleMs > 0) {
             const maximumPrimaryMs = snapshots.reduce(
               (maximum, snapshot) =>
@@ -3189,6 +3233,20 @@ export const device = {
             await controller.stepFrame()
             await new Promise((resolve) => setTimeout(resolve, 0))
           }
+          if (input.workletFrameTimestampsSeconds) {
+            const stats = await pairedPeerStats()
+            const first = stats.nativeFrameFirstTimestampMs
+            const firstFrameIndex =
+              first === null
+                ? null
+                : Math.round(
+                    (first - controller.initialFrame.virtualTimestampMs) / (1000 / 60),
+                  )
+            if (firstFrameIndex !== 1)
+              throw new Error(
+                `paired worklets first delivery did not match the next UI frame: ${firstFrameIndex}`,
+              )
+          }
           return {
             inputReceipts: controller.inputReceipts,
             anchors: anchorRecords,
@@ -3209,15 +3267,16 @@ export const device = {
             },
           }
         } finally {
-          for (const bitmap of keptFrames.values()) bitmap.close()
+          for (const kept of keptFrames.values()) kept.bitmap.close()
           controller.end()
           delete registry[input.token]
         }
       },
       {
+        workletFrameTimestampsSeconds: options.workletFrameTimestampsSeconds,
         detectionTimeoutMs: options.detectionTimeoutMs ?? 3000,
         frame: options.frame ?? null,
-        anchorAtRelease: options.anchorAtRelease ?? false,
+        anchorAtTouch: options.anchorAtTouch ?? null,
         hold: options.hold ?? null,
         motionChangeDefinition: MOTION_CHANGE_DEFINITION,
         platform: device.getPlatform(),
@@ -3228,18 +3287,25 @@ export const device = {
       },
     )
 
-    await page.waitForFunction(
-      (captureToken) => {
-        const registry = window.__sootsimVisibleChangeCaptures
-        return registry?.[captureToken]?.ready === true
-      },
-      token,
-      { timeout: 5000 },
-    )
-
-    const triggerStartMs = Date.now()
+    let captureFailure: { error: unknown } | undefined
+    let triggerStartMs = 0
     let triggerCompletedMs = 0
     try {
+      await Promise.race([
+        page.waitForFunction(
+          (captureToken) => {
+            const registry = window.__sootsimVisibleChangeCaptures
+            return registry?.[captureToken]?.ready === true
+          },
+          token,
+          { timeout: 5000 },
+        ),
+        capturePromise.then(() => {
+          throw new Error('peach motion capture completed before its trigger')
+        }),
+      ])
+
+      triggerStartMs = Date.now()
       const triggerPromise = (async () => {
         if (!options.hold) {
           if (typeof options.trigger !== 'function') {
@@ -3275,6 +3341,7 @@ export const device = {
         },
       }
     } catch (error) {
+      captureFailure = { error }
       await page
         .evaluate((captureToken) => {
           const registry = window.__sootsimVisibleChangeCaptures
@@ -3284,6 +3351,59 @@ export const device = {
         .catch(() => {})
       await capturePromise.catch(() => {})
       throw error
+    } finally {
+      if (options.workletFrameTracePath) {
+        try {
+          const events = await page.evaluate(async () => {
+            const test = window.SootSim?.bridges?.test
+            const read = test?.getShellReanimatedTrace
+            const enable = test?.setShellReanimatedTraceEnabled
+            if (typeof read !== 'function' || typeof enable !== 'function')
+              throw new Error('worklet trace bridge is absent')
+            try {
+              return await read()
+            } finally {
+              await enable(false, false)
+            }
+          })
+          fs.writeFileSync(
+            options.workletFrameTracePath,
+            JSON.stringify(
+              {
+                source: 'peach-native-frame-queue',
+                limit: WORKLET_FRAME_TRACE_LIMIT,
+                events,
+              },
+              null,
+              2,
+            ),
+          )
+        } catch (traceError) {
+          if (!captureFailure) throw traceError
+          const primary = captureFailure.error
+          if (
+            primary &&
+            (typeof primary === 'object' || typeof primary === 'function') &&
+            Object.isExtensible(primary)
+          ) {
+            try {
+              Object.defineProperty(primary, 'workletFrameTraceError', {
+                value: traceError,
+                configurable: true,
+              })
+            } catch (attachmentError) {
+              console.error(
+                '[peach motion capture] could not attach trace failure:',
+                attachmentError,
+              )
+            }
+          }
+          console.error(
+            '[peach motion capture] secondary worklet trace failure:',
+            traceError,
+          )
+        }
+      }
     }
   },
 
@@ -3847,5 +3967,5 @@ export { sootsimExpect as expect, sootsimWaitFor as waitFor }
 export async function cleanup() {
   _browserLaunchAbort?.abort(new Error('Peach driver cleaned up'))
   await _browserLaunch?.catch(() => {})
-  await closeBrowser()
+  await closeBrowser(false)
 }