peachsim 0.1.577 → 0.1.579

package/detox/index.ts

@@ -11,6 +11,7 @@ import {
   resolveBrowserCompositeCdpClip,
 } from '../../peach-engine/src/capture/browser-composite'
 import { isAppBootTargetUrl } from '../../peach-engine/src/render-worker/app-load'
+import { SOOTSIM_SHELL_COMMAND_NAME } from '../src/menu'
 import { pollUntil } from '../src/poll-until'
 import {
   createExpect,
@@ -20,6 +21,7 @@ import {
 } from './expectations'
 import {
   dispatchTwoFingerGesture,
+  DETOX_PLATFORM,
   dragScrollNode,
   readSootsimInteractiveViewport,
   readSootsimViewport,
@@ -46,8 +48,6 @@ const BASE_URL = process.env.PEACH_URL || 'http://localhost:5173'
 const SCREENSHOT_DIR =
   process.env.PEACH_SCREENSHOT_DIR ||
   path.join(process.cwd(), 'test', 'detox-driver', 'screenshots')
-const DETOX_PLATFORM =
-  process.env.PEACH_PLATFORM === 'android' ? ('android' as const) : ('ios' as const)
 
 // shared state -- playwright page and browser
 let _browser: Browser | null = null
@@ -187,116 +187,117 @@ export async function waitForSootsimShellReady(
   // the compositor and shellHost.firstContentPainted never settles. classify
   // with the engine's own boot-target predicate — the same one the shell
   // worker and SootSimCanvas agree on — and await the matching boundary:
-  // shell first paint for home boots, the latched boot-stage painted
-  // receipt (stamped once tenant, shell, and compositor all present) for
+  // shell first paint for home boots, compositor app-surface first paint for
   // app boots.
   // exported for the focused regression test.
   const expectsInitialAppPaint = isAppBootTargetUrl(page.url())
   try {
-    await page.evaluate(async ({ timeoutMs, expectsInitialAppPaint }) => {
-      type ShellHostReadyBridge = {
-        ready?: Promise<unknown>
-        firstContentPainted?: Promise<unknown>
-      }
+    await page.evaluate(
+      async ({ timeoutMs, expectsInitialAppPaint }) => {
+        type ShellHostReadyBridge = {
+          ready?: Promise<unknown>
+          firstContentPainted?: Promise<unknown>
+        }
 
-      const start = Date.now()
-      const deadline = start + timeoutMs
-      const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
-      const remaining = () => Math.max(1, deadline - Date.now())
-      const withTimeout = async <T>(label: string, promise: Promise<T>) => {
-        let timer: ReturnType<typeof setTimeout> | null = null
-        try {
-          await Promise.race([
-            promise,
-            new Promise((_, reject) => {
-              timer = setTimeout(
-                () => reject(new Error(`${label} timed out after ${timeoutMs}ms`)),
-                remaining(),
-              )
-            }),
-          ])
-        } finally {
-          if (timer) clearTimeout(timer)
+        let deadline = Date.now() + timeoutMs
+        const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+        const remaining = () => Math.max(1, deadline - Date.now())
+        const withTimeout = async <T>(label: string, promise: Promise<T>) => {
+          let timer: ReturnType<typeof setTimeout> | null = null
+          try {
+            await Promise.race([
+              promise,
+              new Promise((_, reject) => {
+                timer = setTimeout(
+                  () => reject(new Error(`${label} timed out after ${timeoutMs}ms`)),
+                  remaining(),
+                )
+              }),
+            ])
+          } finally {
+            if (timer) clearTimeout(timer)
+          }
         }
-      }
 
-      const isTenantOnly =
-        new URL(window.location.href).searchParams.get('renderMode') === 'tenant-only'
-      let shellHost: ShellHostReadyBridge | null = null
-      while (Date.now() < deadline) {
-        const candidate = (window as any).SootSim?.bridges?.shellHost
-        if (candidate || isTenantOnly) {
-          shellHost = candidate ?? null
-          break
+        const isTenantOnly =
+          new URL(window.location.href).searchParams.get('renderMode') === 'tenant-only'
+        let shellHost: ShellHostReadyBridge | null = null
+        while (Date.now() < deadline) {
+          const candidate = (window as any).SootSim?.bridges?.shellHost
+          if (candidate || isTenantOnly) {
+            shellHost = candidate ?? null
+            break
+          }
+          await sleep(25)
         }
-        await sleep(25)
-      }
 
-      if (!shellHost) {
-        if (isTenantOnly) return
-        throw new Error(`sootsim shell host unavailable after ${timeoutMs}ms`)
-      }
+        if (!shellHost) {
+          if (isTenantOnly) return
+          throw new Error(`sootsim shell host unavailable after ${timeoutMs}ms`)
+        }
 
-      if (shellHost.ready && typeof shellHost.ready.then === 'function') {
-        await withTimeout('sootsim shell ready', shellHost.ready)
-      }
-      // the tenant restarts into its matching worker artifact when a bundle's
-      // actual mode differs from the booted one (production bundle, no url
-      // mode params), and any in-flight tenant call then rejects with
-      // 'render host disposed'. the receipt poll below is restart-immune
-      // (pure dom read), but the transitions drain is a tenant call, so run
-      // the paint boundary plus drain together and re-run them when a
-      // restart lands mid-sequence. paint timeouts and transition timeouts
-      // are genuine failures and are never retried.
-      const isRenderHostDisposed = (error: unknown): boolean =>
-        error instanceof Error && error.message.includes('render host disposed')
-      for (;;) {
-        try {
-          if (expectsInitialAppPaint) {
-            while (Date.now() < deadline) {
-              if (
-                document.documentElement.dataset.sootsimBootStage === 'painted'
-              ) {
-                break
-              }
-              await sleep(50)
-            }
-            if (document.documentElement.dataset.sootsimBootStage !== 'painted') {
-              throw new Error(
-                `sootsim app first content paint timed out after ${timeoutMs}ms`,
-              )
-            }
-          } else if (
-            shellHost.firstContentPainted &&
-            typeof shellHost.firstContentPainted.then === 'function'
-          ) {
-            await withTimeout(
-              'sootsim shell first content paint',
-              shellHost.firstContentPainted,
-            )
+        if (shellHost.ready && typeof shellHost.ready.then === 'function') {
+          await withTimeout('sootsim shell ready', shellHost.ready)
+        }
+        // the shell's boot-stage receipt can advance on an auxiliary paint.
+        // the compositor promise resolves only when app:one has actually
+        // painted. the enclosing jest test bounds a genuinely hung boot.
+        if (expectsInitialAppPaint) {
+          const compositorHost: { firstContentPainted?: Promise<unknown> } | undefined =
+            Reflect.get(window, '__sootsimCompositor')
+          if (typeof compositorHost?.firstContentPainted?.then !== 'function') {
+            throw new Error('sootsim app compositor unavailable at boot')
           }
+          await compositorHost.firstContentPainted
+          deadline = Date.now() + 3000
+        }
 
-          const waitForScreenTransitions = (window as any).__sootsimTest
-            ?.waitForScreenTransitions
-          if (typeof waitForScreenTransitions === 'function') {
-            const transitionResult = await waitForScreenTransitions({
-              timeoutMs: Math.min(remaining(), 3000),
-              settleMs: 64,
-              startWindowMs: 700,
-            })
-            if (transitionResult?.timedOut === true) {
-              throw new Error(
-                `sootsim app launch transitions timed out: ${JSON.stringify(transitionResult)}`,
+        // the tenant restarts into its matching worker artifact when a bundle's
+        // actual mode differs from the booted one (production bundle, no url
+        // mode params), and any in-flight tenant call then rejects with
+        // 'render host disposed'. the compositor paint promise is stable
+        // across tenant restarts, but the transitions drain is a tenant call,
+        // so run the drain after paint and re-run it when a
+        // restart lands mid-sequence. transition timeouts are genuine failures
+        // and are never retried.
+        const isRenderHostDisposed = (error: unknown): boolean =>
+          error instanceof Error && error.message.includes('render host disposed')
+        for (;;) {
+          try {
+            if (
+              !expectsInitialAppPaint &&
+              shellHost.firstContentPainted &&
+              typeof shellHost.firstContentPainted.then === 'function'
+            ) {
+              await withTimeout(
+                'sootsim shell first content paint',
+                shellHost.firstContentPainted,
               )
             }
+
+            const waitForScreenTransitions = (window as any).__sootsimTest
+              ?.waitForScreenTransitions
+            if (typeof waitForScreenTransitions === 'function') {
+              const transitionResult = await waitForScreenTransitions({
+                timeoutMs: Math.min(remaining(), 3000),
+                settleMs: 64,
+                startWindowMs: 700,
+              })
+              if (transitionResult?.timedOut === true) {
+                throw new Error(
+                  `sootsim app launch transitions timed out: ${JSON.stringify(transitionResult)}`,
+                )
+              }
+            }
+            break
+          } catch (error) {
+            if (!isRenderHostDisposed(error) || Date.now() >= deadline) throw error
+            await sleep(100)
           }
-          break
-        } catch (error) {
-          if (!isRenderHostDisposed(error) || Date.now() >= deadline) throw error
-          await sleep(100)
         }
-      }
-    }, { timeoutMs: timeout, expectsInitialAppPaint })
+      },
+      { timeoutMs: timeout, expectsInitialAppPaint },
+    )
   } catch (error) {
     throw await describeSootsimBridgeFailure(page, error)
   }
@@ -697,7 +698,7 @@ async function dispatchTapAtSootsimPoint(page: Page, x: number, y: number) {
 
 async function isFocusedTextInputNode(page: Page, nodeInfo: any): Promise<boolean> {
   const focused = await page.evaluate(
-    () => window.__sootsimTest!.getFocusedNode?.() ?? null,
+    async () => (await window.__sootsimTest!.getFocusedNode?.()) ?? null,
   )
   return !!focused && typeof focused === 'object' && focused.nodeId === nodeInfo?.nodeId
 }
@@ -710,7 +711,17 @@ async function focusElementForTextEntry(el: SootSimElement): Promise<void> {
   }
   if (await isFocusedTextInputNode(page, node)) return
   await el.tap()
-  await page.waitForTimeout(100)
+  // the tap reaches the worker on its own channel. keys pressed before it lands
+  // would edit around a caret the tap then moves, so wait for its focus.
+  await pollUntil(
+    () =>
+      page.evaluate(async () => (await window.__sootsimTest!.getFocusedNode?.())?.nodeId ?? null),
+    (focusedNodeId) => focusedNodeId === node.nodeId,
+    {
+      timeoutMs: 5000,
+      label: `SootSim text input ${node.nodeId} to focus`,
+    },
+  )
 }
 
 function ensureScreenshotDir() {
@@ -851,6 +862,31 @@ async function dispatchStatusBarOverride(config: StatusBarConfig) {
   await page.waitForTimeout(50)
 }
 
+// rotate the simulated device through the same shell command the rotate
+// control dispatches, so a conformance rotation runs the engine's own
+// orientation switch and geometry republish rather than a driver-side resize.
+// detox's ios server requests UIInterfaceOrientationMask.landscapeRight for
+// 'landscape' (DetoxManager.swift setOrientation), so ios turns to landscape
+// right; android keeps the engine's default landscape.
+async function dispatchDeviceOrientation(orientation: 'portrait' | 'landscape') {
+  const page = getPage()
+  await page.evaluate(
+    ({ eventType, next, landscapeSide }) => {
+      window.dispatchEvent(
+        new CustomEvent(eventType, {
+          detail: { type: 'set-device-orientation', orientation: next, landscapeSide },
+        }),
+      )
+    },
+    {
+      eventType: SOOTSIM_SHELL_COMMAND_NAME,
+      next: orientation,
+      landscapeSide: DETOX_PLATFORM === 'ios' ? 'right' : 'left',
+    },
+  )
+  await page.waitForTimeout(50)
+}
+
 const MAX_SETTLED_SPEED_PT_PER_SEC = 2.0
 
 async function waitForFrameClock(page: Page, minMs = 25): Promise<void> {
@@ -1035,10 +1071,7 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
           if (typeof longPress !== 'function') {
             throw new Error('sootsim longPress bridge is not installed')
           }
-          const hit = await longPress(x, y, duration)
-          if (!hit) {
-            throw new Error(`sootsim longPress missed at ${x},${y}`)
-          }
+          await longPress(x, y, duration)
         },
         { duration, x: target.x, y: target.y },
       )
@@ -1083,19 +1116,31 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
 
       const startPage = await sootsimToPage(page, startSootSimX, startSootSimY)
       const endPage = await sootsimToPage(page, endSootSimX, endSootSimY)
-      const steps = speed === 'slow' ? 20 : 10
+      // Detox's dtx_longPressAtPoint:...thenDragToElement: presses for
+      // `duration`, then moves one point per display frame at its pan
+      // velocity (25pt per event, times 0.1 slow or 0.5 fast), adds one more
+      // point past the end at the same pace, holds `holdDuration` before that
+      // last point and lifts there
+      const pace = 25 * (speed === 'slow' ? 0.1 : 0.5)
+      const steps = Math.max(
+        1,
+        Math.round(
+          Math.max(
+            Math.abs(endSootSimX - startSootSimX),
+            Math.abs(endSootSimY - startSootSimY),
+          ) / pace,
+        ),
+      )
+      const frameMs = 1000 / 60
 
-      // press at start position
       await page.mouse.move(startPage.x, startPage.y)
       await page.mouse.down()
-      await page.waitForTimeout(Math.max(duration, holdDuration))
-
-      // drag to end position
+      await page.waitForTimeout(duration)
       const dx = (endPage.x - startPage.x) / steps
       const dy = (endPage.y - startPage.y) / steps
-      for (let i = 1; i <= steps; i++) {
+      for (let i = 1; i <= steps + 1; i++) {
+        await page.waitForTimeout(i === steps + 1 ? holdDuration : frameMs)
         await page.mouse.move(startPage.x + dx * i, startPage.y + dy * i)
-        await page.waitForTimeout(speed === 'slow' ? 30 : 10)
       }
 
       await page.mouse.up()
@@ -1127,6 +1172,8 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
         if (replaced === true) return
       }
       await focusElementForTextEntry(el)
+      // detox replaces the whole value wherever the focusing tap left the caret
+      await page.keyboard.press('End')
       const value = typeof node?.text === 'string' ? node.text : ''
       for (let i = 0; i < value.length; i++) {
         await page.keyboard.press('Backspace')
@@ -1137,6 +1184,7 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
     async clearText() {
       const page = getPage()
       await focusElementForTextEntry(el)
+      await page.keyboard.press('End')
       const node = await findNodeByMatcher(matcher)
       const value = typeof node?.text === 'string' ? node.text : ''
       for (let i = 0; i < value.length; i++) {
@@ -1428,10 +1476,10 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
 
     async rotate(radians: number, speed: 'fast' | 'slow' = 'fast') {
       // two fingers held on a horizontal axis around the node center, then
-      // both rotated to `radians` around the same center. positive radians
-      // rotate counter-clockwise to match RNGH RotationGesture's reported
-      // sign (its 'rotation' delta is positive for a counter-clockwise
-      // motion of the rear finger relative to the front finger).
+      // both rotated to `radians` around the same center. on a y-down
+      // screen positive radians drive the left finger up and the right
+      // finger down, which is clockwise, so RNGH reports a positive
+      // 'rotation' delta (clockwise reads positive on both natives).
       const page = getPage()
       const node = await findStableNodeByMatcher(matcher, 'rotate')
       if (!node)
@@ -1814,7 +1862,11 @@ export const device = {
   // at or after an offset, so both sides use the same rounding convention.
   async takeScreenshotStagesFromVisibleChangeFast(
     namePrefix: string,
-    stages: Array<{ label: string; offsetMs: number }>,
+    stages: Array<{
+      label: string
+      offsetMs: number
+      anchor?: { id: string; notBeforeMs: number; onsetThresholdPercent?: number }
+    }>,
     options: {
       detectionTimeoutMs?: number
       frame?: { height: number; width: number; x: number; y: number } | null
@@ -1836,10 +1888,19 @@ export const device = {
       trigger?: () => unknown
     },
   ): Promise<{
+    anchors: Array<{
+      changedPixelPercent: number
+      frameIndex: number
+      id: string
+      notBeforeMs: number
+      virtualTimestampMs: number
+    }>
+    driveStart: { frameIndex: number; virtualTimestampMs: number }
     frames: Array<{
       label: string
       offsetMs: number
       actualMs: number
+      anchorId: string
       path: string
       frameIndex: number
       virtualTimestampMs: number
@@ -1870,8 +1931,17 @@ export const device = {
       installGlobal: true,
     })
     const capturePromise: Promise<{
+      anchors: Array<{
+        changedPixelPercent: number
+        frameIndex: number
+        id: string
+        notBeforeMs: number
+        virtualTimestampMs: number
+      }>
+      driveStart: { frameIndex: number; virtualTimestampMs: number }
       frames: Array<
         FastScreenshotData & {
+          anchorId: string
           frameIndex: number
           virtualTimestampMs: number
         }
@@ -1932,6 +2002,7 @@ export const device = {
         }
         type Snapshot = {
           actualMs: number
+          anchorId: string
           bitmap: ImageBitmap
           label: string
           offsetMs: number
@@ -2025,6 +2096,7 @@ export const device = {
           snapshot.bitmap.close()
           return {
             actualMs: snapshot.actualMs,
+            anchorId: snapshot.anchorId,
             dataUrl: canvas.toDataURL('image/png'),
             label: snapshot.label,
             offsetMs: snapshot.offsetMs,
@@ -2080,6 +2152,10 @@ export const device = {
           holdState.released = true
           await interact.touchUp(holdState.x, holdState.y)
         }
+        // an anchor is the frame before its visible change, which the detector
+        // has already stepped past; its bitmap is kept so a 0ms stage can still
+        // capture the anchor frame itself.
+        const keptFrames = new Map<number, ImageBitmap>()
         try {
           const baselineBitmap = await captureBitmap()
           const baseline = regionPixels(baselineBitmap)
@@ -2088,7 +2164,9 @@ export const device = {
           if (input.hold && interact) {
             const hit = await interact.touchDown(input.hold.x, input.hold.y)
             if (!hit) {
-              throw new Error(`peach motion hold missed at ${input.hold.x},${input.hold.y}`)
+              throw new Error(
+                `peach motion hold missed at ${input.hold.x},${input.hold.y}`,
+              )
             }
           } else {
             while (!state.triggerCompleted) {
@@ -2099,6 +2177,8 @@ export const device = {
 
           let visibleStart: FrameReceipt | null = null
           let detectedMeasurement: MotionChangeMeasurement | null = null
+          let previousReceipt: FrameReceipt | null = null
+          let previousBitmap: ImageBitmap | null = null
           const detectionFrameLimit = Math.ceil((input.detectionTimeoutMs * 60) / 1000)
           for (let frame = 0; frame < detectionFrameLimit; frame++) {
             if (state.cancelled) throw new Error('peach motion capture was cancelled')
@@ -2114,27 +2194,165 @@ export const device = {
               label: 'SootSim visible-change detector',
               width: bounds.width,
             })
-            candidateBitmap.close()
             if (measurement.passedMinimum) {
+              candidateBitmap.close()
               visibleStart = receipt
               detectedMeasurement = measurement
               break
             }
+            previousBitmap?.close()
+            previousBitmap = candidateBitmap
+            previousReceipt = receipt
+          }
+          if (previousReceipt && previousBitmap) {
+            keptFrames.set(previousReceipt.frameIndex, previousBitmap)
           }
           if (!visibleStart || !detectedMeasurement) {
             throw new Error(
               `peach motion had no visible change before ${input.detectionTimeoutMs}ms`,
             )
           }
+          // the drive started on the tick the tap landed, which renders no
+          // visible change: the transition opens at p=0 with the snapshot
+          // identical to the source view still underneath it, so the gate
+          // cannot trip before the morph's first tick. stages measure from
+          // that tap tick (or the change itself when the first stepped frame
+          // already moves). native's tap tick trips the gate on the touch
+          // highlight, so its onset frame is the same event tick: same
+          // event, per-leg rule, not same gate side.
+          const driveStart = previousReceipt ?? visibleStart
+          let currentReceipt = visibleStart
+          const resolvedAnchors = new Map<string, FrameReceipt>()
+          const anchorRecords: Array<{
+            changedPixelPercent: number
+            frameIndex: number
+            id: string
+            notBeforeMs: number
+            virtualTimestampMs: number
+          }> = []
+          // a second drive (the pop after a swipe's pan) re-detects from the
+          // search start: the release tick renders no change (the phase flip
+          // lands the frame after), so the new drive is the tick before the
+          // first consecutive pair past the gate, mirroring the drive rule.
+          const resolveAnchor = async (stage: {
+            label: string
+            anchor?: { id: string; notBeforeMs: number; onsetThresholdPercent?: number }
+          }): Promise<{ anchorId: string; receipt: FrameReceipt }> => {
+            const anchor = stage.anchor
+            if (!anchor) return { anchorId: 'transition', receipt: driveStart }
+            const known = resolvedAnchors.get(anchor.id)
+            if (known) return { anchorId: anchor.id, receipt: known }
+            if (
+              typeof anchor.notBeforeMs !== 'number' ||
+              !Number.isFinite(anchor.notBeforeMs) ||
+              anchor.notBeforeMs < 0
+            ) {
+              throw new Error(
+                `peach motion stage ${stage.label} anchor ${anchor.id} needs a non-negative notBeforeMs`,
+              )
+            }
+            // proof.js owns the default and fills it; this backstop only
+            // serves direct shim callers.
+            const onsetThresholdPercent = anchor.onsetThresholdPercent ?? 5
+            const searchStartVts = driveStart.virtualTimestampMs + anchor.notBeforeMs
+            if (currentReceipt.virtualTimestampMs > searchStartVts) {
+              throw new Error(
+                `peach motion anchor ${anchor.id} searches from ${anchor.notBeforeMs}ms but the clock already sits past it: the ladder is unexecutable`,
+              )
+            }
+            // step, never jump, to the search start so hold moves land.
+            let searchReceipt = currentReceipt
+            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()
+            let previousPixels = regionPixels(anchorBitmap)
+            let anchorReceipt = searchReceipt
+            let onsetMeasurement: MotionChangeMeasurement | null = null
+            // a missed second drive is a wrong gate or search start, never
+            // jitter: the capture is lockstep-deterministic. report both
+            // peaks so the failure calibrates the gate (the early window is
+            // pan-only on every swipe lane: both releases land past it).
+            let panPeakPercent = 0
+            let latePeakPercent = 0
+            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)
+              const measurement = measureChange({
+                baseline: previousPixels,
+                candidate,
+                definition: {
+                  ...input.motionChangeDefinition,
+                  minimumChangePercent: onsetThresholdPercent,
+                },
+                height: bounds.height,
+                label: `SootSim second-drive detector ${anchor.id}`,
+                width: bounds.width,
+              })
+              previousPixels = candidate
+              currentReceipt = receipt
+              if (receipt.virtualTimestampMs - searchStartVts < 250) {
+                panPeakPercent = Math.max(panPeakPercent, measurement.changePercent)
+              } else {
+                latePeakPercent = Math.max(latePeakPercent, measurement.changePercent)
+              }
+              if (measurement.passedMinimum) {
+                candidateBitmap.close()
+                onsetMeasurement = measurement
+                break
+              }
+              anchorBitmap.close()
+              anchorBitmap = candidateBitmap
+              anchorReceipt = receipt
+            }
+            if (!onsetMeasurement) {
+              anchorBitmap.close()
+              throw new Error(
+                `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)
+            resolvedAnchors.set(anchor.id, anchorReceipt)
+            anchorRecords.push({
+              changedPixelPercent: onsetMeasurement.changePercent,
+              frameIndex: anchorReceipt.frameIndex,
+              id: anchor.id,
+              notBeforeMs: anchor.notBeforeMs,
+              virtualTimestampMs: anchorReceipt.virtualTimestampMs,
+            })
+            return { anchorId: anchor.id, receipt: anchorReceipt }
+          }
 
           const snapshots: Snapshot[] = []
           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 =
-              visibleStart.frameIndex + Math.ceil(stage.offsetMs / frameMs)
+              anchorReceipt.frameIndex + Math.ceil(stage.offsetMs / frameMs)
+            const kept = keptFrames.get(stageFrameIndex)
+            if (kept && stageFrameIndex < currentReceipt.frameIndex) {
+              snapshots.push({
+                actualMs: 0,
+                anchorId,
+                bitmap: await createImageBitmap(kept),
+                frameIndex: anchorReceipt.frameIndex,
+                label: stage.label,
+                offsetMs: stage.offsetMs,
+                virtualTimestampMs: anchorReceipt.virtualTimestampMs,
+              })
+              continue
+            }
             for (
               let eventFrameIndex = nextHoldEventFrameIndex();
               eventFrameIndex !== null && stageFrameIndex > eventFrameIndex;
@@ -2142,10 +2360,12 @@ export const device = {
             ) {
               await advanceHold(await controller.stepFrame())
             }
-            const receipt = await controller.stepToOffset(visibleStart, stage.offsetMs)
+            const receipt = await controller.stepToOffset(anchorReceipt, stage.offsetMs)
             await advanceHold(receipt)
+            currentReceipt = receipt
             snapshots.push({
-              actualMs: receipt.virtualTimestampMs - visibleStart.virtualTimestampMs,
+              actualMs: receipt.virtualTimestampMs - anchorReceipt.virtualTimestampMs,
+              anchorId,
               bitmap: await captureBitmap(),
               frameIndex: receipt.frameIndex,
               label: stage.label,
@@ -2153,14 +2373,32 @@ export const device = {
               virtualTimestampMs: receipt.virtualTimestampMs,
             })
           }
+          // 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) {
+            const receipt = await controller.stepFrame()
+            await advanceHold(receipt)
+            releasedOffsetMs = receipt.virtualTimestampMs - driveStart.virtualTimestampMs
+          }
           if (input.settleMs > 0) {
-            const maximumOffsetMs = input.stages.reduce(
-              (maximum, stage) => Math.max(maximum, stage.offsetMs),
-              0,
+            const maximumPrimaryMs = snapshots.reduce(
+              (maximum, snapshot) =>
+                Math.max(
+                  maximum,
+                  snapshot.virtualTimestampMs - driveStart.virtualTimestampMs,
+                ),
+              releasedOffsetMs,
             )
-            await controller.stepToOffset(visibleStart, maximumOffsetMs + input.settleMs)
+            await controller.stepToOffset(driveStart, maximumPrimaryMs + input.settleMs)
           }
           return {
+            anchors: anchorRecords,
+            driveStart: {
+              frameIndex: driveStart.frameIndex,
+              virtualTimestampMs: driveStart.virtualTimestampMs,
+            },
             frames: snapshots.map(encode),
             visibleChangeDetection: {
               actualMs: (visibleStart.frameIndex * 1000) / 60,
@@ -2174,6 +2412,7 @@ export const device = {
             },
           }
         } finally {
+          for (const bitmap of keptFrames.values()) bitmap.close()
           controller.end()
           delete registry[input.token]
         }
@@ -2231,6 +2470,8 @@ export const device = {
       }, token)
       const capture = await capturePromise
       return {
+        anchors: capture.anchors,
+        driveStart: capture.driveStart,
         frames: writeFastScreenshotFrames(namePrefix, capture.frames),
         triggerCompletedMs,
         triggerStartMs,
@@ -2599,6 +2840,21 @@ export const device = {
     await dispatchStatusBarOverride(config)
   },
 
+  async setOrientation(orientation: string) {
+    const next =
+      orientation === 'portrait'
+        ? 'portrait'
+        : orientation === 'landscape'
+          ? 'landscape'
+          : null
+    if (!next) {
+      throw new Error(
+        `sootsim device.setOrientation supports portrait and landscape; got ${orientation}`,
+      )
+    }
+    await dispatchDeviceOrientation(next)
+  },
+
   async setURLBlacklist(urls: string[]) {
     // no-op
   },