peachsim 0.1.527

package/detox/jest-preset.cjs

@@ -0,0 +1,29 @@
+// jest preset for running existing detox suites against sootsim.
+//
+// users drop `preset: 'rnxsim/detox'` into their jest config
+// (or `rnx-detox.config.cjs`) and their `import { by, device, element,
+// expect, waitFor } from 'detox'` calls resolve to the sootsim driver.
+
+const path = require('path')
+
+// resolve the published driver entry so the mapping works from any cwd.
+// `require.resolve('sootsim/detox')` honours the subpath export in the
+// sootsim package.json.
+const DRIVER_ENTRY = require.resolve('rnxsim/detox')
+const PACKAGE_ROOT = path.dirname(require.resolve('rnxsim/package.json'))
+
+/** @type {import('@jest/types').Config.InitialOptions} */
+module.exports = {
+  testTimeout: 180000,
+  maxWorkers: 1,
+  watchman: false,
+  verbose: true,
+  testEnvironment: 'node',
+  setupFilesAfterEnv: [path.join(PACKAGE_ROOT, 'detox', 'jest-setup-after-env.cjs')],
+  transform: {
+    '^.+\\.[jt]sx?$': ['@sucrase/jest-plugin', { jsxRuntime: 'automatic' }],
+  },
+  moduleNameMapper: {
+    '^detox$': DRIVER_ENTRY,
+  },
+}

package/detox/jest-setup-after-env.cjs

@@ -0,0 +1,22 @@
+// closes the driver's browser when a test file finishes.
+//
+// the driver launches chrome lazily on first use and tracks it with the shared
+// reaper, but that reaper's safety net is a `process.on('exit')` hook and jest
+// hands every test file a sandboxed COPY of `process`. a handler registered
+// from inside a test therefore never fires on real termination, so under jest
+// the reaper is a no-op and every suite that launched a browser strands its
+// whole chrome tree. one orphan per test file adds up fast on a full run.
+//
+// `cleanup()` is the teardown that does run, and it both closes the browser and
+// force-reaps its tree. registering it here means no suite has to remember an
+// afterAll of its own.
+
+// records which test bodies actually ran, so a downstream reader can tell a
+// setup failure from a behavior failure. no-op unless the run asks for it.
+require('./record-block-execution.cjs')
+
+const { cleanup } = require('rnxsim/detox')
+
+afterAll(async () => {
+  await cleanup()
+})

package/detox/matchers.ts

@@ -0,0 +1,30 @@
+// detox-compatible matchers: by.id(), by.text(), by.label(), by.type()
+// these produce matcher descriptors consumed by element() and expect()
+
+export interface Matcher {
+  type: 'id' | 'text' | 'label' | 'type' | 'role'
+  value: string
+  index?: number
+}
+
+export const by = {
+  id(testID: string): Matcher {
+    return { type: 'id', value: testID }
+  },
+
+  text(text: string): Matcher {
+    return { type: 'text', value: text }
+  },
+
+  label(accessibilityLabel: string): Matcher {
+    return { type: 'label', value: accessibilityLabel }
+  },
+
+  type(nativeType: string): Matcher {
+    return { type: 'type', value: nativeType }
+  },
+
+  role(accessibilityRole: string): Matcher {
+    return { type: 'role', value: accessibilityRole }
+  },
+}

package/detox/motion-change.cjs

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

package/detox/motion-change.d.cts

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

package/detox/navigation-lifecycle.ts

@@ -0,0 +1,290 @@
+import { writeAttemptEvent } from './attempt-events.cjs'
+import type { Page, Request, Response } from 'playwright'
+
+export type SootsimNavigationIdentity = {
+  browserId: number
+  contextId: number
+  operation: 'launchApp' | 'openURL'
+}
+
+type SootsimPageState = {
+  bodyText: string
+  bridges: {
+    sootsim: boolean
+    test: boolean
+  }
+  globals: string[]
+  readyState: string
+  title: string
+  url: string
+}
+
+type ActiveNavigation = SootsimNavigationIdentity & {
+  navigationUrl: string
+  navigationId: number
+}
+
+type NavigationMilestone =
+  | 'document-request'
+  | 'document-request-failed'
+  | 'document-request-finished'
+  | 'document-response'
+  | 'domcontentloaded'
+  | 'error'
+  | 'load'
+  | 'start'
+
+type NavigationDiagnostic = {
+  browserId: number
+  capturedAt: string
+  contextId: number
+  errorText?: string
+  failurePhase?: 'bridge' | 'navigation'
+  headersReceived?: boolean
+  method?: string
+  milestone: NavigationMilestone
+  navigationUrl: string
+  navigationId: number
+  operation: SootsimNavigationIdentity['operation']
+  pageState?: SootsimPageState | { evaluateError: string }
+  status?: number
+  target: string
+  type: 'rnx-navigation'
+  url: string
+}
+
+type PageDiagnostic =
+  | NavigationDiagnostic
+  | {
+      capturedAt: string
+      level: string
+      message: string
+      type: 'page-console'
+    }
+  | {
+      capturedAt: string
+      message: string
+      type: 'page-error'
+    }
+  | {
+      capturedAt: string
+      errorText: string
+      method: string
+      type: 'subresource-request-failed'
+      url: string
+    }
+
+const DIAGNOSTIC_LIMIT = 40
+const pageDiagnostics = new WeakMap<Page, PageDiagnostic[]>()
+const activeNavigations = new WeakMap<Page, ActiveNavigation>()
+const lastNavigations = new WeakMap<Page, ActiveNavigation>()
+let nextNavigationIdentity = 0
+
+function recordPageDiagnostic(page: Page, diagnostic: PageDiagnostic, persist = false) {
+  const entries = pageDiagnostics.get(page)
+  if (!entries) return
+  entries.push(diagnostic)
+  if (entries.length > DIAGNOSTIC_LIMIT) entries.shift()
+  if (persist) writeAttemptEvent(diagnostic)
+}
+
+function isTopLevelDocumentRequest(page: Page, request: Request) {
+  return (
+    request.isNavigationRequest() &&
+    request.resourceType() === 'document' &&
+    request.frame() === page.mainFrame()
+  )
+}
+
+function recordNavigationMilestoneFor(
+  page: Page,
+  active: ActiveNavigation,
+  milestone: NavigationMilestone,
+  details: Partial<
+    Pick<
+      NavigationDiagnostic,
+      | 'errorText'
+      | 'failurePhase'
+      | 'headersReceived'
+      | 'method'
+      | 'pageState'
+      | 'status'
+      | 'url'
+    >
+  > = {},
+) {
+  recordPageDiagnostic(
+    page,
+    {
+      ...active,
+      ...details,
+      capturedAt: new Date().toISOString(),
+      milestone,
+      target: process.env.CONFORMANCE_PROOF_TARGET || 'sootsim',
+      type: 'rnx-navigation',
+      url: details.url ?? active.navigationUrl,
+    },
+    true,
+  )
+}
+
+function recordNavigationMilestone(
+  page: Page,
+  milestone: NavigationMilestone,
+  details: Parameters<typeof recordNavigationMilestoneFor>[3] = {},
+) {
+  const active = activeNavigations.get(page)
+  if (active) recordNavigationMilestoneFor(page, active, milestone, details)
+}
+
+function attachPageDiagnostics(page: Page) {
+  if (pageDiagnostics.has(page)) return
+  pageDiagnostics.set(page, [])
+  page.on('console', (message) => {
+    recordPageDiagnostic(page, {
+      capturedAt: new Date().toISOString(),
+      level: message.type(),
+      message: message.text(),
+      type: 'page-console',
+    })
+  })
+  page.on('pageerror', (error) => {
+    recordPageDiagnostic(page, {
+      capturedAt: new Date().toISOString(),
+      message: error.message,
+      type: 'page-error',
+    })
+  })
+  page.on('request', (request) => {
+    if (!isTopLevelDocumentRequest(page, request)) return
+    recordNavigationMilestone(page, 'document-request', {
+      method: request.method(),
+      url: request.url(),
+    })
+  })
+  page.on('response', (response) => {
+    const request = response.request()
+    if (!isTopLevelDocumentRequest(page, request)) return
+    recordNavigationMilestone(page, 'document-response', {
+      headersReceived: true,
+      status: response.status(),
+      url: request.url(),
+    })
+  })
+  page.on('requestfinished', (request) => {
+    if (!isTopLevelDocumentRequest(page, request)) return
+    recordNavigationMilestone(page, 'document-request-finished', { url: request.url() })
+  })
+  page.on('requestfailed', (request) => {
+    const failure = request.failure()
+    const errorText = failure?.errorText ?? ''
+    if (isTopLevelDocumentRequest(page, request)) {
+      recordNavigationMilestone(page, 'document-request-failed', {
+        errorText,
+        url: request.url(),
+      })
+      return
+    }
+    recordPageDiagnostic(page, {
+      capturedAt: new Date().toISOString(),
+      errorText,
+      method: request.method(),
+      type: 'subresource-request-failed',
+      url: request.url(),
+    })
+  })
+  page.on('domcontentloaded', () => {
+    recordNavigationMilestone(page, 'domcontentloaded')
+  })
+  page.on('load', () => {
+    recordNavigationMilestone(page, 'load')
+  })
+}
+
+async function readSootsimPageState(
+  page: Page,
+): Promise<SootsimPageState | { evaluateError: string }> {
+  try {
+    return await page.evaluate(() => ({
+      bodyText: document.body?.innerText?.slice(0, 500) ?? '',
+      bridges: {
+        sootsim: Boolean(window.SootSim),
+        test: Boolean(window.__sootsimTest),
+      },
+      globals: Object.keys(window)
+        .filter((key) => key.startsWith('__sootsim') || key === 'SootSim')
+        .sort(),
+      readyState: document.readyState,
+      title: document.title,
+      url: window.location.href,
+    }))
+  } catch (error) {
+    return {
+      evaluateError: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export async function describeSootsimBridgeFailure(
+  page: Page,
+  cause: unknown,
+  summary = 'timed out waiting for sootsim test bridge',
+  pageState?: SootsimPageState | { evaluateError: string },
+) {
+  const recordBridgeFailure = pageState === undefined
+  const state = pageState ?? (await readSootsimPageState(page))
+  const navigation = lastNavigations.get(page)
+  if (recordBridgeFailure && navigation) {
+    recordNavigationMilestoneFor(page, navigation, 'error', {
+      errorText: cause instanceof Error ? cause.message : String(cause),
+      failurePhase: 'bridge',
+      pageState: state,
+    })
+  }
+  return new Error(
+    [
+      summary,
+      `cause: ${cause instanceof Error ? cause.message : String(cause)}`,
+      `page: ${JSON.stringify(state)}`,
+      `recent page diagnostics:\n${JSON.stringify(getSootsimNavigationDiagnostics(page))}`,
+    ].join('\n'),
+  )
+}
+
+export async function navigateSootsimPage(
+  page: Page,
+  url: string,
+  identity: SootsimNavigationIdentity,
+): Promise<Response | null> {
+  attachPageDiagnostics(page)
+  const navigation = {
+    ...identity,
+    navigationUrl: url,
+    navigationId: ++nextNavigationIdentity,
+  }
+  activeNavigations.set(page, navigation)
+  lastNavigations.set(page, navigation)
+  recordNavigationMilestone(page, 'start')
+  try {
+    return await page.goto(url, { waitUntil: 'load', timeout: 30000 })
+  } catch (error) {
+    const pageState = await readSootsimPageState(page)
+    recordNavigationMilestone(page, 'error', {
+      errorText: error instanceof Error ? error.message : String(error),
+      failurePhase: 'navigation',
+      pageState,
+    })
+    throw await describeSootsimBridgeFailure(
+      page,
+      error,
+      'sootsim navigation failed',
+      pageState,
+    )
+  } finally {
+    activeNavigations.delete(page)
+  }
+}
+
+export function getSootsimNavigationDiagnostics(page: Page): readonly PageDiagnostic[] {
+  return [...(pageDiagnostics.get(page) ?? [])]
+}

package/detox/navigation.ts

@@ -0,0 +1,43 @@
+// sootsim-compatible replacement for kitchen-sink's e2e/utils/navigation.ts
+// instead of navigating through the UI, we load the test case via URL query param
+
+import { by, device, element, waitFor } from './index'
+
+const BASE_URL = process.env.RNX_URL || 'http://localhost:5173'
+
+/**
+ * navigate to a kitchen-sink test case in sootsim
+ * loads via URL query param instead of tapping through the UI
+ */
+export async function navigateToTestCase(
+  testCaseName: string,
+  waitForElementId?: string,
+) {
+  const page = device.getPage()
+
+  // navigate to the test case directly via URL, preserving any params
+  // already on BASE_URL (device=, colorScheme=, etc.) — the conformance
+  // runner sets these via RNX_URL and dropping them silently rendered
+  // pro max at iphone 16 dimensions.
+  const target = new URL(BASE_URL)
+  target.searchParams.set('test', testCaseName)
+  if (target.pathname === '' || target.pathname === '/') target.pathname = '/'
+  const url = target.toString()
+  await page.goto(url, { waitUntil: 'load', timeout: 30000 })
+
+  // wait for sootsim engine to initialize
+  await page.waitForFunction(
+    'window.__sootsimTest && window.__sootsimRoot && window.__sootsimRoot.children.length > 0',
+    { timeout: 30000 },
+  )
+
+  // let rendering settle
+  await page.waitForTimeout(500)
+
+  // wait for the target element if specified
+  if (waitForElementId) {
+    await waitFor(element(by.id(waitForElementId)))
+      .toExist()
+      .withTimeout(10000)
+  }
+}

package/detox/proof-frame.cjs

@@ -0,0 +1,114 @@
+// proof captures reserve the top and bottom of a device frame for platform
+// chrome. those pixels can be fully opaque while the app surface is blank or
+// still fading in, so evidence density is measured only in the content band.
+const PROOF_CONTENT_DEFINITION = Object.freeze({
+  channelThreshold: 24,
+  contentBandInsetFraction: 0.08,
+  minimumContentPercent: 0.005,
+})
+
+// conformance compares these captures against native ios baselines, so a frame
+// caught mid-animation reads as a real pixel diff. three consecutive identical
+// frames is the evidence that the screen actually stopped moving.
+const REQUIRED_IDENTICAL_PROOF_FRAMES = 3
+
+// a flow's `takeScreenshot` is a developer artifact, not pixel evidence. one
+// settled capture is what it wants: re-capturing flashes the screen on every
+// attempt, and a screen with a blinking caret never produces two identical
+// frames at all, so the step fails on a page that is perfectly fine.
+const REQUIRED_IDENTICAL_FLOW_FRAMES = 1
+
+function framesIdentical(a, b) {
+  if (!a || !b || a.length !== b.length) return false
+  return a.equals(b)
+}
+
+function measureProofFrameContent(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('proof content measurement requires an input object')
+  }
+  const { data, width, height } = input
+  if (
+    !data ||
+    typeof data.length !== 'number' ||
+    !Number.isInteger(width) ||
+    !Number.isInteger(height) ||
+    width <= 0 ||
+    height <= 0 ||
+    data.length !== width * height * 4
+  ) {
+    throw new Error('proof content measurement needs RGBA pixels and dimensions')
+  }
+
+  const yStart = Math.floor(height * PROOF_CONTENT_DEFINITION.contentBandInsetFraction)
+  const yEnd = Math.ceil(height * (1 - PROOF_CONTENT_DEFINITION.contentBandInsetFraction))
+  const bucketCounts = new Uint32Array(32 * 32 * 32)
+  let totalPixels = 0
+  for (let y = yStart; y < yEnd; y++) {
+    for (let x = 0; x < width; x++) {
+      const offset = (y * width + x) * 4
+      const bucket =
+        ((data[offset] >> 3) << 10) |
+        ((data[offset + 1] >> 3) << 5) |
+        (data[offset + 2] >> 3)
+      bucketCounts[bucket]++
+      totalPixels++
+    }
+  }
+
+  let dominantBucket = 0
+  for (let index = 1; index < bucketCounts.length; index++) {
+    if (bucketCounts[index] > bucketCounts[dominantBucket]) dominantBucket = index
+  }
+  const dominant = {
+    red: (((dominantBucket >> 10) & 31) << 3) + 4,
+    green: (((dominantBucket >> 5) & 31) << 3) + 4,
+    blue: ((dominantBucket & 31) << 3) + 4,
+  }
+
+  let contentPixels = 0
+  for (let y = yStart; y < yEnd; y++) {
+    for (let x = 0; x < width; x++) {
+      const offset = (y * width + x) * 4
+      if (
+        Math.max(
+          Math.abs(data[offset] - dominant.red),
+          Math.abs(data[offset + 1] - dominant.green),
+          Math.abs(data[offset + 2] - dominant.blue),
+        ) >= PROOF_CONTENT_DEFINITION.channelThreshold
+      ) {
+        contentPixels++
+      }
+    }
+  }
+
+  const contentPercent = (contentPixels / totalPixels) * 100
+  return {
+    contentPercent,
+    contentPixels,
+    dominant,
+    passedMinimum: contentPercent >= PROOF_CONTENT_DEFINITION.minimumContentPercent,
+    totalPixels,
+  }
+}
+
+function settleDecision(previousPixels, currentFrame) {
+  if (!currentFrame) return { decision: 'continue', content: null }
+  const content = measureProofFrameContent(currentFrame)
+  if (!content.passedMinimum) {
+    return { decision: 'insufficient-content', content }
+  }
+  if (previousPixels && framesIdentical(previousPixels, currentFrame.data)) {
+    return { decision: 'identical', content }
+  }
+  return { decision: 'changed', content }
+}
+
+module.exports = {
+  PROOF_CONTENT_DEFINITION,
+  REQUIRED_IDENTICAL_PROOF_FRAMES,
+  REQUIRED_IDENTICAL_FLOW_FRAMES,
+  framesIdentical,
+  measureProofFrameContent,
+  settleDecision,
+}