rnxsim 0.1.416 → 0.1.418

package/dist-lib/sdk.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.416 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.418 | (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;
@@ -98,656 +98,6 @@ __export(sdk_exports, {
 });
 module.exports = __toCommonJS(sdk_exports);
 
-// 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 layoutDirty = false
-        let pendingFetches = 0
-        let requestTotal = 0
-        let requestInFlight = 0
-        let renderStatsAvailable = false
-        try {
-          const stats = await window.__sootsimRenderHost?.queryStats?.()
-          if (stats) {
-            renderStatsAvailable = true
-            animating =
-              stats.hasActiveAnims === true ||
-              stats.hasActiveNativeAnimations === true ||
-              stats.hasPendingAnimationFrames === true
-            layoutDirty =
-              stats.layoutDirty === true && stats.renderRequested === true
-            // a freshly-pushed screen showing a skeleton is layout-stable
-            // but not actually settled \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, layoutDirty, pendingFetches, renderStatsAvailable, requestTotal, requestInFlight }
-      }
-
-      // how long generic background network is allowed to keep us waiting AFTER
-      // the screen is otherwise visually settled. apps with continuous traffic
-      // (polling, realtime sockets, a tap that fires 20-50 fetches) never reach
-      // requestInFlight===0 / a stable requestTotal, so requiring full network
-      // quiet burns the ENTIRE budget on every command \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.renderStatsAvailable && !snapshot.animating && !snapshot.layoutDirty)
-        // visually settled: no animations, no image content loading, layout
-        // unchanged since the last poll.
-        const visuallyStill =
-          strictOk && snapshot.pendingFetches === 0 && snapshot.layout === lastLayout
-        // generic network quiet: nothing in flight and no new requests issued.
-        const networkQuiet =
-          snapshot.requestInFlight === 0 && snapshot.requestTotal === lastRequestTotal
-        if (visuallyStill) {
-          stable++
-          if (visuallyStillSince === 0) visuallyStillSince = Date.now()
-          // settle once the screen has held still long enough AND either the
-          // network is genuinely quiet OR it has refused to quiet within the
-          // grace (continuous background traffic must not block forever).
-          if (
-            stable >= requiredStablePolls &&
-            (networkQuiet || Date.now() - visuallyStillSince >= networkQuietGraceMs)
-          ) {
-            return { settled: true, elapsed: Date.now() - start }
-          }
-        } else {
-          stable = 0
-          visuallyStillSince = 0
-        }
-        lastLayout = snapshot.layout
-        lastRequestTotal = snapshot.requestTotal
-        await sleep(pollMs)
-      }
-      return { settled: false, elapsed: Date.now() - start }
-    })()`
-    },
-    {
-      timeoutMs: maxMs + 1e3
-    }
-  );
-  const { elapsed, settled } = result ?? {};
-  return {
-    elapsed: typeof elapsed === "number" ? elapsed : maxMs,
-    settled: settled === true
-  };
-}
-
-// 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 {
-    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 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" };
-        }
-        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"
-          };
-        }
-        if (verification?.requestedTargetMatched === false) {
-          return {
-            payload,
-            result: {
-              hit: false,
-              reason: "target-covered",
-              ...verification
-            },
-            attempts,
-            failure: "missed"
-          };
-        }
-        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 };
-      }
-    }
-    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"
-  };
-}
-async function tapCoordinates(bridge, x, y, target) {
-  return bridge.send({
-    type: "tap",
-    x,
-    y,
-    ...target ? { target } : {}
-  });
-}
-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 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 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
-                  ? {
-                      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,
-          }
-        })()`
-    })
-  });
-}
-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
-        }
-      };
-    }
-  });
-}
-
 // src/bridge-contract.ts
 var SEMANTIC_READY_CONTENT_NODE_FLOOR = 100;
 function readyProbeHasContent(probe) {
@@ -1214,778 +564,1292 @@ async function inspectGetLayout(bridge, opts = {}) {
         w: Math.round(node.geometry.width),
         h: Math.round(node.geometry.height)
       }
-    }));
+    }));
+  }
+  const raw = await bridge.send({
+    type: "evaluate",
+    code: layoutGetNativeEval(opts)
+  });
+  return Array.isArray(raw) ? raw : [];
+}
+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 !== void 0 && el.borderRadius > 0) {
+      parts.push(`radius:${el.borderRadius}`);
+    }
+    const p = el.padding;
+    if (p && (p.t || p.r || p.b || p.l)) {
+      const uniform = p.t === p.r && p.r === p.b && p.b === p.l;
+      parts.push(uniform ? `pad:${p.t}` : `pad:${p.t},${p.r},${p.b},${p.l}`);
+    }
+    if (el.fontSize !== void 0 && 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 inspectAccessibilityTree(bridge) {
+  const result = await bridge.send({
+    type: "query",
+    query: { kind: "find", selector: { visible: true } }
+  });
+  if (!isSemanticQueryResult(result)) return [];
+  return result.nodes.flatMap((node) => {
+    if (!node.role && !node.label && !node.text && !node.pressable) return [];
+    return [
+      {
+        role: node.role ?? (node.pressable ? "button" : node.type === "text" ? "statictext" : "none"),
+        label: node.label ?? node.text ?? null,
+        hint: null,
+        state: null,
+        testID: node.testID ?? null,
+        position: {
+          x: Math.round(node.geometry.x),
+          y: Math.round(node.geometry.y)
+        },
+        size: {
+          w: Math.round(node.geometry.width),
+          h: Math.round(node.geometry.height)
+        }
+      }
+    ];
+  });
+}
+function resolveFindMode(q) {
+  if (q.testId) {
+    return { mode: "testid", selector: { testID: q.testId } };
+  }
+  if (q.role) {
+    return { mode: "role", selector: { role: q.role } };
+  }
+  if (q.type) {
+    return { mode: "type", selector: { type: q.type } };
+  }
+  if (q.pressable) {
+    return { mode: "pressable", selector: { pressable: true } };
+  }
+  if (q.interactive) {
+    return { mode: "interactive-targets", selector: { pressable: true } };
+  }
+  if (q.visible) {
+    return { mode: "visible", selector: { visible: true } };
+  }
+  if (q.text) {
+    return { mode: "text", selector: { text: q.text } };
+  }
+  return null;
+}
+async function inspectFind(bridge, q) {
+  const resolved = resolveFindMode(q);
+  if (!resolved) return null;
+  const result = await bridge.send({
+    type: "query",
+    query: { kind: "find", selector: resolved.selector }
+  });
+  if (!isSemanticQueryResult(result)) return { mode: resolved.mode, result: [] };
+  const nodes = result.nodes.map(
+    (node) => ({
+      type: node.type,
+      nodeId: node.nodeId,
+      ...node.testID ? { testID: node.testID } : {},
+      ...node.text ? { text: node.text } : {},
+      ...node.pressable ? { pressable: true } : {},
+      ...node.role ? { accessibilityRole: node.role } : {},
+      ...node.label ? { accessibilityLabel: node.label } : {},
+      absolutePosition: { x: node.geometry.x, y: node.geometry.y },
+      layout: { width: node.geometry.width, height: node.geometry.height }
+    })
+  );
+  const resultValue = resolved.mode === "testid" || resolved.mode === "text" ? nodes[0] ?? null : nodes;
+  return { mode: resolved.mode, result: resultValue };
+}
+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 `rnx do tap-id ${shellEscape(n.testID)}`;
+  const text = typeof n.text === "string" ? n.text.trim() : "";
+  if (text.length > 0 && text.length <= 80) return `rnx do tap-text ${shellEscape(text)}`;
+  const x = Math.round(((n.absolutePosition?.x ?? 0) + (n.layout?.width ?? 0) / 2) * 10) / 10;
+  const y = Math.round(((n.absolutePosition?.y ?? 0) + (n.layout?.height ?? 0) / 2) * 10) / 10;
+  return `rnx do tap ${x} ${y}`;
+}
+function shellEscape(value) {
+  if (/^[A-Za-z0-9_./@:-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function waitReadyReason(status) {
+  if (status.bridgeError) {
+    if (status.bridgeError.includes("headless tenant fetch hung") || status.bridgeError.includes("public RNX Cloud simulators have no network")) {
+      return status.bridgeError;
+    }
+    return `sim unreachable: ${status.bridgeError} \u2014 the target tab is closed or no sim is connected (check \`rnx list\`, reopen with \`rnx 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();
+  let result;
+  try {
+    result = await bridge.send(
+      {
+        type: "waitFor",
+        waitForOptions: { condition: { type: "ready" }, timeoutMs }
+      },
+      { timeoutMs: timeoutMs + 1e3 }
+    );
+  } catch (error) {
+    const bridgeError = error instanceof Error ? error.message : String(error);
+    if (bridgeError.startsWith("multiple sims are connected:") || bridgeError.startsWith("saved sim ")) {
+      throw error;
+    }
+    result = {
+      matched: false,
+      elapsedMs: Date.now() - start,
+      polls: 0,
+      error: bridgeError
+    };
+  }
+  const probe = result.probe;
+  const externalError = probe?.externalError ?? "";
+  const status = {
+    ready: result.matched && !externalError,
+    elapsedMs: result.elapsedMs,
+    nodes: probe?.nodes ?? 0,
+    targets: probe?.targets ?? 0,
+    liveFrameActive: probe?.liveFrameActive ?? false,
+    liveFrameChannels: probe?.liveFrameChannels ?? 0,
+    liveFramePublishes: probe?.liveFramePublishes ?? 0,
+    flag: probe?.flag,
+    loadingText: probe?.loadingText ?? "",
+    externalReady: probe?.externalReady ?? null,
+    externalStatus: probe?.externalStatus ?? "",
+    externalError,
+    suppressedEntryError: probe?.suppressedEntryError ?? "",
+    errors: probe?.errors ?? 0,
+    bridgeError: result.error ?? ""
+  };
+  if (!status.ready && options.onProgress) options.onProgress(status);
+  return status;
+}
+async function inspectWaitSelector(bridge, testId, timeoutMs = 5e3, opts = {}) {
+  const gone = opts.gone === true;
+  const result = await bridge.send(
+    {
+      type: "waitFor",
+      waitForOptions: {
+        condition: {
+          type: gone ? "absent" : "present",
+          selector: { testID: testId }
+        },
+        timeoutMs
+      }
+    },
+    { timeoutMs: timeoutMs + 1e3 }
+  );
+  if (result?.error) throw new Error(result.error);
+  if (result?.node && !isSimSemanticTree([result.node])) {
+    throw new Error("waitFor returned an invalid semantic node");
   }
-  const raw = await bridge.send({
+  return {
+    found: result?.matched === true,
+    ...result?.node ? { node: result.node } : {},
+    elapsed: result?.elapsedMs ?? 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: layoutGetNativeEval(opts)
+    code: consoleEntriesEval("error", limit)
   });
-  return Array.isArray(raw) ? raw : [];
+  return Array.isArray(result) ? result : [];
 }
-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 !== void 0 && el.borderRadius > 0) {
-      parts.push(`radius:${el.borderRadius}`);
-    }
-    const p = el.padding;
-    if (p && (p.t || p.r || p.b || p.l)) {
-      const uniform = p.t === p.r && p.r === p.b && p.b === p.l;
-      parts.push(uniform ? `pad:${p.t}` : `pad:${p.t},${p.r},${p.b},${p.l}`);
-    }
-    if (el.fontSize !== void 0 && 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}"`);
+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++
     }
-    return `  ${parts.join(" ")}`;
+    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"'
   });
-  return lines.join("\n");
 }
-async function inspectAccessibilityTree(bridge) {
+async function inspectRequests(bridge, opts = {}) {
+  const limit = opts.limit ?? 20;
+  const method = opts.failed === false ? "getRequests" : "getFailedRequests";
   const result = await bridge.send({
-    type: "query",
-    query: { kind: "find", selector: { visible: true } }
+    type: "call",
+    path: `__sootsimTest.${method}`,
+    args: [limit]
   });
-  if (!isSemanticQueryResult(result)) return [];
-  return result.nodes.flatMap((node) => {
-    if (!node.role && !node.label && !node.text && !node.pressable) return [];
-    return [
-      {
-        role: node.role ?? (node.pressable ? "button" : node.type === "text" ? "statictext" : "none"),
-        label: node.label ?? node.text ?? null,
-        hint: null,
-        state: null,
-        testID: node.testID ?? null,
-        position: {
-          x: Math.round(node.geometry.x),
-          y: Math.round(node.geometry.y)
-        },
-        size: {
-          w: Math.round(node.geometry.width),
-          h: Math.round(node.geometry.height)
-        }
-      }
-    ];
+  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 {
+    ...state,
+    scrollOffsetX: typeof state.scrollOffsetX === "number" ? state.scrollOffsetX : state.offsetX,
+    scrollOffsetY: typeof state.scrollOffsetY === "number" ? state.scrollOffsetY : state.offsetY
+  };
 }
-function resolveFindMode(q) {
-  if (q.testId) {
-    return { mode: "testid", selector: { testID: q.testId } };
-  }
-  if (q.role) {
-    return { mode: "role", selector: { role: q.role } };
-  }
-  if (q.type) {
-    return { mode: "type", selector: { type: q.type } };
+async function inspectLogs(bridge) {
+  if (bridge.plane === "cloud") {
+    const state = await bridge.send({
+      type: "state",
+      stateOptions: {
+        screenshot: false,
+        tree: false,
+        route: false,
+        errors: false,
+        logs: true,
+        logLimit: 100
+      }
+    });
+    const recentLogs = state && typeof state === "object" && Array.isArray(Reflect.get(state, "recentLogs")) ? Reflect.get(state, "recentLogs") : [];
+    return recentLogs.flatMap((entry, index) => {
+      if (!entry || typeof entry !== "object") return [];
+      const text = Reflect.get(entry, "text");
+      const rawLevel = Reflect.get(entry, "level");
+      if (typeof text !== "string") return [];
+      const level = rawLevel === "log" || rawLevel === "info" || rawLevel === "warn" || rawLevel === "error" || rawLevel === "debug" ? rawLevel : "error";
+      const at = Reflect.get(entry, "at");
+      const ts = typeof at === "number" && Number.isFinite(at) ? at : 0;
+      return [
+        {
+          id: `cloud-${ts}-${index}`,
+          source: "rnx-cloud",
+          level,
+          ts,
+          args: [text],
+          stack: null
+        }
+      ];
+    });
   }
-  if (q.pressable) {
-    return { mode: "pressable", selector: { pressable: true } };
+  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 clearLogs(bridge) {
+  await bridge.send({
+    type: "evaluate",
+    code: 'window.__sootsimObservability?.logs.clear(); "cleared"'
+  });
+}
+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 (q.interactive) {
-    return { mode: "interactive-targets", selector: { pressable: true } };
+  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 (q.visible) {
-    return { mode: "visible", selector: { visible: true } };
+  if (!opts.showInternal) {
+    out = out.filter((e) => {
+      const first = e.args[0];
+      return !(typeof first === "string" && /^\[(?:rnx|sootsim)(?:\s[^\]]*)?\]/.test(first));
+    });
   }
-  if (q.text) {
-    return { mode: "text", selector: { text: q.text } };
+  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 null;
+  return out;
 }
-async function inspectFind(bridge, q) {
-  const resolved = resolveFindMode(q);
-  if (!resolved) return null;
-  const result = await bridge.send({
-    type: "query",
-    query: { kind: "find", selector: resolved.selector }
+async function inspectTimelineSummary(bridge, query) {
+  return await bridge.send({
+    type: "call",
+    path: "SootSim.bridges.timeline.summary",
+    args: [query]
   });
-  if (!isSemanticQueryResult(result)) return { mode: resolved.mode, result: [] };
-  const nodes = result.nodes.map(
-    (node) => ({
-      type: node.type,
-      nodeId: node.nodeId,
-      ...node.testID ? { testID: node.testID } : {},
-      ...node.text ? { text: node.text } : {},
-      ...node.pressable ? { pressable: true } : {},
-      ...node.role ? { accessibilityRole: node.role } : {},
-      ...node.label ? { accessibilityLabel: node.label } : {},
-      absolutePosition: { x: node.geometry.x, y: node.geometry.y },
-      layout: { width: node.geometry.width, height: node.geometry.height }
-    })
-  );
-  const resultValue = resolved.mode === "testid" || resolved.mode === "text" ? nodes[0] ?? null : nodes;
-  return { mode: resolved.mode, result: resultValue };
 }
-function rankInteractive(nodes) {
-  return [...nodes].sort((a, b) => scoreInteractive(b) - scoreInteractive(a));
+async function inspectTimelineRecent(bridge, query) {
+  return await bridge.send({
+    type: "call",
+    path: "SootSim.bridges.timeline.recent",
+    args: [query]
+  });
 }
-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;
+async function detectOpenNativeUI(bridge) {
+  let events;
+  try {
+    const res = await inspectTimelineRecent(bridge, {
+      kinds: ["alert", "actionsheet"],
+      limit: 80
+    });
+    events = res.events;
+  } catch {
+    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;
+  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;
 }
-function tapCommandForNode(n) {
-  if (n.testID) return `rnx do tap-id ${shellEscape(n.testID)}`;
-  const text = typeof n.text === "string" ? n.text.trim() : "";
-  if (text.length > 0 && text.length <= 80) return `rnx do tap-text ${shellEscape(text)}`;
-  const x = Math.round(((n.absolutePosition?.x ?? 0) + (n.layout?.width ?? 0) / 2) * 10) / 10;
-  const y = Math.round(((n.absolutePosition?.y ?? 0) + (n.layout?.height ?? 0) / 2) * 10) / 10;
-  return `rnx do tap ${x} ${y}`;
+async function inspectTimelineAdvanceCursor(bridge, cursorKey, watermark) {
+  await bridge.send({
+    type: "call",
+    path: "SootSim.bridges.timeline.cursorAdvance",
+    args: [cursorKey, watermark]
+  });
 }
-function shellEscape(value) {
-  if (/^[A-Za-z0-9_./@:-]+$/.test(value)) return value;
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+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 waitReadyReason(status) {
-  if (status.bridgeError) {
-    return `sim unreachable: ${status.bridgeError} \u2014 the target tab is closed or no sim is connected (check \`rnx list\`, reopen with \`rnx 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;
+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 inspectWaitReady(bridge, timeoutMs = 2e4, options = {}) {
-  const start = Date.now();
-  let result;
-  try {
-    result = await bridge.send(
-      {
-        type: "waitFor",
-        waitForOptions: { condition: { type: "ready" }, timeoutMs }
-      },
-      { timeoutMs: timeoutMs + 1e3 }
-    );
-  } catch (error) {
-    const bridgeError = error instanceof Error ? error.message : String(error);
-    if (bridgeError.startsWith("multiple sims are connected:") || bridgeError.startsWith("saved sim ")) {
-      throw error;
+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));
     }
-    result = {
-      matched: false,
-      elapsedMs: Date.now() - start,
-      polls: 0,
-      error: bridgeError
-    };
   }
-  const probe = result.probe;
-  const externalError = probe?.externalError ?? "";
-  const status = {
-    ready: result.matched && !externalError,
-    elapsedMs: result.elapsedMs,
-    nodes: probe?.nodes ?? 0,
-    targets: probe?.targets ?? 0,
-    liveFrameActive: probe?.liveFrameActive ?? false,
-    liveFrameChannels: probe?.liveFrameChannels ?? 0,
-    liveFramePublishes: probe?.liveFramePublishes ?? 0,
-    flag: probe?.flag,
-    loadingText: probe?.loadingText ?? "",
-    externalReady: probe?.externalReady ?? null,
-    externalStatus: probe?.externalStatus ?? "",
-    externalError,
-    suppressedEntryError: probe?.suppressedEntryError ?? "",
-    errors: probe?.errors ?? 0,
-    bridgeError: result.error ?? ""
-  };
-  if (!status.ready && options.onProgress) options.onProgress(status);
-  return status;
 }
-async function inspectWaitSelector(bridge, testId, timeoutMs = 5e3, opts = {}) {
-  const gone = opts.gone === true;
-  const result = await bridge.send(
-    {
-      type: "waitFor",
-      waitForOptions: {
-        condition: {
-          type: gone ? "absent" : "present",
-          selector: { testID: testId }
-        },
-        timeoutMs
-      }
-    },
-    { timeoutMs: timeoutMs + 1e3 }
-  );
-  if (result?.error) throw new Error(result.error);
-  if (result?.node && !isSimSemanticTree([result.node])) {
-    throw new Error("waitFor returned an invalid semantic node");
-  }
+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 }
+    })()`
+  });
+  const shell = await getShellState(bridge, 500).catch(() => null);
   return {
-    found: result?.matched === true,
-    ...result?.node ? { node: result.node } : {},
-    elapsed: result?.elapsedMs ?? timeoutMs
+    shell,
+    nav: payload?.nav ?? null,
+    route: payload?.route ?? null,
+    keyboard: payload?.keyboard ?? null
   };
 }
-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})
-  })()`;
+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 inspectErrors(bridge, limit = 20) {
-  const result = await bridge.send({
+async function inspectDebugFlags(bridge) {
+  return bridge.send({ type: "evaluate", code: "window.__sootsimDebug.flags()" });
+}
+async function inspectDebugFind(bridge, target) {
+  return bridge.send({
     type: "evaluate",
-    code: consoleEntriesEval("error", limit)
+    code: `window.__sootsimTest.debugFind(${JSON.stringify(target)})`
   });
-  return Array.isArray(result) ? result : [];
 }
-async function inspectWarnings(bridge, limit = 20) {
-  const result = await bridge.send({
+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: consoleEntriesEval("warn", limit)
+    code: `window.__sootsimDebug.${action}(${args})`
   });
-  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({
+async function inspectMemory(bridge) {
+  if (bridge.plane === "cloud") {
+    const value = await bridge.send({ type: "memory" });
+    const rawWasmHeapBytes = typeof value === "object" && value !== null ? Reflect.get(value, "wasmHeapBytes") : null;
+    const wasmHeapBytes = typeof rawWasmHeapBytes === "number" ? rawWasmHeapBytes : null;
+    return {
+      tenant: {
+        nodesRegistered: null,
+        nodesDetached: null,
+        detachedTypes: null,
+        objects: null,
+        activeNativeAnimations: null,
+        imageLoader: null,
+        workerHeap: null,
+        wasmHeapBytes
+      },
+      shell: null,
+      compositor: null,
+      hostHeap: null
+    };
+  }
+  const result = await bridge.send({
     type: "evaluate",
-    code: 'window.__sootsimConsole?.clear(); window.__sootsimObservability?.logs?.clear?.(); "cleared"'
+    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 "";
 }
-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 : [];
+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}`;
 }
-async function clearRequests(bridge) {
-  await bridge.send({ type: "call", path: "__sootsimTest.clearRequests", args: [] });
+function formatTimelineEvents(events) {
+  if (!events.length) return "";
+  const anchor = events[0]?.t ?? null;
+  return events.map((e) => formatTimelineEvent(e, anchor)).join("\n");
 }
-async function inspectScrollStateAt(bridge, x, y) {
+
+// cli/commands/inspect/resolve-target.ts
+async function resolveTargetCoords(bridge, target) {
   const result = await bridge.send({
-    type: "call",
-    path: "__sootsimTest.getScrollStateAt",
-    args: [x, y]
+    type: "resolve",
+    selector: target.mode === "testid" ? { testID: target.value } : { text: target.value }
   });
-  if (!result || typeof result !== "object") return null;
-  const state = result;
+  if (result === null) return null;
+  if (typeof result !== "object") throw new Error("resolve returned an invalid result");
+  const match = Reflect.get(result, "match");
+  const resolvedTarget = Reflect.get(result, "target");
+  const semanticNodes = [match, resolvedTarget];
+  const point = Reflect.get(result, "point");
+  const x = point !== null && typeof point === "object" ? Reflect.get(point, "x") : void 0;
+  const y = point !== null && typeof point === "object" ? Reflect.get(point, "y") : void 0;
+  if (!isSimSemanticTree(semanticNodes) || typeof x !== "number" || !Number.isFinite(x) || typeof y !== "number" || !Number.isFinite(y)) {
+    throw new Error("resolve returned an invalid result");
+  }
+  const semanticMatch = semanticNodes[0];
+  if (!semanticMatch) throw new Error("resolve returned an invalid result");
   return {
-    ...state,
-    scrollOffsetX: typeof state.scrollOffsetX === "number" ? state.scrollOffsetX : state.offsetX,
-    scrollOffsetY: typeof state.scrollOffsetY === "number" ? state.scrollOffsetY : state.offsetY
+    x,
+    y,
+    testID: semanticMatch.testID ?? null,
+    text: semanticMatch.text ?? (target.mode === "text" ? target.value : semanticMatch.label),
+    type: semanticMatch.type
   };
 }
-async function inspectLogs(bridge) {
-  if (bridge.plane === "cloud") {
-    const state = await bridge.send({
-      type: "state",
-      stateOptions: {
-        screenshot: false,
-        tree: false,
-        route: false,
-        errors: false,
-        logs: true,
-        logLimit: 100
+
+// 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 layoutDirty = false
+        let pendingFetches = 0
+        let requestTotal = 0
+        let requestInFlight = 0
+        let renderStatsAvailable = false
+        try {
+          const stats = await window.__sootsimRenderHost?.queryStats?.()
+          if (stats) {
+            renderStatsAvailable = true
+            animating =
+              stats.hasActiveAnims === true ||
+              stats.hasActiveNativeAnimations === true ||
+              stats.hasPendingAnimationFrames === true
+            layoutDirty =
+              stats.layoutDirty === true && stats.renderRequested === true
+            // a freshly-pushed screen showing a skeleton is layout-stable
+            // but not actually settled \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, layoutDirty, pendingFetches, renderStatsAvailable, requestTotal, requestInFlight }
       }
-    });
-    const recentLogs = state && typeof state === "object" && Array.isArray(Reflect.get(state, "recentLogs")) ? Reflect.get(state, "recentLogs") : [];
-    return recentLogs.flatMap((entry, index) => {
-      if (!entry || typeof entry !== "object") return [];
-      const text = Reflect.get(entry, "text");
-      const rawLevel = Reflect.get(entry, "level");
-      if (typeof text !== "string") return [];
-      const level = rawLevel === "log" || rawLevel === "info" || rawLevel === "warn" || rawLevel === "error" || rawLevel === "debug" ? rawLevel : "error";
-      const at = Reflect.get(entry, "at");
-      const ts = typeof at === "number" && Number.isFinite(at) ? at : 0;
-      return [
-        {
-          id: `cloud-${ts}-${index}`,
-          source: "rnx-cloud",
-          level,
-          ts,
-          args: [text],
-          stack: null
+
+      // 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.renderStatsAvailable && !snapshot.animating && !snapshot.layoutDirty)
+        // visually settled: no animations, no image content loading, layout
+        // unchanged since the last poll.
+        const visuallyStill =
+          strictOk && snapshot.pendingFetches === 0 && snapshot.layout === lastLayout
+        // generic network quiet: nothing in flight and no new requests issued.
+        const networkQuiet =
+          snapshot.requestInFlight === 0 && snapshot.requestTotal === lastRequestTotal
+        if (visuallyStill) {
+          stable++
+          if (visuallyStillSince === 0) visuallyStillSince = Date.now()
+          // settle once the screen has held still long enough AND either the
+          // network is genuinely quiet OR it has refused to quiet within the
+          // grace (continuous background traffic must not block forever).
+          if (
+            stable >= requiredStablePolls &&
+            (networkQuiet || Date.now() - visuallyStillSince >= networkQuietGraceMs)
+          ) {
+            return { settled: true, elapsed: Date.now() - start }
+          }
+        } else {
+          stable = 0
+          visuallyStillSince = 0
         }
-      ];
-    });
-  }
-  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 clearLogs(bridge) {
-  await bridge.send({
-    type: "evaluate",
-    code: 'window.__sootsimObservability?.logs.clear(); "cleared"'
-  });
-}
-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;
+        lastLayout = snapshot.layout
+        lastRequestTotal = snapshot.requestTotal
+        await sleep(pollMs)
+      }
+      return { settled: false, elapsed: Date.now() - start }
+    })()`
+    },
+    {
+      timeoutMs: maxMs + 1e3
     }
-    out.push(entry);
-  }
-  if (!opts.showInternal) {
-    out = out.filter((e) => {
-      const first = e.args[0];
-      return !(typeof first === "string" && /^\[(?:rnx|sootsim)(?:\s[^\]]*)?\]/.test(first));
-    });
+  );
+  const { elapsed, settled } = result ?? {};
+  return {
+    elapsed: typeof elapsed === "number" ? elapsed : maxMs,
+    settled: settled === true
+  };
+}
+
+// cli/commands/inspect/actions.ts
+function isScreenSize(value) {
+  if (value === null || typeof value !== "object") return false;
+  const width = Reflect.get(value, "width");
+  const height = Reflect.get(value, "height");
+  return typeof width === "number" && Number.isFinite(width) && width > 0 && typeof height === "number" && Number.isFinite(height) && height > 0;
+}
+function viewportFromCapture(value) {
+  if (value === null || typeof value !== "object") return void 0;
+  const tree = Reflect.get(value, "tree");
+  return tree !== null && typeof tree === "object" ? Reflect.get(tree, "viewport") : void 0;
+}
+async function readScreen(bridge) {
+  try {
+    const viewport = viewportFromCapture(
+      await bridge.send({ type: "capture", includeVisual: false })
+    );
+    return isScreenSize(viewport) ? { width: viewport.width, height: viewport.height } : null;
+  } catch {
+    return null;
   }
-  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));
+}
+function offscreenPayload(cx, cy, screen) {
+  if (!screen || cx >= 0 && cy >= 0 && cx <= screen.width && cy <= screen.height) {
+    return {};
   }
-  return out;
+  return { offscreen: true, screen };
 }
-async function inspectTimelineSummary(bridge, query) {
-  return await bridge.send({
-    type: "call",
-    path: "SootSim.bridges.timeline.summary",
-    args: [query]
-  });
+function geometryContains(geometry, x, y) {
+  return x >= geometry.x && y >= geometry.y && x <= geometry.x + geometry.width && y <= geometry.y + geometry.height;
 }
-async function inspectTimelineRecent(bridge, query) {
-  return await bridge.send({
-    type: "call",
-    path: "SootSim.bridges.timeline.recent",
-    args: [query]
-  });
+function hitTestSemanticTree(nodes, x, y, ancestors = []) {
+  for (let index = nodes.length - 1; index >= 0; index--) {
+    const node = nodes[index];
+    if (!node || !geometryContains(node.geometry, x, y)) continue;
+    const childHit = node.children?.length ? hitTestSemanticTree(node.children, x, y, [...ancestors, node]) : null;
+    return childHit ?? { node, ancestors };
+  }
+  return null;
 }
-async function detectOpenNativeUI(bridge) {
-  let events;
-  try {
-    const res = await inspectTimelineRecent(bridge, {
-      kinds: ["alert", "actionsheet"],
-      limit: 80
-    });
-    events = res.events;
-  } catch {
-    return [];
+function nodeMatchesRequested(node, requested) {
+  if (typeof requested.nodeId === "number" && node.nodeId === requested.nodeId) {
+    return true;
   }
-  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 });
+  if (requested.testID && node.testID === requested.testID) return true;
+  if (requested.id && node.testID === requested.id) return true;
+  return false;
+}
+function coveringNodeSummary(node) {
+  return {
+    nodeId: node.nodeId,
+    testID: node.testID ?? null,
+    text: node.text ?? node.label ?? null,
+    type: node.type
   };
-  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 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
+  };
 }
-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 isTapSuccess(result) {
+  if (!result || result.hit === false || result.ok === false) return false;
+  if (result.handled === false) return false;
+  if (result.requestedTargetMatched === false) return false;
+  if (result.pointerTapHandled === false && !result.keyboardOpened && !result.isTextInput) {
+    return false;
+  }
+  return true;
 }
-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");
+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 getShellState(bridge, readyTimeoutMs = 0) {
-  const deadline = Date.now() + Math.max(0, readyTimeoutMs);
-  while (true) {
+async function tapResolvedTarget(bridge, args) {
+  const timing = tapTiming(!!args.agent, args.timing);
+  let attempts = 0;
+  let lastPayload = null;
+  let lastResult = null;
+  const canWaitForIdle = bridge.plane !== "cloud" && timing.initialWaitMs > 0;
+  if (canWaitForIdle) {
     try {
-      return await bridge.send({
-        type: "call",
-        path: "SootSim.bridges.mainShell.getState",
-        args: []
+      await waitForSootsimIdle({
+        bridge,
+        maxMs: timing.initialWaitMs,
+        pollMs: 32,
+        stablePolls: 2
       });
-    } catch (error) {
-      if (!isShellCommandUnavailable(error) || Date.now() >= deadline) throw error;
-      await new Promise((r) => setTimeout(r, 50));
+    } catch {
+    }
+  }
+  const deadline = Date.now() + timing.deadlineMs;
+  let lastOffscreenAt = null;
+  const screen = await readScreen(bridge);
+  while (Date.now() <= deadline || attempts === 0) {
+    attempts++;
+    const resolved = await args.resolve();
+    const payload = resolved && typeof resolved.cx === "number" && typeof resolved.cy === "number" ? { ...resolved, ...offscreenPayload(resolved.cx, resolved.cy, screen) } : resolved;
+    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 { tree } = await inspectTree(bridge, 50);
+        if (Array.isArray(tree) && tree.length > 0) {
+          const hit = hitTestSemanticTree(tree, payload.cx, payload.cy);
+          const matched = hit !== null && (nodeMatchesRequested(hit.node, requestedTarget) || hit.ancestors.some(
+            (ancestor) => nodeMatchesRequested(ancestor, requestedTarget)
+          ));
+          if (hit && !matched) {
+            lastResult = {
+              hit: false,
+              reason: "target-covered",
+              requestedTarget,
+              coordinateTarget: coveringNodeSummary(hit.node)
+            };
+            return { payload, result: lastResult, attempts, failure: "missed" };
+          }
+        }
+        const result = await tapCoordinates(
+          bridge,
+          payload.cx,
+          payload.cy,
+          requestedTarget
+        );
+        lastResult = result;
+        if (isTapSuccess(result)) return { payload, result, attempts };
+      }
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    if (bridge.plane === "cloud" || timing.retryWaitMs <= 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)));
     }
   }
-}
-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 }
-    })()`
-  });
-  const shell = await getShellState(bridge, 500).catch(() => null);
   return {
-    shell,
-    nav: payload?.nav ?? null,
-    route: payload?.route ?? null,
-    keyboard: payload?.keyboard ?? null
+    payload: lastPayload,
+    result: lastResult,
+    attempts,
+    failure: lastPayload && typeof lastPayload.cx === "number" ? "missed" : "not-found"
   };
 }
-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'" : "";
+async function tapCoordinates(bridge, x, y, target) {
   return bridge.send({
-    type: "evaluate",
-    code: `window.__sootsimDebug.${action}(${args})`
+    type: "tap",
+    x,
+    y,
+    ...target ? { target } : {}
   });
 }
-async function inspectMemory(bridge) {
-  if (bridge.plane === "cloud") {
-    const value = await bridge.send({ type: "memory" });
-    const rawWasmHeapBytes = typeof value === "object" && value !== null ? Reflect.get(value, "wasmHeapBytes") : null;
-    const wasmHeapBytes = typeof rawWasmHeapBytes === "number" ? rawWasmHeapBytes : null;
-    return {
-      tenant: {
-        nodesRegistered: null,
-        nodesDetached: null,
-        detachedTypes: null,
-        objects: null,
-        activeNativeAnimations: null,
-        imageLoader: null,
-        workerHeap: null,
-        wasmHeapBytes
-      },
-      shell: null,
-      compositor: null,
-      hostHeap: null
-    };
-  }
-  const result = await bridge.send({
-    type: "evaluate",
-    code: `(async () => {
-      const host = window.__sootsimRenderHost
-      const stats = host?.queryStats ? await host.queryStats() : null
-      const shellRaw = window.__sootsimShellMemory
-        ? await window.__sootsimShellMemory()
-        : null
-      const shell = shellRaw && !shellRaw.error ? shellRaw : null
-      // the compositor paints home + app:one + app:two, so every app-surface
-      // picture and raster image is counted here and nowhere else.
-      let compositor = null
-      try {
-        const cs = await window.__sootsimCompositor?.getStats?.(false, true)
-        compositor = cs?.memory ?? null
-      } catch {}
-      const normalize = (m) =>
-        m
-          ? {
-              nodesRegistered: m.nodesRegistered ?? null,
-              nodesDetached: m.nodesDetached ?? null,
-              detachedTypes: m.detachedTypes ?? null,
-              objects: m.objects ?? null,
-              activeNativeAnimations: m.activeNativeAnimations ?? null,
-              imageLoader: m.imageLoader ?? null,
-              workerHeap: m.workerHeap ?? null,
-              wasmHeapBytes: m.wasmHeapBytes ?? null,
-            }
-          : null
-      const hostMem = performance.memory
-        ? {
-            usedJSHeapSize: performance.memory.usedJSHeapSize,
-            totalJSHeapSize: performance.memory.totalJSHeapSize,
-            jsHeapSizeLimit: performance.memory.jsHeapSizeLimit,
-          }
-        : null
-      return {
-        tenant: normalize(stats?.memory),
-        shell: normalize(shell),
-        compositor: normalize(compositor),
-        hostHeap: hostMem,
-      }
-    })()`
-  });
-  return result ?? { tenant: null, shell: null, compositor: null, hostHeap: null };
+function payloadFromResolved(resolved, match, extra = {}) {
+  return {
+    cx: resolved.x,
+    cy: resolved.y,
+    match: {
+      nodeId: match.nodeId ?? null,
+      id: match.testID ?? null,
+      testID: match.testID ?? null,
+      text: match.text ?? null,
+      type: match.type ?? null
+    },
+    target: {
+      nodeId: match.nodeId ?? null,
+      id: resolved.testID ?? match.testID ?? null,
+      testID: resolved.testID ?? match.testID ?? null,
+      text: resolved.text ?? match.text ?? null,
+      type: resolved.type ?? match.type ?? null
+    },
+    strategy: "matched-node",
+    ...extra
+  };
 }
-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);
+function collectTextCandidates(nodes, ancestors = []) {
+  const out = [];
+  for (const node of nodes) {
+    out.push({ node, ancestorTestIDs: ancestors });
+    if (node.children?.length) {
+      const next = node.testID ? [...ancestors, node.testID] : ancestors;
+      out.push(...collectTextCandidates(node.children, next));
     }
   }
-  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 ");
+  return out;
 }
-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 nodeText(node) {
+  return node.text ?? node.label ?? "";
 }
-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` : ""}`;
+async function tapById(bridge, query, opts = {}) {
+  return tapResolvedTarget(bridge, {
+    agent: opts.agent,
+    timing: opts.timing,
+    resolve: async () => {
+      const resolved = await resolveTargetCoords(bridge, { mode: "testid", value: query });
+      if (!resolved) return { cx: null };
+      return payloadFromResolved(resolved, resolved);
     }
-    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");
+async function tapByText(bridge, query, options = {}, opts = {}) {
+  return tapResolvedTarget(bridge, {
+    agent: opts.agent,
+    timing: opts.timing,
+    textFallback: query,
+    resolve: async () => {
+      const { tree } = await inspectTree(bridge, 50);
+      if (!Array.isArray(tree)) return { matched: 0, total: 0 };
+      const needle = options.exact ? query : query.toLowerCase();
+      let candidates = collectTextCandidates(tree).filter(({ node: node2, ancestorTestIDs }) => {
+        const text = nodeText(node2);
+        if (!text) return false;
+        if (options.exact ? text !== needle : !text.toLowerCase().includes(needle)) {
+          return false;
+        }
+        if (options.role && node2.role !== options.role) return false;
+        if (options.within && !ancestorTestIDs.includes(options.within)) return false;
+        const ax = node2.geometry.x;
+        const ay = node2.geometry.y;
+        if (options.minX != null && !(ax >= options.minX)) return false;
+        if (options.maxX != null && !(ax <= options.maxX)) return false;
+        if (options.minY != null && !(ay >= options.minY)) return false;
+        if (options.maxY != null && !(ay <= options.maxY)) return false;
+        return true;
+      });
+      if (options.near) {
+        const { x, y } = options.near;
+        candidates.sort(
+          (a, b) => Math.hypot(a.node.geometry.x - x, a.node.geometry.y - y) - Math.hypot(b.node.geometry.x - x, b.node.geometry.y - y)
+        );
+      } else {
+        candidates.sort((a, b) => {
+          if (Math.abs(a.node.geometry.y - b.node.geometry.y) > 2) {
+            return a.node.geometry.y - b.node.geometry.y;
+          }
+          return a.node.geometry.x - b.node.geometry.x;
+        });
+      }
+      const total = candidates.length;
+      if (total === 0) return { matched: 0, total: 0 };
+      let idx = 0;
+      if (options.nth != null) {
+        idx = options.nth < 0 ? total + options.nth : options.nth;
+        if (idx < 0 || idx >= total) {
+          return { matched: 0, total, nthOutOfRange: true, nth: options.nth };
+        }
+      } else if (total > 1 && !options.first && !options.near) {
+        return {
+          ambiguous: true,
+          total,
+          candidates: candidates.slice(0, 10).map((candidate, index) => ({
+            idx: index,
+            nodeId: candidate.node.nodeId,
+            type: candidate.node.type,
+            testID: candidate.node.testID ?? null,
+            text: nodeText(candidate.node).slice(0, 60),
+            abs: { x: candidate.node.geometry.x, y: candidate.node.geometry.y },
+            layout: {
+              width: Math.round(candidate.node.geometry.width),
+              height: Math.round(candidate.node.geometry.height)
+            },
+            ancestorTestIDs: candidate.ancestorTestIDs.slice(0, 5)
+          }))
+        };
+      }
+      const picked = candidates[idx];
+      if (!picked) return { matched: 0, total };
+      const node = picked.node;
+      let resolved = node.testID ? await resolveTargetCoords(bridge, { mode: "testid", value: node.testID }) : await resolveTargetCoords(bridge, {
+        mode: "text",
+        value: nodeText(node) || query
+      });
+      if (!resolved) {
+        resolved = {
+          x: node.geometry.x + node.geometry.width / 2,
+          y: node.geometry.y + node.geometry.height / 2,
+          testID: node.testID ?? null,
+          text: nodeText(node) || query,
+          type: node.type
+        };
+      }
+      return payloadFromResolved(resolved, node, { total, idx });
+    }
+  });
 }
-
-// cli/commands/inspect/resolve-target.ts
-async function resolveTargetCoords(bridge, target) {
-  const result = await bridge.send({
-    type: "resolve",
-    selector: target.mode === "testid" ? { testID: target.value } : { text: target.value }
+async function tapBest(bridge, query, opts = {}) {
+  return tapResolvedTarget(bridge, {
+    agent: opts.agent,
+    timing: opts.timing,
+    textFallback: query,
+    resolve: async () => {
+      const byId = await resolveTargetCoords(bridge, { mode: "testid", value: query });
+      if (byId) {
+        return {
+          ...payloadFromResolved(byId, byId),
+          strategy: "testid",
+          node: {
+            nodeId: null,
+            id: byId.testID ?? query,
+            testID: byId.testID ?? query,
+            type: byId.type ?? null,
+            text: byId.text ?? null
+          }
+        };
+      }
+      const byText = await resolveTargetCoords(bridge, { mode: "text", value: query });
+      if (byText) {
+        return {
+          ...payloadFromResolved(byText, byText),
+          strategy: "text",
+          node: {
+            nodeId: null,
+            id: byText.testID ?? null,
+            testID: byText.testID ?? null,
+            type: byText.type ?? null,
+            text: byText.text ?? query
+          }
+        };
+      }
+      return { strategy: "none" };
+    }
   });
-  if (result === null) return null;
-  if (typeof result !== "object") throw new Error("resolve returned an invalid result");
-  const match = Reflect.get(result, "match");
-  const resolvedTarget = Reflect.get(result, "target");
-  const semanticNodes = [match, resolvedTarget];
-  const point = Reflect.get(result, "point");
-  const x = point !== null && typeof point === "object" ? Reflect.get(point, "x") : void 0;
-  const y = point !== null && typeof point === "object" ? Reflect.get(point, "y") : void 0;
-  if (!isSimSemanticTree(semanticNodes) || typeof x !== "number" || !Number.isFinite(x) || typeof y !== "number" || !Number.isFinite(y)) {
-    throw new Error("resolve returned an invalid result");
-  }
-  const semanticMatch = semanticNodes[0];
-  if (!semanticMatch) throw new Error("resolve returned an invalid result");
-  return {
-    x,
-    y,
-    testID: semanticMatch.testID ?? null,
-    text: semanticMatch.text ?? (target.mode === "text" ? target.value : semanticMatch.label),
-    type: semanticMatch.type
-  };
 }
 
 // src/app-url.ts