browserclaw 0.8.0 → 0.8.2

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BrowserContext, Page, CDPSession } from 'playwright-core';
+import { BrowserContext, Page, Locator, CDPSession } from 'playwright-core';
 import { lookup } from 'node:dns';
 import { lookup as lookup$1 } from 'node:dns/promises';
 
@@ -517,6 +517,21 @@ interface DialogOptions {
     /** Timeout for waiting for the dialog. Default: `30000` */
     timeoutMs?: number;
 }
+/** Information about a dialog event passed to `onDialog` handlers. */
+interface DialogEvent {
+    /** Dialog type: `'alert'`, `'confirm'`, `'prompt'`, or `'beforeunload'` */
+    type: string;
+    /** The message displayed in the dialog */
+    message: string;
+    /** The default prompt value (for prompt dialogs) */
+    defaultValue: string;
+    /** Accept the dialog (optionally with prompt text) */
+    accept: (promptText?: string) => Promise<void>;
+    /** Dismiss the dialog */
+    dismiss: () => Promise<void>;
+}
+/** Callback for persistent dialog handling. */
+type DialogHandler = (event: DialogEvent) => void | Promise<void>;
 /** Result of intercepting a response body. */
 interface ResponseBodyResult {
     /** The response URL */
@@ -666,6 +681,21 @@ declare class CrawlPage {
      * ```
      */
     click(ref: string, opts?: ClickOptions): Promise<void>;
+    /**
+     * 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' });
+     * ```
+     */
+    clickBySelector(selector: string, opts?: ClickOptions): Promise<void>;
     /**
      * Click at specific page coordinates.
      *
@@ -832,6 +862,42 @@ declare class CrawlPage {
      * ```
      */
     armDialog(opts: DialogOptions): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
+    onDialog(handler: DialogHandler | undefined | null): Promise<void>;
     /**
      * Arm a one-shot file chooser handler.
      *
@@ -1302,6 +1368,52 @@ declare class CrawlPage {
         timeoutMs?: number;
         pollMs?: number;
     }): Promise<ChallengeWaitResult>;
+    /**
+     * 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');
+     * ```
+     */
+    playwrightPage(): Promise<Page>;
+    /**
+     * 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');
+     * ```
+     */
+    locator(selector: string): Promise<Locator>;
 }
 /**
  * Main entry point for browserclaw.
@@ -1548,6 +1660,16 @@ declare function withPageScopedCdpClient<T>(opts: {
     fn: (send: (method: string, params?: Record<string, unknown>) => Promise<unknown>) => Promise<T>;
 }): Promise<T>;
 declare function ensureContextState(context: BrowserContext): ContextState;
+/**
+ * Set or clear a persistent dialog handler for a page.
+ * When set, this handler is called for every dialog that is not covered by armDialog().
+ * Pass `undefined` to clear the handler and restore default auto-dismiss.
+ */
+declare function setDialogHandler(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    handler?: DialogHandler;
+}): Promise<void>;
 /**
  * Force-disconnect a Playwright browser connection for a given CDP target.
  * Clears the connection cache, sends Runtime.terminateExecution via raw CDP
@@ -1633,4 +1755,4 @@ declare function waitForChallengeViaPlaywright(opts: {
     pollMs?: number;
 }): Promise<ChallengeWaitResult>;
 
-export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
+export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogEvent, type DialogHandler, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BrowserContext, Page, CDPSession } from 'playwright-core';
+import { BrowserContext, Page, Locator, CDPSession } from 'playwright-core';
 import { lookup } from 'node:dns';
 import { lookup as lookup$1 } from 'node:dns/promises';
 
@@ -517,6 +517,21 @@ interface DialogOptions {
     /** Timeout for waiting for the dialog. Default: `30000` */
     timeoutMs?: number;
 }
+/** Information about a dialog event passed to `onDialog` handlers. */
+interface DialogEvent {
+    /** Dialog type: `'alert'`, `'confirm'`, `'prompt'`, or `'beforeunload'` */
+    type: string;
+    /** The message displayed in the dialog */
+    message: string;
+    /** The default prompt value (for prompt dialogs) */
+    defaultValue: string;
+    /** Accept the dialog (optionally with prompt text) */
+    accept: (promptText?: string) => Promise<void>;
+    /** Dismiss the dialog */
+    dismiss: () => Promise<void>;
+}
+/** Callback for persistent dialog handling. */
+type DialogHandler = (event: DialogEvent) => void | Promise<void>;
 /** Result of intercepting a response body. */
 interface ResponseBodyResult {
     /** The response URL */
@@ -666,6 +681,21 @@ declare class CrawlPage {
      * ```
      */
     click(ref: string, opts?: ClickOptions): Promise<void>;
+    /**
+     * 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' });
+     * ```
+     */
+    clickBySelector(selector: string, opts?: ClickOptions): Promise<void>;
     /**
      * Click at specific page coordinates.
      *
@@ -832,6 +862,42 @@ declare class CrawlPage {
      * ```
      */
     armDialog(opts: DialogOptions): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
+    onDialog(handler: DialogHandler | undefined | null): Promise<void>;
     /**
      * Arm a one-shot file chooser handler.
      *
@@ -1302,6 +1368,52 @@ declare class CrawlPage {
         timeoutMs?: number;
         pollMs?: number;
     }): Promise<ChallengeWaitResult>;
+    /**
+     * 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');
+     * ```
+     */
+    playwrightPage(): Promise<Page>;
+    /**
+     * 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');
+     * ```
+     */
+    locator(selector: string): Promise<Locator>;
 }
 /**
  * Main entry point for browserclaw.
@@ -1548,6 +1660,16 @@ declare function withPageScopedCdpClient<T>(opts: {
     fn: (send: (method: string, params?: Record<string, unknown>) => Promise<unknown>) => Promise<T>;
 }): Promise<T>;
 declare function ensureContextState(context: BrowserContext): ContextState;
+/**
+ * Set or clear a persistent dialog handler for a page.
+ * When set, this handler is called for every dialog that is not covered by armDialog().
+ * Pass `undefined` to clear the handler and restore default auto-dismiss.
+ */
+declare function setDialogHandler(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    handler?: DialogHandler;
+}): Promise<void>;
 /**
  * Force-disconnect a Playwright browser connection for a given CDP target.
  * Clears the connection cache, sends Runtime.terminateExecution via raw CDP
@@ -1633,4 +1755,4 @@ declare function waitForChallengeViaPlaywright(opts: {
     pollMs?: number;
 }): Promise<ChallengeWaitResult>;
 
-export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
+export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogEvent, type DialogHandler, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };

package/dist/index.js

@@ -1918,6 +1918,41 @@ function ensurePageState(page) {
     });
     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)}`);
       });
@@ -1929,6 +1964,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 !== "")
@@ -2532,7 +2572,17 @@ var BLOCKED_IPV4_RANGES = /* @__PURE__ */ new Set([
   "private",
   "reserved"
 ]);
-var BLOCKED_IPV6_RANGES = /* @__PURE__ */ new Set(["unspecified", "loopback", "linkLocal", "uniqueLocal", "multicast"]);
+var BLOCKED_IPV6_RANGES = /* @__PURE__ */ new Set([
+  "unspecified",
+  "loopback",
+  "linkLocal",
+  "uniqueLocal",
+  "multicast",
+  "reserved",
+  "benchmarking",
+  "discard",
+  "orchid2"
+]);
 var RFC2544_BENCHMARK_PREFIX = [ipaddr.IPv4.parse("198.18.0.0"), 15];
 var EMBEDDED_IPV4_SENTINEL_RULES = [
   // IPv4-compatible (::a.b.c.d)
@@ -4196,6 +4246,7 @@ var CONTENT_ROLES = /* @__PURE__ */ new Set([
 var STRUCTURAL_ROLES = /* @__PURE__ */ new Set([
   "generic",
   "group",
+  "ignored",
   "list",
   "table",
   "row",
@@ -4811,6 +4862,32 @@ 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.
    *
@@ -5054,6 +5131,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.
    *
@@ -5721,6 +5840,58 @@ 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;
@@ -5884,6 +6055,6 @@ var BrowserClaw = class _BrowserClaw {
   }
 };
 
-export { BrowserClaw, BrowserTabNotFoundError, CrawlPage, InvalidBrowserNavigationUrlError, STEALTH_SCRIPT, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
+export { BrowserClaw, BrowserTabNotFoundError, CrawlPage, InvalidBrowserNavigationUrlError, STEALTH_SCRIPT, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map