peachsim 0.1.1625 → 0.1.1640

package/detox/index.ts

@@ -1,8 +1,7 @@
+import { randomBytes } from 'crypto'
 // detox-compatible test driver for sootsim
 // drop-in replacement for `import { by, device, element, expect, waitFor } from 'detox'`
 // uses playwright to control a headless browser running sootsim
-
-import { randomBytes } from 'crypto'
 import * as fs from 'fs'
 import { execFile } from 'node:child_process'
 import { createRequire } from 'node:module'
@@ -14,6 +13,8 @@ import {
   reserveChromiumAdmission,
   type ChromiumLaunchAdmission,
 } from '../../../scripts/lib/reap-browser'
+import { automateWebAuthenticationSessions } from '../../peach-engine/src/web-authentication-automation-host'
+import type { LockstepInputReceipt, SootSimLockstepFrameReceipt } from '@peach/globals'
 export { reserveChromiumAdmission } from '../../../scripts/lib/reap-browser'
 import {
   readBrowserCompositeCaptureRequest,
@@ -87,10 +88,17 @@ type DiscreteObserverState = {
   finish: () => DiscreteFrameTrace
   close: () => void
 }
+type VisibleChangeCaptureState = {
+  cancelled: boolean
+  ready: boolean
+  triggerStarted: boolean
+  triggerCompleted: boolean
+}
 declare global {
   var __peachChromiumAdmission: ChromiumLaunchAdmission | undefined
   var __peachDetoxCleanup: (() => Promise<void>) | undefined
   interface Window {
+    __sootsimVisibleChangeCaptures?: Record<string, VisibleChangeCaptureState>
     __peachClassifyDiscreteFrame?: typeof classifyDiscreteFrame
     __peachDiscreteObserver?: DiscreteObserverState
   }
@@ -119,6 +127,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
@@ -378,7 +387,8 @@ export async function waitForSootsimShellReady(
 async function waitForSootsimWorkletsIdle(page: Page, timeout = 3000): Promise<void> {
   const result = await page.evaluate(
     async ({ timeout }) => {
-      const getPeerStats = window.__sootsimTest?.getPeerStats
+      const testBridge = window.__sootsimTest
+      const getPeerStats = testBridge?.getPeerStats
       if (typeof getPeerStats !== 'function') {
         return { settled: true, skipped: true }
       }
@@ -390,14 +400,30 @@ async function waitForSootsimWorkletsIdle(page: Page, timeout = 3000): Promise<v
       let lastPending: number | null | undefined = null
       let completedReads = 0
       let lastReply: string | null = null
+      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) {
+        readStartedAt = Date.now()
+        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(
-              () => resolve(undefined),
+              () => {
+                deadlineTimerLateMs = Date.now() - deadline
+                resolve(undefined)
+              },
               Math.max(0, deadline - Date.now()),
             )
           }),
@@ -405,6 +431,7 @@ async function waitForSootsimWorkletsIdle(page: Page, timeout = 3000): Promise<v
           if (timer !== undefined) clearTimeout(timer)
         })
         if (stats === undefined) break
+        readStartedAt = null
         if (stats === null) return { settled: true, elapsed: Date.now() - start }
         completedReads++
         lastReply = JSON.stringify({ elapsedMs: Date.now() - start, stats })
@@ -426,77 +453,45 @@ async function waitForSootsimWorkletsIdle(page: Page, timeout = 3000): Promise<v
       }
 
       const waited = Date.now() - start
-      // freeze the completed observations before the separate realm probes.
-      // a later reply cannot replace what the original deadline observed.
-      const observation = { completedReads, lastReply }
-      // no reply at all: ask each realm alone, and time this page's own timer,
-      // so a silent tenant, a silent shell and a starved page read differently
-      let realms: string | null = null
-      if (lastPending === null) {
-        const probe = async (bridge: unknown) => {
-          if (
-            !bridge ||
-            typeof bridge !== 'object' ||
-            !('callTestBridge' in bridge) ||
-            typeof bridge.callTestBridge !== 'function'
-          ) {
-            return { status: 'missing-bridge' }
-          }
-          const callTestBridge = bridge.callTestBridge.bind(bridge)
-          const asked = Date.now()
-          let timer: ReturnType<typeof setTimeout> | undefined
-          try {
-            return await Promise.race([
-              Promise.resolve()
-                .then(() => callTestBridge('getPeerStats', false))
-                .then(
-                  (stats) => ({
-                    status: 'answered',
-                    elapsedMs: Date.now() - asked,
-                    stats,
-                  }),
-                  (error: unknown) => ({
-                    status: 'rejected',
-                    elapsedMs: Date.now() - asked,
-                    error: error instanceof Error ? error.message : String(error),
-                  }),
-                ),
-              new Promise<{ status: 'no-reply'; elapsedMs: number }>((resolve) => {
-                timer = setTimeout(
-                  () => resolve({ status: 'no-reply', elapsedMs: Date.now() - asked }),
-                  1000,
-                )
-              }),
-            ])
-          } finally {
-            if (timer !== undefined) clearTimeout(timer)
-          }
-        }
-        const timerAsked = Date.now()
-        const [tenant, shell, pageTimerLateMs] = await Promise.all([
-          probe(window.__sootsimRenderHost),
-          probe(window.SootSim?.bridges?.shellHost),
-          sleep(0).then(() => Date.now() - timerAsked),
-        ])
-        realms = JSON.stringify({
-          phase: 'after-deadline',
-          tenant,
-          shell,
-          pageTimerLateMs,
-        })
+      // snapshot only the original read. a later request cannot explain which
+      // realm delayed this join, and an unchanged host does not prove readiness.
+      const tenantAtDeadline = window.__sootsimRenderHost
+      const shellAtDeadline = window.SootSim?.bridges?.shellHost
+      const observation = {
+        completedReads,
+        lastReply,
+        outstandingRead:
+          readStartedAt === null
+            ? null
+            : {
+                startedAtMs: readStartedAt - start,
+                elapsedMs: Date.now() - readStartedAt,
+                peerProgress: peerProgress ? { ...peerProgress } : null,
+                testBridgeChanged: window.__sootsimTest !== testBridge,
+                tenant: {
+                  presentAtRequest: !!tenantAtRead,
+                  presentAtDeadline: !!tenantAtDeadline,
+                  changed: tenantAtRead !== tenantAtDeadline,
+                },
+                shell: {
+                  presentAtRequest: !!shellAtRead,
+                  presentAtDeadline: !!shellAtDeadline,
+                  changed: shellAtRead !== shellAtDeadline,
+                },
+              },
+        deadlineTimerLateMs,
       }
       return {
         settled: false,
         elapsed: waited,
         pending: lastPending,
-        realms,
         observation,
       }
     },
     { timeout },
   )
   if (!result?.settled) {
-    const pending = result?.pending ?? `no peer stats reply; ${result?.realms}`
+    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)})`,
     )
@@ -566,7 +561,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}`)
   }
@@ -574,6 +570,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
@@ -588,7 +593,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
@@ -598,7 +604,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))
   }
@@ -851,6 +857,31 @@ async function dispatchTapAtSootsimPoint(page: Page, point: TapPoint, token?: st
             }
           }
         }
+        // detox creates the touch in the matched view's window and sends it
+        // through uiapplication, so system status-bar routing cannot take it.
+        // that window's hit test picks the receiver, so a covering view such as
+        // a box-only parent or a pointerEvents none sibling takes the press.
+        if (token) window.__sootsimAnchorTimedInput?.(token)
+        let result = await window.__sootsimTest!.activatePressAt(x, y, point.nodeId)
+        const refusal = result?.tap
+        const covering =
+          refusal &&
+          typeof refusal === 'object' &&
+          'reason' in refusal &&
+          refusal.reason === 'target-covered' &&
+          'coordinateTarget' in refusal
+            ? refusal.coordinateTarget
+            : null
+        if (covering && typeof covering === 'object' && 'nodeId' in covering) {
+          const { nodeId } = covering
+          if (typeof nodeId === 'number') {
+            result = await window.__sootsimTest!.activatePressAt(x, y, nodeId)
+          }
+        }
+        if (result?.ok !== true) {
+          throw new Error(`element tap was refused: ${JSON.stringify(result)}`)
+        }
+        return
       } else {
         ;({ x, y } = point)
       }
@@ -885,7 +916,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`,
@@ -1429,11 +1460,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
@@ -1673,18 +1705,20 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
         visible: node.layout.width > 0 && node.layout.height > 0,
         enabled: !node.accessibilityState?.disabled,
         ...node,
-        // the transformed rect when the node reports one; a node resolved
-        // without a size (x and y only) keeps its own frame
+        // native detox reads a gauge's accessibility path, which excludes
+        // the empty space below an accessory arc. keep other frame contracts.
         frame:
-          node.absolutePosition?.width !== undefined &&
-          node.absolutePosition.height !== undefined
-            ? {
-                x: node.absolutePosition.x,
-                y: node.absolutePosition.y,
-                width: node.absolutePosition.width,
-                height: node.absolutePosition.height,
-              }
-            : node.frame,
+          node.nativeType === 'ExpoUI_GaugeView' && node.accessibilityFrame
+            ? node.accessibilityFrame
+            : node.absolutePosition?.width !== undefined &&
+                node.absolutePosition.height !== undefined
+              ? {
+                  x: node.absolutePosition.x,
+                  y: node.absolutePosition.y,
+                  width: node.absolutePosition.width,
+                  height: node.absolutePosition.height,
+                }
+              : node.frame,
       })
       // detox reads an unindexed pattern that selects several elements as a list
       if (matcher.regexFlags !== undefined && matcher.index === undefined) {
@@ -1958,10 +1992,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 })
@@ -2019,6 +2054,12 @@ export const device = {
         reapOwnedBrowser()
         throw error
       }
+      await automateWebAuthenticationSessions(
+        _context!,
+        '__peachWebAuthenticationHost',
+        _page,
+        false,
+      )
       contextIdentity = newContextIdentity
     }
 
@@ -2070,7 +2111,7 @@ export const device = {
   },
 
   async terminateApp() {
-    await closeBrowser()
+    await closeBrowser(true)
   },
 
   async installApp() {
@@ -2597,12 +2638,11 @@ export const device = {
     }>,
     options: {
       detectionTimeoutMs?: number
+      workletFrameTimestampsSeconds?: number[]
       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. an external trigger
-      // that holds and releases before returning never paints a frame in
-      // between, because no lockstep frame steps while it runs. moves drag the
+      // 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.
       hold?: {
@@ -2611,11 +2651,16 @@ export const device = {
         x: number
         y: number
       } | null
+      // 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
     },
   ): Promise<{
+    inputReceipts: LockstepInputReceipt[]
     anchors: Array<{
       changedPixelPercent: number
       frameIndex: number
@@ -2659,6 +2704,7 @@ export const device = {
       installGlobal: true,
     })
     const capturePromise: Promise<{
+      inputReceipts: LockstepInputReceipt[]
       anchors: Array<{
         changedPixelPercent: number
         frameIndex: number
@@ -2686,12 +2732,6 @@ export const device = {
       }
     }> = page.evaluate(
       async (input) => {
-        type FrameReceipt = { frameIndex: number; virtualTimestampMs: number }
-        type CaptureState = {
-          cancelled: boolean
-          ready: boolean
-          triggerCompleted: boolean
-        }
         type CaptureWindow = Window & {
           __sootsimMeasureMotionChange?: (input: {
             baseline: Uint8ClampedArray
@@ -2701,7 +2741,6 @@ export const device = {
             label: string
             width: number
           }) => MotionChangeMeasurement
-          __sootsimVisibleChangeCaptures?: Record<string, CaptureState>
           SootSim?: {
             bridges?: {
               interact?: Required<
@@ -2713,19 +2752,6 @@ export const device = {
                   frameToken: number
                 }>
               }
-              lockstepCapture?: {
-                begin: (fps: number) => Promise<{
-                  readonly initialFrame: FrameReceipt
-                  flushFrame: () => Promise<FrameReceipt>
-                  stepFrame: () => Promise<FrameReceipt>
-                  framesForOffset: (offsetMs: number) => number
-                  stepToOffset: (
-                    anchor: FrameReceipt,
-                    offsetMs: number,
-                  ) => Promise<FrameReceipt>
-                  end: () => void
-                }>
-              }
             }
           }
         }
@@ -2751,9 +2777,10 @@ export const device = {
         const registry =
           captureWindow.__sootsimVisibleChangeCaptures ??
           (captureWindow.__sootsimVisibleChangeCaptures = {})
-        const state: CaptureState = {
+        const state: VisibleChangeCaptureState = {
           cancelled: false,
           ready: false,
+          triggerStarted: false,
           triggerCompleted: false,
         }
         registry[input.token] = state
@@ -2838,7 +2865,18 @@ 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)
+        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',
+            )
+          return stats
+        }
+        if (input.workletFrameTimestampsSeconds) await pairedPeerStats(true)
+        const controller = await lockstep.begin(60, {
+          workletFrameTimestampsSeconds: input.workletFrameTimestampsSeconds,
+        })
         // 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
@@ -2848,6 +2886,7 @@ export const device = {
         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,
@@ -2861,7 +2900,7 @@ export const device = {
           const move = moves[holdState.nextMove]
           return holdEventFrameIndex(move ? move.afterMs : input.hold.durationMs)
         }
-        const advanceHold = async (receipt: FrameReceipt) => {
+        const advanceHold = async (receipt: SootSimLockstepFrameReceipt) => {
           if (!input.hold || !interact || holdState.released) return
           if (holdState.pressFrameIndex === null) {
             holdState.pressFrameIndex = receipt.frameIndex - 1
@@ -2885,6 +2924,7 @@ export const device = {
           }
           if (receipt.frameIndex < holdEventFrameIndex(input.hold.durationMs)) return
           holdState.released = true
+          holdState.releaseReceipt = receipt
           await interact.touchUp(
             holdState.x,
             holdState.y,
@@ -2894,11 +2934,30 @@ export const device = {
         }
         // 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(
@@ -2913,13 +2972,13 @@ export const device = {
               )
             }
           } else {
-            while (!state.triggerCompleted) {
+            while (!state.triggerStarted) {
               if (state.cancelled) throw new Error('peach motion capture was cancelled')
               await new Promise((resolve) => setTimeout(resolve, 0))
             }
           }
 
-          let visibleStart: FrameReceipt | null = null
+          let visibleStart: SootSimLockstepFrameReceipt | null = null
           let detectedMeasurement: MotionChangeMeasurement | null = null
           let previousBitmap: ImageBitmap | null = null
           // android can publish mount layout at p=0 before a clock step.
@@ -2940,7 +2999,7 @@ export const device = {
             if (measurement.passedMinimum) {
               visibleStart = receipt
               detectedMeasurement = measurement
-              keptFrames.set(visibleStart.frameIndex, candidateBitmap)
+              keepFrame(visibleStart, candidateBitmap)
             } else {
               candidateBitmap.close()
             }
@@ -2951,6 +3010,13 @@ export const device = {
             const receipt = await controller.stepFrame()
             await advanceHold(receipt)
             const candidateBitmap = await captureBitmap()
+            // a touch anchor's stages may precede the first visible change
+            if (
+              input.anchorAtTouch === 'down' ||
+              (input.anchorAtTouch === 'up' && holdState.releaseReceipt === receipt)
+            ) {
+              keepFrame(receipt, await createImageBitmap(candidateBitmap))
+            }
             const bounds = boundsFor(candidateBitmap)
             const measurement = measureChange({
               baseline,
@@ -2965,7 +3031,7 @@ export const device = {
               previousBitmap = null
               visibleStart = receipt
               detectedMeasurement = measurement
-              keptFrames.set(receipt.frameIndex, candidateBitmap)
+              keepFrame(receipt, candidateBitmap)
               break
             }
             previousBitmap?.close()
@@ -2980,10 +3046,26 @@ 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.
-          const driveStart = visibleStart
+          // 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
-          const resolvedAnchors = new Map<string, FrameReceipt>()
+          if (input.anchorAtTouch === 'down') driveStart = controller.initialFrame
+          if (input.anchorAtTouch === 'up') {
+            while (!holdState.released) {
+              if (state.cancelled) throw new Error('peach motion capture was cancelled')
+              const receipt = await controller.stepFrame()
+              await advanceHold(receipt)
+              currentReceipt = receipt
+              if (holdState.released) keepFrame(receipt, await captureBitmap())
+            }
+            if (!holdState.releaseReceipt) {
+              throw new Error('peach release anchoring found no release frame')
+            }
+            driveStart = holdState.releaseReceipt
+          }
+          const resolvedAnchors = new Map<string, SootSimLockstepFrameReceipt>()
           const anchorRecords: Array<{
             changedPixelPercent: number
             frameIndex: number
@@ -2997,7 +3079,7 @@ export const device = {
           const resolveAnchor = async (stage: {
             label: string
             anchor?: { id: string; notBeforeMs: number; onsetThresholdPercent?: number }
-          }): Promise<{ anchorId: string; receipt: FrameReceipt }> => {
+          }): Promise<{ anchorId: string; receipt: SootSimLockstepFrameReceipt }> => {
             const anchor = stage.anchor
             if (!anchor) return { anchorId: 'transition', receipt: driveStart }
             const known = resolvedAnchors.get(anchor.id)
@@ -3078,8 +3160,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,
@@ -3103,13 +3184,14 @@ export const device = {
             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
             }
@@ -3133,6 +3215,9 @@ 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.
@@ -3153,7 +3238,27 @@ export const device = {
             )
             await controller.stepToOffset(driveStart, maximumPrimaryMs + input.settleMs)
           }
+          while (!state.triggerCompleted) {
+            if (state.cancelled) throw new Error('peach motion capture was cancelled')
+            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,
             driveStart: {
               frameIndex: driveStart.frameIndex,
@@ -3172,14 +3277,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,
+        anchorAtTouch: options.anchorAtTouch ?? null,
         hold: options.hold ?? null,
         motionChangeDefinition: MOTION_CHANGE_DEFINITION,
         platform: device.getPlatform(),
@@ -3190,47 +3297,46 @@ export const device = {
       },
     )
 
-    await page.waitForFunction(
-      (captureToken) => {
-        const registry = (
-          window as Window & {
-            __sootsimVisibleChangeCaptures?: Record<
-              string,
-              { cancelled: boolean; ready: boolean; triggerCompleted: boolean }
-            >
-          }
-        ).__sootsimVisibleChangeCaptures
-        return registry?.[captureToken]?.ready === true
-      },
-      token,
-      { timeout: 5000 },
-    )
+    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')
+      }),
+    ])
 
     const triggerStartMs = Date.now()
     let triggerCompletedMs = 0
     try {
-      if (!options.hold) {
-        if (typeof options.trigger !== 'function') {
-          throw new Error('peach motion capture needs a trigger or a hold')
-        }
-        await Promise.resolve(options.trigger())
-      }
-      triggerCompletedMs = Date.now()
-      await page.evaluate((captureToken) => {
-        const registry = (
-          window as Window & {
-            __sootsimVisibleChangeCaptures?: Record<
-              string,
-              { cancelled: boolean; ready: boolean; triggerCompleted: boolean }
-            >
+      const triggerPromise = (async () => {
+        if (!options.hold) {
+          if (typeof options.trigger !== 'function') {
+            throw new Error('peach motion capture needs a trigger or a hold')
           }
-        ).__sootsimVisibleChangeCaptures
-        const capture = registry?.[captureToken]
-        if (!capture) throw new Error('peach motion capture disarmed before trigger')
-        capture.triggerCompleted = true
-      }, token)
-      const capture = await capturePromise
+          const triggered = Promise.resolve().then(options.trigger)
+          await page.evaluate((captureToken) => {
+            const capture = window.__sootsimVisibleChangeCaptures?.[captureToken]
+            if (!capture) throw new Error('peach motion capture disarmed before trigger')
+            capture.triggerStarted = true
+          }, token)
+          await triggered
+        }
+        triggerCompletedMs = Date.now()
+        await page.evaluate((captureToken) => {
+          const capture = window.__sootsimVisibleChangeCaptures?.[captureToken]
+          if (!capture) throw new Error('peach motion capture disarmed before trigger')
+          capture.triggerCompleted = true
+        }, token)
+      })()
+      const [capture] = await Promise.all([capturePromise, triggerPromise])
       return {
+        inputReceipts: capture.inputReceipts,
         anchors: capture.anchors,
         driveStart: capture.driveStart,
         frames: writeFastScreenshotFrames(namePrefix, capture.frames),
@@ -3245,14 +3351,7 @@ export const device = {
     } catch (error) {
       await page
         .evaluate((captureToken) => {
-          const registry = (
-            window as Window & {
-              __sootsimVisibleChangeCaptures?: Record<
-                string,
-                { cancelled: boolean; ready: boolean; triggerCompleted: boolean }
-              >
-            }
-          ).__sootsimVisibleChangeCaptures
+          const registry = window.__sootsimVisibleChangeCaptures
           const capture = registry?.[captureToken]
           if (capture) capture.cancelled = true
         }, token)
@@ -3822,5 +3921,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)
 }