browser-pilot 0.0.9 → 0.0.11

package/dist/browser.d.cts

@@ -1,7 +1,7 @@
 import { C as CDPClient } from './client-7Nqka5MV.cjs';
 import { b as ConnectOptions } from './types--wXNHUwt.cjs';
-import { y as Page } from './types-CYw-7vx1.cjs';
-export { k as ActionOptions, l as ActionResult, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, p as CustomSelectConfig, D as Dialog, q as DialogHandler, r as DialogType, s as Download, E as ElementInfo, t as ElementNotFoundError, u as EmulationState, v as ErrorHandler, ae as FailureHint, F as FileInput, w as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, x as NetworkIdleOptions, z as PageError, H as PageSnapshot, J as SnapshotNode, K as SubmitOptions, T as TimeoutError, L as TypeOptions, U as UserAgentMetadata, M as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-CYw-7vx1.cjs';
+import { y as Page } from './types-GWuQJs_e.cjs';
+export { k as ActionOptions, l as ActionResult, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, p as CustomSelectConfig, D as Dialog, q as DialogHandler, r as DialogType, s as Download, E as ElementInfo, t as ElementNotFoundError, u as EmulationState, v as ErrorHandler, ae as FailureHint, F as FileInput, w as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, x as NetworkIdleOptions, z as PageError, H as PageSnapshot, J as SnapshotNode, K as SubmitOptions, T as TimeoutError, L as TypeOptions, U as UserAgentMetadata, M as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-GWuQJs_e.cjs';
 
 /**
  * Browser class - manages CDP connection and pages
@@ -14,6 +14,18 @@ interface BrowserOptions extends ConnectOptions {
 interface PageOptions {
     /** Specific target ID to attach to */
     targetId?: string;
+    /** Filter targets to those whose URL contains this string */
+    targetUrl?: string;
+    /**
+     * Minimum acceptable viewport dimensions.
+     * If the attached target's viewport is smaller, it will be overridden.
+     * Defaults to { width: 200, height: 200 }.
+     * Set to false to disable viewport validation.
+     */
+    minViewport?: {
+        width: number;
+        height: number;
+    } | false;
 }
 declare class Browser {
     private cdp;
@@ -25,8 +37,13 @@ declare class Browser {
      */
     static connect(options: BrowserOptions): Promise<Browser>;
     /**
-     * Get or create a page by name
-     * If no name is provided, returns the first available page or creates a new one
+     * Get or create a page by name.
+     * If no name is provided, returns the first available page or creates a new one.
+     *
+     * Target selection heuristics (when no targetId is specified):
+     * - Prefer http/https URLs over chrome://, devtools://, about:blank
+     * - Prefer unattached targets (not already controlled by another client)
+     * - Filter by targetUrl if provided
      */
     page(name?: string, options?: PageOptions): Promise<Page>;
     /**
@@ -72,4 +89,4 @@ declare class Browser {
  */
 declare function connect(options: BrowserOptions): Promise<Browser>;
 
-export { Browser, type BrowserOptions, Page, connect };
+export { Browser, type BrowserOptions, Page, type PageOptions, connect };

package/dist/browser.d.ts

@@ -1,7 +1,7 @@
 import { C as CDPClient } from './client-7Nqka5MV.js';
 import { b as ConnectOptions } from './types--wXNHUwt.js';
-import { y as Page } from './types-DOGsEYQa.js';
-export { k as ActionOptions, l as ActionResult, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, p as CustomSelectConfig, D as Dialog, q as DialogHandler, r as DialogType, s as Download, E as ElementInfo, t as ElementNotFoundError, u as EmulationState, v as ErrorHandler, ae as FailureHint, F as FileInput, w as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, x as NetworkIdleOptions, z as PageError, H as PageSnapshot, J as SnapshotNode, K as SubmitOptions, T as TimeoutError, L as TypeOptions, U as UserAgentMetadata, M as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-DOGsEYQa.js';
+import { y as Page } from './types-DtGF3yGl.js';
+export { k as ActionOptions, l as ActionResult, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, p as CustomSelectConfig, D as Dialog, q as DialogHandler, r as DialogType, s as Download, E as ElementInfo, t as ElementNotFoundError, u as EmulationState, v as ErrorHandler, ae as FailureHint, F as FileInput, w as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, x as NetworkIdleOptions, z as PageError, H as PageSnapshot, J as SnapshotNode, K as SubmitOptions, T as TimeoutError, L as TypeOptions, U as UserAgentMetadata, M as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-DtGF3yGl.js';
 
 /**
  * Browser class - manages CDP connection and pages
@@ -14,6 +14,18 @@ interface BrowserOptions extends ConnectOptions {
 interface PageOptions {
     /** Specific target ID to attach to */
     targetId?: string;
+    /** Filter targets to those whose URL contains this string */
+    targetUrl?: string;
+    /**
+     * Minimum acceptable viewport dimensions.
+     * If the attached target's viewport is smaller, it will be overridden.
+     * Defaults to { width: 200, height: 200 }.
+     * Set to false to disable viewport validation.
+     */
+    minViewport?: {
+        width: number;
+        height: number;
+    } | false;
 }
 declare class Browser {
     private cdp;
@@ -25,8 +37,13 @@ declare class Browser {
      */
     static connect(options: BrowserOptions): Promise<Browser>;
     /**
-     * Get or create a page by name
-     * If no name is provided, returns the first available page or creates a new one
+     * Get or create a page by name.
+     * If no name is provided, returns the first available page or creates a new one.
+     *
+     * Target selection heuristics (when no targetId is specified):
+     * - Prefer http/https URLs over chrome://, devtools://, about:blank
+     * - Prefer unattached targets (not already controlled by another client)
+     * - Filter by targetUrl if provided
      */
     page(name?: string, options?: PageOptions): Promise<Page>;
     /**
@@ -72,4 +89,4 @@ declare class Browser {
  */
 declare function connect(options: BrowserOptions): Promise<Browser>;
 
-export { Browser, type BrowserOptions, Page, connect };
+export { Browser, type BrowserOptions, Page, type PageOptions, connect };

package/dist/browser.mjs

@@ -2,14 +2,14 @@ import {
   Browser,
   Page,
   connect
-} from "./chunk-7OSR2CAE.mjs";
+} from "./chunk-JHAF52FA.mjs";
 import "./chunk-BCOZUKWS.mjs";
-import "./chunk-R3PS4PCM.mjs";
+import "./chunk-BRAFQUMG.mjs";
 import {
   ElementNotFoundError,
   NavigationError,
   TimeoutError
-} from "./chunk-KKW2SZLV.mjs";
+} from "./chunk-FAUNIZR7.mjs";
 export {
   Browser,
   ElementNotFoundError,

package/dist/{chunk-R3PS4PCM.mjs → chunk-BRAFQUMG.mjs}

@@ -129,6 +129,34 @@ var BrowserlessProvider = class {
 };
 
 // src/providers/generic.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchDevToolsJson(host, path, errorPrefix, options = {}) {
+  const protocol = host.includes("://") ? "" : "http://";
+  const attempts = options.attempts ?? 1;
+  let delayMs = options.initialDelayMs ?? 50;
+  const maxDelayMs = options.maxDelayMs ?? 250;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      const response = await fetch(`${protocol}${host}${path}`);
+      if (response.ok) {
+        return await response.json();
+      }
+      lastError = new Error(`${errorPrefix}: ${response.status}`);
+    } catch (error) {
+      lastError = new Error(
+        `${errorPrefix}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    if (attempt < attempts) {
+      await sleep(delayMs);
+      delayMs = Math.min(delayMs * 2, maxDelayMs);
+    }
+  }
+  throw lastError ?? new Error(errorPrefix);
+}
 var GenericProvider = class {
   name = "generic";
   wsUrl;
@@ -147,20 +175,14 @@ var GenericProvider = class {
   }
 };
 async function discoverTargets(host = "localhost:9222") {
-  const protocol = host.includes("://") ? "" : "http://";
-  const response = await fetch(`${protocol}${host}/json/list`);
-  if (!response.ok) {
-    throw new Error(`Failed to discover targets: ${response.status}`);
-  }
-  return await response.json();
+  return fetchDevToolsJson(host, "/json/list", "Failed to discover targets");
 }
 async function getBrowserWebSocketUrl(host = "localhost:9222") {
-  const protocol = host.includes("://") ? "" : "http://";
-  const response = await fetch(`${protocol}${host}/json/version`);
-  if (!response.ok) {
-    throw new Error(`Failed to get browser info: ${response.status}`);
-  }
-  const info = await response.json();
+  const info = await fetchDevToolsJson(host, "/json/version", "Failed to get browser info", {
+    attempts: 10,
+    initialDelayMs: 50,
+    maxDelayMs: 250
+  });
   return info.webSocketDebuggerUrl;
 }
 

package/dist/{chunk-KKW2SZLV.mjs → chunk-FAUNIZR7.mjs}

@@ -4,7 +4,12 @@ var ElementNotFoundError = class extends Error {
   hints;
   constructor(selectors, hints) {
     const selectorList = Array.isArray(selectors) ? selectors : [selectors];
-    super(`Element not found: ${selectorList.join(", ")}`);
+    let msg = `Element not found: ${selectorList.join(", ")}`;
+    if (hints?.length) {
+      msg += `. Did you mean: ${hints.slice(0, 3).map((h) => `${h.element.ref} (${h.element.role} "${h.element.name}")`).join(", ")}`;
+    }
+    msg += `. Run 'bp snapshot' to see available elements.`;
+    super(msg);
     this.name = "ElementNotFoundError";
     this.selectors = selectorList;
     this.hints = hints;
@@ -12,7 +17,8 @@ var ElementNotFoundError = class extends Error {
 };
 var TimeoutError = class extends Error {
   constructor(message = "Operation timed out") {
-    super(message);
+    const msg = message.includes("bp snapshot") ? message : `${message}. Run 'bp snapshot' to check current page state.`;
+    super(msg);
     this.name = "TimeoutError";
   }
 };
@@ -95,7 +101,7 @@ var BatchExecutor = class {
       }
       case "click": {
         if (!step.selector) throw new Error("click requires selector");
-        if (step.waitForNavigation) {
+        if (step.waitForNavigation === true) {
           const navPromise = this.page.waitForNavigation({ timeout, optional });
           await this.page.click(step.selector, { timeout, optional });
           await navPromise;
@@ -110,7 +116,6 @@ var BatchExecutor = class {
         await this.page.fill(step.selector, step.value, {
           timeout,
           optional,
-          clear: step.clear ?? true,
           blur: step.blur
         });
         return { selectorUsed: this.getUsedSelector(step.selector) };
@@ -158,7 +163,8 @@ var BatchExecutor = class {
         await this.page.submit(step.selector, {
           timeout,
           optional,
-          method: step.method ?? "enter+click"
+          method: step.method ?? "enter+click",
+          waitForNavigation: step.waitForNavigation
         });
         return { selectorUsed: this.getUsedSelector(step.selector) };
       }
@@ -380,7 +386,6 @@ var ACTION_RULES = {
   fill: {
     required: { selector: { type: "string|string[]" }, value: { type: "string" } },
     optional: {
-      clear: { type: "boolean" },
       blur: { type: "boolean" }
     }
   },
@@ -411,7 +416,8 @@ var ACTION_RULES = {
   submit: {
     required: { selector: { type: "string|string[]" } },
     optional: {
-      method: { type: "string", enum: ["enter", "click", "enter+click"] }
+      method: { type: "string", enum: ["enter", "click", "enter+click"] },
+      waitForNavigation: { type: "boolean|auto" }
     }
   },
   press: {
@@ -489,7 +495,6 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "timeout",
   "optional",
   "method",
-  "clear",
   "blur",
   "delay",
   "waitForNavigation",
@@ -570,6 +575,11 @@ function checkFieldType(value, rule) {
     case "boolean":
       if (typeof value !== "boolean") return `expected boolean, got ${typeof value}`;
       return null;
+    case "boolean|auto":
+      if (typeof value !== "boolean" && value !== "auto") {
+        return `expected boolean or "auto", got ${typeof value}`;
+      }
+      return null;
   }
 }
 function validateSteps(steps) {