rnxsim 0.1.312 → 0.1.314

package/dist-lib/sdk.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.312 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.314 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;
@@ -29,8 +29,17 @@ __export(sdk_exports, {
   READY_CONTENT_NODE_FLOOR: () => READY_CONTENT_NODE_FLOOR,
   READY_NODE_STABLE_MS: () => READY_NODE_STABLE_MS,
   READY_PROBE_POLL_MS: () => READY_PROBE_POLL_MS,
+  SimClient: () => SimClient,
+  SimClientError: () => SimClientError,
+  SimConnectError: () => SimConnectError,
+  SimKeyboardError: () => SimKeyboardError,
+  SimPerformError: () => SimPerformError,
+  SimReadyTimeoutError: () => SimReadyTimeoutError,
+  SimResetError: () => SimResetError,
+  SimTapError: () => SimTapError,
   WAIT_READY_PROBE: () => WAIT_READY_PROBE,
   WAIT_READY_PROGRESS_INTERVAL_MS: () => WAIT_READY_PROGRESS_INTERVAL_MS,
+  buildSimOpenUrl: () => buildSimOpenUrl,
   clearConsole: () => clearConsole,
   clearLogs: () => clearLogs,
   clearRequests: () => clearRequests,
@@ -92,2175 +101,2645 @@ __export(sdk_exports, {
 });
 module.exports = __toCommonJS(sdk_exports);
 
-// cli/commands/inspect/core.ts
-function resolveMaxMsFlag(args, fallbackMs) {
-  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;
-}
-var INSPECT_PICK_COMMANDS = /* @__PURE__ */ new Set([
-  "tap",
-  "double-tap",
-  "tap-text",
-  "tap-id",
-  "long-press",
-  "touch"
-]);
-function isInspectPickCommand(subcommand) {
-  return typeof subcommand === "string" && INSPECT_PICK_COMMANDS.has(subcommand);
-}
-async function isInspectModeActive(bridge) {
-  const active = await bridge.send({
-    type: "evaluate",
-    code: "window.__sootsimEngineState?.inspectActive === true"
-  });
-  return active === true;
-}
-async function shouldSkipAutoSettleForInspectPick(bridge, subcommand) {
-  if (!isInspectPickCommand(subcommand)) return false;
-  try {
-    return await isInspectModeActive(bridge);
-  } catch {
-    return false;
-  }
-}
-async function inspectNodeCount(bridge) {
-  const count = await bridge.send({
-    type: "evaluate",
-    code: "(async () => await window.__sootsimTest.getNodeCount())()"
-  });
-  return { nodes: typeof count === "number" ? count : 0 };
-}
-async function inspectTree(bridge, depth = 5, opts) {
-  const optsArg = opts?.format ? `, ${JSON.stringify(opts)}` : "";
-  const tree = await bridge.send({
-    type: "evaluate",
-    code: `(async () => await window.__sootsimTest.dumpTree(${depth}${optsArg}))()`
-  });
-  if (opts?.format === "boxes" && typeof tree === "string") {
-    try {
-      return { depth, tree: JSON.parse(tree) };
-    } catch {
-      return { depth, tree };
-    }
-  }
-  return { depth, tree };
-}
-async function inspectUrl(bridge) {
-  const url = await bridge.send({ type: "evaluate", code: "window.location.href" });
-  return { url: typeof url === "string" ? url : "" };
-}
-async function inspectDescribe(bridge, dumpOpts) {
-  const code = `(async () => {
-      const t = window.__sootsimTest
-      const mainShell = window.SootSim?.bridges?.mainShell
-      const kb = window.__sootsimKeyboard
-      if (!t) return { error: 'no test bridge' }
+// cli/commands/inspect/settling.ts
+async function waitForSootsimIdle({
+  bridge,
+  simId,
+  maxMs,
+  pollMs = 50,
+  stablePolls = 3,
+  strict = false
+}) {
+  const result = await bridge.send(
+    {
+      type: "evaluate",
+      simId,
+      code: `(async () => {
+      const start = Date.now()
+      const deadline = start + ${Math.max(0, Math.round(maxMs))}
+      const pollMs = ${Math.max(1, Math.round(pollMs))}
+      const requiredStablePolls = ${Math.max(1, Math.round(stablePolls))}
+      const strict = ${strict ? "true" : "false"}
+      const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
-      let shell = null
+      // route-aware settle: a tap that pushes/pops a screen is async \u2014 the
+      // old screen still renders for a moment, then the new one mounts and
+      // its content loads. a pure layout-hash check reports "idle" on the
+      // outgoing screen or on the incoming skeleton, so a driver re-taps
+      // and stacks duplicate navigations. drain any in-flight screen
+      // transition FIRST, bounded by the overall budget. when no
+      // transition is happening this returns in ~80ms (startWindowMs), so
+      // a plain button tap barely pays for it.
       try {
-        shell = typeof mainShell?.getState === 'function' ? await mainShell.getState() : null
+        const wfst = window.__sootsimTest?.waitForScreenTransitions
+        if (typeof wfst === 'function') {
+          const remaining = deadline - Date.now()
+          if (remaining > 120) {
+            await wfst({
+              timeoutMs: Math.min(remaining - 80, 4000),
+              settleMs: 64,
+              startWindowMs: 80,
+            })
+          }
+        }
       } catch {}
 
-      const opts = ${JSON.stringify(dumpOpts)}
-      const needsRecursiveDump = opts.verbose || opts.subtreeRoot || opts.includeOccluded
-      const globToRegex = (glob) => {
-        const escaped = String(glob).replace(/[.+^$(){}|[\\]\\\\]/g, '\\\\$&')
-        const body = escaped.replace(/\\*/g, '.*').replace(/\\?/g, '.')
-        return new RegExp('^' + body + '$', 'i')
-      }
-      // clipping a describe line is a DISPLAY decision. opts.fullText (set by
-      // \`describe --json\`) keeps the real string, so a bundle-eval stack or a
-      // red-box message reaches the caller whole instead of ending in an
-      // ellipsis nothing downstream can undo.
-      const clipForDisplay = (value, max) => {
-        const text = typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''
-        if (opts.fullText || text.length <= max) return text
-        return text.slice(0, max - 1).trimEnd() + '\u2026'
-      }
-      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)))
+      const readSnapshot = async () => {
+        let animating = false
+        let pendingFetches = 0
+        let requestTotal = 0
+        let requestInFlight = 0
+        try {
+          const stats = await window.__sootsimRenderHost?.queryStats?.()
+          if (stats) {
+            animating =
+              stats.hasActiveAnims === true ||
+              stats.hasActiveNativeAnimations === true ||
+              stats.hasPendingAnimationFrames === true
+            // a freshly-pushed screen showing a skeleton is layout-stable
+            // but not actually settled \u2014 its data/images are still in
+            // flight. treat bounded image-loader fetches as not-idle so
+            // settle waits for real content, capped by the budget.
+            const pf = stats.memory && stats.memory.imageLoader
+              ? stats.memory.imageLoader.pendingFetches
+              : 0
+            pendingFetches = typeof pf === 'number' ? pf : 0
           }
-          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)
+        } catch {}
+        try {
+          const counts = await window.__sootsimTest?.getRequestCounts?.()
+          requestTotal = typeof counts?.total === 'number' ? counts.total : 0
+          requestInFlight = typeof counts?.inFlight === 'number' ? counts.inFlight : 0
+        } catch {}
+        const root = window.__sootsimRoot
+        const nodes = []
+        if (root) {
+          const walk = (n) => {
+            if (n.layout && n.layout.width > 0) {
+              nodes.push(Math.round(n.layout.x) + ',' + Math.round(n.layout.y) + ',' + Math.round(n.layout.width))
+            }
+            for (const c of n.children || []) walk(c)
           }
-          if (handlers.length > 0) parts.push('(tap)')
-          lines.push('  ' + parts.join(' '))
+          walk(root)
         }
-        return { tree: lines.join('\\n'), matched }
+        return { layout: nodes.join(';'), animating, pendingFetches, requestTotal, requestInFlight }
       }
 
-      let tree = ''
-      const compactResult = needsRecursiveDump ? null : await formatInspectableTree()
-      if (compactResult) {
-        tree = compactResult.tree
-      } else {
-        tree = await t.dumpTree(12, opts)
+      // how long generic background network is allowed to keep us waiting AFTER
+      // the screen is otherwise visually settled. apps with continuous traffic
+      // (polling, realtime sockets, a tap that fires 20-50 fetches) never reach
+      // requestInFlight===0 / a stable requestTotal, so requiring full network
+      // quiet burns the ENTIRE budget on every command \u2014 the leading idle that
+      // failed PR-preview recordings for network-heavy apps (3pc fight-pulse).
+      // layout-stability + the image-loader already prove visible content
+      // loaded (a data load changes layout; an image load shows in the loader),
+      // so the generic request counters are a courtesy, not a gate: honor them
+      // only within this grace once the screen is visually still.
+      const networkQuietGraceMs = 1200
+      let lastLayout = ''
+      let lastRequestTotal = -1
+      let stable = 0
+      let visuallyStillSince = 0
+      while (Date.now() < deadline) {
+        const snapshot = await readSnapshot()
+        const strictOk = !strict || !snapshot.animating
+        // visually settled: no animations, no image content loading, layout
+        // unchanged since the last poll.
+        const visuallyStill =
+          strictOk && snapshot.pendingFetches === 0 && snapshot.layout === lastLayout
+        // generic network quiet: nothing in flight and no new requests issued.
+        const networkQuiet =
+          snapshot.requestInFlight === 0 && snapshot.requestTotal === lastRequestTotal
+        if (visuallyStill) {
+          stable++
+          if (visuallyStillSince === 0) visuallyStillSince = Date.now()
+          // settle once the screen has held still long enough AND either the
+          // network is genuinely quiet OR it has refused to quiet within the
+          // grace (continuous background traffic must not block forever).
+          if (
+            stable >= requiredStablePolls &&
+            (networkQuiet || Date.now() - visuallyStillSince >= networkQuietGraceMs)
+          ) {
+            return { settled: true, elapsed: Date.now() - start }
+          }
+        } else {
+          stable = 0
+          visuallyStillSince = 0
+        }
+        lastLayout = snapshot.layout
+        lastRequestTotal = snapshot.requestTotal
+        await sleep(pollMs)
       }
-      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 });
-  return result ?? {};
-}
-function scoreLayoutTextContrast(input) {
-  const required = 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) => {
-    const channel = value / 255;
-    return channel <= 0.04045 ? channel / 12.92 : Math.pow((channel + 0.055) / 1.055, 2.4);
-  };
-  const ratioOf = (foreground, behind) => {
-    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) => `#${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 / 12e3)));
-  const offsetAt = (x, y) => (y * normal.width + x) * 4;
-  const deltaAt = (offset) => 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 = null;
-  let opaqueBackground = 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]
-      ];
+      return { settled: false, elapsed: Date.now() - start }
+    })()`
+    },
+    {
+      timeoutMs: maxMs + 1e3
     }
-  }
-  let bestRatio = Infinity;
-  let bestForeground = null;
-  let bestBackground = null;
-  const consider = (foreground, behind) => {
-    const ratio = ratioOf(foreground, behind);
-    if (ratio >= bestRatio) return;
-    bestRatio = ratio;
-    bestForeground = foreground;
-    bestBackground = behind;
+  );
+  const { elapsed, settled } = result ?? {};
+  return {
+    elapsed: typeof elapsed === "number" ? elapsed : maxMs,
+    settled: settled === true
   };
-  if (strongestDelta >= 2 && strongestForeground) {
-    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) {
-    consider(opaqueBackground, opaqueBackground);
-  }
-  if (!bestForeground || !bestBackground || !Number.isFinite(bestRatio)) {
-    return {
-      ratio: null,
-      required,
-      reason: "could not isolate opaque rendered text pixels"
-    };
+}
+
+// cli/commands/inspect/actions.ts
+var SCREEN_EVAL = `(() => {
+  const spec = window.SootSim?.state?.engineSnapshot?.windowState?.deviceSpec
+  return spec && spec.width > 0 && spec.height > 0
+    ? { width: spec.width, height: spec.height }
+    : null
+})()`;
+var DEFAULT_AGENT_TIMING = {
+  initialWaitMs: 3e3,
+  deadlineMs: 5e3,
+  retryWaitMs: 700
+};
+var DEFAULT_INTERACTIVE_TIMING = {
+  initialWaitMs: 1200,
+  deadlineMs: 2500,
+  retryWaitMs: 700
+};
+function tapTiming(agent, opts = {}) {
+  return {
+    ...agent ? DEFAULT_AGENT_TIMING : DEFAULT_INTERACTIVE_TIMING,
+    ...opts
+  };
+}
+function isTapSuccess(result) {
+  if (!result || result.hit === false || result.ok === false) return false;
+  if (result.requestedTargetMatched === false) return false;
+  if (result.pointerTapHandled === false && !result.keyboardOpened && !result.isTextInput) {
+    return false;
   }
+  return true;
+}
+function tapTargetFromPayload(payload, textFallback) {
   return {
-    ratio: Math.round(bestRatio * 100) / 100,
-    required,
-    foreground: hex(bestForeground),
-    background: hex(bestBackground)
+    nodeId: payload.target?.nodeId ?? payload.match?.nodeId ?? payload.node?.nodeId ?? null,
+    id: payload.target?.id ?? payload.match?.id ?? payload.node?.id ?? null,
+    testID: payload.target?.testID ?? payload.match?.testID ?? payload.node?.testID ?? null,
+    text: payload.target?.text ?? payload.target?.accessibilityLabel ?? payload.match?.text ?? payload.match?.accessibilityLabel ?? payload.node?.text ?? textFallback ?? null,
+    type: payload.target?.type ?? payload.match?.type ?? payload.node?.type ?? null
   };
 }
-function layoutGetNativeEval(opts = {}) {
-  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 \u2014 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)
+async function tapResolvedTarget(bridge, args) {
+  const timing = tapTiming(!!args.agent, args.timing);
+  let attempts = 0;
+  let lastPayload = null;
+  let lastResult = null;
+  try {
+    await waitForSootsimIdle({
+      bridge,
+      maxMs: timing.initialWaitMs,
+      pollMs: 32,
+      stablePolls: 2
+    });
+  } catch {
+  }
+  const deadline = Date.now() + timing.deadlineMs;
+  let lastOffscreenAt = null;
+  while (Date.now() <= deadline || attempts === 0) {
+    attempts++;
+    const payload = await args.resolve();
+    lastPayload = payload;
+    if (payload?.error === "bridge-not-ready" || payload?.ambiguous || payload?.nthOutOfRange) {
+      return { payload, result: null, attempts, failure: "special" };
+    }
+    if (payload && typeof payload.cx === "number" && typeof payload.cy === "number") {
+      if (payload.offscreen) {
+        lastResult = {
+          hit: false,
+          reason: "offscreen",
+          x: payload.cx,
+          y: payload.cy,
+          screen: payload.screen
+        };
+        const at = `${Math.round(payload.cx)},${Math.round(payload.cy)}`;
+        if (lastOffscreenAt === at) {
+          return { payload, result: lastResult, attempts, failure: "missed" };
         }
-        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')
-                  : [],
+        lastOffscreenAt = at;
+      } else {
+        lastOffscreenAt = null;
+        const requestedTarget = tapTargetFromPayload(payload, args.textFallback);
+        const verification = await bridge.send({
+          type: "evaluate",
+          code: `(async () => {
+            const t = window.__sootsimTest
+            if (
+              !t ||
+              typeof t.inspectAt !== 'function' ||
+              typeof t.resolveTapTarget !== 'function'
+            ) {
+              return { error: 'tap-target-inspection-unavailable' }
+            }
+            const requestedTarget = ${JSON.stringify(requestedTarget)}
+            const inspected = await t.inspectAt(${payload.cx}, ${payload.cy})
+            const resolved =
+              inspected && typeof inspected.nodeId === 'number'
+                ? await t.resolveTapTarget(inspected.nodeId)
+                : null
+            const node = (resolved && resolved.target) || inspected
+            const coordinateTarget = node
+              ? {
+                  nodeId: node.nodeId ?? null,
+                  id: node.id ?? null,
+                  testID: node.testID ?? null,
+                  text: node.text ?? node.accessibilityLabel ?? null,
+                  type: node.type ?? null,
+                }
+              : null
+            const coordinateAncestors = Array.isArray(inspected?.ancestors)
+              ? inspected.ancestors
+              : []
+            const ancestorMatchesRequested = coordinateAncestors.some(
+              (ancestor) =>
+                (typeof requestedTarget.nodeId === 'number' &&
+                  ancestor?.nodeId === requestedTarget.nodeId) ||
+                (requestedTarget.testID &&
+                  ancestor?.testID === requestedTarget.testID) ||
+                (requestedTarget.id && ancestor?.id === requestedTarget.id),
+            )
+            const requestedTargetMatched =
+              coordinateTarget === null
+                ? false
+                : typeof requestedTarget.nodeId === 'number' &&
+                    typeof coordinateTarget.nodeId === 'number'
+                  ? requestedTarget.nodeId === coordinateTarget.nodeId ||
+                    ancestorMatchesRequested
+                  : requestedTarget.testID && coordinateTarget.testID
+                    ? requestedTarget.testID === coordinateTarget.testID
+                      || ancestorMatchesRequested
+                    : requestedTarget.id && coordinateTarget.id
+                      ? requestedTarget.id === coordinateTarget.id
+                        || ancestorMatchesRequested
+                      : ancestorMatchesRequested
+            if (!requestedTargetMatched) {
+              return {
+                requestedTargetMatched,
+                requestedTarget,
+                coordinateTarget,
               }
-            : {}),
-          testID: n.testID || n.testId || undefined,
-          role: n.accessibilityRole || n.role || undefined,
-          type: typeof n.type === 'string' ? n.type : 'node',
-          text,
-          box: { x: round(abs.x), y: round(abs.y), w: round(layout.width), h: round(layout.height) },
-          borderRadius: 0,
-          padding: { t: 0, r: 0, b: 0, l: 0 },
-          fontSize: 0,
+            }
+            if (typeof t.activatePressAt !== 'function') {
+              return { error: 'tap-target-activation-unavailable' }
+            }
+            const activation = await t.activatePressAt(
+              ${payload.cx},
+              ${payload.cy},
+              requestedTarget.nodeId,
+            )
+            if (activation?.ok) {
+              window.dispatchEvent(
+                new CustomEvent('sootsim:agentAction', {
+                  detail: {
+                    type: 'tap',
+                    x: ${payload.cx},
+                    y: ${payload.cy},
+                    target: requestedTarget,
+                  },
+                }),
+              )
+            }
+            return {
+              activation,
+              requestedTargetMatched,
+              requestedTarget,
+              coordinateTarget,
+            }
+          })()`
+        });
+        if (verification?.error) {
+          return {
+            payload,
+            result: {
+              hit: false,
+              reason: verification.error,
+              requestedTarget
+            },
+            attempts,
+            failure: "special"
+          };
         }
-        if (!includeStyle) return base
-        // computedStyle has the resolved values; style is the curated subset \u2014
-        // 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,
+        if (verification?.requestedTargetMatched === false) {
+          return {
+            payload,
+            result: {
+              hit: false,
+              reason: "target-covered",
+              ...verification
+            },
+            attempts,
+            failure: "missed"
+          };
         }
-      })
-      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,
-        })
+        const dispatched = verification?.activation?.tap ?? verification?.activation;
+        const result = dispatched && typeof dispatched === "object" ? { ...dispatched, ...verification?.activation, ...verification } : { hit: !!dispatched, ...verification };
+        lastResult = result;
+        if (isTapSuccess(result)) return { payload, result, attempts };
       }
-      return elements
-    })()`;
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    try {
+      await waitForSootsimIdle({
+        bridge,
+        maxMs: Math.min(remaining, timing.retryWaitMs),
+        pollMs: 32,
+        stablePolls: 2
+      });
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, Math.min(120, remaining)));
+    }
+  }
+  return {
+    payload: lastPayload,
+    result: lastResult,
+    attempts,
+    failure: lastPayload && typeof lastPayload.cx === "number" ? "missed" : "not-found"
+  };
 }
-var LAYOUT_GET_NATIVE_EVAL = layoutGetNativeEval();
-async function inspectGetLayout(bridge, opts = {}) {
-  const raw = await bridge.send({
-    type: "evaluate",
-    code: layoutGetNativeEval(opts)
+async function tapCoordinates(bridge, x, y, target) {
+  return bridge.send({
+    type: "tap",
+    x,
+    y,
+    ...target ? { target } : {}
   });
-  return Array.isArray(raw) ? raw : [];
 }
-function formatLayoutElements(elements, opts) {
-  if (elements.length === 0) return "  no visible elements found";
-  const lines = elements.map((el) => {
-    const ident = el.testID ? `#${el.testID}` : el.selector ? el.selector : el.role ? `[${el.role}]` : `<${el.type}>`;
-    const parts = [ident, `@(${el.box.x},${el.box.y})`, `${el.box.w}x${el.box.h}`];
-    if (el.borderRadius > 0) parts.push(`radius:${el.borderRadius}`);
-    const p = el.padding;
-    if (p.t || p.r || p.b || p.l) {
-      const uniform = p.t === p.r && p.r === p.b && p.b === p.l;
-      parts.push(uniform ? `pad:${p.t}` : `pad:${p.t},${p.r},${p.b},${p.l}`);
-    }
-    if (el.fontSize > 0) parts.push(`font:${el.fontSize}`);
-    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)}\u2026` : el.text;
-      parts.push(`"${text}"`);
-    }
-    return `  ${parts.join(" ")}`;
+async function tapById(bridge, query, opts = {}) {
+  const arg = JSON.stringify(query);
+  return tapResolvedTarget(bridge, {
+    agent: opts.agent,
+    timing: opts.timing,
+    resolve: () => bridge.send({
+      type: "evaluate",
+      code: `(async () => {
+          const t = window.__sootsimTest
+          if (!t) return null
+          const n = (await t.findByTestId(${arg})) || (await t.findById(${arg}))
+          if (!n || !n.absolutePosition || !n.layout) return { cx: null }
+          const resolved =
+            typeof n.nodeId === 'number' && typeof t.resolveTapTarget === 'function'
+              ? await t.resolveTapTarget(n.nodeId)
+              : null
+          const target = (resolved && resolved.target) || n
+          const cx =
+            resolved && typeof resolved.cx === 'number'
+              ? resolved.cx
+              : n.absolutePosition.x + (n.layout.width || 0) / 2
+          const cy =
+            resolved && typeof resolved.cy === 'number'
+              ? resolved.cy
+              : n.absolutePosition.y + (n.layout.height || 0) / 2
+          const scr = ${SCREEN_EVAL}
+          const offscreen =
+            !!scr && (cx < 0 || cy < 0 || cx > scr.width || cy > scr.height)
+          return {
+            cx,
+            cy,
+            ...(offscreen ? { offscreen: true, screen: scr } : {}),
+            match: {
+              nodeId: n.nodeId ?? null,
+              id: n.id,
+              testID: n.testID,
+              text: n.text ?? n.accessibilityLabel ?? null,
+              type: n.type,
+            },
+            target: {
+              nodeId: target.nodeId ?? null,
+              id: target.id,
+              testID: target.testID,
+              text:
+                target.text ??
+                target.accessibilityLabel ??
+                n.text ??
+                n.accessibilityLabel ??
+                null,
+              type: target.type,
+            },
+            strategy: (resolved && resolved.strategy) || 'matched-node',
+          }
+        })()`
+    })
   });
-  return lines.join("\n");
 }
-var INSPECT_A11Y_CODE = `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
+async function tapByText(bridge, query, options = {}, opts = {}) {
+  const filterArg = JSON.stringify({
+    query,
+    exact: !!options.exact,
+    role: options.role ?? null,
+    within: options.within ?? null,
+    minX: options.minX ?? null,
+    maxX: options.maxX ?? null,
+    minY: options.minY ?? null,
+    maxY: options.maxY ?? null,
+    near: options.near ?? null,
+    nth: options.nth ?? null,
+    first: !!options.first
+  });
+  return tapResolvedTarget(bridge, {
+    agent: opts.agent,
+    timing: opts.timing,
+    textFallback: query,
+    resolve: () => bridge.send({
+      type: "evaluate",
+      code: `(async () => {
+          const t = window.__sootsimTest
+          if (!t) return { error: 'bridge-not-ready' }
+          const F = ${filterArg}
 
-      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,
-        }
-      }
+          const res = await t.queryTextCandidates({
+            query: F.query,
+            exact: !!F.exact,
+            ...(F.role ? { role: F.role } : {}),
+          })
 
-      if (typeof t.listInspectable === 'function') {
-        const list = await t.listInspectable({})
-        if (Array.isArray(list)) {
-          return list.filter(n => isVisibleTarget(n) && hasAccessibleSignal(n)).map(normalize)
-        }
-      }
+          let candidates = res.candidates || []
 
-      const all = await t.queryAll({ pruneHidden: true })
-      return all
-        .filter(n => isVisibleTarget(n) && hasAccessibleSignal(n))
-        .map(normalize)
-    })()`;
-async function inspectAccessibilityTree(bridge) {
-  const nodes = await bridge.send({ type: "evaluate", code: INSPECT_A11Y_CODE });
-  return Array.isArray(nodes) ? nodes : [];
-}
-var 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
-        )
-      }
-`;
-function resolveFindMode(q) {
-  if (q.testId) {
-    return {
-      mode: "testid",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return null
-      return (await t.findByTestId(${JSON.stringify(q.testId)})) || (await t.findById(${JSON.stringify(q.testId)}))
-    })()`
-    };
-  }
-  if (q.role) {
-    return {
-      mode: "role",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-      return await t.queryAll({ hasRole: ${JSON.stringify(q.role)}, pruneHidden: true })
-    })()`
-    };
-  }
-  if (q.type) {
-    return {
-      mode: "type",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-      return await t.queryAll({ type: ${JSON.stringify(q.type)}, pruneHidden: true })
-    })()`
-    };
-  }
-  if (q.pressable) {
-    return {
-      mode: "pressable",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-${FIND_INSPECTABLE_TARGETS}
-      const inspectable = await fromInspectable()
-      if (inspectable) return inspectable.filter(n => n.pressable && isVisibleTarget(n))
-      const all = await t.queryAll({ pruneHidden: true })
-      return all.filter(n => n.pressable && isVisibleTarget(n))
-    })()`
-    };
-  }
-  if (q.interactive) {
-    return {
-      mode: "interactive-targets",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-${FIND_INSPECTABLE_TARGETS}
-      const inspectable = await fromInspectable()
-      if (inspectable) {
-        return inspectable.filter(n => n.pressable && isVisibleTarget(n))
-      }
-      const all = await t.queryAll({ pruneHidden: true })
-      return all.filter(n => n.pressable && isVisibleTarget(n))
-    })()`
-    };
-  }
-  if (q.visible) {
-    return {
-      mode: "visible",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-      const all = await t.queryAll({ pruneHidden: true })
-      return all.filter(n => n.layout && n.layout.width > 0 && n.layout.height > 0)
-    })()`
-    };
-  }
-  if (q.text) {
-    return {
-      mode: "text",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return null
-      return await t.findByText(${JSON.stringify(q.text)})
-    })()`
-    };
-  }
-  return null;
-}
-async function inspectFind(bridge, q) {
-  const resolved = resolveFindMode(q);
-  if (!resolved) return null;
-  const result = await bridge.send({ type: "evaluate", code: resolved.code });
-  return { mode: resolved.mode, result };
-}
-function rankInteractive(nodes) {
-  return [...nodes].sort((a, b) => scoreInteractive(b) - scoreInteractive(a));
-}
-function scoreInteractive(n) {
-  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 <= 6e4) score += 25;
-  else if (area > 6e4) score -= 20;
-  const y = n.absolutePosition?.y ?? 0;
-  if (y < 0) score -= 30;
-  return score;
-}
-function tapCommandForNode(n) {
-  if (n.testID) return `rnxsim do tap-id ${shellEscape(n.testID)}`;
-  const text = typeof n.text === "string" ? n.text.trim() : "";
-  if (text.length > 0 && text.length <= 80)
-    return `rnxsim do tap-text ${shellEscape(text)}`;
-  const x = Math.round(((n.absolutePosition?.x ?? 0) + (n.layout?.width ?? 0) / 2) * 10) / 10;
-  const y = Math.round(((n.absolutePosition?.y ?? 0) + (n.layout?.height ?? 0) / 2) * 10) / 10;
-  return `rnxsim do tap ${x} ${y}`;
-}
-function shellEscape(value) {
-  if (/^[A-Za-z0-9_./@:-]+$/.test(value)) return value;
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-var WAIT_READY_PROBE = `(async () => {
-    const t = window.__sootsimTest
-    let nodes = 0
-    try { nodes = (await t?.getNodeCount?.()) || 0 } catch {}
-    let targets = 0
-    let liveFrameActive = false
-    let liveFrameChannels = 0
-    let liveFramePublishes = 0
-    let loadingText = ''
-    const cleanText = (value) =>
-      typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''
-    const loadingSignal = (value) => {
-      const text = cleanText(value)
-      if (!text) return ''
-      return /^(opening app\\b|looking for your app\\b|building bundle\\b|preparing rnxsim runtime\\b|loading native bundle\\b|loading rnx stubs\\b|loading bundle loader\\b|loading native stubs\\b|loading compat bridge\\b|loading react-native shim\\b|loading react bridge\\b|loading reconciler\\b|loading replacement modules\\b|injecting rnx modules\\b|warming sqlite engine\\b|capturing root component\\b|reloading app\\b|loading(?:[.!\u2026]*)?$|connecting(?:[.!\u2026]*)?$)/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 \u2014 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 \u2014 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,
-    }
-  })()`;
-var READY_CONTENT_NODE_FLOOR = 100;
-var READY_NODE_STABLE_MS = 750;
-var WAIT_READY_PROGRESS_INTERVAL_MS = 2e3;
-var READY_PROBE_POLL_MS = 150;
-function readyProbeHasContent(probe) {
-  return probe.liveFrameActive || probe.targets > 0 || probe.nodes >= READY_CONTENT_NODE_FLOOR;
-}
-function readyProbeHasTargetContent(probe) {
-  return probe.liveFrameActive || probe.targets > 0;
-}
-function waitReadyReason(status) {
-  if (status.bridgeError) {
-    return `sim unreachable: ${status.bridgeError} \u2014 the target tab is closed or no sim is connected (check \`rnxsim list\`, reopen with \`rnxsim open\`)`;
-  }
-  const base = status.externalError ? `guest app errored: ${status.externalError}` : status.loadingText ? `still showing "${status.loadingText}"` : status.externalReady === false ? "guest app is still loading" : status.flag !== true && status.targets > 0 ? "native content is rendered but the ready signal has not settled" : status.flag !== true ? "guest app has not emitted sootsim:externalAppReady" : status.targets <= 0 ? "ready flag emitted but no visible app content is inspectable yet" : "node tree is still changing";
-  return !status.externalError && status.suppressedEntryError ? `${base} (suppressed entry error: ${status.suppressedEntryError})` : base;
-}
-async function inspectWaitReady(bridge, timeoutMs = 2e4, options = {}) {
-  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;
-  let bridgeError = "";
-  let last = {
-    flag: void 0,
-    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);
-      if (bridgeError.startsWith("multiple sims are connected:") || bridgeError.startsWith("saved sim ")) {
-        throw error;
-      }
-    }
-    const now = Date.now();
-    const status2 = {
-      ready: false,
-      elapsedMs: now - start,
-      nodes: last.nodes,
-      targets: last.targets,
-      liveFrameActive: last.liveFrameActive,
-      liveFrameChannels: last.liveFrameChannels,
-      liveFramePublishes: last.liveFramePublishes,
-      flag: last.flag,
-      loadingText: last.loadingText,
-      externalReady: last.externalReady,
-      externalStatus: last.externalStatus,
-      externalError: last.externalError,
-      suppressedEntryError: last.suppressedEntryError,
-      errors: last.errors,
-      bridgeError
-    };
-    if (last.nodes !== lastNodes) {
-      lastNodes = last.nodes;
-      nodeStableSince = now;
-    }
-    const hasReadySignal = last.flag === true && readyProbeHasContent(last);
-    const hasRenderedContentWithoutReadySignal = last.flag !== true && readyProbeHasTargetContent(last);
-    if ((hasReadySignal || hasRenderedContentWithoutReadySignal) && last.externalReady !== false && !last.externalError && !last.loadingText) {
-      if (now - nodeStableSince >= READY_NODE_STABLE_MS) {
-        return {
-          ...status2,
-          ready: true
-        };
-      }
-    }
-    if (last.externalError) return status2;
-    if (options.onProgress && progressIntervalMs > 0 && now >= nextProgressAt) {
-      options.onProgress(status2);
-      do {
-        nextProgressAt += progressIntervalMs;
-      } while (now >= nextProgressAt);
-    }
-    await new Promise((r) => setTimeout(r, READY_PROBE_POLL_MS));
-  }
-  const status = {
-    ready: false,
-    elapsedMs: Date.now() - start,
-    nodes: last.nodes,
-    targets: last.targets,
-    liveFrameActive: last.liveFrameActive,
-    liveFrameChannels: last.liveFrameChannels,
-    liveFramePublishes: last.liveFramePublishes,
-    flag: last.flag,
-    loadingText: last.loadingText,
-    externalReady: last.externalReady,
-    externalStatus: last.externalStatus,
-    externalError: last.externalError,
-    suppressedEntryError: last.suppressedEntryError,
-    errors: last.errors,
-    bridgeError
-  };
-  if (options.onProgress && progressIntervalMs > 0 && Date.now() >= nextProgressAt) {
-    options.onProgress(status);
-  }
-  return status;
-}
-async function inspectWaitSelector(bridge, testId, timeoutMs = 5e3, opts = {}) {
-  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 \u2014 indeterminate, not "gone"
-        try {
-          // gone-mode confirms a gate/screen LEFT \u2014 it only needs structural
-          // existence + layout, NOT the full-tree occlusion pass (pruneHidden).
-          // that pass (computeOccludedInspectNodeIds) walks the whole tree and
-          // does O(n\xB2)-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 \u2014 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 }
+          candidates = candidates.filter((c) => {
+            const ax = c.info.absolutePosition && c.info.absolutePosition.x
+            const ay = c.info.absolutePosition && c.info.absolutePosition.y
+            if (F.minX !== null && !(ax >= F.minX)) return false
+            if (F.maxX !== null && !(ax <= F.maxX)) return false
+            if (F.minY !== null && !(ay >= F.minY)) return false
+            if (F.maxY !== null && !(ay <= F.maxY)) return false
+            if (F.within && !c.ancestorTestIDs.includes(F.within)) return false
+            return true
+          })
+
+          if (F.near) {
+            candidates.sort((a, b) => {
+              const ax = (a.info.absolutePosition && a.info.absolutePosition.x) || 0
+              const ay = (a.info.absolutePosition && a.info.absolutePosition.y) || 0
+              const bx = (b.info.absolutePosition && b.info.absolutePosition.x) || 0
+              const by = (b.info.absolutePosition && b.info.absolutePosition.y) || 0
+              return (
+                Math.hypot(ax - F.near.x, ay - F.near.y) -
+                Math.hypot(bx - F.near.x, by - F.near.y)
+              )
+            })
           } else {
-            goneStreak = 0
+            candidates.sort((a, b) => {
+              const ay = (a.info.absolutePosition && a.info.absolutePosition.y) || 0
+              const by = (b.info.absolutePosition && b.info.absolutePosition.y) || 0
+              if (Math.abs(ay - by) > 2) return ay - by
+              const ax = (a.info.absolutePosition && a.info.absolutePosition.x) || 0
+              const bx = (b.info.absolutePosition && b.info.absolutePosition.x) || 0
+              return ax - bx
+            })
           }
-        } else if (present(node)) {
-          return { found: true, node, elapsed: Date.now() - start }
-        }
-        await new Promise((r) => setTimeout(r, 80))
-      }
-      return { found: false, elapsed: Date.now() - start }
-    })()`
-    },
-    {
-      timeoutMs: timeoutMs + 1e3
-    }
-  );
-  return result ?? { found: false, elapsed: timeoutMs };
-}
-function consoleEntriesEval(level, limit) {
-  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 \u2014 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})
-  })()`;
-}
-async function inspectErrors(bridge, limit = 20) {
-  const result = await bridge.send({
-    type: "evaluate",
-    code: consoleEntriesEval("error", limit)
-  });
-  return Array.isArray(result) ? result : [];
-}
-async function inspectWarnings(bridge, limit = 20) {
-  const result = await bridge.send({
-    type: "evaluate",
-    code: consoleEntriesEval("warn", limit)
+
+          const total = candidates.length
+          if (total === 0) return { matched: 0, total: 0 }
+
+          let idx = 0
+          if (F.nth !== null) {
+            idx = F.nth < 0 ? total + F.nth : F.nth
+            if (idx < 0 || idx >= total) {
+              return { matched: 0, total, nthOutOfRange: true, nth: F.nth }
+            }
+          } else if (total > 1 && !F.first && !F.near) {
+            return {
+              ambiguous: true,
+              total,
+              candidates: candidates.slice(0, 10).map((c, i) => ({
+                idx: i,
+                nodeId: c.info.nodeId,
+                type: c.info.type,
+                testID: c.info.testID,
+                text: (c.info.text || '').slice(0, 60),
+                abs: c.info.absolutePosition,
+                layout: c.info.layout
+                  ? {
+                      width: Math.round(c.info.layout.width || 0),
+                      height: Math.round(c.info.layout.height || 0),
+                    }
+                  : null,
+                ancestorTestIDs: (c.ancestorTestIDs || []).slice(0, 5),
+              })),
+            }
+          }
+
+          const picked = candidates[idx]
+          const n = picked.info
+          if (!n.absolutePosition || !n.layout) return { matched: 0, total }
+
+          const resolved =
+            typeof n.nodeId === 'number' &&
+            typeof t.resolveTapTarget === 'function'
+              ? await t.resolveTapTarget(n.nodeId)
+              : null
+          const target = (resolved && resolved.target) || n
+          const cx =
+            resolved && typeof resolved.cx === 'number'
+              ? resolved.cx
+              : n.absolutePosition.x + (n.layout.width || 0) / 2
+          const cy =
+            resolved && typeof resolved.cy === 'number'
+              ? resolved.cy
+              : n.absolutePosition.y + (n.layout.height || 0) / 2
+          const scr = ${SCREEN_EVAL}
+          const offscreen =
+            !!scr && (cx < 0 || cy < 0 || cx > scr.width || cy > scr.height)
+          return {
+            cx,
+            cy,
+            ...(offscreen ? { offscreen: true, screen: scr } : {}),
+            match: {
+              nodeId: n.nodeId ?? null,
+              id: n.id,
+              testID: n.testID,
+              type: n.type,
+            },
+            target: {
+              nodeId: target.nodeId ?? null,
+              id: target.id,
+              testID: target.testID,
+              text:
+                target.text ??
+                target.accessibilityLabel ??
+                n.text ??
+                n.accessibilityLabel ??
+                null,
+              type: target.type,
+            },
+            strategy: (resolved && resolved.strategy) || 'matched-node',
+            total,
+            idx,
+          }
+        })()`
+    })
   });
-  return Array.isArray(result) ? result : [];
 }
-var 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++
+async function tapBest(bridge, query, opts = {}) {
+  const arg = JSON.stringify(query);
+  return tapResolvedTarget(bridge, {
+    agent: opts.agent,
+    timing: opts.timing,
+    textFallback: query,
+    resolve: async () => {
+      const payload = await bridge.send({
+        type: "evaluate",
+        code: `(async () => {
+          const t = window.__sootsimTest
+          if (!t) return { error: 'bridge-not-ready' }
+          const byTestId =
+            (await t.findByTestId(${arg})) || (await t.findById(${arg}))
+          if (byTestId && byTestId.absolutePosition && byTestId.layout) {
+            return {
+              strategy: 'testid',
+              node: {
+                nodeId: byTestId.nodeId ?? null,
+                id: byTestId.id,
+                testID: byTestId.testID,
+                type: byTestId.type,
+                text: byTestId.text,
+                absolutePosition: byTestId.absolutePosition,
+                layout: byTestId.layout,
+              },
+              screen: ${SCREEN_EVAL},
+            }
+          }
+          const byText = await t.findByText(${arg})
+          if (byText && byText.absolutePosition && byText.layout) {
+            return {
+              strategy: 'text',
+              node: {
+                nodeId: byText.nodeId ?? null,
+                id: byText.id,
+                testID: byText.testID,
+                type: byText.type,
+                text: byText.text,
+                absolutePosition: byText.absolutePosition,
+                layout: byText.layout,
+              },
+              screen: ${SCREEN_EVAL},
+            }
+          }
+          return { strategy: 'none' }
+        })()`
+      });
+      if (!payload || !("node" in payload)) return payload;
+      const node = payload.node;
+      const cx = node.absolutePosition.x + node.layout.width / 2;
+      const cy = node.absolutePosition.y + node.layout.height / 2;
+      const screen = payload.screen ?? null;
+      const offscreen = !!screen && (cx < 0 || cy < 0 || cx > screen.width || cy > screen.height);
+      return {
+        ...payload,
+        cx,
+        cy,
+        ...offscreen ? { offscreen: true, screen } : {},
+        target: {
+          id: node.id,
+          testID: node.testID,
+          text: payload.strategy === "text" ? query : node.text,
+          type: node.type
+        }
+      };
     }
-    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 }
-  })()`;
-async function clearConsole(bridge) {
-  await bridge.send({
-    type: "evaluate",
-    code: 'window.__sootsimConsole?.clear(); window.__sootsimObservability?.logs?.clear?.(); "cleared"'
   });
 }
-async function inspectRequests(bridge, opts = {}) {
-  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 : [];
+
+// cli/commands/inspect/core.ts
+function resolveMaxMsFlag(args, fallbackMs) {
+  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;
 }
-async function clearRequests(bridge) {
-  await bridge.send({ type: "call", path: "__sootsimTest.clearRequests", args: [] });
+var INSPECT_PICK_COMMANDS = /* @__PURE__ */ new Set([
+  "tap",
+  "double-tap",
+  "tap-text",
+  "tap-id",
+  "long-press",
+  "touch"
+]);
+function isInspectPickCommand(subcommand) {
+  return typeof subcommand === "string" && INSPECT_PICK_COMMANDS.has(subcommand);
 }
-async function inspectScrollStateAt(bridge, x, y) {
-  const result = await bridge.send({
-    type: "call",
-    path: "__sootsimTest.getScrollStateAt",
-    args: [x, y]
+async function isInspectModeActive(bridge) {
+  const active = await bridge.send({
+    type: "evaluate",
+    code: "window.__sootsimEngineState?.inspectActive === true"
   });
-  if (!result || typeof result !== "object") return null;
-  const state = result;
-  return {
-    ...state,
-    scrollOffsetX: typeof state.scrollOffsetX === "number" ? state.scrollOffsetX : state.offsetX,
-    scrollOffsetY: typeof state.scrollOffsetY === "number" ? state.scrollOffsetY : state.offsetY
-  };
+  return active === true;
 }
-async function inspectLogs(bridge) {
-  const res = await bridge.send({
+async function shouldSkipAutoSettleForInspectPick(bridge, subcommand) {
+  if (!isInspectPickCommand(subcommand)) return false;
+  try {
+    return await isInspectModeActive(bridge);
+  } catch {
+    return false;
+  }
+}
+async function inspectNodeCount(bridge) {
+  const count = await bridge.send({
     type: "evaluate",
-    code: `(() => {
-      const obs = window.__sootsimObservability;
-      if (!obs) return { ok: false };
-      return { ok: true, entries: obs.logs.getSnapshot() };
-    })()`
+    code: "(async () => await window.__sootsimTest.getNodeCount())()"
   });
-  if (!res || !res.ok) return [];
-  return res.entries ?? [];
+  return { nodes: typeof count === "number" ? count : 0 };
 }
-async function clearLogs(bridge) {
-  await bridge.send({
+async function inspectTree(bridge, depth = 5, opts) {
+  const optsArg = opts?.format ? `, ${JSON.stringify(opts)}` : "";
+  const tree = await bridge.send({
     type: "evaluate",
-    code: 'window.__sootsimObservability?.logs.clear(); "cleared"'
+    code: `(async () => await window.__sootsimTest.dumpTree(${depth}${optsArg}))()`
   });
-}
-function isForwardedWorkerLogTwin(a, b) {
-  if (a.source === b.source) return false;
-  if (a.level !== b.level) return false;
-  if (Math.abs(a.ts - b.ts) > 1e3) return false;
-  if (a.args.length !== b.args.length) return false;
-  const sources = /* @__PURE__ */ 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;
+  if (opts?.format === "boxes" && typeof tree === "string") {
+    try {
+      return { depth, tree: JSON.parse(tree) };
+    } catch {
+      return { depth, tree };
+    }
   }
-  return a.args.every((arg, index) => arg === b.args[index]);
+  return { depth, tree };
 }
-function filterLogEntries(entries, opts = {}) {
-  let out = [];
-  for (const entry of entries) {
-    if (out.some((candidate) => isForwardedWorkerLogTwin(candidate, entry))) {
-      continue;
+async function inspectUrl(bridge) {
+  const url = await bridge.send({ type: "evaluate", code: "window.location.href" });
+  return { url: typeof url === "string" ? url : "" };
+}
+async function inspectDescribe(bridge, dumpOpts) {
+  const dumpDepth = dumpOpts.maxDepth ?? 12;
+  const code = `(async () => {
+      const t = window.__sootsimTest
+      const mainShell = window.SootSim?.bridges?.mainShell
+      const kb = window.__sootsimKeyboard
+      if (!t) return { error: 'no test bridge' }
+
+      let shell = null
+      try {
+        shell = typeof mainShell?.getState === 'function' ? await mainShell.getState() : null
+      } catch {}
+
+      const opts = ${JSON.stringify(dumpOpts)}
+      const needsRecursiveDump =
+        opts.verbose || opts.subtreeRoot || opts.includeOccluded || opts.maxDepth != null
+      const globToRegex = (glob) => {
+        const escaped = String(glob).replace(/[.+^$(){}|[\\]\\\\]/g, '\\\\$&')
+        const body = escaped.replace(/\\*/g, '.*').replace(/\\?/g, '.')
+        return new RegExp('^' + body + '$', 'i')
+      }
+      // clipping a describe line is a DISPLAY decision. opts.fullText (set by
+      // \`describe --json\`) keeps the real string, so a bundle-eval stack or a
+      // red-box message reaches the caller whole instead of ending in an
+      // ellipsis nothing downstream can undo.
+      const clipForDisplay = (value, max) => {
+        const text = typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''
+        if (opts.fullText || text.length <= max) return text
+        return text.slice(0, max - 1).trimEnd() + '\u2026'
+      }
+      const formatInspectableTree = async () => {
+        if (typeof t.listInspectable !== 'function') return null
+        const list = await t.listInspectable({})
+        if (!Array.isArray(list)) return null
+        const filter = typeof opts.filter === 'string' ? opts.filter.toLowerCase() : ''
+        const testIdRegex = opts.testIdLike ? globToRegex(opts.testIdLike) : null
+        const onlyRegex = opts.onlyGlob ? globToRegex(opts.onlyGlob) : null
+        const lines = []
+        let matched = 0
+        for (const node of list) {
+          const testID = node?.testID || node?.testId || ''
+          const role = node?.role || ''
+          const label = node?.accessibilityLabel || node?.label || ''
+          const text = node?.text || ''
+          if (testIdRegex && !testIdRegex.test(testID)) continue
+          const joined = [role, label, text, testID].filter(Boolean).join(' ')
+          if (onlyRegex && !onlyRegex.test(joined)) continue
+          if (filter && !joined.toLowerCase().includes(filter)) continue
+          matched++
+
+          const type = String(node?.type || 'node').toLowerCase()
+          const handlers = Array.isArray(node?.handlers) ? node.handlers : []
+          const parts = []
+          if (role) parts.push('[' + role + ']')
+          else if (handlers.length > 0) parts.push('[tap]')
+          else parts.push('<' + type + '>')
+          const visibleText = clipForDisplay(text, 50)
+          if (visibleText) parts.push(JSON.stringify(visibleText))
+          if (testID) parts.push('#' + testID)
+          if (label && label !== text) {
+            parts.push('label=' + JSON.stringify(clipForDisplay(label, 50)))
+          }
+          if (!opts.hideXy) {
+            const abs = node?.absolute || {}
+            const layout = node?.layout || {}
+            const x = Math.round(Number(abs.x) || 0)
+            const y = Math.round(Number(abs.y) || 0)
+            const w = Math.round(Number(layout.width) || 0)
+            const h = Math.round(Number(layout.height) || 0)
+            parts.push('@(' + x + ',' + y + ') ' + w + 'x' + h)
+          }
+          if (handlers.length > 0) parts.push('(tap)')
+          lines.push('  ' + parts.join(' '))
+        }
+        return { tree: lines.join('\\n'), matched }
+      }
+
+      let tree = ''
+      const compactResult = needsRecursiveDump ? null : await formatInspectableTree()
+      if (compactResult) {
+        tree = compactResult.tree
+      } else {
+        tree = await t.dumpTree(${dumpDepth}, opts)
+      }
+      const nodeCount = (await t.getNodeCount?.()) || 0
+      const keyboard = kb && typeof kb.getLayout === 'function' ? kb.getLayout() : null
+      return { tree, shell, nodeCount, keyboard }
+    })()`;
+  const result = await bridge.send({ type: "evaluate", code });
+  return result ?? {};
+}
+function scoreLayoutTextContrast(input) {
+  const required = 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) => {
+    const channel = value / 255;
+    return channel <= 0.04045 ? channel / 12.92 : Math.pow((channel + 0.055) / 1.055, 2.4);
+  };
+  const ratioOf = (foreground, behind) => {
+    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) => `#${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 / 12e3)));
+  const offsetAt = (x, y) => (y * normal.width + x) * 4;
+  const deltaAt = (offset) => 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 = null;
+  let opaqueBackground = 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]
+      ];
     }
-    out.push(entry);
   }
-  if (!opts.showInternal) {
-    out = out.filter((e) => {
-      const first = e.args[0];
-      return !(typeof first === "string" && first.startsWith("[rnx]"));
-    });
+  let bestRatio = Infinity;
+  let bestForeground = null;
+  let bestBackground = null;
+  const consider = (foreground, behind) => {
+    const ratio = ratioOf(foreground, behind);
+    if (ratio >= bestRatio) return;
+    bestRatio = ratio;
+    bestForeground = foreground;
+    bestBackground = behind;
+  };
+  if (strongestDelta >= 2 && strongestForeground) {
+    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) {
+    consider(opaqueBackground, opaqueBackground);
   }
-  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));
+  if (!bestForeground || !bestBackground || !Number.isFinite(bestRatio)) {
+    return {
+      ratio: null,
+      required,
+      reason: "could not isolate opaque rendered text pixels"
+    };
   }
-  return out;
+  return {
+    ratio: Math.round(bestRatio * 100) / 100,
+    required,
+    foreground: hex(bestForeground),
+    background: hex(bestBackground)
+  };
+}
+function layoutGetNativeEval(opts = {}) {
+  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 \u2014 omit boring defaults so the agent only sees notable
+      // styling (low opacity, struck text, clipping, a real border/color).
+      const colorStr = (v) => {
+        if (v == null) return undefined
+        const s = String(v).split(' ').join('')
+        return s && s !== 'transparent' && s !== 'rgba(0,0,0,0)' ? s : undefined
+      }
+      const opacityOf = (style) => {
+        const o = style && style.opacity
+        const n = typeof o === 'number' ? o : (typeof o === 'string' ? parseFloat(o) : NaN)
+        return Number.isFinite(n) && n < 1 ? Math.round(n * 100) / 100 : undefined
+      }
+      const weightOf = (style) => {
+        const w = style && style.fontWeight
+        const n = w === 'bold' ? 700 : (typeof w === 'number' ? w : (typeof w === 'string' ? parseInt(w, 10) : NaN))
+        return Number.isFinite(n) && n >= 600 ? n : undefined
+      }
+      const decoOf = (style) => {
+        const d = style && (style.textDecorationLine || style.textDecoration)
+        return d && d !== 'none' && d !== 'normal' ? String(d).split(' ')[0] : undefined
+      }
+      const overflowOf = (style) => (style && style.overflow === 'hidden' ? 'hidden' : undefined)
+      const borderWOf = (style) => {
+        if (!style) return undefined
+        const keys = ['borderWidth','borderTopWidth','borderBottomWidth','borderLeftWidth','borderRightWidth']
+        let max = 0
+        for (const k of keys) {
+          const r = style[k]
+          const n = typeof r === 'number' ? r : (typeof r === 'string' ? parseFloat(r) : NaN)
+          if (Number.isFinite(n)) max = Math.max(max, n)
+        }
+        return max > 0 ? Math.round(max) : undefined
+      }
+      // only meaningful alongside a real border width, so it is resolved by the
+      // caller below rather than on its own.
+      const borderColorOf = (style) => {
+        if (!style) return undefined
+        const keys = ['borderColor','borderTopColor','borderBottomColor','borderLeftColor','borderRightColor']
+        for (const k of keys) {
+          const c = colorStr(style[k])
+          if (c) return c
+        }
+        return undefined
+      }
+
+      const isVisible = (n) => {
+        const layout = n && n.layout
+        if (!layout || layout.width <= 0 || layout.height <= 0) return false
+        const abs = (n && (n.absolute || n.absolutePosition)) || null
+        if (!abs) return true
+        const device = (n && n.device) || {}
+        const screenW = Number(device.width) || window.innerWidth || 0
+        const screenH = Number(device.height) || window.innerHeight || 0
+        if (!screenW || !screenH) return true
+        return abs.x + layout.width > 0 && abs.y + layout.height > 0 && abs.x < screenW && abs.y < screenH
+      }
+
+      const elements = list.filter(isVisible).filter((n) => {
+        const t = typeof n.text === 'string' && n.text.trim() ? n.text.trim() : undefined
+        return matchesFilter(n, t)
+      }).map((n) => {
+        const layout = n.layout || { x: 0, y: 0, width: 0, height: 0 }
+        const abs = n.absolute || n.absolutePosition || { x: layout.x, y: layout.y }
+        const text = typeof n.text === 'string' && n.text.trim() ? n.text.trim() : undefined
+        const base = {
+          ...(typeof n.nodeId === 'number'
+            ? {
+                nodeId: n.nodeId,
+                ancestorIds: Array.isArray(n.ancestors)
+                  ? n.ancestors.map((ancestor) => ancestor && ancestor.nodeId).filter((id) => typeof id === 'number')
+                  : [],
+              }
+            : {}),
+          testID: n.testID || n.testId || undefined,
+          role: n.accessibilityRole || n.role || undefined,
+          type: typeof n.type === 'string' ? n.type : 'node',
+          text,
+          box: { x: round(abs.x), y: round(abs.y), w: round(layout.width), h: round(layout.height) },
+          borderRadius: 0,
+          padding: { t: 0, r: 0, b: 0, l: 0 },
+          fontSize: 0,
+        }
+        if (!includeStyle) return base
+        // computedStyle has the resolved values; style is the curated subset \u2014
+        // 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
+    })()`;
 }
-async function inspectTimelineSummary(bridge, query) {
-  return await bridge.send({
-    type: "call",
-    path: "SootSim.bridges.timeline.summary",
-    args: [query]
+var LAYOUT_GET_NATIVE_EVAL = layoutGetNativeEval();
+async function inspectGetLayout(bridge, opts = {}) {
+  const raw = await bridge.send({
+    type: "evaluate",
+    code: layoutGetNativeEval(opts)
   });
+  return Array.isArray(raw) ? raw : [];
 }
-async function inspectTimelineRecent(bridge, query) {
-  return await bridge.send({
-    type: "call",
-    path: "SootSim.bridges.timeline.recent",
-    args: [query]
+function formatLayoutElements(elements, opts) {
+  if (elements.length === 0) return "  no visible elements found";
+  const lines = elements.map((el) => {
+    const ident = el.testID ? `#${el.testID}` : el.selector ? el.selector : el.role ? `[${el.role}]` : `<${el.type}>`;
+    const parts = [ident, `@(${el.box.x},${el.box.y})`, `${el.box.w}x${el.box.h}`];
+    if (el.borderRadius > 0) parts.push(`radius:${el.borderRadius}`);
+    const p = el.padding;
+    if (p.t || p.r || p.b || p.l) {
+      const uniform = p.t === p.r && p.r === p.b && p.b === p.l;
+      parts.push(uniform ? `pad:${p.t}` : `pad:${p.t},${p.r},${p.b},${p.l}`);
+    }
+    if (el.fontSize > 0) parts.push(`font:${el.fontSize}`);
+    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)}\u2026` : el.text;
+      parts.push(`"${text}"`);
+    }
+    return `  ${parts.join(" ")}`;
   });
+  return lines.join("\n");
 }
-async function detectOpenNativeUI(bridge) {
-  let events;
-  try {
-    const res = await inspectTimelineRecent(bridge, {
-      kinds: ["alert", "actionsheet"],
-      limit: 80
-    });
-    events = res.events;
-  } catch {
-    return [];
-  }
-  const latest = /* @__PURE__ */ new Map();
-  for (const ev of events) latest.set(ev.kind, ev);
-  const out = [];
-  const check = (kind, label) => {
-    const ev = latest.get(kind);
-    if (!ev || !ev.data || typeof ev.data !== "object") return;
-    const d = ev.data;
-    if (d.phase !== "show") return;
-    out.push({ label, title: typeof d.title === "string" ? d.title : null });
-  };
-  check("alert", "Alert");
-  check("actionsheet", "ActionSheet");
-  return out;
-}
-async function inspectTimelineAdvanceCursor(bridge, cursorKey, watermark) {
-  await bridge.send({
-    type: "call",
-    path: "SootSim.bridges.timeline.cursorAdvance",
-    args: [cursorKey, watermark]
-  });
+var 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)
+    })()`;
+async function inspectAccessibilityTree(bridge) {
+  const nodes = await bridge.send({ type: "evaluate", code: INSPECT_A11Y_CODE });
+  return Array.isArray(nodes) ? nodes : [];
 }
-async function inspectKeyboard(bridge) {
-  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' }
+var 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,
+          }
+        })
       }
-      return kb.getLayout()
+      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
+        )
+      }
+`;
+function resolveFindMode(q) {
+  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 result ?? { error: "keyboard bridge returned no result" };
-}
-function isShellCommandUnavailable(error) {
-  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");
-}
-async function getShellState(bridge, readyTimeoutMs = 0) {
-  const deadline = Date.now() + Math.max(0, readyTimeoutMs);
-  while (true) {
-    try {
-      return await bridge.send({
-        type: "call",
-        path: "SootSim.bridges.mainShell.getState",
-        args: []
-      });
-    } catch (error) {
-      if (!isShellCommandUnavailable(error) || Date.now() >= deadline) throw error;
-      await new Promise((r) => setTimeout(r, 50));
-    }
+    };
   }
-}
-async function inspectScreens(bridge) {
-  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 }
+  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 })
     })()`
-  });
-  const shell = await getShellState(bridge, 500).catch(() => null);
-  return {
-    shell,
-    nav: payload?.nav ?? null,
-    route: payload?.route ?? null,
-    keyboard: payload?.keyboard ?? null
-  };
-}
-var DEBUG_CHANNELS = [
-  "portals",
-  "sheets",
-  "layout",
-  "onlayout",
-  "animated",
-  "render",
-  "touch",
-  "yoga"
-];
-async function inspectDebugStatus(bridge) {
-  return bridge.send({ type: "evaluate", code: "window.__sootsimDebug.status()" });
-}
-async function inspectDebugFlags(bridge) {
-  return bridge.send({ type: "evaluate", code: "window.__sootsimDebug.flags()" });
-}
-async function inspectDebugFind(bridge, target) {
-  return bridge.send({
-    type: "evaluate",
-    code: `window.__sootsimTest.debugFind(${JSON.stringify(target)})`
-  });
-}
-async function inspectDebugRecent(bridge, channel, limit = 50) {
-  const code = channel && channel !== "all" ? `window.__sootsimDebug.recent(${JSON.stringify(channel)}, ${limit})` : `window.__sootsimDebug.recent(undefined, ${limit})`;
-  return bridge.send({ type: "evaluate", code });
-}
-async function setDebugChannels(bridge, action, channels) {
-  const args = channels.length > 0 ? channels.map((c) => JSON.stringify(c)).join(", ") : action === "disable" ? "'all'" : "";
-  return bridge.send({
-    type: "evaluate",
-    code: `window.__sootsimDebug.${action}(${args})`
-  });
-}
-async function inspectMemory(bridge) {
-  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,
+    };
+  }
+  if (q.type) {
+    return {
+      mode: "type",
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return []
+      return await t.queryAll({ type: ${JSON.stringify(q.type)}, pruneHidden: true })
+    })()`
+    };
+  }
+  if (q.pressable) {
+    return {
+      mode: "pressable",
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return []
+${FIND_INSPECTABLE_TARGETS}
+      const inspectable = await fromInspectable()
+      if (inspectable) return inspectable.filter(n => n.pressable && isVisibleTarget(n))
+      const all = await t.queryAll({ pruneHidden: true })
+      return all.filter(n => n.pressable && isVisibleTarget(n))
+    })()`
+    };
+  }
+  if (q.interactive) {
+    return {
+      mode: "interactive-targets",
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return []
+${FIND_INSPECTABLE_TARGETS}
+      const inspectable = await fromInspectable()
+      if (inspectable) {
+        return inspectable.filter(n => n.pressable && isVisibleTarget(n))
       }
+      const all = await t.queryAll({ pruneHidden: true })
+      return all.filter(n => n.pressable && isVisibleTarget(n))
     })()`
-  });
-  return result ?? { tenant: null, shell: null, compositor: null, hostHeap: null };
-}
-function formatTimelineSummary(summary) {
-  if (summary.total === 0) return "nothing recorded";
-  const parts = [];
-  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 = /* @__PURE__ */ new Set();
-  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"}`);
+  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 parts.join(" \xB7 ");
+  if (q.text) {
+    return {
+      mode: "text",
+      code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return null
+      return await t.findByText(${JSON.stringify(q.text)})
+    })()`
+    };
+  }
+  return null;
 }
-var NOISY_TIMELINE_KINDS = /* @__PURE__ */ new Set([
-  "react-commit",
-  "layout",
-  "scroll"
-]);
-function formatTimelineRelativeTime(t, anchor) {
-  if (anchor === null) return new Date(t).toLocaleTimeString();
-  const dt = (t - anchor) / 1e3;
-  const sign = dt >= 0 ? "+" : "";
-  return `${sign}${dt.toFixed(2)}s`;
+async function inspectFind(bridge, q) {
+  const resolved = resolveFindMode(q);
+  if (!resolved) return null;
+  const result = await bridge.send({ type: "evaluate", code: resolved.code });
+  return { mode: resolved.mode, result };
 }
-function formatTimelinePayload(kind, d) {
-  switch (kind) {
-    case "app-launch":
-      return d.phase === "launch" ? `launch ${d.appName ?? d.toAppId ?? ""}` : `dismiss ${d.appName ?? d.fromAppId ?? ""} \u2192 ${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 ? ` \u2014 ${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 !== void 0 ? ` "${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;
-      return `${d.fiberCount ?? "?"} fibers ${d.durationMs ?? "?"}ms${slowest?.displayName ? ` \xB7 ${slowest.displayName} ${slowest.durationMs ?? "?"}ms` : ""}`;
-    }
-    case "frame":
-      return `${d.totalMs ?? "?"}ms${d.renderMs ? ` \xB7 render ${d.renderMs}ms` : ""}${d.layoutMs ? ` \xB7 layout ${d.layoutMs}ms` : ""}${d.copyMs ? ` \xB7 copy ${d.copyMs}ms` : ""}`;
-    case "reanimated":
-    case "animation":
-      return `${d.kind ?? ""} ${d.target ?? ""}${d.durationMs ? ` ${d.durationMs}ms` : ""}`;
+function rankInteractive(nodes) {
+  return [...nodes].sort((a, b) => scoreInteractive(b) - scoreInteractive(a));
+}
+function scoreInteractive(n) {
+  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;
   }
-  return "";
+  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 <= 6e4) score += 25;
+  else if (area > 6e4) score -= 20;
+  const y = n.absolutePosition?.y ?? 0;
+  if (y < 0) score -= 30;
+  return score;
 }
-function formatTimelineEvent(event, anchor) {
-  const ts = formatTimelineRelativeTime(event.t, anchor).padStart(8);
-  const ctx = event.context.padEnd(6);
-  const kind = `[${event.kind}]`.padEnd(15);
-  const d = event.data;
-  const payload = d && typeof d === "object" ? formatTimelinePayload(event.kind, d) : "";
-  return `  ${ts}  ${ctx}  ${kind} ${payload}`;
+function tapCommandForNode(n) {
+  if (n.testID) return `rnxsim do tap-id ${shellEscape(n.testID)}`;
+  const text = typeof n.text === "string" ? n.text.trim() : "";
+  if (text.length > 0 && text.length <= 80)
+    return `rnxsim do tap-text ${shellEscape(text)}`;
+  const x = Math.round(((n.absolutePosition?.x ?? 0) + (n.layout?.width ?? 0) / 2) * 10) / 10;
+  const y = Math.round(((n.absolutePosition?.y ?? 0) + (n.layout?.height ?? 0) / 2) * 10) / 10;
+  return `rnxsim do tap ${x} ${y}`;
 }
-function formatTimelineEvents(events) {
-  if (!events.length) return "";
-  const anchor = events[0]?.t ?? null;
-  return events.map((e) => formatTimelineEvent(e, anchor)).join("\n");
+function shellEscape(value) {
+  if (/^[A-Za-z0-9_./@:-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-
-// cli/commands/inspect/settling.ts
-async function waitForSootsimIdle({
-  bridge,
-  simId,
-  maxMs,
-  pollMs = 50,
-  stablePolls = 3,
-  strict = false
-}) {
-  const result = await bridge.send(
-    {
-      type: "evaluate",
-      simId,
-      code: `(async () => {
-      const start = Date.now()
-      const deadline = start + ${Math.max(0, Math.round(maxMs))}
-      const pollMs = ${Math.max(1, Math.round(pollMs))}
-      const requiredStablePolls = ${Math.max(1, Math.round(stablePolls))}
-      const strict = ${strict ? "true" : "false"}
-      const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
-
-      // route-aware settle: a tap that pushes/pops a screen is async \u2014 the
-      // old screen still renders for a moment, then the new one mounts and
-      // its content loads. a pure layout-hash check reports "idle" on the
-      // outgoing screen or on the incoming skeleton, so a driver re-taps
-      // and stacks duplicate navigations. drain any in-flight screen
-      // transition FIRST, bounded by the overall budget. when no
-      // transition is happening this returns in ~80ms (startWindowMs), so
-      // a plain button tap barely pays for it.
-      try {
-        const wfst = window.__sootsimTest?.waitForScreenTransitions
-        if (typeof wfst === 'function') {
-          const remaining = deadline - Date.now()
-          if (remaining > 120) {
-            await wfst({
-              timeoutMs: Math.min(remaining - 80, 4000),
-              settleMs: 64,
-              startWindowMs: 80,
-            })
-          }
-        }
-      } catch {}
-
-      const readSnapshot = async () => {
-        let animating = false
-        let pendingFetches = 0
-        let requestTotal = 0
-        let requestInFlight = 0
-        try {
-          const stats = await window.__sootsimRenderHost?.queryStats?.()
-          if (stats) {
-            animating =
-              stats.hasActiveAnims === true ||
-              stats.hasActiveNativeAnimations === true ||
-              stats.hasPendingAnimationFrames === true
-            // a freshly-pushed screen showing a skeleton is layout-stable
-            // but not actually settled \u2014 its data/images are still in
-            // flight. treat bounded image-loader fetches as not-idle so
-            // settle waits for real content, capped by the budget.
-            const pf = stats.memory && stats.memory.imageLoader
-              ? stats.memory.imageLoader.pendingFetches
-              : 0
-            pendingFetches = typeof pf === 'number' ? pf : 0
-          }
-        } catch {}
-        try {
-          const counts = await window.__sootsimTest?.getRequestCounts?.()
-          requestTotal = typeof counts?.total === 'number' ? counts.total : 0
-          requestInFlight = typeof counts?.inFlight === 'number' ? counts.inFlight : 0
-        } catch {}
-        const root = window.__sootsimRoot
-        const nodes = []
-        if (root) {
-          const walk = (n) => {
-            if (n.layout && n.layout.width > 0) {
-              nodes.push(Math.round(n.layout.x) + ',' + Math.round(n.layout.y) + ',' + Math.round(n.layout.width))
-            }
-            for (const c of n.children || []) walk(c)
-          }
-          walk(root)
-        }
-        return { layout: nodes.join(';'), animating, pendingFetches, requestTotal, requestInFlight }
+var WAIT_READY_PROBE = `(async () => {
+    const t = window.__sootsimTest
+    let nodes = 0
+    try { nodes = (await t?.getNodeCount?.()) || 0 } catch {}
+    let targets = 0
+    let liveFrameActive = false
+    let liveFrameChannels = 0
+    let liveFramePublishes = 0
+    let loadingText = ''
+    const cleanText = (value) =>
+      typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''
+    const loadingSignal = (value) => {
+      const text = cleanText(value)
+      if (!text) return ''
+      return /^(opening app\\b|looking for your app\\b|building bundle\\b|preparing rnxsim runtime\\b|loading native bundle\\b|loading rnx stubs\\b|loading bundle loader\\b|loading native stubs\\b|loading compat bridge\\b|loading react-native shim\\b|loading react bridge\\b|loading reconciler\\b|loading replacement modules\\b|injecting rnx modules\\b|warming sqlite engine\\b|capturing root component\\b|reloading app\\b|loading(?:[.!\u2026]*)?$|connecting(?:[.!\u2026]*)?$)/i.test(text)
+        ? text
+        : ''
+    }
+    try {
+      const loading = window.__sootsimConnectRNLoading
+      if (loading && loading.active === true) {
+        loadingText = [loading.title, loading.detail].map(cleanText).filter(Boolean).join(' ')
       }
-
-      // how long generic background network is allowed to keep us waiting AFTER
-      // the screen is otherwise visually settled. apps with continuous traffic
-      // (polling, realtime sockets, a tap that fires 20-50 fetches) never reach
-      // requestInFlight===0 / a stable requestTotal, so requiring full network
-      // quiet burns the ENTIRE budget on every command \u2014 the leading idle that
-      // failed PR-preview recordings for network-heavy apps (3pc fight-pulse).
-      // layout-stability + the image-loader already prove visible content
-      // loaded (a data load changes layout; an image load shows in the loader),
-      // so the generic request counters are a courtesy, not a gate: honor them
-      // only within this grace once the screen is visually still.
-      const networkQuietGraceMs = 1200
-      let lastLayout = ''
-      let lastRequestTotal = -1
-      let stable = 0
-      let visuallyStillSince = 0
-      while (Date.now() < deadline) {
-        const snapshot = await readSnapshot()
-        const strictOk = !strict || !snapshot.animating
-        // visually settled: no animations, no image content loading, layout
-        // unchanged since the last poll.
-        const visuallyStill =
-          strictOk && snapshot.pendingFetches === 0 && snapshot.layout === lastLayout
-        // generic network quiet: nothing in flight and no new requests issued.
-        const networkQuiet =
-          snapshot.requestInFlight === 0 && snapshot.requestTotal === lastRequestTotal
-        if (visuallyStill) {
-          stable++
-          if (visuallyStillSince === 0) visuallyStillSince = Date.now()
-          // settle once the screen has held still long enough AND either the
-          // network is genuinely quiet OR it has refused to quiet within the
-          // grace (continuous background traffic must not block forever).
-          if (
-            stable >= requiredStablePolls &&
-            (networkQuiet || Date.now() - visuallyStillSince >= networkQuietGraceMs)
-          ) {
-            return { settled: true, elapsed: Date.now() - start }
+    } 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
           }
-        } else {
-          stable = 0
-          visuallyStillSince = 0
+          targets = list.filter(n => isVisible(n) && hasContentSignal(n)).length
         }
-        lastLayout = snapshot.layout
-        lastRequestTotal = snapshot.requestTotal
-        await sleep(pollMs)
       }
-      return { settled: false, elapsed: Date.now() - start }
-    })()`
-    },
-    {
-      timeoutMs: maxMs + 1e3
+    } 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 \u2014 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 \u2014 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,
     }
-  );
-  const { elapsed, settled } = result ?? {};
-  return {
-    elapsed: typeof elapsed === "number" ? elapsed : maxMs,
-    settled: settled === true
-  };
+  })()`;
+var READY_CONTENT_NODE_FLOOR = 100;
+var READY_NODE_STABLE_MS = 750;
+var WAIT_READY_PROGRESS_INTERVAL_MS = 2e3;
+var READY_PROBE_POLL_MS = 150;
+function readyProbeHasContent(probe) {
+  return probe.liveFrameActive || probe.targets > 0 || probe.nodes >= READY_CONTENT_NODE_FLOOR;
 }
-
-// cli/commands/inspect/actions.ts
-var SCREEN_EVAL = `(() => {
-  const spec = window.SootSim?.state?.engineSnapshot?.windowState?.deviceSpec
-  return spec && spec.width > 0 && spec.height > 0
-    ? { width: spec.width, height: spec.height }
-    : null
-})()`;
-var DEFAULT_AGENT_TIMING = {
-  initialWaitMs: 3e3,
-  deadlineMs: 5e3,
-  retryWaitMs: 700
-};
-var DEFAULT_INTERACTIVE_TIMING = {
-  initialWaitMs: 1200,
-  deadlineMs: 2500,
-  retryWaitMs: 700
-};
-function tapTiming(agent, opts = {}) {
-  return {
-    ...agent ? DEFAULT_AGENT_TIMING : DEFAULT_INTERACTIVE_TIMING,
-    ...opts
-  };
+function readyProbeHasTargetContent(probe) {
+  return probe.liveFrameActive || probe.targets > 0;
 }
-function isTapSuccess(result) {
-  if (!result || result.hit === false || result.ok === false) return false;
-  if (result.requestedTargetMatched === false) return false;
-  if (result.pointerTapHandled === false && !result.keyboardOpened && !result.isTextInput) {
-    return false;
+function waitReadyReason(status) {
+  if (status.bridgeError) {
+    return `sim unreachable: ${status.bridgeError} \u2014 the target tab is closed or no sim is connected (check \`rnxsim list\`, reopen with \`rnxsim open\`)`;
   }
-  return true;
+  const base = status.externalError ? `guest app errored: ${status.externalError}` : status.loadingText ? `still showing "${status.loadingText}"` : status.externalReady === false ? "guest app is still loading" : status.flag !== true && status.targets > 0 ? "native content is rendered but the ready signal has not settled" : status.flag !== true ? "guest app has not emitted sootsim:externalAppReady" : status.targets <= 0 ? "ready flag emitted but no visible app content is inspectable yet" : "node tree is still changing";
+  return !status.externalError && status.suppressedEntryError ? `${base} (suppressed entry error: ${status.suppressedEntryError})` : base;
 }
-function tapTargetFromPayload(payload, textFallback) {
-  return {
-    nodeId: payload.target?.nodeId ?? payload.match?.nodeId ?? payload.node?.nodeId ?? null,
-    id: payload.target?.id ?? payload.match?.id ?? payload.node?.id ?? null,
-    testID: payload.target?.testID ?? payload.match?.testID ?? payload.node?.testID ?? null,
-    text: payload.target?.text ?? payload.target?.accessibilityLabel ?? payload.match?.text ?? payload.match?.accessibilityLabel ?? payload.node?.text ?? textFallback ?? null,
-    type: payload.target?.type ?? payload.match?.type ?? payload.node?.type ?? null
+async function inspectWaitReady(bridge, timeoutMs = 2e4, options = {}) {
+  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;
+  let bridgeError = "";
+  let last = {
+    flag: void 0,
+    at: 0,
+    nodes: 0,
+    targets: 0,
+    liveFrameActive: false,
+    liveFrameChannels: 0,
+    liveFramePublishes: 0,
+    errors: 0,
+    loadingText: "",
+    externalReady: null,
+    externalStatus: "",
+    externalError: "",
+    suppressedEntryError: ""
   };
-}
-async function tapResolvedTarget(bridge, args) {
-  const timing = tapTiming(!!args.agent, args.timing);
-  let attempts = 0;
-  let lastPayload = null;
-  let lastResult = null;
-  try {
-    await waitForSootsimIdle({
-      bridge,
-      maxMs: timing.initialWaitMs,
-      pollMs: 32,
-      stablePolls: 2
-    });
-  } catch {
+  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);
+      if (bridgeError.startsWith("multiple sims are connected:") || bridgeError.startsWith("saved sim ")) {
+        throw error;
+      }
+    }
+    const now = Date.now();
+    const status2 = {
+      ready: false,
+      elapsedMs: now - start,
+      nodes: last.nodes,
+      targets: last.targets,
+      liveFrameActive: last.liveFrameActive,
+      liveFrameChannels: last.liveFrameChannels,
+      liveFramePublishes: last.liveFramePublishes,
+      flag: last.flag,
+      loadingText: last.loadingText,
+      externalReady: last.externalReady,
+      externalStatus: last.externalStatus,
+      externalError: last.externalError,
+      suppressedEntryError: last.suppressedEntryError,
+      errors: last.errors,
+      bridgeError
+    };
+    if (last.nodes !== lastNodes) {
+      lastNodes = last.nodes;
+      nodeStableSince = now;
+    }
+    const hasReadySignal = last.flag === true && readyProbeHasContent(last);
+    const hasRenderedContentWithoutReadySignal = last.flag !== true && readyProbeHasTargetContent(last);
+    if ((hasReadySignal || hasRenderedContentWithoutReadySignal) && last.externalReady !== false && !last.externalError && !last.loadingText) {
+      if (now - nodeStableSince >= READY_NODE_STABLE_MS) {
+        return {
+          ...status2,
+          ready: true
+        };
+      }
+    }
+    if (last.externalError) return status2;
+    if (options.onProgress && progressIntervalMs > 0 && now >= nextProgressAt) {
+      options.onProgress(status2);
+      do {
+        nextProgressAt += progressIntervalMs;
+      } while (now >= nextProgressAt);
+    }
+    await new Promise((r) => setTimeout(r, READY_PROBE_POLL_MS));
+  }
+  const status = {
+    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);
   }
-  const deadline = Date.now() + timing.deadlineMs;
-  let lastOffscreenAt = null;
-  while (Date.now() <= deadline || attempts === 0) {
-    attempts++;
-    const payload = await args.resolve();
-    lastPayload = payload;
-    if (payload?.error === "bridge-not-ready" || payload?.ambiguous || payload?.nthOutOfRange) {
-      return { payload, result: null, attempts, failure: "special" };
-    }
-    if (payload && typeof payload.cx === "number" && typeof payload.cy === "number") {
-      if (payload.offscreen) {
-        lastResult = {
-          hit: false,
-          reason: "offscreen",
-          x: payload.cx,
-          y: payload.cy,
-          screen: payload.screen
-        };
-        const at = `${Math.round(payload.cx)},${Math.round(payload.cy)}`;
-        if (lastOffscreenAt === at) {
-          return { payload, result: lastResult, attempts, failure: "missed" };
-        }
-        lastOffscreenAt = at;
-      } else {
-        lastOffscreenAt = null;
-        const requestedTarget = tapTargetFromPayload(payload, args.textFallback);
-        const verification = await bridge.send({
-          type: "evaluate",
-          code: `(async () => {
-            const t = window.__sootsimTest
-            if (
-              !t ||
-              typeof t.inspectAt !== 'function' ||
-              typeof t.resolveTapTarget !== 'function'
-            ) {
-              return { error: 'tap-target-inspection-unavailable' }
-            }
-            const requestedTarget = ${JSON.stringify(requestedTarget)}
-            const inspected = await t.inspectAt(${payload.cx}, ${payload.cy})
-            const resolved =
-              inspected && typeof inspected.nodeId === 'number'
-                ? await t.resolveTapTarget(inspected.nodeId)
-                : null
-            const node = (resolved && resolved.target) || inspected
-            const coordinateTarget = node
-              ? {
-                  nodeId: node.nodeId ?? null,
-                  id: node.id ?? null,
-                  testID: node.testID ?? null,
-                  text: node.text ?? node.accessibilityLabel ?? null,
-                  type: node.type ?? null,
-                }
-              : null
-            const coordinateAncestors = Array.isArray(inspected?.ancestors)
-              ? inspected.ancestors
-              : []
-            const ancestorMatchesRequested = coordinateAncestors.some(
-              (ancestor) =>
-                (typeof requestedTarget.nodeId === 'number' &&
-                  ancestor?.nodeId === requestedTarget.nodeId) ||
-                (requestedTarget.testID &&
-                  ancestor?.testID === requestedTarget.testID) ||
-                (requestedTarget.id && ancestor?.id === requestedTarget.id),
-            )
-            const requestedTargetMatched =
-              coordinateTarget === null
-                ? false
-                : typeof requestedTarget.nodeId === 'number' &&
-                    typeof coordinateTarget.nodeId === 'number'
-                  ? requestedTarget.nodeId === coordinateTarget.nodeId ||
-                    ancestorMatchesRequested
-                  : requestedTarget.testID && coordinateTarget.testID
-                    ? requestedTarget.testID === coordinateTarget.testID
-                      || ancestorMatchesRequested
-                    : requestedTarget.id && coordinateTarget.id
-                      ? requestedTarget.id === coordinateTarget.id
-                        || ancestorMatchesRequested
-                      : ancestorMatchesRequested
-            if (!requestedTargetMatched) {
-              return {
-                requestedTargetMatched,
-                requestedTarget,
-                coordinateTarget,
-              }
-            }
-            if (typeof t.activatePressAt !== 'function') {
-              return { error: 'tap-target-activation-unavailable' }
-            }
-            const activation = await t.activatePressAt(
-              ${payload.cx},
-              ${payload.cy},
-              requestedTarget.nodeId,
-            )
-            if (activation?.ok) {
-              window.dispatchEvent(
-                new CustomEvent('sootsim:agentAction', {
-                  detail: {
-                    type: 'tap',
-                    x: ${payload.cx},
-                    y: ${payload.cy},
-                    target: requestedTarget,
-                  },
-                }),
-              )
-            }
-            return {
-              activation,
-              requestedTargetMatched,
-              requestedTarget,
-              coordinateTarget,
-            }
-          })()`
-        });
-        if (verification?.error) {
-          return {
-            payload,
-            result: {
-              hit: false,
-              reason: verification.error,
-              requestedTarget
-            },
-            attempts,
-            failure: "special"
-          };
+  return status;
+}
+async function inspectWaitSelector(bridge, testId, timeoutMs = 5e3, opts = {}) {
+  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 \u2014 indeterminate, not "gone"
+        try {
+          // gone-mode confirms a gate/screen LEFT \u2014 it only needs structural
+          // existence + layout, NOT the full-tree occlusion pass (pruneHidden).
+          // that pass (computeOccludedInspectNodeIds) walks the whole tree and
+          // does O(n\xB2)-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 \u2014 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
         }
-        if (verification?.requestedTargetMatched === false) {
-          return {
-            payload,
-            result: {
-              hit: false,
-              reason: "target-covered",
-              ...verification
-            },
-            attempts,
-            failure: "missed"
-          };
+      }
+      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 }
         }
-        const dispatched = verification?.activation?.tap ?? verification?.activation;
-        const result = dispatched && typeof dispatched === "object" ? { ...dispatched, ...verification?.activation, ...verification } : { hit: !!dispatched, ...verification };
-        lastResult = result;
-        if (isTapSuccess(result)) return { payload, result, attempts };
+        await new Promise((r) => setTimeout(r, 80))
       }
+      return { found: false, elapsed: Date.now() - start }
+    })()`
+    },
+    {
+      timeoutMs: timeoutMs + 1e3
     }
-    const remaining = deadline - Date.now();
-    if (remaining <= 0) break;
+  );
+  return result ?? { found: false, elapsed: timeoutMs };
+}
+function consoleEntriesEval(level, limit) {
+  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 \u2014 the always-on render-worker / forwarded path
     try {
-      await waitForSootsimIdle({
-        bridge,
-        maxMs: Math.min(remaining, timing.retryWaitMs),
-        pollMs: 32,
-        stablePolls: 2
-      });
-    } catch {
-      await new Promise((resolve) => setTimeout(resolve, Math.min(120, remaining)));
+      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})
+  })()`;
+}
+async function inspectErrors(bridge, limit = 20) {
+  const result = await bridge.send({
+    type: "evaluate",
+    code: consoleEntriesEval("error", limit)
+  });
+  return Array.isArray(result) ? result : [];
+}
+async function inspectWarnings(bridge, limit = 20) {
+  const result = await bridge.send({
+    type: "evaluate",
+    code: consoleEntriesEval("warn", limit)
+  });
+  return Array.isArray(result) ? result : [];
+}
+var 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 }
+  })()`;
+async function clearConsole(bridge) {
+  await bridge.send({
+    type: "evaluate",
+    code: 'window.__sootsimConsole?.clear(); window.__sootsimObservability?.logs?.clear?.(); "cleared"'
+  });
+}
+async function inspectRequests(bridge, opts = {}) {
+  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 : [];
+}
+async function clearRequests(bridge) {
+  await bridge.send({ type: "call", path: "__sootsimTest.clearRequests", args: [] });
+}
+async function inspectScrollStateAt(bridge, x, y) {
+  const result = await bridge.send({
+    type: "call",
+    path: "__sootsimTest.getScrollStateAt",
+    args: [x, y]
+  });
+  if (!result || typeof result !== "object") return null;
+  const state = result;
   return {
-    payload: lastPayload,
-    result: lastResult,
-    attempts,
-    failure: lastPayload && typeof lastPayload.cx === "number" ? "missed" : "not-found"
+    ...state,
+    scrollOffsetX: typeof state.scrollOffsetX === "number" ? state.scrollOffsetX : state.offsetX,
+    scrollOffsetY: typeof state.scrollOffsetY === "number" ? state.scrollOffsetY : state.offsetY
   };
 }
-async function tapCoordinates(bridge, x, y, target) {
-  return bridge.send({
-    type: "tap",
-    x,
-    y,
-    ...target ? { target } : {}
+async function inspectLogs(bridge) {
+  const res = await bridge.send({
+    type: "evaluate",
+    code: `(() => {
+      const obs = window.__sootsimObservability;
+      if (!obs) return { ok: false };
+      return { ok: true, entries: obs.logs.getSnapshot() };
+    })()`
   });
+  if (!res || !res.ok) return [];
+  return res.entries ?? [];
 }
-async function tapById(bridge, query, opts = {}) {
-  const arg = JSON.stringify(query);
-  return tapResolvedTarget(bridge, {
-    agent: opts.agent,
-    timing: opts.timing,
-    resolve: () => bridge.send({
-      type: "evaluate",
-      code: `(async () => {
-          const t = window.__sootsimTest
-          if (!t) return null
-          const n = (await t.findByTestId(${arg})) || (await t.findById(${arg}))
-          if (!n || !n.absolutePosition || !n.layout) return { cx: null }
-          const resolved =
-            typeof n.nodeId === 'number' && typeof t.resolveTapTarget === 'function'
-              ? await t.resolveTapTarget(n.nodeId)
-              : null
-          const target = (resolved && resolved.target) || n
-          const cx =
-            resolved && typeof resolved.cx === 'number'
-              ? resolved.cx
-              : n.absolutePosition.x + (n.layout.width || 0) / 2
-          const cy =
-            resolved && typeof resolved.cy === 'number'
-              ? resolved.cy
-              : n.absolutePosition.y + (n.layout.height || 0) / 2
-          const scr = ${SCREEN_EVAL}
-          const offscreen =
-            !!scr && (cx < 0 || cy < 0 || cx > scr.width || cy > scr.height)
-          return {
-            cx,
-            cy,
-            ...(offscreen ? { offscreen: true, screen: scr } : {}),
-            match: {
-              nodeId: n.nodeId ?? null,
-              id: n.id,
-              testID: n.testID,
-              text: n.text ?? n.accessibilityLabel ?? null,
-              type: n.type,
-            },
-            target: {
-              nodeId: target.nodeId ?? null,
-              id: target.id,
-              testID: target.testID,
-              text:
-                target.text ??
-                target.accessibilityLabel ??
-                n.text ??
-                n.accessibilityLabel ??
-                null,
-              type: target.type,
-            },
-            strategy: (resolved && resolved.strategy) || 'matched-node',
-          }
-        })()`
-    })
+async function clearLogs(bridge) {
+  await bridge.send({
+    type: "evaluate",
+    code: 'window.__sootsimObservability?.logs.clear(); "cleared"'
   });
 }
-async function tapByText(bridge, query, options = {}, opts = {}) {
-  const filterArg = JSON.stringify({
-    query,
-    exact: !!options.exact,
-    role: options.role ?? null,
-    within: options.within ?? null,
-    minX: options.minX ?? null,
-    maxX: options.maxX ?? null,
-    minY: options.minY ?? null,
-    maxY: options.maxY ?? null,
-    near: options.near ?? null,
-    nth: options.nth ?? null,
-    first: !!options.first
+function isForwardedWorkerLogTwin(a, b) {
+  if (a.source === b.source) return false;
+  if (a.level !== b.level) return false;
+  if (Math.abs(a.ts - b.ts) > 1e3) return false;
+  if (a.args.length !== b.args.length) return false;
+  const sources = /* @__PURE__ */ 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]);
+}
+function filterLogEntries(entries, opts = {}) {
+  let out = [];
+  for (const entry of entries) {
+    if (out.some((candidate) => isForwardedWorkerLogTwin(candidate, entry))) {
+      continue;
+    }
+    out.push(entry);
+  }
+  if (!opts.showInternal) {
+    out = out.filter((e) => {
+      const first = e.args[0];
+      return !(typeof first === "string" && first.startsWith("[rnx]"));
+    });
+  }
+  if (opts.level) out = out.filter((e) => opts.level.has(e.level));
+  if (opts.filter) {
+    const lf = opts.filter.toLowerCase();
+    out = out.filter((e) => e.args.join(" ").toLowerCase().includes(lf));
+  }
+  return out;
+}
+async function inspectTimelineSummary(bridge, query) {
+  return await bridge.send({
+    type: "call",
+    path: "SootSim.bridges.timeline.summary",
+    args: [query]
   });
-  return tapResolvedTarget(bridge, {
-    agent: opts.agent,
-    timing: opts.timing,
-    textFallback: query,
-    resolve: () => bridge.send({
-      type: "evaluate",
-      code: `(async () => {
-          const t = window.__sootsimTest
-          if (!t) return { error: 'bridge-not-ready' }
-          const F = ${filterArg}
-
-          const res = await t.queryTextCandidates({
-            query: F.query,
-            exact: !!F.exact,
-            ...(F.role ? { role: F.role } : {}),
-          })
-
-          let candidates = res.candidates || []
-
-          candidates = candidates.filter((c) => {
-            const ax = c.info.absolutePosition && c.info.absolutePosition.x
-            const ay = c.info.absolutePosition && c.info.absolutePosition.y
-            if (F.minX !== null && !(ax >= F.minX)) return false
-            if (F.maxX !== null && !(ax <= F.maxX)) return false
-            if (F.minY !== null && !(ay >= F.minY)) return false
-            if (F.maxY !== null && !(ay <= F.maxY)) return false
-            if (F.within && !c.ancestorTestIDs.includes(F.within)) return false
-            return true
-          })
-
-          if (F.near) {
-            candidates.sort((a, b) => {
-              const ax = (a.info.absolutePosition && a.info.absolutePosition.x) || 0
-              const ay = (a.info.absolutePosition && a.info.absolutePosition.y) || 0
-              const bx = (b.info.absolutePosition && b.info.absolutePosition.x) || 0
-              const by = (b.info.absolutePosition && b.info.absolutePosition.y) || 0
-              return (
-                Math.hypot(ax - F.near.x, ay - F.near.y) -
-                Math.hypot(bx - F.near.x, by - F.near.y)
-              )
-            })
-          } else {
-            candidates.sort((a, b) => {
-              const ay = (a.info.absolutePosition && a.info.absolutePosition.y) || 0
-              const by = (b.info.absolutePosition && b.info.absolutePosition.y) || 0
-              if (Math.abs(ay - by) > 2) return ay - by
-              const ax = (a.info.absolutePosition && a.info.absolutePosition.x) || 0
-              const bx = (b.info.absolutePosition && b.info.absolutePosition.x) || 0
-              return ax - bx
-            })
-          }
-
-          const total = candidates.length
-          if (total === 0) return { matched: 0, total: 0 }
-
-          let idx = 0
-          if (F.nth !== null) {
-            idx = F.nth < 0 ? total + F.nth : F.nth
-            if (idx < 0 || idx >= total) {
-              return { matched: 0, total, nthOutOfRange: true, nth: F.nth }
-            }
-          } else if (total > 1 && !F.first && !F.near) {
-            return {
-              ambiguous: true,
-              total,
-              candidates: candidates.slice(0, 10).map((c, i) => ({
-                idx: i,
-                nodeId: c.info.nodeId,
-                type: c.info.type,
-                testID: c.info.testID,
-                text: (c.info.text || '').slice(0, 60),
-                abs: c.info.absolutePosition,
-                layout: c.info.layout
+}
+async function inspectTimelineRecent(bridge, query) {
+  return await bridge.send({
+    type: "call",
+    path: "SootSim.bridges.timeline.recent",
+    args: [query]
+  });
+}
+async function detectOpenNativeUI(bridge) {
+  let events;
+  try {
+    const res = await inspectTimelineRecent(bridge, {
+      kinds: ["alert", "actionsheet"],
+      limit: 80
+    });
+    events = res.events;
+  } catch {
+    return [];
+  }
+  const latest = /* @__PURE__ */ new Map();
+  for (const ev of events) latest.set(ev.kind, ev);
+  const out = [];
+  const check = (kind, label) => {
+    const ev = latest.get(kind);
+    if (!ev || !ev.data || typeof ev.data !== "object") return;
+    const d = ev.data;
+    if (d.phase !== "show") return;
+    out.push({ label, title: typeof d.title === "string" ? d.title : null });
+  };
+  check("alert", "Alert");
+  check("actionsheet", "ActionSheet");
+  return out;
+}
+async function inspectTimelineAdvanceCursor(bridge, cursorKey, watermark) {
+  await bridge.send({
+    type: "call",
+    path: "SootSim.bridges.timeline.cursorAdvance",
+    args: [cursorKey, watermark]
+  });
+}
+async function inspectKeyboard(bridge) {
+  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()
+    })()`
+  });
+  return result ?? { error: "keyboard bridge returned no result" };
+}
+function isShellCommandUnavailable(error) {
+  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");
+}
+async function getShellState(bridge, readyTimeoutMs = 0) {
+  const deadline = Date.now() + Math.max(0, readyTimeoutMs);
+  while (true) {
+    try {
+      return await bridge.send({
+        type: "call",
+        path: "SootSim.bridges.mainShell.getState",
+        args: []
+      });
+    } catch (error) {
+      if (!isShellCommandUnavailable(error) || Date.now() >= deadline) throw error;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+}
+async function inspectScreens(bridge) {
+  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
                   ? {
-                      width: Math.round(c.info.layout.width || 0),
-                      height: Math.round(c.info.layout.height || 0),
+                      keyboardType: layout.spec.keyboardType,
+                      returnKeyType: layout.spec.returnKeyType,
                     }
                   : null,
-                ancestorTestIDs: (c.ancestorTestIDs || []).slice(0, 5),
-              })),
+              } : null
+            })()
+          : null
+      return { nav: navSnap, route, keyboard }
+    })()`
+  });
+  const shell = await getShellState(bridge, 500).catch(() => null);
+  return {
+    shell,
+    nav: payload?.nav ?? null,
+    route: payload?.route ?? null,
+    keyboard: payload?.keyboard ?? null
+  };
+}
+var DEBUG_CHANNELS = [
+  "portals",
+  "sheets",
+  "layout",
+  "onlayout",
+  "animated",
+  "render",
+  "touch",
+  "yoga"
+];
+async function inspectDebugStatus(bridge) {
+  return bridge.send({ type: "evaluate", code: "window.__sootsimDebug.status()" });
+}
+async function inspectDebugFlags(bridge) {
+  return bridge.send({ type: "evaluate", code: "window.__sootsimDebug.flags()" });
+}
+async function inspectDebugFind(bridge, target) {
+  return bridge.send({
+    type: "evaluate",
+    code: `window.__sootsimTest.debugFind(${JSON.stringify(target)})`
+  });
+}
+async function inspectDebugRecent(bridge, channel, limit = 50) {
+  const code = channel && channel !== "all" ? `window.__sootsimDebug.recent(${JSON.stringify(channel)}, ${limit})` : `window.__sootsimDebug.recent(undefined, ${limit})`;
+  return bridge.send({ type: "evaluate", code });
+}
+async function setDebugChannels(bridge, action, channels) {
+  const args = channels.length > 0 ? channels.map((c) => JSON.stringify(c)).join(", ") : action === "disable" ? "'all'" : "";
+  return bridge.send({
+    type: "evaluate",
+    code: `window.__sootsimDebug.${action}(${args})`
+  });
+}
+async function inspectMemory(bridge) {
+  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,
+      }
+    })()`
+  });
+  return result ?? { tenant: null, shell: null, compositor: null, hostHeap: null };
+}
+function formatTimelineSummary(summary) {
+  if (summary.total === 0) return "nothing recorded";
+  const parts = [];
+  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 = /* @__PURE__ */ new Set();
+  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(" \xB7 ");
+}
+var NOISY_TIMELINE_KINDS = /* @__PURE__ */ new Set([
+  "react-commit",
+  "layout",
+  "scroll"
+]);
+function formatTimelineRelativeTime(t, anchor) {
+  if (anchor === null) return new Date(t).toLocaleTimeString();
+  const dt = (t - anchor) / 1e3;
+  const sign = dt >= 0 ? "+" : "";
+  return `${sign}${dt.toFixed(2)}s`;
+}
+function formatTimelinePayload(kind, d) {
+  switch (kind) {
+    case "app-launch":
+      return d.phase === "launch" ? `launch ${d.appName ?? d.toAppId ?? ""}` : `dismiss ${d.appName ?? d.fromAppId ?? ""} \u2192 ${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 ? ` \u2014 ${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 !== void 0 ? ` "${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;
+      return `${d.fiberCount ?? "?"} fibers ${d.durationMs ?? "?"}ms${slowest?.displayName ? ` \xB7 ${slowest.displayName} ${slowest.durationMs ?? "?"}ms` : ""}`;
+    }
+    case "frame":
+      return `${d.totalMs ?? "?"}ms${d.renderMs ? ` \xB7 render ${d.renderMs}ms` : ""}${d.layoutMs ? ` \xB7 layout ${d.layoutMs}ms` : ""}${d.copyMs ? ` \xB7 copy ${d.copyMs}ms` : ""}`;
+    case "reanimated":
+    case "animation":
+      return `${d.kind ?? ""} ${d.target ?? ""}${d.durationMs ? ` ${d.durationMs}ms` : ""}`;
+  }
+  return "";
+}
+function formatTimelineEvent(event, anchor) {
+  const ts = formatTimelineRelativeTime(event.t, anchor).padStart(8);
+  const ctx = event.context.padEnd(6);
+  const kind = `[${event.kind}]`.padEnd(15);
+  const d = event.data;
+  const payload = d && typeof d === "object" ? formatTimelinePayload(event.kind, d) : "";
+  return `  ${ts}  ${ctx}  ${kind} ${payload}`;
+}
+function formatTimelineEvents(events) {
+  if (!events.length) return "";
+  const anchor = events[0]?.t ?? null;
+  return events.map((e) => formatTimelineEvent(e, anchor)).join("\n");
+}
 
-          const picked = candidates[idx]
-          const n = picked.info
-          if (!n.absolutePosition || !n.layout) return { matched: 0, total }
-
-          const resolved =
-            typeof n.nodeId === 'number' &&
-            typeof t.resolveTapTarget === 'function'
-              ? await t.resolveTapTarget(n.nodeId)
-              : null
-          const target = (resolved && resolved.target) || n
-          const cx =
-            resolved && typeof resolved.cx === 'number'
-              ? resolved.cx
-              : n.absolutePosition.x + (n.layout.width || 0) / 2
-          const cy =
-            resolved && typeof resolved.cy === 'number'
-              ? resolved.cy
-              : n.absolutePosition.y + (n.layout.height || 0) / 2
-          const scr = ${SCREEN_EVAL}
-          const offscreen =
-            !!scr && (cx < 0 || cy < 0 || cx > scr.width || cy > scr.height)
-          return {
-            cx,
-            cy,
-            ...(offscreen ? { offscreen: true, screen: scr } : {}),
-            match: {
-              nodeId: n.nodeId ?? null,
-              id: n.id,
-              testID: n.testID,
-              type: n.type,
-            },
-            target: {
-              nodeId: target.nodeId ?? null,
-              id: target.id,
-              testID: target.testID,
-              text:
-                target.text ??
-                target.accessibilityLabel ??
-                n.text ??
-                n.accessibilityLabel ??
-                null,
-              type: target.type,
-            },
-            strategy: (resolved && resolved.strategy) || 'matched-node',
-            total,
-            idx,
-          }
-        })()`
-    })
+// cli/commands/inspect/resolve-target.ts
+async function resolveTargetCoords(bridge, target) {
+  const arg = JSON.stringify(target.value);
+  const findExpr = target.mode === "testid" ? `(await t.findByTestId(${arg})) || (await t.findById(${arg}))` : `await t.findByText(${arg})`;
+  const result = await bridge.send({
+    type: "evaluate",
+    code: `(async () => {
+      const t = window.__sootsimTest
+      if (!t) return null
+      const n = ${findExpr}
+      if (!n || !n.absolutePosition || !n.layout) return null
+      const resolved =
+        typeof n.nodeId === 'number' && typeof t.resolveTapTarget === 'function'
+          ? await t.resolveTapTarget(n.nodeId)
+          : null
+      const cx =
+        typeof resolved?.cx === 'number'
+          ? resolved.cx
+          : n.absolutePosition.x + (n.layout.width || 0) / 2
+      const cy =
+        typeof resolved?.cy === 'number'
+          ? resolved.cy
+          : n.absolutePosition.y + (n.layout.height || 0) / 2
+      return {
+        x: cx,
+        y: cy,
+        id: n.id ?? null,
+        testID: n.testID ?? null,
+        text: ${JSON.stringify(target.mode === "text")} ? ${arg} : (n.text ?? n.accessibilityLabel ?? null),
+        type: n.type ?? null,
+      }
+    })()`
   });
+  return result ?? null;
 }
-async function tapBest(bridge, query, opts = {}) {
-  const arg = JSON.stringify(query);
-  return tapResolvedTarget(bridge, {
-    agent: opts.agent,
-    timing: opts.timing,
-    textFallback: query,
-    resolve: async () => {
-      const payload = await bridge.send({
-        type: "evaluate",
-        code: `(async () => {
-          const t = window.__sootsimTest
-          if (!t) return { error: 'bridge-not-ready' }
-          const byTestId =
-            (await t.findByTestId(${arg})) || (await t.findById(${arg}))
-          if (byTestId && byTestId.absolutePosition && byTestId.layout) {
-            return {
-              strategy: 'testid',
-              node: {
-                nodeId: byTestId.nodeId ?? null,
-                id: byTestId.id,
-                testID: byTestId.testID,
-                type: byTestId.type,
-                text: byTestId.text,
-                absolutePosition: byTestId.absolutePosition,
-                layout: byTestId.layout,
-              },
-              screen: ${SCREEN_EVAL},
-            }
-          }
-          const byText = await t.findByText(${arg})
-          if (byText && byText.absolutePosition && byText.layout) {
-            return {
-              strategy: 'text',
-              node: {
-                nodeId: byText.nodeId ?? null,
-                id: byText.id,
-                testID: byText.testID,
-                type: byText.type,
-                text: byText.text,
-                absolutePosition: byText.absolutePosition,
-                layout: byText.layout,
-              },
-              screen: ${SCREEN_EVAL},
-            }
-          }
-          return { strategy: 'none' }
-        })()`
+
+// src/sim-client.ts
+var SimClientError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var SimConnectError = class extends SimClientError {
+};
+var SimReadyTimeoutError = class extends SimClientError {
+  status;
+  constructor(status) {
+    super(`sim not ready: ${waitReadyReason(status)}`);
+    this.status = status;
+  }
+};
+var SimTapError = class extends SimClientError {
+  outcome;
+  constructor(message, outcome = null) {
+    super(message);
+    this.outcome = outcome;
+  }
+};
+var SimKeyboardError = class extends SimClientError {
+};
+var SimPerformError = class extends SimClientError {
+  result;
+  constructor(result) {
+    const failed = result.steps.find((step) => !step.ok);
+    const at = failed ? `${failed.index} (${failed.type})` : String(result.completed);
+    const cause = failed?.error ?? result.error;
+    super(`perform failed at step ${at}${cause ? `: ${cause}` : ""}`);
+    this.result = result;
+  }
+};
+var SimResetError = class extends SimClientError {
+  result;
+  constructor(result) {
+    super(`reset (${result.strategy}) failed${result.error ? `: ${result.error}` : ""}`);
+    this.result = result;
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function decodePngDataUrl(dataUrl) {
+  if (typeof dataUrl !== "string" || !dataUrl.startsWith("data:image/png;base64,")) {
+    throw new SimClientError(
+      `screenshot bridge returned a non-png payload: ${JSON.stringify(
+        typeof dataUrl === "string" ? dataUrl.slice(0, 80) : dataUrl
+      )}`
+    );
+  }
+  const base64 = dataUrl.slice("data:image/png;base64,".length);
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return { dataUrl, bytes };
+}
+var TARGET_SEARCH_PARAMS = [
+  "bundle",
+  "demo",
+  "app",
+  "open",
+  "port",
+  "inspectOpen",
+  "appFonts",
+  "appSplash"
+];
+function buildSimOpenUrl(currentUrl, target) {
+  const url = new URL(currentUrl);
+  for (const param of TARGET_SEARCH_PARAMS) url.searchParams.delete(param);
+  const pathname = url.pathname.replace(/\/+$/, "") || "/";
+  const prefix = pathname === "/__soot" || pathname.startsWith("/__soot/") ? "/__soot" : "";
+  const normalized = String(target).trim();
+  if (/^\d+$/.test(normalized)) {
+    url.pathname = `${prefix}/rn/${normalized}`;
+  } else {
+    url.pathname = `${prefix}/rn`;
+    url.searchParams.set("open", normalized);
+  }
+  return url.toString();
+}
+function isTextTapTarget(target) {
+  return typeof target === "object" && "text" in target && typeof target.text === "string" && !("layout" in target) && !("absolutePosition" in target);
+}
+var SimClient = class {
+  simId;
+  bridge;
+  closed = false;
+  constructor(bridge, simId, _options = {}) {
+    this.bridge = bridge;
+    this.simId = simId;
+  }
+  // --- transport (WsBridge/InspectBridge) ---
+  send(cmd, opts) {
+    if (this.closed) {
+      return Promise.reject(new SimConnectError("sim client is closed"));
+    }
+    const payload = cmd.simId === void 0 ? { ...cmd, simId: this.simId } : cmd;
+    return this.bridge.send(payload, opts);
+  }
+  listSims() {
+    return this.bridge.listSims();
+  }
+  focusSim(simId = this.simId) {
+    return this.bridge.focusSim(simId);
+  }
+  closeSim(simId = this.simId) {
+    return this.bridge.closeSim(simId);
+  }
+  claim(simId = this.simId, opts) {
+    return this.bridge.claim(simId, opts);
+  }
+  /** release the socket. a script that connected must close to exit cleanly. */
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.bridge.close();
+  }
+  // --- navigation + readiness ---
+  /**
+   * point this sim at a dev target: a metro port (`8081`), or anything the
+   * shell's connect flow accepts (`localhost:8081`, an app slug…). resolves
+   * once the reloaded page answers on the new target route.
+   */
+  async open(target, opts = {}) {
+    const sims = await this.listSims();
+    const sim = sims.find((entry) => entry.id === this.simId);
+    if (!sim) {
+      throw new SimConnectError(`sim ${this.simId} is no longer connected`);
+    }
+    const currentUrl = sim.url ?? sim.origin;
+    if (!currentUrl) {
+      throw new SimConnectError(
+        `sim ${this.simId} reported no URL to derive the shell from`
+      );
+    }
+    const nextUrl = buildSimOpenUrl(currentUrl, target);
+    const expected = new URL(nextUrl);
+    await this.send({
+      type: "evaluate",
+      code: `window.location.href = ${JSON.stringify(nextUrl)}`
+    });
+    const deadline = Date.now() + (opts.timeoutMs ?? 3e4);
+    while (Date.now() < deadline) {
+      await sleep(250);
+      try {
+        const { url } = await inspectUrl(this);
+        const current = new URL(url);
+        if (current.pathname === expected.pathname && current.searchParams.get("open") === expected.searchParams.get("open")) {
+          return;
+        }
+      } catch {
+      }
+    }
+    throw new SimConnectError(
+      `timed out waiting for sim ${this.simId} to load ${nextUrl}`
+    );
+  }
+  /**
+   * block until the guest app has mounted and painted real content.
+   * throws SimReadyTimeoutError (with the last probe status) on timeout.
+   */
+  async waitReady(opts = {}) {
+    const status = await inspectWaitReady(this, opts.timeoutMs ?? 2e4, {
+      onProgress: opts.onProgress
+    });
+    if (!status.ready) throw new SimReadyTimeoutError(status);
+    return status;
+  }
+  /** wait for layout/animation/transition settle after an interaction. */
+  settle(opts = {}) {
+    return waitForSootsimIdle({
+      bridge: this,
+      maxMs: opts.maxMs ?? 3e3,
+      strict: opts.strict
+    });
+  }
+  // --- read verbs ---
+  /** first matching node, or null. query precedence matches the CLI's find. */
+  async find(query) {
+    const nodes = await this.findAll(query);
+    return nodes[0] ?? null;
+  }
+  async findAll(query) {
+    const mapped = {
+      testId: query.testId ?? null,
+      role: query.role ?? null,
+      type: query.type ?? null,
+      text: query.text ?? null,
+      pressable: query.pressable
+    };
+    const found = await inspectFind(this, mapped);
+    if (!found) {
+      throw new SimClientError(
+        "find() needs at least one of testId, text, role, type, or pressable"
+      );
+    }
+    const { result } = found;
+    if (Array.isArray(result)) return result;
+    return result ? [result] : [];
+  }
+  async tree(depth = 5) {
+    const { tree } = await inspectTree(this, depth);
+    return tree;
+  }
+  /** compact visible-UI dump with shell + keyboard state, as the CLI prints. */
+  describe(opts = {}) {
+    return inspectDescribe(this, {
+      describe: true,
+      verbose: opts.verbose ?? false,
+      filter: opts.filter ?? "",
+      compact: !opts.verbose,
+      hideXy: false,
+      fullText: true
+    });
+  }
+  accessibilityTree() {
+    return inspectAccessibilityTree(this);
+  }
+  async logs(opts = {}) {
+    return filterLogEntries(await inspectLogs(this), opts);
+  }
+  errors(limit = 20) {
+    return inspectErrors(this, limit);
+  }
+  warnings(limit = 20) {
+    return inspectWarnings(this, limit);
+  }
+  keyboard() {
+    return inspectKeyboard(this);
+  }
+  shellState(readyTimeoutMs = 0) {
+    return getShellState(this, readyTimeoutMs);
+  }
+  async url() {
+    const { url } = await inspectUrl(this);
+    return url;
+  }
+  async screenshot(opts = {}) {
+    const result = await this.send({
+      type: "screenshot",
+      ...opts.layers ? { layers: opts.layers } : {},
+      ...opts.crop ? { crop: opts.crop } : {}
+    });
+    return decodePngDataUrl(result);
+  }
+  // --- input verbs ---
+  /**
+   * tap by testID, visible text, node, or coordinates. resolution, retry, and
+   * hit verification are the CLI's shared tap kernels. throws SimTapError when
+   * the target is missing, covered, offscreen, or the press missed.
+   */
+  async tap(target) {
+    if (typeof target === "string") {
+      return this.throwUnlessTapped(await tapBest(this, target), target);
+    }
+    if ("testId" in target && typeof target.testId === "string") {
+      return this.throwUnlessTapped(await tapById(this, target.testId), target.testId);
+    }
+    if (isTextTapTarget(target)) {
+      const { text, ...textOpts } = target;
+      return this.throwUnlessTapped(await tapByText(this, text, textOpts), text);
+    }
+    if ("testID" in target && typeof target.testID === "string") {
+      return this.throwUnlessTapped(await tapById(this, target.testID), target.testID);
+    }
+    const coords = this.coordsForTapTarget(target);
+    const result = await this.send({ type: "tap", x: coords.x, y: coords.y });
+    if (!isTapSuccess(result)) {
+      throw new SimTapError(
+        `tap at ${coords.x},${coords.y} missed: ${JSON.stringify(result)}`
+      );
+    }
+  }
+  async longPress(target, opts = {}) {
+    const coords = await this.resolveCoords(target);
+    const result = await this.send(
+      {
+        type: "longPress",
+        x: coords.x,
+        y: coords.y,
+        durationMs: opts.durationMs ?? 600
+      },
+      { timeoutMs: (opts.durationMs ?? 600) + 15e3 }
+    );
+    if (!result?.ok) {
+      throw new SimTapError(`longPress at ${coords.x},${coords.y} missed`);
+    }
+  }
+  /** type through the visual iOS keyboard. requires a focused input. */
+  async type(text) {
+    await this.requireVisibleKeyboard("type");
+    await this.send({ type: "keyboard", action: "type", text });
+  }
+  /** press a keyboard key ('return', 'delete', 'space', …). */
+  async press(key) {
+    await this.requireVisibleKeyboard("press");
+    await this.send({ type: "keyboard", action: "press", text: key });
+  }
+  async dismissKeyboard() {
+    await this.send({ type: "keyboard", action: "dismiss" });
+  }
+  // --- batched input, compound state, reset ---
+  /**
+   * execute an ordered step batch inside the page in ONE round-trip, so waits
+   * and gesture physics run on real wall-clock timing. `tapText` steps are
+   * resolved to coordinates client-side before the batch is sent. throws
+   * SimPerformError (carrying the per-step result) when the batch fails.
+   */
+  async perform(steps, options) {
+    const resolved = [];
+    for (const step of steps) {
+      if (step.type !== "tapText") {
+        resolved.push(step);
+        continue;
+      }
+      const target = await resolveTargetCoords(this, {
+        mode: "text",
+        value: step.text
       });
-      if (!payload || !("node" in payload)) return payload;
-      const node = payload.node;
-      const cx = node.absolutePosition.x + node.layout.width / 2;
-      const cy = node.absolutePosition.y + node.layout.height / 2;
-      const screen = payload.screen ?? null;
-      const offscreen = !!screen && (cx < 0 || cy < 0 || cx > screen.width || cy > screen.height);
-      return {
-        ...payload,
-        cx,
-        cy,
-        ...offscreen ? { offscreen: true, screen } : {},
+      if (!target) {
+        throw new SimTapError(
+          `perform tapText: no node with text ${JSON.stringify(step.text)}`
+        );
+      }
+      resolved.push({
+        type: "tap",
+        x: target.x,
+        y: target.y,
         target: {
-          id: node.id,
-          testID: node.testID,
-          text: payload.strategy === "text" ? query : node.text,
-          type: node.type
+          testID: target.testID ?? void 0,
+          text: target.text ?? void 0,
+          type: target.type ?? void 0
         }
+      });
+    }
+    const batchTimeoutMs = options?.timeoutMs ?? 3e4;
+    const result = await this.send(
+      {
+        type: "perform",
+        steps: resolved,
+        ...options ? { performOptions: options } : {}
+      },
+      { timeoutMs: batchTimeoutMs + 5e3 }
+    );
+    if (!result?.ok) throw new SimPerformError(result);
+    return result;
+  }
+  /** screenshot + tree + route + recent errors in one round-trip. */
+  state(options) {
+    return this.send({
+      type: "state",
+      ...options ? { stateOptions: options } : {}
+    });
+  }
+  /**
+   * two-tier app state wipe ('data' clears storage/caches, 'full' also clears
+   * keychain/permissions/native-module state). throws SimResetError on failure.
+   */
+  async reset(options) {
+    const result = await this.send(
+      { type: "reset", ...options ? { resetOptions: options } : {} },
+      { timeoutMs: 6e4 }
+    );
+    if (!result?.ok) throw new SimResetError(result);
+    return result;
+  }
+  // --- internals ---
+  throwUnlessTapped(outcome, label) {
+    if (!outcome.failure && isTapSuccess(outcome.result)) return;
+    const reason = outcome.failure === "not-found" ? "no matching node" : outcome.failure === "missed" ? outcome.result?.reason ?? "press missed" : outcome.payload?.ambiguous ? `ambiguous: ${outcome.payload.total} matches` : outcome.result?.reason ?? outcome.payload?.error ?? "tap failed";
+    throw new SimTapError(`tap ${JSON.stringify(label)} failed: ${reason}`, outcome);
+  }
+  coordsForTapTarget(target) {
+    if (typeof target === "object" && "x" in target && "y" in target && typeof target.x === "number" && typeof target.y === "number") {
+      return { x: target.x, y: target.y };
+    }
+    if (typeof target === "object" && "absolutePosition" in target && target.absolutePosition && target.layout) {
+      return {
+        x: target.absolutePosition.x + (target.layout.width ?? 0) / 2,
+        y: target.absolutePosition.y + (target.layout.height ?? 0) / 2
       };
     }
-  });
-}
+    throw new SimClientError(
+      "tap target needs coordinates, a testId, text, or a node from find()"
+    );
+  }
+  async resolveCoords(target) {
+    if (typeof target === "string") {
+      const resolved = await resolveTargetCoords(this, { mode: "testid", value: target }) ?? await resolveTargetCoords(this, { mode: "text", value: target });
+      if (!resolved) throw new SimTapError(`no node matching ${JSON.stringify(target)}`);
+      return resolved;
+    }
+    if ("testId" in target && typeof target.testId === "string") {
+      const resolved = await resolveTargetCoords(this, {
+        mode: "testid",
+        value: target.testId
+      });
+      if (!resolved) {
+        throw new SimTapError(`no node with testID ${JSON.stringify(target.testId)}`);
+      }
+      return resolved;
+    }
+    if ("text" in target && typeof target.text === "string" && !("layout" in target)) {
+      const resolved = await resolveTargetCoords(this, {
+        mode: "text",
+        value: target.text
+      });
+      if (!resolved) {
+        throw new SimTapError(`no node with text ${JSON.stringify(target.text)}`);
+      }
+      return resolved;
+    }
+    return this.coordsForTapTarget(target);
+  }
+  async requireVisibleKeyboard(action) {
+    const deadline = Date.now() + 1500;
+    for (; ; ) {
+      const state = await inspectKeyboard(this);
+      if (!("error" in state) && state.visible) return;
+      if (Date.now() >= deadline) {
+        throw new SimKeyboardError(
+          `${action} requires the iOS keyboard to be visible \u2014 focus an input first (tap a TextInput)`
+        );
+      }
+      await sleep(150);
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEBUG_CHANNELS,
@@ -2270,8 +2749,17 @@ async function tapBest(bridge, query, opts = {}) {
   READY_CONTENT_NODE_FLOOR,
   READY_NODE_STABLE_MS,
   READY_PROBE_POLL_MS,
+  SimClient,
+  SimClientError,
+  SimConnectError,
+  SimKeyboardError,
+  SimPerformError,
+  SimReadyTimeoutError,
+  SimResetError,
+  SimTapError,
   WAIT_READY_PROBE,
   WAIT_READY_PROGRESS_INTERVAL_MS,
+  buildSimOpenUrl,
   clearConsole,
   clearLogs,
   clearRequests,