browserclaw 0.5.7 → 0.5.8

package/dist/index.cjs

@@ -1441,6 +1441,64 @@ async function stopChrome(running, timeoutMs = 2500) {
   } catch {
   }
 }
+var BrowserTabNotFoundError = class extends Error {
+  constructor(message = "Tab not found") {
+    super(message);
+    this.name = "BrowserTabNotFoundError";
+  }
+};
+var OPENCLAW_EXTENSION_RELAY_BROWSER = "OpenClaw/extension-relay";
+var extensionRelayByCdpUrl = /* @__PURE__ */ new Map();
+async function fetchJsonForCdp(url, timeoutMs) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+function appendCdpPath2(cdpUrl, cdpPath) {
+  try {
+    const url = new URL(cdpUrl);
+    url.pathname = `${url.pathname.replace(/\/$/, "")}${cdpPath.startsWith("/") ? cdpPath : `/${cdpPath}`}`;
+    return url.toString();
+  } catch {
+    return `${cdpUrl.replace(/\/$/, "")}${cdpPath}`;
+  }
+}
+async function isExtensionRelayCdpEndpoint(cdpUrl) {
+  const normalized = normalizeCdpUrl(cdpUrl);
+  const cached = extensionRelayByCdpUrl.get(normalized);
+  if (cached !== void 0) return cached;
+  try {
+    const version = await fetchJsonForCdp(appendCdpPath2(normalizeCdpHttpBaseForJsonEndpoints(normalized), "/json/version"), 2e3);
+    const isRelay = String(version?.Browser ?? "").trim() === OPENCLAW_EXTENSION_RELAY_BROWSER;
+    extensionRelayByCdpUrl.set(normalized, isRelay);
+    return isRelay;
+  } catch {
+    extensionRelayByCdpUrl.set(normalized, false);
+    return false;
+  }
+}
+async function withPlaywrightPageCdpSession(page, fn) {
+  const session = await page.context().newCDPSession(page);
+  try {
+    return await fn(session);
+  } finally {
+    await session.detach().catch(() => {
+    });
+  }
+}
+async function withPageScopedCdpClient(opts) {
+  return await withPlaywrightPageCdpSession(opts.page, async (session) => {
+    return await opts.fn((method, params) => session.send(method, params));
+  });
+}
 var LOOPBACK_ENTRIES = "localhost,127.0.0.1,[::1]";
 function noProxyAlreadyCoversLocalhost() {
   const current = process.env.NO_PROXY || process.env.no_proxy || "";
@@ -1713,9 +1771,11 @@ async function connectBrowser(cdpUrl, authToken) {
         if (authToken && !headers["Authorization"]) headers["Authorization"] = `Bearer ${authToken}`;
         const browser = await withNoProxyForCdpUrl(endpoint, () => playwrightCore.chromium.connectOverCDP(endpoint, { timeout, headers }));
         const onDisconnected = () => {
-          if (cachedByCdpUrl.get(normalized)?.browser === browser) cachedByCdpUrl.delete(normalized);
-          for (const key of roleRefsByTarget.keys()) {
-            if (key.startsWith(normalized + "::")) roleRefsByTarget.delete(key);
+          if (cachedByCdpUrl.get(normalized)?.browser === browser) {
+            cachedByCdpUrl.delete(normalized);
+            for (const key of roleRefsByTarget.keys()) {
+              if (key.startsWith(normalized + "::")) roleRefsByTarget.delete(key);
+            }
           }
         };
         const connected = { browser, cdpUrl: normalized, onDisconnected };
@@ -1859,8 +1919,36 @@ async function pageTargetId(page) {
     });
   }
 }
+function matchPageByTargetList(pages, targets, targetId) {
+  const target = targets.find((entry) => entry.id === targetId);
+  if (!target) return null;
+  const urlMatch = pages.filter((page) => page.url() === target.url);
+  if (urlMatch.length === 1) return urlMatch[0] ?? null;
+  if (urlMatch.length > 1) {
+    const sameUrlTargets = targets.filter((entry) => entry.url === target.url);
+    if (sameUrlTargets.length === urlMatch.length) {
+      const idx = sameUrlTargets.findIndex((entry) => entry.id === targetId);
+      if (idx >= 0 && idx < urlMatch.length) return urlMatch[idx] ?? null;
+    }
+  }
+  return null;
+}
+async function findPageByTargetIdViaTargetList(pages, targetId, cdpUrl) {
+  const targets = await fetchJsonForCdp(appendCdpPath2(normalizeCdpHttpBaseForJsonEndpoints(cdpUrl), "/json/list"), 2e3);
+  if (!Array.isArray(targets)) return null;
+  return matchPageByTargetList(pages, targets, targetId);
+}
 async function findPageByTargetId(browser, targetId, cdpUrl) {
   const pages = await getAllPages(browser);
+  const isExtensionRelay = cdpUrl ? await isExtensionRelayCdpEndpoint(cdpUrl).catch(() => false) : false;
+  if (cdpUrl && isExtensionRelay) {
+    try {
+      const matched = await findPageByTargetIdViaTargetList(pages, targetId, cdpUrl);
+      if (matched) return matched;
+    } catch {
+    }
+    return pages.length === 1 ? pages[0] ?? null : null;
+  }
   let resolvedViaCdp = false;
   for (const page of pages) {
     let tid = null;
@@ -1874,34 +1962,11 @@ async function findPageByTargetId(browser, targetId, cdpUrl) {
   }
   if (cdpUrl) {
     try {
-      const listUrl = `${normalizeCdpHttpBaseForJsonEndpoints(cdpUrl)}/json/list`;
-      const headers = {};
-      const ctrl = new AbortController();
-      const t = setTimeout(() => ctrl.abort(), 2e3);
-      try {
-        const response = await fetch(listUrl, { headers, signal: ctrl.signal });
-        if (response.ok) {
-          const targets = await response.json();
-          const target = targets.find((entry) => entry.id === targetId);
-          if (target) {
-            const urlMatch = pages.filter((p) => p.url() === target.url);
-            if (urlMatch.length === 1) return urlMatch[0];
-            if (urlMatch.length > 1) {
-              const sameUrlTargets = targets.filter((entry) => entry.url === target.url);
-              if (sameUrlTargets.length === urlMatch.length) {
-                const idx = sameUrlTargets.findIndex((entry) => entry.id === targetId);
-                if (idx >= 0 && idx < urlMatch.length) return urlMatch[idx];
-              }
-            }
-          }
-        }
-      } finally {
-        clearTimeout(t);
-      }
+      return await findPageByTargetIdViaTargetList(pages, targetId, cdpUrl);
     } catch {
     }
   }
-  if (!resolvedViaCdp && pages.length === 1) return pages[0];
+  if (!resolvedViaCdp && pages.length === 1) return pages[0] ?? null;
   return null;
 }
 async function getPageForTargetId(opts) {
@@ -1913,10 +1978,49 @@ async function getPageForTargetId(opts) {
   const found = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
   if (!found) {
     if (pages.length === 1) return first;
-    throw new Error(`Tab not found (targetId: ${opts.targetId}). Call browser.tabs() to list open tabs.`);
+    throw new BrowserTabNotFoundError(`Tab not found (targetId: ${opts.targetId}). Call browser.tabs() to list open tabs.`);
   }
   return found;
 }
+async function resolvePageByTargetIdOrThrow(opts) {
+  const { browser } = await connectBrowser(opts.cdpUrl);
+  const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
+  if (!page) throw new BrowserTabNotFoundError();
+  return page;
+}
+function parseRoleRef(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  const normalized = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed.startsWith("ref=") ? trimmed.slice(4) : trimmed;
+  return /^e\d+$/.test(normalized) ? normalized : null;
+}
+function requireRef(value) {
+  const raw = typeof value === "string" ? value.trim() : "";
+  const ref = (raw ? parseRoleRef(raw) : null) ?? (raw.startsWith("@") ? raw.slice(1) : raw);
+  if (!ref) throw new Error("ref is required");
+  return ref;
+}
+function requireRefOrSelector(ref, selector) {
+  const trimmedRef = typeof ref === "string" ? ref.trim() : "";
+  const trimmedSelector = typeof selector === "string" ? selector.trim() : "";
+  if (!trimmedRef && !trimmedSelector) throw new Error("ref or selector is required");
+  return { ref: trimmedRef || void 0, selector: trimmedSelector || void 0 };
+}
+function resolveInteractionTimeoutMs(timeoutMs) {
+  return Math.max(500, Math.min(6e4, Math.floor(timeoutMs ?? 8e3)));
+}
+function resolveBoundedDelayMs(value, label, maxMs) {
+  const normalized = Math.floor(value ?? 0);
+  if (!Number.isFinite(normalized) || normalized < 0) throw new Error(`${label} must be >= 0`);
+  if (normalized > maxMs) throw new Error(`${label} exceeds maximum of ${maxMs}ms`);
+  return normalized;
+}
+async function getRestoredPageForTarget(opts) {
+  const page = await getPageForTargetId(opts);
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  return page;
+}
 function refLocator(page, ref) {
   const normalized = ref.startsWith("@") ? ref.slice(1) : ref.startsWith("ref=") ? ref.slice(4) : ref;
   if (!normalized.trim()) throw new Error("ref is required");
@@ -2232,12 +2336,14 @@ async function snapshotAi(opts) {
   let snapshot = String(result?.full ?? "");
   const maxChars = opts.maxChars;
   const limit = typeof maxChars === "number" && Number.isFinite(maxChars) && maxChars > 0 ? Math.floor(maxChars) : void 0;
+  let truncated = false;
   if (limit && snapshot.length > limit) {
     const lastNewline = snapshot.lastIndexOf("\n", limit);
     const cutoff = lastNewline > 0 ? lastNewline : limit;
     snapshot = `${snapshot.slice(0, cutoff)}
 
 [...TRUNCATED - page too large]`;
+    truncated = true;
   }
   const built = buildRoleSnapshotFromAiSnapshot(snapshot, opts.options);
   storeRoleRefsForTarget({
@@ -2251,6 +2357,7 @@ async function snapshotAi(opts) {
     snapshot: built.snapshot,
     refs: built.refs,
     stats: getRoleSnapshotStats(built.snapshot, built.refs),
+    ...truncated ? { truncated } : {},
     untrusted: true,
     contentMeta: {
       sourceUrl,
@@ -2324,24 +2431,20 @@ async function snapshotAria(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const sourceUrl = page.url();
-  const session = await page.context().newCDPSession(page);
-  try {
+  const res = await withPlaywrightPageCdpSession(page, async (session) => {
     await session.send("Accessibility.enable").catch(() => {
     });
-    const res = await session.send("Accessibility.getFullAXTree");
-    return {
-      nodes: formatAriaNodes(Array.isArray(res?.nodes) ? res.nodes : [], limit),
-      untrusted: true,
-      contentMeta: {
-        sourceUrl,
-        contentType: "browser-aria-tree",
-        capturedAt: (/* @__PURE__ */ new Date()).toISOString()
-      }
-    };
-  } finally {
-    await session.detach().catch(() => {
-    });
-  }
+    return await session.send("Accessibility.getFullAXTree");
+  });
+  return {
+    nodes: formatAriaNodes(Array.isArray(res?.nodes) ? res.nodes : [], limit),
+    untrusted: true,
+    contentMeta: {
+      sourceUrl,
+      contentType: "browser-aria-tree",
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
 }
 function axValue(v) {
   if (!v || typeof v !== "object") return "";
@@ -2793,6 +2896,14 @@ async function assertSafeUploadPaths(paths) {
     }
   }
 }
+async function resolveStrictExistingUploadPaths(params) {
+  try {
+    await assertSafeUploadPaths(params.requestedPaths);
+    return { ok: true, paths: params.requestedPaths };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
 function sanitizeUntrustedFileName(fileName, fallbackName) {
   const trimmed = String(fileName ?? "").trim();
   if (!trimmed) return fallbackName;
@@ -2866,47 +2977,57 @@ function requiresInspectableBrowserNavigationRedirects(ssrfPolicy) {
 
 // src/actions/interaction.ts
 var MAX_CLICK_DELAY_MS = 5e3;
-function resolveBoundedDelayMs(value, label, maxMs) {
-  const normalized = Math.floor(value ?? 0);
-  if (!Number.isFinite(normalized) || normalized < 0) throw new Error(`${label} must be >= 0`);
-  if (normalized > maxMs) throw new Error(`${label} exceeds maximum of ${maxMs}ms`);
-  return normalized;
-}
-function resolveInteractionTimeoutMs(timeoutMs) {
-  return Math.max(500, Math.min(6e4, Math.floor(timeoutMs ?? 8e3)));
-}
-function requireRefOrSelector(ref, selector) {
-  const trimmedRef = typeof ref === "string" ? ref.trim() : "";
-  const trimmedSelector = typeof selector === "string" ? selector.trim() : "";
-  if (!trimmedRef && !trimmedSelector) throw new Error("ref or selector is required");
-  return { ref: trimmedRef || void 0, selector: trimmedSelector || void 0 };
-}
+var CHECKABLE_ROLES = /* @__PURE__ */ new Set(["menuitemcheckbox", "menuitemradio", "checkbox", "switch"]);
 function resolveLocator(page, resolved) {
   return resolved.ref ? refLocator(page, resolved.ref) : page.locator(resolved.selector);
 }
-async function getRestoredPageForTarget(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
-  return page;
-}
 async function clickViaPlaywright(opts) {
   const resolved = requireRefOrSelector(opts.ref, opts.selector);
   const page = await getRestoredPageForTarget(opts);
   const label = resolved.ref ?? resolved.selector;
   const locator = resolveLocator(page, resolved);
   const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
+  let checkableRole = false;
+  if (resolved.ref) {
+    const refId = parseRoleRef(resolved.ref);
+    if (refId) {
+      const state = ensurePageState(page);
+      const info = state.roleRefs?.[refId];
+      if (info && CHECKABLE_ROLES.has(info.role)) checkableRole = true;
+    }
+  }
   try {
     const delayMs = resolveBoundedDelayMs(opts.delayMs, "click delayMs", MAX_CLICK_DELAY_MS);
     if (delayMs > 0) {
       await locator.hover({ timeout });
       await new Promise((resolve2) => setTimeout(resolve2, delayMs));
     }
+    let ariaCheckedBefore;
+    if (checkableRole && !opts.doubleClick) {
+      ariaCheckedBefore = await locator.getAttribute("aria-checked", { timeout }).catch(() => void 0);
+    }
     if (opts.doubleClick) {
       await locator.dblclick({ timeout, button: opts.button, modifiers: opts.modifiers });
     } else {
       await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
     }
+    if (checkableRole && !opts.doubleClick && ariaCheckedBefore !== void 0) {
+      const POLL_INTERVAL_MS = 50;
+      const POLL_TIMEOUT_MS = 500;
+      let changed = false;
+      for (let elapsed = 0; elapsed < POLL_TIMEOUT_MS; elapsed += POLL_INTERVAL_MS) {
+        const current = await locator.getAttribute("aria-checked", { timeout }).catch(() => void 0);
+        if (current === void 0 || current !== ariaCheckedBefore) {
+          changed = true;
+          break;
+        }
+        await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
+      }
+      if (!changed) {
+        await locator.evaluate((el) => el.click()).catch(() => {
+        });
+      }
+    }
   } catch (err) {
     throw toAIFriendlyError(err, label);
   }
@@ -3006,10 +3127,11 @@ async function scrollIntoViewViaPlaywright(opts) {
 }
 async function highlightViaPlaywright(opts) {
   const page = await getRestoredPageForTarget(opts);
+  const ref = requireRef(opts.ref);
   try {
-    await refLocator(page, opts.ref).highlight();
+    await refLocator(page, ref).highlight();
   } catch (err) {
-    throw toAIFriendlyError(err, opts.ref);
+    throw toAIFriendlyError(err, ref);
   }
 }
 async function setInputFilesViaPlaywright(opts) {
@@ -3020,9 +3142,14 @@ async function setInputFilesViaPlaywright(opts) {
   if (inputRef && element) throw new Error("ref and element are mutually exclusive");
   if (!inputRef && !element) throw new Error("Either ref or element is required for setInputFiles");
   const locator = inputRef ? refLocator(page, inputRef) : page.locator(element).first();
-  await assertSafeUploadPaths(opts.paths);
+  const uploadPathsResult = await resolveStrictExistingUploadPaths({
+    requestedPaths: opts.paths,
+    scopeLabel: "uploads directory"
+  });
+  if (!uploadPathsResult.ok) throw new Error(uploadPathsResult.error);
+  const resolvedPaths = uploadPathsResult.paths;
   try {
-    await locator.setInputFiles(opts.paths);
+    await locator.setInputFiles(resolvedPaths);
   } catch (err) {
     throw toAIFriendlyError(err, inputRef || element);
   }
@@ -3065,16 +3192,18 @@ async function armFileUploadViaPlaywright(opts) {
       }
       return;
     }
-    try {
-      await assertSafeUploadPaths(opts.paths);
-    } catch {
+    const uploadPathsResult = await resolveStrictExistingUploadPaths({
+      requestedPaths: opts.paths,
+      scopeLabel: "uploads directory"
+    });
+    if (!uploadPathsResult.ok) {
       try {
         await page.keyboard.press("Escape");
       } catch {
       }
       return;
     }
-    await fileChooser.setFiles(opts.paths);
+    await fileChooser.setFiles(uploadPathsResult.paths);
     try {
       const input = typeof fileChooser.element === "function" ? await Promise.resolve(fileChooser.element()) : null;
       if (input) {
@@ -3146,21 +3275,21 @@ async function listPagesViaPlaywright(opts) {
   return results;
 }
 async function createPageViaPlaywright(opts) {
-  const targetUrl = (opts.url ?? "").trim() || "about:blank";
-  const policy = opts.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
-  if (targetUrl !== "about:blank") {
-    await assertBrowserNavigationAllowed({ url: targetUrl, ssrfPolicy: policy });
-  }
   const { browser } = await connectBrowser(opts.cdpUrl);
   const context = browser.contexts()[0] ?? await browser.newContext();
   ensureContextState(context);
   const page = await context.newPage();
   ensurePageState(page);
+  const targetUrl = (opts.url ?? "").trim() || "about:blank";
+  const policy = opts.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
   if (targetUrl !== "about:blank") {
     const navigationPolicy = withBrowserNavigationPolicy(policy);
-    const response = await page.goto(targetUrl, { timeout: 3e4 }).catch(() => null);
-    await assertBrowserNavigationRedirectChainAllowed({ request: response?.request(), ...navigationPolicy });
-    await assertBrowserNavigationResultAllowed({ url: page.url(), ssrfPolicy: policy });
+    await assertBrowserNavigationAllowed({ url: targetUrl, ...navigationPolicy });
+    await assertBrowserNavigationRedirectChainAllowed({
+      request: (await page.goto(targetUrl, { timeout: 3e4 }).catch(() => null))?.request(),
+      ...navigationPolicy
+    });
+    await assertBrowserNavigationResultAllowed({ url: page.url(), ...navigationPolicy });
   }
   const tid = await pageTargetId(page).catch(() => null);
   if (!tid) throw new Error("Failed to get targetId for new page");
@@ -3171,27 +3300,31 @@ async function createPageViaPlaywright(opts) {
     type: "page"
   };
 }
-async function closePageByTargetIdViaPlaywright(opts) {
-  const { browser } = await connectBrowser(opts.cdpUrl);
-  const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
-  if (!page) throw new Error(`Tab not found (targetId: ${opts.targetId}). Use browser.tabs() to list open tabs.`);
+async function closePageViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
   await page.close();
 }
+async function closePageByTargetIdViaPlaywright(opts) {
+  await (await resolvePageByTargetIdOrThrow(opts)).close();
+}
 async function focusPageByTargetIdViaPlaywright(opts) {
-  const { browser } = await connectBrowser(opts.cdpUrl);
-  const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
-  if (!page) throw new Error(`Tab not found (targetId: ${opts.targetId}). Use browser.tabs() to list open tabs.`);
+  const page = await resolvePageByTargetIdOrThrow(opts);
   try {
     await page.bringToFront();
   } catch (err) {
-    const session = await page.context().newCDPSession(page);
     try {
-      await session.send("Page.bringToFront");
+      await withPageScopedCdpClient({
+        cdpUrl: opts.cdpUrl,
+        page,
+        targetId: opts.targetId,
+        fn: async (send) => {
+          await send("Page.bringToFront");
+        }
+      });
+      return;
     } catch {
       throw err;
-    } finally {
-      await session.detach().catch(() => {
-      });
     }
   }
 }
@@ -3379,6 +3512,165 @@ async function evaluateViaPlaywright(opts) {
     if (signal && abortListener) signal.removeEventListener("abort", abortListener);
   }
 }
+
+// src/actions/batch.ts
+var MAX_BATCH_DEPTH = 5;
+var MAX_BATCH_ACTIONS = 100;
+async function executeSingleAction(action, cdpUrl, targetId, evaluateEnabled, depth = 0) {
+  if (depth > MAX_BATCH_DEPTH) throw new Error(`Batch nesting depth exceeds maximum of ${MAX_BATCH_DEPTH}`);
+  const effectiveTargetId = action.targetId ?? targetId;
+  switch (action.kind) {
+    case "click":
+      await clickViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        doubleClick: action.doubleClick,
+        button: action.button,
+        modifiers: action.modifiers,
+        delayMs: action.delayMs,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "type":
+      await typeViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        text: action.text,
+        submit: action.submit,
+        slowly: action.slowly,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "press":
+      await pressKeyViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        key: action.key,
+        delayMs: action.delayMs
+      });
+      break;
+    case "hover":
+      await hoverViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "scrollIntoView":
+      await scrollIntoViewViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "drag":
+      await dragViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        startRef: action.startRef,
+        startSelector: action.startSelector,
+        endRef: action.endRef,
+        endSelector: action.endSelector,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "select":
+      await selectOptionViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        values: action.values,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "fill":
+      await fillFormViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        fields: action.fields,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "resize":
+      await resizeViewportViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        width: action.width,
+        height: action.height
+      });
+      break;
+    case "wait":
+      if (action.fn && !evaluateEnabled) throw new Error("wait --fn is disabled by config (browser.evaluateEnabled=false)");
+      await waitForViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        timeMs: action.timeMs,
+        text: action.text,
+        textGone: action.textGone,
+        selector: action.selector,
+        url: action.url,
+        loadState: action.loadState,
+        fn: action.fn,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "evaluate":
+      if (!evaluateEnabled) throw new Error("act:evaluate is disabled by config (browser.evaluateEnabled=false)");
+      await evaluateViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        fn: action.fn,
+        ref: action.ref,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "close":
+      await closePageViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId
+      });
+      break;
+    case "batch":
+      await batchViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        actions: action.actions,
+        stopOnError: action.stopOnError,
+        evaluateEnabled,
+        depth: depth + 1
+      });
+      break;
+    default:
+      throw new Error(`Unsupported batch action kind: ${action.kind}`);
+  }
+}
+async function batchViaPlaywright(opts) {
+  const depth = opts.depth ?? 0;
+  if (depth > MAX_BATCH_DEPTH) throw new Error(`Batch nesting depth exceeds maximum of ${MAX_BATCH_DEPTH}`);
+  if (opts.actions.length > MAX_BATCH_ACTIONS) throw new Error(`Batch exceeds maximum of ${MAX_BATCH_ACTIONS} actions`);
+  const results = [];
+  const evaluateEnabled = opts.evaluateEnabled !== false;
+  for (const action of opts.actions) {
+    try {
+      await executeSingleAction(action, opts.cdpUrl, opts.targetId, evaluateEnabled, depth);
+      results.push({ ok: true });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      results.push({ ok: false, error: message });
+      if (opts.stopOnError !== false) break;
+    }
+  }
+  return { results };
+}
 function createPageDownloadWaiter(page, timeoutMs) {
   let done = false;
   let timer;
@@ -3500,32 +3792,33 @@ async function setDeviceViaPlaywright(opts) {
       height: device.viewport.height
     });
   }
-  const session = await page.context().newCDPSession(page);
-  try {
-    const locale = device.locale;
-    if (device.userAgent || locale) {
-      await session.send("Emulation.setUserAgentOverride", {
-        userAgent: device.userAgent ?? "",
-        acceptLanguage: locale ?? void 0
-      });
-    }
-    if (device.viewport) {
-      await session.send("Emulation.setDeviceMetricsOverride", {
-        mobile: Boolean(device.isMobile),
-        width: device.viewport.width,
-        height: device.viewport.height,
-        deviceScaleFactor: device.deviceScaleFactor ?? 1,
-        screenWidth: device.viewport.width,
-        screenHeight: device.viewport.height
-      });
-    }
-    if (device.hasTouch) {
-      await session.send("Emulation.setTouchEmulationEnabled", { enabled: true });
+  await withPageScopedCdpClient({
+    cdpUrl: opts.cdpUrl,
+    page,
+    targetId: opts.targetId,
+    fn: async (send) => {
+      const locale = device.locale;
+      if (device.userAgent || locale) {
+        await send("Emulation.setUserAgentOverride", {
+          userAgent: device.userAgent ?? "",
+          acceptLanguage: locale ?? void 0
+        });
+      }
+      if (device.viewport) {
+        await send("Emulation.setDeviceMetricsOverride", {
+          mobile: Boolean(device.isMobile),
+          width: device.viewport.width,
+          height: device.viewport.height,
+          deviceScaleFactor: device.deviceScaleFactor ?? 1,
+          screenWidth: device.viewport.width,
+          screenHeight: device.viewport.height
+        });
+      }
+      if (device.hasTouch) {
+        await send("Emulation.setTouchEmulationEnabled", { enabled: true });
+      }
     }
-  } finally {
-    await session.detach().catch(() => {
-    });
-  }
+  });
 }
 async function setExtraHTTPHeadersViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
@@ -3577,18 +3870,19 @@ async function setLocaleViaPlaywright(opts) {
   ensurePageState(page);
   const locale = String(opts.locale ?? "").trim();
   if (!locale) throw new Error("locale is required");
-  const session = await page.context().newCDPSession(page);
-  try {
-    try {
-      await session.send("Emulation.setLocaleOverride", { locale });
-    } catch (err) {
-      if (String(err).includes("Another locale override is already in effect")) return;
-      throw err;
+  await withPageScopedCdpClient({
+    cdpUrl: opts.cdpUrl,
+    page,
+    targetId: opts.targetId,
+    fn: async (send) => {
+      try {
+        await send("Emulation.setLocaleOverride", { locale });
+      } catch (err) {
+        if (String(err).includes("Another locale override is already in effect")) return;
+        throw err;
+      }
     }
-  } finally {
-    await session.detach().catch(() => {
-    });
-  }
+  });
 }
 async function setOfflineViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
@@ -3600,20 +3894,21 @@ async function setTimezoneViaPlaywright(opts) {
   ensurePageState(page);
   const timezoneId = String(opts.timezoneId ?? "").trim();
   if (!timezoneId) throw new Error("timezoneId is required");
-  const session = await page.context().newCDPSession(page);
-  try {
-    try {
-      await session.send("Emulation.setTimezoneOverride", { timezoneId });
-    } catch (err) {
-      const msg = String(err);
-      if (msg.includes("Timezone override is already in effect")) return;
-      if (msg.includes("Invalid timezone")) throw new Error(`Invalid timezone ID: ${timezoneId}`, { cause: err });
-      throw err;
+  await withPageScopedCdpClient({
+    cdpUrl: opts.cdpUrl,
+    page,
+    targetId: opts.targetId,
+    fn: async (send) => {
+      try {
+        await send("Emulation.setTimezoneOverride", { timezoneId });
+      } catch (err) {
+        const msg = String(err);
+        if (msg.includes("Timezone override is already in effect")) return;
+        if (msg.includes("Invalid timezone")) throw new Error(`Invalid timezone ID: ${timezoneId}`, { cause: err });
+        throw err;
+      }
     }
-  } finally {
-    await session.detach().catch(() => {
-    });
-  }
+  });
 }
 
 // src/capture/screenshot.ts
@@ -3636,47 +3931,65 @@ async function screenshotWithLabelsViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
-  const maxLabels = opts.maxLabels ?? 50;
+  const maxLabels = typeof opts.maxLabels === "number" && Number.isFinite(opts.maxLabels) ? Math.max(1, Math.floor(opts.maxLabels)) : 150;
   const type = opts.type ?? "png";
   const refs = opts.refs.slice(0, maxLabels);
   const skipped = opts.refs.slice(maxLabels);
+  const viewport = await page.evaluate(() => ({
+    width: window.innerWidth || 0,
+    height: window.innerHeight || 0
+  }));
   const labels = [];
   for (let i = 0; i < refs.length; i++) {
     const ref = refs[i];
     try {
       const locator = refLocator(page, ref);
       const box = await locator.boundingBox({ timeout: 2e3 });
-      if (box) {
-        labels.push({ ref, index: i + 1, box });
-      } else {
+      if (!box) {
         skipped.push(ref);
+        continue;
       }
+      const x1 = box.x + box.width;
+      const y1 = box.y + box.height;
+      if (x1 < 0 || box.x > viewport.width || y1 < 0 || box.y > viewport.height) {
+        skipped.push(ref);
+        continue;
+      }
+      labels.push({ ref, index: i + 1, box });
     } catch {
       skipped.push(ref);
     }
   }
-  await page.evaluate((labelData) => {
-    const container = document.createElement("div");
-    container.id = "__browserclaw_labels__";
-    container.style.cssText = "position:fixed;top:0;left:0;width:100%;height:100%;pointer-events:none;z-index:2147483647;";
-    for (const { index, box } of labelData) {
-      const border = document.createElement("div");
-      border.style.cssText = `position:absolute;left:${box.x}px;top:${box.y}px;width:${box.width}px;height:${box.height}px;border:2px solid #FF4500;box-sizing:border-box;`;
-      container.appendChild(border);
-      const badge = document.createElement("div");
-      badge.textContent = String(index);
-      badge.style.cssText = `position:absolute;left:${box.x}px;top:${Math.max(0, box.y - 18)}px;background:#FF4500;color:#fff;font:bold 12px/16px monospace;padding:0 4px;border-radius:2px;`;
-      container.appendChild(badge);
+  try {
+    if (labels.length > 0) {
+      await page.evaluate((labelData) => {
+        document.querySelectorAll("[data-browserclaw-labels]").forEach((el) => el.remove());
+        const container = document.createElement("div");
+        container.setAttribute("data-browserclaw-labels", "1");
+        container.style.cssText = "position:fixed;top:0;left:0;width:100%;height:100%;pointer-events:none;z-index:2147483647;";
+        for (const { index, box } of labelData) {
+          const border = document.createElement("div");
+          border.style.cssText = `position:absolute;left:${box.x}px;top:${box.y}px;width:${box.width}px;height:${box.height}px;border:2px solid #FF4500;box-sizing:border-box;`;
+          container.appendChild(border);
+          const badge = document.createElement("div");
+          badge.textContent = String(index);
+          badge.style.cssText = `position:absolute;left:${box.x}px;top:${Math.max(0, box.y - 18)}px;background:#FF4500;color:#fff;font:bold 12px/16px monospace;padding:0 4px;border-radius:2px;`;
+          container.appendChild(badge);
+        }
+        document.documentElement.appendChild(container);
+      }, labels.map((l) => ({ index: l.index, box: l.box })));
     }
-    document.body.appendChild(container);
-  }, labels.map((l) => ({ index: l.index, box: l.box })));
-  const buffer = await page.screenshot({ type });
-  await page.evaluate(() => {
-    const el = document.getElementById("__browserclaw_labels__");
-    if (el) el.remove();
-  }).catch(() => {
-  });
-  return { buffer, labels, skipped };
+    return {
+      buffer: await page.screenshot({ type }),
+      labels,
+      skipped
+    };
+  } finally {
+    await page.evaluate(() => {
+      document.querySelectorAll("[data-browserclaw-labels]").forEach((el) => el.remove());
+    }).catch(() => {
+    });
+  }
 }
 
 // src/capture/pdf.ts
@@ -3720,15 +4033,33 @@ async function traceStopViaPlaywright(opts) {
 }
 
 // src/capture/response.ts
+function matchUrlPattern(pattern, url) {
+  if (!pattern || !url) return false;
+  if (pattern === url) return true;
+  if (pattern.includes("*")) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    try {
+      return new RegExp(`^${escaped}$`).test(url);
+    } catch {
+      return false;
+    }
+  }
+  return url.includes(pattern);
+}
 async function responseBodyViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
-  const response = await page.waitForResponse(opts.url, { timeout });
+  const pattern = String(opts.url ?? "").trim();
+  if (!pattern) throw new Error("url is required");
+  const response = await page.waitForResponse(
+    (resp) => matchUrlPattern(pattern, resp.url()),
+    { timeout }
+  );
   let body = await response.text();
   let truncated = false;
-  const maxChars = typeof opts.maxChars === "number" && Number.isFinite(opts.maxChars) ? Math.max(1, Math.min(5e6, Math.floor(opts.maxChars))) : void 0;
-  if (maxChars !== void 0 && body.length > maxChars) {
+  const maxChars = typeof opts.maxChars === "number" && Number.isFinite(opts.maxChars) ? Math.max(1, Math.min(5e6, Math.floor(opts.maxChars))) : 2e5;
+  if (body.length > maxChars) {
     body = body.slice(0, maxChars);
     truncated = true;
   }
@@ -4148,6 +4479,22 @@ var CrawlPage = class {
       timeoutMs: opts?.timeoutMs
     });
   }
+  /**
+   * Execute multiple browser actions in sequence.
+   *
+   * @param actions - Array of actions to execute
+   * @param opts - Options (stopOnError: stop on first failure, default true)
+   * @returns Array of per-action results
+   */
+  async batch(actions, opts) {
+    return batchViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      actions,
+      stopOnError: opts?.stopOnError,
+      evaluateEnabled: opts?.evaluateEnabled
+    });
+  }
   // ── Keyboard ─────────────────────────────────────────────────
   /**
    * Press a keyboard key or key combination.
@@ -4875,22 +5222,36 @@ var BrowserClaw = class _BrowserClaw {
 };
 
 exports.BrowserClaw = BrowserClaw;
+exports.BrowserTabNotFoundError = BrowserTabNotFoundError;
 exports.CrawlPage = CrawlPage;
 exports.InvalidBrowserNavigationUrlError = InvalidBrowserNavigationUrlError;
 exports.assertBrowserNavigationAllowed = assertBrowserNavigationAllowed;
 exports.assertBrowserNavigationRedirectChainAllowed = assertBrowserNavigationRedirectChainAllowed;
 exports.assertBrowserNavigationResultAllowed = assertBrowserNavigationResultAllowed;
+exports.assertSafeUploadPaths = assertSafeUploadPaths;
+exports.batchViaPlaywright = batchViaPlaywright;
 exports.createPinnedLookup = createPinnedLookup;
 exports.ensureContextState = ensureContextState;
+exports.executeSingleAction = executeSingleAction;
 exports.forceDisconnectPlaywrightForTarget = forceDisconnectPlaywrightForTarget;
 exports.getChromeWebSocketUrl = getChromeWebSocketUrl;
+exports.getRestoredPageForTarget = getRestoredPageForTarget;
 exports.isChromeCdpReady = isChromeCdpReady;
 exports.isChromeReachable = isChromeReachable;
 exports.normalizeCdpHttpBaseForJsonEndpoints = normalizeCdpHttpBaseForJsonEndpoints;
+exports.parseRoleRef = parseRoleRef;
+exports.requireRef = requireRef;
+exports.requireRefOrSelector = requireRefOrSelector;
 exports.requiresInspectableBrowserNavigationRedirects = requiresInspectableBrowserNavigationRedirects;
+exports.resolveBoundedDelayMs = resolveBoundedDelayMs;
+exports.resolveInteractionTimeoutMs = resolveInteractionTimeoutMs;
+exports.resolvePageByTargetIdOrThrow = resolvePageByTargetIdOrThrow;
 exports.resolvePinnedHostnameWithPolicy = resolvePinnedHostnameWithPolicy;
+exports.resolveStrictExistingUploadPaths = resolveStrictExistingUploadPaths;
 exports.sanitizeUntrustedFileName = sanitizeUntrustedFileName;
 exports.withBrowserNavigationPolicy = withBrowserNavigationPolicy;
+exports.withPageScopedCdpClient = withPageScopedCdpClient;
+exports.withPlaywrightPageCdpSession = withPlaywrightPageCdpSession;
 exports.writeViaSiblingTempPath = writeViaSiblingTempPath;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map