rnxsim 0.1.366 → 0.1.367

package/dist-lib/sdk.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.366 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.367 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
@@ -653,6 +653,15 @@ async function tapBest(bridge, query, opts = {}) {
   });
 }
 
+// src/bridge-contract.ts
+var SEMANTIC_READY_CONTENT_NODE_FLOOR = 100;
+function readyProbeHasContent(probe) {
+  return probe.liveFrameActive || probe.targets > 0 || probe.nodes >= SEMANTIC_READY_CONTENT_NODE_FLOOR;
+}
+function readyProbeHasTargetContent(probe) {
+  return probe.liveFrameActive || probe.targets > 0;
+}
+
 // cli/commands/inspect/core.ts
 function resolveMaxMsFlag(args, fallbackMs) {
   const aliases = ["--max-ms", "--maxMs", "--maxms", "--max_ms"];
@@ -692,121 +701,116 @@ async function shouldSkipAutoSettleForInspectPick(bridge, subcommand) {
   }
 }
 async function inspectNodeCount(bridge) {
-  const count = await bridge.send({
-    type: "evaluate",
-    code: "(async () => await window.__sootsimTest.getNodeCount())()"
+  const result = await bridge.send({
+    type: "query",
+    query: { kind: "count" }
   });
-  return { nodes: typeof count === "number" ? count : 0 };
+  return { nodes: isSemanticQueryResult(result) ? result.total : 0 };
 }
-async function inspectTree(bridge, depth = 5, opts) {
-  const optsArg = opts?.format ? `, ${JSON.stringify(opts)}` : "";
-  const tree = await bridge.send({
-    type: "evaluate",
-    code: `(async () => await window.__sootsimTest.dumpTree(${depth}${optsArg}))()`
+async function inspectTree(bridge, depth = 5) {
+  const result = await bridge.send({
+    type: "query",
+    query: { kind: "tree", depth }
   });
-  if (opts?.format === "boxes" && typeof tree === "string") {
-    try {
-      return { depth, tree: JSON.parse(tree) };
-    } catch {
-      return { depth, tree };
-    }
-  }
+  const tree = isSemanticQueryResult(result) ? result.nodes : [];
   return { depth, tree };
 }
 async function inspectUrl(bridge) {
   const url = await bridge.send({ type: "evaluate", code: "window.location.href" });
   return { url: typeof url === "string" ? url : "" };
 }
-async function inspectDescribe(bridge, dumpOpts) {
-  const dumpDepth = dumpOpts.maxDepth ?? 12;
-  const code = `(async () => {
-      const t = window.__sootsimTest
-      const mainShell = window.SootSim?.bridges?.mainShell
-      const kb = window.__sootsimKeyboard
-      if (!t) return { error: 'no test bridge' }
-
-      let shell = null
-      try {
-        shell = typeof mainShell?.getState === 'function' ? await mainShell.getState() : null
-      } catch {}
-
-      const opts = ${JSON.stringify(dumpOpts)}
-      const needsRecursiveDump =
-        opts.verbose || opts.subtreeRoot || opts.includeOccluded || opts.maxDepth != null
-      const globToRegex = (glob) => {
-        const escaped = String(glob).replace(/[.+^$(){}|[\\]\\\\]/g, '\\\\$&')
-        const body = escaped.replace(/\\*/g, '.*').replace(/\\?/g, '.')
-        return new RegExp('^' + body + '$', 'i')
-      }
-      // clipping a describe line is a DISPLAY decision. opts.fullText (set by
-      // \`describe --json\`) keeps the real string, so a bundle-eval stack or a
-      // red-box message reaches the caller whole instead of ending in an
-      // ellipsis nothing downstream can undo.
-      const clipForDisplay = (value, max) => {
-        const text = typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''
-        if (opts.fullText || text.length <= max) return text
-        return text.slice(0, max - 1).trimEnd() + '\u2026'
+function isSemanticGeometry(value) {
+  return value !== null && typeof value === "object" && [
+    Reflect.get(value, "x"),
+    Reflect.get(value, "y"),
+    Reflect.get(value, "width"),
+    Reflect.get(value, "height")
+  ].every(
+    (coordinate) => typeof coordinate === "number" ? Number.isFinite(coordinate) : false
+  );
+}
+function isSimSemanticTree(value) {
+  if (!Array.isArray(value)) return false;
+  return value.every((node) => {
+    if (node === null || typeof node !== "object" || !Number.isInteger(Reflect.get(node, "nodeId")) || typeof Reflect.get(node, "type") !== "string" || !isSemanticGeometry(Reflect.get(node, "geometry"))) {
+      return false;
+    }
+    for (const key of ["testID", "text", "role", "label"]) {
+      const value2 = Reflect.get(node, key);
+      if (value2 !== void 0 && typeof value2 !== "string") return false;
+    }
+    const pressable = Reflect.get(node, "pressable");
+    if (pressable !== void 0 && pressable !== true) return false;
+    const children = Reflect.get(node, "children");
+    return children === void 0 || isSimSemanticTree(children);
+  });
+}
+function isSemanticQueryResult(value) {
+  const total = value !== null && typeof value === "object" ? Reflect.get(value, "total") : void 0;
+  return value !== null && typeof value === "object" && typeof total === "number" && Number.isInteger(total) && total >= 0 && isSimSemanticTree(Reflect.get(value, "nodes"));
+}
+function globRegex(glob) {
+  const escaped = glob.replace(/[.+^$(){}|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`, "i");
+}
+function formatSemanticTree(nodes, opts = {}) {
+  const filter = opts.filter?.toLowerCase() ?? "";
+  const testIDRegex = opts.testIdLike ? globRegex(opts.testIdLike) : null;
+  const onlyRegex = opts.onlyGlob ? globRegex(opts.onlyGlob) : null;
+  const lines = [];
+  const visit = (node, indent) => {
+    const joined = [node.role, node.label, node.text, node.testID].filter((value) => typeof value === "string").join(" ");
+    const matches = (!filter || joined.toLowerCase().includes(filter)) && (!testIDRegex || testIDRegex.test(node.testID ?? "")) && (!onlyRegex || onlyRegex.test(joined));
+    if (matches) {
+      const parts = [
+        node.role ? `[${node.role}]` : node.pressable ? "[tap]" : `<${node.type}>`
+      ];
+      if (node.text) {
+        const text = opts.fullText || node.text.length <= 50 ? node.text : `${node.text.slice(0, 49).trimEnd()}\u2026`;
+        parts.push(JSON.stringify(text));
       }
-      const formatInspectableTree = async () => {
-        if (typeof t.listInspectable !== 'function') return null
-        const list = await t.listInspectable({})
-        if (!Array.isArray(list)) return null
-        const filter = typeof opts.filter === 'string' ? opts.filter.toLowerCase() : ''
-        const testIdRegex = opts.testIdLike ? globToRegex(opts.testIdLike) : null
-        const onlyRegex = opts.onlyGlob ? globToRegex(opts.onlyGlob) : null
-        const lines = []
-        let matched = 0
-        for (const node of list) {
-          const testID = node?.testID || node?.testId || ''
-          const role = node?.role || ''
-          const label = node?.accessibilityLabel || node?.label || ''
-          const text = node?.text || ''
-          if (testIdRegex && !testIdRegex.test(testID)) continue
-          const joined = [role, label, text, testID].filter(Boolean).join(' ')
-          if (onlyRegex && !onlyRegex.test(joined)) continue
-          if (filter && !joined.toLowerCase().includes(filter)) continue
-          matched++
-
-          const type = String(node?.type || 'node').toLowerCase()
-          const handlers = Array.isArray(node?.handlers) ? node.handlers : []
-          const parts = []
-          if (role) parts.push('[' + role + ']')
-          else if (handlers.length > 0) parts.push('[tap]')
-          else parts.push('<' + type + '>')
-          const visibleText = clipForDisplay(text, 50)
-          if (visibleText) parts.push(JSON.stringify(visibleText))
-          if (testID) parts.push('#' + testID)
-          if (label && label !== text) {
-            parts.push('label=' + JSON.stringify(clipForDisplay(label, 50)))
-          }
-          if (!opts.hideXy) {
-            const abs = node?.absolute || {}
-            const layout = node?.layout || {}
-            const x = Math.round(Number(abs.x) || 0)
-            const y = Math.round(Number(abs.y) || 0)
-            const w = Math.round(Number(layout.width) || 0)
-            const h = Math.round(Number(layout.height) || 0)
-            parts.push('@(' + x + ',' + y + ') ' + w + 'x' + h)
-          }
-          if (handlers.length > 0) parts.push('(tap)')
-          lines.push('  ' + parts.join(' '))
-        }
-        return { tree: lines.join('\\n'), matched }
+      if (node.testID) parts.push(`#${node.testID}`);
+      if (node.label && node.label !== node.text) {
+        parts.push(`label=${JSON.stringify(node.label)}`);
       }
-
-      let tree = ''
-      const compactResult = needsRecursiveDump ? null : await formatInspectableTree()
-      if (compactResult) {
-        tree = compactResult.tree
-      } else {
-        tree = await t.dumpTree(${dumpDepth}, opts)
+      if (!opts.hideXy) {
+        const geometry = node.geometry;
+        parts.push(
+          `@(${Math.round(geometry.x)},${Math.round(geometry.y)}) ${Math.round(geometry.width)}x${Math.round(geometry.height)}`
+        );
       }
-      const nodeCount = (await t.getNodeCount?.()) || 0
-      const keyboard = kb && typeof kb.getLayout === 'function' ? kb.getLayout() : null
-      return { tree, shell, nodeCount, keyboard }
-    })()`;
-  const result = await bridge.send({ type: "evaluate", code });
-  return result ?? {};
+      if (node.pressable) parts.push("(tap)");
+      lines.push(`${"  ".repeat(indent + 1)}${parts.join(" ")}`);
+    }
+    for (const child of node.children ?? []) visit(child, indent + 1);
+  };
+  let roots = nodes;
+  if (opts.subtreeRoot) {
+    const pending = [...nodes];
+    let found;
+    while (pending.length > 0 && !found) {
+      const candidate = pending.shift();
+      if (!candidate) continue;
+      if (candidate.testID === opts.subtreeRoot) found = candidate;
+      else pending.push(...candidate.children ?? []);
+    }
+    if (!found) return `__SUBTREE_NOT_FOUND__:${opts.subtreeRoot}`;
+    roots = [found];
+  }
+  for (const root of roots) visit(root, 0);
+  return lines.join("\n");
+}
+async function inspectDescribe(bridge, dumpOpts) {
+  const dumpDepth = dumpOpts.maxDepth ?? 12;
+  const result = await bridge.send({
+    type: "query",
+    query: { kind: "tree", depth: dumpDepth }
+  });
+  if (!isSemanticQueryResult(result)) return {};
+  return {
+    tree: formatSemanticTree(result.nodes, dumpOpts),
+    nodeCount: result.total
+  };
 }
 function scoreLayoutTextContrast(input) {
   const required = input.fontSize >= 18 || input.fontSize >= 14 && (input.fontWeight ?? 400) >= 700 ? 3 : 4.5;
@@ -1021,9 +1025,6 @@ function layoutGetNativeEval(opts = {}) {
           type: typeof n.type === 'string' ? n.type : 'node',
           text,
           box: { x: round(abs.x), y: round(abs.y), w: round(layout.width), h: round(layout.height) },
-          borderRadius: 0,
-          padding: { t: 0, r: 0, b: 0, l: 0 },
-          fontSize: 0,
         }
         if (!includeStyle) return base
         // computedStyle has the resolved values; style is the curated subset \u2014
@@ -1094,6 +1095,32 @@ function layoutGetNativeEval(opts = {}) {
 }
 var LAYOUT_GET_NATIVE_EVAL = layoutGetNativeEval();
 async function inspectGetLayout(bridge, opts = {}) {
+  if (!opts.styling) {
+    const result = await bridge.send({
+      type: "query",
+      query: { kind: "find", selector: { visible: true } }
+    });
+    if (!isSemanticQueryResult(result)) return [];
+    const filter = opts.filter?.trim().toLowerCase() ?? "";
+    return result.nodes.filter((node) => {
+      if (!filter) return true;
+      return [node.text, node.testID, node.role, node.type].some(
+        (value) => typeof value === "string" && value.toLowerCase().includes(filter)
+      );
+    }).map((node) => ({
+      nodeId: node.nodeId,
+      ...node.testID ? { testID: node.testID } : {},
+      ...node.role ? { role: node.role } : {},
+      type: node.type,
+      ...node.text ? { text: node.text } : {},
+      box: {
+        x: Math.round(node.geometry.x),
+        y: Math.round(node.geometry.y),
+        w: Math.round(node.geometry.width),
+        h: Math.round(node.geometry.height)
+      }
+    }));
+  }
   const raw = await bridge.send({
     type: "evaluate",
     code: layoutGetNativeEval(opts)
@@ -1105,13 +1132,17 @@ function formatLayoutElements(elements, opts) {
   const lines = elements.map((el) => {
     const ident = el.testID ? `#${el.testID}` : el.selector ? el.selector : el.role ? `[${el.role}]` : `<${el.type}>`;
     const parts = [ident, `@(${el.box.x},${el.box.y})`, `${el.box.w}x${el.box.h}`];
-    if (el.borderRadius > 0) parts.push(`radius:${el.borderRadius}`);
+    if (el.borderRadius !== void 0 && el.borderRadius > 0) {
+      parts.push(`radius:${el.borderRadius}`);
+    }
     const p = el.padding;
-    if (p.t || p.r || p.b || p.l) {
+    if (p && (p.t || p.r || p.b || p.l)) {
       const uniform = p.t === p.r && p.r === p.b && p.b === p.l;
       parts.push(uniform ? `pad:${p.t}` : `pad:${p.t},${p.r},${p.b},${p.l}`);
     }
-    if (el.fontSize > 0) parts.push(`font:${el.fontSize}`);
+    if (el.fontSize !== 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}`);
@@ -1138,246 +1169,80 @@ function formatLayoutElements(elements, opts) {
   });
   return lines.join("\n");
 }
-var INSPECT_A11Y_CODE = `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-
-      const readLayout = (n) => n?.layout || null
-      const readAbs = (n) => n?.absolutePosition || n?.absolute || null
-      const readRole = (n) => n?.accessibilityRole || n?.role || null
-      const readLabel = (n) => n?.accessibilityLabel || n?.label || n?.text || null
-      const readHint = (n) => n?.accessibilityHint || n?.hint || null
-      const readState = (n) => n?.accessibilityState || n?.state || null
-      const readTestId = (n) => n?.testID || n?.testId || null
-      const readType = (n) => typeof n?.type === 'string' ? n.type.toLowerCase() : n?.type
-      const readPressable = (n) => {
-        if (n?.pressable) return true
-        const handlers = Array.isArray(n?.handlers) ? n.handlers : []
-        const role = readRole(n)
-        return handlers.length > 0 || role === 'button' || role === 'link' || role === 'tab'
-      }
-      const isTextInput = (n) => n?.isTextInput === true
-      const isTextNode = (n) => readType(n) === 'text'
-      const isVisibleTarget = (n) => {
-        const layout = readLayout(n)
-        if (!layout || layout.width <= 0 || layout.height <= 0) return false
-        const abs = readAbs(n)
-        if (!abs) return true
-        const device = n?.device || {}
-        const screenW = Number(device.width) || window.innerWidth || 0
-        const screenH = Number(device.height) || window.innerHeight || 0
-        return (
-          abs.x + layout.width > 0 &&
-          abs.y + layout.height > 0 &&
-          abs.x < screenW &&
-          abs.y < screenH
-        )
-      }
-      const hasAccessibleSignal = (n) => {
-        const role = readRole(n)
-        const label = readLabel(n)
-        const hint = readHint(n)
-        if (role) return true
-        if (hint) return true
-        if (isTextInput(n)) return true
-        if (readPressable(n)) return true
-        if (isTextNode(n) && n?.text) return true
-        if (typeof label === 'string' && label.length <= 30 && label !== n?.text) return true
-        return false
-      }
-      const normalize = (n) => {
-        const layout = readLayout(n)
-        const abs = readAbs(n)
-        const role = readRole(n) || (readPressable(n) ? 'button' : isTextInput(n) ? 'textfield' : isTextNode(n) ? 'statictext' : 'none')
-        return {
-          role,
-          label: readLabel(n),
-          hint: readHint(n),
-          state: readState(n),
-          testID: readTestId(n),
-          position: abs ? { x: Math.round(abs.x), y: Math.round(abs.y) } : null,
-          size: layout ? { w: Math.round(layout.width), h: Math.round(layout.height) } : null,
-        }
-      }
-
-      if (typeof t.listInspectable === 'function') {
-        const list = await t.listInspectable({})
-        if (Array.isArray(list)) {
-          return list.filter(n => isVisibleTarget(n) && hasAccessibleSignal(n)).map(normalize)
-        }
-      }
-
-      const all = await t.queryAll({ pruneHidden: true })
-      return all
-        .filter(n => isVisibleTarget(n) && hasAccessibleSignal(n))
-        .map(normalize)
-    })()`;
 async function inspectAccessibilityTree(bridge) {
-  const nodes = await bridge.send({ type: "evaluate", code: INSPECT_A11Y_CODE });
-  return Array.isArray(nodes) ? nodes : [];
-}
-var FIND_INSPECTABLE_TARGETS = `
-      const fromInspectable = async () => {
-        if (typeof t.listInspectable !== 'function') return null
-        const list = await t.listInspectable({})
-        if (!Array.isArray(list)) return null
-        return list.map((n) => {
-          const role = n.accessibilityRole ?? n.role
-          const label = n.accessibilityLabel ?? n.label
-          const layout = n.layout
-          const absolutePosition = n.absolutePosition ?? n.absolute
-          const screenW = Number(n.device?.width) || window.innerWidth || 0
-          const screenH = Number(n.device?.height) || window.innerHeight || 0
-          const visibleFrame = layout && absolutePosition
-            ? {
-                x: Math.max(0, absolutePosition.x),
-                y: Math.max(0, absolutePosition.y),
-                width: Math.max(
-                  0,
-                  Math.min(screenW, absolutePosition.x + layout.width) -
-                    Math.max(0, absolutePosition.x),
-                ),
-                height: Math.max(
-                  0,
-                  Math.min(screenH, absolutePosition.y + layout.height) -
-                    Math.max(0, absolutePosition.y),
-                ),
-              }
-            : null
-          const handlers = Array.isArray(n.handlers) ? n.handlers : []
-          const pressable =
-            handlers.length > 0 ||
-            role === 'button' ||
-            role === 'link' ||
-            role === 'tab'
-          return {
-            type: typeof n.type === 'string' ? n.type.toLowerCase() : n.type,
-            id: n.id ?? n.nodeId,
-            nodeId: n.nodeId,
-            testID: n.testID ?? n.testId,
-            text: n.text,
-            layout,
-            absolutePosition,
-            visibleFrame,
-            style: n.computedStyle ?? n.style ?? {},
-            childCount: n.childCount ?? 0,
-            pressed: n.pressed ?? false,
-            pressable,
-            isTextInput: n.isTextInput ?? false,
-            accessible: n.accessible ?? true,
-            accessibilityLabel: label,
-            accessibilityRole: role,
-            accessibilityHint: n.accessibilityHint,
-            accessibilityState: n.accessibilityState,
-            accessibilityValue: n.accessibilityValue,
-          }
-        })
-      }
-      const isVisibleTarget = (n) => {
-        if (!n?.layout) return false
-        const frame = n.visibleFrame
-        if (frame) return frame.width > 0 && frame.height > 0
-        const abs = n.absolutePosition
-        if (!abs) return n.layout.width > 0 && n.layout.height > 0
-        const screenW = window.innerWidth || 0
-        const screenH = window.innerHeight || 0
-        return (
-          abs.x + n.layout.width > 0 &&
-          abs.y + n.layout.height > 0 &&
-          abs.x < screenW &&
-          abs.y < screenH
-        )
+  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",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return null
-      return (await t.findByTestId(${JSON.stringify(q.testId)})) || (await t.findById(${JSON.stringify(q.testId)}))
-    })()`
-    };
+    return { mode: "testid", selector: { testID: q.testId } };
   }
   if (q.role) {
-    return {
-      mode: "role",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-      return await t.queryAll({ hasRole: ${JSON.stringify(q.role)}, pruneHidden: true })
-    })()`
-    };
+    return { mode: "role", selector: { role: q.role } };
   }
   if (q.type) {
-    return {
-      mode: "type",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-      return await t.queryAll({ type: ${JSON.stringify(q.type)}, pruneHidden: true })
-    })()`
-    };
+    return { mode: "type", selector: { type: q.type } };
   }
   if (q.pressable) {
-    return {
-      mode: "pressable",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-${FIND_INSPECTABLE_TARGETS}
-      const inspectable = await fromInspectable()
-      if (inspectable) return inspectable.filter(n => n.pressable && isVisibleTarget(n))
-      const all = await t.queryAll({ pruneHidden: true })
-      return all.filter(n => n.pressable && isVisibleTarget(n))
-    })()`
-    };
+    return { mode: "pressable", selector: { pressable: true } };
   }
   if (q.interactive) {
-    return {
-      mode: "interactive-targets",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-${FIND_INSPECTABLE_TARGETS}
-      const inspectable = await fromInspectable()
-      if (inspectable) {
-        return inspectable.filter(n => n.pressable && isVisibleTarget(n))
-      }
-      const all = await t.queryAll({ pruneHidden: true })
-      return all.filter(n => n.pressable && isVisibleTarget(n))
-    })()`
-    };
+    return { mode: "interactive-targets", selector: { pressable: true } };
   }
   if (q.visible) {
-    return {
-      mode: "visible",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return []
-      const all = await t.queryAll({ pruneHidden: true })
-      return all.filter(n => n.layout && n.layout.width > 0 && n.layout.height > 0)
-    })()`
-    };
+    return { mode: "visible", selector: { visible: true } };
   }
   if (q.text) {
-    return {
-      mode: "text",
-      code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return null
-      return await t.findByText(${JSON.stringify(q.text)})
-    })()`
-    };
+    return { mode: "text", selector: { text: q.text } };
   }
   return null;
 }
 async function inspectFind(bridge, q) {
   const resolved = resolveFindMode(q);
   if (!resolved) return null;
-  const result = await bridge.send({ type: "evaluate", code: resolved.code });
-  return { mode: resolved.mode, result };
+  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));
@@ -1411,158 +1276,6 @@ function shellEscape(value) {
   if (/^[A-Za-z0-9_./@:-]+$/.test(value)) return value;
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-var WAIT_READY_PROBE = `(async () => {
-    const t = window.__sootsimTest
-    let nodes = 0
-    try { nodes = (await t?.getNodeCount?.()) || 0 } catch {}
-    let targets = 0
-    let liveFrameActive = false
-    let liveFrameChannels = 0
-    let liveFramePublishes = 0
-    let loadingText = ''
-    const cleanText = (value) =>
-      typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''
-    const loadingSignal = (value) => {
-      const text = cleanText(value)
-      if (!text) return ''
-      return /^(opening app\\b|looking for your app\\b|building bundle\\b|preparing rnx runtime\\b|loading native bundle\\b|loading rnx stubs\\b|loading bundle loader\\b|loading native stubs\\b|loading compat bridge\\b|loading react-native shim\\b|loading react bridge\\b|loading reconciler\\b|loading replacement modules\\b|injecting rnx modules\\b|warming sqlite engine\\b|capturing root component\\b|reloading app\\b|loading(?:[.!\u2026]*)?$|connecting(?:[.!\u2026]*)?$)/i.test(text)
-        ? text
-        : ''
-    }
-    try {
-      const loading = window.__sootsimConnectRNLoading
-      if (loading && loading.active === true) {
-        loadingText = [loading.title, loading.detail].map(cleanText).filter(Boolean).join(' ')
-      }
-    } catch {}
-    try {
-      if (typeof t?.listInspectable === 'function') {
-        const list = await t.listInspectable({})
-        if (Array.isArray(list)) {
-          const screenW = window.innerWidth || 0
-          const screenH = window.innerHeight || 0
-          const isVisible = (n) => {
-            const layout = n?.layout
-            if (!layout || layout.width <= 0 || layout.height <= 0) return false
-            const abs = n?.absolutePosition || n?.absolute
-            if (!abs) return true
-            const device = n?.device || {}
-            const w = Number(device.width) || screenW
-            const h = Number(device.height) || screenH
-            return (
-              abs.x + layout.width > 0 &&
-              abs.y + layout.height > 0 &&
-              abs.x < w &&
-              abs.y < h
-            )
-          }
-          const hasContentSignal = (n) => {
-            const role = n?.accessibilityRole || n?.role
-            const label = cleanText(n?.accessibilityLabel || n?.label)
-            const handlers = Array.isArray(n?.handlers) ? n.handlers : []
-            const text = cleanText(n?.text)
-            const testID = cleanText(n?.testID || n?.testId)
-            const loading = loadingSignal(text) || loadingSignal(label) || loadingSignal(testID)
-            if (!loadingText && loading) {
-              loadingText = loading
-            }
-            if (handlers.length > 0) return true
-            if (role) return true
-            if (n?.isTextInput) return true
-            if (text) return true
-            if (label) return true
-            if (testID && !/^splash|loading/i.test(testID)) return true
-            return false
-          }
-          targets = list.filter(n => isVisible(n) && hasContentSignal(n)).length
-        }
-      }
-    } catch {}
-    try {
-      const stats = await t?.getImageLoaderStats?.()
-      const presentation = stats?.liveFramePresentation
-      liveFrameChannels = Number(presentation?.activeChannels) || 0
-      liveFramePublishes = Number(presentation?.publishes) || 0
-      const previous = window.__sootsimWaitReadyLiveFramePublishes
-      liveFrameActive =
-        liveFrameChannels > 0 &&
-        typeof previous === 'number' &&
-        liveFramePublishes > previous
-      window.__sootsimWaitReadyLiveFramePublishes = liveFramePublishes
-    } catch {}
-    let externalReady = null
-    let externalStatus = ''
-    let externalError = ''
-    let suppressedEntryError = ''
-    try {
-      const getExternalAppState = t?.getExternalAppState
-      const external = typeof getExternalAppState === 'function'
-        ? await Promise.race([
-            getExternalAppState(),
-            new Promise((resolve) => setTimeout(
-              () => resolve({
-                state: {
-                  ready: false,
-                  loading: true,
-                  status: 'waiting for tenant worker...',
-                },
-              }),
-              1000,
-            )),
-          ])
-        : null
-      const state = external?.state
-      if (state && typeof state === 'object') {
-        externalReady = state.ready === true
-        if (typeof state.status === 'string') externalStatus = state.status
-        if (typeof state.error === 'string') externalError = state.error
-      }
-      if (!externalError && Array.isArray(external?.entryErrors)) {
-        // suppressed-and-continued entry errors (bundle-loader's patched __r
-        // swallows entry throws and moves on) must NOT gate readiness \u2014 the
-        // app frequently runs fine after one (e.g. metro's "Unknown named
-        // module" probing noise). they surface separately as a diagnostic
-        // for the timeout path.
-        const isReal = (item) => item && typeof item.message === 'string' && item.message.trim()
-        const fatal = external.entryErrors.find((item) => isReal(item) && item.suppressed !== true)
-        if (fatal) externalError = fatal.message
-        const suppressed = external.entryErrors.find((item) => isReal(item) && item.suppressed === true)
-        if (suppressed) suppressedEntryError = suppressed.message
-      }
-      // once the app has errored its last status ("injecting sootsim
-      // modules...") is stale \u2014 reporting it makes a dead app read as one that
-      // is still booting.
-      if (externalError) loadingText = ''
-      else if (externalReady === false && externalStatus) loadingText = externalStatus
-    } catch {}
-    let errors = 0
-    try { errors = window.__sootsimConsole?.count?.()?.errors ?? 0 } catch {}
-    return {
-      flag: (window).__sootsimExternalAppReady,
-      at: (window).__sootsimExternalAppReadyAt || 0,
-      nodes,
-      targets,
-      liveFrameActive,
-      liveFrameChannels,
-      liveFramePublishes,
-      errors,
-      loadingText,
-      externalReady,
-      externalStatus,
-      externalError,
-      suppressedEntryError,
-    }
-  })()`;
-var READY_CONTENT_NODE_FLOOR = 100;
-var READY_NODE_STABLE_MS = 750;
-var WAIT_READY_PROGRESS_INTERVAL_MS = 2e3;
-var READY_PROBE_POLL_MS = 150;
-function readyProbeHasContent(probe) {
-  return probe.liveFrameActive || probe.targets > 0 || probe.nodes >= READY_CONTENT_NODE_FLOOR;
-}
-function readyProbeHasTargetContent(probe) {
-  return probe.liveFrameActive || probe.targets > 0;
-}
 function waitReadyReason(status) {
   if (status.bridgeError) {
     return `sim unreachable: ${status.bridgeError} \u2014 the target tab is closed or no sim is connected (check \`rnx list\`, reopen with \`rnx open\`)`;
@@ -1572,155 +1285,69 @@ function waitReadyReason(status) {
 }
 async function inspectWaitReady(bridge, timeoutMs = 2e4, options = {}) {
   const start = Date.now();
-  const deadline = start + timeoutMs;
-  const progressIntervalMs = options.progressIntervalMs ?? WAIT_READY_PROGRESS_INTERVAL_MS;
-  let nextProgressAt = start + progressIntervalMs;
-  let lastNodes = -1;
-  let nodeStableSince = start;
-  let bridgeError = "";
-  let last = {
-    flag: void 0,
-    at: 0,
-    nodes: 0,
-    targets: 0,
-    liveFrameActive: false,
-    liveFrameChannels: 0,
-    liveFramePublishes: 0,
-    errors: 0,
-    loadingText: "",
-    externalReady: null,
-    externalStatus: "",
-    externalError: "",
-    suppressedEntryError: ""
-  };
-  while (Date.now() < deadline) {
-    try {
-      last = await bridge.send({ type: "evaluate", code: WAIT_READY_PROBE }) ?? last;
-      bridgeError = "";
-    } catch (error) {
-      bridgeError = error instanceof Error ? error.message : String(error);
-      if (bridgeError.startsWith("multiple sims are connected:") || bridgeError.startsWith("saved sim ")) {
-        throw error;
-      }
+  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;
     }
-    const now = Date.now();
-    const status2 = {
-      ready: false,
-      elapsedMs: now - start,
-      nodes: last.nodes,
-      targets: last.targets,
-      liveFrameActive: last.liveFrameActive,
-      liveFrameChannels: last.liveFrameChannels,
-      liveFramePublishes: last.liveFramePublishes,
-      flag: last.flag,
-      loadingText: last.loadingText,
-      externalReady: last.externalReady,
-      externalStatus: last.externalStatus,
-      externalError: last.externalError,
-      suppressedEntryError: last.suppressedEntryError,
-      errors: last.errors,
-      bridgeError
+    result = {
+      matched: false,
+      elapsedMs: Date.now() - start,
+      polls: 0,
+      error: bridgeError
     };
-    if (last.nodes !== lastNodes) {
-      lastNodes = last.nodes;
-      nodeStableSince = now;
-    }
-    const hasReadySignal = last.flag === true && readyProbeHasContent(last);
-    const hasRenderedContentWithoutReadySignal = last.flag !== true && readyProbeHasTargetContent(last);
-    if ((hasReadySignal || hasRenderedContentWithoutReadySignal) && last.externalReady !== false && !last.externalError && !last.loadingText) {
-      if (now - nodeStableSince >= READY_NODE_STABLE_MS) {
-        return {
-          ...status2,
-          ready: true
-        };
-      }
-    }
-    if (last.externalError) return status2;
-    if (options.onProgress && progressIntervalMs > 0 && now >= nextProgressAt) {
-      options.onProgress(status2);
-      do {
-        nextProgressAt += progressIntervalMs;
-      } while (now >= nextProgressAt);
-    }
-    await new Promise((r) => setTimeout(r, READY_PROBE_POLL_MS));
   }
+  const probe = result.probe;
   const status = {
-    ready: false,
-    elapsedMs: Date.now() - start,
-    nodes: last.nodes,
-    targets: last.targets,
-    liveFrameActive: last.liveFrameActive,
-    liveFrameChannels: last.liveFrameChannels,
-    liveFramePublishes: last.liveFramePublishes,
-    flag: last.flag,
-    loadingText: last.loadingText,
-    externalReady: last.externalReady,
-    externalStatus: last.externalStatus,
-    externalError: last.externalError,
-    suppressedEntryError: last.suppressedEntryError,
-    errors: last.errors,
-    bridgeError
+    ready: result.matched,
+    elapsedMs: result.elapsedMs,
+    nodes: probe?.nodes ?? 0,
+    targets: probe?.targets ?? 0,
+    liveFrameActive: probe?.liveFrameActive ?? false,
+    liveFrameChannels: probe?.liveFrameChannels ?? 0,
+    liveFramePublishes: probe?.liveFramePublishes ?? 0,
+    flag: probe?.flag,
+    loadingText: probe?.loadingText ?? "",
+    externalReady: probe?.externalReady ?? null,
+    externalStatus: probe?.externalStatus ?? "",
+    externalError: probe?.externalError ?? "",
+    suppressedEntryError: probe?.suppressedEntryError ?? "",
+    errors: probe?.errors ?? 0,
+    bridgeError: result.error ?? ""
   };
-  if (options.onProgress && progressIntervalMs > 0 && Date.now() >= nextProgressAt) {
-    options.onProgress(status);
-  }
+  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: "evaluate",
-      code: `(async () => {
-      const start = Date.now()
-      const deadline = start + ${timeoutMs}
-      const gone = ${gone}
-      const ID = ${JSON.stringify(testId)}
-      const present = (node) => !!(node && node.layout && node.layout.width > 0 && node.layout.height > 0)
-      const find = async () => {
-        const t = window.__sootsimTest
-        if (!t) return undefined // bridge not ready \u2014 indeterminate, not "gone"
-        try {
-          // gone-mode confirms a gate/screen LEFT \u2014 it only needs structural
-          // existence + layout, NOT the full-tree occlusion pass (pruneHidden).
-          // that pass (computeOccludedInspectNodeIds) walks the whole tree and
-          // does O(n\xB2)-ish rect-occlusion testing EVERY poll; on a large
-          // post-login app tree it costs seconds per poll, so --gone can never
-          // get two clean "absent" polls inside budget and falsely reports the
-          // gate as still blocked \u2014 the root cause of the 3pc PR-preview outage.
-          // presence-mode keeps pruneHidden so "appeared" still means
-          // visibly-reachable. a departed gate is unmounted or zero-sized, so the
-          // cheap structural+layout check is correct here and ~O(n) cheap.
-          const matches = await t.queryAll?.(gone ? { hasId: ID } : { hasId: ID, pruneHidden: true })
-          if (!Array.isArray(matches)) return undefined
-          return matches.find(present) || null
-        } catch {
-          return undefined
-        }
-      }
-      let goneStreak = 0
-      while (Date.now() < deadline) {
-        const node = await find()
-        if (gone) {
-          if (node === null) {
-            goneStreak += 1
-            if (goneStreak >= 2) return { found: true, elapsed: Date.now() - start }
-          } else {
-            goneStreak = 0
-          }
-        } else if (present(node)) {
-          return { found: true, node, elapsed: Date.now() - start }
-        }
-        await new Promise((r) => setTimeout(r, 80))
+      type: "waitFor",
+      waitForOptions: {
+        condition: { type: gone ? "absent" : "present", testID: testId },
+        timeoutMs
       }
-      return { found: false, elapsed: Date.now() - start }
-    })()`
     },
-    {
-      timeoutMs: timeoutMs + 1e3
-    }
+    { timeoutMs: timeoutMs + 1e3 }
   );
-  return result ?? { found: false, elapsed: timeoutMs };
+  if (result?.error) throw new Error(result.error);
+  if (result?.node && !isSimSemanticTree([result.node])) {
+    throw new Error("waitFor returned an invalid semantic node");
+  }
+  return {
+    found: result?.matched === true,
+    ...result?.node ? { node: result.node } : {},
+    elapsed: result?.elapsedMs ?? timeoutMs
+  };
 }
 function consoleEntriesEval(level, limit) {
   const getter = level === "error" ? "getErrors" : "getWarnings";
@@ -2183,38 +1810,30 @@ function formatTimelineEvents(events) {
 
 // cli/commands/inspect/resolve-target.ts
 async function resolveTargetCoords(bridge, target) {
-  const arg = JSON.stringify(target.value);
-  const findExpr = target.mode === "testid" ? `(await t.findByTestId(${arg})) || (await t.findById(${arg}))` : `await t.findByText(${arg})`;
   const result = await bridge.send({
-    type: "evaluate",
-    code: `(async () => {
-      const t = window.__sootsimTest
-      if (!t) return null
-      const n = ${findExpr}
-      if (!n || !n.absolutePosition || !n.layout) return null
-      const resolved =
-        typeof n.nodeId === 'number' && typeof t.resolveTapTarget === 'function'
-          ? await t.resolveTapTarget(n.nodeId)
-          : null
-      const cx =
-        typeof resolved?.cx === 'number'
-          ? resolved.cx
-          : n.absolutePosition.x + (n.layout.width || 0) / 2
-      const cy =
-        typeof resolved?.cy === 'number'
-          ? resolved.cy
-          : n.absolutePosition.y + (n.layout.height || 0) / 2
-      return {
-        x: cx,
-        y: cy,
-        id: n.id ?? null,
-        testID: n.testID ?? null,
-        text: ${JSON.stringify(target.mode === "text")} ? ${arg} : (n.text ?? n.accessibilityLabel ?? null),
-        type: n.type ?? null,
-      }
-    })()`
+    type: "resolve",
+    selector: target.mode === "testid" ? { testID: target.value } : { text: target.value }
   });
-  return result ?? null;
+  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
@@ -2452,9 +2071,12 @@ var SimClient = class {
   }
   async tree(depth = 5) {
     const { tree } = await inspectTree(this, depth);
-    return tree;
+    return Array.isArray(tree) ? tree : [];
+  }
+  resolve(selector) {
+    return this.send({ type: "resolve", selector });
   }
-  /** compact visible-UI dump with shell + keyboard state, as the CLI prints. */
+  /** compact visible semantic tree, formatted as the CLI prints it. */
   describe(opts = {}) {
     return inspectDescribe(this, {
       describe: true,
@@ -2683,9 +2305,6 @@ export {
   LAYOUT_GET_NATIVE_EVAL,
   MERGED_CONSOLE_COUNT_EVAL,
   NOISY_TIMELINE_KINDS,
-  READY_CONTENT_NODE_FLOOR,
-  READY_NODE_STABLE_MS,
-  READY_PROBE_POLL_MS,
   SimClient,
   SimClientError,
   SimConnectError,
@@ -2694,8 +2313,6 @@ export {
   SimReadyTimeoutError,
   SimResetError,
   SimTapError,
-  WAIT_READY_PROBE,
-  WAIT_READY_PROGRESS_INTERVAL_MS,
   buildSimOpenUrl,
   clearConsole,
   clearLogs,
@@ -2703,6 +2320,7 @@ export {
   detectOpenNativeUI,
   filterLogEntries,
   formatLayoutElements,
+  formatSemanticTree,
   formatTimelineEvent,
   formatTimelineEvents,
   formatTimelinePayload,
@@ -2735,6 +2353,7 @@ export {
   isInspectModeActive,
   isInspectPickCommand,
   isShellCommandUnavailable,
+  isSimSemanticTree,
   isTapSuccess,
   layoutGetNativeEval,
   rankInteractive,