peachsim 0.1.1635 → 0.1.1640

package/detox/attempt-events.d.cts

@@ -104,3 +104,10 @@ export function writeDiscreteFrameReceipt(
   context: DiscreteProofContext,
   trace: DiscreteFrameTrace,
 ): DiscreteProofReference
+
+export function boundText(
+  root: string,
+  relative: string,
+  sha256: string,
+  label: string,
+): string

package/detox/expectations.ts

@@ -54,8 +54,12 @@ export function isNodeVisible(node: SootSimNodeInfo | null | undefined): boolean
 }
 
 // a native host is focused when its editor child holds focus.
-export function focusIsWithin(focused: SootSimFocusedNodeInfo, nodeId: number): boolean {
-  return focused.nodeId === nodeId || focused.ancestorNodeIds.includes(nodeId)
+export function focusIsWithin(
+  focused: SootSimFocusedNodeInfo,
+  node: SootSimNodeInfo,
+): boolean {
+  const nativeNodeId = node.nativeTag ?? node.nodeId
+  return focused.nodeId === nativeNodeId || focused.ancestorNodeIds.includes(nativeNodeId)
 }
 
 // the engine owns focus for canvas inputs and hosted native editors.
@@ -64,7 +68,7 @@ export async function isTextInputNodeFocused(
   page: Page,
 ): Promise<boolean> {
   const focused = await page.evaluate(async () => window.__sootsimTest!.getFocusedNode())
-  return focused !== null && focusIsWithin(focused, node.nodeId)
+  return focused !== null && focusIsWithin(focused, node)
 }
 
 async function isNodeFocused(node: SootSimNodeInfo, page: Page): Promise<boolean> {

package/detox/index.ts

@@ -127,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
@@ -402,6 +403,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 +411,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 +466,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,
@@ -553,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}`)
   }
@@ -561,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
@@ -575,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
@@ -585,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))
   }
@@ -897,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`,
@@ -1441,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
@@ -1972,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 })
@@ -2090,7 +2111,7 @@ export const device = {
   },
 
   async terminateApp() {
-    await closeBrowser()
+    await closeBrowser(true)
   },
 
   async installApp() {
@@ -2617,6 +2638,7 @@ 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
@@ -2629,10 +2651,10 @@ export const device = {
         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
@@ -2843,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
@@ -2901,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(
@@ -2947,7 +2999,7 @@ export const device = {
             if (measurement.passedMinimum) {
               visibleStart = receipt
               detectedMeasurement = measurement
-              keptFrames.set(visibleStart.frameIndex, candidateBitmap)
+              keepFrame(visibleStart, candidateBitmap)
             } else {
               candidateBitmap.close()
             }
@@ -2958,9 +3010,12 @@ export const device = {
             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' && holdState.releaseReceipt === receipt)
+            ) {
+              keepFrame(receipt, await createImageBitmap(candidateBitmap))
             }
             const bounds = boundsFor(candidateBitmap)
             const measurement = measureChange({
@@ -2976,8 +3031,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,22 +3046,19 @@ 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')
-            }
+          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) {
-                keptFrames.set(receipt.frameIndex, await captureBitmap())
-              }
+              if (holdState.released) keepFrame(receipt, await captureBitmap())
             }
             if (!holdState.releaseReceipt) {
               throw new Error('peach release anchoring found no release frame')
@@ -3109,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,
@@ -3134,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
             }
@@ -3164,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.
@@ -3189,6 +3243,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 +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,
-        anchorAtRelease: options.anchorAtRelease ?? false,
+        anchorAtTouch: options.anchorAtTouch ?? null,
         hold: options.hold ?? null,
         motionChangeDefinition: MOTION_CHANGE_DEFINITION,
         platform: device.getPlatform(),
@@ -3228,14 +3297,19 @@ export const device = {
       },
     )
 
-    await page.waitForFunction(
-      (captureToken) => {
-        const registry = window.__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
@@ -3847,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)
 }

package/detox/motion-change.cjs

@@ -106,30 +106,35 @@ function measureProofMotionChange(input) {
 // exactly still, so only oracle changes of at least this much need a sootsim
 // match.
 const PAIRED_MOTION_MINIMUM_CHANGE_PERCENT = 0.3
-// a lone change below this after a still transition is a settle blip, which
-// the two targets land a frame or two apart, so it needs no match.
+// the last oracle change, when it is below this and follows a still
+// transition, is a settle blip, which the two targets land a frame or two
+// apart, so it needs no match. only that one blip is exempt.
 const SETTLE_BLIP_MAXIMUM_CHANGE_PERCENT = 0.6
 
 // a present or dismiss records one second (60 transitions); a gesture ladder
 // records four. a gesture jumps at its touch cadence and each capture phases
 // that cadence differently, so a gesture is graded by total travel instead of
-// by frame, and the native driver plays the finger path up to ten frames ahead
-// of the sootsim one, so the whole gesture's travel is judged, not its timing.
+// by frame. travel is judged over the whole gesture and again over each quarter
+// so one jump or a lagging release cannot pass on its total.
 const GESTURE_MOTION_MIN_TRANSITIONS = 120
 const GESTURE_TRAVEL_RATIO_RANGE = Object.freeze({ min: 0.8, max: 1.25 })
+const GESTURE_QUARTER_TRAVEL_RATIO_RANGE = Object.freeze({ min: 0.5, max: 2 })
 
 // a sampled motion proves movement as a pair: the oracle moves in at least one
 // transition. a one second motion also needs sootsim to move within one frame
 // of every transition where the oracle changed by the paired minimum; a hold
 // where the oracle holds needs no sootsim movement, while a static sootsim
 // against a moving oracle fails. a gesture needs sootsim's total travel within
-// a range of the oracle's. transitions pair by their stage labels; every
-// measurement must exist.
+// a range of the oracle's. both lanes hold the same unique stage-label
+// transitions in the same order; every measurement must exist.
 function evaluateMotionTransitions(transitions, oracleTarget) {
   const key = (transition) => `${transition.fromLabel}\u0000${transition.toLabel}`
   const oracle = transitions.filter((transition) => transition.target === oracleTarget)
   const sootsim = transitions.filter((transition) => transition.target === 'sootsim')
-  const sootsimByKey = new Map(sootsim.map((transition) => [key(transition), transition]))
+  const paired =
+    oracle.length === sootsim.length &&
+    new Set(oracle.map(key)).size === oracle.length &&
+    oracle.every((transition, index) => key(transition) === key(sootsim[index]))
   const measured = transitions.every(
     (transition) =>
       transition.dimensionsMatch &&
@@ -137,38 +142,64 @@ function evaluateMotionTransitions(transitions, oracleTarget) {
       transition.changePixels !== null &&
       transition.totalPixels !== null,
   )
-  const moving = oracle.filter((transition) => transition.passedMinimum)
   const travel = (list) =>
     list
       .filter(
         (transition) => transition.changePercent >= PAIRED_MOTION_MINIMUM_CHANGE_PERCENT,
       )
       .reduce((total, transition) => total + transition.changePercent, 0)
-  const sootsimMovesNear = (index) =>
-    [index - 1, index, index + 1].some(
-      (neighbour) => sootsim[neighbour]?.passedMinimum === true,
-    )
-  const isSettleBlip = (transition, index) =>
-    transition.changePercent < SETTLE_BLIP_MAXIMUM_CHANGE_PERCENT &&
-    !(oracle[index - 1]?.passedMinimum ?? true)
+  const movesNear = (list, index) =>
+    [index - 1, index, index + 1].some((neighbour) => list[neighbour]?.passedMinimum === true)
+  const pairedChange = (transition) =>
+    transition.changePercent >= PAIRED_MOTION_MINIMUM_CHANGE_PERCENT
+  const settleBlip = (list) => {
+    const index = list.findLastIndex(pairedChange)
+    return index >= 0 &&
+      list[index].changePercent < SETTLE_BLIP_MAXIMUM_CHANGE_PERCENT &&
+      !(list[index - 1]?.passedMinimum ?? true)
+      ? index
+      : -1
+  }
+  const oracleBlip = settleBlip(oracle)
+  const sootsimBlip = settleBlip(sootsim)
+  // the oracle moves only where it changed by the paired minimum; drift and
+  // its settle blip alone are not a motion.
+  const moving = oracle.filter(
+    (transition, index) => pairedChange(transition) && index !== oracleBlip,
+  )
   const within = (actual, expected, range) =>
     actual >= expected * range.min && actual <= expected * range.max
+  const quarter = (list, index) =>
+    list.slice(
+      Math.floor((list.length * index) / 4),
+      Math.floor((list.length * (index + 1)) / 4),
+    )
   const follows =
     oracle.length >= GESTURE_MOTION_MIN_TRANSITIONS
-      ? within(travel(sootsim), travel(oracle), GESTURE_TRAVEL_RATIO_RANGE)
+      ? within(travel(sootsim), travel(oracle), GESTURE_TRAVEL_RATIO_RANGE) &&
+        [0, 1, 2, 3].every((index) =>
+          within(
+            travel(quarter(sootsim, index)),
+            travel(quarter(oracle, index)),
+            GESTURE_QUARTER_TRAVEL_RATIO_RANGE,
+          ),
+        )
       : oracle.every(
           (transition, index) =>
-            !transition.passedMinimum ||
-            transition.changePercent < PAIRED_MOTION_MINIMUM_CHANGE_PERCENT ||
-            isSettleBlip(transition, index) ||
-            (sootsimByKey.has(key(transition)) && sootsimMovesNear(index)),
+            !pairedChange(transition) ||
+            index === oracleBlip ||
+            movesNear(sootsim, index),
+        ) &&
+        sootsim.every(
+          (transition, index) =>
+            !pairedChange(transition) || index === sootsimBlip || movesNear(oracle, index),
         )
   return {
     moving: moving.length,
     passed:
       measured &&
       oracle.length > 0 &&
-      sootsim.length === oracle.length &&
+      paired &&
       moving.length > 0 &&
       follows,
   }
@@ -429,8 +460,126 @@ function evaluateDiscreteFrameTrace(input) {
   return { mode: 'playing', anchorMs: anchor.atMs, holds }
 }
 
+// a motion publishes when its transitions pair and its pixels agree at the
+// ends and at a few places in between. the first and last stage must pass their
+// region budget; a ladder of at least ten stages also needs two intermediate
+// stages that pass while the oracle is still moving into them. dense samples
+// may move less than the pairing bar; filtered pixel change away from both
+// endpoint images still proves intermediate motion. a settled tail frame
+// proves nothing about the motion and one frame of timing shift
+// fails a stage outright. the remaining intermediate stages are reported as
+// room to improve, never as a failure. a sparse ladder samples too coarsely to
+// ask for intermediates. a repeating motion also needs every cycle's period
+// within one frame of the oracle's, since re-anchoring each cycle would
+// otherwise hide a lane that runs fast or slow.
+const PUBLICATION_DENSE_LADDER_MIN_STAGES = 10
+const PUBLICATION_MIN_INTERMEDIATE_PASSES = 2
+
+// one onset per cycle of a repeating animation on the lane's own clock: the
+// transition drive, then each `cycle` anchor in declaration order. ios reports
+// recording seconds (the transition's triggerInVideoSec, each anchor's
+// detection.atSec), android its producer clock (triggerProducerSeconds, each
+// anchor's producerSeconds), and peach virtual clock milliseconds (driveStart,
+// each anchor's own receipt).
+function motionCycleOnsets(event, eventPath) {
+  if (!Array.isArray(event.anchors)) return []
+  const cycles = event.anchors.filter(
+    (anchor) => typeof anchor === 'object' && anchor !== null && anchor.cycle === true,
+  )
+  if (cycles.length === 0) return []
+  const finite = (value, label) => {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+      throw new Error(`motion event cycle ${label} has no onset time: ${eventPath}`)
+    return value
+  }
+  const android = event.captureMode === 'android-screenrecord-sequence'
+  const peach = typeof event.driveStart === 'object' && event.driveStart !== null
+  const basisMs = peach
+    ? finite(event.driveStart.virtualTimestampMs, 'transition')
+    : android
+      ? finite(event.triggerProducerSeconds, 'transition') * 1000
+      : finite(event.triggerInVideoSec, 'transition') * 1000
+  return [
+    { id: 'transition', atMs: basisMs },
+    ...cycles.map((anchor) => {
+      if (typeof anchor.id !== 'string')
+        throw new Error(`motion event cycle anchor has no id: ${eventPath}`)
+      const atMs = peach
+        ? finite(anchor.virtualTimestampMs, anchor.id)
+        : android
+          ? finite(anchor.producerSeconds, anchor.id) * 1000
+          : finite(anchor.detection?.atSec, anchor.id) * 1000
+      return { id: anchor.id, atMs }
+    }),
+  ]
+}
+
+// one display frame: the period a native repeat cycle may differ from
+// peach's before re-anchoring each cycle would hide real drift
+const MOTION_CYCLE_PERIOD_TOLERANCE_MS = 1000 / 60
+
+function motionCyclePeriods(reference, sootsim) {
+  const ids = (onsets) => onsets.map((onset) => onset.id).join(',')
+  if (ids(reference) !== ids(sootsim))
+    throw new Error(
+      `motion cycle anchors differ between lanes: reference [${ids(reference)}], sootsim [${ids(sootsim)}]`,
+    )
+  return reference.slice(1).map((onset, index) => {
+    const referenceMs = onset.atMs - reference[index].atMs
+    const sootsimMs = sootsim[index + 1].atMs - sootsim[index].atMs
+    return {
+      id: onset.id,
+      passed: Math.abs(referenceMs - sootsimMs) <= MOTION_CYCLE_PERIOD_TOLERANCE_MS,
+      referenceMs,
+      sootsimMs,
+    }
+  })
+}
+
+function evaluateMotionPublication(stages, transitions, oracleTarget, cycleOnsets) {
+  const cyclePeriods = motionCyclePeriods(cycleOnsets.reference, cycleOnsets.sootsim)
+  const intermediates = stages.slice(1, -1)
+  const intermediatePassed = intermediates.filter((stage) => stage.passedThreshold).length
+  const stagesByLabel = new Map(stages.map((stage) => [stage.label, stage]))
+  const oracleMovingInto = new Set(
+    transitions
+      .filter(
+        (transition) =>
+          transition.target === oracleTarget &&
+          (transition.changePercent >= PAIRED_MOTION_MINIMUM_CHANGE_PERCENT ||
+            (transition.changePixels > 0 &&
+              stagesByLabel.get(transition.toLabel)?.oracleFromFirstPercent >=
+                PAIRED_MOTION_MINIMUM_CHANGE_PERCENT &&
+              stagesByLabel.get(transition.toLabel)?.oracleFromLastPercent >=
+                PAIRED_MOTION_MINIMUM_CHANGE_PERCENT)),
+      )
+      .map((transition) => transition.toLabel),
+  )
+  const movingPassed = intermediates.filter(
+    (stage) => stage.passedThreshold && oracleMovingInto.has(stage.label),
+  ).length
+  const needsIntermediates = stages.length >= PUBLICATION_DENSE_LADDER_MIN_STAGES
+  const first = stages[0]
+  const last = stages[stages.length - 1]
+  return {
+    passed:
+      stages.length > 0 &&
+      first.passedThreshold &&
+      last.passedThreshold &&
+      (!needsIntermediates || movingPassed >= PUBLICATION_MIN_INTERMEDIATE_PASSES) &&
+      cyclePeriods.every((period) => period.passed) &&
+      evaluateMotionTransitions(transitions, oracleTarget).passed,
+    cyclePeriods,
+    intermediateCount: intermediates.length,
+    intermediatePassed,
+    movingPassed,
+  }
+}
+
 module.exports = {
   MOTION_CHANGE_DEFINITION,
+  evaluateMotionPublication,
+  motionCycleOnsets,
   measureMotionChange,
   measureProofMotionChange,
   evaluateMotionTransitions,