browserclaw 0.7.0 → 0.8.0

package/README.md

@@ -1,13 +1,15 @@
 <h2 align="center">🦞 BrowserClaw — Standalone OpenClaw browser module</h2>
 
 <p align="center">
-  <a href="https://browserclaw.agent"><img src="https://img.shields.io/badge/Live-browserclaw.agent-orange" alt="Live" /></a>
+  <a href="https://browserclaw.org"><img src="https://img.shields.io/badge/Live-browserclaw.org-orange" alt="Live" /></a>
   <a href="https://www.npmjs.com/package/browserclaw"><img src="https://img.shields.io/npm/v/browserclaw.svg" alt="npm version" /></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
   <a href="https://www.npmjs.com/package/browserclaw"><img src="https://img.shields.io/npm/dw/browserclaw" alt="npm downloads" /></a>
   <a href="https://github.com/idan-rubin/browserclaw/stargazers"><img src="https://img.shields.io/github/stars/idan-rubin/browserclaw" alt="GitHub stars" /></a>
 </p>
 
+> **DISCLAIMER: This project is NOT affiliated with browserclaw.com in any form. We have no connection to that site and recommend treating it with caution.**
+
 Extracted and refined from [OpenClaw](https://github.com/openclaw/openclaw)'s browser automation module. A standalone, typed library for AI-friendly browser control with **snapshot + ref targeting** — no CSS selectors, no XPath, no vision, just numbered refs that map to interactive elements.
 
 ```typescript

package/dist/index.cjs

@@ -1198,8 +1198,13 @@ function isWebSocketUrl(url) {
 function isLoopbackHost(hostname) {
   return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
 }
-function hasProxyEnvConfigured() {
-  return (process.env.HTTP_PROXY ?? process.env.HTTPS_PROXY ?? process.env.http_proxy ?? process.env.https_proxy ?? "") !== "";
+var PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
+function hasProxyEnvConfigured(env = process.env) {
+  for (const key of PROXY_ENV_KEYS) {
+    const value = env[key];
+    if (typeof value === "string" && value.trim().length > 0) return true;
+  }
+  return false;
 }
 function normalizeCdpWsUrl(wsUrl, cdpUrl) {
   const ws = new URL(wsUrl);
@@ -1292,23 +1297,20 @@ async function fetchChromeVersion(cdpUrl, timeoutMs = 500, authToken) {
     clearTimeout(t);
   }
 }
+var COMMON_CDP_PORTS = [9222, 9223, 9224, 9225, 9226, 9229];
+async function discoverChromeCdpUrl(timeoutMs = 500) {
+  const results = await Promise.all(
+    COMMON_CDP_PORTS.map(async (port) => {
+      const url = `http://127.0.0.1:${String(port)}`;
+      return await isChromeReachable(url, timeoutMs) ? url : null;
+    })
+  );
+  return results.find((url) => url !== null) ?? null;
+}
 async function isChromeReachable(cdpUrl, timeoutMs = 500, authToken) {
   if (isWebSocketUrl(cdpUrl)) return await canOpenWebSocket(cdpUrl, timeoutMs);
   const version = await fetchChromeVersion(cdpUrl, timeoutMs, authToken);
-  if (version !== null) return true;
-  let isLoopback = false;
-  try {
-    const u = new URL(cdpUrl.startsWith("http") ? cdpUrl : `http://${cdpUrl}`);
-    isLoopback = isLoopbackHost(u.hostname);
-  } catch {
-  }
-  if (!isLoopback) return false;
-  for (let i = 0; i < 2; i++) {
-    await new Promise((r) => setTimeout(r, 150));
-    const retry = await fetchChromeVersion(cdpUrl, timeoutMs, authToken);
-    if (retry !== null) return true;
-  }
-  return false;
+  return version !== null;
 }
 async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500, authToken) {
   if (isWebSocketUrl(cdpUrl)) return cdpUrl;
@@ -1925,6 +1927,12 @@ function ensurePageState(page) {
         rec.ok = false;
       }
     });
+    page.on("dialog", (dialog) => {
+      if (state.armIdDialog > 0) return;
+      dialog.dismiss().catch((err) => {
+        console.warn(`[browserclaw] Failed to dismiss dialog: ${err instanceof Error ? err.message : String(err)}`);
+      });
+    });
     page.on("close", () => {
       pageStates.delete(page);
       observedPages.delete(page);
@@ -2053,6 +2061,8 @@ async function disconnectBrowser() {
     }
   }
   for (const cur of cachedByCdpUrl.values()) {
+    if (cur.onDisconnected && typeof cur.browser.off === "function")
+      cur.browser.off("disconnected", cur.onDisconnected);
     await cur.browser.close().catch(() => {
     });
   }
@@ -2362,48 +2372,52 @@ async function awaitEvalWithAbort(evalPromise, abortPromise) {
 }
 var BROWSER_EVALUATOR = new Function(
   "args",
-  `
-  "use strict";
-  var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
-  try {
-    var candidate = eval("(" + fnBody + ")");
-    var result = typeof candidate === "function" ? candidate() : candidate;
-    if (result && typeof result.then === "function") {
-      return Promise.race([
-        result,
-        new Promise(function(_, reject) {
-          setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
-        })
-      ]);
-    }
-    return result;
-  } catch (err) {
-    throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
-  }
-`
+  [
+    '"use strict";',
+    "var fnBody = args.fnBody, timeoutMs = args.timeoutMs;",
+    "try {",
+    "  var candidate;",
+    '  try { candidate = eval("(" + fnBody + ")"); }',
+    "  catch (_) { candidate = (0, eval)(fnBody); }",
+    '  var result = typeof candidate === "function" ? candidate() : candidate;',
+    '  if (result && typeof result.then === "function") {',
+    "    return Promise.race([",
+    "      result,",
+    "      new Promise(function(_, reject) {",
+    '        setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);',
+    "      })",
+    "    ]);",
+    "  }",
+    "  return result;",
+    "} catch (err) {",
+    '  throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));',
+    "}"
+  ].join("\n")
 );
 var ELEMENT_EVALUATOR = new Function(
   "el",
   "args",
-  `
-  "use strict";
-  var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
-  try {
-    var candidate = eval("(" + fnBody + ")");
-    var result = typeof candidate === "function" ? candidate(el) : candidate;
-    if (result && typeof result.then === "function") {
-      return Promise.race([
-        result,
-        new Promise(function(_, reject) {
-          setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
-        })
-      ]);
-    }
-    return result;
-  } catch (err) {
-    throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
-  }
-`
+  [
+    '"use strict";',
+    "var fnBody = args.fnBody, timeoutMs = args.timeoutMs;",
+    "try {",
+    "  var candidate;",
+    '  try { candidate = eval("(" + fnBody + ")"); }',
+    "  catch (_) { candidate = (0, eval)(fnBody); }",
+    '  var result = typeof candidate === "function" ? candidate(el) : candidate;',
+    '  if (result && typeof result.then === "function") {',
+    "    return Promise.race([",
+    "      result,",
+    "      new Promise(function(_, reject) {",
+    '        setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);',
+    "      })",
+    "    ]);",
+    "  }",
+    "  return result;",
+    "} catch (err) {",
+    '  throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));',
+    "}"
+  ].join("\n")
 );
 async function evaluateViaPlaywright(opts) {
   const fnText = opts.fn.trim();
@@ -2471,6 +2485,18 @@ async function evaluateViaPlaywright(opts) {
 
 // src/security.ts
 var ipaddr = __toESM(require_ipaddr());
+function resolveDefaultBrowserTmpDir() {
+  try {
+    if (process.platform === "linux" || process.platform === "darwin") {
+      return "/tmp/browserclaw";
+    }
+  } catch {
+  }
+  return path.join(os.tmpdir(), "browserclaw");
+}
+var DEFAULT_BROWSER_TMP_DIR = resolveDefaultBrowserTmpDir();
+path.join(DEFAULT_BROWSER_TMP_DIR, "downloads");
+var DEFAULT_UPLOAD_DIR = path.join(DEFAULT_BROWSER_TMP_DIR, "uploads");
 var InvalidBrowserNavigationUrlError = class extends Error {
   constructor(message) {
     super(message);
@@ -2482,7 +2508,7 @@ function withBrowserNavigationPolicy(ssrfPolicy) {
 }
 var NETWORK_NAVIGATION_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
 var SAFE_NON_NETWORK_URLS = /* @__PURE__ */ new Set(["about:blank"]);
-var PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
+var PROXY_ENV_KEYS2 = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
 var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "localhost.localdomain", "metadata.google.internal"]);
 function isAllowedNonNetworkNavigationUrl(parsed) {
   return SAFE_NON_NETWORK_URLS.has(parsed.href);
@@ -2491,7 +2517,7 @@ function isPrivateNetworkAllowedByPolicy(policy) {
   return policy?.dangerouslyAllowPrivateNetwork === true || policy?.allowPrivateNetwork === true;
 }
 function hasProxyEnvConfigured2(env = process.env) {
-  for (const key of PROXY_ENV_KEYS) {
+  for (const key of PROXY_ENV_KEYS2) {
     const value = env[key];
     if (typeof value === "string" && value.trim().length > 0) return true;
   }
@@ -2696,6 +2722,8 @@ function dedupeAndPreferIpv4(results) {
 }
 function createPinnedLookup(params) {
   const normalizedHost = normalizeHostname(params.hostname);
+  if (params.addresses.length === 0)
+    throw new Error(`Pinned lookup requires at least one address for ${params.hostname}`);
   const fallback = params.fallback ?? dns.lookup;
   const records = params.addresses.map((address) => ({
     address,
@@ -2870,6 +2898,48 @@ async function resolveStrictExistingUploadPaths(params) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }
 }
+function resolvePathWithinRoot(params) {
+  const root = path.resolve(params.rootDir);
+  const raw = params.requestedPath.trim();
+  const effectivePath = raw === "" && params.defaultFileName != null && params.defaultFileName !== "" ? params.defaultFileName : raw;
+  if (effectivePath === "") return { ok: false, error: `Empty path is not allowed (${params.scopeLabel}).` };
+  const resolved = path.resolve(root, effectivePath);
+  const rel = path.relative(root, resolved);
+  if (!rel || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    return { ok: false, error: `Path escapes ${params.scopeLabel}: "${params.requestedPath}".` };
+  }
+  return { ok: true, path: resolved };
+}
+async function resolveStrictExistingPathsWithinRoot(params) {
+  const root = path.resolve(params.rootDir);
+  const resolved = [];
+  for (const raw of params.requestedPaths) {
+    const lexical = resolvePathWithinRoot({ rootDir: root, requestedPath: raw, scopeLabel: params.scopeLabel });
+    if (!lexical.ok) return lexical;
+    let real;
+    try {
+      real = await promises$1.realpath(lexical.path);
+    } catch (e) {
+      if (e.code === "ENOENT") {
+        return { ok: false, error: `Path does not exist (${params.scopeLabel}): "${raw}".` };
+      }
+      return { ok: false, error: `Cannot resolve "${raw}" (${params.scopeLabel}): ${e.message}` };
+    }
+    const rel = path.relative(root, real);
+    if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+      return { ok: false, error: `Path escapes ${params.scopeLabel} via symlink: "${raw}".` };
+    }
+    const stat = await promises$1.lstat(real);
+    if (stat.isSymbolicLink()) {
+      return { ok: false, error: `Path is a symbolic link (${params.scopeLabel}): "${raw}".` };
+    }
+    if (!stat.isFile()) {
+      return { ok: false, error: `Path is not a regular file (${params.scopeLabel}): "${raw}".` };
+    }
+    resolved.push(real);
+  }
+  return { ok: true, paths: resolved };
+}
 function sanitizeUntrustedFileName(fileName, fallbackName) {
   const trimmed = fileName.trim();
   if (trimmed === "") return fallbackName;
@@ -2950,6 +3020,35 @@ function resolveLocator(page, resolved) {
   const sel = resolved.selector ?? "";
   return page.locator(sel);
 }
+async function mouseClickViaPlaywright(opts) {
+  const page = await getRestoredPageForTarget(opts);
+  await page.mouse.click(opts.x, opts.y, {
+    button: opts.button,
+    clickCount: opts.clickCount,
+    delay: opts.delayMs
+  });
+}
+async function clickByTextViaPlaywright(opts) {
+  const page = await getRestoredPageForTarget(opts);
+  const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
+  try {
+    await page.getByText(opts.text, { exact: opts.exact }).click({ timeout, button: opts.button, modifiers: opts.modifiers });
+  } catch (err) {
+    throw toAIFriendlyError(err, `text="${opts.text}"`);
+  }
+}
+async function clickByRoleViaPlaywright(opts) {
+  const page = await getRestoredPageForTarget(opts);
+  const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
+  try {
+    await page.getByRole(opts.role, { name: opts.name }).click({ timeout, button: opts.button, modifiers: opts.modifiers });
+  } catch (err) {
+    throw toAIFriendlyError(
+      err,
+      `role=${opts.role}${opts.name !== void 0 && opts.name !== "" ? ` name="${opts.name}"` : ""}`
+    );
+  }
+}
 async function clickViaPlaywright(opts) {
   const resolved = requireRefOrSelector(opts.ref, opts.selector);
   const page = await getRestoredPageForTarget(opts);
@@ -3113,9 +3212,10 @@ 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();
-  const uploadPathsResult = await resolveStrictExistingUploadPaths({
+  const uploadPathsResult = await resolveStrictExistingPathsWithinRoot({
+    rootDir: DEFAULT_UPLOAD_DIR,
     requestedPaths: opts.paths,
-    scopeLabel: "uploads directory"
+    scopeLabel: `uploads directory (${DEFAULT_UPLOAD_DIR})`
   });
   if (!uploadPathsResult.ok) throw new Error(uploadPathsResult.error);
   const resolvedPaths = uploadPathsResult.paths;
@@ -3143,9 +3243,14 @@ async function armDialogViaPlaywright(opts) {
   const armId = state.armIdDialog;
   page.waitForEvent("dialog", { timeout }).then(async (dialog) => {
     if (state.armIdDialog !== armId) return;
-    if (opts.accept) await dialog.accept(opts.promptText);
-    else await dialog.dismiss();
+    try {
+      if (opts.accept) await dialog.accept(opts.promptText);
+      else await dialog.dismiss();
+    } finally {
+      if (state.armIdDialog === armId) state.armIdDialog = 0;
+    }
   }).catch(() => {
+    if (state.armIdDialog === armId) state.armIdDialog = 0;
   });
 }
 async function armFileUploadViaPlaywright(opts) {
@@ -3163,9 +3268,10 @@ async function armFileUploadViaPlaywright(opts) {
       }
       return;
     }
-    const uploadPathsResult = await resolveStrictExistingUploadPaths({
+    const uploadPathsResult = await resolveStrictExistingPathsWithinRoot({
+      rootDir: DEFAULT_UPLOAD_DIR,
       requestedPaths: opts.paths,
-      scopeLabel: "uploads directory"
+      scopeLabel: `uploads directory (${DEFAULT_UPLOAD_DIR})`
     });
     if (!uploadPathsResult.ok) {
       try {
@@ -3199,6 +3305,17 @@ async function pressKeyViaPlaywright(opts) {
 }
 
 // src/actions/navigation.ts
+var recordingContexts = /* @__PURE__ */ new Map();
+function clearRecordingContext(cdpUrl) {
+  recordingContexts.delete(cdpUrl);
+}
+async function createRecordingContext(browser, cdpUrl, recordVideo) {
+  const context = await browser.newContext({ recordVideo });
+  observeContext(context);
+  recordingContexts.set(cdpUrl, context);
+  context.on("close", () => recordingContexts.delete(cdpUrl));
+  return context;
+}
 function isRetryableNavigateError(err) {
   const msg = typeof err === "string" ? err.toLowerCase() : err instanceof Error ? err.message.toLowerCase() : "";
   return msg.includes("frame has been detached") || msg.includes("target page, context or browser has been closed");
@@ -3251,7 +3368,7 @@ async function listPagesViaPlaywright(opts) {
 }
 async function createPageViaPlaywright(opts) {
   const { browser } = await connectBrowser(opts.cdpUrl);
-  const context = browser.contexts()[0] ?? await browser.newContext();
+  const context = opts.recordVideo ? recordingContexts.get(opts.cdpUrl) ?? await createRecordingContext(browser, opts.cdpUrl, opts.recordVideo) : browser.contexts()[0] ?? await browser.newContext();
   ensureContextState(context);
   const page = await context.newPage();
   ensurePageState(page);
@@ -3328,10 +3445,10 @@ async function waitForViaPlaywright(opts) {
     await page.waitForTimeout(resolveBoundedDelayMs2(opts.timeMs, "wait timeMs", MAX_WAIT_TIME_MS));
   }
   if (opts.text !== void 0 && opts.text !== "") {
-    await page.getByText(opts.text).first().waitFor({ state: "visible", timeout });
+    await page.waitForFunction((text) => (document.body?.innerText ?? "").includes(text), opts.text, { timeout });
   }
   if (opts.textGone !== void 0 && opts.textGone !== "") {
-    await page.getByText(opts.textGone).first().waitFor({ state: "hidden", timeout });
+    await page.waitForFunction((text) => !(document.body?.innerText ?? "").includes(text), opts.textGone, { timeout });
   }
   if (opts.selector !== void 0 && opts.selector !== "") {
     const selector = opts.selector.trim();
@@ -3603,7 +3720,7 @@ async function waitForDownloadViaPlaywright(opts) {
   try {
     const download = await waiter.promise;
     if (state.armIdDownload !== armId) throw new Error("Download was superseded by another waiter");
-    const savePath = opts.path ?? download.suggestedFilename();
+    const savePath = opts.path ?? sanitizeUntrustedFileName(download.suggestedFilename() || "download.bin", "download.bin");
     await assertSafeOutputPath(savePath, opts.allowedOutputRoots);
     return await saveDownloadPayload(download, savePath);
   } catch (err) {
@@ -4270,6 +4387,16 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
     return match ? match[1] : null;
   }
   if (options.interactive === true) {
+    let interactiveMaxRef = 0;
+    for (const line of lines) {
+      const refMatch = /\[ref=e(\d+)\]/.exec(line);
+      if (refMatch) interactiveMaxRef = Math.max(interactiveMaxRef, Number.parseInt(refMatch[1], 10));
+    }
+    let interactiveCounter = interactiveMaxRef;
+    const nextInteractiveRef = () => {
+      interactiveCounter++;
+      return `e${String(interactiveCounter)}`;
+    };
     const out2 = [];
     for (const line of lines) {
       const parsed = matchInteractiveSnapshotLine(line, options);
@@ -4277,13 +4404,32 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
       const { roleRaw, role, name, suffix } = parsed;
       if (!INTERACTIVE_ROLES.has(role)) continue;
       const ref = parseAiSnapshotRef(suffix);
-      if (ref === null) continue;
       const prefix = /^(\s*-\s*)/.exec(line)?.[1] ?? "";
-      refs[ref] = { role, ...name !== void 0 && name !== "" ? { name } : {} };
-      out2.push(`${prefix}${roleRaw}${name !== void 0 && name !== "" ? ` "${name}"` : ""}${suffix}`);
+      if (ref !== null) {
+        refs[ref] = { role, ...name !== void 0 && name !== "" ? { name } : {} };
+        out2.push(`${prefix}${roleRaw}${name !== void 0 && name !== "" ? ` "${name}"` : ""}${suffix}`);
+      } else {
+        const generatedRef = nextInteractiveRef();
+        refs[generatedRef] = { role, ...name !== void 0 && name !== "" ? { name } : {} };
+        let enhanced = `${prefix}${roleRaw}`;
+        if (name !== void 0 && name !== "") enhanced += ` "${name}"`;
+        enhanced += ` [ref=${generatedRef}]`;
+        if (suffix.trim() !== "") enhanced += suffix;
+        out2.push(enhanced);
+      }
     }
     return { snapshot: out2.join("\n") || "(no interactive elements)", refs };
   }
+  let maxRef = 0;
+  for (const line of lines) {
+    const refMatch = /\[ref=e(\d+)\]/.exec(line);
+    if (refMatch) maxRef = Math.max(maxRef, Number.parseInt(refMatch[1], 10));
+  }
+  let generatedCounter = maxRef;
+  const nextGeneratedRef = () => {
+    generatedCounter++;
+    return `e${String(generatedCounter)}`;
+  };
   const out = [];
   for (const line of lines) {
     const depth = getIndentLevel(line);
@@ -4293,7 +4439,7 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
       out.push(line);
       continue;
     }
-    const [, , roleRaw, name, suffix] = match;
+    const [, prefix, roleRaw, name, suffix] = match;
     if (roleRaw.startsWith("/")) {
       out.push(line);
       continue;
@@ -4302,8 +4448,20 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
     const isStructural = STRUCTURAL_ROLES.has(role);
     if (options.compact === true && isStructural && name === "") continue;
     const ref = parseAiSnapshotRef(suffix);
-    if (ref !== null) refs[ref] = { role, ...name !== "" ? { name } : {} };
-    out.push(line);
+    if (ref !== null) {
+      refs[ref] = { role, ...name !== "" ? { name } : {} };
+      out.push(line);
+    } else if (INTERACTIVE_ROLES.has(role)) {
+      const generatedRef = nextGeneratedRef();
+      refs[generatedRef] = { role, ...name !== "" ? { name } : {} };
+      let enhanced = `${prefix}${roleRaw}`;
+      if (name !== "") enhanced += ` "${name}"`;
+      enhanced += ` [ref=${generatedRef}]`;
+      if (suffix.trim() !== "") enhanced += suffix;
+      out.push(enhanced);
+    } else {
+      out.push(line);
+    }
   }
   const tree = out.join("\n") || "(empty)";
   return { snapshot: options.compact === true ? compactTree(tree) : tree, refs };
@@ -4664,6 +4822,85 @@ var CrawlPage = class {
       timeoutMs: opts?.timeoutMs
     });
   }
+  /**
+   * Click at specific page coordinates.
+   *
+   * Useful for canvas elements, custom widgets, or elements without ARIA roles.
+   *
+   * @param x - X coordinate in pixels
+   * @param y - Y coordinate in pixels
+   * @param opts - Click options (button, clickCount, delayMs)
+   *
+   * @example
+   * ```ts
+   * await page.mouseClick(100, 200);
+   * await page.mouseClick(100, 200, { button: 'right' });
+   * await page.mouseClick(100, 200, { clickCount: 2 }); // double-click
+   * ```
+   */
+  async mouseClick(x, y, opts) {
+    return mouseClickViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      x,
+      y,
+      button: opts?.button,
+      clickCount: opts?.clickCount,
+      delayMs: opts?.delayMs
+    });
+  }
+  /**
+   * Click an element by its visible text content (no snapshot/ref needed).
+   *
+   * Finds and clicks atomically — no stale ref problem.
+   *
+   * @param text - Text content to match
+   * @param opts - Options (exact: require full match, button, modifiers)
+   *
+   * @example
+   * ```ts
+   * await page.clickByText('Submit');
+   * await page.clickByText('Save Changes', { exact: true });
+   * ```
+   */
+  async clickByText(text, opts) {
+    return clickByTextViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      text,
+      exact: opts?.exact,
+      button: opts?.button,
+      modifiers: opts?.modifiers,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
+  /**
+   * Click an element by its ARIA role and accessible name (no snapshot/ref needed).
+   *
+   * Finds and clicks atomically — no stale ref problem.
+   *
+   * @param role - ARIA role (e.g. `'button'`, `'link'`, `'menuitem'`)
+   * @param name - Accessible name to match (optional)
+   * @param opts - Click options
+   *
+   * @example
+   * ```ts
+   * await page.clickByRole('button', 'Save');
+   * await page.clickByRole('link', 'Settings');
+   * await page.clickByRole('menuitem', 'Delete');
+   * ```
+   */
+  async clickByRole(role, name, opts) {
+    return clickByRoleViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      role,
+      name,
+      button: opts?.button,
+      modifiers: opts?.modifiers,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
   /**
    * Type text into an input element by ref.
    *
@@ -5499,11 +5736,13 @@ var CrawlPage = class {
 var BrowserClaw = class _BrowserClaw {
   cdpUrl;
   ssrfPolicy;
+  recordVideo;
   chrome;
-  constructor(cdpUrl, chrome, ssrfPolicy) {
+  constructor(cdpUrl, chrome, ssrfPolicy, recordVideo) {
     this.cdpUrl = cdpUrl;
     this.chrome = chrome;
     this.ssrfPolicy = ssrfPolicy;
+    this.recordVideo = recordVideo;
   }
   /**
    * Launch a new Chrome instance and connect to it.
@@ -5532,7 +5771,7 @@ var BrowserClaw = class _BrowserClaw {
     const chrome = await launchChrome(opts);
     const cdpUrl = `http://127.0.0.1:${String(chrome.cdpPort)}`;
     const ssrfPolicy = opts.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
-    return new _BrowserClaw(cdpUrl, chrome, ssrfPolicy);
+    return new _BrowserClaw(cdpUrl, chrome, ssrfPolicy, opts.recordVideo);
   }
   /**
    * Connect to an already-running Chrome instance via its CDP endpoint.
@@ -5549,12 +5788,22 @@ var BrowserClaw = class _BrowserClaw {
    * ```
    */
   static async connect(cdpUrl, opts) {
-    if (!await isChromeReachable(cdpUrl, 3e3, opts?.authToken)) {
-      throw new Error(`Cannot connect to Chrome at ${cdpUrl}. Is Chrome running with --remote-debugging-port?`);
+    let resolvedUrl = cdpUrl;
+    if (resolvedUrl === void 0 || resolvedUrl === "") {
+      const discovered = await discoverChromeCdpUrl();
+      if (discovered === null) {
+        throw new Error(
+          "No Chrome instance found on common CDP ports (9222-9226, 9229). Start Chrome with --remote-debugging-port=9222, or pass a CDP URL."
+        );
+      }
+      resolvedUrl = discovered;
+    }
+    if (!await isChromeReachable(resolvedUrl, 3e3, opts?.authToken)) {
+      throw new Error(`Cannot connect to Chrome at ${resolvedUrl}. Is Chrome running with --remote-debugging-port?`);
     }
-    await connectBrowser(cdpUrl, opts?.authToken);
+    await connectBrowser(resolvedUrl, opts?.authToken);
     const ssrfPolicy = opts?.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts?.ssrfPolicy;
-    return new _BrowserClaw(cdpUrl, null, ssrfPolicy);
+    return new _BrowserClaw(resolvedUrl, null, ssrfPolicy, opts?.recordVideo);
   }
   /**
    * Open a URL in a new tab and return the page handle.
@@ -5569,7 +5818,12 @@ var BrowserClaw = class _BrowserClaw {
    * ```
    */
   async open(url) {
-    const tab = await createPageViaPlaywright({ cdpUrl: this.cdpUrl, url, ssrfPolicy: this.ssrfPolicy });
+    const tab = await createPageViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      url,
+      ssrfPolicy: this.ssrfPolicy,
+      recordVideo: this.recordVideo
+    });
     return new CrawlPage(this.cdpUrl, tab.targetId, this.ssrfPolicy);
   }
   /**
@@ -5632,6 +5886,7 @@ var BrowserClaw = class _BrowserClaw {
    * Playwright connection is closed.
    */
   async stop() {
+    clearRecordingContext(this.cdpUrl);
     await disconnectBrowser();
     if (this.chrome) {
       await stopChrome(this.chrome);