peachsim 0.1.527

package/cli/commands/inspect/memory.ts

@@ -0,0 +1,215 @@
+// `rnx get memory` / `rnx debug memory` — per-worker live object
+// counts (nodes registered, pictures, raster images, paragraphs, yoga wasm
+// nodes), image-loader cache, and JS heaps. one-shot by default; --watch
+// samples repeatedly and reports per-counter slope, which is the leak-RCA
+// workflow: run the repro, watch which counter's slope tracks RSS.
+
+import { inspectMemory, type MemoryReport, type WorkerMemorySample } from './core'
+import { printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n}B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`
+  return `${(n / 1024 / 1024).toFixed(1)}MB`
+}
+
+function pct(num: number, denom: number): string {
+  if (denom <= 0) return '?'
+  return `${((num / denom) * 100).toFixed(0)}%`
+}
+
+// flatten one report into named numeric counters so watch mode can diff and
+// slope every field uniformly.
+function flattenCounters(report: MemoryReport): Record<string, number> {
+  const out: Record<string, number> = {}
+  const worker = (prefix: string, w: WorkerMemorySample | null) => {
+    if (!w) return
+    if (w.nodesRegistered != null) out[`${prefix}.nodes`] = w.nodesRegistered
+    if (w.nodesDetached != null) out[`${prefix}.detached`] = w.nodesDetached
+    if (w.objects) {
+      out[`${prefix}.paragraphs`] = w.objects.paragraphs
+      out[`${prefix}.yogaNodes`] = w.objects.yogaNodes
+      out[`${prefix}.pictures`] = w.objects.pictures
+      out[`${prefix}.rasterImages`] = w.objects.rasterImages
+    }
+    if (w.imageLoader) {
+      out[`${prefix}.imageCacheEntries`] = w.imageLoader.cacheEntries
+      out[`${prefix}.imagePixelBytes`] = w.imageLoader.cachePixelBytes
+    }
+    if (w.workerHeap) out[`${prefix}.heapBytes`] = w.workerHeap.usedJSHeapSize
+    if (w.wasmHeapBytes != null) out[`${prefix}.wasmHeapBytes`] = w.wasmHeapBytes
+  }
+  worker('tenant', report.tenant)
+  worker('shell', report.shell)
+  worker('compositor', report.compositor)
+  if (report.hostHeap) out['host.heapBytes'] = report.hostHeap.usedJSHeapSize
+  return out
+}
+
+function formatCounter(key: string, value: number): string {
+  return key.endsWith('Bytes') ? formatBytes(value) : String(value)
+}
+
+function printWorkerBlock(name: string, w: WorkerMemorySample | null): void {
+  if (!w) {
+    console.log(`    ${name}: not available`)
+    return
+  }
+  const objects = w.objects
+  console.log(`    ${name}`)
+  if (w.nodesRegistered != null) {
+    console.log(`      nodes registered:  ${w.nodesRegistered}`)
+  }
+  if (w.nodesDetached != null) {
+    const types = Object.entries(w.detachedTypes ?? {})
+      .map(([type, count]) => `${type}:${count}`)
+      .join(' ')
+    console.log(
+      `      nodes detached:    ${w.nodesDetached}${types ? ` (${types})` : ''}`,
+    )
+  }
+  if (objects) {
+    console.log(`      paragraphs:        ${objects.paragraphs}`)
+    console.log(`      yoga nodes:        ${objects.yogaNodes}`)
+    console.log(`      pictures:          ${objects.pictures}`)
+    console.log(`      raster images:     ${objects.rasterImages}`)
+  }
+  if (w.activeNativeAnimations != null) {
+    console.log(`      native anims:      ${w.activeNativeAnimations}`)
+  }
+  if (w.imageLoader) {
+    const im = w.imageLoader
+    console.log(
+      `      image cache:       ${im.cacheEntries}/${im.cacheMaxEntries} entries, ${formatBytes(im.cachePixelBytes)}/${formatBytes(im.cachePixelBudget)} (${pct(im.cachePixelBytes, im.cachePixelBudget)})`,
+    )
+  }
+  if (w.workerHeap) {
+    console.log(
+      `      js heap:           ${formatBytes(w.workerHeap.usedJSHeapSize)} used / ${formatBytes(w.workerHeap.totalJSHeapSize)} total`,
+    )
+  }
+  if (w.wasmHeapBytes != null) {
+    console.log(`      canvaskit wasm:    ${formatBytes(w.wasmHeapBytes)}`)
+  }
+}
+
+function printReport(report: MemoryReport): void {
+  console.log('  memory:')
+  printWorkerBlock('tenant worker', report.tenant)
+  printWorkerBlock('shell worker', report.shell)
+  printWorkerBlock('compositor worker', report.compositor)
+  if (report.hostHeap) {
+    console.log('    host')
+    console.log(
+      `      js heap:           ${formatBytes(report.hostHeap.usedJSHeapSize)} used / ${formatBytes(report.hostHeap.totalJSHeapSize)} total`,
+    )
+  } else {
+    console.log('    host js heap: not available (chrome only)')
+  }
+}
+
+function readNumberFlag(args: string[], flag: string, fallback: number): number {
+  const idx = args.indexOf(flag)
+  if (idx === -1) return fallback
+  const value = Number(args[idx + 1])
+  return Number.isFinite(value) && value > 0 ? value : fallback
+}
+
+export async function runMemorySubcommand(
+  bridge: WsBridge,
+  opts: { args: string[] } = { args: [] },
+): Promise<void> {
+  const json = wantsJson(opts.args)
+  const watchIdx = opts.args.indexOf('--watch')
+
+  if (watchIdx === -1) {
+    const report = await inspectMemory(bridge)
+    if (json) {
+      printJson(report)
+      return
+    }
+    printReport(report)
+    return
+  }
+
+  // --watch [seconds] — sample every --interval seconds (default 5) for the
+  // given duration (default 60s), then report per-counter slope.
+  const durationValue = Number(opts.args[watchIdx + 1])
+  const durationSec =
+    Number.isFinite(durationValue) && durationValue > 0 ? durationValue : 60
+  const intervalSec = readNumberFlag(opts.args, '--interval', 5)
+
+  const samples: Array<{ tSec: number; counters: Record<string, number> }> = []
+  const start = Date.now()
+  let prev: Record<string, number> | null = null
+
+  if (!json) {
+    console.log(`  sampling every ${intervalSec}s for ${durationSec}s — deltas per tick:`)
+  }
+
+  while (true) {
+    const report = await inspectMemory(bridge)
+    const tSec = (Date.now() - start) / 1000
+    const counters = flattenCounters(report)
+    samples.push({ tSec, counters })
+
+    if (!json) {
+      const parts: string[] = []
+      for (const [key, value] of Object.entries(counters)) {
+        const delta = prev && key in prev ? value - prev[key] : null
+        if (delta === null || delta === 0) continue
+        const sign = delta > 0 ? '+' : '-'
+        const deltaStr = key.endsWith('Bytes')
+          ? `${sign}${formatBytes(Math.abs(delta))}`
+          : `${sign}${Math.abs(delta)}`
+        parts.push(`${key} ${formatCounter(key, value)} (${deltaStr})`)
+      }
+      console.log(
+        `  t+${tSec.toFixed(0)}s ${
+          parts.length
+            ? parts.join('  ')
+            : prev
+              ? 'no change'
+              : Object.entries(counters)
+                  .map(([k, v]) => `${k} ${formatCounter(k, v)}`)
+                  .join('  ')
+        }`,
+      )
+    }
+    prev = counters
+
+    if (tSec >= durationSec) break
+    await new Promise((resolve) => setTimeout(resolve, intervalSec * 1000))
+  }
+
+  // per-counter slope over the whole window
+  const first = samples[0]
+  const last = samples[samples.length - 1]
+  const elapsed = Math.max(last.tSec - first.tSec, 0.001)
+  const perSecond: Record<string, number> = {}
+  for (const key of Object.keys(last.counters)) {
+    if (!(key in first.counters)) continue
+    perSecond[key] = (last.counters[key] - first.counters[key]) / elapsed
+  }
+
+  if (json) {
+    printJson({ samples, perSecond, elapsedSec: elapsed })
+    return
+  }
+
+  console.log(`\n  slope over ${elapsed.toFixed(0)}s:`)
+  const moving = Object.entries(perSecond)
+    .filter(([, v]) => v !== 0)
+    .sort((a, b) => Math.abs(b[1]) - Math.abs(a[1]))
+  if (moving.length === 0) {
+    console.log('    all counters flat')
+    return
+  }
+  for (const [key, rate] of moving) {
+    const label = key.endsWith('Bytes')
+      ? `${formatBytes(Math.abs(rate))}/s${rate < 0 ? ' (shrinking)' : ''}`
+      : `${rate > 0 ? '+' : ''}${rate.toFixed(2)}/s`
+    console.log(`    ${key.padEnd(28)}${label}`)
+  }
+}

package/cli/commands/inspect/redaction.ts

@@ -0,0 +1,39 @@
+export const SECURE_TEXT_REDACTION = '<redacted secure text>'
+
+type KeyboardSpecLike = {
+  secureTextEntry?: boolean | null
+  keyboardType?: string | null
+} | null
+
+type KeyboardStateLike = {
+  layout?: { spec?: KeyboardSpecLike } | null
+  spec?: KeyboardSpecLike
+  focusedInput?: Record<string, unknown> | null
+} | null
+
+export function isSecureKeyboardState(state: KeyboardStateLike): boolean {
+  const spec = state?.layout?.spec ?? state?.spec ?? null
+  return !!spec?.secureTextEntry && spec.keyboardType !== 'visible-password'
+}
+
+export function redactTextForKeyboardState(
+  text: string,
+  state: KeyboardStateLike,
+): string {
+  return isSecureKeyboardState(state) ? SECURE_TEXT_REDACTION : text
+}
+
+export function redactKeyboardStateForOutput<T extends KeyboardStateLike>(state: T): T {
+  if (!state || !isSecureKeyboardState(state)) return state
+  const focusedInput = state.focusedInput
+  if (!focusedInput || typeof focusedInput !== 'object') return state
+  return {
+    ...state,
+    focusedInput: {
+      ...focusedInput,
+      secureTextEntry: true,
+      text:
+        typeof focusedInput.text === 'string' ? SECURE_TEXT_REDACTION : focusedInput.text,
+    },
+  }
+}

package/cli/commands/inspect/resolve-target.ts

@@ -0,0 +1,77 @@
+import { isSimSemanticTree, type InspectBridge } from './core'
+
+// read a --testid / --text flag from args. returns null when neither is
+// present so coord-based do verbs can fall through to their positional path.
+//
+// pass `positional` from a verb whose positionals are x/y coordinates (tap,
+// double-tap, long-press) and a bare non-numeric first positional reads as a
+// testID: `rnx do tap my-button` works like `do tap-id my-button` and like
+// `do scroll <id>`, instead of failing with a usage line for the one verb an
+// agent is most likely to reach for. a coordinate is always numeric, so there
+// is nothing to disambiguate.
+export function readTargetFlag(
+  args: string[],
+  positional?: string[],
+): { mode: 'testid' | 'text'; value: string } | null {
+  const tid = args.indexOf('--testid')
+  if (tid >= 0 && args[tid + 1]) return { mode: 'testid', value: args[tid + 1] }
+  const alt = args.indexOf('--test-id')
+  if (alt >= 0 && args[alt + 1]) return { mode: 'testid', value: args[alt + 1] }
+  const text = args.indexOf('--text')
+  if (text >= 0 && args[text + 1]) return { mode: 'text', value: args[text + 1] }
+  const bare = positional?.[1]
+  if (bare && !bare.startsWith('-') && !Number.isFinite(Number(bare))) {
+    return { mode: 'testid', value: bare }
+  }
+  return null
+}
+
+export interface ResolvedTargetCoords {
+  nodeId?: number
+  x: number
+  y: number
+  testID?: string | null
+  text?: string | null
+  type?: string | null
+}
+
+export async function resolveTargetCoords(
+  bridge: InspectBridge,
+  target: { mode: 'testid' | 'text'; value: string },
+): Promise<ResolvedTargetCoords | null> {
+  const result: unknown = await bridge.send({
+    type: 'resolve',
+    selector:
+      target.mode === 'testid' ? { testID: target.value } : { text: target.value },
+  })
+  if (result === null) return null
+  if (typeof result !== 'object') throw new Error('resolve returned an invalid result')
+  const match = Reflect.get(result, 'match')
+  const resolvedTarget = Reflect.get(result, 'target')
+  const semanticNodes = [match, resolvedTarget]
+  const point = Reflect.get(result, 'point')
+  const x =
+    point !== null && typeof point === 'object' ? Reflect.get(point, 'x') : undefined
+  const y =
+    point !== null && typeof point === 'object' ? Reflect.get(point, 'y') : undefined
+  if (
+    !isSimSemanticTree(semanticNodes) ||
+    typeof x !== 'number' ||
+    !Number.isFinite(x) ||
+    typeof y !== 'number' ||
+    !Number.isFinite(y)
+  ) {
+    throw new Error('resolve returned an invalid result')
+  }
+  const semanticMatch = semanticNodes[1]
+  if (!semanticMatch) throw new Error('resolve returned an invalid result')
+  return {
+    x,
+    y,
+    nodeId: semanticMatch.nodeId,
+    testID: semanticMatch.testID ?? null,
+    text:
+      semanticMatch.text ?? (target.mode === 'text' ? target.value : semanticMatch.label),
+    type: semanticMatch.type,
+  }
+}

package/cli/commands/inspect/screens.ts

@@ -0,0 +1,78 @@
+// `rnx get screens` — print the current navigation stack + shell state +
+// any presented modal + keyboard. answers "what screen am I on?" without
+// having to dump the whole tree or scrape screen-specific testIDs.
+//
+// sources:
+//   - navigation-runtime snapshot (test bridge) for screen stack + phase
+//   - mainShell.getState() for active app + switcher / launch progress
+//   - __sootsimKeyboard.getLayout() for keyboard visibility + spec
+
+import { inspectScreens } from './core'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runScreensSubcommand(
+  bridge: WsBridge,
+  opts: { json?: boolean } = {},
+): Promise<void> {
+  const { nav, route, keyboard, shell } = await inspectScreens(bridge)
+
+  if (opts.json) {
+    console.log(JSON.stringify({ shell: shell ?? null, nav, route, keyboard }, null, 2))
+    return
+  }
+
+  const lines: string[] = []
+
+  // shell — what app, what switcher state
+  if (shell) {
+    const activeApp = shell.activeApp ?? shell.state ?? '<none>'
+    const switcher = shell.showSwitcher ? ' (app switcher open)' : ''
+    const launchProgress =
+      typeof shell.launchProgress === 'number' && shell.launchProgress < 0.98
+        ? ` launching (${Math.round(shell.launchProgress * 100)}%)`
+        : ''
+    lines.push(`shell:    ${activeApp}${switcher}${launchProgress}`)
+  } else {
+    lines.push(`shell:    <unavailable>`)
+  }
+
+  // navigation stack
+  if (nav) {
+    const phase =
+      nav.transitionPhase !== 'idle'
+        ? ` (${nav.transitionPhase}, ${nav.activeTransitionCount} active)`
+        : ''
+    lines.push(`nav:      phase=${nav.transitionPhase}${phase}`)
+    if (nav.screens.length === 0) {
+      lines.push(`  <no registered screens — app may not use react-native-screens>`)
+    } else {
+      for (const s of nav.screens) {
+        const marker = s.isActive ? '▶' : ' '
+        const route = s.routeName ? ` ${s.routeName}` : ''
+        const header = s.headerHeight > 0 ? ` header=${s.headerHeight}` : ''
+        const lt =
+          s.largeTitleState && s.largeTitleState !== 'expanded'
+            ? ` large-title=${s.largeTitleState}`
+            : ''
+        lines.push(`  ${marker} #${s.id}${route}${header}${lt}`)
+      }
+    }
+  } else {
+    lines.push(`nav:      <runtime not available>`)
+  }
+  lines.push(`route:    ${route?.currentPath ?? '<unavailable>'}`)
+  if (route?.coveringPath) {
+    lines.push(`covered:  a presented screen (${route.coveringPath}) is above this route`)
+  }
+
+  // keyboard
+  if (keyboard && keyboard.visible) {
+    const type = keyboard.spec?.keyboardType ?? 'default'
+    const ret = keyboard.spec?.returnKeyType ?? 'default'
+    lines.push(`keyboard: visible (${type}, return=${ret}, mode=${keyboard.mode ?? '?'})`)
+  } else {
+    lines.push(`keyboard: hidden`)
+  }
+
+  console.log(lines.join('\n'))
+}

package/cli/commands/inspect/settle.ts

@@ -0,0 +1,32 @@
+import { waitForSootsimIdle } from './settling'
+import type { WsBridge } from '../../ws-bridge'
+
+// default: layout hash stable for 3 consecutive polls. --strict additionally
+// requires worker queryStats animation flags to be false — use when the
+// target app has no perpetual background animation.
+export async function runSettleSubcommand(opts: {
+  bridge: WsBridge
+  args: string[]
+  positional: string[]
+}): Promise<void> {
+  const { bridge, args, positional } = opts
+  const maxMs = positional[1] ? Number(positional[1]) * 1000 : 3000
+  if (bridge.plane === 'cloud') {
+    const maxFrames = Math.max(1, Math.min(600, Math.ceil(maxMs / 16)))
+    const result: unknown = await bridge.send({ type: 'settle', maxFrames })
+    const frames =
+      result !== null && typeof result === 'object' ? Reflect.get(result, 'frames') : null
+    console.log(
+      typeof frames === 'number' ? `  settled in ${frames} frames` : '  settled',
+    )
+    return
+  }
+  const strict = args.includes('--strict')
+  const { elapsed, settled } = await waitForSootsimIdle({ bridge, maxMs, strict })
+
+  if (settled) {
+    console.log(`  settled in ${elapsed}ms`)
+  } else {
+    console.log(`  timed out after ${elapsed}ms (may still be animating)`)
+  }
+}

package/cli/commands/inspect/settling.ts

@@ -0,0 +1,197 @@
+import type { InspectBridge } from './core'
+
+export type WaitForSootsimIdleOptions = {
+  bridge: InspectBridge
+  simId?: string
+  maxMs: number
+  pollMs?: number
+  stablePolls?: number
+  strict?: boolean
+}
+
+export type WaitForSootsimIdleResult = {
+  elapsed: number
+  settled: boolean
+  // what the last poll still saw moving. a settle that only reports "did not
+  // settle" cannot tell a slow screen from one that animates forever, and the
+  // two need opposite fixes.
+  blockedBy: string
+}
+
+export async function waitForSootsimIdle({
+  bridge,
+  simId,
+  maxMs,
+  pollMs = 50,
+  stablePolls = 3,
+  strict = false,
+}: WaitForSootsimIdleOptions): Promise<WaitForSootsimIdleResult> {
+  const result = await bridge.send(
+    {
+      type: 'evaluate',
+      simId,
+      code: `(async () => {
+      const start = Date.now()
+      const deadline = start + ${Math.max(0, Math.round(maxMs))}
+      const pollMs = ${Math.max(1, Math.round(pollMs))}
+      const requiredStablePolls = ${Math.max(1, Math.round(stablePolls))}
+      const strict = ${strict ? 'true' : 'false'}
+      const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+      // route-aware settle: a tap that pushes/pops a screen is async — the
+      // old screen still renders for a moment, then the new one mounts and
+      // its content loads. a pure layout-hash check reports "idle" on the
+      // outgoing screen or on the incoming skeleton, so a driver re-taps
+      // and stacks duplicate navigations. drain any in-flight screen
+      // transition FIRST, bounded by the overall budget. when no
+      // transition is happening this returns in ~80ms (startWindowMs), so
+      // a plain button tap barely pays for it.
+      try {
+        const wfst = window.__sootsimTest?.waitForScreenTransitions
+        if (typeof wfst === 'function') {
+          const remaining = deadline - Date.now()
+          if (remaining > 120) {
+            await wfst({
+              timeoutMs: Math.min(remaining - 80, 4000),
+              settleMs: 64,
+              startWindowMs: 80,
+            })
+          }
+        }
+      } catch {}
+
+      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
+            // settle waits for real content, capped by the budget.
+            const pf = stats.memory && stats.memory.imageLoader
+              ? stats.memory.imageLoader.pendingFetches
+              : 0
+            pendingFetches = typeof pf === 'number' ? pf : 0
+          }
+        } catch {}
+        try {
+          const counts = await window.__sootsimTest?.getRequestCounts?.()
+          requestTotal = typeof counts?.total === 'number' ? counts.total : 0
+          requestInFlight = typeof counts?.inFlight === 'number' ? counts.inFlight : 0
+        } catch {}
+        const root = window.__sootsimRoot
+        const nodes = []
+        if (root) {
+          const walk = (n) => {
+            if (n.layout && n.layout.width > 0) {
+              nodes.push(Math.round(n.layout.x) + ',' + Math.round(n.layout.y) + ',' + Math.round(n.layout.width))
+            }
+            for (const c of n.children || []) walk(c)
+          }
+          walk(root)
+        }
+        return { layout: nodes.join(';'), animating, layoutDirty, pendingFetches, renderStatsAvailable, requestTotal, requestInFlight }
+      }
+
+      // how long generic background network is allowed to keep us waiting AFTER
+      // the screen is otherwise visually settled. apps with continuous traffic
+      // (polling, realtime sockets, a tap that fires 20-50 fetches) never reach
+      // requestInFlight===0 / a stable requestTotal, so requiring full network
+      // quiet burns the ENTIRE budget on every command — the leading idle that
+      // failed PR-preview recordings for network-heavy apps (3pc fight-pulse).
+      // layout-stability + the image-loader already prove visible content
+      // loaded (a data load changes layout; an image load shows in the loader),
+      // so the generic request counters are a courtesy, not a gate: honor them
+      // only within this grace once the screen is visually still.
+      const networkQuietGraceMs = 1200
+      let lastLayout = ''
+      let lastRequestTotal = -1
+      let stable = 0
+      let visuallyStillSince = 0
+      // counts across the whole budget: a flag that is true on every poll is a
+      // different bug from one that is true intermittently, and the two need
+      // opposite fixes (engine vs budget).
+      let polls = 0
+      let dirtyPolls = 0
+      let animatingPolls = 0
+      let layoutChangedPolls = 0
+      while (Date.now() < deadline) {
+        const snapshot = await readSnapshot()
+        polls++
+        if (snapshot.layoutDirty) dirtyPolls++
+        if (snapshot.animating) animatingPolls++
+        if (polls > 1 && snapshot.layout !== lastLayout) layoutChangedPolls++
+        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 =
+          strictOk && snapshot.pendingFetches === 0 && snapshot.layout === lastLayout
+        // generic network quiet: nothing in flight and no new requests issued.
+        const networkQuiet =
+          snapshot.requestInFlight === 0 && snapshot.requestTotal === lastRequestTotal
+        if (visuallyStill) {
+          stable++
+          if (visuallyStillSince === 0) visuallyStillSince = Date.now()
+          // settle once the screen has held still long enough AND either the
+          // network is genuinely quiet OR it has refused to quiet within the
+          // grace (continuous background traffic must not block forever).
+          if (
+            stable >= requiredStablePolls &&
+            (networkQuiet || Date.now() - visuallyStillSince >= networkQuietGraceMs)
+          ) {
+            return { settled: true, elapsed: Date.now() - start, blockedBy: '' }
+          }
+        } else {
+          stable = 0
+          visuallyStillSince = 0
+        }
+        lastLayout = snapshot.layout
+        lastRequestTotal = snapshot.requestTotal
+        await sleep(pollMs)
+      }
+      const last = await readSnapshot()
+      const blockers = []
+      if (strict && !last.renderStatsAvailable) blockers.push('render stats unavailable')
+      if (last.animating) blockers.push('animations still running')
+      if (last.layoutDirty) blockers.push('layout still dirty')
+      if (last.pendingFetches > 0) blockers.push(last.pendingFetches + ' image fetches pending')
+      if (last.layout !== lastLayout) blockers.push('layout still changing')
+      if (last.requestInFlight > 0) blockers.push(last.requestInFlight + ' requests in flight')
+      return {
+        settled: false,
+        elapsed: Date.now() - start,
+        blockedBy:
+          (blockers.length ? blockers.join(', ') : 'unknown') +
+          ' over ' + polls + ' polls (layout changed ' + layoutChangedPolls +
+          'x, layoutDirty ' + dirtyPolls + 'x, animating ' + animatingPolls + 'x)',
+      }
+    })()`,
+    },
+    {
+      timeoutMs: maxMs + 1_000,
+    },
+  )
+
+  const { elapsed, settled, blockedBy } = (result ??
+    {}) as Partial<WaitForSootsimIdleResult>
+  return {
+    elapsed: typeof elapsed === 'number' ? elapsed : maxMs,
+    settled: settled === true,
+    blockedBy: typeof blockedBy === 'string' ? blockedBy : 'unknown',
+  }
+}