@avasapp/agent-bridge 0.3.0 → 0.4.0

package/dist/runtime/index.cjs

@@ -23,13 +23,14 @@ __export(runtime_exports, {
   RUNTIME_MARKER: () => RUNTIME_MARKER,
   cdpTransport: () => cdpTransport,
   createGate: () => createGate,
+  onRestore: () => onRestore,
   settle: () => settle,
   startAgentBridge: () => startAgentBridge,
   useAgentBridge: () => useAgentBridge
 });
 module.exports = __toCommonJS(runtime_exports);
 var import_react = require("react");
-var import_react_native2 = require("react-native");
+var import_react_native3 = require("react-native");
 
 // src/shared/protocol.ts
 var PROTOCOL_VERSION = 1;
@@ -43,6 +44,73 @@ function toAsciiJson(value) {
   );
 }
 
+// src/runtime/builtin-tools.ts
+var import_react_native2 = require("react-native");
+
+// src/runtime/undo.ts
+var undos = [];
+function onRestore(fn, label) {
+  if (typeof fn !== "function") throw new Error("onRestore takes a function");
+  undos.push({ fn, label });
+}
+function pendingUndos() {
+  return undos.map((u) => u.label ?? "undo").reverse();
+}
+async function runUndos() {
+  const batch = undos.splice(0).reverse();
+  const errors = [];
+  for (const { fn, label } of batch) {
+    try {
+      await fn();
+    } catch (error) {
+      const why = error instanceof Error ? error.message : String(error);
+      errors.push(label ? `${label}: ${why}` : why);
+    }
+  }
+  return { ran: batch.length, errors };
+}
+
+// src/runtime/tools/app.ts
+function selectReload(host, devSettingsReload) {
+  return () => {
+    const expo = host.expo;
+    if (typeof expo?.reloadAppAsync !== "function") return devSettingsReload();
+    try {
+      Promise.resolve(expo.reloadAppAsync("agent-bridge app.reload")).catch(
+        () => devSettingsReload()
+      );
+    } catch {
+      devSettingsReload();
+    }
+  };
+}
+function appTools(reload) {
+  return {
+    "app.reload": {
+      description: "Reload the app's JS (Expo's reloadAppAsync, else DevSettings.reload). Pending restores (store, query, mocks, pins) are lost. Returns before it reloads; a session waits for the new bridge and reports what was lost.",
+      run: () => {
+        setTimeout(reload, 50);
+        return { reloading: true };
+      }
+    },
+    "app.restore": {
+      maxArgs: 0,
+      // The labels, so bridge.pending shows what the app's own tools changed.
+      pending: () => {
+        const labels = pendingUndos();
+        return labels.length ? labels : false;
+      },
+      description: "Undo what the app's own tools changed: runs the undos they registered with onRestore, newest first, once. Returns how many ran.",
+      run: async () => {
+        const { ran, errors } = await runUndos();
+        if (errors.length)
+          throw new Error(`${errors.join("; ")} (${ran - errors.length} of ${ran} undone)`);
+        return { undone: ran };
+      }
+    }
+  };
+}
+
 // src/runtime/tools/bridge.ts
 function bridgeTools(listTools) {
   return {
@@ -57,6 +125,42 @@ function bridgeTools(listTools) {
   };
 }
 
+// src/runtime/tools/capture.ts
+var MAX_BASE64_CHARS = 2e5;
+var UNAVAILABLE = "screen.capture needs react-native-view-shot, which this app does not have. Take the screenshot with agent-device, `xcrun simctl io booted screenshot <file>` (iOS simulator) or `adb exec-out screencap -p > <file>` (Android) instead.";
+function loadViewShot() {
+  try {
+    const mod = require("react-native-view-shot");
+    return typeof mod?.captureScreen === "function" ? mod : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function captureTools(load) {
+  return {
+    "screen.capture": {
+      description: "Screenshot the app as a PNG. Returns {path} of a file on the device. `{base64:true}` returns {base64} instead when small enough (else {path}). Only works if the app already has react-native-view-shot; otherwise errors and you use agent-device, simctl or adb.",
+      maxArgs: 1,
+      run: async (options) => {
+        const viewShot = load();
+        if (!viewShot) throw new Error(UNAVAILABLE);
+        if (options?.base64) {
+          const base64 = await viewShot.captureScreen({
+            format: "png",
+            result: "base64"
+          });
+          if (base64.length <= MAX_BASE64_CHARS) return { base64 };
+        }
+        const path2 = await viewShot.captureScreen({
+          format: "png",
+          result: "tmpfile"
+        });
+        return { path: path2 };
+      }
+    }
+  };
+}
+
 // src/runtime/tools/logs.ts
 function logTools(logs) {
   return {
@@ -75,8 +179,28 @@ function logTools(logs) {
 var SUFFIX = ".restore";
 var SELF = "bridge.restore";
 var LAST = "scenario.restore";
+function pendingByArea(tools, detail = false) {
+  const out = {};
+  for (const [name, d] of Object.entries(tools)) {
+    if (!name.endsWith(SUFFIX) || name === SELF || typeof d === "function")
+      continue;
+    const area3 = name.slice(0, -SUFFIX.length);
+    try {
+      const found = d.pending?.({ detail });
+      if (found) out[area3] = found;
+    } catch (error) {
+      out[area3] = `pending check failed: ${error instanceof Error ? error.message : String(error)}`;
+    }
+  }
+  return out;
+}
 function restoreTools(getTools) {
   return {
+    "bridge.pending": {
+      maxArgs: 0,
+      description: "What bridge.restore would undo right now, per area (store, query, net, app, ...): the value is true, or detail such as a store's snapshot against its current value. Empty when nothing is pending. Changes nothing.",
+      run: () => pendingByArea(getTools(), true)
+    },
     [SELF]: {
       description: "Undo what the agent changed: runs every *.restore tool in name order, scenario.restore last, and returns each result or error.",
       run: async () => {
@@ -161,7 +285,7 @@ function checkOptions(schema, options) {
 // src/runtime/tools/scenario.ts
 var active = /* @__PURE__ */ new Map();
 var message = (error) => error instanceof Error ? error.message : String(error);
-async function runUndos(entry) {
+async function runUndos2(entry) {
   const errors = [];
   for (const undo2 of entry.undos.splice(0).reverse()) {
     try {
@@ -176,7 +300,7 @@ async function undo(name) {
   const entry = active.get(name);
   if (!entry) return [];
   active.delete(name);
-  return (await runUndos(entry)).map((e) => `${name}: ${e}`);
+  return (await runUndos2(entry)).map((e) => `${name}: ${e}`);
 }
 function scenarioTools(getScenarios, getTools) {
   const find = (name) => {
@@ -241,6 +365,7 @@ scenario.list shows its options schema.`
       }
     },
     "scenario.restore": {
+      pending: () => active.size > 0,
       description: "Undo every active scenario, newest first. bridge.restore runs this after every other restorer.",
       run: async () => {
         const names = [...active.keys()].reverse();
@@ -296,40 +421,101 @@ function textOf(fiber) {
   }
   return null;
 }
-function inActiveScreen(fiber) {
-  for (let f = fiber; f; f = f.return) {
-    if (f.tag !== HOST_COMPONENT) continue;
-    const props = f.memoizedProps;
-    if (props?.activityState === 0) return false;
+
+// src/runtime/screen/webview-mark.ts
+var MARK = /^\/\*agent-bridge:webview:([^*]*)\*\//;
+function webViewNameOf(props) {
+  const script = props.injectedJavaScriptBeforeContentLoaded;
+  const found = typeof script === "string" ? MARK.exec(script) : null;
+  if (!found) return void 0;
+  try {
+    return decodeURIComponent(found[1]);
+  } catch {
+    return found[1];
   }
+}
+
+// src/runtime/screen/elements.ts
+var propsOf = (fiber) => fiber.memoizedProps && typeof fiber.memoizedProps === "object" ? fiber.memoizedProps : null;
+var nodeOf = (fiber) => {
+  const n = fiber.stateNode;
+  return n && typeof n === "object" ? n : null;
+};
+var SCROLL_METHODS = ["scrollTo", "scrollToOffset"];
+function scrolls(fiber) {
+  const node = nodeOf(fiber);
+  if (!node || !SCROLL_METHODS.some((m) => isFn(node[m]))) return false;
+  if (typeof node.scrollHeight === "number" && typeof node.clientHeight === "number")
+    return node.scrollHeight > node.clientHeight + 1 || node.scrollWidth > node.clientWidth + 1;
   return true;
 }
-function findTextInTree(roots, text, window, options = {}) {
-  const stack = [...roots];
-  const matches = [];
-  while (stack.length) {
-    const fiber = stack.pop();
-    const found = textOf(fiber);
-    if (found && (options.exact ? found.text === text : found.text.includes(text))) {
-      const rect = found.host ? measureHost(found.host) : null;
-      const onScreen = !!rect && inActiveScreen(fiber) && rect.width > 0 && rect.height > 0 && rect.x < window.width && rect.y < window.height && rect.x + rect.width > 0 && rect.y + rect.height > 0;
-      matches.push({ text: found.text, rect, onScreen });
+var displayNone = (style) => displayOf(style) === "none";
+function displayOf(style) {
+  if (Array.isArray(style)) {
+    for (let i = style.length - 1; i >= 0; i--) {
+      const d = displayOf(style[i]);
+      if (d !== void 0) return d;
     }
-    if (fiber.child) stack.push(fiber.child);
-    if (fiber.sibling) stack.push(fiber.sibling);
+    return void 0;
+  }
+  return style && typeof style === "object" ? style.display : void 0;
+}
+var hiddenBy = (p) => p.activityState === 0 || displayNone(p.style) || p["aria-hidden"] === true || p.accessibilityElementsHidden === true || p.importantForAccessibility === "no-hide-descendants";
+var MODAL_HOSTS = /* @__PURE__ */ new Set(["RCTModalHostView", "ModalHostView"]);
+var OVERLAY_HOST = "RNSFullWindowOverlay";
+var SCREEN_STACK = "RNSScreenStack";
+var STACK_SCREENS = /* @__PURE__ */ new Set(["RNSScreen", "RNSModalScreen"]);
+var SEE_THROUGH = /* @__PURE__ */ new Set(["transparentModal", "containedTransparentModal", "overFullScreen"]);
+var undimmedSheet = (p) => {
+  const at = p.sheetLargestUndimmedDetentIndex;
+  return p.stackPresentation === "formSheet" && at !== void 0 && at !== null && at !== "none" && at !== -1;
+};
+function presentationOf(screen) {
+  const p = propsOf(screen);
+  if (typeof p?.stackPresentation === "string") return p.stackPresentation;
+  return screen.type === "RNSModalScreen" ? "modal" : null;
+}
+var seeThrough = (screen) => {
+  const presentation = presentationOf(screen);
+  return presentation !== null && SEE_THROUGH.has(presentation) || undimmedSheet(propsOf(screen) ?? {});
+};
+var coversWindow = (screen) => {
+  const presentation = presentationOf(screen);
+  return presentation !== null && presentation !== "push" && !undimmedSheet(propsOf(screen) ?? {});
+};
+function stackScreens(stack) {
+  const screens = [];
+  const todo = stack.child ? [stack.child] : [];
+  while (todo.length) {
+    const f = todo.pop();
+    if (f.sibling) todo.push(f.sibling);
+    if (f.tag === HOST_COMPONENT && STACK_SCREENS.has(f.type)) {
+      if (propsOf(f)?.activityState !== 0) screens.push(f);
+    } else if (f.child) todo.push(f.child);
   }
+  let base = screens.length - 1;
+  while (base > 0 && seeThrough(screens[base])) base--;
   return {
-    found: matches.length,
-    onScreen: matches.filter((m) => m.onScreen).length,
-    matches
+    covered: screens.slice(0, Math.max(0, base)),
+    presented: screens.slice(1).filter(coversWindow)
   };
 }
-
-// src/runtime/screen/elements.ts
-var propsOf = (fiber) => fiber.memoizedProps && typeof fiber.memoizedProps === "object" ? fiber.memoizedProps : null;
+function hostAbove(host) {
+  let up = host.return;
+  while (up && up.tag !== HOST_COMPONENT) up = up.return;
+  return up ?? host;
+}
+var REFRESH_HOST = /refresh/i;
+var refreshTwin = (rec, host) => rec && REFRESH_HOST.test(String(rec.host.type)) && hostAbove(host) === rec.host ? rec : null;
+var inside = (modal, top) => {
+  for (let m = modal; m; m = m.up) if (m === top) return true;
+  return false;
+};
+var SWITCH_HOSTS = /* @__PURE__ */ new Set(["RCTSwitch", "AndroidSwitch"]);
 var isFn = (v) => typeof v === "function";
-var isInputProps = (p) => isFn(p.onChangeText) || isFn(p.onChange) && ("value" in p || "defaultValue" in p || "placeholder" in p);
-var interesting = (p) => isFn(p.onPress) || isInputProps(p) || typeof p.testID === "string";
+var isInputProps = (p) => isFn(p.onChangeText) || isFn(p.onChange) && typeof p.value !== "boolean" && ("value" in p || "defaultValue" in p || "placeholder" in p);
+var labelOf = (p) => p.accessibilityLabel ?? p["aria-label"];
+var interesting = (p) => isFn(p.onPress) || isFn(p.onValueChange) || isInputProps(p) || typeof p.testID === "string" || typeof labelOf(p) === "string" || webViewNameOf(p) !== void 0;
 var ICON_GLYPHS = /[\uE000-\uF8FF]/g;
 function firstHost(fiber) {
   if (fiber.tag === HOST_COMPONENT) return fiber;
@@ -350,22 +536,77 @@ function absorb(rec, fiber, p) {
     if (e[key] === void 0 && typeof v === "string") e[key] = v;
   };
   fill("testID", p.testID);
-  fill("label", p.accessibilityLabel ?? p["aria-label"]);
+  fill("label", labelOf(p));
   fill("role", p.accessibilityRole ?? p.role);
   fill("placeholder", p.placeholder);
-  if (e.value === void 0 && ("value" in p || "defaultValue" in p)) {
+  const webview = webViewNameOf(p);
+  if (e.webview === void 0 && webview !== void 0) e.webview = webview;
+  const isSwitch = SWITCH_HOSTS.has(fiber.type) || (p.accessibilityRole ?? p.role ?? e.role) === "switch";
+  if (isSwitch && typeof p.value === "boolean") {
+    if (e.checked === void 0) e.checked = p.value;
+    if (e.role === void 0) e.role = "switch";
+  } else if (e.value === void 0 && !(typeof p.value === "boolean" && isFn(p.onValueChange)) && ("value" in p || "defaultValue" in p)) {
     const v = p.value ?? p.defaultValue;
-    if (v != null) e.value = String(v);
+    if (v != null && typeof v !== "object" && !isFn(v)) e.value = String(v);
   }
   if (rec.maxLength === void 0 && typeof p.maxLength === "number")
     rec.maxLength = p.maxLength;
   if (p.editable === false || p.readOnly === true) e.editable = false;
   const state = p.accessibilityState;
+  const checked = state?.checked ?? p["aria-checked"];
+  if (e.checked === void 0 && (typeof checked === "boolean" || checked === "mixed"))
+    e.checked = checked;
+  const flag = (key) => {
+    const v = state?.[key] ?? p[`aria-${key}`];
+    if (e[key] === void 0 && typeof v === "boolean") e[key] = v;
+  };
+  flag("selected");
+  flag("expanded");
   if (p.disabled === true || state?.disabled === true || p["aria-disabled"] === true)
     e.disabled = true;
 }
-function isOnScreen(rect, window) {
-  return !!rect && rect.width > 0 && rect.height > 0 && rect.x < window.width && rect.y < window.height && rect.x + rect.width > 0 && rect.y + rect.height > 0;
+var intersect = (a, b) => {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  return right > x && bottom > y ? { x, y, width: right - x, height: bottom - y } : null;
+};
+var usable = (r) => !!r && r.width > 0 && r.height > 0;
+var within = (host, ancestor) => {
+  for (let f = host; f; f = f.return) if (f === ancestor) return true;
+  return false;
+};
+function visibleArea(base, host, bars, window) {
+  let area3 = base;
+  const clip2 = (r) => {
+    area3 = area3 && intersect(area3, r);
+  };
+  for (const bar of bars) {
+    if (within(host, bar)) continue;
+    const r = measureHost(bar);
+    if (!usable(r) || r.width < window.width * 0.9) continue;
+    clip2(
+      r.y + r.height / 2 > window.height / 2 ? { x: -1e9, y: -1e9, width: 2e9, height: 1e9 + r.y } : { x: -1e9, y: r.y + r.height, width: 2e9, height: 1e9 }
+    );
+  }
+  return area3;
+}
+var viewportOf = (s, view, window) => usable(view) ? visibleArea(view, s.host, s.modal ? [] : s.bars, window) : null;
+function isOnScreen(rec, rect, window, bars) {
+  if (!usable(rect)) return false;
+  const shown = intersect(rect, { x: 0, y: 0, ...window });
+  if (!shown) return false;
+  const cx = shown.x + shown.width / 2;
+  const cy = shown.y + shown.height / 2;
+  const holds = (r) => !!r && cx >= r.x && cx <= r.x + r.width && cy >= r.y && cy <= r.y + r.height;
+  if (!holds(visibleArea(shown, rec.host, rec.modal ? [] : bars, window))) return false;
+  for (let s = rec.scroller; s; s = s.parent) {
+    if (s.host === rec.host || s.modal !== rec.modal) continue;
+    const view = measureHost(s.host);
+    if (usable(view) && !holds(viewportOf(s, view, window))) return false;
+  }
+  return true;
 }
 var round = (r) => r && {
   x: Math.round(r.x),
@@ -389,10 +630,15 @@ function absorbChain(rec, fiber, host) {
     if (f === host) break;
   }
 }
-function collectElements(roots, window) {
+function collectScreen(roots, window) {
   const byHost = /* @__PURE__ */ new Map();
   const order = [];
-  const recFor = (fiber, host, parent) => {
+  const scrollByHost = /* @__PURE__ */ new Map();
+  const covered = /* @__PURE__ */ new Set();
+  const presented = /* @__PURE__ */ new Set();
+  const bars = [];
+  let topModal = null;
+  const recFor = (fiber, host, parent, hidden, scroller, modal, overlay) => {
     let rec = byHost.get(host);
     if (rec) return rec;
     rec = {
@@ -402,6 +648,10 @@ function collectElements(roots, window) {
       host,
       press: null,
       input: null,
+      hidden,
+      scroller,
+      modal,
+      overlay,
       parent,
       parts: []
     };
@@ -414,49 +664,118 @@ function collectElements(roots, window) {
     for (let r = rec; r; r = r.parent) if (r.press) return r;
     return null;
   };
-  const stack = roots.map((fiber) => ({ fiber, rec: null }));
+  const textHost = (host) => {
+    let h = host;
+    for (; ; ) {
+      let up = h.return;
+      while (up && up.tag !== HOST_COMPONENT) up = up.return;
+      if (!up) return h;
+      if (h.type !== "RCTVirtualText") return h;
+      h = up;
+    }
+  };
+  const stack = roots.map((fiber) => ({
+    fiber,
+    rec: null,
+    hidden: false,
+    scroller: null,
+    modal: null,
+    overlay: false
+  }));
   while (stack.length) {
-    const { fiber, rec: parentRec } = stack.pop();
-    if (fiber.sibling) stack.push({ fiber: fiber.sibling, rec: parentRec });
+    const item = stack.pop();
+    const { fiber, rec: parentRec } = item;
+    if (fiber.sibling) stack.push({ ...item, fiber: fiber.sibling });
     const p = propsOf(fiber);
-    if (fiber.tag === HOST_COMPONENT && p?.activityState === 0) continue;
+    let { hidden, scroller, modal, overlay } = item;
+    if (fiber.tag === HOST_COMPONENT) {
+      if (p && hiddenBy(p)) hidden = true;
+      if (covered.has(fiber)) hidden = true;
+      if (fiber.type === SCREEN_STACK) {
+        const screens = stackScreens(fiber);
+        for (const s of screens.covered) covered.add(s);
+        for (const s of screens.presented) presented.add(s);
+      }
+      if (fiber.type === OVERLAY_HOST) overlay = true;
+      if (p && !hidden && (p.accessibilityRole ?? p.role) === "tablist") bars.push(fiber);
+      if (!hidden && (MODAL_HOSTS.has(fiber.type) || presented.has(fiber))) {
+        modal = { host: fiber, up: modal };
+        topModal = modal;
+      }
+    }
+    if (scrolls(fiber)) {
+      const host = firstHost(fiber);
+      if (host) {
+        let found2 = scrollByHost.get(host);
+        if (!found2) {
+          found2 = { host, fibers: [], hidden, parent: scroller, modal, overlay, bars };
+          scrollByHost.set(host, found2);
+        }
+        found2.fibers.push(fiber);
+        scroller = found2;
+      }
+    }
     let rec = parentRec;
     if (p && interesting(p)) {
       const host = firstHost(fiber);
-      const same = host && !byHost.has(host) ? sameControl(parentRec, p) : null;
-      if (host && same) {
+      const twin = host && !byHost.has(host) ? refreshTwin(parentRec, host) : null;
+      const same = host && !twin && !byHost.has(host) ? sameControl(parentRec, p) : null;
+      if (host && twin) {
+        byHost.set(host, twin);
+        rec = twin;
+      } else if (host && same) {
         byHost.set(host, same);
         same.host = host;
         absorbChain(same, fiber, host);
         rec = same;
       } else if (host) {
-        rec = recFor(fiber, host, parentRec);
+        rec = recFor(fiber, host, parentRec, hidden, scroller, modal, overlay);
         absorb(rec, fiber, p);
       }
     }
     const found = textOf(fiber);
     if (found?.host) {
-      const owner = buttonOf(rec) ?? recFor(found.host, found.host, rec);
+      const host = textHost(found.host);
+      const owner = buttonOf(rec) ?? recFor(host, host, rec, hidden, scroller, modal, overlay);
       const last = owner.parts[owner.parts.length - 1];
-      if (last?.host === found.host) last.text += found.text;
-      else owner.parts.push({ host: found.host, text: found.text });
+      if (last?.host === host) last.text += found.text;
+      else owner.parts.push({ host, text: found.text });
     }
-    if (fiber.child) stack.push({ fiber: fiber.child, rec });
+    if (fiber.child) stack.push({ fiber: fiber.child, rec, hidden, scroller, modal, overlay });
   }
+  const top = topModal;
+  const covers2 = (x) => !!top && !x.overlay && !inside(x.modal, top);
+  for (const scrollable of scrollByHost.values())
+    scrollable.hidden || (scrollable.hidden = covers2(scrollable));
   for (const rec of order) {
     const e = rec.element;
+    rec.hidden || (rec.hidden = covers2(rec));
     const text = rec.parts.map((part) => part.text.replace(ICON_GLYPHS, "").replace(/\s+/g, " ").trim()).filter(Boolean).join(" ");
     if (text) e.text = text;
-    e.kind = rec.input ? "input" : rec.press ? "button" : rec.parts.length ? "text" : "view";
+    e.kind = e.webview !== void 0 ? "webview" : rec.input ? "input" : rec.press ? "button" : rec.parts.length ? "text" : "view";
     if (e.kind === "input" && e.editable === void 0) e.editable = true;
     const rect = measureHost(rec.host);
     e.rect = round(rect);
-    rec.onScreen = isOnScreen(rect, window);
+    const own = scrollByHost.get(rec.host) ?? scrollByHost.get(hostAbove(rec.host));
+    if (own) rec.scroller = own;
+    rec.onScreen = isOnScreen(rec, rect, window, bars);
   }
-  return order.filter(
-    (rec) => rec.element.kind !== "text" || rec.element.text !== void 0
-  );
+  const named = /* @__PURE__ */ new Set();
+  const single = (rec) => {
+    const name = rec.element.webview;
+    if (name === void 0) return true;
+    if (named.has(name)) return false;
+    named.add(name);
+    return true;
+  };
+  return {
+    found: order.filter(
+      (rec) => (rec.element.kind !== "text" || rec.element.text !== void 0) && single(rec)
+    ),
+    scrollables: [...scrollByHost.values()]
+  };
 }
+var focused = (found) => found.filter((f) => !f.hidden);
 function pressFiberOf(found) {
   if (found.press) return found.press;
   for (let f = found.fiber.return; f; f = f.return) {
@@ -467,6 +786,26 @@ function pressFiberOf(found) {
 }
 
 // src/runtime/screen/targets.ts
+var TARGET_KEYS = ["testID", "label", "placeholder", "text", "at", "index"];
+function checkTarget(target) {
+  if (typeof target === "string") return;
+  if (target === null || typeof target !== "object" || Array.isArray(target))
+    throw new Error(
+      `A target is a string or an object with ${TARGET_KEYS.join(", ")}; got ${JSON.stringify(target)}`
+    );
+  const unknown = Object.keys(target).filter((k) => !TARGET_KEYS.includes(k));
+  if (unknown.length)
+    throw new Error(
+      `Unknown target key ${unknown.map((k) => JSON.stringify(k)).join(", ")}. Valid keys: ${TARGET_KEYS.join(", ")}`
+    );
+  const { at, index } = target;
+  if (at !== void 0 && !(Array.isArray(at) && at.length === 2 && at.every(Number.isFinite)))
+    throw new Error(`Target "at" must be [x, y] in window points; got ${JSON.stringify(at)}`);
+  if (index !== void 0 && !Number.isInteger(index))
+    throw new Error(`Target "index" must be an integer; got ${JSON.stringify(index)}`);
+}
+var covers = (e, [x, y]) => !!e.rect && x >= e.rect.x && x <= e.rect.x + e.rect.width && y >= e.rect.y && y <= e.rect.y + e.rect.height;
+var area = (f) => f.element.rect ? f.element.rect.width * f.element.rect.height : 0;
 function tiers(target) {
   if (typeof target === "string") {
     return [
@@ -477,59 +816,77 @@ function tiers(target) {
       (e) => !!e.text?.includes(target)
     ];
   }
-  const { testID, label, placeholder, text } = target;
-  const fields = (e) => (testID === void 0 || e.testID === testID) && (label === void 0 || e.label === label) && (placeholder === void 0 || e.placeholder === placeholder);
+  const { testID, label, placeholder, text, at } = target;
+  const fields = (e) => (testID === void 0 || e.testID === testID) && (at === void 0 || covers(e, at)) && (label === void 0 || e.label === label) && (placeholder === void 0 || e.placeholder === placeholder);
   if (text === void 0) return [fields];
   return [
     (e) => fields(e) && e.text === text,
     (e) => fields(e) && !!e.text?.includes(text)
   ];
 }
+var labelOnly = ({ element: e, press, input }) => e.kind === "view" && !e.testID && !e.text && !e.placeholder && !press && !input;
 function matchTarget(found, target) {
-  for (const test of tiers(target)) {
-    const matches = found.filter((f) => test(f.element));
-    if (matches.length) return matches;
+  checkTarget(target);
+  for (const pool of [found.filter((f) => !labelOnly(f)), found.filter(labelOnly)]) {
+    for (const test of tiers(target)) {
+      const matches = pool.filter((f) => test(f.element));
+      if (matches.length)
+        return isAt(target) ? matches.sort((a, b) => area(a) - area(b)) : matches;
+    }
   }
   return [];
 }
+var isAt = (target) => typeof target === "object" && target.at !== void 0;
 var indexOf = (target) => typeof target === "object" ? target.index : void 0;
 var clip = (s) => s.length > 40 ? `${s.slice(0, 39)}\u2026` : s;
 function describe(e) {
-  const bits = [e.kind];
+  const stated = e.checked !== void 0 || e.selected !== void 0 || e.expanded !== void 0;
+  const bits = [stated && e.role ? e.role : e.kind];
+  if (e.webview !== void 0) bits.push(JSON.stringify(e.webview));
   if (e.testID) bits.push(`#${e.testID}`);
   if (e.text) bits.push(JSON.stringify(clip(e.text)));
   if (e.label && e.label !== e.text) bits.push(`label=${JSON.stringify(clip(e.label))}`);
   if (e.placeholder) bits.push(`placeholder=${JSON.stringify(clip(e.placeholder))}`);
   if (e.value !== void 0) bits.push(`value=${JSON.stringify(clip(e.value))}`);
+  if (e.checked !== void 0) bits.push(e.checked === true ? "checked" : e.checked === false ? "unchecked" : "mixed");
+  if (e.selected !== void 0) bits.push(e.selected ? "selected" : "unselected");
+  if (e.expanded !== void 0) bits.push(e.expanded ? "expanded" : "collapsed");
   if (e.disabled) bits.push("disabled");
   return bits.join(" ");
 }
 var showTarget = (target) => JSON.stringify(target);
 function onScreenSummary(found, max = 15) {
-  const on = found.filter((f) => f.onScreen);
+  const on = found.filter((f) => f.onScreen && !f.hidden);
   if (!on.length) return "nothing";
   const shown = on.slice(0, max).map((f) => describe(f.element));
   if (on.length > max) shown.push(`+${on.length - max} more`);
   return shown.join("; ");
 }
-function resolveTarget(found, target, prefer) {
+function resolveTarget(found, target, prefer, options) {
+  const reachable = found.filter((f) => !f.hidden);
   let matches = matchTarget(
-    found.filter((f) => f.onScreen),
+    reachable.filter((f) => f.onScreen),
     target
   );
+  if (!matches.length && options?.offscreen) matches = matchTarget(reachable, target);
   if (!matches.length) {
     const hidden = matchTarget(found, target)[0];
+    if (hidden?.hidden)
+      throw new Error(
+        `${showTarget(target)} matches ${describe(hidden.element)}, which is on a screen that is not in front (an unfocused tab or stack screen, or behind a modal). screen.snapshot {all:true} lists it`
+      );
     if (hidden)
       throw new Error(
-        `${showTarget(target)} matches ${describe(hidden.element)}, which is not on screen`
+        `${showTarget(target)} matches ${describe(hidden.element)}, which is not on screen. Pass {scroll:true} to scroll it into view, or use screen.scroll`
       );
+    const unrendered = options?.offscreen ? ". A list renders only the rows near its window: for a row it has not rendered yet, screen.scroll {toEnd:true} or {by: points} first" : "";
     throw new Error(
-      `Nothing on screen matches ${showTarget(target)}. On screen: ${onScreenSummary(found)}`
+      `Nothing on screen matches ${showTarget(target)}. On screen: ${onScreenSummary(found)}${unrendered}`
     );
   }
   const preferred = prefer ? matches.filter(prefer) : [];
   if (preferred.length) matches = preferred;
-  const index = indexOf(target);
+  const index = options?.index ?? indexOf(target) ?? (isAt(target) ? 0 : void 0);
   if (index !== void 0) {
     const pick = matches[index];
     if (!pick)
@@ -540,8 +897,9 @@ function resolveTarget(found, target, prefer) {
   }
   if (matches.length > 1) {
     const list = matches.slice(0, 10).map((f, i) => `${i}: ${describe(f.element)}`).join("; ");
+    const example = typeof target === "string" ? `${JSON.stringify(options?.afterText ? [target, "<text>", { index: 1 }] : [target, { index: 1 }])} (index as the last argument)` : `${JSON.stringify({ ...target, index: 1 })} (index inside the target)`;
     throw new Error(
-      `${showTarget(target)} matches ${matches.length} elements; pass { index } or a narrower target. ${list}`
+      `${showTarget(target)} matches ${matches.length} elements; pick one with an index, e.g. ${example}, or use a narrower target. ${list}`
     );
   }
   return matches[0];
@@ -584,11 +942,13 @@ function fillInput(found, text, options = {}) {
   return value;
 }
 var center = (rect) => rect ? { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 } : { x: 0, y: 0 };
-function pressElement(found) {
+function pressElement(found, options = {}) {
   const fiber = pressFiberOf(found);
   if (!fiber) throw new Error(`${describe(found.element)} has no onPress`);
-  if (found.element.disabled || propsOf(fiber)?.disabled === true)
-    throw new Error(`${describe(found.element)} is disabled`);
+  if (!options.force && (found.element.disabled || propsOf(fiber)?.disabled === true))
+    throw new Error(
+      `${describe(found.element)} is disabled; pass {"force":true} as the last argument to press anyway`
+    );
   const { x, y } = center(found.element.rect);
   const e = () => event({
     locationX: found.element.rect ? found.element.rect.width / 2 : 0,
@@ -602,6 +962,236 @@ function pressElement(found) {
   handler(fiber, "onPressOut")?.(e());
 }
 
+// src/runtime/screen/find-text.ts
+var normalize = (s) => s.toLowerCase().replace(/\s+/g, " ").trim();
+function nearMisses(found, text, max = 5) {
+  const want = normalize(text);
+  if (!want) return [];
+  const close = (s) => {
+    const have = s && normalize(s);
+    return !!have && (have.includes(want) || have.length >= 3 && want.includes(have));
+  };
+  return found.filter((f) => !f.hidden).filter((f) => close(f.element.text) || close(f.element.label)).slice(0, max).map((f) => `${describe(f.element)}${f.onScreen ? "" : " (off screen)"}`);
+}
+function findText(found, text, options = {}) {
+  const test = (s) => s !== void 0 && (options.exact ? s === text : s.includes(text));
+  const matches = [];
+  let hidden = 0;
+  for (const f of found) {
+    const { element } = f;
+    const field = test(element.text) ? "text" : options.labels !== false && test(element.label) ? "label" : null;
+    if (!field) continue;
+    if (f.hidden) {
+      hidden += 1;
+      continue;
+    }
+    matches.push({
+      text: field === "text" ? element.text : element.label,
+      field,
+      rect: element.rect,
+      onScreen: f.onScreen
+    });
+  }
+  const result = {
+    found: matches.length,
+    onScreen: matches.filter((m) => m.onScreen).length,
+    matches
+  };
+  if (hidden) result.hidden = hidden;
+  if (!matches.length) result.nearMisses = nearMisses(found, text);
+  return result;
+}
+
+// src/runtime/screen/scroll.ts
+var COMMANDS = ["to", "toEnd", "toStart", "by"];
+function parseScroll(arg) {
+  if (arg === null || typeof arg !== "object" || Array.isArray(arg) || !COMMANDS.some((k) => k in arg))
+    return { kind: "to", target: arg };
+  const keys = Object.keys(arg);
+  if (keys.length !== 1)
+    throw new Error(
+      `screen.scroll takes one of {to: target}, {toEnd:true}, {toStart:true} or {by: points}; got ${JSON.stringify(arg)}`
+    );
+  const [key] = keys;
+  const value = arg[key];
+  if (key === "to") return { kind: "to", target: value };
+  if (key === "by") {
+    if (typeof value !== "number" || !Number.isFinite(value))
+      throw new Error(`{by} is a number of points (negative scrolls back); got ${JSON.stringify(value)}`);
+    return { kind: "by", amount: value };
+  }
+  if (value !== true) throw new Error(`{${key}} must be true; got ${JSON.stringify(value)}`);
+  return { kind: key };
+}
+var nodeOf2 = (fiber) => {
+  const n = fiber.stateNode;
+  return n && typeof n === "object" ? n : null;
+};
+var method = (fiber, name) => {
+  const node = nodeOf2(fiber);
+  const fn = node?.[name];
+  return typeof fn === "function" ? fn.bind(node) : null;
+};
+var isHorizontal = (s) => s.fibers.some((f) => propsOf(f)?.horizontal === true);
+function scrollNode(s) {
+  if (!REFRESH_HOST.test(String(s.host.type))) return s.host;
+  const todo = s.host.child ? [s.host.child] : [];
+  while (todo.length) {
+    const f = todo.pop();
+    if (f.sibling) todo.push(f.sibling);
+    if (f.tag === 5) return f;
+    if (f.child) todo.push(f.child);
+  }
+  return s.host;
+}
+function contentHost(node) {
+  const todo = node.child ? [node.child] : [];
+  while (todo.length) {
+    const f = todo.pop();
+    if (f.sibling) todo.push(f.sibling);
+    if (f.tag === 5) {
+      if (!REFRESH_HOST.test(String(f.type))) return f;
+    } else if (f.child) todo.push(f.child);
+  }
+  return null;
+}
+function isInverted(s, horizontal) {
+  const axis = horizontal ? "scaleX" : "scaleY";
+  return s.fibers.some((f) => {
+    const p = propsOf(f);
+    if (p?.inverted === true) return true;
+    const style = [].concat(p?.style ?? []).flat(Infinity);
+    return style.some((st) => {
+      const t = st?.transform;
+      return Array.isArray(t) && t.some(
+        (x) => x && typeof x === "object" && (x[axis] === -1 || x.scale === -1)
+      );
+    });
+  });
+}
+function metricsOf(s) {
+  const horizontal = isHorizontal(s);
+  const host = scrollNode(s);
+  const node = nodeOf2(host);
+  const view = measureHost(host);
+  if (node && typeof node.scrollTop === "number" && typeof node.scrollHeight === "number") {
+    const size = horizontal ? [node.scrollLeft, node.scrollWidth, node.clientWidth] : [node.scrollTop, node.scrollHeight, node.clientHeight];
+    const [offset, total, shown2] = size;
+    return {
+      offset,
+      max: Math.max(0, total - shown2),
+      view,
+      inverted: false
+    };
+  }
+  const content = contentHost(host);
+  const box = content && measureHost(content);
+  if (!view || !box) return null;
+  const max = Math.max(0, horizontal ? box.width - view.width : box.height - view.height);
+  const shown = horizontal ? view.x - box.x : view.y - box.y;
+  const inverted = isInverted(s, horizontal);
+  return { offset: inverted ? max - shown : shown, max, view, inverted };
+}
+var round2 = (n) => Math.round(n * 100) / 100;
+function scrollToOffset(s, offset) {
+  const horizontal = isHorizontal(s);
+  const x = horizontal ? offset : 0;
+  const y = horizontal ? 0 : offset;
+  const target = { x, y, left: x, top: y, animated: false, behavior: "instant" };
+  for (const f of [...s.fibers].reverse()) {
+    const scrollTo = method(f, "scrollTo");
+    if (scrollTo) return void scrollTo(target);
+  }
+  for (const f of s.fibers) {
+    const toOffset = method(f, "scrollToOffset");
+    if (toOffset) return void toOffset({ offset, animated: false });
+  }
+  throw new Error("This scrollable has no scrollTo or scrollToOffset");
+}
+function scrollToEnd(s) {
+  for (const f of s.fibers) {
+    const toEnd = method(f, "scrollToEnd");
+    if (toEnd) return void toEnd({ animated: false });
+  }
+  const max = metricsOf(s)?.max;
+  if (max == null) throw new Error("This scrollable has no scrollToEnd and its size is unknown");
+  scrollToOffset(s, max);
+}
+var scrollEnabled = (s) => !s.fibers.some((f) => propsOf(f)?.scrollEnabled === false);
+function offsetFor(s, found, window) {
+  const rect = found.element.rect;
+  const m = metricsOf(s);
+  if (!rect || !m?.view) return null;
+  const view = viewportOf(s, m.view, window) ?? m.view;
+  const [start, size, viewStart, viewSize] = isHorizontal(s) ? [rect.x, rect.width, view.x, view.width] : [rect.y, rect.height, view.y, view.height];
+  if (start >= viewStart && start + size <= viewStart + viewSize) return null;
+  const delta = size >= viewSize ? start - viewStart : start + size / 2 - (viewStart + viewSize / 2);
+  const next = Math.max(0, Math.min(m.max ?? Infinity, m.offset + (m.inverted ? -delta : delta)));
+  return Math.abs(next - m.offset) < 1 ? null : round2(next);
+}
+function scrollerFor(found, window) {
+  for (let s = found.scroller; s; s = s.parent) {
+    if (s.hidden || s.host === found.host || !scrollEnabled(s)) continue;
+    const offset = offsetFor(s, found, window);
+    if (offset !== null) return { scrollable: s, offset };
+  }
+  return null;
+}
+var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function awaitScroll(s, before, want) {
+  const near = (x, to) => !!x && to !== void 0 && Math.abs(x.offset - to) < 1;
+  let m = metricsOf(s);
+  if (!m || near(m, want)) return m;
+  let idle = 0;
+  for (let waited = 0; waited < 300; waited += 16) {
+    await wait(16);
+    const next = metricsOf(s);
+    if (!next || near(next, want)) return next;
+    idle = Math.abs(next.offset - m.offset) < 1 ? idle + 1 : 0;
+    m = next;
+    if (idle >= 2 && !near(m, before)) break;
+  }
+  return m;
+}
+function refreshHandler(s) {
+  for (const f of s.fibers) {
+    const p = propsOf(f);
+    const control = p?.refreshControl?.props;
+    if (typeof control?.onRefresh === "function") return control.onRefresh;
+    if (typeof p?.onRefresh === "function") return p.onRefresh;
+  }
+  return null;
+}
+function draggable(s) {
+  for (let x = s; x; x = x.parent) if (!x.hidden && scrollEnabled(x)) return x;
+  return null;
+}
+function layoutOf(scrollables, window) {
+  let ready = true;
+  const parts = [];
+  for (const s of scrollables) {
+    if (s.hidden) continue;
+    const view = measureHost(s.host);
+    if (!view) continue;
+    const m = metricsOf(s);
+    if (view.width <= 0 || view.height <= 0 || !m?.view) ready = false;
+    const limit = viewportOf(s, view, window);
+    parts.push(JSON.stringify([view, m && [m.max, m.offset], limit]));
+  }
+  return { ready, sig: parts.join("|") };
+}
+var area2 = (r) => r ? r.width * r.height : 0;
+var onWindow = (r, w) => !!r && r.width > 0 && r.height > 0 && r.x < w.width && r.y < w.height && r.x + r.width > 0 && r.y + r.height > 0;
+function mainScrollable(scrollables, window, need) {
+  const candidates = scrollables.filter((s) => !s.hidden && (need === "refresh" ? refreshHandler(s) : scrollEnabled(s))).map((s) => ({ s, rect: measureHost(s.host) })).filter(({ rect }) => onWindow(rect, window)).map(({ s, rect }) => ({ s, rect: viewportOf(s, rect, window) })).filter(({ rect }) => !!rect).sort((a, b) => area2(b.rect) - area2(a.rect));
+  const [best] = candidates;
+  if (!best)
+    throw new Error(
+      need === "refresh" ? "No scrollable on screen has a RefreshControl (or an onRefresh prop)" : "No scrollable on screen"
+    );
+  return best.s;
+}
+
 // src/runtime/screen/settle.ts
 var STATE = /* @__PURE__ */ Symbol.for("@avasapp/agent-bridge/commits");
 var UPDATE_LANES = (1 << 22) - 1;
@@ -673,6 +1263,11 @@ async function settle(options = {}) {
 
 // src/runtime/screen/wait-for.ts
 var POLL_MS = 50;
+function nearMissNote(found, target) {
+  const text = typeof target === "string" ? target : target.text;
+  const near = text ? nearMisses(found, text) : [];
+  return near.length ? `. Near misses: ${near.join("; ")}` : "";
+}
 function waitForTarget(collect, target, options = {}) {
   const timeoutMs = options.timeoutMs ?? 5e3;
   const t0 = performance.now();
@@ -691,7 +1286,7 @@ function waitForTarget(collect, target, options = {}) {
       try {
         const found = collect();
         const matches = matchTarget(
-          found.filter((f) => f.onScreen),
+          found.filter((f) => f.onScreen && !f.hidden),
           target
         );
         const hit = matches[indexOf(target) ?? 0];
@@ -703,7 +1298,7 @@ function waitForTarget(collect, target, options = {}) {
           const what = options.gone ? "to disappear" : "to appear";
           reject(
             new Error(
-              `Timed out after ${timeoutMs} ms waiting for ${showTarget(target)} ${what}. On screen: ${onScreenSummary(found)}`
+              `Timed out after ${timeoutMs} ms waiting for ${showTarget(target)} ${what}. On screen: ${onScreenSummary(found)}${nearMissNote(found, target)}`
             )
           );
         }
@@ -724,41 +1319,184 @@ function waitForTarget(collect, target, options = {}) {
 
 // src/runtime/screen/index.ts
 function createScreen(env) {
-  const collect = () => collectElements(env.roots(), env.window());
-  const refresh = (found) => {
+  const collectAll = () => collectScreen(env.roots(), env.window());
+  const collect = () => collectAll().found;
+  const collectSettled = async () => {
+    let prev = null;
+    let same = 0;
+    for (let waited = 0; ; waited += 16) {
+      const all = collectAll();
+      const { ready, sig } = layoutOf(all.scrollables, env.window());
+      same = sig === prev ? same + 1 : 0;
+      if (waited >= 320 || (ready ? same >= 3 : same >= 6)) return all;
+      prev = sig;
+      await wait(16);
+    }
+  };
+  const reread = (found) => {
     const node = found.host.stateNode;
     const again = collect().find(
       (f) => f.host === found.host || node != null && f.host.stateNode === node
     );
-    return (again ?? found).element;
+    return again ?? found;
+  };
+  const scrollableOf = (found, what) => {
+    if (!found.scroller)
+      throw new Error(`${describe(found.element)} ${what}`);
+    return found.scroller;
+  };
+  const scrolled = async (scrollable, act) => {
+    const before = metricsOf(scrollable);
+    const want = act();
+    await settle();
+    return awaitScroll(scrollable, before?.offset, want ?? before?.max ?? void 0);
+  };
+  const bringIntoView = async (found) => {
+    let current = found;
+    let metrics = null;
+    for (let i = 0; i < 4; i++) {
+      const plan = scrollerFor(current, env.window());
+      if (!plan) break;
+      metrics = await scrolled(plan.scrollable, () => {
+        scrollToOffset(plan.scrollable, plan.offset);
+        return plan.offset;
+      });
+      current = reread(current);
+    }
+    if (!metrics && current.scroller) metrics = metricsOf(current.scroller);
+    return { found: current, metrics };
+  };
+  const resolve = async (target, prefer, options) => {
+    let found = resolveTarget(collect(), target, prefer, {
+      ...options,
+      offscreen: options.scroll
+    });
+    if (found.onScreen) return found;
+    found = (await bringIntoView(found)).found;
+    if (!found.onScreen)
+      throw new Error(
+        `${describe(found.element)} is not on screen and no scrollable around it can bring it into view`
+      );
+    return found;
   };
   return {
     snapshot(options = {}) {
       const found = collect();
-      if (!options.all)
-        return { elements: found.filter((f) => f.onScreen).map((f) => f.element) };
-      return {
-        elements: found.map((f) => ({ ...f.element, onScreen: f.onScreen }))
-      };
+      if (options.all)
+        return {
+          elements: found.map((f) => ({
+            ...f.element,
+            onScreen: f.onScreen,
+            ...f.hidden && { hidden: true }
+          }))
+        };
+      const shown = focused(found);
+      const elements = shown.filter((f) => f.onScreen).map((f) => f.element);
+      const hidden = found.length - shown.length;
+      return hidden ? { elements, hidden } : { elements };
     },
+    findText: (text, options) => findText(collect(), text, options),
     async fill(target, text, options = {}) {
-      const found = resolveTarget(collect(), target, (f) => !!f.input);
+      const found = await resolve(target, (f) => !!f.input, {
+        index: options.index,
+        afterText: true,
+        scroll: options.scroll
+      });
       const filled = fillInput(found, String(text), options);
       await settle();
-      return { filled, element: refresh(found) };
+      return { filled, element: reread(found).element };
     },
-    async press(target) {
-      const found = resolveTarget(collect(), target, (f) => !!f.press);
-      pressElement(found);
+    async press(target, options = {}) {
+      const found = await resolve(target, (f) => !!f.press, options);
+      pressElement(found, options);
       await settle();
       return found.element;
     },
+    /**
+     * Scrolls the nearest scrollable of a target (or `within`, or the main one
+     * on screen) to the target, to either end, or by a distance in points.
+     */
+    async scroll(arg, options = {}) {
+      const command = parseScroll(arg);
+      const { found: all, scrollables } = await collectSettled();
+      const named = options.within ? scrollableOf(
+        resolveTarget(all, options.within, void 0, { offscreen: true }),
+        "is not a scrollable or inside one"
+      ) : null;
+      const within2 = named && draggable(named);
+      if (named && !within2)
+        throw new Error(
+          `${describe(resolveTarget(all, options.within, void 0, { offscreen: true }).element)} can't be scrolled (scrollEnabled is false, or it is on a hidden screen) and no scrollable around it can`
+        );
+      const target = command.kind === "to" ? resolveTarget(all, command.target, void 0, {
+        index: options.index,
+        offscreen: true
+      }) : null;
+      let metrics;
+      let again = null;
+      if (target && !within2) {
+        scrollableOf(target, "is not inside a scrollable");
+        ({ found: again, metrics } = await bringIntoView(target));
+      } else if (target && within2) {
+        const offset = offsetFor(within2, target, env.window());
+        metrics = offset === null ? metricsOf(within2) : await scrolled(within2, () => (scrollToOffset(within2, offset), offset));
+        again = reread(target);
+      } else {
+        const scrollable = within2 ?? mainScrollable(scrollables, env.window(), "scroll");
+        metrics = await scrolled(scrollable, () => {
+          if (command.kind === "toEnd") {
+            scrollToEnd(scrollable);
+            return metricsOf(scrollable)?.max ?? void 0;
+          }
+          if (command.kind === "toStart") {
+            scrollToOffset(scrollable, 0);
+            return 0;
+          }
+          const now2 = metricsOf(scrollable);
+          if (!now2)
+            throw new Error("Can not read the scroll position, so can not scroll by a distance");
+          const next = Math.max(
+            0,
+            Math.min(now2.max ?? Infinity, now2.offset + command.amount)
+          );
+          scrollToOffset(scrollable, next);
+          return next;
+        });
+      }
+      const result = {};
+      if (metrics) {
+        result.offset = Math.round(metrics.offset * 100) / 100;
+        if (metrics.max != null) result.max = Math.round(metrics.max * 100) / 100;
+      }
+      if (again) {
+        result.element = again.element;
+        result.onScreen = again.onScreen;
+      }
+      return result;
+    },
+    /** Calls the `onRefresh` of a scrollable's RefreshControl, as a pull would. */
+    async refresh(target, options = {}) {
+      const { found: all, scrollables } = collectAll();
+      const scrollable = target ? scrollableOf(
+        resolveTarget(all, target, void 0, {
+          index: options.index,
+          offscreen: true
+        }),
+        "is not a scrollable or inside one"
+      ) : mainScrollable(scrollables, env.window(), "refresh");
+      const onRefresh = refreshHandler(scrollable);
+      if (!onRefresh) throw new Error("That scrollable has no RefreshControl (or onRefresh prop)");
+      onRefresh();
+      await settle();
+      return { refreshed: true };
+    },
     waitFor: (target, options) => waitForTarget(collect, target, options)
   };
 }
 
 // src/runtime/tools/screen.ts
 var devToolsHook = () => globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+var TARGET_HELP = "target is a string (testID, label, placeholder or text) or an object that must match every key it sets: {testID, label, placeholder, text, at:[x,y], index}. Unknown keys are errors. {at:[x,y]} hits the smallest element covering that point, for icon-only buttons with no label. Several matches: add an index, either in the target or as a trailing {index:n} argument.";
 function screenTools() {
   const screen = createScreen({
     roots: () => fiberRoots(devToolsHook()),
@@ -766,28 +1504,31 @@ function screenTools() {
   });
   return {
     "screen.findText": {
-      description: "Find rendered text (substring, or exact with {exact:true}) and whether it is on screen. Ignores inactive tabs and screens.",
-      run: (text, options) => findTextInTree(
-        fiberRoots(devToolsHook()),
-        text,
-        import_react_native.Dimensions.get("window"),
-        options
-      )
+      description: "Find text on screen (substring, or exact with {exact:true}) and whether each match is on screen. Searches the same joined text screen.snapshot shows (nested Text concatenated) and accessibility labels; {labels:false} searches text only. Each match says which field matched; a miss lists near misses. Ignores screens the user can't reach (unfocused tabs and stack screens, under a modal); `hidden` counts matches there.",
+      run: (text, options) => screen.findText(text, options)
     },
     "screen.snapshot": {
-      description: "Buttons, inputs, text and testID views on screen, with rects. {all:true} adds off-screen ones.",
+      description: "Buttons, inputs, text, and testID or labelled views on screen, with rects and checked/selected/expanded state (a Switch's value is checked). Only the focused screen: unfocused tabs and stack screens, content under an open modal, display:none and accessibility-hidden subtrees are left out, and `hidden` counts the elements skipped. {all:true} lists everything, marking off-screen (onScreen:false) and hidden (hidden:true) ones. A WebView registered with the react-native-webview adapter shows as one `webview` element with its name: use webview.* inside it.",
       run: (options) => screen.snapshot(options)
     },
     "screen.fill": {
-      description: "Type into an input by testID, label, placeholder or text, then wait for the render. {submit:true} also submits.",
+      description: `Type into an input, then wait for the render. ${TARGET_HELP} {submit:true} also submits.`,
       run: (target, text, options) => screen.fill(target, text, options)
     },
     "screen.press": {
-      description: "Press a button by testID, label or text, then wait for the render.",
-      run: (target) => screen.press(target)
+      description: `Press a button, then wait for the render. ${TARGET_HELP} Disabled elements are refused; {force:true} presses anyway, to see what the app does on tap. {scroll:true} scrolls an off-screen target into view first.`,
+      run: (target, options) => screen.press(target, options)
+    },
+    "screen.scroll": {
+      description: `Scroll the nearest ScrollView/FlatList/FlashList, then wait for the render. Takes a target (or {to: target}) to bring into the middle of its scrollable, {toEnd:true}, {toStart:true}, or {by: points} (negative scrolls back); the last argument may be {within: target, index} to name the scrollable (a target inside it, or its testID). Without a target it scrolls the largest scrollable on screen. Only rendered elements can be targeted: rows a FlatList has not rendered yet need {toEnd:true} or {by} first. Returns the offset and, for a target, whether it is now on screen. ${TARGET_HELP}`,
+      run: (arg, options) => screen.scroll(arg, options)
+    },
+    "screen.refresh": {
+      description: "Pull to refresh: call the onRefresh of the RefreshControl of the scrollable holding a target (or the largest one with a RefreshControl on screen), then wait for the render. It does not wait for the data: follow with screen.waitFor.",
+      run: (target, options) => screen.refresh(target, options)
     },
     "screen.waitFor": {
-      description: "Wait until a target is on screen, or gone with {gone:true}. Default timeout 5000 ms.",
+      description: "Wait until a target is on screen, or gone with {gone:true}. Matches testID, label, placeholder, then the same joined text screen.snapshot shows. Default timeout 5000 ms; a timeout lists near misses.",
       run: (target, options) => screen.waitFor(target, options)
     }
   };
@@ -797,9 +1538,13 @@ function screenTools() {
 function builtinTools(listTools, getTools, logs, getScenarios) {
   return {
     ...bridgeTools(listTools),
+    ...appTools(
+      selectReload(globalThis, () => import_react_native2.DevSettings.reload())
+    ),
     ...logTools(logs),
     ...restoreTools(getTools),
     ...screenTools(),
+    ...captureTools(loadViewShot),
     // Only when the app defines scenarios, so `tools` doesn't list empty ones.
     ...getScenarios && scenarioTools(getScenarios, getTools)
   };
@@ -862,6 +1607,9 @@ function createGate(name) {
   };
 }
 
+// src/runtime/load-id.ts
+var loadId = Math.random().toString(36).slice(2, 10);
+
 // src/runtime/logs.ts
 var CAPACITY = 200;
 var STACK_LINES = 10;
@@ -1043,7 +1791,7 @@ function toJson(value) {
 function unwrap(definition) {
   return typeof definition === "function" ? { run: definition } : definition;
 }
-function createRegistry(getTools, logs) {
+function createRegistry(getTools, logs, loadId2) {
   const list = () => Object.entries(getTools()).map(([name, definition]) => ({
     name,
     description: unwrap(definition).description
@@ -1052,7 +1800,12 @@ function createRegistry(getTools, logs) {
     const end = logs?.begin(call.tool);
     const result = await run(call, from).finally(end);
     const errors = logs?.takeErrors();
-    return errors?.length ? { ...result, logs: errors } : result;
+    const stamped = loadId2 ? { ...result, loadId: loadId2, ...pending() } : result;
+    return errors?.length ? { ...stamped, logs: errors } : stamped;
+  }
+  function pending() {
+    const areas = Object.keys(pendingByArea(getTools()));
+    return areas.length ? { pending: areas } : {};
   }
   async function run(call, from) {
     const t0 = performance.now();
@@ -1063,7 +1816,13 @@ function createRegistry(getTools, logs) {
         const known = list().map((t) => t.name).join(", ");
         throw new Error(`Unknown tool "${call.tool}". Known: ${known}`);
       }
-      const value = await unwrap(definition).run(...call.args ?? []);
+      const { run: tool, maxArgs } = unwrap(definition);
+      const args = call.args ?? [];
+      if (maxArgs !== void 0 && args.length > maxArgs)
+        throw new Error(
+          `${call.tool} takes at most ${maxArgs} argument${maxArgs === 1 ? "" : "s"}, got ${args.length}. A JSON array is spread into the arguments; wrap it once more to pass an array as one argument.`
+        );
+      const value = await tool(...args);
       return { id: call.id, from, ok: true, value: toJson(value), ms: ms() };
     } catch (error) {
       const message2 = error instanceof Error ? error.message : String(error);
@@ -1085,12 +1844,13 @@ function startAgentBridge(options = {}) {
     ...builtinTools(() => registry.list(), allTools, logs.capture, getScenarios),
     ...userTools()
   });
-  const registry = createRegistry(allTools, logs.capture);
+  const registry = createRegistry(allTools, logs.capture, loadId);
   const info = () => ({
     deviceId,
-    name: options.name ?? import_react_native2.Platform.OS,
-    platform: import_react_native2.Platform.OS,
+    name: options.name ?? import_react_native3.Platform.OS,
+    platform: import_react_native3.Platform.OS,
     protocol: PROTOCOL_VERSION,
+    loadId,
     tools: registry.list()
   });
   const context = {