rnxsim 0.1.354 → 0.1.355

package/cli/bridge-flow-runner.ts

@@ -2,6 +2,10 @@ import * as fs from 'fs'
 import * as path from 'path'
 import { devices, type DeviceModel } from 'sootsim-engine/settings'
 import yaml from 'yaml'
+import {
+  REQUIRED_IDENTICAL_PROOF_FRAMES,
+  framesIdentical,
+} from '../detox/proof-frame.cjs'
 import { composeFramedScreenshot } from '../src/screenshots/frame-compose'
 import { resetGuestAppStateEval } from './app-state-reset'
 import {
@@ -415,7 +419,6 @@ export class SootSimBridgeFlowRunner {
   private lastRecordingDurationMs: number | null = null
   private lastRecordingFrameStats: unknown = null
   private flowTraceSteps: SootSimFlowTraceStep[] = []
-  private lastVisualSettledAtMs = 0
   private simRouteHint: string | null = null
   // set by runStep when a step throws — lets the outer flow command
   // dump a rich per-step failure bundle (screenshot + describe.json +
@@ -1489,23 +1492,6 @@ export class SootSimBridgeFlowRunner {
           layers?: 'full' | 'tenant' | 'shell'
         },
   ): Promise<string> {
-    // give transitions + last-moment data paint a brief settle window before
-    // freezing the frame. screenshot flows care more about visual completeness
-    // than minimum latency. waitForVisualSettle drains in-flight animations
-    // (it returns immediately if nothing is animating), then we hold for an
-    // additional 250ms paint window for fade-ins / image decodes / etc.
-    // before this change, a 250ms sleep was the *only* settle window — flows
-    // that took a screenshot at the tail of a screen transition would catch
-    // a half-finished frame on slow machines.
-    if (!this.hasFreshVisualSettle()) {
-      try {
-        await this.waitForVisualSettle()
-        await sleep(250)
-      } catch {
-        // settling helper can throw on disconnected sims; fall through so a
-        // stale sim still produces *some* screenshot.
-      }
-    }
     // flow `takeScreenshot: <name>` may be a plain name ("hero") or a full
     // relative path with slashes ("apps/foo/screenshots/en/02-forum") —
     // maestro flows commonly use the latter. mkdir the parent of the
@@ -1531,9 +1517,32 @@ export class SootSimBridgeFlowRunner {
       simId: this.opts.simId,
     }
     if (layers && layers !== 'full') screenshotRequest.layers = layers
-    const dataUrl: string = await this.bridge.send(screenshotRequest)
-    const base64 = dataUrl.replace(/^data:image\/png;base64,/, '')
-    const rawBuffer = Buffer.from(base64, 'base64')
+    let previousBuffer: Buffer | null = null
+    let identicalFrames = 1
+    let rawBuffer: Buffer | null = null
+    for (let attempt = 0; attempt < 12; attempt++) {
+      await this.waitForVisualSettle()
+      const dataUrl: string = await this.bridge.send(screenshotRequest)
+      const current = Buffer.from(
+        dataUrl.replace(/^data:image\/png;base64,/, ''),
+        'base64',
+      )
+      if (framesIdentical(previousBuffer, current)) {
+        identicalFrames++
+        if (identicalFrames >= REQUIRED_IDENTICAL_PROOF_FRAMES) {
+          rawBuffer = current
+          break
+        }
+      } else {
+        identicalFrames = 1
+      }
+      previousBuffer = current
+    }
+    if (!rawBuffer) {
+      throw new Error(
+        `screenshot did not reach ${REQUIRED_IDENTICAL_PROOF_FRAMES} identical idle frames`,
+      )
+    }
     if (spec.withFrame) {
       const model = await this.readCurrentDeviceModel()
       if (!model) {
@@ -1563,13 +1572,7 @@ export class SootSimBridgeFlowRunner {
   }
 
   async captureScreenshot(outputPath: string) {
-    fs.mkdirSync(path.dirname(outputPath), { recursive: true })
-    const dataUrl: string = await this.bridge.send({
-      type: 'screenshot',
-      simId: this.opts.simId,
-    })
-    const base64 = dataUrl.replace(/^data:image\/png;base64,/, '')
-    fs.writeFileSync(outputPath, Buffer.from(base64, 'base64'))
+    await this.takeScreenshot({ path: outputPath })
   }
 
   // writes a per-failure debug bundle: screenshot + structured describe
@@ -1880,7 +1883,9 @@ export class SootSimBridgeFlowRunner {
       stablePolls: 2,
       strict: true,
     })
-    if (result.settled) this.markVisualSettled()
+    if (!result.settled) {
+      throw new Error(`animation did not settle within ${maxMs}ms`)
+    }
   }
 
   async back() {
@@ -2082,31 +2087,19 @@ export class SootSimBridgeFlowRunner {
   }
 
   private async waitForVisualSettle() {
-    try {
-      await this.evaluate(`new Promise((resolve) => {
-        requestAnimationFrame(() => {
-          requestAnimationFrame(() => {
-            requestAnimationFrame(() => {
-              setTimeout(resolve, 180)
-            })
-          })
-        })
-      })`)
-      this.markVisualSettled()
-    } catch {
-      await sleep(180)
-      this.markVisualSettled()
+    const result = await waitForSootsimIdle({
+      bridge: this.bridge,
+      simId: this.opts.simId,
+      maxMs: 10_000,
+      pollMs: 32,
+      stablePolls: 3,
+      strict: true,
+    })
+    if (!result.settled) {
+      throw new Error(`visual state did not settle within ${result.elapsed}ms`)
     }
   }
 
-  private markVisualSettled() {
-    this.lastVisualSettledAtMs = Date.now()
-  }
-
-  private hasFreshVisualSettle() {
-    return Date.now() - this.lastVisualSettledAtMs < 750
-  }
-
   private resolveShellLaunchAppId(opts: unknown, state: ShellState | null): string {
     if (typeof opts === 'string' && opts.length > 0) return opts
     if (isObjectRecord(opts)) {

package/cli/commands/inspect/settling.ts

@@ -58,16 +58,21 @@ export async function waitForSootsimIdle({
 
       const readSnapshot = async () => {
         let animating = false
+        let layoutDirty = false
         let pendingFetches = 0
         let requestTotal = 0
         let requestInFlight = 0
+        let renderStatsAvailable = false
         try {
           const stats = await window.__sootsimRenderHost?.queryStats?.()
           if (stats) {
+            renderStatsAvailable = true
             animating =
               stats.hasActiveAnims === true ||
               stats.hasActiveNativeAnimations === true ||
               stats.hasPendingAnimationFrames === true
+            layoutDirty =
+              stats.layoutDirty === true && stats.renderRequested === true
             // a freshly-pushed screen showing a skeleton is layout-stable
             // but not actually settled — its data/images are still in
             // flight. treat bounded image-loader fetches as not-idle so
@@ -94,7 +99,7 @@ export async function waitForSootsimIdle({
           }
           walk(root)
         }
-        return { layout: nodes.join(';'), animating, pendingFetches, requestTotal, requestInFlight }
+        return { layout: nodes.join(';'), animating, layoutDirty, pendingFetches, renderStatsAvailable, requestTotal, requestInFlight }
       }
 
       // how long generic background network is allowed to keep us waiting AFTER
@@ -114,7 +119,9 @@ export async function waitForSootsimIdle({
       let visuallyStillSince = 0
       while (Date.now() < deadline) {
         const snapshot = await readSnapshot()
-        const strictOk = !strict || !snapshot.animating
+        const strictOk =
+          !strict ||
+          (snapshot.renderStatsAvailable && !snapshot.animating && !snapshot.layoutDirty)
         // visually settled: no animations, no image content loading, layout
         // unchanged since the last poll.
         const visuallyStill =

package/cli/outbound-endpoints.ts

@@ -125,7 +125,7 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     count: 3,
   },
   'packages/sootsim-engine/src/components/native-ui/LottieHost.tsx :: fetch :: descriptor.value':
-    { category: 'guest_app_network', count: 1 },
+    { category: 'guest_app_network', count: 2 },
   'packages/sootsim-engine/src/demo/demo-share-register.ts :: fetch :: shareUrl': {
     category: 'guest_app_network',
     count: 1,

package/detox/index.ts

@@ -6,6 +6,7 @@ import * as fs from 'fs'
 import * as path from 'path'
 import { chromium } from 'playwright'
 import { launchReapedChromeScoped } from '../../../scripts/lib/reap-browser'
+import { pollUntil } from '../src/poll-until'
 import { createExpect, createWaitFor } from './expectations'
 import {
   dispatchTwoFingerGesture,
@@ -22,6 +23,7 @@ import {
   type MotionChangeDefinition,
   type MotionChangeMeasurement,
 } from './motion-change.cjs'
+import { REQUIRED_IDENTICAL_PROOF_FRAMES, framesIdentical } from './proof-frame.cjs'
 import type { SootSimElement } from './element-types'
 import type { Browser, BrowserContext, Page } from 'playwright'
 import type { SootsimEventMap, SootsimEventName } from 'sootsim-engine/sootsim-event'
@@ -42,6 +44,7 @@ let _reapBrowserNow: (() => void) | null = null
 let _context: BrowserContext | null = null
 let _page: Page | null = null
 let _synchronizationEnabled = false
+let _suspendedAppId: string | null = null
 const pageDiagnostics = new WeakMap<Page, string[]>()
 
 const STATUS_BAR_OVERRIDE_EVENT = 'sootsim:statusBarOverride'
@@ -339,9 +342,14 @@ async function closeBrowser() {
   }
 }
 
-export async function waitForSootsimIdle(page: Page, maxMs = 3000): Promise<void> {
+export async function waitForSootsimIdle(
+  page: Page,
+  maxMs = 3000,
+  strict = false,
+): Promise<void> {
   const result = await page.evaluate(
-    async ({ maxMs }) => {
+    async ({ maxMs, strict }) => {
+      const start = Date.now()
       let transitionError: string | null = null
       try {
         const waitForScreenTransitions = (window as any).__sootsimTest
@@ -352,13 +360,6 @@ export async function waitForSootsimIdle(page: Page, maxMs = 3000): Promise<void
             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,
@@ -371,7 +372,6 @@ export async function waitForSootsimIdle(page: Page, maxMs = 3000): Promise<void
         transitionError = error instanceof Error ? error.message : String(error)
       }
 
-      const start = Date.now()
       const deadline = start + maxMs
       const pollMs = 50
       const requiredStablePolls = 3
@@ -388,6 +388,28 @@ export async function waitForSootsimIdle(page: Page, maxMs = 3000): Promise<void
       const readSnapshot = async () => {
         const root = (window as any).__sootsimRoot
         const layout: number[] = []
+        let animating = false
+        let auxSurfaceDebug: unknown = null
+        let layoutDirty = false
+        let renderStatsAvailable = false
+        if (strict) {
+          try {
+            const renderHost: unknown = Reflect.get(window, '__sootsimRenderHost')
+            const queryStats =
+              typeof renderHost === 'object' && renderHost !== null
+                ? Reflect.get(renderHost, 'queryStats')
+                : null
+            const stats =
+              typeof queryStats === 'function' ? await queryStats.call(renderHost) : null
+            renderStatsAvailable = !!stats
+            auxSurfaceDebug = stats?.auxSurfaceDebug ?? null
+            animating =
+              stats?.hasActiveAnims === true ||
+              stats?.hasActiveNativeAnimations === true ||
+              stats?.hasPendingAnimationFrames === true
+            layoutDirty = stats?.layoutDirty === true && stats?.renderRequested === true
+          } catch {}
+        }
         if (root) {
           const walk = (node: any) => {
             if (node.layout && node.layout.width > 0) {
@@ -402,20 +424,33 @@ export async function waitForSootsimIdle(page: Page, maxMs = 3000): Promise<void
           }
           walk(root)
         }
-        return layout
+        return {
+          animating,
+          auxSurfaceDebug,
+          layout,
+          layoutDirty,
+          renderStatsAvailable,
+        }
       }
 
       let stableLayout: number[] | null = null
       let stable = 0
+      let lastSnapshot: Awaited<ReturnType<typeof readSnapshot>> | null = null
       while (Date.now() < deadline) {
-        const layout = await readSnapshot()
-        if (isLayoutStable(stableLayout, layout)) {
+        const snapshot = await readSnapshot()
+        lastSnapshot = snapshot
+        if (
+          (!strict || snapshot.renderStatsAvailable) &&
+          !snapshot.animating &&
+          !snapshot.layoutDirty &&
+          isLayoutStable(stableLayout, snapshot.layout)
+        ) {
           stable++
           if (stable >= requiredStablePolls) {
             return { settled: true, elapsed: Date.now() - start }
           }
         } else {
-          stableLayout = layout
+          stableLayout = snapshot.layout
           stable = 0
         }
         await sleep(pollMs)
@@ -425,10 +460,12 @@ export async function waitForSootsimIdle(page: Page, maxMs = 3000): Promise<void
         elapsed: Date.now() - start,
         reason: transitionError
           ? `layout fallback after screen transition wait failed: ${transitionError}`
-          : 'layout fallback',
+          : strict
+            ? `strict idle state unavailable: renderStats=${lastSnapshot?.renderStatsAvailable === true} animating=${lastSnapshot?.animating === true} layoutDirty=${lastSnapshot?.layoutDirty === true} layoutNodes=${(lastSnapshot?.layout.length ?? 0) / 4} aux=${JSON.stringify(lastSnapshot?.auxSurfaceDebug)}`
+            : 'layout fallback',
       }
     },
-    { maxMs },
+    { maxMs, strict },
   )
 
   if (!result?.settled) {
@@ -633,7 +670,7 @@ function writeFastScreenshotFrames<T extends FastScreenshotData>(
 
 // 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
+// usual captureSootsimPng requires three consecutive idle frames to be byte-equal
 // which is ideal for settled screenshots but blocks for the full timeout
 // while an animation is running.
 async function captureSootsimPngFast(opts?: {
@@ -661,62 +698,25 @@ 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`,
-    )
+  const deadline = Date.now() + 8000
+  let previous: Buffer | null = null
+  let identicalFrames = 1
+  let attempts = 0
+  while (Date.now() < deadline) {
+    await waitForSootsimIdle(page, Math.max(1, deadline - Date.now()), true)
+    const current = await captureSootsimPngFast(opts)
+    attempts++
+    if (framesIdentical(previous, current)) {
+      identicalFrames++
+      if (identicalFrames >= REQUIRED_IDENTICAL_PROOF_FRAMES) return current
+    } else {
+      identicalFrames = 1
+    }
+    previous = current
   }
-  return decodePngDataUrl(result.dataUrl)
+  throw new Error(
+    `sootsim screenshot did not reach ${REQUIRED_IDENTICAL_PROOF_FRAMES} identical idle frames in ${attempts} captures`,
+  )
 }
 
 async function writeSootsimScreenshot(
@@ -892,8 +892,23 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
 
     async replaceText(text: string) {
       const page = getPage()
-      await focusElementForTextEntry(el)
       const node = await findNodeByMatcher(matcher)
+      if (
+        matcher.type === 'id' &&
+        typeof node?.nodeId === 'number' &&
+        node.nodeId >= 0x40000000
+      ) {
+        const replaced = await page.evaluate(
+          async ({ id, value }) => {
+            const mainShell = window.SootSim?.bridges?.mainShell
+            if (typeof mainShell?.callTestBridge !== 'function') return false
+            return mainShell.callTestBridge('replaceTextByTestId', id, value)
+          },
+          { id: matcher.value, value: text },
+        )
+        if (replaced === true) return
+      }
+      await focusElementForTextEntry(el)
       const value = typeof node?.text === 'string' ? node.text : ''
       for (let i = 0; i < value.length; i++) {
         await page.keyboard.press('Backspace')
@@ -1267,6 +1282,40 @@ export const device = {
     // toggled on an existing context.
     recordVideoDir?: string
   }) {
+    if (
+      _page &&
+      opts?.newInstance === false &&
+      !opts.delete &&
+      !opts.recordVideoDir &&
+      _suspendedAppId
+    ) {
+      const page = _page
+      const appId = _suspendedAppId
+      await page.evaluate(
+        (id) => window.SootSim?.bridges?.mainShell?.launchApp?.(id),
+        appId,
+      )
+      await pollUntil(
+        () =>
+          page.evaluate(async (id) => {
+            const state = await window.SootSim?.bridges?.mainShell?.getState?.()
+            return (
+              state?.state === 'app' &&
+              state.activeApp === id &&
+              state.switcherPhase === 'idle'
+            )
+          }, appId),
+        Boolean,
+        {
+          timeoutMs: 10000,
+          label: `SootSim app ${appId} to resume`,
+        },
+      )
+      _suspendedAppId = null
+      await waitForSootsimTree(page, 10000)
+      return
+    }
+
     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
@@ -2237,7 +2286,28 @@ export const device = {
   },
 
   async sendToHome() {
-    // no-op
+    const page = getPage()
+    _suspendedAppId = await page.evaluate(async () => {
+      const state = await window.SootSim?.bridges?.mainShell?.getState?.()
+      const appId = state?.activeApp
+      if (typeof appId !== 'string') {
+        throw new Error(`cannot send an inactive SootSim app home`)
+      }
+      window.SootSim?.bridges?.mainShell?.goHome?.()
+      return appId
+    })
+    await pollUntil(
+      () =>
+        page.evaluate(async () => {
+          const state = await window.SootSim?.bridges?.mainShell?.getState?.()
+          return state?.state === 'home' && state.switcherPhase === 'idle'
+        }),
+      Boolean,
+      {
+        timeoutMs: 10000,
+        label: 'SootSim home transition',
+      },
+    )
   },
 
   // get direct access to the playwright page for advanced use

package/detox/proof-frame.cjs

@@ -0,0 +1,107 @@
+// 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,
+})
+
+const REQUIRED_IDENTICAL_PROOF_FRAMES = 3
+
+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,
+  framesIdentical,
+  measureProofFrameContent,
+  settleDecision,
+}