rnxsim 0.1.313 → 0.1.314

package/cli/commands/inspect/core.ts

@@ -0,0 +1,2405 @@
+// transport-agnostic sootsim inspect-verb kernels.
+//
+// each function here builds the JS a verb runs against a sootsim instance and
+// returns *structured data* — no arg parsing, no stdout, no formatting. the
+// CLI subcommand handlers wrap these with their WS bridge + text formatting;
+// the in-browser agent wraps them with an in-process bridge over its preview
+// window. one implementation, two transports — the DRY core of the inspect
+// surface.
+//
+// MUST stay browser-safe: no node builtins, no `process`, no `ws`. the only
+// dependency is the `InspectBridge.send` seam below, which both transports
+// satisfy (the CLI's `WsBridge` already has a matching `send`).
+
+import type {
+  SootSimRouteInfo,
+  SootSimRequestEntry,
+  SootSimTimelineEvent,
+  SootSimTimelineKind,
+  SootSimTimelineQuery,
+  SootSimTimelineQueryResult,
+  SootSimTimelineSummary,
+} from '@sootsim/globals'
+
+// resolve a `--max-ms <n>` flag, tolerating the spellings agents and humans
+// actually type (`--maxMs`, `--maxms`, `--max_ms`). a silently-ignored
+// timeout flag is a sharp edge: the call doesn't error, it just uses the
+// default, so the operator thinks their bound applied when it didn't.
+export function resolveMaxMsFlag(args: string[], fallbackMs: number): number {
+  const aliases = ['--max-ms', '--maxMs', '--maxms', '--max_ms']
+  for (const flag of aliases) {
+    const i = args.indexOf(flag)
+    if (i >= 0 && args[i + 1]) {
+      const n = Number(args[i + 1])
+      if (Number.isFinite(n)) return Math.max(100, n)
+    }
+  }
+  return fallbackMs
+}
+
+// the minimal bridge an inspect kernel needs: a JSON command channel into a
+// sootsim instance. `{ type: 'evaluate', code }` evaluates JS in the page;
+// `{ type: 'call', path, args }` invokes a method by dotted path.
+export interface InspectBridge {
+  send(
+    cmd: { type: string; [k: string]: any },
+    opts?: { timeoutMs?: number },
+  ): Promise<any>
+}
+
+const INSPECT_PICK_COMMANDS = new Set([
+  'tap',
+  'double-tap',
+  'tap-text',
+  'tap-id',
+  'long-press',
+  'touch',
+])
+
+export function isInspectPickCommand(subcommand: string | null | undefined): boolean {
+  return typeof subcommand === 'string' && INSPECT_PICK_COMMANDS.has(subcommand)
+}
+
+export async function isInspectModeActive(bridge: InspectBridge): Promise<boolean> {
+  const active = await bridge.send({
+    type: 'evaluate',
+    code: 'window.__sootsimEngineState?.inspectActive === true',
+  })
+  return active === true
+}
+
+export async function shouldSkipAutoSettleForInspectPick(
+  bridge: InspectBridge,
+  subcommand: string | null | undefined,
+): Promise<boolean> {
+  if (!isInspectPickCommand(subcommand)) return false
+  try {
+    return await isInspectModeActive(bridge)
+  } catch {
+    return false
+  }
+}
+
+// `get count` — total SootSimNode count in the live tree.
+export async function inspectNodeCount(
+  bridge: InspectBridge,
+): Promise<{ nodes: number }> {
+  const count = await bridge.send({
+    type: 'evaluate',
+    code: '(async () => await window.__sootsimTest.getNodeCount())()',
+  })
+  return { nodes: typeof count === 'number' ? count : 0 }
+}
+
+// `get tree` — raw node tree dump. goes through the merged test bridge
+// (shell + tenant). `tree` is returned raw so each frontend formats it.
+// `format: 'boxes'` asks the engine for the structured rect tree (a JSON
+// string on the wire) and parses it here.
+export async function inspectTree(
+  bridge: InspectBridge,
+  depth = 5,
+  opts?: { format?: 'boxes' },
+): Promise<{ depth: number; tree: unknown }> {
+  const optsArg = opts?.format ? `, ${JSON.stringify(opts)}` : ''
+  const tree = await bridge.send({
+    type: 'evaluate',
+    code: `(async () => await window.__sootsimTest.dumpTree(${depth}${optsArg}))()`,
+  })
+  if (opts?.format === 'boxes' && typeof tree === 'string') {
+    try {
+      return { depth, tree: JSON.parse(tree) }
+    } catch {
+      return { depth, tree }
+    }
+  }
+  return { depth, tree }
+}
+
+// `get url` — the current page URL the bridge is attached to.
+export async function inspectUrl(bridge: InspectBridge): Promise<{ url: string }> {
+  const url = await bridge.send({ type: 'evaluate', code: 'window.location.href' })
+  return { url: typeof url === 'string' ? url : '' }
+}
+
+// ─── describe ───
+
+export interface DescribeDumpOptions {
+  describe: boolean
+  verbose: boolean
+  filter: string
+  testIdLike?: string
+  onlyGlob?: string
+  subtreeRoot?: string
+  compact: boolean
+  hideXy: boolean
+  includeOccluded?: boolean
+  // machine consumers keep the whole string; the terminal dump clips it
+  fullText?: boolean
+  // depth for the recursive dump. omitted means the default 12. setting it
+  // forces the recursive path, because the compact inspectable listing has no
+  // depth to honor and would silently ignore the request.
+  maxDepth?: number
+}
+
+export interface DescribeKeyboardLayout {
+  visible?: boolean
+  spec?: {
+    autoCapitalize?: string
+    keyboardType?: string
+    returnKeyType?: string
+  }
+  mode?: string
+  shifted?: boolean
+  capsLock?: boolean
+  accessoryBarId?: string | null
+}
+
+export interface DescribeResult {
+  tree?: string
+  shell?: {
+    state?: string
+    activeApp?: string
+    showSwitcher?: boolean
+    switcherPhase?: string
+  } | null
+  nodeCount?: number
+  keyboard?: DescribeKeyboardLayout | null
+}
+
+// `describe` — the visible-UI tree with layout + style annotations, plus shell
+// + keyboard state. the dump itself lives in the engine's test-bridge
+// `dumpTree`; this kernel just bundles the one evaluate call. callers own
+// arg-parsing, preflight, hints, watch loop, and formatting.
+export async function inspectDescribe(
+  bridge: InspectBridge,
+  dumpOpts: DescribeDumpOptions,
+): Promise<DescribeResult> {
+  // resolve the depth here rather than inside the eval string: it is a typed
+  // decision, and the generated code stays a literal call the caller can read.
+  const dumpDepth = dumpOpts.maxDepth ?? 12
+  const code = `(async () => {
+      const t = window.__sootsimTest
+      const mainShell = window.SootSim?.bridges?.mainShell
+      const kb = window.__sootsimKeyboard
+      if (!t) return { error: 'no test bridge' }
+
+      let shell = null
+      try {
+        shell = typeof mainShell?.getState === 'function' ? await mainShell.getState() : null
+      } catch {}
+
+      const opts = ${JSON.stringify(dumpOpts)}
+      const needsRecursiveDump =
+        opts.verbose || opts.subtreeRoot || opts.includeOccluded || opts.maxDepth != null
+      const globToRegex = (glob) => {
+        const escaped = String(glob).replace(/[.+^$(){}|[\\]\\\\]/g, '\\\\$&')
+        const body = escaped.replace(/\\*/g, '.*').replace(/\\?/g, '.')
+        return new RegExp('^' + body + '$', 'i')
+      }
+      // clipping a describe line is a DISPLAY decision. opts.fullText (set by
+      // \`describe --json\`) keeps the real string, so a bundle-eval stack or a
+      // red-box message reaches the caller whole instead of ending in an
+      // ellipsis nothing downstream can undo.
+      const clipForDisplay = (value, max) => {
+        const text = typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''
+        if (opts.fullText || text.length <= max) return text
+        return text.slice(0, max - 1).trimEnd() + '…'
+      }
+      const formatInspectableTree = async () => {
+        if (typeof t.listInspectable !== 'function') return null
+        const list = await t.listInspectable({})
+        if (!Array.isArray(list)) return null
+        const filter = typeof opts.filter === 'string' ? opts.filter.toLowerCase() : ''
+        const testIdRegex = opts.testIdLike ? globToRegex(opts.testIdLike) : null
+        const onlyRegex = opts.onlyGlob ? globToRegex(opts.onlyGlob) : null
+        const lines = []
+        let matched = 0
+        for (const node of list) {
+          const testID = node?.testID || node?.testId || ''
+          const role = node?.role || ''
+          const label = node?.accessibilityLabel || node?.label || ''
+          const text = node?.text || ''
+          if (testIdRegex && !testIdRegex.test(testID)) continue
+          const joined = [role, label, text, testID].filter(Boolean).join(' ')
+          if (onlyRegex && !onlyRegex.test(joined)) continue
+          if (filter && !joined.toLowerCase().includes(filter)) continue
+          matched++
+
+          const type = String(node?.type || 'node').toLowerCase()
+          const handlers = Array.isArray(node?.handlers) ? node.handlers : []
+          const parts = []
+          if (role) parts.push('[' + role + ']')
+          else if (handlers.length > 0) parts.push('[tap]')
+          else parts.push('<' + type + '>')
+          const visibleText = clipForDisplay(text, 50)
+          if (visibleText) parts.push(JSON.stringify(visibleText))
+          if (testID) parts.push('#' + testID)
+          if (label && label !== text) {
+            parts.push('label=' + JSON.stringify(clipForDisplay(label, 50)))
+          }
+          if (!opts.hideXy) {
+            const abs = node?.absolute || {}
+            const layout = node?.layout || {}
+            const x = Math.round(Number(abs.x) || 0)
+            const y = Math.round(Number(abs.y) || 0)
+            const w = Math.round(Number(layout.width) || 0)
+            const h = Math.round(Number(layout.height) || 0)
+            parts.push('@(' + x + ',' + y + ') ' + w + 'x' + h)
+          }
+          if (handlers.length > 0) parts.push('(tap)')
+          lines.push('  ' + parts.join(' '))
+        }
+        return { tree: lines.join('\\n'), matched }
+      }
+
+      let tree = ''
+      const compactResult = needsRecursiveDump ? null : await formatInspectableTree()
+      if (compactResult) {
+        tree = compactResult.tree
+      } else {
+        tree = await t.dumpTree(${dumpDepth}, opts)
+      }
+      const nodeCount = (await t.getNodeCount?.()) || 0
+      const keyboard = kb && typeof kb.getLayout === 'function' ? kb.getLayout() : null
+      return { tree, shell, nodeCount, keyboard }
+    })()`
+  const result = (await bridge.send({ type: 'evaluate', code })) as DescribeResult | null
+  return result ?? {}
+}
+
+// ─── get-layout ───
+//
+// per-element bounding-box measurement for meaningful elements on the current
+// screen. `describe` gives the element tree; this gives the numbers a designer
+// needs to check spacing/sizing parity: the on-screen box (x/y/w/h). callers opt
+// into computed borderRadius, per-side padding, fontSize, and visual style
+// fields with `styling:true` / `--styling`.
+//
+// the SAME LayoutElement shape is produced by both preview surfaces:
+//   - native/sootsim — `LAYOUT_GET_NATIVE_EVAL` reads the engine node tree via
+//     __sootsimTest.listInspectable() (the source `describe` uses), where each
+//     SootSimInspectInfo already carries absolute layout and optional style /
+//     box-model data.
+//   - web — the DOM extractor in webLayout.ts measures candidate elements with
+//     getBoundingClientRect(), and calls getComputedStyle() only for styling.
+// both feed the same `formatLayoutElements` renderer, so the agent tool and the
+// CLI print identical output regardless of surface.
+
+export interface LayoutBox {
+  x: number
+  y: number
+  w: number
+  h: number
+}
+
+export interface LayoutPadding {
+  t: number
+  r: number
+  b: number
+  l: number
+}
+
+export interface LayoutExtractionOptions {
+  styling?: boolean
+  // case-insensitive substring matched against text, testID, role, and
+  // selector. narrows a full-screen read down to the part being checked so
+  // styling detail stays affordable.
+  filter?: string
+}
+
+export interface LayoutTextContrast {
+  ratio: number | null
+  required: 3 | 4.5
+  foreground?: string
+  background?: string
+  reason?: string
+}
+
+export function scoreLayoutTextContrast(input: {
+  normal: { width: number; height: number; data: ArrayLike<number> }
+  background: { width: number; height: number; data: ArrayLike<number> }
+  box: LayoutBox
+  fontSize: number
+  fontWeight?: number
+}): LayoutTextContrast {
+  const required: 3 | 4.5 =
+    input.fontSize >= 18 || (input.fontSize >= 14 && (input.fontWeight ?? 400) >= 700)
+      ? 3
+      : 4.5
+  const { normal, background } = input
+  if (
+    normal.width <= 0 ||
+    normal.height <= 0 ||
+    normal.width !== background.width ||
+    normal.height !== background.height
+  ) {
+    return { ratio: null, required, reason: 'capture dimensions do not match' }
+  }
+  const left = Math.max(0, Math.floor(input.box.x))
+  const top = Math.max(0, Math.floor(input.box.y))
+  const right = Math.min(normal.width, Math.ceil(input.box.x + input.box.w))
+  const bottom = Math.min(normal.height, Math.ceil(input.box.y + input.box.h))
+  if (right <= left || bottom <= top) {
+    return { ratio: null, required, reason: 'text is outside the captured frame' }
+  }
+
+  const linear = (value: number) => {
+    const channel = value / 255
+    return channel <= 0.04045 ? channel / 12.92 : Math.pow((channel + 0.055) / 1.055, 2.4)
+  }
+  const ratioOf = (foreground: readonly number[], behind: readonly number[]) => {
+    const foregroundLuminance =
+      0.2126 * linear(foreground[0]) +
+      0.7152 * linear(foreground[1]) +
+      0.0722 * linear(foreground[2])
+    const backgroundLuminance =
+      0.2126 * linear(behind[0]) + 0.7152 * linear(behind[1]) + 0.0722 * linear(behind[2])
+    return (
+      (Math.max(foregroundLuminance, backgroundLuminance) + 0.05) /
+      (Math.min(foregroundLuminance, backgroundLuminance) + 0.05)
+    )
+  }
+  const hex = (color: readonly number[]) =>
+    `#${color
+      .slice(0, 3)
+      .map((value) => Math.round(value).toString(16).padStart(2, '0'))
+      .join('')}`
+  const area = (right - left) * (bottom - top)
+  const step = Math.max(1, Math.floor(Math.sqrt(area / 12_000)))
+  const offsetAt = (x: number, y: number) => (y * normal.width + x) * 4
+  const deltaAt = (offset: number) =>
+    Math.max(
+      Math.abs(normal.data[offset] - background.data[offset]),
+      Math.abs(normal.data[offset + 1] - background.data[offset + 1]),
+      Math.abs(normal.data[offset + 2] - background.data[offset + 2]),
+    )
+
+  let strongestDelta = 0
+  let strongestForeground: number[] | null = null
+  let opaqueBackground: number[] | null = null
+  for (let y = top; y < bottom; y += step) {
+    for (let x = left; x < right; x += step) {
+      const offset = offsetAt(x, y)
+      if (background.data[offset + 3] < 250) continue
+      const behind = [
+        background.data[offset],
+        background.data[offset + 1],
+        background.data[offset + 2],
+      ]
+      opaqueBackground ??= behind
+      const delta = deltaAt(offset)
+      if (delta <= strongestDelta) continue
+      strongestDelta = delta
+      strongestForeground = [
+        normal.data[offset],
+        normal.data[offset + 1],
+        normal.data[offset + 2],
+      ]
+    }
+  }
+  let bestRatio = Infinity
+  let bestForeground: number[] | null = null
+  let bestBackground: number[] | null = null
+  const consider = (foreground: number[], behind: number[]) => {
+    const ratio = ratioOf(foreground, behind)
+    if (ratio >= bestRatio) return
+    bestRatio = ratio
+    bestForeground = foreground
+    bestBackground = behind
+  }
+
+  if (strongestDelta >= 2 && strongestForeground) {
+    // The largest normal/background delta is the closest rendered sample to
+    // the solid glyph color. Compare that color against every background pixel
+    // where the suppressed pass proves text actually drew. This preserves the
+    // weak side of text over gradients instead of selecting its best contrast.
+    for (let y = top; y < bottom; y += step) {
+      for (let x = left; x < right; x += step) {
+        const offset = offsetAt(x, y)
+        if (background.data[offset + 3] < 250 || deltaAt(offset) < 2) {
+          continue
+        }
+        consider(strongestForeground, [
+          background.data[offset],
+          background.data[offset + 1],
+          background.data[offset + 2],
+        ])
+      }
+    }
+  } else if (opaqueBackground) {
+    // No final pixel changed when the renderer omitted this visible text. Its
+    // effective foreground is therefore identical to the pixels behind it:
+    // exact 1:1 contrast, not an "unmeasurable" escape hatch.
+    consider(opaqueBackground, opaqueBackground)
+  }
+
+  if (!bestForeground || !bestBackground || !Number.isFinite(bestRatio)) {
+    return {
+      ratio: null,
+      required,
+      reason: 'could not isolate opaque rendered text pixels',
+    }
+  }
+  return {
+    ratio: Math.round(bestRatio * 100) / 100,
+    required,
+    foreground: hex(bestForeground),
+    background: hex(bestBackground),
+  }
+}
+
+export interface LayoutElement {
+  // extractor-local identity and closest-first ancestry. app_get_layout uses
+  // these internally to distinguish real overlaps from ordinary nesting; the
+  // formatter intentionally omits them from the agent-facing rows.
+  nodeId?: string | number
+  ancestorIds?: Array<string | number>
+  // a stable way to refer to this element. testID/role when present; otherwise
+  // a CSS selector (web) or the engine node type (native).
+  selector?: string
+  testID?: string
+  role?: string
+  type: string
+  text?: string
+  // on-screen bounding box in device/viewport px (x/y are absolute).
+  box: LayoutBox
+  // box-model fields are zero-filled unless the caller opts into styling.
+  borderRadius: number
+  padding: LayoutPadding
+  fontSize: number
+  // styling — so a text-only agent (no vision) can still reason about visual
+  // quality: theme correctness (is this screen actually emerald?), contrast
+  // (color vs bg), washed-out opacity, garbled/struck text, clipping
+  // (overflow:hidden + tiny box), flat-vs-styled (no bg where a card is
+  // expected). colors are compacted css strings; each field is omitted when it
+  // holds its boring default so rows stay scannable.
+  color?: string
+  bg?: string
+  opacity?: number
+  fontWeight?: number
+  textDecoration?: string
+  overflow?: string
+  borderWidth?: number
+  // only when the element actually draws a border. every element has a
+  // resolved border-color, so reporting it unconditionally would be pure noise.
+  borderColor?: string
+  contrast?: LayoutTextContrast
+  // text-flow metrics (web extractor) — wrap quality a no-vision agent cannot
+  // otherwise see: how many lines the text broke into, whether the last line
+  // is a lone hanging word, and whether ellipsis truncation is active.
+  textLines?: number
+  lastLineWords?: number
+  // last line width relative to the widest line (0-1).
+  lastLineWidthRatio?: number
+  ellipsisActive?: boolean
+}
+
+export interface LayoutResult {
+  preview: 'web' | 'native'
+  count: number
+  elements: LayoutElement[]
+}
+
+// in-page extractor for the native preview. mirrors the visibility + device
+// sizing the a11y / wait-ready kernels use so "what's on screen" agrees across
+// the inspect surface. returns LayoutElement[] (or [] when the bridge is cold).
+export function layoutGetNativeEval(opts: LayoutExtractionOptions = {}): string {
+  const includeStyle = opts.styling === true
+  const filter = opts.filter?.trim().toLowerCase() ?? ''
+  return `(async () => {
+      const t = window.__sootsimTest
+      if (!t || typeof t.listInspectable !== 'function') return []
+      const list = await t.listInspectable({})
+      if (!Array.isArray(list)) return []
+      const includeStyle = ${JSON.stringify(includeStyle)}
+      const scoreContrast = ${scoreLayoutTextContrast.toString()}
+      // narrows by ELEMENT, not by style field: fewer rows, full detail on each.
+      const filter = ${JSON.stringify(filter)}
+      const matchesFilter = (n, text) => {
+        if (!filter) return true
+        const fields = [text, n.testID || n.testId, n.accessibilityRole || n.role, n.type]
+        return fields.some((f) => typeof f === 'string' && f.toLowerCase().includes(filter))
+      }
+
+      const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+      const round = (v) => Math.round(num(v))
+
+      // borderRadius can be authored as a string ("12px") or split per-corner;
+      // prefer the uniform borderRadius, else the largest corner radius present.
+      const radiusOf = (style) => {
+        if (!style) return 0
+        const keys = ['borderRadius','borderTopLeftRadius','borderTopRightRadius','borderBottomLeftRadius','borderBottomRightRadius']
+        let max = 0
+        for (const k of keys) {
+          const raw = style[k]
+          const n = typeof raw === 'number' ? raw : (typeof raw === 'string' ? parseFloat(raw) : NaN)
+          if (Number.isFinite(n)) max = Math.max(max, n)
+        }
+        return Math.round(max)
+      }
+      const fontSizeOf = (style) => {
+        if (!style) return 0
+        const raw = style.fontSize
+        const n = typeof raw === 'number' ? raw : (typeof raw === 'string' ? parseFloat(raw) : NaN)
+        return Number.isFinite(n) ? Math.round(n) : 0
+      }
+      // styling extractors — omit boring defaults so the agent only sees notable
+      // styling (low opacity, struck text, clipping, a real border/color).
+      const colorStr = (v) => {
+        if (v == null) return undefined
+        const s = String(v).split(' ').join('')
+        return s && s !== 'transparent' && s !== 'rgba(0,0,0,0)' ? s : undefined
+      }
+      const opacityOf = (style) => {
+        const o = style && style.opacity
+        const n = typeof o === 'number' ? o : (typeof o === 'string' ? parseFloat(o) : NaN)
+        return Number.isFinite(n) && n < 1 ? Math.round(n * 100) / 100 : undefined
+      }
+      const weightOf = (style) => {
+        const w = style && style.fontWeight
+        const n = w === 'bold' ? 700 : (typeof w === 'number' ? w : (typeof w === 'string' ? parseInt(w, 10) : NaN))
+        return Number.isFinite(n) && n >= 600 ? n : undefined
+      }
+      const decoOf = (style) => {
+        const d = style && (style.textDecorationLine || style.textDecoration)
+        return d && d !== 'none' && d !== 'normal' ? String(d).split(' ')[0] : undefined
+      }
+      const overflowOf = (style) => (style && style.overflow === 'hidden' ? 'hidden' : undefined)
+      const borderWOf = (style) => {
+        if (!style) return undefined
+        const keys = ['borderWidth','borderTopWidth','borderBottomWidth','borderLeftWidth','borderRightWidth']
+        let max = 0
+        for (const k of keys) {
+          const r = style[k]
+          const n = typeof r === 'number' ? r : (typeof r === 'string' ? parseFloat(r) : NaN)
+          if (Number.isFinite(n)) max = Math.max(max, n)
+        }
+        return max > 0 ? Math.round(max) : undefined
+      }
+      // only meaningful alongside a real border width, so it is resolved by the
+      // caller below rather than on its own.
+      const borderColorOf = (style) => {
+        if (!style) return undefined
+        const keys = ['borderColor','borderTopColor','borderBottomColor','borderLeftColor','borderRightColor']
+        for (const k of keys) {
+          const c = colorStr(style[k])
+          if (c) return c
+        }
+        return undefined
+      }
+
+      const isVisible = (n) => {
+        const layout = n && n.layout
+        if (!layout || layout.width <= 0 || layout.height <= 0) return false
+        const abs = (n && (n.absolute || n.absolutePosition)) || null
+        if (!abs) return true
+        const device = (n && n.device) || {}
+        const screenW = Number(device.width) || window.innerWidth || 0
+        const screenH = Number(device.height) || window.innerHeight || 0
+        if (!screenW || !screenH) return true
+        return abs.x + layout.width > 0 && abs.y + layout.height > 0 && abs.x < screenW && abs.y < screenH
+      }
+
+      const elements = list.filter(isVisible).filter((n) => {
+        const t = typeof n.text === 'string' && n.text.trim() ? n.text.trim() : undefined
+        return matchesFilter(n, t)
+      }).map((n) => {
+        const layout = n.layout || { x: 0, y: 0, width: 0, height: 0 }
+        const abs = n.absolute || n.absolutePosition || { x: layout.x, y: layout.y }
+        const text = typeof n.text === 'string' && n.text.trim() ? n.text.trim() : undefined
+        const base = {
+          ...(typeof n.nodeId === 'number'
+            ? {
+                nodeId: n.nodeId,
+                ancestorIds: Array.isArray(n.ancestors)
+                  ? n.ancestors.map((ancestor) => ancestor && ancestor.nodeId).filter((id) => typeof id === 'number')
+                  : [],
+              }
+            : {}),
+          testID: n.testID || n.testId || undefined,
+          role: n.accessibilityRole || n.role || undefined,
+          type: typeof n.type === 'string' ? n.type : 'node',
+          text,
+          box: { x: round(abs.x), y: round(abs.y), w: round(layout.width), h: round(layout.height) },
+          borderRadius: 0,
+          padding: { t: 0, r: 0, b: 0, l: 0 },
+          fontSize: 0,
+        }
+        if (!includeStyle) return base
+        // computedStyle has the resolved values; style is the curated subset —
+        // fall back across both so radius/fontSize survive either shape.
+        const style = Object.assign({}, n.style || {}, n.computedStyle || {})
+        const pad = (n.boxModel && n.boxModel.padding) || {}
+        const borderWidth = borderWOf(style)
+        return {
+          ...base,
+          borderRadius: radiusOf(style),
+          padding: { t: round(pad.top), r: round(pad.right), b: round(pad.bottom), l: round(pad.left) },
+          fontSize: text ? (fontSizeOf(style) || 14) : 0,
+          color: text ? colorStr(style.color) : undefined,
+          bg: colorStr(style.backgroundColor),
+          opacity: opacityOf(style),
+          fontWeight: weightOf(style),
+          textDecoration: decoOf(style),
+          overflow: overflowOf(style),
+          borderWidth,
+          borderColor: borderWidth ? borderColorOf(style) : undefined,
+        }
+      })
+      const textElements = elements.filter((element) => element.text && element.fontSize > 0)
+      if (!includeStyle || textElements.length === 0) return elements
+
+      const screenshot = window.SootSim && window.SootSim.bridges && window.SootSim.bridges.screenshot
+      if (typeof screenshot !== 'function') {
+        throw new Error('styled native layout requires the rnx capture bridge')
+      }
+      const device = list.find((node) => node && node.device)?.device || {}
+      const width = Math.round(Number(device.width) || window.innerWidth || 0)
+      const height = Math.round(Number(device.height) || window.innerHeight || 0)
+      if (!width || !height) throw new Error('native layout has no capture dimensions')
+      const capture = async (suppressText) => {
+        const dataUrl = await screenshot({
+          format: 'png',
+          outputWidth: width,
+          outputHeight: height,
+          ...(suppressText ? { suppressText: true } : {}),
+        })
+        const image = await new Promise((resolve, reject) => {
+          const next = new Image()
+          next.onload = () => resolve(next)
+          next.onerror = () => reject(new Error('could not decode native layout pixels'))
+          next.src = dataUrl
+        })
+        const canvas = document.createElement('canvas')
+        canvas.width = image.naturalWidth
+        canvas.height = image.naturalHeight
+        const context = canvas.getContext('2d', { willReadFrequently: true })
+        if (!context) throw new Error('could not read native layout pixels')
+        context.drawImage(image, 0, 0)
+        return context.getImageData(0, 0, canvas.width, canvas.height)
+      }
+      const normal = await capture(false)
+      const background = await capture(true)
+      for (const element of textElements) {
+        element.contrast = scoreContrast({
+          normal,
+          background,
+          box: element.box,
+          fontSize: element.fontSize,
+          fontWeight: element.fontWeight,
+        })
+      }
+      return elements
+    })()`
+}
+
+export const LAYOUT_GET_NATIVE_EVAL = layoutGetNativeEval()
+
+// `get-layout` (native) — bounding boxes for visible meaningful elements on the
+// sootsim/native preview. transport-agnostic: the CLI runs it over its WS
+// bridge, the agent runs it over its in-process preview bridge.
+export async function inspectGetLayout(
+  bridge: InspectBridge,
+  opts: LayoutExtractionOptions = {},
+): Promise<LayoutElement[]> {
+  const raw = await bridge.send({
+    type: 'evaluate',
+    code: layoutGetNativeEval(opts),
+  })
+  return Array.isArray(raw) ? (raw as LayoutElement[]) : []
+}
+
+// one-line-per-element renderer shared by the CLI and the agent tool so web +
+// native + every transport print the same thing. padding collapses to a single
+// number when uniform, and zero-valued fields are omitted to keep rows scannable.
+export function formatLayoutElements(
+  elements: readonly LayoutElement[],
+  opts?: { styling?: boolean },
+): string {
+  if (elements.length === 0) return '  no visible elements found'
+  const lines = elements.map((el) => {
+    const ident = el.testID
+      ? `#${el.testID}`
+      : el.selector
+        ? el.selector
+        : el.role
+          ? `[${el.role}]`
+          : `<${el.type}>`
+    const parts = [ident, `@(${el.box.x},${el.box.y})`, `${el.box.w}x${el.box.h}`]
+    if (el.borderRadius > 0) parts.push(`radius:${el.borderRadius}`)
+    const p = el.padding
+    if (p.t || p.r || p.b || p.l) {
+      const uniform = p.t === p.r && p.r === p.b && p.b === p.l
+      parts.push(uniform ? `pad:${p.t}` : `pad:${p.t},${p.r},${p.b},${p.l}`)
+    }
+    if (el.fontSize > 0) parts.push(`font:${el.fontSize}`)
+    // styling is opt-in (the `styling` flag): the default rows stay scannable
+    // for UI inspection, and a no-vision agent asks for styling when judging
+    // visual quality (contrast, washed-out, garbled/struck, clipping, flat).
+    if (opts?.styling) {
+      if (el.fontWeight) parts.push(`weight:${el.fontWeight}`)
+      if (el.color) parts.push(`color:${el.color}`)
+      if (el.bg) parts.push(`bg:${el.bg}`)
+      if (el.contrast) {
+        const score =
+          el.contrast.ratio == null
+            ? `?/${el.contrast.required}`
+            : `${el.contrast.ratio}/${el.contrast.required}${el.contrast.ratio < el.contrast.required ? ' FAIL' : ''}`
+        parts.push(`contrast:${score}`)
+        if (el.contrast.background) parts.push(`on:${el.contrast.background}`)
+      }
+      if (el.opacity != null) parts.push(`opacity:${el.opacity}`)
+      if (el.textDecoration) parts.push(`deco:${el.textDecoration}`)
+      if (el.overflow) parts.push(`overflow:${el.overflow}`)
+      if (el.borderWidth) {
+        parts.push(
+          el.borderColor
+            ? `border:${el.borderWidth}/${el.borderColor}`
+            : `border:${el.borderWidth}`,
+        )
+      }
+    }
+    if (el.text) {
+      const text = el.text.length > 40 ? `${el.text.slice(0, 39)}…` : el.text
+      parts.push(`"${text}"`)
+    }
+    return `  ${parts.join(' ')}`
+  })
+  return lines.join('\n')
+}
+
+// ─── accessibility ───
+
+export interface AccessibilityTreeNode {
+  role: string
+  label: string | null
+  hint: string | null
+  state: Record<string, unknown> | null
+  testID: string | null
+  position: { x: number; y: number } | null
+  size: { w: number; h: number } | null
+}
+
+const INSPECT_A11Y_CODE = `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return []
+
+      const readLayout = (n) => n?.layout || null
+      const readAbs = (n) => n?.absolutePosition || n?.absolute || null
+      const readRole = (n) => n?.accessibilityRole || n?.role || null
+      const readLabel = (n) => n?.accessibilityLabel || n?.label || n?.text || null
+      const readHint = (n) => n?.accessibilityHint || n?.hint || null
+      const readState = (n) => n?.accessibilityState || n?.state || null
+      const readTestId = (n) => n?.testID || n?.testId || null
+      const readType = (n) => typeof n?.type === 'string' ? n.type.toLowerCase() : n?.type
+      const readPressable = (n) => {
+        if (n?.pressable) return true
+        const handlers = Array.isArray(n?.handlers) ? n.handlers : []
+        const role = readRole(n)
+        return handlers.length > 0 || role === 'button' || role === 'link' || role === 'tab'
+      }
+      const isTextInput = (n) => n?.isTextInput === true
+      const isTextNode = (n) => readType(n) === 'text'
+      const isVisibleTarget = (n) => {
+        const layout = readLayout(n)
+        if (!layout || layout.width <= 0 || layout.height <= 0) return false
+        const abs = readAbs(n)
+        if (!abs) return true
+        const device = n?.device || {}
+        const screenW = Number(device.width) || window.innerWidth || 0
+        const screenH = Number(device.height) || window.innerHeight || 0
+        return (
+          abs.x + layout.width > 0 &&
+          abs.y + layout.height > 0 &&
+          abs.x < screenW &&
+          abs.y < screenH
+        )
+      }
+      const hasAccessibleSignal = (n) => {
+        const role = readRole(n)
+        const label = readLabel(n)
+        const hint = readHint(n)
+        if (role) return true
+        if (hint) return true
+        if (isTextInput(n)) return true
+        if (readPressable(n)) return true
+        if (isTextNode(n) && n?.text) return true
+        if (typeof label === 'string' && label.length <= 30 && label !== n?.text) return true
+        return false
+      }
+      const normalize = (n) => {
+        const layout = readLayout(n)
+        const abs = readAbs(n)
+        const role = readRole(n) || (readPressable(n) ? 'button' : isTextInput(n) ? 'textfield' : isTextNode(n) ? 'statictext' : 'none')
+        return {
+          role,
+          label: readLabel(n),
+          hint: readHint(n),
+          state: readState(n),
+          testID: readTestId(n),
+          position: abs ? { x: Math.round(abs.x), y: Math.round(abs.y) } : null,
+          size: layout ? { w: Math.round(layout.width), h: Math.round(layout.height) } : null,
+        }
+      }
+
+      if (typeof t.listInspectable === 'function') {
+        const list = await t.listInspectable({})
+        if (Array.isArray(list)) {
+          return list.filter(n => isVisibleTarget(n) && hasAccessibleSignal(n)).map(normalize)
+        }
+      }
+
+      const all = await t.queryAll({ pruneHidden: true })
+      return all
+        .filter(n => isVisibleTarget(n) && hasAccessibleSignal(n))
+        .map(normalize)
+    })()`
+
+// `get a11y` — flat accessibility summary for the currently visible SootSim
+// surface. listInspectable is preferred because it already resolves the active
+// shell/tenant surface and excludes covered launcher/app-switcher content.
+export async function inspectAccessibilityTree(
+  bridge: InspectBridge,
+): Promise<AccessibilityTreeNode[]> {
+  const nodes = await bridge.send({ type: 'evaluate', code: INSPECT_A11Y_CODE })
+  return Array.isArray(nodes) ? (nodes as AccessibilityTreeNode[]) : []
+}
+
+// ─── find ───
+
+export type FindMode =
+  | 'testid'
+  | 'role'
+  | 'type'
+  | 'pressable'
+  | 'interactive-targets'
+  | 'visible'
+  | 'text'
+
+export interface FindQuery {
+  testId?: string | null
+  role?: string | null
+  type?: string | null
+  text?: string | null
+  pressable?: boolean
+  visible?: boolean
+  interactive?: boolean
+}
+
+const FIND_INSPECTABLE_TARGETS = `
+      const fromInspectable = async () => {
+        if (typeof t.listInspectable !== 'function') return null
+        const list = await t.listInspectable({})
+        if (!Array.isArray(list)) return null
+        return list.map((n) => {
+          const role = n.accessibilityRole ?? n.role
+          const label = n.accessibilityLabel ?? n.label
+          const layout = n.layout
+          const absolutePosition = n.absolutePosition ?? n.absolute
+          const screenW = Number(n.device?.width) || window.innerWidth || 0
+          const screenH = Number(n.device?.height) || window.innerHeight || 0
+          const visibleFrame = layout && absolutePosition
+            ? {
+                x: Math.max(0, absolutePosition.x),
+                y: Math.max(0, absolutePosition.y),
+                width: Math.max(
+                  0,
+                  Math.min(screenW, absolutePosition.x + layout.width) -
+                    Math.max(0, absolutePosition.x),
+                ),
+                height: Math.max(
+                  0,
+                  Math.min(screenH, absolutePosition.y + layout.height) -
+                    Math.max(0, absolutePosition.y),
+                ),
+              }
+            : null
+          const handlers = Array.isArray(n.handlers) ? n.handlers : []
+          const pressable =
+            handlers.length > 0 ||
+            role === 'button' ||
+            role === 'link' ||
+            role === 'tab'
+          return {
+            type: typeof n.type === 'string' ? n.type.toLowerCase() : n.type,
+            id: n.id ?? n.nodeId,
+            nodeId: n.nodeId,
+            testID: n.testID ?? n.testId,
+            text: n.text,
+            layout,
+            absolutePosition,
+            visibleFrame,
+            style: n.computedStyle ?? n.style ?? {},
+            childCount: n.childCount ?? 0,
+            pressed: n.pressed ?? false,
+            pressable,
+            isTextInput: n.isTextInput ?? false,
+            accessible: n.accessible ?? true,
+            accessibilityLabel: label,
+            accessibilityRole: role,
+            accessibilityHint: n.accessibilityHint,
+            accessibilityState: n.accessibilityState,
+            accessibilityValue: n.accessibilityValue,
+          }
+        })
+      }
+      const isVisibleTarget = (n) => {
+        if (!n?.layout) return false
+        const frame = n.visibleFrame
+        if (frame) return frame.width > 0 && frame.height > 0
+        const abs = n.absolutePosition
+        if (!abs) return n.layout.width > 0 && n.layout.height > 0
+        const screenW = window.innerWidth || 0
+        const screenH = window.innerHeight || 0
+        return (
+          abs.x + n.layout.width > 0 &&
+          abs.y + n.layout.height > 0 &&
+          abs.x < screenW &&
+          abs.y < screenH
+        )
+      }
+`
+
+// resolve a find query to its mode + the JS to evaluate. precedence matches
+// the CLI: testid → role → type → pressable → interactive → visible → text.
+// returns null when nothing was asked for (caller prints usage).
+export function resolveFindMode(q: FindQuery): { mode: FindMode; code: string } | null {
+  if (q.testId) {
+    return {
+      mode: 'testid',
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return null
+      return (await t.findByTestId(${JSON.stringify(q.testId)})) || (await t.findById(${JSON.stringify(q.testId)}))
+    })()`,
+    }
+  }
+  if (q.role) {
+    return {
+      mode: 'role',
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return []
+      return await t.queryAll({ hasRole: ${JSON.stringify(q.role)}, pruneHidden: true })
+    })()`,
+    }
+  }
+  if (q.type) {
+    return {
+      mode: 'type',
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return []
+      return await t.queryAll({ type: ${JSON.stringify(q.type)}, pruneHidden: true })
+    })()`,
+    }
+  }
+  if (q.pressable) {
+    return {
+      mode: 'pressable',
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return []
+${FIND_INSPECTABLE_TARGETS}
+      const inspectable = await fromInspectable()
+      if (inspectable) return inspectable.filter(n => n.pressable && isVisibleTarget(n))
+      const all = await t.queryAll({ pruneHidden: true })
+      return all.filter(n => n.pressable && isVisibleTarget(n))
+    })()`,
+    }
+  }
+  if (q.interactive) {
+    return {
+      mode: 'interactive-targets',
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return []
+${FIND_INSPECTABLE_TARGETS}
+      const inspectable = await fromInspectable()
+      if (inspectable) {
+        return inspectable.filter(n => n.pressable && isVisibleTarget(n))
+      }
+      const all = await t.queryAll({ pruneHidden: true })
+      return all.filter(n => n.pressable && isVisibleTarget(n))
+    })()`,
+    }
+  }
+  if (q.visible) {
+    return {
+      mode: 'visible',
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return []
+      const all = await t.queryAll({ pruneHidden: true })
+      return all.filter(n => n.layout && n.layout.width > 0 && n.layout.height > 0)
+    })()`,
+    }
+  }
+  if (q.text) {
+    return {
+      mode: 'text',
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return null
+      return await t.findByText(${JSON.stringify(q.text)})
+    })()`,
+    }
+  }
+  return null
+}
+
+// `find` — locate nodes by text / testID / role / type / predicate. returns
+// the raw bridge result (a node, a node array, or null) plus the resolved
+// mode; null when the query was empty.
+export async function inspectFind(
+  bridge: InspectBridge,
+  q: FindQuery,
+): Promise<{ mode: FindMode; result: unknown } | null> {
+  const resolved = resolveFindMode(q)
+  if (!resolved) return null
+  const result = await bridge.send({ type: 'evaluate', code: resolved.code })
+  return { mode: resolved.mode, result }
+}
+
+export interface InteractiveNode {
+  type?: string
+  text?: string
+  testID?: string
+  pressable?: boolean
+  accessibilityRole?: string
+  accessibilityLabel?: string
+  absolutePosition?: { x: number; y: number }
+  layout?: { width: number; height: number }
+  [key: string]: unknown
+}
+
+// `find --interactive-targets` ranking. visible+pressable nodes scored by
+// identifying signal (testID > visible text > a11y label > role) and area,
+// with chrome / off-screen nodes de-prioritised. higher score = better
+// "next tap" candidate. shared so the CLI and the agent rank identically.
+export function rankInteractive<T extends InteractiveNode>(nodes: T[]): T[] {
+  return [...nodes].sort((a, b) => scoreInteractive(b) - scoreInteractive(a))
+}
+
+export function scoreInteractive(n: InteractiveNode): number {
+  let score = 0
+  if (n.testID) score += 100
+  if (typeof n.text === 'string' && n.text.trim().length > 0) score += 60
+  if (
+    typeof n.accessibilityLabel === 'string' &&
+    n.accessibilityLabel.trim().length > 0
+  ) {
+    score += 30
+  }
+  if (n.accessibilityRole) score += 15
+  const w = n.layout?.width ?? 0
+  const h = n.layout?.height ?? 0
+  const area = w * h
+  if (area >= 400 && area <= 60_000) score += 25
+  else if (area > 60_000) score -= 20
+  const y = n.absolutePosition?.y ?? 0
+  if (y < 0) score -= 30
+  return score
+}
+
+// the copy-paste `sootsim do` tap command for an interactive node.
+export function tapCommandForNode(n: InteractiveNode): string {
+  if (n.testID) return `rnxsim do tap-id ${shellEscape(n.testID)}`
+  const text = typeof n.text === 'string' ? n.text.trim() : ''
+  if (text.length > 0 && text.length <= 80)
+    return `rnxsim do tap-text ${shellEscape(text)}`
+  const x =
+    Math.round(((n.absolutePosition?.x ?? 0) + (n.layout?.width ?? 0) / 2) * 10) / 10
+  const y =
+    Math.round(((n.absolutePosition?.y ?? 0) + (n.layout?.height ?? 0) / 2) * 10) / 10
+  return `rnxsim do tap ${x} ${y}`
+}
+
+function shellEscape(value: string): string {
+  if (/^[A-Za-z0-9_./@:-]+$/.test(value)) return value
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+// ─── wait ───
+
+export interface ReadyProbe {
+  flag: unknown
+  at: number
+  nodes: number
+  targets: number
+  liveFrameActive: boolean
+  liveFrameChannels: number
+  liveFramePublishes: number
+  errors: number
+  loadingText: string
+  externalReady: boolean | null
+  externalStatus: string
+  externalError: string
+  // entry-require throw that bundle-loader suppressed-and-continued past.
+  // diagnostic only — never gates readiness.
+  suppressedEntryError: string
+}
+
+export const WAIT_READY_PROBE = `(async () => {
+    const t = window.__sootsimTest
+    let nodes = 0
+    try { nodes = (await t?.getNodeCount?.()) || 0 } catch {}
+    let targets = 0
+    let liveFrameActive = false
+    let liveFrameChannels = 0
+    let liveFramePublishes = 0
+    let loadingText = ''
+    const cleanText = (value) =>
+      typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''
+    const loadingSignal = (value) => {
+      const text = cleanText(value)
+      if (!text) return ''
+      return /^(opening app\\b|looking for your app\\b|building bundle\\b|preparing rnxsim runtime\\b|loading native bundle\\b|loading rnx stubs\\b|loading bundle loader\\b|loading native stubs\\b|loading compat bridge\\b|loading react-native shim\\b|loading react bridge\\b|loading reconciler\\b|loading replacement modules\\b|injecting rnx modules\\b|warming sqlite engine\\b|capturing root component\\b|reloading app\\b|loading(?:[.!…]*)?$|connecting(?:[.!…]*)?$)/i.test(text)
+        ? text
+        : ''
+    }
+    try {
+      const loading = window.__sootsimConnectRNLoading
+      if (loading && loading.active === true) {
+        loadingText = [loading.title, loading.detail].map(cleanText).filter(Boolean).join(' ')
+      }
+    } catch {}
+    try {
+      if (typeof t?.listInspectable === 'function') {
+        const list = await t.listInspectable({})
+        if (Array.isArray(list)) {
+          const screenW = window.innerWidth || 0
+          const screenH = window.innerHeight || 0
+          const isVisible = (n) => {
+            const layout = n?.layout
+            if (!layout || layout.width <= 0 || layout.height <= 0) return false
+            const abs = n?.absolutePosition || n?.absolute
+            if (!abs) return true
+            const device = n?.device || {}
+            const w = Number(device.width) || screenW
+            const h = Number(device.height) || screenH
+            return (
+              abs.x + layout.width > 0 &&
+              abs.y + layout.height > 0 &&
+              abs.x < w &&
+              abs.y < h
+            )
+          }
+          const hasContentSignal = (n) => {
+            const role = n?.accessibilityRole || n?.role
+            const label = cleanText(n?.accessibilityLabel || n?.label)
+            const handlers = Array.isArray(n?.handlers) ? n.handlers : []
+            const text = cleanText(n?.text)
+            const testID = cleanText(n?.testID || n?.testId)
+            const loading = loadingSignal(text) || loadingSignal(label) || loadingSignal(testID)
+            if (!loadingText && loading) {
+              loadingText = loading
+            }
+            if (handlers.length > 0) return true
+            if (role) return true
+            if (n?.isTextInput) return true
+            if (text) return true
+            if (label) return true
+            if (testID && !/^splash|loading/i.test(testID)) return true
+            return false
+          }
+          targets = list.filter(n => isVisible(n) && hasContentSignal(n)).length
+        }
+      }
+    } catch {}
+    try {
+      const stats = await t?.getImageLoaderStats?.()
+      const presentation = stats?.liveFramePresentation
+      liveFrameChannels = Number(presentation?.activeChannels) || 0
+      liveFramePublishes = Number(presentation?.publishes) || 0
+      const previous = window.__sootsimWaitReadyLiveFramePublishes
+      liveFrameActive =
+        liveFrameChannels > 0 &&
+        typeof previous === 'number' &&
+        liveFramePublishes > previous
+      window.__sootsimWaitReadyLiveFramePublishes = liveFramePublishes
+    } catch {}
+    let externalReady = null
+    let externalStatus = ''
+    let externalError = ''
+    let suppressedEntryError = ''
+    try {
+      const getExternalAppState = t?.getExternalAppState
+      const external = typeof getExternalAppState === 'function'
+        ? await Promise.race([
+            getExternalAppState(),
+            new Promise((resolve) => setTimeout(
+              () => resolve({
+                state: {
+                  ready: false,
+                  loading: true,
+                  status: 'waiting for tenant worker...',
+                },
+              }),
+              1000,
+            )),
+          ])
+        : null
+      const state = external?.state
+      if (state && typeof state === 'object') {
+        externalReady = state.ready === true
+        if (typeof state.status === 'string') externalStatus = state.status
+        if (typeof state.error === 'string') externalError = state.error
+      }
+      if (!externalError && Array.isArray(external?.entryErrors)) {
+        // suppressed-and-continued entry errors (bundle-loader's patched __r
+        // swallows entry throws and moves on) must NOT gate readiness — the
+        // app frequently runs fine after one (e.g. metro's "Unknown named
+        // module" probing noise). they surface separately as a diagnostic
+        // for the timeout path.
+        const isReal = (item) => item && typeof item.message === 'string' && item.message.trim()
+        const fatal = external.entryErrors.find((item) => isReal(item) && item.suppressed !== true)
+        if (fatal) externalError = fatal.message
+        const suppressed = external.entryErrors.find((item) => isReal(item) && item.suppressed === true)
+        if (suppressed) suppressedEntryError = suppressed.message
+      }
+      // once the app has errored its last status ("injecting sootsim
+      // modules...") is stale — reporting it makes a dead app read as one that
+      // is still booting.
+      if (externalError) loadingText = ''
+      else if (externalReady === false && externalStatus) loadingText = externalStatus
+    } catch {}
+    let errors = 0
+    try { errors = window.__sootsimConsole?.count?.()?.errors ?? 0 } catch {}
+    return {
+      flag: (window).__sootsimExternalAppReady,
+      at: (window).__sootsimExternalAppReadyAt || 0,
+      nodes,
+      targets,
+      liveFrameActive,
+      liveFrameChannels,
+      liveFramePublishes,
+      errors,
+      loadingText,
+      externalReady,
+      externalStatus,
+      externalError,
+      suppressedEntryError,
+    }
+  })()`
+
+export const READY_CONTENT_NODE_FLOOR = 100
+export const READY_NODE_STABLE_MS = 750
+export const WAIT_READY_PROGRESS_INTERVAL_MS = 2000
+// how often the readiness probe re-runs. shared so `sootsim wait ready` and the
+// flow runner's launchApp wait resolve a ready app with the same latency.
+export const READY_PROBE_POLL_MS = 150
+
+export function readyProbeHasContent(
+  probe: Pick<ReadyProbe, 'nodes' | 'targets'> &
+    Partial<Pick<ReadyProbe, 'liveFrameActive'>>,
+) {
+  return (
+    probe.liveFrameActive || probe.targets > 0 || probe.nodes >= READY_CONTENT_NODE_FLOOR
+  )
+}
+
+export function readyProbeHasTargetContent(
+  probe: Pick<ReadyProbe, 'targets'> & Partial<Pick<ReadyProbe, 'liveFrameActive'>>,
+) {
+  return probe.liveFrameActive || probe.targets > 0
+}
+
+export interface WaitReadyStatus {
+  ready: boolean
+  elapsedMs: number
+  nodes: number
+  targets: number
+  liveFrameActive: boolean
+  liveFrameChannels: number
+  liveFramePublishes: number
+  flag: unknown
+  loadingText: string
+  externalReady: boolean | null
+  externalStatus: string
+  externalError: string
+  suppressedEntryError: string
+  errors: number
+  // non-empty when the probe itself stopped reaching the sim (tab closed,
+  // sim never connected) — the wait failed on the bridge, not on the app.
+  bridgeError: string
+}
+
+export interface WaitReadyOptions {
+  progressIntervalMs?: number
+  onProgress?: (status: WaitReadyStatus) => void
+}
+
+export function waitReadyReason(
+  status: Pick<
+    WaitReadyStatus,
+    | 'externalError'
+    | 'loadingText'
+    | 'externalReady'
+    | 'flag'
+    | 'targets'
+    | 'suppressedEntryError'
+  > & { bridgeError?: string },
+): string {
+  if (status.bridgeError) {
+    return `sim unreachable: ${status.bridgeError} — the target tab is closed or no sim is connected (check \`rnxsim list\`, reopen with \`rnxsim open\`)`
+  }
+  const base = status.externalError
+    ? `guest app errored: ${status.externalError}`
+    : status.loadingText
+      ? `still showing "${status.loadingText}"`
+      : status.externalReady === false
+        ? 'guest app is still loading'
+        : status.flag !== true && status.targets > 0
+          ? 'native content is rendered but the ready signal has not settled'
+          : status.flag !== true
+            ? 'guest app has not emitted sootsim:externalAppReady'
+            : status.targets <= 0
+              ? 'ready flag emitted but no visible app content is inspectable yet'
+              : 'node tree is still changing'
+  // suppressed entry errors never gate readiness, but on a stall they are
+  // often the actual diagnosis — surface them as a hint.
+  return !status.externalError && status.suppressedEntryError
+    ? `${base} (suppressed entry error: ${status.suppressedEntryError})`
+    : base
+}
+
+// `wait ready` — block until the guest app bundle has mounted and painted.
+// the persistent `__sootsimExternalAppReady` flag is necessary but not enough:
+// under the shell renderer the flag can fire before the shell has materialized
+// the tenant tree, and the node count can then jump through placeholder
+// counts before the app has finished publishing its first real surface. require
+// visible inspectable content (or a larger non-placeholder tree) and a brief
+// stable count. polling is caller-side so the timeout is decoupled from the
+// bridge's per-command timeout (cold guest bundles routinely need 20-30s).
+export async function inspectWaitReady(
+  bridge: InspectBridge,
+  timeoutMs = 20_000,
+  options: WaitReadyOptions = {},
+): Promise<WaitReadyStatus> {
+  const start = Date.now()
+  const deadline = start + timeoutMs
+  const progressIntervalMs = options.progressIntervalMs ?? WAIT_READY_PROGRESS_INTERVAL_MS
+  let nextProgressAt = start + progressIntervalMs
+  let lastNodes = -1
+  let nodeStableSince = start
+  // the wait keeps polling through bridge errors — the target sim may still
+  // be launching (`sootsim open` running concurrently) — but the latest error
+  // is surfaced in progress lines and the timeout reason so a dead sim reads
+  // as "sim unreachable", not as misleading zero-node app state.
+  let bridgeError = ''
+  let last: ReadyProbe = {
+    flag: undefined,
+    at: 0,
+    nodes: 0,
+    targets: 0,
+    liveFrameActive: false,
+    liveFrameChannels: 0,
+    liveFramePublishes: 0,
+    errors: 0,
+    loadingText: '',
+    externalReady: null,
+    externalStatus: '',
+    externalError: '',
+    suppressedEntryError: '',
+  }
+  while (Date.now() < deadline) {
+    try {
+      last = (await bridge.send({ type: 'evaluate', code: WAIT_READY_PROBE })) ?? last
+      bridgeError = ''
+    } catch (error) {
+      bridgeError = error instanceof Error ? error.message : String(error)
+      // launching can make an unreachable sim transient, but target
+      // ambiguity cannot resolve until the caller chooses a sim.
+      if (
+        bridgeError.startsWith('multiple sims are connected:') ||
+        bridgeError.startsWith('saved sim ')
+      ) {
+        throw error
+      }
+    }
+    const now = Date.now()
+    const status: WaitReadyStatus = {
+      ready: false,
+      elapsedMs: now - start,
+      nodes: last.nodes,
+      targets: last.targets,
+      liveFrameActive: last.liveFrameActive,
+      liveFrameChannels: last.liveFrameChannels,
+      liveFramePublishes: last.liveFramePublishes,
+      flag: last.flag,
+      loadingText: last.loadingText,
+      externalReady: last.externalReady,
+      externalStatus: last.externalStatus,
+      externalError: last.externalError,
+      suppressedEntryError: last.suppressedEntryError,
+      errors: last.errors,
+      bridgeError,
+    }
+    if (last.nodes !== lastNodes) {
+      lastNodes = last.nodes
+      nodeStableSince = now
+    }
+    const hasReadySignal = last.flag === true && readyProbeHasContent(last)
+    const hasRenderedContentWithoutReadySignal =
+      last.flag !== true && readyProbeHasTargetContent(last)
+    if (
+      (hasReadySignal || hasRenderedContentWithoutReadySignal) &&
+      last.externalReady !== false &&
+      !last.externalError &&
+      !last.loadingText
+    ) {
+      if (now - nodeStableSince >= READY_NODE_STABLE_MS) {
+        return {
+          ...status,
+          ready: true,
+        }
+      }
+    }
+    // a guest app that reported a load error is DONE — it paints a red box and
+    // stays there until something reloads it (the reload path clears `error`
+    // atomically). polling out the rest of the budget only delays the same
+    // answer, and it is why a boot failure used to cost 90s before the caller
+    // was told anything.
+    if (last.externalError) return status
+    if (options.onProgress && progressIntervalMs > 0 && now >= nextProgressAt) {
+      options.onProgress(status)
+      do {
+        nextProgressAt += progressIntervalMs
+      } while (now >= nextProgressAt)
+    }
+    await new Promise((r) => setTimeout(r, READY_PROBE_POLL_MS))
+  }
+  const status: WaitReadyStatus = {
+    ready: false,
+    elapsedMs: Date.now() - start,
+    nodes: last.nodes,
+    targets: last.targets,
+    liveFrameActive: last.liveFrameActive,
+    liveFrameChannels: last.liveFrameChannels,
+    liveFramePublishes: last.liveFramePublishes,
+    flag: last.flag,
+    loadingText: last.loadingText,
+    externalReady: last.externalReady,
+    externalStatus: last.externalStatus,
+    externalError: last.externalError,
+    suppressedEntryError: last.suppressedEntryError,
+    errors: last.errors,
+    bridgeError,
+  }
+  if (options.onProgress && progressIntervalMs > 0 && Date.now() >= nextProgressAt) {
+    options.onProgress(status)
+  }
+  return status
+}
+
+// `wait selector` — block until a node with the given testID is present and
+// laid out. the polling loop runs inside the evaluated code (one round-trip).
+export async function inspectWaitSelector(
+  bridge: InspectBridge,
+  testId: string,
+  timeoutMs = 5000,
+  opts: { gone?: boolean } = {},
+): Promise<{ found: boolean; node?: any; elapsed: number }> {
+  // gone-mode inverts the predicate: resolve (found:true) when the node is
+  // confirmed absent from the active visible inspect tree. this is the
+  // positive "the gate/screen left" signal — e.g. waiting for an access-gate
+  // button to disappear after a successful sign-in instead of re-tapping it.
+  // an indeterminate bridge (test hooks not ready yet) never counts as gone,
+  // and visible absence is debounced across two polls so a transient tree swap
+  // doesn't resolve early. `gone` only steers the predicate; the return shape
+  // is the same as presence-mode (callers/the handler don't need a gone flag).
+  const gone = opts.gone === true
+  const result = await bridge.send(
+    {
+      type: 'evaluate',
+      code: `(async () => {
+      const start = Date.now()
+      const deadline = start + ${timeoutMs}
+      const gone = ${gone}
+      const ID = ${JSON.stringify(testId)}
+      const present = (node) => !!(node && node.layout && node.layout.width > 0 && node.layout.height > 0)
+      const find = async () => {
+        const t = window.__sootsimTest
+        if (!t) return undefined // bridge not ready — indeterminate, not "gone"
+        try {
+          // gone-mode confirms a gate/screen LEFT — it only needs structural
+          // existence + layout, NOT the full-tree occlusion pass (pruneHidden).
+          // that pass (computeOccludedInspectNodeIds) walks the whole tree and
+          // does O(n²)-ish rect-occlusion testing EVERY poll; on a large
+          // post-login app tree it costs seconds per poll, so --gone can never
+          // get two clean "absent" polls inside budget and falsely reports the
+          // gate as still blocked — the root cause of the 3pc PR-preview outage.
+          // presence-mode keeps pruneHidden so "appeared" still means
+          // visibly-reachable. a departed gate is unmounted or zero-sized, so the
+          // cheap structural+layout check is correct here and ~O(n) cheap.
+          const matches = await t.queryAll?.(gone ? { hasId: ID } : { hasId: ID, pruneHidden: true })
+          if (!Array.isArray(matches)) return undefined
+          return matches.find(present) || null
+        } catch {
+          return undefined
+        }
+      }
+      let goneStreak = 0
+      while (Date.now() < deadline) {
+        const node = await find()
+        if (gone) {
+          if (node === null) {
+            goneStreak += 1
+            if (goneStreak >= 2) return { found: true, elapsed: Date.now() - start }
+          } else {
+            goneStreak = 0
+          }
+        } else if (present(node)) {
+          return { found: true, node, elapsed: Date.now() - start }
+        }
+        await new Promise((r) => setTimeout(r, 80))
+      }
+      return { found: false, elapsed: Date.now() - start }
+    })()`,
+    },
+    {
+      timeoutMs: timeoutMs + 1_000,
+    },
+  )
+  return (result ?? { found: false, elapsed: timeoutMs }) as {
+    found: boolean
+    node?: any
+    elapsed: number
+  }
+}
+
+// ─── console errors / warnings ───
+
+// a captured console entry. `__sootsimConsole` records each console.error /
+// console.warn with its args and (for errors) a stack. `source` is set when
+// the entry came from the engine observability store (e.g. 'render-worker')
+// so the reader can tell page-realm errors from forwarded tenant-worker ones.
+export interface ConsoleEntry {
+  timestamp: number
+  args: unknown[]
+  stack?: string
+  source?: string
+  [key: string]: unknown
+}
+
+// in-page merge of the two error/warning sources, evaluated in the preview
+// realm. `level` is 'error' | 'warn'.
+//
+// why two sources: `__sootsimConsole` (the ws-bridge ring buffer) only sees a
+// tenant render-worker error if the worker→host `{type:'log'}` re-emit makes it
+// through the host realm's monkey-patched `console.error` — and only when
+// ws-bridge's `setupConsoleCapture()` ran (gated on localhost/electron). The
+// engine observability store (`__sootsimObservability.logs`) captures the SAME
+// worker errors via two unconditional paths — the worker's own BroadcastChannel
+// capture and the host's `recordForwardedWorkerLog('render-worker', …)` — and
+// carries an explicit `source`/`level`. Reading only `__sootsimConsole` is how
+// a native render-worker crash (e.g. a tamagui "Missing theme" thrown by the
+// One root error boundary in the tenant worker) can be live and screaming in
+// the driver's console while the agent's `sootsim_errors` reports nothing.
+// Merge both, dedup, so worker + root-error-boundary failures always surface.
+function consoleEntriesEval(level: 'error' | 'warn', limit: number): string {
+  const getter = level === 'error' ? 'getErrors' : 'getWarnings'
+  return `(() => {
+    const out = []
+    const seen = new Set()
+    const norm = (s) => (typeof s === 'string' ? s : (() => { try { return JSON.stringify(s) } catch { return String(s) } })())
+    const key = (ts, args) => Math.round((ts || 0) / 250) + '|' + (Array.isArray(args) ? args.map(norm).join(' ') : norm(args))
+    const push = (e) => {
+      if (!e) return
+      const ts = typeof e.timestamp === 'number' ? e.timestamp : (typeof e.ts === 'number' ? e.ts : 0)
+      const k = key(ts, e.args)
+      if (seen.has(k)) return
+      seen.add(k)
+      out.push({ timestamp: ts, args: Array.isArray(e.args) ? e.args : [e.args], stack: e.stack || undefined, source: e.source || undefined })
+    }
+    // page-realm ws-bridge buffer first (richest stacks for page-origin errors)
+    try { for (const e of (window.__sootsimConsole?.${getter}(${limit}) || [])) push(e) } catch {}
+    // engine observability store — the always-on render-worker / forwarded path
+    try {
+      const obs = window.__sootsimObservability
+      const snap = obs && obs.logs && typeof obs.logs.getSnapshot === 'function' ? obs.logs.getSnapshot() : []
+      for (const e of snap) if (e && e.level === ${JSON.stringify(level)}) push(e)
+    } catch {}
+    return out.sort((a, b) => (a.timestamp || 0) - (b.timestamp || 0)).slice(-${limit})
+  })()`
+}
+
+// `get errors` — the most recent captured `console.error` entries, merged from
+// the ws-bridge buffer and the engine observability store so forwarded
+// tenant-worker errors (render-worker / root-error-boundary) are never missed.
+export async function inspectErrors(
+  bridge: InspectBridge,
+  limit = 20,
+): Promise<ConsoleEntry[]> {
+  const result = await bridge.send({
+    type: 'evaluate',
+    code: consoleEntriesEval('error', limit),
+  })
+  return Array.isArray(result) ? (result as ConsoleEntry[]) : []
+}
+
+// `get warnings` — the most recent captured `console.warn` entries, merged from
+// both capture sources (see inspectErrors).
+export async function inspectWarnings(
+  bridge: InspectBridge,
+  limit = 20,
+): Promise<ConsoleEntry[]> {
+  const result = await bridge.send({
+    type: 'evaluate',
+    code: consoleEntriesEval('warn', limit),
+  })
+  return Array.isArray(result) ? (result as ConsoleEntry[]) : []
+}
+
+// merged error/warning COUNT across both capture sources, evaluated in the
+// preview realm. used by the CLI's proactive "console: N errors" notice and
+// the `get state` diagnostics so the count agrees with what inspectErrors /
+// inspectWarnings actually return — otherwise a render-worker-only error would
+// read as `0 errors` and the agent would never be nudged to inspect it.
+export const MERGED_CONSOLE_COUNT_EVAL = `(() => {
+    const norm = (s) => (typeof s === 'string' ? s : (() => { try { return JSON.stringify(s) } catch { return String(s) } })())
+    const key = (lvl, ts, args) => lvl + '|' + Math.round((ts || 0) / 250) + '|' + (Array.isArray(args) ? args.map(norm).join(' ') : norm(args))
+    const seen = new Set()
+    let errors = 0
+    let warnings = 0
+    const add = (lvl, ts, args) => {
+      if (lvl !== 'error' && lvl !== 'warn') return
+      const k = key(lvl, ts, args)
+      if (seen.has(k)) return
+      seen.add(k)
+      if (lvl === 'error') errors++
+      else warnings++
+    }
+    try {
+      const c = window.__sootsimConsole
+      for (const e of (c?.getErrors?.(200) || [])) add('error', e?.timestamp ?? e?.ts, e?.args)
+      for (const e of (c?.getWarnings?.(200) || [])) add('warn', e?.timestamp ?? e?.ts, e?.args)
+    } catch {}
+    try {
+      const obs = window.__sootsimObservability
+      const snap = obs && obs.logs && typeof obs.logs.getSnapshot === 'function' ? obs.logs.getSnapshot() : []
+      for (const e of snap) if (e) add(e.level, e.ts, e.args)
+    } catch {}
+    return { errors, warnings, total: errors + warnings }
+  })()`
+
+// `get errors clear` — drop BOTH captured buffers so a follow-up read starts
+// clean (the ws-bridge ring buffer and the engine observability log store).
+export async function clearConsole(bridge: InspectBridge): Promise<void> {
+  await bridge.send({
+    type: 'evaluate',
+    code: 'window.__sootsimConsole?.clear(); window.__sootsimObservability?.logs?.clear?.(); "cleared"',
+  })
+}
+
+// ─── network requests ───
+
+// `get requests` — the captured fetch / XHR entries. `failed` restricts to
+// unsuccessful / errored requests (the CLI's default); pass `failed: false` for
+// every request. backed by the test bridge's request observability store.
+export async function inspectRequests(
+  bridge: InspectBridge,
+  opts: { failed?: boolean; limit?: number } = {},
+): Promise<SootSimRequestEntry[]> {
+  const limit = opts.limit ?? 20
+  const method = opts.failed === false ? 'getRequests' : 'getFailedRequests'
+  const result = await bridge.send({
+    type: 'call',
+    path: `__sootsimTest.${method}`,
+    args: [limit],
+  })
+  return Array.isArray(result) ? (result as SootSimRequestEntry[]) : []
+}
+
+// `get requests clear` — drop the captured request buffer.
+export async function clearRequests(bridge: InspectBridge): Promise<void> {
+  await bridge.send({ type: 'call', path: '__sootsimTest.clearRequests', args: [] })
+}
+
+// ─── scroll state ───
+
+export interface ScrollState {
+  scrollOffsetX?: number
+  scrollOffsetY?: number
+  offsetX?: number
+  offsetY?: number
+  [k: string]: unknown
+}
+
+// the scroll state of whichever scrollable sits under a screen coordinate.
+// used to verify a swipe / scroll actually moved content — read it before
+// and after the gesture and compare the offsets.
+export async function inspectScrollStateAt(
+  bridge: InspectBridge,
+  x: number,
+  y: number,
+): Promise<ScrollState | null> {
+  const result = await bridge.send({
+    type: 'call',
+    path: '__sootsimTest.getScrollStateAt',
+    args: [x, y],
+  })
+  if (!result || typeof result !== 'object') return null
+  const state = result as ScrollState
+  return {
+    ...state,
+    scrollOffsetX:
+      typeof state.scrollOffsetX === 'number' ? state.scrollOffsetX : state.offsetX,
+    scrollOffsetY:
+      typeof state.scrollOffsetY === 'number' ? state.scrollOffsetY : state.offsetY,
+  }
+}
+
+// ─── console logs ───
+
+export type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug'
+
+export interface LogEntry {
+  id: string
+  source: string
+  level: LogLevel
+  ts: number
+  args: string[]
+  stack: string | null
+}
+
+export interface LogFilterOptions {
+  level?: ReadonlySet<LogLevel> | null
+  filter?: string | null
+  // engine-internal `[sootsim]` bootstrap logs are hidden unless this is set.
+  showInternal?: boolean
+}
+
+// `logs` — the full captured console snapshot (log / info / warn / error /
+// debug) from the engine observability store. when the observability bridge has
+// not installed yet, return an empty snapshot so validation tools don't turn a
+// missing diagnostics buffer into the app failure being diagnosed.
+export async function inspectLogs(bridge: InspectBridge): Promise<LogEntry[]> {
+  const res = (await bridge.send({
+    type: 'evaluate',
+    code: `(() => {
+      const obs = window.__sootsimObservability;
+      if (!obs) return { ok: false };
+      return { ok: true, entries: obs.logs.getSnapshot() };
+    })()`,
+  })) as { ok: boolean; entries?: LogEntry[] } | null
+  if (!res || !res.ok) return []
+  return res.entries ?? []
+}
+
+// `logs clear` — drop the engine's captured log buffer.
+export async function clearLogs(bridge: InspectBridge): Promise<void> {
+  await bridge.send({
+    type: 'evaluate',
+    code: 'window.__sootsimObservability?.logs.clear(); "cleared"',
+  })
+}
+
+function isForwardedWorkerLogTwin(a: LogEntry, b: LogEntry): boolean {
+  if (a.source === b.source) return false
+  if (a.level !== b.level) return false
+  if (Math.abs(a.ts - b.ts) > 1000) return false
+  if (a.args.length !== b.args.length) return false
+  const sources = new Set([a.source, b.source])
+  if (!sources.has('sootsim-worker')) return false
+  if (!sources.has('render-worker') && !sources.has('forwarded-render-worker')) {
+    return false
+  }
+  return a.args.every((arg, index) => arg === b.args[index])
+}
+
+// shared log filtering — engine-internal `[sootsim]` noise hidden by default,
+// optional level set + message substring. used by the CLI `logs` verb and the
+// agent so both see the same filtered view.
+export function filterLogEntries(
+  entries: LogEntry[],
+  opts: LogFilterOptions = {},
+): LogEntry[] {
+  let out: LogEntry[] = []
+  for (const entry of entries) {
+    if (out.some((candidate) => isForwardedWorkerLogTwin(candidate, entry))) {
+      continue
+    }
+    out.push(entry)
+  }
+  if (!opts.showInternal) {
+    out = out.filter((e) => {
+      const first = e.args[0]
+      return !(typeof first === 'string' && first.startsWith('[rnx]'))
+    })
+  }
+  if (opts.level) out = out.filter((e) => opts.level!.has(e.level))
+  if (opts.filter) {
+    const lf = opts.filter.toLowerCase()
+    out = out.filter((e) => e.args.join(' ').toLowerCase().includes(lf))
+  }
+  return out
+}
+
+// ─── timeline / what-happened ───
+
+// `what-happened --summary` — counts by kind since the query window.
+export async function inspectTimelineSummary(
+  bridge: InspectBridge,
+  query: SootSimTimelineQuery,
+): Promise<SootSimTimelineSummary> {
+  return (await bridge.send({
+    type: 'call',
+    path: 'SootSim.bridges.timeline.summary',
+    args: [query],
+  })) as SootSimTimelineSummary
+}
+
+// `what-happened` — the recent timeline events for the query window.
+export async function inspectTimelineRecent(
+  bridge: InspectBridge,
+  query: SootSimTimelineQuery,
+): Promise<SootSimTimelineQueryResult> {
+  return (await bridge.send({
+    type: 'call',
+    path: 'SootSim.bridges.timeline.recent',
+    args: [query],
+  })) as SootSimTimelineQueryResult
+}
+
+// a blocking native-UI surface (iOS Alert / ActionSheet) currently presented
+// by the shell worker. `label` is the human word for the CLI note; `title` is
+// the surface's title text when it has one.
+export interface OpenNativeUISurface {
+  label: string
+  title: string | null
+}
+
+// detect blocking native-UI surfaces that are currently open, computed from the
+// timeline. the shell native-UI provider records a `show` then a `resolve`
+// event per surface (both DEFAULT_ON kinds, so no `timeline start` is needed),
+// so the latest event of each kind tells whether it's still up. the CLI surfaces
+// this because these surfaces live in the shell worker — invisible to `describe`
+// (which reads the tenant tree) — yet an open modal silently swallows every
+// tap/drag/type meant for the app underneath, which reads as "the action did
+// nothing." returns [] on any read error; this is an advisory note, never fatal.
+export async function detectOpenNativeUI(
+  bridge: InspectBridge,
+): Promise<OpenNativeUISurface[]> {
+  let events: SootSimTimelineEvent[]
+  try {
+    const res = await inspectTimelineRecent(bridge, {
+      kinds: ['alert', 'actionsheet'],
+      limit: 80,
+    })
+    events = res.events
+  } catch {
+    return []
+  }
+  // events arrive time-ordered; keep the latest event per kind.
+  const latest = new Map<string, SootSimTimelineEvent>()
+  for (const ev of events) latest.set(ev.kind, ev)
+  const out: OpenNativeUISurface[] = []
+  const check = (kind: string, label: string) => {
+    const ev = latest.get(kind)
+    if (!ev || !ev.data || typeof ev.data !== 'object') return
+    // timeline payloads are plain JSON records (see formatTimelinePayload)
+    const d = ev.data as Record<string, unknown>
+    if (d.phase !== 'show') return
+    out.push({ label, title: typeof d.title === 'string' ? d.title : null })
+  }
+  check('alert', 'Alert')
+  check('actionsheet', 'ActionSheet')
+  return out
+}
+
+// advance a caller's cursor past the events it has consumed, so the next
+// `what-happened` for the same cursor key shows only newer events.
+export async function inspectTimelineAdvanceCursor(
+  bridge: InspectBridge,
+  cursorKey: string,
+  watermark: number,
+): Promise<void> {
+  await bridge.send({
+    type: 'call',
+    path: 'SootSim.bridges.timeline.cursorAdvance',
+    args: [cursorKey, watermark],
+  })
+}
+
+// ─── keyboard ───
+
+export interface KeyboardState {
+  visible: boolean
+  spec: {
+    keyboardType: string
+    returnKeyType: string
+    secureTextEntry: boolean
+    enablesReturnKeyAutomatically: boolean
+    autoCapitalize: string
+    autoCorrect: boolean
+    keyboardAppearance: string
+    accessoryBarId: string | null
+    currentTextIsEmpty: boolean
+  } | null
+  mode: string
+  shifted: boolean
+  capsLock: boolean
+  accessoryBarId: string | null
+}
+
+// `get keyboard` — the live iOS keyboard state from `__sootsimKeyboard`,
+// populated by shell-worker `keyboard.layout` broadcasts. returns the raw
+// payload or `{ error }` when the keyboard bridge has not installed yet.
+export async function inspectKeyboard(
+  bridge: InspectBridge,
+): Promise<KeyboardState | { error: string }> {
+  const result = (await bridge.send({
+    type: 'evaluate',
+    code: `(() => {
+      const kb = window.__sootsimKeyboard
+      if (!kb || typeof kb.getLayout !== 'function') {
+        return { error: 'keyboard bridge getLayout() not available' }
+      }
+      return kb.getLayout()
+    })()`,
+  })) as KeyboardState | { error: string }
+  return result ?? { error: 'keyboard bridge returned no result' }
+}
+
+// ─── shell state ───
+
+// true when a `SootSim.bridges.mainShell.*` call failed because the shell
+// bridge has not installed yet (boot race) — distinct from a real error.
+export function isShellCommandUnavailable(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  return (
+    message.includes('call target not found: SootSim.bridges.mainShell') ||
+    message.includes('test bridge unavailable before app-in-worker boot')
+  )
+}
+
+// read `mainShell.getState()`, retrying past the boot race for up to
+// `readyTimeoutMs`. shared by the CLI's inspect verbs and the agent.
+export async function getShellState(
+  bridge: InspectBridge,
+  readyTimeoutMs = 0,
+): Promise<Record<string, any> | null> {
+  const deadline = Date.now() + Math.max(0, readyTimeoutMs)
+  while (true) {
+    try {
+      return (await bridge.send({
+        type: 'call',
+        path: 'SootSim.bridges.mainShell.getState',
+        args: [],
+      })) as Record<string, any> | null
+    } catch (error) {
+      if (!isShellCommandUnavailable(error) || Date.now() >= deadline) throw error
+      await new Promise((r) => setTimeout(r, 50))
+    }
+  }
+}
+
+// ─── screens ───
+
+export interface ScreenEntry {
+  id: string
+  routeName?: string
+  isActive: boolean
+  headerHeight: number
+  largeTitleState?: string
+}
+
+export interface NavSnapshot {
+  screens: ScreenEntry[]
+  activeScreenId: string | null
+  transitionPhase: string
+  activeTransitionCount: number
+  activeHeaderHeight: number
+  activeLargeTitleState?: string
+}
+
+export interface ScreensReport {
+  shell: Record<string, any> | null
+  nav: NavSnapshot | null
+  route: SootSimRouteInfo | null
+  keyboard: {
+    visible: boolean
+    mode?: string
+    spec?: { keyboardType?: string; returnKeyType?: string } | null
+  } | null
+}
+
+// `get screens` — the navigation stack + shell state + keyboard, a "what
+// screen am I on?" dashboard. nav + keyboard are read in one evaluate so the
+// snapshot is consistent; shell state is a best-effort separate call.
+export async function inspectScreens(bridge: InspectBridge): Promise<ScreensReport> {
+  const payload = (await bridge.send({
+    type: 'evaluate',
+    code: `(async () => {
+      const test = window.__sootsimTest
+      const kb = window.__sootsimKeyboard
+      const navSnap =
+        test && typeof test.getNavigationSnapshot === 'function'
+          ? await test.getNavigationSnapshot()
+          : null
+      const route =
+        test && typeof test.getRouteInfo === 'function'
+          ? await test.getRouteInfo()
+          : null
+      const keyboard =
+        kb && typeof kb.getLayout === 'function'
+          ? (() => {
+              const layout = kb.getLayout()
+              return layout ? {
+                visible: layout.visible,
+                mode: layout.mode,
+                spec: layout.spec
+                  ? {
+                      keyboardType: layout.spec.keyboardType,
+                      returnKeyType: layout.spec.returnKeyType,
+                    }
+                  : null,
+              } : null
+            })()
+          : null
+      return { nav: navSnap, route, keyboard }
+    })()`,
+  })) as {
+    nav: NavSnapshot | null
+    route: SootSimRouteInfo | null
+    keyboard: ScreensReport['keyboard']
+  } | null
+  const shell = await getShellState(bridge, 500).catch(() => null)
+  return {
+    shell,
+    nav: payload?.nav ?? null,
+    route: payload?.route ?? null,
+    keyboard: payload?.keyboard ?? null,
+  }
+}
+
+// ─── debug channels ───
+
+// the `window.__sootsimDebug` channels the engine instruments. `all` is a
+// meta-target accepted by enable/disable.
+export const DEBUG_CHANNELS = [
+  'portals',
+  'sheets',
+  'layout',
+  'onlayout',
+  'animated',
+  'render',
+  'touch',
+  'yoga',
+] as const
+
+export type DebugChannel = (typeof DEBUG_CHANNELS)[number]
+
+// `debug status` — which debug channels are currently enabled + their counts.
+export async function inspectDebugStatus(bridge: InspectBridge): Promise<unknown> {
+  return bridge.send({ type: 'evaluate', code: 'window.__sootsimDebug.status()' })
+}
+
+// `debug flags` — the engine's debug feature flags.
+export async function inspectDebugFlags(bridge: InspectBridge): Promise<unknown> {
+  return bridge.send({ type: 'evaluate', code: 'window.__sootsimDebug.flags()' })
+}
+
+// `debug find sheets|portals` — locate all live sheet / portal nodes.
+// routed through the test bridge (not the page __sootsimDebug global) so the
+// walk runs against the worker's live tree — the page-local tree is empty
+// under the worker renderer.
+export async function inspectDebugFind(
+  bridge: InspectBridge,
+  target: 'sheets' | 'portals' | 'boundaries',
+): Promise<unknown> {
+  return bridge.send({
+    type: 'evaluate',
+    code: `window.__sootsimTest.debugFind(${JSON.stringify(target)})`,
+  })
+}
+
+// `debug recent` — recent debug events, optionally filtered to one channel.
+// only channels enabled via `setDebugChannels` record events.
+export async function inspectDebugRecent(
+  bridge: InspectBridge,
+  channel?: string,
+  limit = 50,
+): Promise<unknown> {
+  const code =
+    channel && channel !== 'all'
+      ? `window.__sootsimDebug.recent(${JSON.stringify(channel)}, ${limit})`
+      : `window.__sootsimDebug.recent(undefined, ${limit})`
+  return bridge.send({ type: 'evaluate', code })
+}
+
+// `debug enable|disable <channels>` — turn debug channels on or off. returns
+// the resulting active-channel set. an empty list with `disable` clears all.
+export async function setDebugChannels(
+  bridge: InspectBridge,
+  action: 'enable' | 'disable',
+  channels: string[],
+): Promise<unknown> {
+  const args =
+    channels.length > 0
+      ? channels.map((c) => JSON.stringify(c)).join(', ')
+      : action === 'disable'
+        ? "'all'"
+        : ''
+  return bridge.send({
+    type: 'evaluate',
+    code: `window.__sootsimDebug.${action}(${args})`,
+  })
+}
+
+// ─── memory ───
+
+export interface ImageLoaderStats {
+  cacheEntries: number
+  cachePixelBytes: number
+  cachePixelBudget: number
+  cacheMaxEntries: number
+  pendingFetches: number
+  pendingBytes: number
+  failedUris: number
+  snapshots: number
+  liveFrames: number
+}
+
+export interface WorkerHeapStats {
+  usedJSHeapSize: number
+  totalJSHeapSize: number
+  jsHeapSizeLimit: number
+}
+
+export interface EngineObjectCounts {
+  pictures: number
+  rasterImages: number
+  paragraphs: number
+  yogaNodes: number
+}
+
+export interface WorkerMemorySample {
+  // total nodes ever registered in the worker's handleToNode map — a
+  // monotonically climbing value while the on-screen tree is stable means
+  // discarded subtrees are being retained.
+  nodesRegistered: number | null
+  // registered nodes not reachable from a root container, by count and type
+  nodesDetached: number | null
+  detachedTypes: Record<string, number> | null
+  objects: EngineObjectCounts | null
+  activeNativeAnimations: number | null
+  imageLoader: ImageLoaderStats | null
+  workerHeap: WorkerHeapStats | null
+  // canvaskit's wasm linear memory in this worker. every worker that loads
+  // canvaskit allocates its own, no js-heap counter includes it, and on webkit
+  // (where performance.memory does not exist) it is the only number available.
+  wasmHeapBytes: number | null
+}
+
+export interface MemoryReport {
+  tenant: WorkerMemorySample | null
+  shell: WorkerMemorySample | null
+  compositor: WorkerMemorySample | null
+  hostHeap: WorkerHeapStats | null
+}
+
+// `get memory` / `debug memory` — per-worker object counts + image-loader
+// cache + JS heaps. tenant numbers ride the queryStats memory block; the
+// shell worker answers via __sootsimShellMemory, and the compositor — which
+// paints home + app:one + app:two, and therefore holds every app-surface
+// picture and raster image — answers through its stats channel.
+// performance.memory is chrome-only, null on webkit.
+export async function inspectMemory(bridge: InspectBridge): Promise<MemoryReport> {
+  const result = (await bridge.send({
+    type: 'evaluate',
+    code: `(async () => {
+      const host = window.__sootsimRenderHost
+      const stats = host?.queryStats ? await host.queryStats() : null
+      const shellRaw = window.__sootsimShellMemory
+        ? await window.__sootsimShellMemory()
+        : null
+      const shell = shellRaw && !shellRaw.error ? shellRaw : null
+      // the compositor paints home + app:one + app:two, so every app-surface
+      // picture and raster image is counted here and nowhere else.
+      let compositor = null
+      try {
+        const cs = await window.__sootsimCompositor?.getStats?.(false, true)
+        compositor = cs?.memory ?? null
+      } catch {}
+      const normalize = (m) =>
+        m
+          ? {
+              nodesRegistered: m.nodesRegistered ?? null,
+              nodesDetached: m.nodesDetached ?? null,
+              detachedTypes: m.detachedTypes ?? null,
+              objects: m.objects ?? null,
+              activeNativeAnimations: m.activeNativeAnimations ?? null,
+              imageLoader: m.imageLoader ?? null,
+              workerHeap: m.workerHeap ?? null,
+              wasmHeapBytes: m.wasmHeapBytes ?? null,
+            }
+          : null
+      const hostMem = performance.memory
+        ? {
+            usedJSHeapSize: performance.memory.usedJSHeapSize,
+            totalJSHeapSize: performance.memory.totalJSHeapSize,
+            jsHeapSizeLimit: performance.memory.jsHeapSizeLimit,
+          }
+        : null
+      return {
+        tenant: normalize(stats?.memory),
+        shell: normalize(shell),
+        compositor: normalize(compositor),
+        hostHeap: hostMem,
+      }
+    })()`,
+  })) as MemoryReport | null
+  return result ?? { tenant: null, shell: null, compositor: null, hostHeap: null }
+}
+
+// one-line counts, ordered by descriptive priority. shared by the CLI's
+// `what-happened --summary` and the agent's sootsim_what_happened.
+export function formatTimelineSummary(summary: SootSimTimelineSummary): string {
+  if (summary.total === 0) return 'nothing recorded'
+  const parts: string[] = []
+  const ORDER = [
+    'error',
+    'warning',
+    'console',
+    'fetch',
+    'toast',
+    'alert',
+    'actionsheet',
+    'picker',
+    'notification',
+    'screen',
+    'route',
+    'keyboard',
+    'app-launch',
+    'shell',
+    'scroll',
+    'gesture',
+    'text-input',
+    'react-commit',
+    'animation',
+    'reanimated',
+  ]
+  const seen = new Set<string>()
+  for (const k of ORDER) {
+    const n = summary.byKind[k]
+    if (n) {
+      parts.push(`${n} ${k}${n === 1 ? '' : 's'}`)
+      seen.add(k)
+    }
+  }
+  for (const [k, n] of Object.entries(summary.byKind)) {
+    if (!seen.has(k) && n) parts.push(`${n} ${k}${n === 1 ? '' : 's'}`)
+  }
+  return parts.join(' · ')
+}
+
+// high-frequency render/layout/scroll kinds that drown the meaningful
+// events. both the `what-happened` CLI and the sootsim_what_happened agent
+// tool hide these by default so a single tap doesn't get buried under 1000+
+// react-commit rows. callers opt back in explicitly.
+export const NOISY_TIMELINE_KINDS: ReadonlySet<string> = new Set([
+  'react-commit',
+  'layout',
+  'scroll',
+])
+
+function formatTimelineRelativeTime(t: number, anchor: number | null): string {
+  if (anchor === null) return new Date(t).toLocaleTimeString()
+  const dt = (t - anchor) / 1000
+  const sign = dt >= 0 ? '+' : ''
+  return `${sign}${dt.toFixed(2)}s`
+}
+
+// payload rendering per timeline-event kind. one exhaustive switch over
+// SootSimTimelineKind so adding a kind forces a formatter decision rather
+// than silently leaving it JSON-dumped. shared by the `what-happened` CLI and
+// the sootsim_what_happened agent tool — one renderer, two transports.
+export function formatTimelinePayload(
+  kind: SootSimTimelineKind,
+  d: Record<string, unknown>,
+): string {
+  switch (kind) {
+    case 'app-launch':
+      return d.phase === 'launch'
+        ? `launch ${d.appName ?? d.toAppId ?? ''}`
+        : `dismiss ${d.appName ?? d.fromAppId ?? ''} → ${d.toAppId ?? ''}`
+    case 'toast':
+      return `"${d.text ?? ''}"${d.durationMs ? ` (${d.durationMs}ms)` : ''}`
+    case 'keyboard':
+      return `${d.phase ?? '?'}${d.heightPx ? ` h=${d.heightPx}` : ''}${d.mode ? ` ${d.mode}` : ''}`
+    case 'screen':
+      return `${d.phase ?? '?'} ${d.name ?? d.activeName ?? ''}`
+    case 'flow-step':
+      return `${d.status ?? '?'} ${d.stepName ?? 'step'}${d.durationMs ? ` ${d.durationMs}ms` : ''}`
+    case 'route':
+      return `${d.phase ?? '?'} ${d.path ?? d.pathname ?? ''}`
+    case 'alert':
+    case 'actionsheet':
+    case 'picker':
+      return `${d.phase ?? '?'} ${d.title ?? d.message ?? ''}`
+    case 'notification':
+      return `${d.title ?? ''}${d.body ? ` — ${d.body}` : ''}`
+    case 'fetch':
+      return `${d.method ?? 'GET'} ${d.url ?? ''}${d.status ? ` -> ${d.status}` : ''}`
+    case 'console':
+    case 'console-log':
+      return `${d.level ?? 'log'}: ${(d.message ?? '').toString().slice(0, 120)}`
+    case 'shell':
+      return `${d.event ?? d.type ?? d.phase ?? ''}`
+    case 'scroll':
+      return `${d.phase ?? '?'} ${d.target ?? ''}`
+    case 'gesture':
+      return `${d.phase ?? '?'} ${d.type ?? ''}`
+    case 'text-input':
+      return `${d.phase ?? '?'}${d.value !== undefined ? ` "${String(d.value).slice(0, 40)}"` : ''}`
+    case 'layout':
+      return `${d.kind ?? '?'} ${d.testID ?? d.type ?? ''}${
+        d.skipped ? ` skipped:${d.reason ?? 'unknown'}` : ''
+      }`
+    case 'react-commit': {
+      const slowest = d.slowest as
+        | { displayName?: unknown; durationMs?: unknown }
+        | null
+        | undefined
+      return `${d.fiberCount ?? '?'} fibers ${d.durationMs ?? '?'}ms${
+        slowest?.displayName
+          ? ` · ${slowest.displayName} ${slowest.durationMs ?? '?'}ms`
+          : ''
+      }`
+    }
+    case 'frame':
+      return `${d.totalMs ?? '?'}ms${d.renderMs ? ` · render ${d.renderMs}ms` : ''}${
+        d.layoutMs ? ` · layout ${d.layoutMs}ms` : ''
+      }${d.copyMs ? ` · copy ${d.copyMs}ms` : ''}`
+    case 'reanimated':
+    case 'animation':
+      return `${d.kind ?? ''} ${d.target ?? ''}${d.durationMs ? ` ${d.durationMs}ms` : ''}`
+  }
+  return ''
+}
+
+// one compact line per event: `  +0.42s  shell   [fetch]         GET /api -> 200`.
+// pass anchor = first event's `t` for relative times, or null for wall-clock.
+export function formatTimelineEvent(
+  event: SootSimTimelineEvent,
+  anchor: number | null,
+): string {
+  const ts = formatTimelineRelativeTime(event.t, anchor).padStart(8)
+  const ctx = event.context.padEnd(6)
+  const kind = `[${event.kind}]`.padEnd(15)
+  const d = event.data as Record<string, unknown> | null
+  const payload = d && typeof d === 'object' ? formatTimelinePayload(event.kind, d) : ''
+  return `  ${ts}  ${ctx}  ${kind} ${payload}`
+}
+
+// render an event list as compact lines, anchored to the first event so times
+// read +0.00s, +0.13s, … . the agent tool and CLI both call this rather than
+// JSON-dumping the events array.
+export function formatTimelineEvents(events: readonly SootSimTimelineEvent[]): string {
+  if (!events.length) return ''
+  const anchor = events[0]?.t ?? null
+  return events.map((e) => formatTimelineEvent(e, anchor)).join('\n')
+}