browserclaw 0.7.1 → 0.8.1

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,6 +1297,16 @@ 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);
@@ -1912,6 +1927,43 @@ function ensurePageState(page) {
         rec.ok = false;
       }
     });
+    page.on("dialog", (dialog) => {
+      if (state.armIdDialog > 0) return;
+      if (state.dialogHandler) {
+        let handled = false;
+        const event = {
+          type: dialog.type(),
+          message: dialog.message(),
+          defaultValue: dialog.defaultValue(),
+          accept: (promptText) => {
+            handled = true;
+            return dialog.accept(promptText);
+          },
+          dismiss: () => {
+            handled = true;
+            return dialog.dismiss();
+          }
+        };
+        Promise.resolve(state.dialogHandler(event)).then(() => {
+          if (!handled) {
+            dialog.dismiss().catch((err) => {
+              console.warn(`[browserclaw] Failed to auto-dismiss dialog: ${err instanceof Error ? err.message : String(err)}`);
+            });
+          }
+        }).catch((err) => {
+          console.warn(`[browserclaw] onDialog handler error: ${err instanceof Error ? err.message : String(err)}`);
+          if (!handled) {
+            dialog.dismiss().catch((dismissErr) => {
+              console.warn(`[browserclaw] Failed to dismiss dialog after handler error: ${dismissErr instanceof Error ? dismissErr.message : String(dismissErr)}`);
+            });
+          }
+        });
+        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);
@@ -1919,6 +1971,11 @@ function ensurePageState(page) {
   }
   return state;
 }
+async function setDialogHandler(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  const state = ensurePageState(page);
+  state.dialogHandler = opts.handler;
+}
 function applyStealthToPage(page) {
   page.evaluate(STEALTH_SCRIPT).catch((e) => {
     if (process.env.DEBUG !== void 0 && process.env.DEBUG !== "")
@@ -2351,48 +2408,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();
@@ -2460,6 +2521,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);
@@ -2471,7 +2544,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);
@@ -2480,7 +2553,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;
   }
@@ -2685,6 +2758,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,
@@ -2859,6 +2934,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;
@@ -2939,6 +3056,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);
@@ -3102,9 +3248,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;
@@ -3132,9 +3279,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) {
@@ -3152,9 +3304,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 {
@@ -3188,6 +3341,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");
@@ -3240,7 +3404,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);
@@ -3317,10 +3481,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();
@@ -3592,7 +3756,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) {
@@ -4259,6 +4423,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);
@@ -4266,13 +4440,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);
@@ -4282,7 +4475,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;
@@ -4291,8 +4484,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 };
@@ -4653,6 +4858,111 @@ var CrawlPage = class {
       timeoutMs: opts?.timeoutMs
     });
   }
+  /**
+   * Click an element by CSS selector (no snapshot/ref needed).
+   *
+   * Finds and clicks atomically — no stale ref problem.
+   *
+   * @param selector - CSS selector (e.g. `'#submit-btn'`, `'.modal button'`)
+   * @param opts - Click options (double-click, button, modifiers)
+   *
+   * @example
+   * ```ts
+   * await page.clickBySelector('#submit-btn');
+   * await page.clickBySelector('.modal .close', { button: 'right' });
+   * ```
+   */
+  async clickBySelector(selector, opts) {
+    return clickViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      selector,
+      doubleClick: opts?.doubleClick,
+      button: opts?.button,
+      modifiers: opts?.modifiers,
+      delayMs: opts?.delayMs,
+      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.
    *
@@ -4817,6 +5127,48 @@ var CrawlPage = class {
       timeoutMs: opts.timeoutMs
     });
   }
+  /**
+   * Register a persistent dialog handler for all dialogs (alert, confirm, prompt, beforeunload).
+   *
+   * Unlike `armDialog()` which handles a single expected dialog, `onDialog()` handles
+   * every dialog that appears until cleared. This prevents unexpected dialogs from
+   * blocking the page.
+   *
+   * The handler receives a `DialogEvent` with `accept()` and `dismiss()` methods.
+   * If the handler throws or doesn't call either, the dialog is auto-dismissed.
+   *
+   * Pass `undefined` or `null` to clear the handler and restore default auto-dismiss.
+   *
+   * Note: `armDialog()` takes priority — if a one-shot handler is armed, it handles
+   * the next dialog instead of the persistent handler.
+   *
+   * @param handler - Callback for dialog events, or `undefined`/`null` to clear
+   *
+   * @example
+   * ```ts
+   * // Accept all confirm dialogs, dismiss everything else
+   * page.onDialog((event) => {
+   *   if (event.type === 'confirm') event.accept();
+   *   else event.dismiss();
+   * });
+   *
+   * // Log and auto-accept all dialogs
+   * page.onDialog(async (event) => {
+   *   console.log(`Dialog: ${event.type} — ${event.message}`);
+   *   await event.accept();
+   * });
+   *
+   * // Clear the handler (restore default auto-dismiss)
+   * page.onDialog(undefined);
+   * ```
+   */
+  async onDialog(handler) {
+    return setDialogHandler({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      handler: handler ?? void 0
+    });
+  }
   /**
    * Arm a one-shot file chooser handler.
    *
@@ -5484,15 +5836,69 @@ var CrawlPage = class {
       pollMs: opts?.pollMs
     });
   }
+  // ── Playwright Escape Hatches ─────────────────────────────────
+  /**
+   * Get the underlying Playwright `Page` object for this tab.
+   *
+   * Use this when browserclaw's API doesn't cover your use case and you need
+   * direct access to Playwright's full API (custom locator strategies,
+   * frame manipulation, request interception, etc.).
+   *
+   * **Warning:** Modifications made via the raw Playwright page may conflict
+   * with browserclaw's internal state (e.g. ref tracking). Use with care.
+   *
+   * @returns The Playwright `Page` instance
+   *
+   * @example
+   * ```ts
+   * const pwPage = await page.playwrightPage();
+   *
+   * // Use Playwright's full API directly
+   * await pwPage.locator('.my-component').waitFor({ state: 'visible' });
+   * await pwPage.route('**\/api/**', route => route.fulfill({ body: '{}' }));
+   *
+   * // Access frames
+   * const frame = pwPage.frameLocator('#my-iframe');
+   * ```
+   */
+  async playwrightPage() {
+    return getRestoredPageForTarget({ cdpUrl: this.cdpUrl, targetId: this.targetId });
+  }
+  /**
+   * Create a Playwright `Locator` for a CSS selector on this page.
+   *
+   * Convenience method that returns a Playwright locator without needing
+   * to first obtain the Page object. Useful for one-off Playwright operations.
+   *
+   * @param selector - CSS selector or Playwright selector string
+   * @returns A Playwright `Locator` instance
+   *
+   * @example
+   * ```ts
+   * const loc = await page.locator('.modal-dialog button.confirm');
+   * await loc.waitFor({ state: 'visible' });
+   * await loc.click();
+   *
+   * // Use Playwright selectors
+   * const input = await page.locator('input[name="email"]');
+   * await input.fill('test@example.com');
+   * ```
+   */
+  async locator(selector) {
+    const pwPage = await getRestoredPageForTarget({ cdpUrl: this.cdpUrl, targetId: this.targetId });
+    return pwPage.locator(selector);
+  }
 };
 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.
@@ -5521,7 +5927,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.
@@ -5538,12 +5944,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.
@@ -5558,7 +5974,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);
   }
   /**
@@ -5621,6 +6042,7 @@ var BrowserClaw = class _BrowserClaw {
    * Playwright connection is closed.
    */
   async stop() {
+    clearRecordingContext(this.cdpUrl);
     await disconnectBrowser();
     if (this.chrome) {
       await stopChrome(this.chrome);
@@ -5659,6 +6081,7 @@ exports.resolvePageByTargetIdOrThrow = resolvePageByTargetIdOrThrow;
 exports.resolvePinnedHostnameWithPolicy = resolvePinnedHostnameWithPolicy;
 exports.resolveStrictExistingUploadPaths = resolveStrictExistingUploadPaths;
 exports.sanitizeUntrustedFileName = sanitizeUntrustedFileName;
+exports.setDialogHandler = setDialogHandler;
 exports.waitForChallengeViaPlaywright = waitForChallengeViaPlaywright;
 exports.withBrowserNavigationPolicy = withBrowserNavigationPolicy;
 exports.withPageScopedCdpClient = withPageScopedCdpClient;