browserclaw 0.8.0 → 0.8.1

package/dist/index.cjs

@@ -1929,6 +1929,37 @@ 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)}`);
       });
@@ -1940,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 !== "")
@@ -4822,6 +4858,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.
    *
@@ -5065,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.
    *
@@ -5732,6 +5836,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;
@@ -5925,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;