sootsim 0.1.83 → 0.1.85

package/detox/index.ts

@@ -0,0 +1,1403 @@
+// 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 { createExpect, createWaitFor } from './expectations'
+import {
+  dispatchTwoFingerGesture,
+  dragScrollNode,
+  readSootsimInteractiveViewport,
+  sootsimToPage,
+  waitForSootsimGestureHandler,
+} from './gestures'
+import { by, type Matcher } from './matchers'
+import type { SootElement } from './element-types'
+import type { Browser, BrowserContext, Page } from 'playwright'
+import type { SootsimEventMap, SootsimEventName } from 'sootsim-engine/sootsim-event'
+
+export { by }
+export type { SootElement } 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 _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 closeContext() {
+  const context = _context
+  _context = null
+  _page = null
+  _synchronizationEnabled = false
+  if (context) await context.close()
+}
+
+async function closeBrowser() {
+  if (!_browser) return
+  const browser = _browser
+  _browser = null
+  await closeContext()
+  await browser.close()
+}
+
+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.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 getDefaultTapPoint(
+  page: Page,
+  nodeInfo: any,
+): Promise<{ x: number; y: number }> {
+  const center = getNodeCenter(nodeInfo)
+  const viewport = await readSootsimInteractiveViewport(page)
+  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 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 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: SootElement): 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')
+  }
+  return Buffer.from(match[1], 'base64')
+}
+
+// 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 },
+  )
+  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,
+    },
+  )
+  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 createSootElement(matcher: Matcher): SootElement {
+  const el: SootElement = {
+    _matcher: matcher,
+
+    async tap(point) {
+      const page = getPage()
+      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 targetSootX =
+        typeof point?.x === 'number'
+          ? node.absolutePosition.x + point.x
+          : (defaultPoint?.x ?? node.absolutePosition.x + node.layout.width / 2)
+      const targetSootY =
+        typeof point?.y === 'number'
+          ? node.absolutePosition.y + point.y
+          : (defaultPoint?.y ?? node.absolutePosition.y + node.layout.height / 2)
+      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: targetSootX, y: targetSootY },
+      )
+      // small settling time for react state updates
+      await page.waitForTimeout(50)
+      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)
+      const pageCoords = await sootsimToPage(page, center.x, center.y)
+
+      await page.mouse.move(pageCoords.x, pageCoords.y)
+      await page.mouse.down()
+      await page.waitForTimeout(duration)
+      await page.mouse.up()
+      await page.waitForTimeout(50)
+    },
+
+    async longPressAndDrag(
+      duration: number,
+      normalizedStartX: number,
+      normalizedStartY: number,
+      targetElement: SootElement,
+      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 startSootX =
+        srcNode.absolutePosition.x + srcNode.layout.width * normalizedStartX
+      const startSootY =
+        srcNode.absolutePosition.y + srcNode.layout.height * normalizedStartY
+      const endSootX = tgtNode.absolutePosition.x + tgtNode.layout.width * normalizedEndX
+      const endSootY = tgtNode.absolutePosition.y + tgtNode.layout.height * normalizedEndY
+
+      const startPage = await sootsimToPage(page, startSootX, startSootY)
+      const endPage = await sootsimToPage(page, endSootX, endSootY)
+      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',
+      percentage = 0.75,
+    ) {
+      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
+
+      // start from center
+      const startSootX = absolutePosition.x + layout.width * 0.5
+      const startSootY = absolutePosition.y + layout.height * 0.5
+
+      // compute distance
+      let endSootX = startSootX
+      let endSootY = startSootY
+      const dist =
+        direction === 'up' || direction === 'down'
+          ? layout.height * percentage
+          : layout.width * percentage
+
+      switch (direction) {
+        case 'up':
+          endSootY -= dist
+          break
+        case 'down':
+          endSootY += dist
+          break
+        case 'left':
+          endSootX -= dist
+          break
+        case 'right':
+          endSootX += dist
+          break
+      }
+
+      const steps = speed === 'slow' ? 20 : speed === 'fast' ? 8 : 12
+      const stepDelay = speed === 'slow' ? 25 : speed === 'fast' ? 5 : 15
+
+      await page.evaluate(
+        async ({ fromX, fromY, toX, toY, steps, stepMs }) => {
+          const drag = window.__sootsimTest?.drag
+          if (typeof drag !== 'function') {
+            throw new Error('sootsim drag bridge is not installed')
+          }
+          await drag(fromX, fromY, toX, toY, steps, stepMs)
+        },
+        {
+          fromX: startSootX,
+          fromY: startSootY,
+          toX: endSootX,
+          toY: endSootY,
+          steps,
+          stepMs: stepDelay,
+        },
+      )
+      await page.waitForTimeout(100)
+    },
+
+    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 center = getNodeCenter(node)
+      const centerPage = await sootsimToPage(page, center.x, center.y)
+      const startSpread = 60
+      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,
+        { x: centerPage.x + a0.dx, y: centerPage.y + a0.dy },
+        { x: centerPage.x + b0.dx, y: centerPage.y + b0.dy },
+        { x: centerPage.x + a1.dx, y: centerPage.y + a1.dy },
+        { x: centerPage.x + b1.dx, y: centerPage.y + 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 center = getNodeCenter(node)
+      const centerPage = await sootsimToPage(page, center.x, center.y)
+      const radius = 60
+      const startA = { x: centerPage.x - radius, y: centerPage.y }
+      const startB = { x: centerPage.x + radius, y: centerPage.y }
+      const cos = Math.cos(radians)
+      const sin = Math.sin(radians)
+      const endA = {
+        x: centerPage.x - radius * cos,
+        y: centerPage.y - radius * sin,
+      }
+      const endB = {
+        x: centerPage.x + radius * cos,
+        y: centerPage.y + 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)}`,
+        )
+
+      return writeSootsimScreenshot(name, {
+        crop: {
+          x: node.absolutePosition.x,
+          y: node.absolutePosition.y,
+          w: node.layout.width,
+          h: node.layout.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) {
+      // sootsim resolves a testID to exactly one SootSimNode, so the
+      // detox-style atIndex is a passthrough. supplied for parity with
+      // real Detox so library tests can wrap atIndex around matchers
+      // that surface multiple native views on iOS (e.g. RNGH RectButton)
+      // without diverging code paths between the two lanes.
+      return el
+    },
+  }
+
+  return el
+}
+
+// element() factory -- takes a matcher and returns an element interaction object
+export function element(matcher: Matcher): SootElement {
+  return createSootElement(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) {
+      _browser = await chromium.launch({ headless: true })
+    }
+
+    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)
+    // record the wall-clock time the page is ready — captureProofMenuStages
+    // uses this to compute trigger-in-video offsets
+    device._lastReadyAtMs = Date.now()
+    await _page!.waitForTimeout(500)
+  },
+
+  _lastReadyAtMs: 0,
+
+  async reloadReactNative() {
+    const page = getPage()
+    await page.reload({ waitUntil: 'load', timeout: 30000 })
+    await waitForSootsimTree(page, 30000)
+    await page.waitForTimeout(500)
+  },
+
+  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)
+  },
+
+  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 `bun 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 `bun 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('SootSim 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 })
+  },
+
+  async setBottomTabAnimOverride(
+    value: { fromIndex: number; progress: number; toIndex: number } | null,
+  ): Promise<void> {
+    await dispatchSootsimEventInPage('sootsim:bottomTabAnimOverride', { value })
+  },
+
+  // 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 }>,
+  ): 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('SootSim 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.)
+        await screenshot()
+        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()
+                    }
+                    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 },
+    )
+    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,
+      }
+    })
+  },
+
+  // 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()
+          out.push({ label: stage.label, offsetMs: stage.offsetMs, actualMs, dataUrl })
+        }
+        return out
+      },
+      { 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,
+      }
+    })
+  },
+
+  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
+    await element(by.id('android-nav-back')).tap()
+  },
+
+  // 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 sootExpect = createExpect(findNodeByMatcher, getPage)
+const sootWaitFor = createWaitFor(findNodeByMatcher, getPage)
+
+export { sootExpect as expect, sootWaitFor as waitFor }
+
+// cleanup -- call this in afterAll
+export async function cleanup() {
+  if (_browser) {
+    await _browser.close()
+    _browser = null
+    _page = null
+  }
+}