peachsim 0.1.527

package/cli/commands/inspect/core.ts

@@ -0,0 +1,2086 @@
+// transport-agnostic rnx inspect-verb kernels.
+//
+// each function here sends the smallest bridge command its verb needs and
+// returns *structured data* — no arg parsing or stdout. 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 {
+  HEADLESS_TENANT_FETCH_HUNG_MARKER,
+  PUBLIC_NO_NETWORK_MARKER,
+  type SemanticWaitResult,
+} from '../../../src/bridge-contract'
+export {
+  readyProbeHasContent,
+  readyProbeHasTargetContent,
+} from '../../../src/bridge-contract'
+import type {
+  SimSemanticNode,
+  SimSemanticQueryResult,
+  SimSemanticSelector,
+} from '../../../src/bridge-contract'
+import type {
+  SootSimRouteInfo,
+  SootSimRequestEntry,
+  SootSimTimelineEvent,
+  SootSimTimelineKind,
+  SootSimTimelineQuery,
+  SootSimTimelineQueryResult,
+  SootSimTimelineSummary,
+} from '@rnx/globals'
+import type { KeyboardLayoutSnapshot } from 'sootsim-engine/render-worker/native-ui-protocol'
+
+// 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
+// rnx instance.
+export interface InspectBridge {
+  readonly plane?: 'local' | 'cloud'
+  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 result: unknown = await bridge.send({
+    type: 'query',
+    query: { kind: 'count' },
+  })
+  return { nodes: isSemanticQueryResult(result) ? result.total : 0 }
+}
+
+// `get tree` — pruned visible semantic tree. formatting stays client-side.
+export async function inspectTree(
+  bridge: InspectBridge,
+  depth = 5,
+): Promise<{ depth: number; tree: unknown }> {
+  const result: unknown = await bridge.send({
+    type: 'query',
+    query: { kind: 'tree', depth },
+  })
+  const tree = isSemanticQueryResult(result) ? result.nodes : []
+  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
+  // 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 DescribeResult {
+  tree?: string
+  nodeCount?: number
+}
+
+function isSemanticGeometry(value: unknown): boolean {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    [
+      Reflect.get(value, 'x'),
+      Reflect.get(value, 'y'),
+      Reflect.get(value, 'width'),
+      Reflect.get(value, 'height'),
+    ].every((coordinate) =>
+      typeof coordinate === 'number' ? Number.isFinite(coordinate) : false,
+    )
+  )
+}
+
+export function isSimSemanticTree(value: unknown): value is SimSemanticNode[] {
+  if (!Array.isArray(value)) return false
+  return value.every((node) => {
+    if (
+      node === null ||
+      typeof node !== 'object' ||
+      !Number.isInteger(Reflect.get(node, 'nodeId')) ||
+      typeof Reflect.get(node, 'type') !== 'string' ||
+      !isSemanticGeometry(Reflect.get(node, 'geometry'))
+    ) {
+      return false
+    }
+    for (const key of ['testID', 'text', 'role', 'label']) {
+      const value = Reflect.get(node, key)
+      if (value !== undefined && typeof value !== 'string') return false
+    }
+    const pressable = Reflect.get(node, 'pressable')
+    if (pressable !== undefined && pressable !== true) return false
+    const children = Reflect.get(node, 'children')
+    return children === undefined || isSimSemanticTree(children)
+  })
+}
+
+function isSemanticQueryResult(value: unknown): value is SimSemanticQueryResult {
+  const total =
+    value !== null && typeof value === 'object' ? Reflect.get(value, 'total') : undefined
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof total === 'number' &&
+    Number.isInteger(total) &&
+    total >= 0 &&
+    isSimSemanticTree(Reflect.get(value, 'nodes'))
+  )
+}
+
+function globRegex(glob: string): RegExp {
+  const escaped = glob.replace(/[.+^$(){}|[\]\\]/g, '\\$&')
+  return new RegExp(`^${escaped.replace(/\*/g, '.*').replace(/\?/g, '.')}$`, 'i')
+}
+
+export function formatSemanticTree(
+  nodes: readonly SimSemanticNode[],
+  opts: Partial<DescribeDumpOptions> = {},
+): string {
+  const filter = opts.filter?.toLowerCase() ?? ''
+  const testIDRegex = opts.testIdLike ? globRegex(opts.testIdLike) : null
+  const onlyRegex = opts.onlyGlob ? globRegex(opts.onlyGlob) : null
+  const lines: string[] = []
+  const visit = (node: SimSemanticNode, indent: number): void => {
+    const joined = [node.role, node.label, node.text, node.testID]
+      .filter((value): value is string => typeof value === 'string')
+      .join(' ')
+    const matches =
+      (!filter || joined.toLowerCase().includes(filter)) &&
+      (!testIDRegex || testIDRegex.test(node.testID ?? '')) &&
+      (!onlyRegex || onlyRegex.test(joined))
+    if (matches) {
+      const parts = [
+        node.role ? `[${node.role}]` : node.pressable ? '[tap]' : `<${node.type}>`,
+      ]
+      if (node.text) {
+        const text =
+          opts.fullText || node.text.length <= 50
+            ? node.text
+            : `${node.text.slice(0, 49).trimEnd()}…`
+        parts.push(JSON.stringify(text))
+      }
+      if (node.testID) parts.push(`#${node.testID}`)
+      if (node.label && node.label !== node.text) {
+        parts.push(`label=${JSON.stringify(node.label)}`)
+      }
+      if (!opts.hideXy) {
+        const geometry = node.geometry
+        parts.push(
+          `@(${Math.round(geometry.x)},${Math.round(geometry.y)}) ${Math.round(geometry.width)}x${Math.round(geometry.height)}`,
+        )
+      }
+      if (node.pressable) parts.push('(tap)')
+      lines.push(`${'  '.repeat(indent + 1)}${parts.join(' ')}`)
+    }
+    for (const child of node.children ?? []) visit(child, indent + 1)
+  }
+  let roots = nodes
+  if (opts.subtreeRoot) {
+    const pending = [...nodes]
+    let found: SimSemanticNode | undefined
+    while (pending.length > 0 && !found) {
+      const candidate = pending.shift()
+      if (!candidate) continue
+      if (candidate.testID === opts.subtreeRoot) found = candidate
+      else pending.push(...(candidate.children ?? []))
+    }
+    if (!found) return `__SUBTREE_NOT_FOUND__:${opts.subtreeRoot}`
+    roots = [found]
+  }
+  for (const root of roots) visit(root, 0)
+  return lines.join('\n')
+}
+
+// `describe` — format the visible structured tree for humans. callers own
+// arg-parsing, preflight, hints, and the watch loop.
+export async function inspectDescribe(
+  bridge: InspectBridge,
+  dumpOpts: DescribeDumpOptions,
+): Promise<DescribeResult> {
+  const dumpDepth = dumpOpts.maxDepth ?? 12
+  const result: unknown = await bridge.send({
+    type: 'query',
+    query: { kind: 'tree', depth: dumpDepth },
+  })
+  if (!isSemanticQueryResult(result)) return {}
+  return {
+    tree: formatSemanticTree(result.nodes, dumpOpts),
+    nodeCount: result.total,
+  }
+}
+
+// ─── 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/rnx — `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 available only when the caller opts into styling.
+  // measured zero remains distinct from an unavailable field.
+  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) },
+        }
+        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
+// rnx/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[]> {
+  if (!opts.styling) {
+    const result: unknown = await bridge.send({
+      type: 'query',
+      query: { kind: 'find', selector: { visible: true } },
+    })
+    if (!isSemanticQueryResult(result)) return []
+    const filter = opts.filter?.trim().toLowerCase() ?? ''
+    return result.nodes
+      .filter((node) => {
+        if (!filter) return true
+        return [node.text, node.testID, node.role, node.type].some(
+          (value) => typeof value === 'string' && value.toLowerCase().includes(filter),
+        )
+      })
+      .map((node) => ({
+        nodeId: node.nodeId,
+        ...(node.testID ? { testID: node.testID } : {}),
+        ...(node.role ? { role: node.role } : {}),
+        type: node.type,
+        ...(node.text ? { text: node.text } : {}),
+        box: {
+          x: Math.round(node.geometry.x),
+          y: Math.round(node.geometry.y),
+          w: Math.round(node.geometry.width),
+          h: Math.round(node.geometry.height),
+        },
+      }))
+  }
+  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 !== undefined && el.borderRadius > 0) {
+      parts.push(`radius:${el.borderRadius}`)
+    }
+    const p = el.padding
+    if (p && (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 !== undefined && 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
+}
+
+// `get a11y` — flat accessibility summary projected from the visible semantic
+// tree, which already excludes hidden and covered content.
+export async function inspectAccessibilityTree(
+  bridge: InspectBridge,
+): Promise<AccessibilityTreeNode[]> {
+  const result: unknown = await bridge.send({
+    type: 'query',
+    query: { kind: 'find', selector: { visible: true } },
+  })
+  if (!isSemanticQueryResult(result)) return []
+  return result.nodes.flatMap((node) => {
+    if (!node.role && !node.label && !node.text && !node.pressable) return []
+    return [
+      {
+        role:
+          node.role ??
+          (node.pressable ? 'button' : node.type === 'text' ? 'statictext' : 'none'),
+        label: node.label ?? node.text ?? null,
+        hint: null,
+        state: null,
+        testID: node.testID ?? null,
+        position: {
+          x: Math.round(node.geometry.x),
+          y: Math.round(node.geometry.y),
+        },
+        size: {
+          w: Math.round(node.geometry.width),
+          h: Math.round(node.geometry.height),
+        },
+      },
+    ]
+  })
+}
+
+// ─── 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
+}
+
+// resolve a find query to its mode + structured selector. 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; selector: SimSemanticSelector } | null {
+  if (q.testId) {
+    return { mode: 'testid', selector: { testID: q.testId } }
+  }
+  if (q.role) {
+    return { mode: 'role', selector: { role: q.role } }
+  }
+  if (q.type) {
+    return { mode: 'type', selector: { type: q.type } }
+  }
+  if (q.pressable) {
+    return { mode: 'pressable', selector: { pressable: true } }
+  }
+  if (q.interactive) {
+    return { mode: 'interactive-targets', selector: { pressable: true } }
+  }
+  if (q.visible) {
+    return { mode: 'visible', selector: { visible: true } }
+  }
+  if (q.text) {
+    return { mode: 'text', selector: { text: 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: unknown = await bridge.send({
+    type: 'query',
+    query: { kind: 'find', selector: resolved.selector },
+  })
+  if (!isSemanticQueryResult(result)) return { mode: resolved.mode, result: [] }
+  const nodes = result.nodes.map(
+    (node): InteractiveNode => ({
+      type: node.type,
+      nodeId: node.nodeId,
+      ...(node.testID ? { testID: node.testID } : {}),
+      ...(node.text ? { text: node.text } : {}),
+      ...(node.pressable ? { pressable: true } : {}),
+      ...(node.role ? { accessibilityRole: node.role } : {}),
+      ...(node.label ? { accessibilityLabel: node.label } : {}),
+      absolutePosition: { x: node.geometry.x, y: node.geometry.y },
+      layout: { width: node.geometry.width, height: node.geometry.height },
+    }),
+  )
+  const resultValue =
+    resolved.mode === 'testid' || resolved.mode === 'text' ? (nodes[0] ?? null) : nodes
+  return { mode: resolved.mode, result: resultValue }
+}
+
+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 `rnx do` tap command for an interactive node.
+export function tapCommandForNode(n: InteractiveNode): string {
+  if (n.testID) return `rnx do tap-id ${shellEscape(n.testID)}`
+  const text = typeof n.text === 'string' ? n.text.trim() : ''
+  if (text.length > 0 && text.length <= 80) return `rnx 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 `rnx 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 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
+  simId?: string
+}
+
+export function waitReadyReason(
+  status: Pick<
+    WaitReadyStatus,
+    | 'externalError'
+    | 'loadingText'
+    | 'externalReady'
+    | 'externalStatus'
+    | 'flag'
+    | 'targets'
+    | 'suppressedEntryError'
+  > & { bridgeError?: string },
+): string {
+  if (status.bridgeError) {
+    if (
+      status.bridgeError.includes(HEADLESS_TENANT_FETCH_HUNG_MARKER) ||
+      status.bridgeError.includes(PUBLIC_NO_NETWORK_MARKER)
+    ) {
+      return status.bridgeError
+    }
+    return `sim unreachable: ${status.bridgeError} — the target tab is closed or no sim is connected (check \`rnx list\`, reopen with \`rnx open\`)`
+  }
+  const waitingOnGuestFetch =
+    status.externalReady === false && /https?:\/\//.test(status.externalStatus)
+  const base = status.externalError
+    ? `guest app errored: ${status.externalError}`
+    : waitingOnGuestFetch
+      ? `waiting on a guest fetch: ${status.externalStatus}`
+      : 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. the engine owns the full polling loop, so every caller pays
+// exactly one bridge request even for a cold guest bundle.
+export async function inspectWaitReady(
+  bridge: InspectBridge,
+  timeoutMs = 20_000,
+  options: WaitReadyOptions = {},
+): Promise<WaitReadyStatus> {
+  const start = Date.now()
+  let result: SemanticWaitResult
+  try {
+    result = await bridge.send(
+      {
+        type: 'waitFor',
+        ...(options.simId ? { simId: options.simId } : {}),
+        waitForOptions: { condition: { type: 'ready' }, timeoutMs },
+      },
+      { timeoutMs: timeoutMs + 1_000 },
+    )
+  } catch (error) {
+    const bridgeError = error instanceof Error ? error.message : String(error)
+    if (
+      bridgeError.startsWith('multiple sims are connected:') ||
+      bridgeError.startsWith('saved sim ')
+    ) {
+      throw error
+    }
+    result = {
+      matched: false,
+      elapsedMs: Date.now() - start,
+      polls: 0,
+      error: bridgeError,
+    }
+  }
+  const probe = result.probe
+  // a guest app that redboxes still paints: its ErrorBoundary is a real tree
+  // with real nodes, so the engine's own readiness condition matches and every
+  // caller reads exit 0 as "the app is up". an app that has errored is not
+  // ready, so a guest error is disqualifying here rather than merely printed
+  // on the failure path. `errors` (a console.error count) is deliberately not
+  // used because apps can log errors benignly. `suppressedEntryError` remains
+  // excluded because it never gates readiness by contract.
+  const externalError = probe?.externalError ?? ''
+  const status: WaitReadyStatus = {
+    ready: result.matched && !externalError,
+    elapsedMs: result.elapsedMs,
+    nodes: probe?.nodes ?? 0,
+    targets: probe?.targets ?? 0,
+    liveFrameActive: probe?.liveFrameActive ?? false,
+    liveFrameChannels: probe?.liveFrameChannels ?? 0,
+    liveFramePublishes: probe?.liveFramePublishes ?? 0,
+    flag: probe?.flag,
+    loadingText: probe?.loadingText ?? '',
+    externalReady: probe?.externalReady ?? null,
+    externalStatus: probe?.externalStatus ?? '',
+    externalError,
+    suppressedEntryError: probe?.suppressedEntryError ?? '',
+    errors: probe?.errors ?? 0,
+    bridgeError: result.error ?? '',
+  }
+  if (!status.ready && options.onProgress) 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; structural?: boolean } = {},
+): Promise<{ found: boolean; node?: SimSemanticNode; elapsed: number }> {
+  const gone = opts.gone === true
+  const result: SemanticWaitResult = await bridge.send(
+    {
+      type: 'waitFor',
+      waitForOptions: {
+        condition: {
+          type: gone ? 'absent' : opts.structural === true ? 'mounted' : 'present',
+          selector: { testID: testId },
+        },
+        timeoutMs,
+      },
+    },
+    { timeoutMs: timeoutMs + 1_000 },
+  )
+  if (result?.error) throw new Error(result.error)
+  if (result?.node && !isSimSemanticTree([result.node])) {
+    throw new Error('waitFor returned an invalid semantic node')
+  }
+  return {
+    found: result?.matched === true,
+    ...(result?.node ? { node: result.node } : {}),
+    elapsed: result?.elapsedMs ?? timeoutMs,
+  }
+}
+
+// ─── 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[]> {
+  if (bridge.plane === 'cloud') {
+    const state: unknown = await bridge.send({
+      type: 'state',
+      stateOptions: {
+        screenshot: false,
+        tree: false,
+        route: false,
+        errors: false,
+        logs: true,
+        logLimit: 100,
+      },
+    })
+    const recentLogs =
+      state &&
+      typeof state === 'object' &&
+      Array.isArray(Reflect.get(state, 'recentLogs'))
+        ? Reflect.get(state, 'recentLogs')
+        : []
+    return recentLogs.flatMap((entry: unknown, index: number) => {
+      if (!entry || typeof entry !== 'object') return []
+      const text = Reflect.get(entry, 'text')
+      const rawLevel = Reflect.get(entry, 'level')
+      if (typeof text !== 'string') return []
+      const level: LogLevel =
+        rawLevel === 'log' ||
+        rawLevel === 'info' ||
+        rawLevel === 'warn' ||
+        rawLevel === 'error' ||
+        rawLevel === 'debug'
+          ? rawLevel
+          : 'error'
+      const at = Reflect.get(entry, 'at')
+      const ts = typeof at === 'number' && Number.isFinite(at) ? at : 0
+      return [
+        {
+          id: `cloud-${ts}-${index}`,
+          source: 'rnx-cloud',
+          level,
+          ts,
+          args: [text],
+          stack: null,
+        },
+      ]
+    })
+  }
+  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' && /^\[(?:rnx|sootsim)(?:\s[^\]]*)?\]/.test(first)
+      )
+    })
+  }
+  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 ───
+
+// `__sootsimKeyboard.getLayout()` returns the shell's own snapshot, so the
+// engine's contract is the type. a copy here drifts from it silently.
+export type KeyboardState = KeyboardLayoutSnapshot
+
+// `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 buffers belong to their execution context. tenant calls use the
+// existing test bridge; host calls keep shell/compositor flag forwarding intact.
+export async function callDebugBridge(
+  bridge: InspectBridge,
+  expression: string,
+  host = false,
+): Promise<unknown> {
+  const code = `globalThis.__sootsimDebug.${expression}`
+  if (host) return bridge.send({ type: 'evaluate', code })
+  return bridge.send({
+    type: 'evaluate',
+    code: `(async () => {
+      const result = await window.__sootsimTest.evalInTenant(${JSON.stringify(code)})
+      if (!result.ok) throw new Error(result.error)
+      return result.value
+    })()`,
+  })
+}
+
+// `debug recent` reads tenant events; --host explicitly selects the page buffer.
+export async function inspectDebugRecent(
+  bridge: InspectBridge,
+  channel?: string,
+  limit = 50,
+  host = false,
+): Promise<unknown> {
+  return callDebugBridge(
+    bridge,
+    `recent(${channel && channel !== 'all' ? JSON.stringify(channel) : 'undefined'}, ${limit})`,
+    host,
+  )
+}
+
+// channel controls reach the host (and its shell/compositor subscribers) plus
+// the active tenant. await the tenant reply before reporting success.
+export async function setDebugChannels(
+  bridge: InspectBridge,
+  action: 'enable' | 'disable',
+  channels: string[],
+  host = false,
+): Promise<unknown> {
+  const args =
+    channels.length > 0
+      ? channels.map((c) => JSON.stringify(c)).join(', ')
+      : action === 'disable'
+        ? "'all'"
+        : ''
+  const expression = `${action}(${args})`
+  const active = await callDebugBridge(bridge, expression, true)
+  if (host) return active
+  return callDebugBridge(bridge, expression)
+}
+
+// ─── 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> {
+  if (bridge.plane === 'cloud') {
+    const value: unknown = await bridge.send({ type: 'memory' })
+    const rawWasmHeapBytes =
+      typeof value === 'object' && value !== null
+        ? Reflect.get(value, 'wasmHeapBytes')
+        : null
+    const wasmHeapBytes = typeof rawWasmHeapBytes === 'number' ? rawWasmHeapBytes : null
+    return {
+      tenant: {
+        nodesRegistered: null,
+        nodesDetached: null,
+        detachedTypes: null,
+        objects: null,
+        activeNativeAnimations: null,
+        imageLoader: null,
+        workerHeap: null,
+        wasmHeapBytes,
+      },
+      shell: null,
+      compositor: null,
+      hostHeap: null,
+    }
+  }
+  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')
+}