sootsim 0.1.111 → 0.1.113

package/dist-lib/sdk.mjs

@@ -0,0 +1,1360 @@
+/*! sootsim v0.1.113 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+
+// cli/commands/inspect/core.ts
+function resolveMaxMsFlag(args, fallbackMs) {
+  const aliases = ["--max-ms", "--maxMs", "--maxms", "--max_ms"];
+  for (const flag of aliases) {
+    const i = args.indexOf(flag);
+    if (i >= 0 && args[i + 1]) {
+      const n = Number(args[i + 1]);
+      if (Number.isFinite(n)) return Math.max(100, n);
+    }
+  }
+  return fallbackMs;
+}
+var INSPECT_PICK_COMMANDS = /* @__PURE__ */ new Set([
+  "tap",
+  "double-tap",
+  "tap-text",
+  "tap-id",
+  "long-press",
+  "touch"
+]);
+function isInspectPickCommand(subcommand) {
+  return typeof subcommand === "string" && INSPECT_PICK_COMMANDS.has(subcommand);
+}
+async function isInspectModeActive(bridge) {
+  const active = await bridge.send({
+    type: "evaluate",
+    code: "window.__sootsimEngineState?.inspectActive === true"
+  });
+  return active === true;
+}
+async function shouldSkipAutoSettleForInspectPick(bridge, subcommand) {
+  if (!isInspectPickCommand(subcommand)) return false;
+  try {
+    return await isInspectModeActive(bridge);
+  } catch {
+    return false;
+  }
+}
+async function inspectNodeCount(bridge) {
+  const count = await bridge.send({
+    type: "evaluate",
+    code: "(async () => await window.__sootsimTest.getNodeCount())()"
+  });
+  return { nodes: typeof count === "number" ? count : 0 };
+}
+async function inspectTree(bridge, depth = 5) {
+  const tree = await bridge.send({
+    type: "evaluate",
+    code: `(async () => await window.__sootsimTest.dumpTree(${depth}))()`
+  });
+  return { depth, tree };
+}
+async function inspectUrl(bridge) {
+  const url = await bridge.send({ type: "evaluate", code: "window.location.href" });
+  return { url: typeof url === "string" ? url : "" };
+}
+async function inspectDescribe(bridge, dumpOpts) {
+  const code = `(async () => {
+      const t = window.__sootsimTest
+      const mainShell = window.SootSim?.bridges?.mainShell
+      const kb = window.__sootsimKeyboard
+      if (!t) return { error: 'no test bridge' }
+
+      let shell = null
+      try {
+        shell = typeof mainShell?.getState === 'function' ? await mainShell.getState() : null
+      } catch {}
+
+      const tree = await t.dumpTree(12, ${JSON.stringify(dumpOpts)})
+      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 ?? {};
+}
+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
+        )
+      }
+`;
+function resolveFindMode(q) {
+  if (q.testId) {
+    return {
+      mode: "testid",
+      code: `(async () => {
+      const t = window.__sootsimTest
+      return (await t.findByTestId(${JSON.stringify(q.testId)})) || (await t.findById(${JSON.stringify(q.testId)}))
+    })()`
+    };
+  }
+  if (q.role) {
+    return {
+      mode: "role",
+      code: `(async () => await window.__sootsimTest.queryAll({ hasRole: ${JSON.stringify(q.role)}, pruneHidden: true }))()`
+    };
+  }
+  if (q.type) {
+    return {
+      mode: "type",
+      code: `(async () => await window.__sootsimTest.queryAll({ type: ${JSON.stringify(q.type)}, pruneHidden: true }))()`
+    };
+  }
+  if (q.pressable) {
+    return {
+      mode: "pressable",
+      code: `(async () => {
+      const t = window.__sootsimTest
+${FIND_INSPECTABLE_TARGETS}
+      const inspectable = await fromInspectable()
+      if (inspectable) return inspectable.filter(n => n.pressable && isVisibleTarget(n))
+      const all = await t.queryAll({ pruneHidden: true })
+      return all.filter(n => n.pressable && isVisibleTarget(n))
+    })()`
+    };
+  }
+  if (q.interactive) {
+    return {
+      mode: "interactive-targets",
+      code: `(async () => {
+      const t = window.__sootsimTest
+${FIND_INSPECTABLE_TARGETS}
+      const inspectable = await fromInspectable()
+      if (inspectable) {
+        return inspectable.filter(n => n.pressable && isVisibleTarget(n))
+      }
+      const all = await t.queryAll({ pruneHidden: true })
+      return all.filter(n => n.pressable && isVisibleTarget(n))
+    })()`
+    };
+  }
+  if (q.visible) {
+    return {
+      mode: "visible",
+      code: `(async () => {
+      const all = await window.__sootsimTest.queryAll({ pruneHidden: true })
+      return all.filter(n => n.layout && n.layout.width > 0 && n.layout.height > 0)
+    })()`
+    };
+  }
+  if (q.text) {
+    return {
+      mode: "text",
+      code: `(async () => await window.__sootsimTest.findByText(${JSON.stringify(q.text)}))()`
+    };
+  }
+  return null;
+}
+async function inspectFind(bridge, q) {
+  const resolved = resolveFindMode(q);
+  if (!resolved) return null;
+  const result = await bridge.send({ type: "evaluate", code: resolved.code });
+  return { mode: resolved.mode, result };
+}
+function rankInteractive(nodes) {
+  return [...nodes].sort((a, b) => scoreInteractive(b) - scoreInteractive(a));
+}
+function scoreInteractive(n) {
+  let score = 0;
+  if (n.testID) score += 100;
+  if (typeof n.text === "string" && n.text.trim().length > 0) score += 60;
+  if (typeof n.accessibilityLabel === "string" && n.accessibilityLabel.trim().length > 0) {
+    score += 30;
+  }
+  if (n.accessibilityRole) score += 15;
+  const w = n.layout?.width ?? 0;
+  const h = n.layout?.height ?? 0;
+  const area = w * h;
+  if (area >= 400 && area <= 6e4) score += 25;
+  else if (area > 6e4) score -= 20;
+  const y = n.absolutePosition?.y ?? 0;
+  if (y < 0) score -= 30;
+  return score;
+}
+function tapCommandForNode(n) {
+  if (n.testID) return `sootsim do tap-id ${shellEscape(n.testID)}`;
+  const text = typeof n.text === "string" ? n.text.trim() : "";
+  if (text.length > 0 && text.length <= 80)
+    return `sootsim 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 `sootsim do tap ${x} ${y}`;
+}
+function shellEscape(value) {
+  if (/^[A-Za-z0-9_./@:-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+var WAIT_READY_PROBE = `(async () => {
+    const t = window.__sootsimTest
+    let nodes = 0
+    try { nodes = (await t?.getNodeCount?.()) || 0 } catch {}
+    let targets = 0
+    let loadingText = ''
+    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 = n?.accessibilityLabel || n?.label
+            const handlers = Array.isArray(n?.handlers) ? n.handlers : []
+            const text = typeof n?.text === 'string' ? n.text.trim() : ''
+            const testID = typeof (n?.testID || n?.testId) === 'string' ? (n.testID || n.testId) : ''
+            if (!loadingText && /^(opening app|loading|capturing|connecting)$/i.test(text)) {
+              loadingText = text
+            }
+            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 {}
+    let externalReady = null
+    let externalStatus = ''
+    let externalError = ''
+    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)) {
+        const entry = external.entryErrors.find((item) => {
+          return item && typeof item.message === 'string' && item.message.trim()
+        })
+        if (entry) externalError = entry.message
+      }
+      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,
+      errors,
+      loadingText,
+      externalReady,
+      externalStatus,
+      externalError,
+    }
+  })()`;
+var READY_CONTENT_NODE_FLOOR = 100;
+var READY_NODE_STABLE_MS = 750;
+var WAIT_READY_PROGRESS_INTERVAL_MS = 2e3;
+function readyProbeHasContent(probe) {
+  return probe.targets > 0 || probe.nodes >= READY_CONTENT_NODE_FLOOR;
+}
+function waitReadyReason(status) {
+  return status.externalError ? `guest app errored: ${status.externalError}` : status.loadingText ? `still showing "${status.loadingText}"` : status.externalReady === false ? "guest app is still loading" : 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";
+}
+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 last = {
+    flag: void 0,
+    at: 0,
+    nodes: 0,
+    targets: 0,
+    errors: 0,
+    loadingText: "",
+    externalReady: null,
+    externalStatus: "",
+    externalError: ""
+  };
+  while (Date.now() < deadline) {
+    try {
+      last = await bridge.send({ type: "evaluate", code: WAIT_READY_PROBE }) ?? last;
+    } catch {
+    }
+    const now = Date.now();
+    const status = {
+      ready: false,
+      elapsedMs: now - start,
+      nodes: last.nodes,
+      targets: last.targets,
+      flag: last.flag,
+      loadingText: last.loadingText,
+      externalReady: last.externalReady,
+      externalStatus: last.externalStatus,
+      externalError: last.externalError,
+      errors: last.errors
+    };
+    if (last.nodes !== lastNodes) {
+      lastNodes = last.nodes;
+      nodeStableSince = now;
+    }
+    if (last.flag === true) {
+      if (last.externalReady !== false && !last.externalError && !last.loadingText && readyProbeHasContent(last)) {
+        if (now - nodeStableSince >= READY_NODE_STABLE_MS) {
+          return {
+            ...status,
+            ready: true
+          };
+        }
+      }
+    }
+    if (options.onProgress && progressIntervalMs > 0 && now >= nextProgressAt) {
+      options.onProgress(status);
+      do {
+        nextProgressAt += progressIntervalMs;
+      } while (now >= nextProgressAt);
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  return {
+    ready: false,
+    elapsedMs: Date.now() - start,
+    nodes: last.nodes,
+    targets: last.targets,
+    flag: last.flag,
+    loadingText: last.loadingText,
+    externalReady: last.externalReady,
+    externalStatus: last.externalStatus,
+    externalError: last.externalError,
+    errors: last.errors
+  };
+}
+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 {
+          const matches = await t.queryAll?.({ hasId: ID, pruneHidden: true })
+          if (!Array.isArray(matches)) return undefined
+          return matches.find(present) || null
+        } catch {
+          return undefined
+        }
+      }
+      let goneStreak = 0
+      while (Date.now() < deadline) {
+        const node = await find()
+        if (gone) {
+          if (node === null) {
+            goneStreak += 1
+            if (goneStreak >= 2) return { found: true, elapsed: Date.now() - start }
+          } else {
+            goneStreak = 0
+          }
+        } else if (present(node)) {
+          return { found: true, node, elapsed: Date.now() - start }
+        }
+        await new Promise((r) => setTimeout(r, 80))
+      }
+      return { found: false, elapsed: Date.now() - start }
+    })()`
+    },
+    {
+      timeoutMs: timeoutMs + 1e3
+    }
+  );
+  return result ?? { found: false, elapsed: timeoutMs };
+}
+async function inspectErrors(bridge, limit = 20) {
+  const result = await bridge.send({
+    type: "evaluate",
+    code: `window.__sootsimConsole?.getErrors(${limit}) || []`
+  });
+  return Array.isArray(result) ? result : [];
+}
+async function inspectWarnings(bridge, limit = 20) {
+  const result = await bridge.send({
+    type: "evaluate",
+    code: `window.__sootsimConsole?.getWarnings(${limit}) || []`
+  });
+  return Array.isArray(result) ? result : [];
+}
+async function clearConsole(bridge) {
+  await bridge.send({
+    type: "evaluate",
+    code: 'window.__sootsimConsole?.clear(); "cleared"'
+  });
+}
+async function inspectRequests(bridge, opts = {}) {
+  const limit = opts.limit ?? 20;
+  const method = opts.failed === false ? "getRequests" : "getFailedRequests";
+  const result = await bridge.send({
+    type: "call",
+    path: `__sootsimTest.${method}`,
+    args: [limit]
+  });
+  return Array.isArray(result) ? result : [];
+}
+async function clearRequests(bridge) {
+  await bridge.send({ type: "call", path: "__sootsimTest.clearRequests", args: [] });
+}
+async function inspectScrollStateAt(bridge, x, y) {
+  const result = await bridge.send({
+    type: "call",
+    path: "__sootsimTest.getScrollStateAt",
+    args: [x, y]
+  });
+  return result && typeof result === "object" ? result : null;
+}
+async function inspectLogs(bridge) {
+  const res = await bridge.send({
+    type: "evaluate",
+    code: `(() => {
+      const obs = window.__sootsimObservability;
+      if (!obs) return { ok: false };
+      return { ok: true, entries: obs.logs.getSnapshot() };
+    })()`
+  });
+  if (!res || !res.ok) return [];
+  return res.entries ?? [];
+}
+async function 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;
+    }
+    out.push(entry);
+  }
+  if (!opts.showInternal) {
+    out = out.filter((e) => {
+      const first = e.args[0];
+      return !(typeof first === "string" && first.startsWith("[sootsim]"));
+    });
+  }
+  if (opts.level) out = out.filter((e) => opts.level.has(e.level));
+  if (opts.filter) {
+    const lf = opts.filter.toLowerCase();
+    out = out.filter((e) => e.args.join(" ").toLowerCase().includes(lf));
+  }
+  return out;
+}
+async function inspectTimelineSummary(bridge, query) {
+  return await bridge.send({
+    type: "call",
+    path: "SootSim.bridges.timeline.summary",
+    args: [query]
+  });
+}
+async function inspectTimelineRecent(bridge, query) {
+  return await bridge.send({
+    type: "call",
+    path: "SootSim.bridges.timeline.recent",
+    args: [query]
+  });
+}
+async function inspectTimelineAdvanceCursor(bridge, cursorKey, watermark) {
+  await bridge.send({
+    type: "call",
+    path: "SootSim.bridges.timeline.cursorAdvance",
+    args: [cursorKey, watermark]
+  });
+}
+async function inspectKeyboard(bridge) {
+  const result = await bridge.send({
+    type: "evaluate",
+    code: `(() => {
+      const kb = window.__sootsimKeyboard
+      if (!kb || typeof kb.getLayout !== 'function') {
+        return { error: 'keyboard bridge getLayout() not available' }
+      }
+      return kb.getLayout()
+    })()`
+  });
+  return result ?? { error: "keyboard bridge returned no result" };
+}
+function isShellCommandUnavailable(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("call target not found: SootSim.bridges.mainShell") || message.includes("test bridge unavailable before app-in-worker boot");
+}
+async function getShellState(bridge, readyTimeoutMs = 0) {
+  const deadline = Date.now() + Math.max(0, readyTimeoutMs);
+  while (true) {
+    try {
+      return await bridge.send({
+        type: "call",
+        path: "SootSim.bridges.mainShell.getState",
+        args: []
+      });
+    } catch (error) {
+      if (!isShellCommandUnavailable(error) || Date.now() >= deadline) throw error;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+}
+async function inspectScreens(bridge) {
+  const payload = await bridge.send({
+    type: "evaluate",
+    code: `(async () => {
+      const test = window.__sootsimTest
+      const kb = window.__sootsimKeyboard
+      const navSnap =
+        test && typeof test.getNavigationSnapshot === 'function'
+          ? await test.getNavigationSnapshot()
+          : null
+      const 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, keyboard }
+    })()`
+  });
+  const shell = await getShellState(bridge, 500).catch(() => null);
+  return {
+    shell,
+    nav: payload?.nav ?? null,
+    keyboard: payload?.keyboard ?? null
+  };
+}
+var DEBUG_CHANNELS = [
+  "portals",
+  "sheets",
+  "layout",
+  "onlayout",
+  "animated",
+  "render",
+  "touch",
+  "yoga"
+];
+async function inspectDebugStatus(bridge) {
+  return bridge.send({ type: "evaluate", code: "window.__sootsimDebug.status()" });
+}
+async function inspectDebugFlags(bridge) {
+  return bridge.send({ type: "evaluate", code: "window.__sootsimDebug.flags()" });
+}
+async function inspectDebugFind(bridge, target) {
+  const method = target === "sheets" ? "findSheets" : "findPortals";
+  return bridge.send({
+    type: "evaluate",
+    code: `window.__sootsimDebug.${method}()`
+  });
+}
+async function inspectDebugRecent(bridge, channel, limit = 50) {
+  const code = channel && channel !== "all" ? `window.__sootsimDebug.recent(${JSON.stringify(channel)}, ${limit})` : `window.__sootsimDebug.recent(undefined, ${limit})`;
+  return bridge.send({ type: "evaluate", code });
+}
+async function setDebugChannels(bridge, action, channels) {
+  const args = channels.length > 0 ? channels.map((c) => JSON.stringify(c)).join(", ") : action === "disable" ? "'all'" : "";
+  return bridge.send({
+    type: "evaluate",
+    code: `window.__sootsimDebug.${action}(${args})`
+  });
+}
+async function inspectMemory(bridge) {
+  const result = await bridge.send({
+    type: "evaluate",
+    code: `(async () => {
+      const host = window.__sootsimRenderHost
+      const stats = host?.queryStats ? await host.queryStats() : null
+      const hostMem = performance.memory
+        ? {
+            usedJSHeapSize: performance.memory.usedJSHeapSize,
+            totalJSHeapSize: performance.memory.totalJSHeapSize,
+            jsHeapSizeLimit: performance.memory.jsHeapSizeLimit,
+          }
+        : null
+      return {
+        imageLoader: stats?.memory?.imageLoader ?? null,
+        workerHeap: stats?.memory?.workerHeap ?? null,
+        hostHeap: hostMem,
+      }
+    })()`
+  });
+  return result ?? { imageLoader: null, workerHeap: 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 ");
+}
+
+// cli/commands/inspect/settling.ts
+async function waitForSootsimIdle({
+  bridge,
+  simId,
+  maxMs,
+  pollMs = 50,
+  stablePolls = 3,
+  strict = false
+}) {
+  const result = await bridge.send(
+    {
+      type: "evaluate",
+      simId,
+      code: `(async () => {
+      const start = Date.now()
+      const deadline = start + ${Math.max(0, Math.round(maxMs))}
+      const pollMs = ${Math.max(1, Math.round(pollMs))}
+      const requiredStablePolls = ${Math.max(1, Math.round(stablePolls))}
+      const strict = ${strict ? "true" : "false"}
+      const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+      // route-aware settle: a tap that pushes/pops a screen is async \u2014 the
+      // old screen still renders for a moment, then the new one mounts and
+      // its content loads. a pure layout-hash check reports "idle" on the
+      // outgoing screen or on the incoming skeleton, so a driver re-taps
+      // and stacks duplicate navigations. drain any in-flight screen
+      // transition FIRST, bounded by the overall budget. when no
+      // transition is happening this returns in ~80ms (startWindowMs), so
+      // a plain button tap barely pays for it.
+      try {
+        const wfst = window.__sootsimTest?.waitForScreenTransitions
+        if (typeof wfst === 'function') {
+          const remaining = deadline - Date.now()
+          if (remaining > 120) {
+            await wfst({
+              timeoutMs: Math.min(remaining - 80, 4000),
+              settleMs: 64,
+              startWindowMs: 80,
+            })
+          }
+        }
+      } catch {}
+
+      const readSnapshot = async () => {
+        let animating = false
+        let pendingFetches = 0
+        let requestTotal = 0
+        let requestInFlight = 0
+        try {
+          const stats = await window.__sootsimRenderHost?.queryStats?.()
+          if (stats) {
+            animating =
+              stats.hasActiveAnims === true ||
+              stats.hasActiveNativeAnimations === true ||
+              stats.hasPendingAnimationFrames === true
+            // a freshly-pushed screen showing a skeleton is layout-stable
+            // but not actually settled \u2014 its data/images are still in
+            // flight. treat bounded image-loader fetches as not-idle so
+            // settle waits for real content, capped by the budget.
+            const pf = stats.memory && stats.memory.imageLoader
+              ? stats.memory.imageLoader.pendingFetches
+              : 0
+            pendingFetches = typeof pf === 'number' ? pf : 0
+          }
+        } catch {}
+        try {
+          const counts = await window.__sootsimTest?.getRequestCounts?.()
+          requestTotal = typeof counts?.total === 'number' ? counts.total : 0
+          requestInFlight = typeof counts?.inFlight === 'number' ? counts.inFlight : 0
+        } catch {}
+        const root = window.__sootsimRoot
+        const nodes = []
+        if (root) {
+          const walk = (n) => {
+            if (n.layout && n.layout.width > 0) {
+              nodes.push(Math.round(n.layout.x) + ',' + Math.round(n.layout.y) + ',' + Math.round(n.layout.width))
+            }
+            for (const c of n.children || []) walk(c)
+          }
+          walk(root)
+        }
+        return { layout: nodes.join(';'), animating, pendingFetches, requestTotal, requestInFlight }
+      }
+
+      let lastLayout = ''
+      let lastRequestTotal = -1
+      let stable = 0
+      while (Date.now() < deadline) {
+        const snapshot = await readSnapshot()
+        const strictOk = !strict || !snapshot.animating
+        const contentReady = snapshot.pendingFetches === 0 && snapshot.requestInFlight === 0
+        const requestsStable = snapshot.requestTotal === lastRequestTotal
+        if (strictOk && contentReady && requestsStable && snapshot.layout === lastLayout) {
+          stable++
+          if (stable >= requiredStablePolls) {
+            return { settled: true, elapsed: Date.now() - start }
+          }
+        } else {
+          stable = 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 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.pointerTapHandled === false && !result.keyboardOpened && !result.isTextInput) {
+    return false;
+  }
+  return true;
+}
+function tapTargetFromPayload(payload, textFallback) {
+  return {
+    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;
+  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") {
+      const result = await bridge.send({
+        type: "tap",
+        x: payload.cx,
+        y: payload.cy,
+        target: tapTargetFromPayload(payload, args.textFallback)
+      });
+      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
+          return {
+            cx,
+            cy,
+            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
+          return {
+            cx,
+            cy,
+            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,
+              },
+            }
+          }
+          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,
+              },
+            }
+          }
+          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;
+      return {
+        ...payload,
+        cx,
+        cy,
+        target: {
+          id: node.id,
+          testID: node.testID,
+          text: payload.strategy === "text" ? query : node.text,
+          type: node.type
+        }
+      };
+    }
+  });
+}
+export {
+  DEBUG_CHANNELS,
+  READY_CONTENT_NODE_FLOOR,
+  READY_NODE_STABLE_MS,
+  WAIT_READY_PROBE,
+  WAIT_READY_PROGRESS_INTERVAL_MS,
+  clearConsole,
+  clearLogs,
+  clearRequests,
+  filterLogEntries,
+  formatTimelineSummary,
+  getShellState,
+  inspectAccessibilityTree,
+  inspectDebugFind,
+  inspectDebugFlags,
+  inspectDebugRecent,
+  inspectDebugStatus,
+  inspectDescribe,
+  inspectErrors,
+  inspectFind,
+  inspectKeyboard,
+  inspectLogs,
+  inspectMemory,
+  inspectNodeCount,
+  inspectRequests,
+  inspectScreens,
+  inspectScrollStateAt,
+  inspectTimelineAdvanceCursor,
+  inspectTimelineRecent,
+  inspectTimelineSummary,
+  inspectTree,
+  inspectUrl,
+  inspectWaitReady,
+  inspectWaitSelector,
+  inspectWarnings,
+  isInspectModeActive,
+  isInspectPickCommand,
+  isShellCommandUnavailable,
+  isTapSuccess,
+  rankInteractive,
+  readyProbeHasContent,
+  resolveFindMode,
+  resolveMaxMsFlag,
+  scoreInteractive,
+  setDebugChannels,
+  shouldSkipAutoSettleForInspectPick,
+  tapBest,
+  tapById,
+  tapByText,
+  tapCommandForNode,
+  tapCoordinates,
+  tapResolvedTarget,
+  tapTargetFromPayload,
+  waitForSootsimIdle,
+  waitReadyReason
+};