rnxsim 0.0.0 → 0.1.312

package/detox/index.ts

@@ -0,0 +1,2118 @@
+// 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 * as fs from 'fs'
+import * as path from 'path'
+import { chromium } from 'playwright'
+import { launchReapedChromeScoped } from '../../../scripts/lib/reap-browser'
+import { createExpect, createWaitFor } from './expectations'
+import {
+  dispatchTwoFingerGesture,
+  dragScrollNode,
+  readSootsimInteractiveViewport,
+  readSootsimViewport,
+  sootsimToPage,
+  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'
+
+export { by }
+export type { SootSimElement } from './element-types'
+
+const BASE_URL = process.env.SOOTSIM_URL || 'http://localhost:5173'
+const SCREENSHOT_DIR =
+  process.env.SOOTSIM_SCREENSHOT_DIR ||
+  path.join(process.cwd(), 'test', 'detox-driver', 'screenshots')
+const DETOX_PLATFORM =
+  process.env.SOOTSIM_PLATFORM === 'android' ? ('android' as const) : ('ios' as const)
+
+// shared state -- playwright page and browser
+let _browser: Browser | null = null
+let _reapBrowserNow: (() => void) | null = null
+let _context: BrowserContext | null = null
+let _page: Page | null = null
+let _synchronizationEnabled = false
+const pageDiagnostics = new WeakMap<Page, string[]>()
+
+const STATUS_BAR_OVERRIDE_EVENT = 'sootsim:statusBarOverride'
+
+type StatusBarConfig = {
+  time?: string
+  dataNetwork?: string
+  wifiMode?: string
+  wifiBars?: string
+  cellularMode?: string
+  cellularBars?: string
+  operatorName?: string
+  batteryState?: string
+  batteryLevel?: string | number
+}
+
+function getPage(): Page {
+  if (!_page)
+    throw new Error('sootsim driver not initialized -- call device.launchApp() first')
+  return _page
+}
+
+function recordPageDiagnostic(page: Page, message: string) {
+  const entries = pageDiagnostics.get(page)
+  if (!entries) return
+  entries.push(message)
+  if (entries.length > 40) entries.shift()
+}
+
+function attachPageDiagnostics(page: Page) {
+  if (pageDiagnostics.has(page)) return
+  pageDiagnostics.set(page, [])
+  page.on('console', (message) => {
+    recordPageDiagnostic(page, `[console:${message.type()}] ${message.text()}`)
+  })
+  page.on('pageerror', (error) => {
+    recordPageDiagnostic(page, `[pageerror] ${error.message}`)
+  })
+  page.on('requestfailed', (request) => {
+    const failure = request.failure()
+    recordPageDiagnostic(
+      page,
+      `[requestfailed] ${request.method()} ${request.url()} ${failure?.errorText ?? ''}`,
+    )
+  })
+}
+
+async function describeSootsimBridgeFailure(page: Page, cause: unknown) {
+  let pageState: unknown = null
+  try {
+    pageState = await page.evaluate(() => ({
+      bodyText: document.body?.innerText?.slice(0, 500) ?? '',
+      globals: Object.keys(window)
+        .filter((key) => key.startsWith('__sootsim') || key === 'SootSim')
+        .sort(),
+      readyState: document.readyState,
+      title: document.title,
+      url: window.location.href,
+    }))
+  } catch (error) {
+    pageState = {
+      evaluateError: error instanceof Error ? error.message : String(error),
+    }
+  }
+
+  return new Error(
+    [
+      `timed out waiting for sootsim test bridge`,
+      `cause: ${cause instanceof Error ? cause.message : String(cause)}`,
+      `page: ${JSON.stringify(pageState)}`,
+      `recent page diagnostics:\n${(pageDiagnostics.get(page) ?? []).join('\n') || '(none)'}`,
+    ].join('\n'),
+  )
+}
+
+async function waitForSootsimTree(page: Page, timeout = 30000): Promise<void> {
+  try {
+    await page.waitForFunction(() => !!window.__sootsimTest?.waitForTree, {
+      timeout,
+    })
+    await page.evaluate(async (timeoutMs) => {
+      await Promise.race([
+        window.__sootsimTest!.waitForTree(),
+        new Promise((_, reject) => {
+          setTimeout(
+            () => reject(new Error(`sootsim waitForTree timed out after ${timeoutMs}ms`)),
+            timeoutMs,
+          )
+        }),
+      ])
+    }, timeout)
+  } catch (error) {
+    throw await describeSootsimBridgeFailure(page, error)
+  }
+}
+
+async function waitForSootsimSurfaceMetrics(page: Page, timeout = 30000): Promise<void> {
+  const deadline = Date.now() + timeout
+  let lastSnapshot: unknown = null
+  while (Date.now() < deadline) {
+    lastSnapshot = await page.evaluate(async () => {
+      const metricsWindow = (value: unknown): Record<string, unknown> | null => {
+        if (!value || typeof value !== 'object') return null
+        const windowValue = (value as Record<string, unknown>).window
+        if (!windowValue || typeof windowValue !== 'object') return null
+        return windowValue as Record<string, unknown>
+      }
+      const snapshot = await window.__sootsimTest?.getSurfaceMetricsSnapshot?.()
+      const windowMetrics = metricsWindow(snapshot)
+      const width = windowMetrics?.width
+      const height = windowMetrics?.height
+      if (
+        typeof width === 'number' &&
+        typeof height === 'number' &&
+        width > 0 &&
+        height > 0
+      ) {
+        return { ready: true }
+      }
+      return { ready: false, snapshot }
+    })
+    if (
+      lastSnapshot &&
+      typeof lastSnapshot === 'object' &&
+      (lastSnapshot as { ready?: boolean }).ready
+    ) {
+      return
+    }
+    await page.waitForTimeout(50)
+  }
+  throw new Error(
+    `timed out waiting for sootsim surface metrics: ${JSON.stringify(lastSnapshot)}`,
+  )
+}
+
+async function waitForSootsimShellReady(page: Page, timeout = 30000): Promise<void> {
+  try {
+    await page.evaluate(async (timeoutMs) => {
+      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)
+        }
+      }
+
+      const isTenantOnly =
+        new URL(window.location.href).searchParams.get('renderMode') === 'tenant-only'
+      const currentUrl = new URL(window.location.href)
+      const expectsInitialAppPaint =
+        currentUrl.searchParams.has('test') || currentUrl.pathname.includes('/app/')
+      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)
+      }
+
+      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)
+      }
+      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)}`,
+          )
+        }
+      }
+    }, timeout)
+  } catch (error) {
+    throw await describeSootsimBridgeFailure(page, error)
+  }
+}
+
+async function waitForSootsimWorkletsIdle(page: Page, timeout = 3000): Promise<void> {
+  const result = await page.evaluate(
+    async ({ timeout }) => {
+      const getPeerStats = (window as any).__sootsimTest?.getPeerStats
+      if (typeof getPeerStats !== 'function') {
+        return { settled: true, skipped: true }
+      }
+
+      const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+      const readStats = () =>
+        Promise.race([
+          getPeerStats(false),
+          new Promise((resolve) => setTimeout(() => resolve(null), 250)),
+        ])
+      const start = Date.now()
+      const deadline = start + timeout
+      const requiredStableMs = 120
+      let stableSince: number | null = null
+      let lastPending = 0
+      await sleep(0)
+
+      while (Date.now() < deadline) {
+        const stats = await readStats()
+        const pending =
+          stats &&
+          typeof stats === 'object' &&
+          typeof (stats as { pendingRunWorklets?: unknown }).pendingRunWorklets ===
+            'number'
+            ? stats.pendingRunWorklets
+            : 0
+        lastPending = pending
+        if (pending === 0) {
+          stableSince ??= Date.now()
+          if (Date.now() - stableSince >= requiredStableMs) {
+            return { settled: true, elapsed: Date.now() - start, pending }
+          }
+        } else {
+          stableSince = null
+        }
+        await sleep(25)
+      }
+
+      return {
+        settled: false,
+        elapsed: Date.now() - start,
+        pending: lastPending,
+      }
+    },
+    { timeout },
+  )
+  if (!result?.settled) {
+    throw new Error(
+      `sootsim worklet runtime did not settle after ${result?.elapsed ?? timeout}ms (pending=${result?.pending ?? 'unknown'})`,
+    )
+  }
+}
+
+async function closeContext() {
+  const context = _context
+  _context = null
+  _page = null
+  _synchronizationEnabled = false
+  if (context) await context.close()
+}
+
+async function closeBrowser() {
+  if (!_browser) return
+  const browser = _browser
+  const reapBrowserNow = _reapBrowserNow
+  _browser = null
+  _reapBrowserNow = null
+  await closeContext()
+  try {
+    await browser.close()
+  } finally {
+    reapBrowserNow?.()
+  }
+}
+
+export async function waitForSootsimIdle(page: Page, maxMs = 3000): Promise<void> {
+  const result = await page.evaluate(
+    async ({ maxMs }) => {
+      let transitionError: string | null = null
+      try {
+        const waitForScreenTransitions = (window as any).__sootsimTest
+          ?.waitForScreenTransitions
+        if (typeof waitForScreenTransitions === 'function') {
+          const transitionResult = await waitForScreenTransitions({
+            timeoutMs: Math.min(maxMs, 1800),
+            settleMs: 48,
+            startWindowMs: 600,
+          })
+          if (
+            transitionResult?.started === true &&
+            transitionResult.settled === true &&
+            transitionResult.timedOut !== true
+          ) {
+            return { settled: true, elapsed: transitionResult.waitedMs ?? 0 }
+          }
+          if (transitionResult?.timedOut) {
+            return {
+              settled: false,
+              elapsed: transitionResult.waitedMs,
+              reason: 'screen transition',
+            }
+          }
+        }
+      } catch (error) {
+        transitionError = error instanceof Error ? error.message : String(error)
+      }
+
+      const start = Date.now()
+      const deadline = start + maxMs
+      const pollMs = 50
+      const requiredStablePolls = 3
+      const layoutTolerance = 1
+      const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+      const isLayoutStable = (a: number[] | null, b: number[]) => {
+        if (!a || a.length !== b.length) return false
+        for (let i = 0; i < b.length; i++) {
+          if (Math.abs(a[i] - b[i]) > layoutTolerance) return false
+        }
+        return true
+      }
+
+      const readSnapshot = async () => {
+        const root = (window as any).__sootsimRoot
+        const layout: number[] = []
+        if (root) {
+          const walk = (node: any) => {
+            if (node.layout && node.layout.width > 0) {
+              layout.push(
+                Math.round(node.layout.x),
+                Math.round(node.layout.y),
+                Math.round(node.layout.width),
+                Math.round(node.layout.height),
+              )
+            }
+            for (const child of node.children || []) walk(child)
+          }
+          walk(root)
+        }
+        return layout
+      }
+
+      let stableLayout: number[] | null = null
+      let stable = 0
+      while (Date.now() < deadline) {
+        const layout = await readSnapshot()
+        if (isLayoutStable(stableLayout, layout)) {
+          stable++
+          if (stable >= requiredStablePolls) {
+            return { settled: true, elapsed: Date.now() - start }
+          }
+        } else {
+          stableLayout = layout
+          stable = 0
+        }
+        await sleep(pollMs)
+      }
+      return {
+        settled: false,
+        elapsed: Date.now() - start,
+        reason: transitionError
+          ? `layout fallback after screen transition wait failed: ${transitionError}`
+          : 'layout fallback',
+      }
+    },
+    { maxMs },
+  )
+
+  if (!result?.settled) {
+    throw new Error(
+      `sootsim synchronization timed out after ${result?.elapsed ?? maxMs}ms${result?.reason ? ` (${result.reason})` : ''}`,
+    )
+  }
+}
+
+// find a node in the sootsim tree matching a matcher descriptor
+async function findNodeByMatcher(matcher: Matcher): Promise<any> {
+  const page = getPage()
+  if (matcher.index !== undefined) {
+    return page.evaluate(async (indexedMatcher: Matcher) => {
+      const filter =
+        indexedMatcher.type === 'id'
+          ? { hasId: indexedMatcher.value }
+          : indexedMatcher.type === 'text'
+            ? { hasText: indexedMatcher.value }
+            : indexedMatcher.type === 'label'
+              ? { hasLabel: indexedMatcher.value }
+              : indexedMatcher.type === 'role'
+                ? { hasRole: indexedMatcher.value }
+                : { type: indexedMatcher.value }
+      const results = await window.__sootsimTest!.queryAll(filter)
+      return results[indexedMatcher.index ?? 0] ?? null
+    }, matcher)
+  }
+  if (matcher.type === 'id') {
+    return page.evaluate(
+      (id: string) => window.__sootsimTest!.findByTestId(id),
+      matcher.value,
+    )
+  } else if (matcher.type === 'text') {
+    return page.evaluate(
+      (text: string) => window.__sootsimTest!.findByText(text),
+      matcher.value,
+    )
+  } else if (matcher.type === 'label') {
+    return page.evaluate(
+      (label: string) => window.__sootsimTest!.findByLabel(label),
+      matcher.value,
+    )
+  } else if (matcher.type === 'role') {
+    return page.evaluate(
+      (role: string) => window.__sootsimTest!.findByRole(role),
+      matcher.value,
+    )
+  } else if (matcher.type === 'type') {
+    return page.evaluate(async (type: string) => {
+      const results = await window.__sootsimTest!.queryAll({ type })
+      return results[0] || null
+    }, matcher.value)
+  }
+  return null
+}
+
+// get the absolute center coordinates of a node in sootsim coordinate space
+function getNodeCenter(nodeInfo: any): { x: number; y: number } {
+  return {
+    x: nodeInfo.absolutePosition.x + nodeInfo.layout.width / 2,
+    y: nodeInfo.absolutePosition.y + nodeInfo.layout.height / 2,
+  }
+}
+
+async function nodeOffsetToPage(
+  page: Page,
+  nodeInfo: any,
+  dx: number,
+  dy: number,
+): Promise<{ x: number; y: number }> {
+  const center = getNodeCenter(nodeInfo)
+  return sootsimToPage(page, center.x + dx, center.y + dy)
+}
+
+async function getDefaultTapPoint(
+  page: Page,
+  nodeInfo: any,
+): Promise<{ x: number; y: number }> {
+  const resolvedTarget = await page.evaluate(
+    (nodeId) => window.__sootsimTest?.resolveTapTarget?.(nodeId) ?? null,
+    nodeInfo.nodeId,
+  )
+  const center =
+    resolvedTarget &&
+    typeof resolvedTarget.cx === 'number' &&
+    typeof resolvedTarget.cy === 'number'
+      ? { x: resolvedTarget.cx, y: resolvedTarget.cy }
+      : getNodeCenter(nodeInfo)
+  const frame = nodeInfo.visibleFrame ?? {
+    x: nodeInfo.absolutePosition?.x ?? nodeInfo.layout?.x ?? 0,
+    y: nodeInfo.absolutePosition?.y ?? nodeInfo.layout?.y ?? 0,
+    width: nodeInfo.layout?.width ?? 0,
+    height: nodeInfo.layout?.height ?? 0,
+  }
+  const fullFrameTolerance = 0.5
+  const fullyVisible =
+    typeof nodeInfo.absolutePosition?.x === 'number' &&
+    typeof nodeInfo.absolutePosition?.y === 'number' &&
+    typeof nodeInfo.layout?.width === 'number' &&
+    typeof nodeInfo.layout?.height === 'number' &&
+    Math.abs(frame.x - nodeInfo.absolutePosition.x) <= fullFrameTolerance &&
+    Math.abs(frame.y - nodeInfo.absolutePosition.y) <= fullFrameTolerance &&
+    frame.width >= nodeInfo.layout.width - fullFrameTolerance &&
+    frame.height >= nodeInfo.layout.height - fullFrameTolerance
+  if (fullyVisible) return center
+
+  const viewport = await readSootsimInteractiveViewport(page)
+  const left = Math.max(0, frame.x)
+  const top = Math.max(0, frame.y)
+  const right = Math.min(viewport.width, frame.x + frame.width)
+  const bottom = Math.min(viewport.height, frame.y + frame.height)
+
+  if (right <= left || bottom <= top) {
+    return center
+  }
+
+  return {
+    x: left + (right - left) / 2,
+    y: top + (bottom - top) / 2,
+  }
+}
+
+async function dispatchTapAtSootsimPoint(page: Page, x: number, y: number) {
+  await page.evaluate(
+    async ({ x, y }) => {
+      const interactTap = window.SootSim?.bridges?.interact?.tap
+      if (typeof interactTap === 'function') {
+        const result = await interactTap(x, y)
+        if (result && (typeof result !== 'object' || result.hit !== false)) return
+      }
+      const tap = window.__sootsimTest?.tap
+      if (typeof tap !== 'function') {
+        throw new Error('sootsim tap bridge is not installed')
+      }
+      await tap(x, y)
+    },
+    { x, y },
+  )
+}
+
+async function isFocusedTextInputNode(page: Page, nodeInfo: any): Promise<boolean> {
+  const focused = await page.evaluate(
+    () => window.__sootsimTest!.getFocusedNode?.() ?? null,
+  )
+  return !!focused && typeof focused === 'object' && focused.nodeId === nodeInfo?.nodeId
+}
+
+async function focusElementForTextEntry(el: SootSimElement): Promise<void> {
+  const page = getPage()
+  const node = await findNodeByMatcher(el._matcher)
+  if (!node) {
+    throw new Error(`element not found for text entry: ${JSON.stringify(el._matcher)}`)
+  }
+  if (await isFocusedTextInputNode(page, node)) return
+  await el.tap()
+  await page.waitForTimeout(100)
+}
+
+function ensureScreenshotDir() {
+  if (!fs.existsSync(SCREENSHOT_DIR)) {
+    fs.mkdirSync(SCREENSHOT_DIR, { recursive: true })
+  }
+}
+
+function decodePngDataUrl(dataUrl: string): Buffer {
+  const match = /^data:image\/png;base64,(.+)$/.exec(dataUrl)
+  if (!match) {
+    throw new Error(
+      `sootsim screenshot bridge returned a non-png payload: ${JSON.stringify(dataUrl.slice(0, 120))}`,
+    )
+  }
+  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
+// which is ideal for settled screenshots but blocks for the full timeout
+// while an animation is running.
+async function captureSootsimPngFast(opts?: {
+  crop?: { h: number; w: number; x: number; y: number }
+}) {
+  const page = getPage()
+  const dataUrl = await page.evaluate(
+    async (captureOpts) => {
+      const screenshot = (window as { SootSim?: { bridges?: { screenshot?: unknown } } })
+        .SootSim?.bridges?.screenshot as ((opts?: unknown) => Promise<string>) | undefined
+      if (typeof screenshot !== 'function') {
+        throw new Error('sootsim screenshot bridge is not installed')
+      }
+      return screenshot(captureOpts)
+    },
+    { crop: opts?.crop, format: 'png' },
+  )
+  if (!dataUrl) {
+    throw new Error('sootsim screenshot bridge returned an empty image')
+  }
+  return decodePngDataUrl(dataUrl)
+}
+
+async function captureSootsimPng(opts?: {
+  crop?: { h: number; w: number; x: number; y: number }
+}) {
+  const page = getPage()
+  // frame-stability poll: capture twice with a gap > one tenant live-blur
+  // push interval (~67ms) and accept only when both PNGs are byte-equal.
+  // PNGs from canvas.toDataURL are deterministic for stable RGBA, so byte-
+  // equal = pixel-equal. without this, the keyboard's blur stream and the
+  // text-input cursor blink produce 1-12pp frame-to-frame variance in
+  // captures fired blindly after a settle, which then drifts the published
+  // proof manifest. matches the same poll in scripts/conformance-fast-iter.ts
+  // so cron and publish lock onto the same stable frame.
+  const result: {
+    dataUrl: string
+    stable: boolean
+    attempts: number
+    elapsedMs: number
+  } = await page.evaluate(
+    async (captureOpts) => {
+      const screenshot = (window as { SootSim?: { bridges?: { screenshot?: unknown } } })
+        .SootSim?.bridges?.screenshot as ((opts?: unknown) => Promise<string>) | undefined
+      if (typeof screenshot !== 'function') {
+        throw new Error('sootsim screenshot bridge is not installed')
+      }
+      const gapMs = 100
+      const maxWaitMs = 8000
+      const minAttempts = 3
+      const t0 = Date.now()
+      let prev = await screenshot(captureOpts)
+      let attempts = 1
+      while (attempts < minAttempts || Date.now() - t0 < maxWaitMs) {
+        await new Promise((r) => setTimeout(r, gapMs))
+        const next = await screenshot(captureOpts)
+        attempts++
+        if (next === prev) {
+          return {
+            dataUrl: next,
+            stable: true,
+            attempts,
+            elapsedMs: Date.now() - t0,
+          }
+        }
+        prev = next
+      }
+      return { dataUrl: prev, stable: false, attempts, elapsedMs: Date.now() - t0 }
+    },
+    {
+      crop: opts?.crop,
+      format: 'png',
+    },
+  )
+  if (!result.dataUrl) {
+    throw new Error('sootsim screenshot bridge returned an empty image')
+  }
+  if (!result.stable) {
+    console.warn(
+      `[sootsim-detox] screenshot did not stabilize after ${result.elapsedMs}ms (${result.attempts} captures); using last frame`,
+    )
+  }
+  return decodePngDataUrl(result.dataUrl)
+}
+
+async function writeSootsimScreenshot(
+  name: string,
+  opts?: { crop?: { h: number; w: number; x: number; y: number } },
+) {
+  ensureScreenshotDir()
+  const screenshotPath = path.join(SCREENSHOT_DIR, `${name}.png`)
+  fs.writeFileSync(screenshotPath, await captureSootsimPng(opts))
+  return screenshotPath
+}
+
+async function dispatchStatusBarOverride(config: StatusBarConfig) {
+  const page = getPage()
+  const time =
+    typeof config.time === 'string' && config.time.length > 0 ? config.time : null
+  await page.evaluate(
+    ({ eventType, time }) => {
+      window.dispatchEvent(
+        new CustomEvent(eventType, {
+          detail: { time },
+        }),
+      )
+    },
+    { eventType: STATUS_BAR_OVERRIDE_EVENT, time },
+  )
+  await page.waitForTimeout(50)
+}
+
+async function dispatchSootsimEventInPage<K extends SootsimEventName>(
+  type: K,
+  detail: SootsimEventMap[K],
+) {
+  const page = getPage()
+  await page.evaluate(
+    ({ detail, type }) => {
+      window.dispatchEvent(new CustomEvent(type, { detail }))
+    },
+    { detail, type },
+  )
+}
+
+function createSootSimElement(matcher: Matcher): SootSimElement {
+  const el: SootSimElement = {
+    _matcher: matcher,
+
+    async tap(point) {
+      const page = getPage()
+      await waitForSootsimWorkletsIdle(page, 3000)
+      const node = await findNodeByMatcher(matcher)
+      if (!node) throw new Error(`element not found for tap: ${JSON.stringify(matcher)}`)
+      const defaultPoint = point ? null : await getDefaultTapPoint(page, node)
+      const targetSootSimX =
+        typeof point?.x === 'number'
+          ? node.absolutePosition.x + point.x
+          : (defaultPoint?.x ?? node.absolutePosition.x + node.layout.width / 2)
+      const targetSootSimY =
+        typeof point?.y === 'number'
+          ? node.absolutePosition.y + point.y
+          : (defaultPoint?.y ?? node.absolutePosition.y + node.layout.height / 2)
+      await dispatchTapAtSootsimPoint(page, targetSootSimX, targetSootSimY)
+      if (_synchronizationEnabled) {
+        await waitForSootsimIdle(page)
+      }
+    },
+
+    async multiTap(times: number) {
+      // detox iOS multiTap performs N taps with the system's natural double-
+      // tap pause. UITapGestureRecognizer treats taps within ~250ms as a
+      // multi-tap. emit each tap as a discrete down/up at the same node
+      // center with a small inter-tap pause that stays inside RNGH's
+      // default maxDelay window of 200ms.
+      const page = getPage()
+      const node = await findNodeByMatcher(matcher)
+      if (!node)
+        throw new Error(`element not found for multiTap: ${JSON.stringify(matcher)}`)
+      const center = getNodeCenter(node)
+      const pageCoords = await sootsimToPage(page, center.x, center.y)
+
+      for (let i = 0; i < times; i++) {
+        await page.mouse.move(pageCoords.x, pageCoords.y)
+        await page.mouse.down()
+        await page.waitForTimeout(50)
+        await page.mouse.up()
+        if (i < times - 1) {
+          await page.waitForTimeout(80)
+        }
+      }
+      await page.waitForTimeout(80)
+    },
+
+    async longPress(duration = 1000) {
+      const page = getPage()
+      const node = await findNodeByMatcher(matcher)
+      if (!node)
+        throw new Error(`element not found for longPress: ${JSON.stringify(matcher)}`)
+      const center = getNodeCenter(node)
+      await page.evaluate(
+        async ({ duration, x, y }) => {
+          const longPress = window.SootSim?.bridges?.interact?.longPress
+          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}`)
+          }
+        },
+        { duration, x: center.x, y: center.y },
+      )
+      await page.waitForTimeout(50)
+    },
+
+    async longPressAndDrag(
+      duration: number,
+      normalizedStartX: number,
+      normalizedStartY: number,
+      targetElement: SootSimElement,
+      normalizedEndX: number,
+      normalizedEndY: number,
+      speed = 'fast',
+      holdDuration = 0,
+    ) {
+      const page = getPage()
+      // resolve source element
+      const srcNode = await findNodeByMatcher(matcher)
+      if (!srcNode)
+        throw new Error(`source element not found: ${JSON.stringify(matcher)}`)
+
+      // resolve target element
+      const tgtNode = await findNodeByMatcher(targetElement._matcher)
+      if (!tgtNode)
+        throw new Error(
+          `target element not found: ${JSON.stringify(targetElement._matcher)}`,
+        )
+
+      // compute start and end in sootsim coords
+      const startSootSimX =
+        srcNode.absolutePosition.x + srcNode.layout.width * normalizedStartX
+      const startSootSimY =
+        srcNode.absolutePosition.y + srcNode.layout.height * normalizedStartY
+      const endSootSimX =
+        tgtNode.absolutePosition.x + tgtNode.layout.width * normalizedEndX
+      const endSootSimY =
+        tgtNode.absolutePosition.y + tgtNode.layout.height * normalizedEndY
+
+      const startPage = await sootsimToPage(page, startSootSimX, startSootSimY)
+      const endPage = await sootsimToPage(page, endSootSimX, endSootSimY)
+      const steps = speed === 'slow' ? 20 : 10
+
+      // 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
+      const dx = (endPage.x - startPage.x) / steps
+      const dy = (endPage.y - startPage.y) / steps
+      for (let i = 1; i <= steps; i++) {
+        await page.mouse.move(startPage.x + dx * i, startPage.y + dy * i)
+        await page.waitForTimeout(speed === 'slow' ? 30 : 10)
+      }
+
+      await page.mouse.up()
+      await page.waitForTimeout(50)
+    },
+
+    async typeText(text: string) {
+      const page = getPage()
+      await focusElementForTextEntry(el)
+      await page.keyboard.type(text)
+    },
+
+    async replaceText(text: string) {
+      const page = getPage()
+      await focusElementForTextEntry(el)
+      const node = await findNodeByMatcher(matcher)
+      const value = typeof node?.text === 'string' ? node.text : ''
+      for (let i = 0; i < value.length; i++) {
+        await page.keyboard.press('Backspace')
+      }
+      await page.keyboard.type(text)
+    },
+
+    async clearText() {
+      const page = getPage()
+      await focusElementForTextEntry(el)
+      const node = await findNodeByMatcher(matcher)
+      const value = typeof node?.text === 'string' ? node.text : ''
+      for (let i = 0; i < value.length; i++) {
+        await page.keyboard.press('Backspace')
+      }
+    },
+
+    async scroll(pixels: number, direction: 'up' | 'down' | 'left' | 'right') {
+      const node = await findNodeByMatcher(matcher)
+      if (!node)
+        throw new Error(`element not found for scroll: ${JSON.stringify(matcher)}`)
+      const page = getPage()
+      await dragScrollNode(page, node, pixels, direction)
+    },
+
+    async scrollTo(edge: 'top' | 'bottom' | 'left' | 'right') {
+      const node = await findNodeByMatcher(matcher)
+      if (!node)
+        throw new Error(`element not found for scrollTo: ${JSON.stringify(matcher)}`)
+
+      const targetId =
+        typeof node.testID === 'string' && node.testID
+          ? node.testID
+          : typeof node.id === 'string' && node.id
+            ? node.id
+            : null
+      if (!targetId) {
+        throw new Error(
+          `scrollTo requires an id-backed scroll view: ${JSON.stringify(matcher)}`,
+        )
+      }
+
+      const hitX = node.absolutePosition.x + node.layout.width / 2
+      const hitY = node.absolutePosition.y + node.layout.height / 2
+      const page = getPage()
+      const result = await page.evaluate(
+        async ({ edge, hitX, hitY, targetId }) => {
+          const bridge = window.__sootsimTest
+          if (!bridge?.getScrollStateAt || !bridge.scrollTo) {
+            return { ok: false, reason: 'scroll bridge unavailable' }
+          }
+
+          const state = await bridge.getScrollStateAt(hitX, hitY)
+          if (!state) return { ok: false, reason: 'scroll state not found' }
+
+          const maxOffset =
+            state.maxOffset && typeof state.maxOffset === 'object'
+              ? (state.maxOffset as { x?: number; y?: number })
+              : null
+          const offset =
+            state.offset && typeof state.offset === 'object'
+              ? (state.offset as { x?: number; y?: number })
+              : null
+          const maxX =
+            typeof state.maxOffsetX === 'number' ? state.maxOffsetX : (maxOffset?.x ?? 0)
+          const maxY =
+            typeof state.maxOffsetY === 'number' ? state.maxOffsetY : (maxOffset?.y ?? 0)
+          const currentX =
+            typeof state.offsetX === 'number' ? state.offsetX : (offset?.x ?? 0)
+          const currentY =
+            typeof state.offsetY === 'number' ? state.offsetY : (offset?.y ?? 0)
+
+          const x = edge === 'left' ? 0 : edge === 'right' ? maxX : currentX
+          const y = edge === 'top' ? 0 : edge === 'bottom' ? maxY : currentY
+          return bridge.scrollTo(targetId, x, y, false)
+        },
+        { edge, hitX, hitY, targetId },
+      )
+
+      if (!result?.ok) {
+        throw new Error(
+          `scrollTo(${edge}) failed for ${targetId}: ${result?.reason ?? 'unknown error'}`,
+        )
+      }
+
+      await page.evaluate(
+        () =>
+          new Promise<void>((resolve) => {
+            requestAnimationFrame(() => resolve())
+          }),
+      )
+      if (_synchronizationEnabled) {
+        await waitForSootsimIdle(page)
+      }
+    },
+
+    async swipe(
+      direction: 'up' | 'down' | 'left' | 'right',
+      speed: 'fast' | 'slow' = 'fast',
+      percentage = 0.75,
+      normalizedStartingPointX = 0.5,
+      normalizedStartingPointY = 0.5,
+    ) {
+      const node = await findNodeByMatcher(matcher)
+      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
+      const startSootSimY = absolutePosition.y + layout.height * normalizedStartingPointY
+
+      let endSootSimX = startSootSimX
+      let endSootSimY = startSootSimY
+      const viewport = await readSootsimViewport(page)
+      const dist =
+        direction === 'up' || direction === 'down'
+          ? viewport.height * percentage
+          : viewport.width * percentage
+
+      switch (direction) {
+        case 'up':
+          endSootSimY -= dist
+          break
+        case 'down':
+          endSootSimY += dist
+          break
+        case 'left':
+          endSootSimX -= dist
+          break
+        case 'right':
+          endSootSimX += dist
+          break
+      }
+
+      // detox injects one point per display-link tick. its fast path contains
+      // 21 points and its slow path 41, including the endpoints.
+      const steps = speed === 'slow' ? 40 : 20
+      const stepDelay = 1000 / 60
+
+      await page.evaluate(
+        async ({ fromX, fromY, toX, toY, steps, stepMs }) => {
+          // the interact bridge, not __sootsimTest.drag. the test bridge's drag
+          // runs the whole down/move/up loop through the tenant's own
+          // dispatchPointer and never fans to the shell, where gesture-handler's
+          // recognizers live, so a swipe reported exact-zero activations for
+          // every pan, fling, and manual gesture. taps were unaffected because
+          // the responder path is tenant-local. the interact bridge resolves the
+          // owner and feeds both, which is why the cases that call it directly
+          // pass.
+          const drag = window.__sootsimInteract?.drag
+          if (typeof drag !== 'function') {
+            throw new Error('sootsim interact bridge is not installed')
+          }
+          await drag(fromX, fromY, toX, toY, steps, stepMs)
+        },
+        {
+          fromX: startSootSimX,
+          fromY: startSootSimY,
+          toX: endSootSimX,
+          toY: endSootSimY,
+          steps,
+          stepMs: stepDelay,
+        },
+      )
+      await page.waitForTimeout(100)
+    },
+
+    async setColumnToValue(column: number, value: string) {
+      if (!Number.isInteger(column) || column < 0) {
+        throw new Error(`picker column must be a non-negative integer, got ${column}`)
+      }
+      if (typeof value !== 'string') {
+        throw new Error(`picker value must be a string, got ${typeof value}`)
+      }
+
+      const picker = await findNodeByMatcher(matcher)
+      if (!picker) {
+        throw new Error(
+          `element not found for setColumnToValue: ${JSON.stringify(matcher)}`,
+        )
+      }
+
+      const page = getPage()
+      const candidates = await page.evaluate(
+        async ({ picker, column, value }) => {
+          const result = await window.__sootsimTest?.queryTextCandidates?.({
+            query: value,
+            exact: true,
+          })
+          if (!result || !Array.isArray(result.candidates)) return []
+          const left = picker.absolutePosition.x
+          const top = picker.absolutePosition.y
+          const right = left + picker.layout.width
+          const bottom = top + picker.layout.height
+          return result.candidates
+            .filter((candidate) => candidate.ancestorPickerColumnIndices.includes(column))
+            .map((candidate) => candidate.info)
+            .filter((candidate) => {
+              const x = candidate.absolutePosition?.x
+              const y = candidate.absolutePosition?.y
+              const width = candidate.layout?.width
+              const height = candidate.layout?.height
+              if (
+                typeof x !== 'number' ||
+                typeof y !== 'number' ||
+                typeof width !== 'number' ||
+                typeof height !== 'number'
+              ) {
+                return false
+              }
+              const centerX = x + width / 2
+              const centerY = y + height / 2
+              return (
+                centerX >= left && centerX <= right && centerY >= top && centerY <= bottom
+              )
+            })
+        },
+        { picker, column, value },
+      )
+
+      if (candidates.length !== 1) {
+        throw new Error(
+          `setColumnToValue(${column}, ${JSON.stringify(value)}) found ${candidates.length} matching rows inside ${JSON.stringify(matcher)}`,
+        )
+      }
+
+      const target = candidates[0]
+      // detox selects the picker row, whose hit rectangle stays flat. the
+      // label is visually projected around the wheel and can overlap a later
+      // label near the cylinder edge.
+      const tapTarget = await page.evaluate(
+        async (nodeId) => window.__sootsimTest?.resolveTapTarget(nodeId),
+        target.nodeId,
+      )
+      if (!tapTarget) {
+        throw new Error(
+          `setColumnToValue(${column}, ${JSON.stringify(value)}) could not resolve its picker row`,
+        )
+      }
+      await dispatchTapAtSootsimPoint(
+        page,
+        tapTarget.target.absolutePosition.x + tapTarget.target.layout.width / 2,
+        tapTarget.target.absolutePosition.y + tapTarget.target.layout.height / 2,
+      )
+    },
+
+    async pinch(scale: number, speed: 'fast' | 'slow' = 'fast', angle: number = 0) {
+      // detox iOS pinch: scale > 1 spreads fingers (zoom in), scale < 1
+      // brings them together (zoom out). speed maps to step delay so RNGH's
+      // velocity tracking sees a realistic delta. angle (radians) tilts the
+      // pinch axis off horizontal — matches Detox's third arg.
+      const page = getPage()
+      const node = await findNodeByMatcher(matcher)
+      if (!node)
+        throw new Error(`element not found for pinch: ${JSON.stringify(matcher)}`)
+      await waitForSootsimGestureHandler(page, node.nodeId, 'PinchGestureHandler')
+      const startSpread = Math.min(
+        60,
+        Math.max(12, Math.min(node.layout.width, node.layout.height) * 0.25),
+      )
+      const endSpread = startSpread * Math.max(scale, 0.05)
+      const cos = Math.cos(angle)
+      const sin = Math.sin(angle)
+      const offset = (d: number) => ({ dx: d * cos, dy: d * sin })
+      const a0 = offset(-startSpread)
+      const b0 = offset(startSpread)
+      const a1 = offset(-endSpread)
+      const b1 = offset(endSpread)
+      await dispatchTwoFingerGesture(
+        page,
+        await nodeOffsetToPage(page, node, a0.dx, a0.dy),
+        await nodeOffsetToPage(page, node, b0.dx, b0.dy),
+        await nodeOffsetToPage(page, node, a1.dx, a1.dy),
+        await nodeOffsetToPage(page, node, b1.dx, b1.dy),
+        { steps: speed === 'fast' ? 4 : 12, stepDelayMs: speed === 'fast' ? 18 : 24 },
+      )
+    },
+
+    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).
+      const page = getPage()
+      const node = await findNodeByMatcher(matcher)
+      if (!node)
+        throw new Error(`element not found for rotate: ${JSON.stringify(matcher)}`)
+      await waitForSootsimGestureHandler(page, node.nodeId, 'RotationGestureHandler')
+      const radius = Math.min(
+        60,
+        Math.max(12, Math.min(node.layout.width, node.layout.height) * 0.25),
+      )
+      const startA = await nodeOffsetToPage(page, node, -radius, 0)
+      const startB = await nodeOffsetToPage(page, node, radius, 0)
+      const cos = Math.cos(radians)
+      const sin = Math.sin(radians)
+      const endA = await nodeOffsetToPage(page, node, -radius * cos, -radius * sin)
+      const endB = await nodeOffsetToPage(page, node, radius * cos, radius * sin)
+      await dispatchTwoFingerGesture(page, startA, startB, endA, endB, {
+        steps: speed === 'fast' ? 10 : 20,
+        stepDelayMs: speed === 'fast' ? 14 : 24,
+      })
+    },
+
+    async takeScreenshot(name: string): Promise<string> {
+      const node = await findNodeByMatcher(matcher)
+      if (!node)
+        throw new Error(
+          `element not found for takeScreenshot: ${JSON.stringify(matcher)}`,
+        )
+
+      const box = node.frame ?? {
+        x: node.absolutePosition.x,
+        y: node.absolutePosition.y,
+        width: node.layout.width,
+        height: node.layout.height,
+      }
+      return writeSootsimScreenshot(name, {
+        crop: {
+          x: box.x,
+          y: box.y,
+          w: box.width,
+          h: box.height,
+        },
+      })
+    },
+
+    async getAttributes(): Promise<any> {
+      const node = await findNodeByMatcher(matcher)
+      if (!node)
+        throw new Error(`element not found for getAttributes: ${JSON.stringify(matcher)}`)
+      return {
+        text: node.text || '',
+        label: node.accessibilityLabel || node.text || '',
+        identifier: node.testID || node.id || '',
+        visible: node.layout.width > 0 && node.layout.height > 0,
+        enabled: !node.accessibilityState?.disabled,
+        ...node,
+      }
+    },
+
+    atIndex(index: number) {
+      return createSootSimElement({ ...matcher, index })
+    },
+  }
+
+  return el
+}
+
+// element() factory -- takes a matcher and returns an element interaction object
+export function element(matcher: Matcher): SootSimElement {
+  return createSootSimElement(matcher)
+}
+
+// device object -- app lifecycle
+export const device = {
+  _currentUrl: '',
+  _platform: DETOX_PLATFORM as 'ios' | 'android',
+
+  async launchApp(opts?: {
+    delete?: boolean
+    newInstance?: boolean
+    url?: string
+    launchArgs?: Record<string, any>
+    // when set, the new BrowserContext records video at this dir. used by
+    // captureProofMenuStages for the multi-stage animation diff path. must
+    // be set at launchApp time because playwright recordVideo can't be
+    // toggled on an existing context.
+    recordVideoDir?: string
+  }) {
+    if (!_browser) {
+      // Conformance renders CanvasKit and must use the real platform GPU. The
+      // bundled chromium_headless_shell has no GPU and silently falls back to
+      // SwiftShader, invalidating visual/perf results while pegging the box.
+      // The canonical GPU args force Metal/Vulkan and stripping Playwright's
+      // --enable-unsafe-swiftshader default makes GPU init fail loudly. The
+      // scoped reaper owns the whole Chrome process tree if Detox is interrupted.
+      const launched = await launchReapedChromeScoped(
+        (options) => chromium.launch(options),
+        { headless: true },
+      )
+      _browser = launched.browser
+      _reapBrowserNow = launched.reapNow
+    }
+
+    if (!_page || opts?.newInstance || opts?.delete || opts?.recordVideoDir) {
+      await closeContext()
+      const contextOpts: Parameters<NonNullable<typeof _browser>['newContext']>[0] = {
+        hasTouch: true,
+        viewport: { width: 500, height: 900 },
+      }
+      if (opts?.recordVideoDir) {
+        fs.mkdirSync(opts.recordVideoDir, { recursive: true })
+        contextOpts.recordVideo = {
+          dir: opts.recordVideoDir,
+          size: { width: 500, height: 900 },
+        }
+      }
+      _context = await _browser.newContext(contextOpts)
+      _page = await _context.newPage()
+      attachPageDiagnostics(_page)
+    }
+
+    const url = opts?.url || BASE_URL
+    device._currentUrl = url
+    await _page!.goto(url, { waitUntil: 'load', timeout: 30000 })
+
+    await waitForSootsimTree(_page!, 30000)
+    await waitForSootsimSurfaceMetrics(_page!, 30000)
+    await waitForSootsimShellReady(_page!, 30000)
+    await waitForSootsimWorkletsIdle(_page!, 3000)
+    // record the wall-clock time the page is ready — captureProofMenuStages
+    // uses this to compute trigger-in-video offsets
+    device._lastReadyAtMs = Date.now()
+  },
+
+  _lastReadyAtMs: 0,
+
+  async reloadReactNative() {
+    const page = getPage()
+    await page.reload({ waitUntil: 'load', timeout: 30000 })
+    await waitForSootsimTree(page, 30000)
+    await waitForSootsimSurfaceMetrics(page, 30000)
+    await waitForSootsimShellReady(page, 30000)
+    await waitForSootsimWorkletsIdle(page, 3000)
+  },
+
+  async terminateApp() {
+    await closeBrowser()
+  },
+
+  async installApp() {
+    // no-op for sootsim -- app runs in browser
+  },
+
+  async uninstallApp() {
+    // no-op
+  },
+
+  async openURL(url: { url: string; sourceApp?: string }) {
+    const page = getPage()
+    await page.goto(url.url, { waitUntil: 'load', timeout: 30000 })
+    await waitForSootsimTree(page, 10000)
+    await waitForSootsimSurfaceMetrics(page, 10000)
+    await waitForSootsimShellReady(page, 10000)
+    await waitForSootsimWorkletsIdle(page, 3000)
+  },
+
+  async takeScreenshot(name: string): Promise<string> {
+    return writeSootsimScreenshot(name)
+  },
+
+  // single-shot variant for multi-stage animation captures. skips the
+  // frame-stability poll so callers can sample mid-transition.
+  async takeScreenshotFast(name: string): Promise<string> {
+    ensureScreenshotDir()
+    const screenshotPath = path.join(SCREENSHOT_DIR, `${name}.png`)
+    fs.writeFileSync(screenshotPath, await captureSootsimPngFast())
+    return screenshotPath
+  },
+
+  // record the SootSim canvas via the engine's headless recorder
+  // (window.__sootsimRecorder — @sootsim/plugin-recording). this is the
+  // SAME code path `sootsim record video` drives, NOT the rail-button
+  // path (SootSim.bridges.startRecording wires the dialog state machine
+  // and never stashes the resulting blob into __sootsimRecorder.lastBlob,
+  // which is what getBlobBase64 streams from).
+  //
+  // unlike playwright's page-level recordVideo, the headless recorder
+  // captures ONLY the device canvas (composited shell + tenant surfaces)
+  // — no browser chrome, no menu bar, no device frame. uses the EXISTING
+  // page/context so per-test state is preserved across capture.
+  async startBridgeRecording(opts?: {
+    durationMs?: number
+    layers?: 'full' | 'tenant' | 'shell'
+    fps?: number
+  }): Promise<void> {
+    const page = getPage()
+    const startOpts = {
+      format: 'webm' as const,
+      fps: opts?.fps ?? 60,
+      layers: opts?.layers ?? 'tenant',
+      durationMs: opts?.durationMs ?? 5000,
+    }
+    const result = await page.evaluate(async (startOpts) => {
+      const rec = (
+        window as {
+          __sootsimRecorder?: {
+            start?: (
+              o: unknown,
+            ) => Promise<{ ok: boolean; error?: string; format?: string }>
+          }
+        }
+      ).__sootsimRecorder
+      const start = rec?.start
+      if (typeof start !== 'function') {
+        return { ok: false, error: '__sootsimRecorder.start not installed' }
+      }
+      return start(startOpts)
+    }, startOpts)
+    if (!result.ok) {
+      throw new Error(`startBridgeRecording failed: ${result.error ?? 'unknown'}`)
+    }
+  },
+
+  // stop the headless recorder, stream the resulting blob in chunks (same
+  // protocol as `sootsim record`), and write the webm to outPath.
+  async stopAndSaveBridgeRecording(outPath: string): Promise<string> {
+    const page = getPage()
+    const stopResult = await page.evaluate(async () => {
+      const rec = (
+        window as {
+          __sootsimRecorder?: {
+            stop?: () => Promise<{
+              ok: boolean
+              error?: string
+              size?: number
+              mime?: string
+              durationMs?: number
+            }>
+          }
+        }
+      ).__sootsimRecorder
+      const stop = rec?.stop
+      if (typeof stop !== 'function') {
+        return { ok: false, error: '__sootsimRecorder.stop not installed' }
+      }
+      return stop()
+    })
+    if (!stopResult.ok) {
+      throw new Error(`stopBridgeRecording failed: ${stopResult.error ?? 'unknown'}`)
+    }
+    if (!stopResult.size) {
+      throw new Error('stopBridgeRecording: recorder returned empty blob')
+    }
+    const chunks: Buffer[] = []
+    let offset = 0
+    const CHUNK = 2 * 1024 * 1024
+    while (true) {
+      const result: {
+        data: string
+        size: number
+        offset: number
+        done: boolean
+        mime: string
+      } | null = await page.evaluate(
+        ({ offset, chunk }) => {
+          const rec = (window as { __sootsimRecorder?: { getBlobBase64?: unknown } })
+            .__sootsimRecorder
+          const get = rec?.getBlobBase64 as
+            | ((args: { offset: number; chunk: number }) => Promise<{
+                data: string
+                size: number
+                offset: number
+                done: boolean
+                mime: string
+              } | null>)
+            | undefined
+          if (typeof get !== 'function') return null
+          return get({ offset, chunk })
+        },
+        { offset, chunk: CHUNK },
+      )
+      if (!result) throw new Error('rnx recorder produced no blob')
+      chunks.push(Buffer.from(result.data, 'base64'))
+      offset = result.offset
+      if (result.done) break
+    }
+    fs.mkdirSync(path.dirname(outPath), { recursive: true })
+    fs.writeFileSync(outPath, Buffer.concat(chunks))
+    ;(this as { _lastRecordingPath?: string })._lastRecordingPath = outPath
+    return outPath
+  },
+
+  _lastRecordingPath: '' as string,
+
+  // set the engine's ContextMenu animation-progress override. visual-proof
+  // harnesses use this to drive each capture stage to a known animProgress
+  // (matched against the iOS oracle's curve) instead of fighting capture
+  // latency vs. sub-second spring timing. pass null to clear.
+  //
+  // dispatches a host CustomEvent that the engine forwards to the tenant
+  // worker (see shell-event-registry.ts + input-bridge.ts handleShellEvent).
+  // the worker writes globalThis.__sootsimMenuAnimOverride which the engine
+  // ContextMenu reads each rAF tick.
+  async setMenuAnimOverride(progress: number | null): Promise<void> {
+    // dispatched from the playwright host; the typed `dispatchSootsimEvent`
+    // helper lives in the engine bundle and isn't reachable from outside
+    // the page. keep this host-side wrapper typed against SootsimEventMap so
+    // the event names and payload shapes still come from the central registry.
+    await dispatchSootsimEventInPage('sootsim:menuAnimOverride', { value: progress })
+  },
+
+  // 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('rnx 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('rnx motion change definition is not installed')
+        }
+
+        const captureBitmap = async () => {
+          const { canvas } = await live.captureFresh()
+          if (!canvas) throw new Error('rnx 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('rnx 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('rnx 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('rnx 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('rnx 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(
+              `rnx motion had no visible change before ${input.detectionTimeoutMs}ms`,
+            )
+          }
+
+          const snapshots: Snapshot[] = []
+          for (const stage of input.stages) {
+            if (state.cancelled) throw new Error('rnx 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('rnx 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
+  // schedules a setTimeout at its requested offsetMs and at that moment
+  // SYNCHRONOUSLY snapshots the engine's `liveComposite` host-side canvas
+  // (drawImage from the worker-transferred home + overlay canvases). PNG
+  // encoding is queued after all snapshots land — encoding stalls don't
+  // contaminate the animation window.
+  //
+  // unlike `takeScreenshotStages`, this does NOT go through screenshot()
+  // (which calls forceRenderAll + composite + toDataURL serially at
+  // 300-1300ms per call and blows the spring-open timing). the worker's
+  // vsync-pumped rAF keeps the home canvas fresh; we just sample it.
+  //
+  // returns paths in stage order; actualMs reports when the snapshot
+  // actually fired (typically within a few ms of offsetMs).
+  async takeScreenshotStagesFast(
+    namePrefix: string,
+    stages: Array<{ label: string; offsetMs: number }>,
+    options?: { skipWarmup?: boolean },
+  ): Promise<Array<{ label: string; offsetMs: number; actualMs: number; path: string }>> {
+    const page = getPage()
+    const frames: Array<{
+      label: string
+      offsetMs: number
+      actualMs: number
+      dataUrl: string
+    }> = await page.evaluate(
+      async (input) => {
+        const sim = window as {
+          SootSim?: {
+            bridges?: {
+              screenshot?: (opts?: unknown) => Promise<string>
+              liveComposite?: {
+                captureFresh: () => Promise<{
+                  canvas: HTMLCanvasElement | null
+                  frameToken: number
+                }>
+              }
+            }
+          }
+        }
+        const screenshot = sim.SootSim?.bridges?.screenshot
+        const live = sim.SootSim?.bridges?.liveComposite
+        if (typeof screenshot !== 'function') {
+          throw new Error('rnx screenshot bridge is not installed')
+        }
+        // initial warm-up: ensure the worker has produced at least one
+        // frame after the menu's portal mount before we start sampling.
+        // (a pump at higher cadence was tried and starved tap propagation —
+        // the tenant React commit for setOpen never landed between
+        // forceRender calls.)
+        if (!input.skipWarmup) {
+          await screenshot({ format: 'png' })
+        }
+        const start = performance.now()
+        type Snapshot = {
+          label: string
+          offsetMs: number
+          actualMs: number
+          dataUrl: string | null
+        }
+        // each stage fires at its requested offset and SYNCHRONOUSLY
+        // snapshots the engine's host-side composite canvas (drawImage
+        // from the worker-transferred home canvas + overlay). encoding
+        // happens after — encoding stalls don't disturb the next stage's
+        // capture moment.
+        const snaps: Snapshot[] = await Promise.all(
+          input.stages.map(
+            (stage) =>
+              new Promise<Snapshot>((resolve) => {
+                const fire = async () => {
+                  const actualMs = performance.now() - start
+                  try {
+                    let dataUrl: string | null = null
+                    if (live && typeof live.captureFresh === 'function') {
+                      // synchronous paint of current canvas state — no
+                      // worker round-trip. the background pump keeps the
+                      // canvas fresh.
+                      const { canvas } = await live.captureFresh()
+                      if (canvas) {
+                        const bmp = await createImageBitmap(canvas)
+                        const enc = document.createElement('canvas')
+                        enc.width = bmp.width
+                        enc.height = bmp.height
+                        const ctx = enc.getContext('2d')
+                        if (ctx) {
+                          ctx.drawImage(bmp, 0, 0)
+                          dataUrl = enc.toDataURL('image/png')
+                        }
+                        bmp.close()
+                      }
+                    }
+                    if (!dataUrl) {
+                      dataUrl = await screenshot({ format: 'png' })
+                    }
+                    resolve({
+                      label: stage.label,
+                      offsetMs: stage.offsetMs,
+                      actualMs,
+                      dataUrl,
+                    })
+                  } catch {
+                    resolve({
+                      label: stage.label,
+                      offsetMs: stage.offsetMs,
+                      actualMs,
+                      dataUrl: null,
+                    })
+                  }
+                }
+                setTimeout(
+                  () => {
+                    void fire()
+                  },
+                  Math.max(0, stage.offsetMs),
+                )
+              }),
+          ),
+        )
+        const out: Array<{
+          label: string
+          offsetMs: number
+          actualMs: number
+          dataUrl: string
+        }> = []
+        for (const snap of snaps) {
+          if (!snap.dataUrl) continue
+          out.push({
+            label: snap.label,
+            offsetMs: snap.offsetMs,
+            actualMs: snap.actualMs,
+            dataUrl: snap.dataUrl,
+          })
+        }
+        return out
+      },
+      { stages, skipWarmup: options?.skipWarmup === true },
+    )
+    return writeFastScreenshotFrames(namePrefix, frames)
+  },
+
+  // batched multi-stage capture for animation diffs. all N captures happen
+  // inside one page.evaluate round trip so browser-side timing controls the
+  // offsets — sidesteps the ~300ms per-call bridge overhead that blows
+  // sub-second animation windows. each stage gets a screenshot at the
+  // requested offsetMs (from when the evaluate starts, i.e. right after
+  // trigger() returns). returns absolute paths in stage order.
+  async takeScreenshotStages(
+    namePrefix: string,
+    stages: Array<{ label: string; offsetMs: number }>,
+  ): Promise<Array<{ label: string; offsetMs: number; actualMs: number; path: string }>> {
+    const page = getPage()
+    const frames: Array<{
+      label: string
+      offsetMs: number
+      actualMs: number
+      dataUrl: string
+    }> = await page.evaluate(
+      async (input) => {
+        const screenshot = (
+          window as { SootSim?: { bridges?: { screenshot?: unknown } } }
+        ).SootSim?.bridges?.screenshot as
+          | ((opts?: unknown) => Promise<string>)
+          | undefined
+        if (typeof screenshot !== 'function') {
+          throw new Error('sootsim screenshot bridge is not installed')
+        }
+        const start = Date.now()
+        const out: Array<{
+          label: string
+          offsetMs: number
+          actualMs: number
+          dataUrl: string
+        }> = []
+        for (const stage of input.stages) {
+          const elapsed = Date.now() - start
+          const wait = Math.max(0, stage.offsetMs - elapsed)
+          if (wait > 0) await new Promise((r) => setTimeout(r, wait))
+          const actualMs = Date.now() - start
+          const dataUrl = await screenshot({ format: 'png' })
+          out.push({ label: stage.label, offsetMs: stage.offsetMs, actualMs, dataUrl })
+        }
+        return out
+      },
+      { stages },
+    )
+    return writeFastScreenshotFrames(namePrefix, frames)
+  },
+
+  async shake() {
+    // no-op for sootsim
+  },
+
+  async setLocation(lat: number, lon: number) {
+    // no-op
+  },
+
+  async setStatusBar(config: StatusBarConfig) {
+    await dispatchStatusBarOverride(config)
+  },
+
+  async setURLBlacklist(urls: string[]) {
+    // no-op
+  },
+
+  async enableSynchronization() {
+    _synchronizationEnabled = true
+  },
+
+  async disableSynchronization() {
+    _synchronizationEnabled = false
+  },
+
+  getPlatform(): 'ios' | 'android' {
+    return device._platform
+  },
+
+  async pressBack() {
+    if (device._platform !== 'android') return
+    const page = getPage()
+    const dispatched = await page.evaluate(async () => {
+      const goBack = window.SootSim?.bridges?.mainShell?.goBack
+      if (typeof goBack !== 'function') return false
+      return (await goBack()) !== false
+    })
+    if (!dispatched) throw new Error('sootsim Android back bridge is not installed')
+    if (_synchronizationEnabled) {
+      await waitForSootsimIdle(page)
+    }
+  },
+
+  // raw coordinate tap, bypassing the element-based visibility/hit-test path.
+  // mirrors detox 20.x device.tap({ x, y }) on real iOS — used when the
+  // target is occluded by a native UIWindow (e.g. UIMenu's dim layer) so
+  // `element(...).tap({x,y})` would fail Detox's visibility threshold.
+  async tap(point?: { x: number; y: number } | boolean) {
+    if (point == null || typeof point === 'boolean') return
+    const page = getPage()
+    const { x, y } = point
+    await page.evaluate(
+      async ({ x: tx, y: ty }) => {
+        const interactTap = window.SootSim?.bridges?.interact?.tap
+        if (typeof interactTap === 'function') {
+          const result = await interactTap(tx, ty)
+          if (result && (typeof result !== 'object' || result.hit !== false)) return
+        }
+        const tap = window.__sootsimTest?.tap
+        if (typeof tap !== 'function') {
+          throw new Error('sootsim tap bridge is not installed')
+        }
+        await tap(tx, ty)
+      },
+      { x, y },
+    )
+    await page.waitForTimeout(50)
+    if (_synchronizationEnabled) {
+      await waitForSootsimIdle(page)
+    }
+  },
+
+  async sendToHome() {
+    // no-op
+  },
+
+  // get direct access to the playwright page for advanced use
+  getPage(): Page {
+    return getPage()
+  },
+}
+
+// exports matching detox API
+const sootsimExpect = createExpect(findNodeByMatcher, getPage)
+const sootsimWaitFor = createWaitFor(findNodeByMatcher, getPage)
+
+export { sootsimExpect as expect, sootsimWaitFor as waitFor }
+
+// cleanup -- call this in afterAll
+export async function cleanup() {
+  await closeBrowser()
+}