sootsim 0.1.295 → 0.1.297

package/README.md

@@ -188,7 +188,7 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 | SootSimBridgeHost (serve/daemon) | The bridge process (`sootsim serve`, or autostarted as the daemon via launchd/systemd). HTTP+WS hub on `:7668`: relays commands between CLI clients and registered sims; also serves runtime HTTP, `/__server-scan`, and fetch/WS proxies. | `src/host/bridge-host.ts`, `cli/commands/serve.ts`, `cli/commands/daemon.ts`, `src/home-paths.ts` |
 | AgentHost + sessions | Agent-routing extension of the host: owns the single FIFO reader per agent session and fans `agent:event`/`session-status` pushes to every WS subscriber. Backed by agent-sessions + attached-projects stores. | `src/host/agent-host.ts`, `src/agent-sessions.ts`, `src/attached-projects.ts`, `src/agent-daemon-client.ts` |
 | host proxies + dev-server scan | Host-side helpers so a cross-origin tenant worker can reach local dev servers and same-origin APIs: `/__server-scan` discovers running metro/expo/vxrn/one servers; fetch + websocket proxies relay guest-app network through the daemon. | `src/host/fetch-proxy-handler.ts`, `src/host/websocket-proxy.ts`, `scripts/dev-server-scanner.ts`, `src/dev-bundle-resolution.ts` |
-| runtime delivery + sootsim home | Versioned engine runtime management. The machinery (manifest fetch, sha256 verification, channels, pinning, auto-update) is product-agnostic and shared with the contrast CLI; `src/runtime-delivery.ts` binds it to sootsim's identity — the CDN origin (`https://contrast.dev`), the `SOOTSIM_*` env overrides, and `~/.sootsim/runtimes/<version>`. Active version, config, and the daemon lockfile live under the sootsim home. | `src/runtime-delivery.ts`, `packages/contrast-runtime-delivery/`, `src/home-paths.ts`, `src/runtime-assets.ts`, `scripts/postinstall.cjs` |
+| runtime delivery + sootsim home | Versioned engine runtime management. The shared machinery owns manifest fetch, sha256 verification, channels, and auto-update. SootSim binds it to `https://contrast.dev` and `~/.sootsim/runtimes/<version>`. A repo can select `runtimeVersion` without changing the machine default. | `src/runtime-delivery.ts`, `packages/contrast-runtime-delivery/`, `src/home-paths.ts`, `src/runtime-assets.ts`, `scripts/postinstall.cjs` |
 | `sootsim/vite` + `sootsim/metro` (runtime serving) | Published bundler plugins. Both serve the installed engine runtime at `/__soot/` from `~/.sootsim/runtimes/<version>` so an app's own dev server can host the sim shell; the vite plugin can also launch the Electron app. | `src/vite-plugin-one.ts`, `src/metro-plugin.ts`, `src/runtime-assets.ts` |
 | `sootsim()` vite resolver plugin (internal) | The large RN-resolution / native-stub vite plugin: aliases `react-native` to the engine shim, native packages to `@sootsim/compat` stubs, applies worklets/babel transforms, and instantiates `SootSimBridgeHost` in its dev server. Distinct from the published `sootsim/vite` export. | `src/vite-plugin.ts`, `src/worklets-babel.ts`, `packages/compat/src/stub-manifest.ts` |
 | skills registry | SootSim agent skills (`sootsim-setup`, `sootsim-debug`, `sootsim-test`, `sootsim-visual`, and the generated `contrast` index) installable with `sootsim skill`. | `skills/*.md`, `src/skills/registry.ts`, `src/skills/types.ts` |
@@ -261,6 +261,8 @@ sootsim open 8081         # load a running metro/expo dev server
 sootsim open /settings    # route via React Native Linking
 sootsim describe          # dump UI tree
 sootsim get errors 5      # recent runtime failures
+sootsim compat            # scan native package compatibility
+sootsim report-issue "…"  # preview an opt-in compatibility report
 sootsim find --testid cta # inspect one node deeply
 sootsim debug enable animated,layout
 sootsim debug trace shell on 240
@@ -450,7 +452,7 @@ verifies its sha256, and unpacks it under `~/.sootsim`:
 ├── runtimes/
 │   ├── <active>/         unpacked engine assets (served at /__soot/)
 │   └── <rollback>/       previous version for rollback
-├── cache/                transient downloads; empty after extraction
+├── cache/                legacy downloads; empty after cleanup
 ├── profiles/             persistent named app storage, without browser caches
 ├── electron/userData/    desktop app storage, with bounded browser caches
 ├── daemon.json           lockfile: pid, ports, active runtime, heartbeat
@@ -467,13 +469,20 @@ disabled for simulator profiles and globally capped for app chrome. Cookies,
 localStorage, IndexedDB, service workers, recordings, and captured frames are
 user-owned data and are not removed by the default cleanup command.
 
+Per-repo configuration is optional. When `sootsim.config.ts` sets
+`runtimeVersion`, `sootsim open` installs that version without changing the
+machine default and serves it from a version-specific localhost origin. Running
+from a monorepo root resolves the only React Native app from package workspaces,
+then shares that app root across config, font, and splash discovery. The fallback
+scan is bounded and prunes dependency, build, native, fixture, and example trees.
+
 The first interactive CLI command after this cleanup generation finishes its
 requested work, then launches the same safe default plan in a detached
 maintenance process. The app and terminal command are usable before the legacy
 filesystem scan begins. The worker prints the reclaimed size to stderr, records
 completion, and does not run the scan again. Open browser profiles and a runtime
-served by the live daemon are left untouched; the automatic pass retries on a
-later command after they close. The explicit `sootsim cleanup --aggressive`
+served by a live daemon or development bridge are left untouched. The automatic
+pass retries on a later command after they close. The explicit `sootsim cleanup --aggressive`
 command remains the only path that removes the rollback runtime or user-created
 recordings.
 

package/detox/index.ts

@@ -15,6 +15,12 @@ import {
   waitForSootsimGestureHandler,
 } from './gestures'
 import { by, type Matcher } from './matchers'
+import {
+  MOTION_CHANGE_DEFINITION,
+  measureMotionChange,
+  type MotionChangeDefinition,
+  type MotionChangeMeasurement,
+} from './motion-change.cjs'
 import type { SootSimElement } from './element-types'
 import type { Browser, BrowserContext, Page } from 'playwright'
 import type { SootsimEventMap, SootsimEventName } from 'sootsim-engine/sootsim-event'
@@ -554,6 +560,32 @@ function decodePngDataUrl(dataUrl: string): Buffer {
   return Buffer.from(match[1], 'base64')
 }
 
+type FastScreenshotData = {
+  label: string
+  offsetMs: number
+  actualMs: number
+  dataUrl: string
+  frameIndex?: number
+  virtualTimestampMs?: number
+}
+
+function writeFastScreenshotFrames<T extends FastScreenshotData>(
+  namePrefix: string,
+  frames: T[],
+): Array<Omit<T, 'dataUrl'> & { path: string }> {
+  ensureScreenshotDir()
+  return frames.map((frame) => {
+    const safeName = `${namePrefix}-${frame.label}`.replace(/[^a-zA-Z0-9._-]+/g, '-')
+    const filePath = path.join(SCREENSHOT_DIR, `${safeName}.png`)
+    fs.writeFileSync(filePath, decodePngDataUrl(frame.dataUrl))
+    const { dataUrl: _dataUrl, ...metadata } = frame
+    return {
+      ...metadata,
+      path: filePath,
+    }
+  })
+}
+
 // single-shot canvas capture — no frame-stability poll. used for multi-stage
 // animation captures where we explicitly want to sample mid-transition. the
 // usual captureSootsimPng polls until two consecutive frames are byte-equal
@@ -1347,10 +1379,352 @@ export const device = {
     await dispatchSootsimEventInPage('sootsim:menuAnimOverride', { value: progress })
   },
 
-  async setBottomTabAnimOverride(
-    value: { elapsedMs: number; fromIndex: number; toIndex: number } | null,
-  ): Promise<void> {
-    await dispatchSootsimEventInPage('sootsim:bottomTabAnimOverride', { value })
+  // park every render clock before the interaction, detect the first changed
+  // stepped frame inside the named component, then advance exact 60fps frames
+  // to each requested offset. native extraction also chooses the first frame
+  // at or after an offset, so both sides use the same rounding convention.
+  async takeScreenshotStagesFromVisibleChangeFast(
+    namePrefix: string,
+    stages: Array<{ label: string; offsetMs: number }>,
+    options: {
+      detectionTimeoutMs?: number
+      frame?: { height: number; width: number; x: number; y: number } | null
+      rootFrame?: { height: number; width: number; x: number; y: number } | null
+      trigger: () => unknown
+    },
+  ): Promise<{
+    frames: Array<{
+      label: string
+      offsetMs: number
+      actualMs: number
+      path: string
+      frameIndex: number
+      virtualTimestampMs: number
+    }>
+    triggerCompletedMs: number
+    triggerStartMs: number
+    visibleChangeDetection: {
+      actualMs: number
+      changedPixelPercent: number
+      changedPixels: number
+      channelThreshold: number
+      frame: { height: number; width: number; x: number; y: number } | null
+      minimumChangePercent: number
+      rootFrame: { height: number; width: number; x: number; y: number } | null
+      totalPixels: number
+      frameIndex: number
+      virtualTimestampMs: number
+    }
+  }> {
+    const page = getPage()
+    const token = `motion-${process.pid}-${Date.now()}-${Math.random()}`
+    await page.evaluate(measureMotionChange, {
+      definition: MOTION_CHANGE_DEFINITION,
+      installGlobal: true,
+    })
+    const capturePromise: Promise<{
+      frames: Array<
+        FastScreenshotData & {
+          frameIndex: number
+          virtualTimestampMs: number
+        }
+      >
+      visibleChangeDetection: {
+        actualMs: number
+        changedPixelPercent: number
+        changedPixels: number
+        channelThreshold: number
+        frameIndex: number
+        minimumChangePercent: number
+        totalPixels: number
+        virtualTimestampMs: number
+      }
+    }> = 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
+            candidate: Uint8ClampedArray
+            definition: MotionChangeDefinition
+            height: number
+            label: string
+            width: number
+          }) => MotionChangeMeasurement
+          __sootsimVisibleChangeCaptures?: Record<string, CaptureState>
+          SootSim?: {
+            bridges?: {
+              liveComposite?: {
+                captureFresh: () => Promise<{
+                  canvas: HTMLCanvasElement | null
+                  frameToken: number
+                }>
+              }
+              lockstepCapture?: {
+                begin: (fps: number) => Promise<{
+                  stepFrame: () => Promise<FrameReceipt>
+                  stepToOffset: (
+                    anchor: FrameReceipt,
+                    offsetMs: number,
+                  ) => Promise<FrameReceipt>
+                  end: () => void
+                }>
+              }
+            }
+          }
+        }
+        type Snapshot = {
+          actualMs: number
+          bitmap: ImageBitmap
+          label: string
+          offsetMs: number
+          frameIndex: number
+          virtualTimestampMs: number
+        }
+
+        const captureWindow = window as unknown as CaptureWindow
+        const live = captureWindow.SootSim?.bridges?.liveComposite
+        const lockstep = captureWindow.SootSim?.bridges?.lockstepCapture
+        if (!live || typeof live.captureFresh !== 'function') {
+          throw new Error('SootSim live composite bridge is not installed')
+        }
+        if (!lockstep || typeof lockstep.begin !== 'function') {
+          throw new Error('SootSim lockstep capture bridge is not installed')
+        }
+        const registry =
+          captureWindow.__sootsimVisibleChangeCaptures ??
+          (captureWindow.__sootsimVisibleChangeCaptures = {})
+        const state: CaptureState = {
+          cancelled: false,
+          ready: false,
+          triggerCompleted: false,
+        }
+        registry[input.token] = state
+        const measureChange = captureWindow.__sootsimMeasureMotionChange
+        if (!measureChange) {
+          throw new Error('SootSim motion change definition is not installed')
+        }
+
+        const captureBitmap = async () => {
+          const { canvas } = await live.captureFresh()
+          if (!canvas) throw new Error('SootSim live composite produced no canvas')
+          return createImageBitmap(canvas)
+        }
+        const boundsFor = (bitmap: ImageBitmap) => {
+          const scale =
+            input.rootFrame && input.rootFrame.width > 0
+              ? bitmap.width / input.rootFrame.width
+              : 1
+          return {
+            height: input.frame
+              ? Math.max(
+                  1,
+                  Math.min(
+                    bitmap.height,
+                    Math.ceil((input.frame.y + input.frame.height) * scale),
+                  ) - Math.max(0, Math.floor(input.frame.y * scale)),
+                )
+              : bitmap.height,
+            left: input.frame ? Math.max(0, Math.floor(input.frame.x * scale)) : 0,
+            top: input.frame ? Math.max(0, Math.floor(input.frame.y * scale)) : 0,
+            width: input.frame
+              ? Math.max(
+                  1,
+                  Math.min(
+                    bitmap.width,
+                    Math.ceil((input.frame.x + input.frame.width) * scale),
+                  ) - Math.max(0, Math.floor(input.frame.x * scale)),
+                )
+              : bitmap.width,
+          }
+        }
+        const regionPixels = (bitmap: ImageBitmap) => {
+          const bounds = boundsFor(bitmap)
+          const canvas = document.createElement('canvas')
+          canvas.width = bounds.width
+          canvas.height = bounds.height
+          const context = canvas.getContext('2d', { willReadFrequently: true })
+          if (!context) throw new Error('SootSim motion detector needs a 2d canvas')
+          context.drawImage(
+            bitmap,
+            bounds.left,
+            bounds.top,
+            bounds.width,
+            bounds.height,
+            0,
+            0,
+            bounds.width,
+            bounds.height,
+          )
+          return context.getImageData(0, 0, bounds.width, bounds.height).data
+        }
+        const encode = (snapshot: Snapshot) => {
+          const canvas = document.createElement('canvas')
+          canvas.width = snapshot.bitmap.width
+          canvas.height = snapshot.bitmap.height
+          const context = canvas.getContext('2d')
+          if (!context) throw new Error('SootSim motion capture needs a 2d canvas')
+          context.drawImage(snapshot.bitmap, 0, 0)
+          snapshot.bitmap.close()
+          return {
+            actualMs: snapshot.actualMs,
+            dataUrl: canvas.toDataURL('image/png'),
+            label: snapshot.label,
+            offsetMs: snapshot.offsetMs,
+            frameIndex: snapshot.frameIndex,
+            virtualTimestampMs: snapshot.virtualTimestampMs,
+          }
+        }
+
+        const controller = await lockstep.begin(60)
+        try {
+          const baselineBitmap = await captureBitmap()
+          const baseline = regionPixels(baselineBitmap)
+          baselineBitmap.close()
+          state.ready = true
+          while (!state.triggerCompleted) {
+            if (state.cancelled) throw new Error('SootSim motion capture was cancelled')
+            await new Promise((resolve) => setTimeout(resolve, 0))
+          }
+
+          let visibleStart: FrameReceipt | null = null
+          let detectedMeasurement: MotionChangeMeasurement | null = null
+          const detectionFrameLimit = Math.ceil((input.detectionTimeoutMs * 60) / 1000)
+          for (let frame = 0; frame < detectionFrameLimit; frame++) {
+            if (state.cancelled) throw new Error('SootSim motion capture was cancelled')
+            const receipt = await controller.stepFrame()
+            const candidateBitmap = await captureBitmap()
+            const bounds = boundsFor(candidateBitmap)
+            const measurement = measureChange({
+              baseline,
+              candidate: regionPixels(candidateBitmap),
+              definition: input.motionChangeDefinition,
+              height: bounds.height,
+              label: 'SootSim visible-change detector',
+              width: bounds.width,
+            })
+            candidateBitmap.close()
+            if (measurement.passedMinimum) {
+              visibleStart = receipt
+              detectedMeasurement = measurement
+              break
+            }
+          }
+          if (!visibleStart || !detectedMeasurement) {
+            throw new Error(
+              `SootSim motion had no visible change before ${input.detectionTimeoutMs}ms`,
+            )
+          }
+
+          const snapshots: Snapshot[] = []
+          for (const stage of input.stages) {
+            if (state.cancelled) throw new Error('SootSim motion capture was cancelled')
+            const receipt = await controller.stepToOffset(visibleStart, stage.offsetMs)
+            snapshots.push({
+              actualMs: receipt.virtualTimestampMs - visibleStart.virtualTimestampMs,
+              bitmap: await captureBitmap(),
+              frameIndex: receipt.frameIndex,
+              label: stage.label,
+              offsetMs: stage.offsetMs,
+              virtualTimestampMs: receipt.virtualTimestampMs,
+            })
+          }
+          return {
+            frames: snapshots.map(encode),
+            visibleChangeDetection: {
+              actualMs: (visibleStart.frameIndex * 1000) / 60,
+              changedPixelPercent: detectedMeasurement.changePercent,
+              changedPixels: detectedMeasurement.changePixels,
+              channelThreshold: input.motionChangeDefinition.channelThreshold,
+              minimumChangePercent: input.motionChangeDefinition.minimumChangePercent,
+              totalPixels: detectedMeasurement.totalPixels,
+              frameIndex: visibleStart.frameIndex,
+              virtualTimestampMs: visibleStart.virtualTimestampMs,
+            },
+          }
+        } finally {
+          controller.end()
+          delete registry[input.token]
+        }
+      },
+      {
+        detectionTimeoutMs: options.detectionTimeoutMs ?? 3000,
+        frame: options.frame ?? null,
+        motionChangeDefinition: MOTION_CHANGE_DEFINITION,
+        rootFrame: options.rootFrame ?? null,
+        stages,
+        token,
+      },
+    )
+
+    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 },
+    )
+
+    const triggerStartMs = Date.now()
+    let triggerCompletedMs = 0
+    try {
+      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 }
+            >
+          }
+        ).__sootsimVisibleChangeCaptures
+        const capture = registry?.[captureToken]
+        if (!capture) throw new Error('SootSim motion capture disarmed before trigger')
+        capture.triggerCompleted = true
+      }, token)
+      const capture = await capturePromise
+      return {
+        frames: writeFastScreenshotFrames(namePrefix, capture.frames),
+        triggerCompletedMs,
+        triggerStartMs,
+        visibleChangeDetection: {
+          ...capture.visibleChangeDetection,
+          frame: options.frame ?? null,
+          rootFrame: options.rootFrame ?? null,
+        },
+      }
+    } catch (error) {
+      await page
+        .evaluate((captureToken) => {
+          const registry = (
+            window as Window & {
+              __sootsimVisibleChangeCaptures?: Record<
+                string,
+                { cancelled: boolean; ready: boolean; triggerCompleted: boolean }
+              >
+            }
+          ).__sootsimVisibleChangeCaptures
+          const capture = registry?.[captureToken]
+          if (capture) capture.cancelled = true
+        }, token)
+        .catch(() => {})
+      await capturePromise.catch(() => {})
+      throw error
+    }
   },
 
   // FAST multi-stage capture for sub-second animation diffs. each stage
@@ -1490,18 +1864,7 @@ export const device = {
       },
       { stages, skipWarmup: options?.skipWarmup === true },
     )
-    ensureScreenshotDir()
-    return frames.map((f) => {
-      const safeName = `${namePrefix}-${f.label}`.replace(/[^a-zA-Z0-9._-]+/g, '-')
-      const filePath = path.join(SCREENSHOT_DIR, `${safeName}.png`)
-      fs.writeFileSync(filePath, decodePngDataUrl(f.dataUrl))
-      return {
-        label: f.label,
-        offsetMs: f.offsetMs,
-        actualMs: f.actualMs,
-        path: filePath,
-      }
-    })
+    return writeFastScreenshotFrames(namePrefix, frames)
   },
 
   // batched multi-stage capture for animation diffs. all N captures happen
@@ -1549,18 +1912,7 @@ export const device = {
       },
       { stages },
     )
-    ensureScreenshotDir()
-    return frames.map((f) => {
-      const safeName = `${namePrefix}-${f.label}`.replace(/[^a-zA-Z0-9._-]+/g, '-')
-      const filePath = path.join(SCREENSHOT_DIR, `${safeName}.png`)
-      fs.writeFileSync(filePath, decodePngDataUrl(f.dataUrl))
-      return {
-        label: f.label,
-        offsetMs: f.offsetMs,
-        actualMs: f.actualMs,
-        path: filePath,
-      }
-    })
+    return writeFastScreenshotFrames(namePrefix, frames)
   },
 
   async shake() {

package/detox/motion-change.cjs

@@ -0,0 +1,109 @@
+// native recordings and SootSim live frames must use this exact definition.
+// retained static Android crops measured as high as 0.0331% after the channel
+// filter. the smallest corrected component transition with visible motion was
+// 0.1748%, so a 0.1% floor separates every measured static and moving frame.
+const MOTION_CHANGE_DEFINITION = Object.freeze({
+  channelThreshold: 24,
+  minimumChangePercent: 0.1,
+})
+
+function measureMotionChange(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('motion change measurement requires an input object')
+  }
+  if (input.installGlobal === true) {
+    globalThis.__sootsimMeasureMotionChange = measureMotionChange
+    return null
+  }
+
+  const definition = input.definition
+  if (
+    !definition ||
+    typeof definition !== 'object' ||
+    !Number.isInteger(definition.channelThreshold) ||
+    definition.channelThreshold < 0 ||
+    definition.channelThreshold > 255 ||
+    !Number.isFinite(definition.minimumChangePercent) ||
+    definition.minimumChangePercent <= 0 ||
+    definition.minimumChangePercent >= 100
+  ) {
+    throw new Error(
+      'motion change definition needs a channel threshold from 0 to 255 and a minimum greater than 0% and less than 100%',
+    )
+  }
+
+  const label =
+    typeof input.label === 'string' && input.label.length > 0
+      ? input.label
+      : 'motion change'
+  let changePixels = input.changePixels
+  let totalPixels = input.totalPixels
+  if (input.baseline !== undefined || input.candidate !== undefined) {
+    const baseline = input.baseline
+    const candidate = input.candidate
+    const width = input.width
+    const height = input.height
+    if (
+      !baseline ||
+      !candidate ||
+      typeof baseline.length !== 'number' ||
+      typeof candidate.length !== 'number' ||
+      !Number.isInteger(width) ||
+      !Number.isInteger(height) ||
+      width <= 0 ||
+      height <= 0
+    ) {
+      throw new Error(`${label} needs two RGBA pixel arrays and positive dimensions`)
+    }
+    totalPixels = width * height
+    const expectedBytes = totalPixels * 4
+    if (baseline.length !== expectedBytes || candidate.length !== expectedBytes) {
+      throw new Error(
+        `${label} pixel data has ${baseline.length}/${candidate.length} bytes; expected ${expectedBytes}`,
+      )
+    }
+    changePixels = 0
+    for (let offset = 0; offset < expectedBytes; offset += 4) {
+      if (
+        Math.abs(baseline[offset] - candidate[offset]) > definition.channelThreshold ||
+        Math.abs(baseline[offset + 1] - candidate[offset + 1]) >
+          definition.channelThreshold ||
+        Math.abs(baseline[offset + 2] - candidate[offset + 2]) >
+          definition.channelThreshold ||
+        Math.abs(baseline[offset + 3] - candidate[offset + 3]) >
+          definition.channelThreshold
+      ) {
+        changePixels++
+      }
+    }
+  }
+
+  if (!Number.isInteger(totalPixels) || totalPixels <= 0) {
+    throw new Error(`${label} has no positive measured region area`)
+  }
+  if (!Number.isInteger(changePixels) || changePixels < 0 || changePixels > totalPixels) {
+    throw new Error(
+      `${label} changed pixel count ${changePixels} is outside its ${totalPixels}px measured region`,
+    )
+  }
+  const changePercent = (changePixels / totalPixels) * 100
+  return {
+    changePercent,
+    changePixels,
+    passedMinimum: changePercent >= definition.minimumChangePercent,
+    totalPixels,
+  }
+}
+
+function measureProofMotionChange(input) {
+  return measureMotionChange({
+    ...input,
+    definition: MOTION_CHANGE_DEFINITION,
+  })
+}
+
+module.exports = {
+  MOTION_CHANGE_DEFINITION,
+  measureMotionChange,
+  measureProofMotionChange,
+}

package/detox/motion-change.d.cts

@@ -0,0 +1,35 @@
+export type MotionChangeDefinition = {
+  channelThreshold: number
+  minimumChangePercent: number
+}
+
+type MotionChangePixels = ArrayLike<number>
+
+export type MotionChangeInput = {
+  baseline?: MotionChangePixels
+  candidate?: MotionChangePixels
+  changePixels?: number
+  definition: MotionChangeDefinition
+  height?: number
+  installGlobal?: boolean
+  label?: string
+  totalPixels?: number
+  width?: number
+}
+
+export type MotionChangeMeasurement = {
+  changePercent: number
+  changePixels: number
+  passedMinimum: boolean
+  totalPixels: number
+}
+
+export const MOTION_CHANGE_DEFINITION: Readonly<MotionChangeDefinition>
+
+export function measureMotionChange(
+  input: MotionChangeInput,
+): MotionChangeMeasurement | null
+
+export function measureProofMotionChange(
+  input: Omit<MotionChangeInput, 'definition' | 'installGlobal'>,
+): MotionChangeMeasurement