rnxsim 0.1.366 → 0.1.368

package/cli/commands/inspect/core.ts

@@ -1,7 +1,7 @@
 // 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
+// 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
@@ -11,6 +11,16 @@
 // dependency is the `InspectBridge.send` seam below, which both transports
 // satisfy (the CLI's `WsBridge` already has a matching `send`).
 
+import 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,
@@ -38,8 +48,7 @@ export function resolveMaxMsFlag(args: string[], fallbackMs: number): number {
 }
 
 // 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.
+// sootsim instance.
 export interface InspectBridge {
   send(
     cmd: { type: string; [k: string]: any },
@@ -84,34 +93,23 @@ export async function shouldSkipAutoSettleForInspectPick(
 export async function inspectNodeCount(
   bridge: InspectBridge,
 ): Promise<{ nodes: number }> {
-  const count = await bridge.send({
-    type: 'evaluate',
-    code: '(async () => await window.__sootsimTest.getNodeCount())()',
+  const result: unknown = await bridge.send({
+    type: 'query',
+    query: { kind: 'count' },
   })
-  return { nodes: typeof count === 'number' ? count : 0 }
+  return { nodes: isSemanticQueryResult(result) ? result.total : 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.
+// `get tree` — pruned visible semantic tree. formatting stays client-side.
 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}))()`,
+  const result: unknown = await bridge.send({
+    type: 'query',
+    query: { kind: 'tree', depth },
   })
-  if (opts?.format === 'boxes' && typeof tree === 'string') {
-    try {
-      return { depth, tree: JSON.parse(tree) }
-    } catch {
-      return { depth, tree }
-    }
-  }
+  const tree = isSemanticQueryResult(result) ? result.nodes : []
   return { depth, tree }
 }
 
@@ -132,7 +130,6 @@ export interface DescribeDumpOptions {
   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
@@ -141,130 +138,142 @@ export interface DescribeDumpOptions {
   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' }
+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,
+    )
+  )
+}
 
-      let shell = null
-      try {
-        shell = typeof mainShell?.getState === 'function' ? await mainShell.getState() : null
-      } catch {}
+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'))
+  )
+}
 
-      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')
+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))
       }
-      // 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() + '…'
+      if (node.testID) parts.push(`#${node.testID}`)
+      if (node.label && node.label !== node.text) {
+        parts.push(`label=${JSON.stringify(node.label)}`)
       }
-      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 }
+      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')
+}
 
-      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 ?? {}
+// `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 ───
@@ -463,10 +472,11 @@ export interface LayoutElement {
   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
+  // 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
@@ -621,9 +631,6 @@ export function layoutGetNativeEval(opts: LayoutExtractionOptions = {}): string
           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 —
@@ -702,6 +709,34 @@ 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),
@@ -726,13 +761,17 @@ export function formatLayoutElements(
           ? `[${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}`)
+    if (el.borderRadius !== undefined && el.borderRadius > 0) {
+      parts.push(`radius:${el.borderRadius}`)
+    }
     const p = el.padding
-    if (p.t || p.r || p.b || p.l) {
+    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 > 0) parts.push(`font:${el.fontSize}`)
+    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).
@@ -780,89 +819,38 @@ export interface AccessibilityTreeNode {
   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.
+// `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 nodes = await bridge.send({ type: 'evaluate', code: INSPECT_A11Y_CODE })
-  return Array.isArray(nodes) ? (nodes as 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 ───
@@ -886,164 +874,32 @@ export interface FindQuery {
   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
+// 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; code: string } | null {
+export function resolveFindMode(
+  q: FindQuery,
+): { mode: FindMode; selector: SimSemanticSelector } | 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)}))
-    })()`,
-    }
+    return { mode: 'testid', selector: { testID: 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 })
-    })()`,
-    }
+    return { mode: 'role', selector: { role: q.role } }
   }
   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 })
-    })()`,
-    }
+    return { mode: 'type', selector: { type: q.type } }
   }
   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))
-    })()`,
-    }
+    return { mode: 'pressable', selector: { pressable: true } }
   }
   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))
-    })()`,
-    }
+    return { mode: 'interactive-targets', selector: { pressable: true } }
   }
   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)
-    })()`,
-    }
+    return { mode: 'visible', selector: { visible: true } }
   }
   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 { mode: 'text', selector: { text: q.text } }
   }
   return null
 }
@@ -1057,8 +913,27 @@ export async function inspectFind(
 ): 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 }
+  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 {
@@ -1121,189 +996,6 @@ function shellEscape(value: string): string {
 
 // ─── 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 rnx 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
@@ -1369,126 +1061,57 @@ export function waitReadyReason(
 // 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).
+// 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()
-  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)
+  let result: SemanticWaitResult
+  try {
+    result = await bridge.send(
+      {
+        type: 'waitFor',
+        waitForOptions: { condition: { type: 'ready' }, timeoutMs },
+      },
+      { timeoutMs: timeoutMs + 1_000 },
+    )
+  } catch (error) {
+    const bridgeError = error instanceof Error ? error.message : String(error)
     if (
-      (hasReadySignal || hasRenderedContentWithoutReadySignal) &&
-      last.externalReady !== false &&
-      !last.externalError &&
-      !last.loadingText
+      bridgeError.startsWith('multiple sims are connected:') ||
+      bridgeError.startsWith('saved sim ')
     ) {
-      if (now - nodeStableSince >= READY_NODE_STABLE_MS) {
-        return {
-          ...status,
-          ready: true,
-        }
-      }
+      throw error
     }
-    // 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)
+    result = {
+      matched: false,
+      elapsedMs: Date.now() - start,
+      polls: 0,
+      error: bridgeError,
     }
-    await new Promise((r) => setTimeout(r, READY_PROBE_POLL_MS))
   }
+  const probe = result.probe
   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)
+    ready: result.matched,
+    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: probe?.externalError ?? '',
+    suppressedEntryError: probe?.suppressedEntryError ?? '',
+    errors: probe?.errors ?? 0,
+    bridgeError: result.error ?? '',
   }
+  if (!status.ready && options.onProgress) options.onProgress(status)
   return status
 }
 
@@ -1499,72 +1122,26 @@ export async function inspectWaitSelector(
   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).
+): Promise<{ found: boolean; node?: SimSemanticNode; elapsed: number }> {
   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 }
-    })()`,
-    },
+  const result: SemanticWaitResult = await bridge.send(
     {
-      timeoutMs: timeoutMs + 1_000,
+      type: 'waitFor',
+      waitForOptions: {
+        condition: { type: gone ? 'absent' : 'present', testID: testId },
+        timeoutMs,
+      },
     },
+    { timeoutMs: timeoutMs + 1_000 },
   )
-  return (result ?? { found: false, elapsed: timeoutMs }) as {
-    found: boolean
-    node?: any
-    elapsed: number
+  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,
   }
 }