browserclaw 0.10.0 → 0.10.2

package/dist/index.d.cts

@@ -77,6 +77,7 @@ type BatchAction = {
     url?: string;
     loadState?: 'load' | 'domcontentloaded' | 'networkidle';
     fn?: string;
+    arg?: unknown;
     targetId?: string;
     timeoutMs?: number;
 } | {
@@ -411,7 +412,9 @@ interface WaitOptions {
     /** Wait for a specific page load state */
     loadState?: 'load' | 'domcontentloaded' | 'networkidle';
     /** Wait until a JavaScript function returns truthy (evaluated in browser context). Accepts a string or a serializable function. */
-    fn?: string | (() => unknown);
+    fn?: string | ((arg?: unknown) => unknown);
+    /** Serializable argument passed to `fn` in the browser context. Use an array or object to pass multiple values. */
+    arg?: unknown;
     /** Timeout for each condition in milliseconds. Default: `20000` */
     timeoutMs?: number;
 }
@@ -540,6 +543,23 @@ interface DialogEvent {
 }
 /** Callback for persistent dialog handling. */
 type DialogHandler = (event: DialogEvent) => void | Promise<void>;
+/** Result of waiting for a network request to complete. */
+interface RequestResult {
+    /** The final request URL */
+    url: string;
+    /** HTTP method (e.g. `'GET'`, `'POST'`) */
+    method: string;
+    /** Request body (for POST/PUT/PATCH requests) */
+    postData?: string;
+    /** HTTP response status code */
+    status: number;
+    /** Whether the response status was 2xx */
+    ok: boolean;
+    /** Response body text */
+    responseBody?: string;
+    /** Whether the response body was truncated due to maxChars */
+    truncated?: boolean;
+}
 /** Result of intercepting a response body. */
 interface ResponseBodyResult {
     /** The response URL */
@@ -1165,6 +1185,30 @@ declare class CrawlPage {
         timeoutMs?: number;
         maxChars?: number;
     }): Promise<ResponseBodyResult>;
+    /**
+     * Wait for a network request matching a URL pattern and return request + response details.
+     *
+     * Unlike `networkRequests()` which only captures metadata, this method captures
+     * the full request body (POST data) and response body.
+     *
+     * @param url - URL string or pattern to match (supports `*` wildcards and substring matching)
+     * @param opts - Options (method filter, timeoutMs, maxChars for response body)
+     * @returns Request method, postData, response status, and response body
+     *
+     * @example
+     * ```ts
+     * const reqPromise = page.waitForRequest('/api/submit', { method: 'POST' });
+     * await page.click('e5'); // submit a form
+     * const req = await reqPromise;
+     * console.log(req.postData); // form body
+     * console.log(req.status, req.responseBody); // response
+     * ```
+     */
+    waitForRequest(url: string, opts?: {
+        method?: string;
+        timeoutMs?: number;
+        maxChars?: number;
+    }): Promise<RequestResult>;
     /**
      * Get console messages captured from the page.
      *
@@ -1535,6 +1579,26 @@ declare class BrowserClaw {
      * @returns Array of tab information objects
      */
     tabs(): Promise<BrowserTab[]>;
+    /**
+     * Wait for a tab matching the given criteria and return a page handle.
+     *
+     * Polls open tabs until one matches, then focuses it and returns a CrawlPage.
+     *
+     * @param opts - Match criteria (urlContains, titleContains) and timeout
+     * @returns A CrawlPage for the matched tab
+     *
+     * @example
+     * ```ts
+     * await page.click('e5'); // opens a new tab
+     * const appPage = await browser.waitForTab({ urlContains: 'app-web' });
+     * const { snapshot } = await appPage.snapshot();
+     * ```
+     */
+    waitForTab(opts: {
+        urlContains?: string;
+        titleContains?: string;
+        timeoutMs?: number;
+    }): Promise<CrawlPage>;
     /**
      * Bring a tab to the foreground.
      *
@@ -1793,4 +1857,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 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, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, 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 RequestResult, 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, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };

package/dist/index.d.ts

@@ -77,6 +77,7 @@ type BatchAction = {
     url?: string;
     loadState?: 'load' | 'domcontentloaded' | 'networkidle';
     fn?: string;
+    arg?: unknown;
     targetId?: string;
     timeoutMs?: number;
 } | {
@@ -411,7 +412,9 @@ interface WaitOptions {
     /** Wait for a specific page load state */
     loadState?: 'load' | 'domcontentloaded' | 'networkidle';
     /** Wait until a JavaScript function returns truthy (evaluated in browser context). Accepts a string or a serializable function. */
-    fn?: string | (() => unknown);
+    fn?: string | ((arg?: unknown) => unknown);
+    /** Serializable argument passed to `fn` in the browser context. Use an array or object to pass multiple values. */
+    arg?: unknown;
     /** Timeout for each condition in milliseconds. Default: `20000` */
     timeoutMs?: number;
 }
@@ -540,6 +543,23 @@ interface DialogEvent {
 }
 /** Callback for persistent dialog handling. */
 type DialogHandler = (event: DialogEvent) => void | Promise<void>;
+/** Result of waiting for a network request to complete. */
+interface RequestResult {
+    /** The final request URL */
+    url: string;
+    /** HTTP method (e.g. `'GET'`, `'POST'`) */
+    method: string;
+    /** Request body (for POST/PUT/PATCH requests) */
+    postData?: string;
+    /** HTTP response status code */
+    status: number;
+    /** Whether the response status was 2xx */
+    ok: boolean;
+    /** Response body text */
+    responseBody?: string;
+    /** Whether the response body was truncated due to maxChars */
+    truncated?: boolean;
+}
 /** Result of intercepting a response body. */
 interface ResponseBodyResult {
     /** The response URL */
@@ -1165,6 +1185,30 @@ declare class CrawlPage {
         timeoutMs?: number;
         maxChars?: number;
     }): Promise<ResponseBodyResult>;
+    /**
+     * Wait for a network request matching a URL pattern and return request + response details.
+     *
+     * Unlike `networkRequests()` which only captures metadata, this method captures
+     * the full request body (POST data) and response body.
+     *
+     * @param url - URL string or pattern to match (supports `*` wildcards and substring matching)
+     * @param opts - Options (method filter, timeoutMs, maxChars for response body)
+     * @returns Request method, postData, response status, and response body
+     *
+     * @example
+     * ```ts
+     * const reqPromise = page.waitForRequest('/api/submit', { method: 'POST' });
+     * await page.click('e5'); // submit a form
+     * const req = await reqPromise;
+     * console.log(req.postData); // form body
+     * console.log(req.status, req.responseBody); // response
+     * ```
+     */
+    waitForRequest(url: string, opts?: {
+        method?: string;
+        timeoutMs?: number;
+        maxChars?: number;
+    }): Promise<RequestResult>;
     /**
      * Get console messages captured from the page.
      *
@@ -1535,6 +1579,26 @@ declare class BrowserClaw {
      * @returns Array of tab information objects
      */
     tabs(): Promise<BrowserTab[]>;
+    /**
+     * Wait for a tab matching the given criteria and return a page handle.
+     *
+     * Polls open tabs until one matches, then focuses it and returns a CrawlPage.
+     *
+     * @param opts - Match criteria (urlContains, titleContains) and timeout
+     * @returns A CrawlPage for the matched tab
+     *
+     * @example
+     * ```ts
+     * await page.click('e5'); // opens a new tab
+     * const appPage = await browser.waitForTab({ urlContains: 'app-web' });
+     * const { snapshot } = await appPage.snapshot();
+     * ```
+     */
+    waitForTab(opts: {
+        urlContains?: string;
+        titleContains?: string;
+        timeoutMs?: number;
+    }): Promise<CrawlPage>;
     /**
      * Bring a tab to the foreground.
      *
@@ -1793,4 +1857,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 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, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, 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 RequestResult, 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, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };

package/dist/index.js

@@ -3107,7 +3107,7 @@ async function pressAndHoldViaCdp(opts) {
 async function clickByTextViaPlaywright(opts) {
   const page = await getRestoredPageForTarget(opts);
   const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
-  const locator = page.getByText(opts.text, { exact: opts.exact }).or(page.getByTitle(opts.text, { exact: opts.exact })).first();
+  const locator = page.getByText(opts.text, { exact: opts.exact }).and(page.locator(":visible")).or(page.getByTitle(opts.text, { exact: opts.exact })).first();
   try {
     await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
   } catch (err) {
@@ -3507,6 +3507,27 @@ async function focusPageByTargetIdViaPlaywright(opts) {
     }
   }
 }
+async function waitForTabViaPlaywright(opts) {
+  if (opts.urlContains === void 0 && opts.titleContains === void 0)
+    throw new Error("urlContains or titleContains is required");
+  const timeout = Math.max(1e3, Math.min(12e4, opts.timeoutMs ?? 3e4));
+  const start = Date.now();
+  const POLL_INTERVAL_MS = 250;
+  while (Date.now() - start < timeout) {
+    const tabs = await listPagesViaPlaywright({ cdpUrl: opts.cdpUrl });
+    const match = tabs.find((t) => {
+      if (opts.urlContains !== void 0 && !t.url.includes(opts.urlContains)) return false;
+      if (opts.titleContains !== void 0 && !t.title.includes(opts.titleContains)) return false;
+      return true;
+    });
+    if (match) return match;
+    await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
+  }
+  const criteria = [];
+  if (opts.urlContains !== void 0) criteria.push(`url contains "${opts.urlContains}"`);
+  if (opts.titleContains !== void 0) criteria.push(`title contains "${opts.titleContains}"`);
+  throw new Error(`Timed out waiting for tab: ${criteria.join(", ")}`);
+}
 async function resizeViewportViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
@@ -3550,10 +3571,10 @@ async function waitForViaPlaywright(opts) {
   }
   if (opts.fn !== void 0) {
     if (typeof opts.fn === "function") {
-      await page.waitForFunction(opts.fn, void 0, { timeout });
+      await page.waitForFunction(opts.fn, opts.arg, { timeout });
     } else {
       const fn = opts.fn.trim();
-      if (fn !== "") await page.waitForFunction(fn, void 0, { timeout });
+      if (fn !== "") await page.waitForFunction(fn, opts.arg, { timeout });
     }
   }
 }
@@ -3666,6 +3687,7 @@ async function executeSingleAction(action, cdpUrl, targetId, evaluateEnabled, de
         url: action.url,
         loadState: action.loadState,
         fn: action.fn,
+        arg: action.arg,
         timeoutMs: action.timeoutMs
       });
       break;
@@ -4141,6 +4163,40 @@ async function responseBodyViaPlaywright(opts) {
     truncated
   };
 }
+async function waitForRequestViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
+  const pattern = opts.url.trim();
+  if (!pattern) throw new Error("url is required");
+  const upperMethod = opts.method !== void 0 ? opts.method.toUpperCase() : void 0;
+  const response = await page.waitForResponse(
+    (resp) => matchUrlPattern(pattern, resp.url()) && (upperMethod === void 0 || resp.request().method() === upperMethod),
+    { timeout }
+  );
+  const request = response.request();
+  let responseBody;
+  let truncated = false;
+  try {
+    responseBody = await response.text();
+    const maxChars = typeof opts.maxChars === "number" && Number.isFinite(opts.maxChars) ? Math.max(1, Math.min(5e6, Math.floor(opts.maxChars))) : 2e5;
+    if (responseBody.length > maxChars) {
+      responseBody = responseBody.slice(0, maxChars);
+      truncated = true;
+    }
+  } catch (err) {
+    console.warn("[browserclaw] response body unavailable:", err instanceof Error ? err.message : String(err));
+  }
+  return {
+    url: response.url(),
+    method: request.method(),
+    postData: request.postData() ?? void 0,
+    status: response.status(),
+    ok: response.ok(),
+    responseBody,
+    truncated
+  };
+}
 
 // src/capture/screenshot.ts
 async function takeScreenshotViaPlaywright(opts) {
@@ -5577,6 +5633,35 @@ var CrawlPage = class {
       maxChars: opts?.maxChars
     });
   }
+  /**
+   * Wait for a network request matching a URL pattern and return request + response details.
+   *
+   * Unlike `networkRequests()` which only captures metadata, this method captures
+   * the full request body (POST data) and response body.
+   *
+   * @param url - URL string or pattern to match (supports `*` wildcards and substring matching)
+   * @param opts - Options (method filter, timeoutMs, maxChars for response body)
+   * @returns Request method, postData, response status, and response body
+   *
+   * @example
+   * ```ts
+   * const reqPromise = page.waitForRequest('/api/submit', { method: 'POST' });
+   * await page.click('e5'); // submit a form
+   * const req = await reqPromise;
+   * console.log(req.postData); // form body
+   * console.log(req.status, req.responseBody); // response
+   * ```
+   */
+  async waitForRequest(url, opts) {
+    return waitForRequestViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      url,
+      method: opts?.method,
+      timeoutMs: opts?.timeoutMs,
+      maxChars: opts?.maxChars
+    });
+  }
   /**
    * Get console messages captured from the page.
    *
@@ -6099,6 +6184,31 @@ var BrowserClaw = class _BrowserClaw {
   async tabs() {
     return listPagesViaPlaywright({ cdpUrl: this.cdpUrl });
   }
+  /**
+   * Wait for a tab matching the given criteria and return a page handle.
+   *
+   * Polls open tabs until one matches, then focuses it and returns a CrawlPage.
+   *
+   * @param opts - Match criteria (urlContains, titleContains) and timeout
+   * @returns A CrawlPage for the matched tab
+   *
+   * @example
+   * ```ts
+   * await page.click('e5'); // opens a new tab
+   * const appPage = await browser.waitForTab({ urlContains: 'app-web' });
+   * const { snapshot } = await appPage.snapshot();
+   * ```
+   */
+  async waitForTab(opts) {
+    const tab = await waitForTabViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      urlContains: opts.urlContains,
+      titleContains: opts.titleContains,
+      timeoutMs: opts.timeoutMs
+    });
+    await focusPageByTargetIdViaPlaywright({ cdpUrl: this.cdpUrl, targetId: tab.targetId });
+    return new CrawlPage(this.cdpUrl, tab.targetId, this.ssrfPolicy);
+  }
   /**
    * Bring a tab to the foreground.
    *