browser-pilot 0.0.1

package/dist/cli.cjs

@@ -0,0 +1,3587 @@
+#!/usr/bin/env bun
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli/index.ts
+var cli_exports = {};
+__export(cli_exports, {
+  output: () => output
+});
+module.exports = __toCommonJS(cli_exports);
+
+// src/cli/commands/actions.ts
+var ACTIONS_HELP = `
+bp actions - Complete action reference
+
+All actions are JSON objects with "action" field. Use with 'bp exec'.
+
+NAVIGATION
+  {"action": "goto", "url": "https://..."}
+    Navigate to URL.
+
+  {"action": "wait", "waitFor": "navigation"}
+    Wait for page navigation to complete.
+
+  {"action": "wait", "waitFor": "networkIdle"}
+    Wait for network activity to settle.
+
+  {"action": "wait", "timeout": 2000}
+    Simple delay in milliseconds.
+
+INTERACTION
+  {"action": "click", "selector": "#button"}
+  {"action": "click", "selector": ["#primary", ".fallback"]}
+    Click element. Multi-selector tries each until success.
+
+  {"action": "fill", "selector": "#input", "value": "text"}
+  {"action": "fill", "selector": "#input", "value": "text", "clear": false}
+    Fill input field. Clears first by default.
+
+  {"action": "type", "selector": "#input", "value": "text", "delay": 50}
+    Type character-by-character (for autocomplete).
+
+  {"action": "select", "selector": "#dropdown", "value": "option-value"}
+    Select native <select> option by value.
+
+  {"action": "select", "trigger": ".dropdown", "option": ".item", "value": "Label", "match": "text"}
+    Custom dropdown: click trigger, then click matching option.
+
+  {"action": "check", "selector": "#checkbox"}
+  {"action": "uncheck", "selector": "#checkbox"}
+    Check/uncheck checkbox or radio.
+
+  {"action": "submit", "selector": "form"}
+  {"action": "submit", "selector": "#btn", "method": "click"}
+    Submit form. Methods: enter | click | enter+click (default).
+
+  {"action": "press", "key": "Enter"}
+  {"action": "press", "key": "Escape"}
+  {"action": "press", "key": "Tab"}
+    Press key. Common keys: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right.
+
+  {"action": "focus", "selector": "#input"}
+  {"action": "hover", "selector": ".menu-item"}
+    Focus or hover element.
+
+  {"action": "scroll", "selector": "#footer"}
+  {"action": "scroll", "x": 0, "y": 1000}
+  {"action": "scroll", "direction": "down", "amount": 500}
+    Scroll to element, coordinates, or by direction (up/down/left/right).
+
+WAITING
+  {"action": "wait", "selector": ".loaded", "waitFor": "visible"}
+  {"action": "wait", "selector": ".spinner", "waitFor": "hidden"}
+  {"action": "wait", "selector": "#element", "waitFor": "attached"}
+  {"action": "wait", "selector": "#removed", "waitFor": "detached"}
+    Wait for element state. States: visible | hidden | attached | detached.
+
+  {"action": "wait", "timeout": 1000}
+    Simple delay (milliseconds).
+
+CONTENT EXTRACTION
+  {"action": "snapshot"}
+    Get accessibility tree (best for understanding page structure).
+
+  {"action": "screenshot"}
+  {"action": "screenshot", "fullPage": true, "format": "jpeg", "quality": 80}
+    Capture screenshot. Formats: png | jpeg | webp.
+
+  {"action": "evaluate", "value": "document.title"}
+    Run JavaScript and return result.
+
+IFRAME NAVIGATION
+  {"action": "switchFrame", "selector": "iframe#checkout"}
+    Switch context to an iframe. All subsequent actions target the iframe content.
+
+  {"action": "switchToMain"}
+    Switch back to the main document from an iframe.
+
+  Example iframe workflow:
+    [
+      {"action": "switchFrame", "selector": "iframe#payment"},
+      {"action": "fill", "selector": "#card-number", "value": "4242424242424242"},
+      {"action": "fill", "selector": "#expiry", "value": "12/25"},
+      {"action": "switchToMain"},
+      {"action": "click", "selector": "#submit-order"}
+    ]
+
+  Note: Cross-origin iframes cannot be accessed due to browser security.
+
+DIALOG HANDLING
+  Use --dialog flag: bp exec --dialog accept '[...]'
+  Modes: accept (click OK), dismiss (click Cancel)
+
+  WARNING: Without --dialog flag, native dialogs (alert/confirm/prompt) will
+  block ALL automation until manual intervention.
+
+COMMON OPTIONS (all actions)
+  "timeout": 5000        Override default timeout (ms)
+  "optional": true       Don't fail if element not found
+
+REF SELECTORS (from snapshot)
+  After taking a snapshot, use refs directly:
+    bp snapshot -s dev --format text   # Shows: button "Submit" [ref=e4]
+    bp exec '{"action":"click","selector":"ref:e4"}'
+
+  Refs are stable until navigation. Prefix with "ref:" to use.
+  Example: {"action":"fill","selector":"ref:e23","value":"hello"}
+
+MULTI-SELECTOR PATTERN
+  All selectors accept arrays: ["#id", ".class", "[aria-label=X]"]
+  Tries each in order until one succeeds.
+  Combine refs with CSS fallbacks: ["ref:e4", "#submit", ".btn"]
+
+SELECTOR PRIORITY (Most to Least Reliable)
+  1. ref:eN               - From snapshot, most reliable for AI agents
+  2. [data-testid="..."]  - Explicit test hooks
+  3. #id                  - Reliable if IDs are stable
+  4. [aria-label="..."]   - Good for buttons without testids
+  5. Multi-selector array - Fallback pattern for compatibility
+
+SHADOW DOM
+  Selectors automatically pierce shadow DOM (1-2 levels). No special syntax needed.
+  For deeper nesting (3+ levels), use refs from snapshot - they work at any depth.
+
+:has-text() SELECTOR
+  Matches elements containing text content.
+  Does NOT match aria-label - use [aria-label="..."] instead.
+  Example: button:has-text("Submit") matches <button>Submit</button>
+           button[aria-label="Submit"] matches <button aria-label="Submit">X</button>
+
+EXAMPLES
+  # Login flow
+  bp exec '[
+    {"action":"goto","url":"https://app.example.com/login"},
+    {"action":"fill","selector":"#email","value":"user@example.com"},
+    {"action":"fill","selector":"#password","value":"secret"},
+    {"action":"submit","selector":"form"},
+    {"action":"wait","waitFor":"navigation"},
+    {"action":"snapshot"}
+  ]'
+
+  # Handle cookie banner then extract content
+  bp exec '[
+    {"action":"goto","url":"https://example.com"},
+    {"action":"click","selector":"#accept-cookies","optional":true,"timeout":3000},
+    {"action":"snapshot"}
+  ]'
+
+  # Use ref from snapshot
+  bp snapshot --format text  # Note the refs
+  bp exec '{"action":"click","selector":"ref:e4"}'
+
+  # Scroll and wait
+  bp exec '[
+    {"action":"scroll","direction":"down","amount":1000},
+    {"action":"wait","timeout":500},
+    {"action":"scroll","direction":"down","amount":1000}
+  ]'
+
+  # Handle dialogs
+  bp exec --dialog accept '[
+    {"action":"click","selector":"#delete-btn"},
+    {"action":"wait","selector":"#success-message","waitFor":"visible"}
+  ]'
+`;
+async function actionsCommand() {
+  console.log(ACTIONS_HELP);
+}
+
+// src/actions/executor.ts
+var DEFAULT_TIMEOUT = 3e4;
+var BatchExecutor = class {
+  page;
+  constructor(page) {
+    this.page = page;
+  }
+  /**
+   * Execute a batch of steps
+   */
+  async execute(steps, options = {}) {
+    const { timeout = DEFAULT_TIMEOUT, onFail = "stop" } = options;
+    const results = [];
+    const startTime = Date.now();
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const stepStart = Date.now();
+      try {
+        const result = await this.executeStep(step, timeout);
+        results.push({
+          index: i,
+          action: step.action,
+          selector: step.selector,
+          selectorUsed: result.selectorUsed,
+          success: true,
+          durationMs: Date.now() - stepStart,
+          result: result.value,
+          text: result.text
+        });
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        results.push({
+          index: i,
+          action: step.action,
+          selector: step.selector,
+          success: false,
+          durationMs: Date.now() - stepStart,
+          error: errorMessage
+        });
+        if (onFail === "stop" && !step.optional) {
+          return {
+            success: false,
+            stoppedAtIndex: i,
+            steps: results,
+            totalDurationMs: Date.now() - startTime
+          };
+        }
+      }
+    }
+    const allSuccess = results.every((r) => r.success || steps[r.index]?.optional);
+    return {
+      success: allSuccess,
+      steps: results,
+      totalDurationMs: Date.now() - startTime
+    };
+  }
+  /**
+   * Execute a single step
+   */
+  async executeStep(step, defaultTimeout) {
+    const timeout = step.timeout ?? defaultTimeout;
+    const optional = step.optional ?? false;
+    switch (step.action) {
+      case "goto": {
+        if (!step.url) throw new Error("goto requires url");
+        await this.page.goto(step.url, { timeout, optional });
+        return {};
+      }
+      case "click": {
+        if (!step.selector) throw new Error("click requires selector");
+        if (step.waitForNavigation) {
+          const navPromise = this.page.waitForNavigation({ timeout, optional });
+          await this.page.click(step.selector, { timeout, optional });
+          await navPromise;
+        } else {
+          await this.page.click(step.selector, { timeout, optional });
+        }
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "fill": {
+        if (!step.selector) throw new Error("fill requires selector");
+        if (typeof step.value !== "string") throw new Error("fill requires string value");
+        await this.page.fill(step.selector, step.value, {
+          timeout,
+          optional,
+          clear: step.clear ?? true
+        });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "type": {
+        if (!step.selector) throw new Error("type requires selector");
+        if (typeof step.value !== "string") throw new Error("type requires string value");
+        await this.page.type(step.selector, step.value, {
+          timeout,
+          optional,
+          delay: step.delay ?? 50
+        });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "select": {
+        if (step.trigger && step.option && typeof step.value === "string") {
+          await this.page.select(
+            {
+              trigger: step.trigger,
+              option: step.option,
+              value: step.value,
+              match: step.match
+            },
+            { timeout, optional }
+          );
+          return { selectorUsed: this.getUsedSelector(step.trigger) };
+        }
+        if (!step.selector) throw new Error("select requires selector");
+        if (!step.value) throw new Error("select requires value");
+        await this.page.select(step.selector, step.value, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "check": {
+        if (!step.selector) throw new Error("check requires selector");
+        await this.page.check(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "uncheck": {
+        if (!step.selector) throw new Error("uncheck requires selector");
+        await this.page.uncheck(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "submit": {
+        if (!step.selector) throw new Error("submit requires selector");
+        await this.page.submit(step.selector, {
+          timeout,
+          optional,
+          method: step.method ?? "enter+click"
+        });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "press": {
+        if (!step.key) throw new Error("press requires key");
+        await this.page.press(step.key);
+        return {};
+      }
+      case "focus": {
+        if (!step.selector) throw new Error("focus requires selector");
+        await this.page.focus(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "hover": {
+        if (!step.selector) throw new Error("hover requires selector");
+        await this.page.hover(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "scroll": {
+        if (step.x !== void 0 || step.y !== void 0) {
+          await this.page.scroll("body", { x: step.x, y: step.y, timeout, optional });
+          return {};
+        }
+        if (!step.selector && (step.direction || step.amount !== void 0)) {
+          const amount = step.amount ?? 500;
+          const direction = step.direction ?? "down";
+          const deltaY = direction === "down" ? amount : direction === "up" ? -amount : 0;
+          const deltaX = direction === "right" ? amount : direction === "left" ? -amount : 0;
+          await this.page.evaluate(`window.scrollBy(${deltaX}, ${deltaY})`);
+          return {};
+        }
+        if (!step.selector) throw new Error("scroll requires selector, coordinates, or direction");
+        await this.page.scroll(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "wait": {
+        if (!step.selector && !step.waitFor) {
+          const delay = step.timeout ?? 1e3;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          return {};
+        }
+        if (step.waitFor === "navigation") {
+          await this.page.waitForNavigation({ timeout, optional });
+          return {};
+        }
+        if (step.waitFor === "networkIdle") {
+          await this.page.waitForNetworkIdle({ timeout, optional });
+          return {};
+        }
+        if (!step.selector)
+          throw new Error(
+            "wait requires selector (or waitFor: navigation/networkIdle, or timeout for simple delay)"
+          );
+        await this.page.waitFor(step.selector, {
+          timeout,
+          optional,
+          state: step.waitFor ?? "visible"
+        });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "snapshot": {
+        const snapshot = await this.page.snapshot();
+        return { value: snapshot };
+      }
+      case "screenshot": {
+        const data = await this.page.screenshot({
+          format: step.format,
+          quality: step.quality,
+          fullPage: step.fullPage
+        });
+        return { value: data };
+      }
+      case "evaluate": {
+        if (typeof step.value !== "string")
+          throw new Error("evaluate requires string value (expression)");
+        const result = await this.page.evaluate(step.value);
+        return { value: result };
+      }
+      case "text": {
+        const selector = Array.isArray(step.selector) ? step.selector[0] : step.selector;
+        const text = await this.page.text(selector);
+        return { text, selectorUsed: selector };
+      }
+      case "switchFrame": {
+        if (!step.selector) throw new Error("switchFrame requires selector");
+        await this.page.switchToFrame(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "switchToMain": {
+        await this.page.switchToMain();
+        return {};
+      }
+      default:
+        throw new Error(
+          `Unknown action: ${step.action}. Run 'bp actions' for available actions.`
+        );
+    }
+  }
+  /**
+   * Get the first selector if multiple were provided
+   * (actual used selector tracking would need to be implemented in Page)
+   */
+  getUsedSelector(selector) {
+    return Array.isArray(selector) ? selector[0] : selector;
+  }
+};
+function addBatchToPage(page) {
+  const executor = new BatchExecutor(page);
+  return Object.assign(page, {
+    batch: (steps, options) => executor.execute(steps, options)
+  });
+}
+
+// src/cdp/protocol.ts
+var CDPError = class extends Error {
+  code;
+  data;
+  constructor(error) {
+    super(error.message);
+    this.name = "CDPError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+};
+
+// src/cdp/transport.ts
+function createTransport(wsUrl, options = {}) {
+  const { timeout = 3e4 } = options;
+  return new Promise((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      reject(new Error(`WebSocket connection timeout after ${timeout}ms`));
+    }, timeout);
+    const ws = new WebSocket(wsUrl);
+    const messageHandlers = [];
+    const closeHandlers = [];
+    const errorHandlers = [];
+    ws.addEventListener("open", () => {
+      clearTimeout(timeoutId);
+      const transport = {
+        send(message) {
+          if (ws.readyState === WebSocket.OPEN) {
+            ws.send(message);
+          } else {
+            throw new Error(
+              `Cannot send message, WebSocket is ${getReadyStateString(ws.readyState)}`
+            );
+          }
+        },
+        async close() {
+          return new Promise((resolveClose) => {
+            if (ws.readyState === WebSocket.CLOSED) {
+              resolveClose();
+              return;
+            }
+            const onClose = () => {
+              ws.removeEventListener("close", onClose);
+              resolveClose();
+            };
+            ws.addEventListener("close", onClose);
+            ws.close();
+            setTimeout(resolveClose, 5e3);
+          });
+        },
+        onMessage(handler) {
+          messageHandlers.push(handler);
+        },
+        onClose(handler) {
+          closeHandlers.push(handler);
+        },
+        onError(handler) {
+          errorHandlers.push(handler);
+        }
+      };
+      resolve(transport);
+    });
+    ws.addEventListener("message", (event) => {
+      const data = typeof event.data === "string" ? event.data : String(event.data);
+      for (const handler of messageHandlers) {
+        handler(data);
+      }
+    });
+    ws.addEventListener("close", () => {
+      for (const handler of closeHandlers) {
+        handler();
+      }
+    });
+    ws.addEventListener("error", (_event) => {
+      clearTimeout(timeoutId);
+      const error = new Error("WebSocket connection error");
+      for (const handler of errorHandlers) {
+        handler(error);
+      }
+      reject(error);
+    });
+  });
+}
+function getReadyStateString(state) {
+  switch (state) {
+    case WebSocket.CONNECTING:
+      return "CONNECTING";
+    case WebSocket.OPEN:
+      return "OPEN";
+    case WebSocket.CLOSING:
+      return "CLOSING";
+    case WebSocket.CLOSED:
+      return "CLOSED";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+// src/cdp/client.ts
+async function createCDPClient(wsUrl, options = {}) {
+  const { debug = false, timeout = 3e4 } = options;
+  const transport = await createTransport(wsUrl, { timeout });
+  let messageId = 0;
+  let currentSessionId;
+  let connected = true;
+  const pending = /* @__PURE__ */ new Map();
+  const eventHandlers = /* @__PURE__ */ new Map();
+  const anyEventHandlers = /* @__PURE__ */ new Set();
+  transport.onMessage((raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      if (debug) console.error("[CDP] Failed to parse message:", raw);
+      return;
+    }
+    if (debug) {
+      console.log("[CDP] <--", JSON.stringify(msg, null, 2).slice(0, 500));
+    }
+    if ("id" in msg && typeof msg.id === "number") {
+      const response = msg;
+      const request = pending.get(response.id);
+      if (request) {
+        pending.delete(response.id);
+        clearTimeout(request.timer);
+        if (response.error) {
+          request.reject(new CDPError(response.error));
+        } else {
+          request.resolve(response.result);
+        }
+      }
+      return;
+    }
+    if ("method" in msg) {
+      const event = msg;
+      const params = event.params ?? {};
+      for (const handler of anyEventHandlers) {
+        try {
+          handler(event.method, params);
+        } catch (e) {
+          if (debug) console.error("[CDP] Error in any-event handler:", e);
+        }
+      }
+      const handlers = eventHandlers.get(event.method);
+      if (handlers) {
+        for (const handler of handlers) {
+          try {
+            handler(params);
+          } catch (e) {
+            if (debug) console.error(`[CDP] Error in handler for ${event.method}:`, e);
+          }
+        }
+      }
+    }
+  });
+  transport.onClose(() => {
+    connected = false;
+    for (const [id, request] of pending) {
+      clearTimeout(request.timer);
+      request.reject(new Error("WebSocket connection closed"));
+      pending.delete(id);
+    }
+  });
+  transport.onError((error) => {
+    if (debug) console.error("[CDP] Transport error:", error);
+  });
+  const client = {
+    async send(method, params, sessionId) {
+      if (!connected) {
+        throw new Error("CDP client is not connected");
+      }
+      const id = ++messageId;
+      const effectiveSessionId = sessionId ?? currentSessionId;
+      const request = { id, method };
+      if (params !== void 0) {
+        request.params = params;
+      }
+      if (effectiveSessionId !== void 0) {
+        request.sessionId = effectiveSessionId;
+      }
+      const message = JSON.stringify(request);
+      if (debug) {
+        console.log("[CDP] -->", message.slice(0, 500));
+      }
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`CDP command ${method} timed out after ${timeout}ms`));
+        }, timeout);
+        pending.set(id, {
+          resolve,
+          reject,
+          method,
+          timer
+        });
+        try {
+          transport.send(message);
+        } catch (e) {
+          pending.delete(id);
+          clearTimeout(timer);
+          reject(e);
+        }
+      });
+    },
+    on(event, handler) {
+      let handlers = eventHandlers.get(event);
+      if (!handlers) {
+        handlers = /* @__PURE__ */ new Set();
+        eventHandlers.set(event, handlers);
+      }
+      handlers.add(handler);
+    },
+    off(event, handler) {
+      const handlers = eventHandlers.get(event);
+      if (handlers) {
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+          eventHandlers.delete(event);
+        }
+      }
+    },
+    onAny(handler) {
+      anyEventHandlers.add(handler);
+    },
+    async close() {
+      connected = false;
+      await transport.close();
+    },
+    async attachToTarget(targetId) {
+      const result = await this.send("Target.attachToTarget", {
+        targetId,
+        flatten: true
+      });
+      currentSessionId = result.sessionId;
+      return result.sessionId;
+    },
+    get sessionId() {
+      return currentSessionId;
+    },
+    get isConnected() {
+      return connected;
+    }
+  };
+  return client;
+}
+
+// src/providers/browserbase.ts
+var BrowserBaseProvider = class {
+  name = "browserbase";
+  apiKey;
+  projectId;
+  baseUrl;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.projectId = options.projectId;
+    this.baseUrl = options.baseUrl ?? "https://api.browserbase.com";
+  }
+  async createSession(options = {}) {
+    const response = await fetch(`${this.baseUrl}/v1/sessions`, {
+      method: "POST",
+      headers: {
+        "X-BB-API-Key": this.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        projectId: this.projectId,
+        browserSettings: {
+          viewport: options.width && options.height ? {
+            width: options.width,
+            height: options.height
+          } : void 0
+        },
+        ...options
+      })
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`BrowserBase createSession failed: ${response.status} ${text}`);
+    }
+    const session = await response.json();
+    const connectResponse = await fetch(`${this.baseUrl}/v1/sessions/${session.id}`, {
+      headers: {
+        "X-BB-API-Key": this.apiKey
+      }
+    });
+    if (!connectResponse.ok) {
+      throw new Error(`BrowserBase getSession failed: ${connectResponse.status}`);
+    }
+    const sessionDetails = await connectResponse.json();
+    if (!sessionDetails.connectUrl) {
+      throw new Error("BrowserBase session does not have a connectUrl");
+    }
+    return {
+      wsUrl: sessionDetails.connectUrl,
+      sessionId: session.id,
+      metadata: {
+        debugUrl: sessionDetails.debugUrl,
+        projectId: this.projectId,
+        status: sessionDetails.status
+      },
+      close: async () => {
+        await fetch(`${this.baseUrl}/v1/sessions/${session.id}`, {
+          method: "DELETE",
+          headers: {
+            "X-BB-API-Key": this.apiKey
+          }
+        });
+      }
+    };
+  }
+  async resumeSession(sessionId) {
+    const response = await fetch(`${this.baseUrl}/v1/sessions/${sessionId}`, {
+      headers: {
+        "X-BB-API-Key": this.apiKey
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`BrowserBase resumeSession failed: ${response.status}`);
+    }
+    const session = await response.json();
+    if (!session.connectUrl) {
+      throw new Error("BrowserBase session does not have a connectUrl (may be closed)");
+    }
+    return {
+      wsUrl: session.connectUrl,
+      sessionId: session.id,
+      metadata: {
+        debugUrl: session.debugUrl,
+        projectId: this.projectId,
+        status: session.status
+      },
+      close: async () => {
+        await fetch(`${this.baseUrl}/v1/sessions/${sessionId}`, {
+          method: "DELETE",
+          headers: {
+            "X-BB-API-Key": this.apiKey
+          }
+        });
+      }
+    };
+  }
+};
+
+// src/providers/browserless.ts
+var BrowserlessProvider = class {
+  name = "browserless";
+  token;
+  baseUrl;
+  constructor(options) {
+    this.token = options.token;
+    this.baseUrl = options.baseUrl ?? "wss://chrome.browserless.io";
+  }
+  async createSession(options = {}) {
+    const params = new URLSearchParams({
+      token: this.token
+    });
+    if (options.width && options.height) {
+      params.set("--window-size", `${options.width},${options.height}`);
+    }
+    if (options.proxy?.server) {
+      params.set("--proxy-server", options.proxy.server);
+    }
+    const wsUrl = `${this.baseUrl}?${params.toString()}`;
+    return {
+      wsUrl,
+      metadata: {
+        provider: "browserless"
+      },
+      close: async () => {
+      }
+    };
+  }
+  // Browserless doesn't support session resumption in the same way
+  // Each connection is a fresh browser instance
+};
+
+// src/providers/generic.ts
+var GenericProvider = class {
+  name = "generic";
+  wsUrl;
+  constructor(options) {
+    this.wsUrl = options.wsUrl;
+  }
+  async createSession(_options = {}) {
+    return {
+      wsUrl: this.wsUrl,
+      metadata: {
+        provider: "generic"
+      },
+      close: async () => {
+      }
+    };
+  }
+};
+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();
+  return info.webSocketDebuggerUrl;
+}
+
+// src/providers/index.ts
+function createProvider(options) {
+  switch (options.provider) {
+    case "browserbase":
+      if (!options.apiKey) {
+        throw new Error("BrowserBase provider requires apiKey");
+      }
+      if (!options.projectId) {
+        throw new Error("BrowserBase provider requires projectId");
+      }
+      return new BrowserBaseProvider({
+        apiKey: options.apiKey,
+        projectId: options.projectId
+      });
+    case "browserless":
+      if (!options.apiKey) {
+        throw new Error("Browserless provider requires apiKey (token)");
+      }
+      return new BrowserlessProvider({
+        token: options.apiKey
+      });
+    case "generic":
+      if (!options.wsUrl) {
+        throw new Error("Generic provider requires wsUrl");
+      }
+      return new GenericProvider({
+        wsUrl: options.wsUrl
+      });
+    default:
+      throw new Error(`Unknown provider: ${options.provider}`);
+  }
+}
+
+// src/network/interceptor.ts
+var RequestInterceptor = class {
+  cdp;
+  enabled = false;
+  handlers = [];
+  pendingRequests = /* @__PURE__ */ new Map();
+  boundHandleRequestPaused;
+  boundHandleAuthRequired;
+  constructor(cdp) {
+    this.cdp = cdp;
+    this.boundHandleRequestPaused = this.handleRequestPaused.bind(this);
+    this.boundHandleAuthRequired = this.handleAuthRequired.bind(this);
+  }
+  /**
+   * Enable request interception with optional patterns
+   */
+  async enable(patterns) {
+    if (this.enabled) return;
+    this.cdp.on("Fetch.requestPaused", this.boundHandleRequestPaused);
+    this.cdp.on("Fetch.authRequired", this.boundHandleAuthRequired);
+    await this.cdp.send("Fetch.enable", {
+      patterns: patterns?.map((p) => ({
+        urlPattern: p.urlPattern ?? "*",
+        resourceType: p.resourceType,
+        requestStage: p.requestStage ?? "Request"
+      })) ?? [{ urlPattern: "*" }],
+      handleAuthRequests: true
+    });
+    this.enabled = true;
+  }
+  /**
+   * Disable request interception
+   */
+  async disable() {
+    if (!this.enabled) return;
+    await this.cdp.send("Fetch.disable");
+    this.cdp.off("Fetch.requestPaused", this.boundHandleRequestPaused);
+    this.cdp.off("Fetch.authRequired", this.boundHandleAuthRequired);
+    this.enabled = false;
+    this.handlers = [];
+    this.pendingRequests.clear();
+  }
+  /**
+   * Add a request handler
+   */
+  addHandler(pattern, handler) {
+    const entry = { pattern, handler };
+    this.handlers.push(entry);
+    return () => {
+      const idx = this.handlers.indexOf(entry);
+      if (idx !== -1) this.handlers.splice(idx, 1);
+    };
+  }
+  /**
+   * Handle paused request from CDP
+   */
+  async handleRequestPaused(params) {
+    const requestId = params["requestId"];
+    const request = params["request"];
+    const responseStatusCode = params["responseStatusCode"];
+    const responseHeaders = params["responseHeaders"];
+    const intercepted = {
+      requestId,
+      url: request["url"],
+      method: request["method"],
+      headers: request["headers"],
+      postData: request["postData"],
+      resourceType: params["resourceType"],
+      frameId: params["frameId"],
+      isNavigationRequest: params["isNavigationRequest"],
+      responseStatusCode,
+      responseHeaders: responseHeaders ? Object.fromEntries(responseHeaders.map((h) => [h.name, h.value])) : void 0
+    };
+    this.pendingRequests.set(requestId, { request: intercepted, handled: false });
+    const matchingHandler = this.handlers.find((h) => this.matchesPattern(intercepted, h.pattern));
+    if (matchingHandler) {
+      const actions = this.createActions(requestId);
+      try {
+        await matchingHandler.handler(intercepted, actions);
+      } catch (err) {
+        console.error("[RequestInterceptor] Handler error:", err);
+        if (!this.pendingRequests.get(requestId)?.handled) {
+          await actions.continue();
+        }
+      }
+    } else {
+      await this.continueRequest(requestId);
+    }
+    this.pendingRequests.delete(requestId);
+  }
+  /**
+   * Handle auth challenge
+   */
+  async handleAuthRequired(params) {
+    const requestId = params["requestId"];
+    await this.cdp.send("Fetch.continueWithAuth", {
+      requestId,
+      authChallengeResponse: { response: "CancelAuth" }
+    });
+  }
+  /**
+   * Check if request matches pattern
+   */
+  matchesPattern(request, pattern) {
+    if (pattern.resourceType && request.resourceType !== pattern.resourceType) {
+      return false;
+    }
+    if (pattern.urlPattern) {
+      const regex = this.globToRegex(pattern.urlPattern);
+      if (!regex.test(request.url)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Convert glob pattern to regex
+   */
+  globToRegex(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+  }
+  /**
+   * Create actions object for handler
+   */
+  createActions(requestId) {
+    const pending = this.pendingRequests.get(requestId);
+    const markHandled = () => {
+      if (pending) pending.handled = true;
+    };
+    return {
+      continue: async (options) => {
+        markHandled();
+        await this.continueRequest(requestId, options);
+      },
+      fulfill: async (options) => {
+        markHandled();
+        await this.fulfillRequest(requestId, options);
+      },
+      fail: async (options) => {
+        markHandled();
+        await this.failRequest(requestId, options);
+      }
+    };
+  }
+  /**
+   * Continue a paused request
+   */
+  async continueRequest(requestId, options) {
+    await this.cdp.send("Fetch.continueRequest", {
+      requestId,
+      url: options?.url,
+      method: options?.method,
+      headers: options?.headers ? Object.entries(options.headers).map(([name, value]) => ({ name, value })) : void 0,
+      postData: options?.postData ? btoa(options.postData) : void 0
+    });
+  }
+  /**
+   * Fulfill a request with custom response
+   */
+  async fulfillRequest(requestId, options) {
+    const headers = Object.entries(options.headers ?? {}).map(([name, value]) => ({
+      name,
+      value
+    }));
+    await this.cdp.send("Fetch.fulfillRequest", {
+      requestId,
+      responseCode: options.status,
+      responseHeaders: headers,
+      body: options.isBase64Encoded ? options.body : options.body ? btoa(options.body) : void 0
+    });
+  }
+  /**
+   * Fail/abort a request
+   */
+  async failRequest(requestId, options) {
+    await this.cdp.send("Fetch.failRequest", {
+      requestId,
+      errorReason: options?.reason ?? "BlockedByClient"
+    });
+  }
+};
+
+// src/wait/strategies.ts
+var DEEP_QUERY_SCRIPT = `
+function deepQuery(selector, root = document) {
+  // Try direct query first (fastest path)
+  let el = root.querySelector(selector);
+  if (el) return el;
+
+  // Search in shadow roots recursively
+  const searchShadows = (node) => {
+    // Check if this node has a shadow root
+    if (node.shadowRoot) {
+      el = node.shadowRoot.querySelector(selector);
+      if (el) return el;
+      // Search children of shadow root
+      for (const child of node.shadowRoot.querySelectorAll('*')) {
+        el = searchShadows(child);
+        if (el) return el;
+      }
+    }
+    // Search children that might have shadow roots
+    for (const child of node.querySelectorAll('*')) {
+      if (child.shadowRoot) {
+        el = searchShadows(child);
+        if (el) return el;
+      }
+    }
+    return null;
+  };
+
+  return searchShadows(root);
+}
+`;
+async function isElementVisible(cdp, selector, contextId) {
+  const params = {
+    expression: `(() => {
+      ${DEEP_QUERY_SCRIPT}
+      const el = deepQuery(${JSON.stringify(selector)});
+      if (!el) return false;
+      const style = getComputedStyle(el);
+      if (style.display === 'none') return false;
+      if (style.visibility === 'hidden') return false;
+      if (parseFloat(style.opacity) === 0) return false;
+      const rect = el.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0;
+    })()`,
+    returnByValue: true
+  };
+  if (contextId !== void 0) {
+    params["contextId"] = contextId;
+  }
+  const result = await cdp.send("Runtime.evaluate", params);
+  return result.result.value === true;
+}
+async function isElementAttached(cdp, selector, contextId) {
+  const params = {
+    expression: `(() => {
+      ${DEEP_QUERY_SCRIPT}
+      return deepQuery(${JSON.stringify(selector)}) !== null;
+    })()`,
+    returnByValue: true
+  };
+  if (contextId !== void 0) {
+    params["contextId"] = contextId;
+  }
+  const result = await cdp.send("Runtime.evaluate", params);
+  return result.result.value === true;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForAnyElement(cdp, selectors, options = {}) {
+  const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
+  const startTime = Date.now();
+  const deadline = startTime + timeout;
+  while (Date.now() < deadline) {
+    for (const selector of selectors) {
+      let conditionMet = false;
+      switch (state) {
+        case "visible":
+          conditionMet = await isElementVisible(cdp, selector, contextId);
+          break;
+        case "hidden":
+          conditionMet = !await isElementVisible(cdp, selector, contextId);
+          break;
+        case "attached":
+          conditionMet = await isElementAttached(cdp, selector, contextId);
+          break;
+        case "detached":
+          conditionMet = !await isElementAttached(cdp, selector, contextId);
+          break;
+      }
+      if (conditionMet) {
+        return { success: true, selector, waitedMs: Date.now() - startTime };
+      }
+    }
+    await sleep(pollInterval);
+  }
+  return { success: false, waitedMs: Date.now() - startTime };
+}
+async function getCurrentUrl(cdp) {
+  const result = await cdp.send("Runtime.evaluate", {
+    expression: "location.href",
+    returnByValue: true
+  });
+  return result.result.value;
+}
+async function waitForNavigation(cdp, options = {}) {
+  const { timeout = 3e4, allowSameDocument = true } = options;
+  const startTime = Date.now();
+  let startUrl;
+  try {
+    startUrl = await getCurrentUrl(cdp);
+  } catch {
+    startUrl = "";
+  }
+  return new Promise((resolve) => {
+    let resolved = false;
+    const cleanup = [];
+    const done = (success) => {
+      if (resolved) return;
+      resolved = true;
+      for (const fn of cleanup) fn();
+      resolve({ success, waitedMs: Date.now() - startTime });
+    };
+    const timer = setTimeout(() => done(false), timeout);
+    cleanup.push(() => clearTimeout(timer));
+    const onLoad = () => done(true);
+    cdp.on("Page.loadEventFired", onLoad);
+    cleanup.push(() => cdp.off("Page.loadEventFired", onLoad));
+    const onFrameNavigated = (params) => {
+      const frame = params["frame"];
+      if (frame && !frame.parentId && frame.url !== startUrl) {
+        done(true);
+      }
+    };
+    cdp.on("Page.frameNavigated", onFrameNavigated);
+    cleanup.push(() => cdp.off("Page.frameNavigated", onFrameNavigated));
+    if (allowSameDocument) {
+      const onSameDoc = () => done(true);
+      cdp.on("Page.navigatedWithinDocument", onSameDoc);
+      cleanup.push(() => cdp.off("Page.navigatedWithinDocument", onSameDoc));
+    }
+    const pollUrl = async () => {
+      while (!resolved && Date.now() < startTime + timeout) {
+        await sleep(100);
+        if (resolved) return;
+        try {
+          const currentUrl = await getCurrentUrl(cdp);
+          if (startUrl && currentUrl !== startUrl) {
+            done(true);
+            return;
+          }
+        } catch {
+        }
+      }
+    };
+    pollUrl();
+  });
+}
+async function waitForNetworkIdle(cdp, options = {}) {
+  const { timeout = 3e4, idleTime = 500 } = options;
+  const startTime = Date.now();
+  await cdp.send("Network.enable");
+  return new Promise((resolve) => {
+    let inFlight = 0;
+    let idleTimer = null;
+    const timeoutTimer = setTimeout(() => {
+      cleanup();
+      resolve({ success: false, waitedMs: Date.now() - startTime });
+    }, timeout);
+    const checkIdle = () => {
+      if (inFlight === 0) {
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+          cleanup();
+          resolve({ success: true, waitedMs: Date.now() - startTime });
+        }, idleTime);
+      }
+    };
+    const onRequestStart = () => {
+      inFlight++;
+      if (idleTimer) {
+        clearTimeout(idleTimer);
+        idleTimer = null;
+      }
+    };
+    const onRequestEnd = () => {
+      inFlight = Math.max(0, inFlight - 1);
+      checkIdle();
+    };
+    const cleanup = () => {
+      clearTimeout(timeoutTimer);
+      if (idleTimer) clearTimeout(idleTimer);
+      cdp.off("Network.requestWillBeSent", onRequestStart);
+      cdp.off("Network.loadingFinished", onRequestEnd);
+      cdp.off("Network.loadingFailed", onRequestEnd);
+    };
+    cdp.on("Network.requestWillBeSent", onRequestStart);
+    cdp.on("Network.loadingFinished", onRequestEnd);
+    cdp.on("Network.loadingFailed", onRequestEnd);
+    checkIdle();
+  });
+}
+
+// src/browser/types.ts
+var ElementNotFoundError = class extends Error {
+  selectors;
+  constructor(selectors) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    super(`Element not found: ${selectorList.join(", ")}`);
+    this.name = "ElementNotFoundError";
+    this.selectors = selectorList;
+  }
+};
+var TimeoutError = class extends Error {
+  constructor(message = "Operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+
+// src/browser/page.ts
+var DEFAULT_TIMEOUT2 = 3e4;
+var Page = class {
+  cdp;
+  rootNodeId = null;
+  batchExecutor;
+  emulationState = {};
+  interceptor = null;
+  consoleHandlers = /* @__PURE__ */ new Set();
+  errorHandlers = /* @__PURE__ */ new Set();
+  dialogHandler = null;
+  consoleEnabled = false;
+  /** Map of ref (e.g., "e4") to backendNodeId for ref-based selectors */
+  refMap = /* @__PURE__ */ new Map();
+  /** Current frame context (null = main frame) */
+  currentFrame = null;
+  /** Stored frame document node IDs for context switching */
+  frameContexts = /* @__PURE__ */ new Map();
+  /** Map of frameId → executionContextId for JS evaluation in frames */
+  frameExecutionContexts = /* @__PURE__ */ new Map();
+  /** Current frame's execution context ID (null = main frame default) */
+  currentFrameContextId = null;
+  constructor(cdp) {
+    this.cdp = cdp;
+    this.batchExecutor = new BatchExecutor(this);
+  }
+  /**
+   * Initialize the page (enable required CDP domains)
+   */
+  async init() {
+    this.cdp.on("Runtime.executionContextCreated", (params) => {
+      const context = params["context"];
+      if (context.auxData?.frameId && context.auxData?.isDefault) {
+        this.frameExecutionContexts.set(context.auxData.frameId, context.id);
+      }
+    });
+    this.cdp.on("Runtime.executionContextDestroyed", (params) => {
+      const contextId = params["executionContextId"];
+      for (const [frameId, ctxId] of this.frameExecutionContexts.entries()) {
+        if (ctxId === contextId) {
+          this.frameExecutionContexts.delete(frameId);
+          break;
+        }
+      }
+    });
+    this.cdp.on("Page.javascriptDialogOpening", this.handleDialogOpening.bind(this));
+    await Promise.all([
+      this.cdp.send("Page.enable"),
+      this.cdp.send("DOM.enable"),
+      this.cdp.send("Runtime.enable"),
+      this.cdp.send("Network.enable")
+    ]);
+  }
+  // ============ Navigation ============
+  /**
+   * Navigate to a URL
+   */
+  async goto(url, options = {}) {
+    const { timeout = DEFAULT_TIMEOUT2 } = options;
+    const navPromise = this.waitForNavigation({ timeout });
+    await this.cdp.send("Page.navigate", { url });
+    const result = await navPromise;
+    if (!result) {
+      throw new TimeoutError(`Navigation to ${url} timed out after ${timeout}ms`);
+    }
+    this.rootNodeId = null;
+    this.refMap.clear();
+  }
+  /**
+   * Get the current URL
+   */
+  async url() {
+    const result = await this.cdp.send("Runtime.evaluate", {
+      expression: "location.href",
+      returnByValue: true
+    });
+    return result.result.value;
+  }
+  /**
+   * Get the page title
+   */
+  async title() {
+    const result = await this.cdp.send("Runtime.evaluate", {
+      expression: "document.title",
+      returnByValue: true
+    });
+    return result.result.value;
+  }
+  /**
+   * Reload the page
+   */
+  async reload(options = {}) {
+    const { timeout = DEFAULT_TIMEOUT2 } = options;
+    const navPromise = this.waitForNavigation({ timeout });
+    await this.cdp.send("Page.reload");
+    await navPromise;
+    this.rootNodeId = null;
+    this.refMap.clear();
+  }
+  /**
+   * Go back in history
+   */
+  async goBack(options = {}) {
+    const { timeout = DEFAULT_TIMEOUT2 } = options;
+    const history = await this.cdp.send("Page.getNavigationHistory");
+    if (history.currentIndex <= 0) {
+      return;
+    }
+    const navPromise = this.waitForNavigation({ timeout });
+    await this.cdp.send("Page.navigateToHistoryEntry", {
+      entryId: history.entries[history.currentIndex - 1].id
+    });
+    await navPromise;
+    this.rootNodeId = null;
+    this.refMap.clear();
+  }
+  /**
+   * Go forward in history
+   */
+  async goForward(options = {}) {
+    const { timeout = DEFAULT_TIMEOUT2 } = options;
+    const history = await this.cdp.send("Page.getNavigationHistory");
+    if (history.currentIndex >= history.entries.length - 1) {
+      return;
+    }
+    const navPromise = this.waitForNavigation({ timeout });
+    await this.cdp.send("Page.navigateToHistoryEntry", {
+      entryId: history.entries[history.currentIndex + 1].id
+    });
+    await navPromise;
+    this.rootNodeId = null;
+    this.refMap.clear();
+  }
+  // ============ Core Actions ============
+  /**
+   * Click an element (supports multi-selector)
+   *
+   * Uses CDP mouse events for regular elements. For form submit buttons,
+   * uses dispatchEvent to reliably trigger form submission in headless Chrome.
+   */
+  async click(selector, options = {}) {
+    return this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        throw new ElementNotFoundError(selector);
+      }
+      await this.scrollIntoView(element.nodeId);
+      const submitResult = await this.evaluateInFrame(
+        `(() => {
+          const el = document.querySelector(${JSON.stringify(element.selector)});
+          if (!el) return { isSubmit: false };
+
+          // Check if this is a form submit button
+          const isSubmitButton = (el instanceof HTMLButtonElement && (el.type === 'submit' || (el.form && el.type !== 'button'))) ||
+                                 (el instanceof HTMLInputElement && el.type === 'submit');
+
+          if (isSubmitButton && el.form) {
+            // Dispatch submit event directly - works reliably in headless Chrome
+            el.form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+            return { isSubmit: true };
+          }
+          return { isSubmit: false };
+        })()`
+      );
+      const isSubmit = submitResult.result.value?.isSubmit;
+      if (!isSubmit) {
+        await this.clickElement(element.nodeId);
+      }
+      return true;
+    });
+  }
+  /**
+   * Fill an input field (clears first by default)
+   */
+  async fill(selector, value, options = {}) {
+    const { clear = true } = options;
+    return this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        throw new ElementNotFoundError(selector);
+      }
+      await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
+      if (clear) {
+        await this.evaluateInFrame(
+          `(() => {
+            const el = document.querySelector(${JSON.stringify(element.selector)});
+            if (el) {
+              el.value = '';
+              el.dispatchEvent(new Event('input', { bubbles: true }));
+            }
+          })()`
+        );
+      }
+      await this.cdp.send("Input.insertText", { text: value });
+      await this.evaluateInFrame(
+        `(() => {
+          const el = document.querySelector(${JSON.stringify(element.selector)});
+          if (el) {
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new Event('change', { bubbles: true }));
+          }
+        })()`
+      );
+      return true;
+    });
+  }
+  /**
+   * Type text character by character (for autocomplete fields, etc.)
+   */
+  async type(selector, text, options = {}) {
+    const { delay = 50 } = options;
+    const element = await this.findElement(selector, options);
+    if (!element) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(selector);
+    }
+    await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
+    for (const char of text) {
+      await this.cdp.send("Input.dispatchKeyEvent", {
+        type: "keyDown",
+        key: char,
+        text: char
+      });
+      await this.cdp.send("Input.dispatchKeyEvent", {
+        type: "keyUp",
+        key: char
+      });
+      if (delay > 0) {
+        await sleep2(delay);
+      }
+    }
+    return true;
+  }
+  async select(selectorOrConfig, valueOrOptions, maybeOptions) {
+    if (typeof selectorOrConfig === "object" && !Array.isArray(selectorOrConfig) && "trigger" in selectorOrConfig) {
+      return this.selectCustom(selectorOrConfig, valueOrOptions);
+    }
+    const selector = selectorOrConfig;
+    const value = valueOrOptions;
+    const options = maybeOptions ?? {};
+    const element = await this.findElement(selector, options);
+    if (!element) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(selector);
+    }
+    const values = Array.isArray(value) ? value : [value];
+    await this.cdp.send("Runtime.evaluate", {
+      expression: `(() => {
+        const el = document.querySelector(${JSON.stringify(element.selector)});
+        if (!el || el.tagName !== 'SELECT') return false;
+        const values = ${JSON.stringify(values)};
+        for (const opt of el.options) {
+          opt.selected = values.includes(opt.value) || values.includes(opt.text);
+        }
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+        return true;
+      })()`,
+      returnByValue: true
+    });
+    return true;
+  }
+  /**
+   * Handle custom (non-native) select/dropdown components
+   */
+  async selectCustom(config, options = {}) {
+    const { trigger, option, value, match = "text" } = config;
+    await this.click(trigger, options);
+    await sleep2(100);
+    let optionSelector;
+    const optionSelectors = Array.isArray(option) ? option : [option];
+    if (match === "contains") {
+      optionSelector = optionSelectors.map((s) => `${s}:has-text("${value}")`).join(", ");
+    } else if (match === "value") {
+      optionSelector = optionSelectors.map((s) => `${s}[data-value="${value}"], ${s}[value="${value}"]`).join(", ");
+    } else {
+      optionSelector = optionSelectors.map((s) => `${s}`).join(", ");
+    }
+    const result = await this.cdp.send("Runtime.evaluate", {
+      expression: `(() => {
+        const options = document.querySelectorAll(${JSON.stringify(optionSelector)});
+        for (const opt of options) {
+          const text = opt.textContent?.trim();
+          if (${match === "text" ? `text === ${JSON.stringify(value)}` : match === "contains" ? `text?.includes(${JSON.stringify(value)})` : "true"}) {
+            opt.click();
+            return true;
+          }
+        }
+        return false;
+      })()`,
+      returnByValue: true
+    });
+    if (!result.result.value) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(`Option with ${match} "${value}"`);
+    }
+    return true;
+  }
+  /**
+   * Check a checkbox or radio button
+   */
+  async check(selector, options = {}) {
+    const element = await this.findElement(selector, options);
+    if (!element) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(selector);
+    }
+    const result = await this.cdp.send("Runtime.evaluate", {
+      expression: `(() => {
+        const el = document.querySelector(${JSON.stringify(element.selector)});
+        if (!el) return false;
+        if (!el.checked) el.click();
+        return true;
+      })()`,
+      returnByValue: true
+    });
+    return result.result.value;
+  }
+  /**
+   * Uncheck a checkbox
+   */
+  async uncheck(selector, options = {}) {
+    const element = await this.findElement(selector, options);
+    if (!element) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(selector);
+    }
+    const result = await this.cdp.send("Runtime.evaluate", {
+      expression: `(() => {
+        const el = document.querySelector(${JSON.stringify(element.selector)});
+        if (!el) return false;
+        if (el.checked) el.click();
+        return true;
+      })()`,
+      returnByValue: true
+    });
+    return result.result.value;
+  }
+  /**
+   * Submit a form (tries Enter key first, then click)
+   *
+   * Navigation waiting behavior:
+   * - 'auto' (default): Attempt to detect navigation for 1 second, then assume client-side handling
+   * - true: Wait for full navigation (traditional forms)
+   * - false: Return immediately (AJAX forms where you'll wait for something else)
+   */
+  async submit(selector, options = {}) {
+    const { method = "enter+click", waitForNavigation: shouldWait = "auto" } = options;
+    const element = await this.findElement(selector, options);
+    if (!element) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(selector);
+    }
+    await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
+    if (method.includes("enter")) {
+      await this.press("Enter");
+      if (shouldWait === true) {
+        try {
+          await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_TIMEOUT2 });
+          return true;
+        } catch {
+        }
+      } else if (shouldWait === "auto") {
+        const navigationDetected = await Promise.race([
+          this.waitForNavigation({ timeout: 1e3, optional: true }).then(
+            (success) => success ? "nav" : null
+          ),
+          sleep2(500).then(() => "timeout")
+        ]);
+        if (navigationDetected === "nav") {
+          return true;
+        }
+      } else {
+        if (method === "enter") return true;
+      }
+    }
+    if (method.includes("click")) {
+      await this.click(element.selector, { ...options, optional: false });
+      if (shouldWait === true) {
+        await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_TIMEOUT2 });
+      } else if (shouldWait === "auto") {
+        await sleep2(100);
+      }
+    }
+    return true;
+  }
+  /**
+   * Press a key
+   */
+  async press(key) {
+    const keyMap = {
+      Enter: { key: "Enter", code: "Enter", keyCode: 13 },
+      Tab: { key: "Tab", code: "Tab", keyCode: 9 },
+      Escape: { key: "Escape", code: "Escape", keyCode: 27 },
+      Backspace: { key: "Backspace", code: "Backspace", keyCode: 8 },
+      Delete: { key: "Delete", code: "Delete", keyCode: 46 },
+      ArrowUp: { key: "ArrowUp", code: "ArrowUp", keyCode: 38 },
+      ArrowDown: { key: "ArrowDown", code: "ArrowDown", keyCode: 40 },
+      ArrowLeft: { key: "ArrowLeft", code: "ArrowLeft", keyCode: 37 },
+      ArrowRight: { key: "ArrowRight", code: "ArrowRight", keyCode: 39 }
+    };
+    const keyInfo = keyMap[key] ?? { key, code: key, keyCode: 0 };
+    await this.cdp.send("Input.dispatchKeyEvent", {
+      type: "keyDown",
+      key: keyInfo.key,
+      code: keyInfo.code,
+      windowsVirtualKeyCode: keyInfo.keyCode
+    });
+    await this.cdp.send("Input.dispatchKeyEvent", {
+      type: "keyUp",
+      key: keyInfo.key,
+      code: keyInfo.code,
+      windowsVirtualKeyCode: keyInfo.keyCode
+    });
+  }
+  /**
+   * Focus an element
+   */
+  async focus(selector, options = {}) {
+    const element = await this.findElement(selector, options);
+    if (!element) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(selector);
+    }
+    await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
+    return true;
+  }
+  /**
+   * Hover over an element
+   */
+  async hover(selector, options = {}) {
+    return this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        throw new ElementNotFoundError(selector);
+      }
+      await this.scrollIntoView(element.nodeId);
+      const box = await this.getBoxModel(element.nodeId);
+      if (!box) {
+        if (options.optional) return false;
+        throw new Error("Could not get element box model");
+      }
+      const x = box.content[0] + box.width / 2;
+      const y = box.content[1] + box.height / 2;
+      await this.cdp.send("Input.dispatchMouseEvent", {
+        type: "mouseMoved",
+        x,
+        y
+      });
+      return true;
+    });
+  }
+  /**
+   * Scroll an element into view (or scroll to coordinates)
+   */
+  async scroll(selector, options = {}) {
+    const { x, y } = options;
+    if (x !== void 0 || y !== void 0) {
+      await this.cdp.send("Runtime.evaluate", {
+        expression: `window.scrollTo(${x ?? 0}, ${y ?? 0})`
+      });
+      return true;
+    }
+    const element = await this.findElement(selector, options);
+    if (!element) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(selector);
+    }
+    await this.scrollIntoView(element.nodeId);
+    return true;
+  }
+  // ============ Frame Navigation ============
+  /**
+   * Switch context to an iframe for subsequent actions
+   * @param selector - Selector for the iframe element
+   * @param options - Optional timeout and optional flags
+   * @returns true if switch succeeded
+   */
+  async switchToFrame(selector, options = {}) {
+    const element = await this.findElement(selector, options);
+    if (!element) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(selector);
+    }
+    const descResult = await this.cdp.send("DOM.describeNode", {
+      nodeId: element.nodeId,
+      depth: 1
+    });
+    if (!descResult.node.contentDocument) {
+      if (options.optional) return false;
+      throw new Error(
+        "Cannot access iframe content. This may be a cross-origin iframe which requires different handling."
+      );
+    }
+    const frameKey = Array.isArray(selector) ? selector[0] : selector;
+    this.frameContexts.set(frameKey, descResult.node.contentDocument.nodeId);
+    this.currentFrame = frameKey;
+    this.rootNodeId = descResult.node.contentDocument.nodeId;
+    if (descResult.node.frameId) {
+      let contextId = this.frameExecutionContexts.get(descResult.node.frameId);
+      if (!contextId) {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        contextId = this.frameExecutionContexts.get(descResult.node.frameId);
+      }
+      if (contextId) {
+        this.currentFrameContextId = contextId;
+      }
+    }
+    this.refMap.clear();
+    return true;
+  }
+  /**
+   * Switch back to the main document from an iframe
+   */
+  async switchToMain() {
+    this.currentFrame = null;
+    this.rootNodeId = null;
+    this.currentFrameContextId = null;
+    this.refMap.clear();
+  }
+  /**
+   * Get the current frame context (null = main frame)
+   */
+  getCurrentFrame() {
+    return this.currentFrame;
+  }
+  // ============ Waiting ============
+  /**
+   * Wait for an element to reach a state
+   */
+  async waitFor(selector, options = {}) {
+    const { timeout = DEFAULT_TIMEOUT2, state = "visible" } = options;
+    const selectors = Array.isArray(selector) ? selector : [selector];
+    const result = await waitForAnyElement(this.cdp, selectors, {
+      state,
+      timeout,
+      contextId: this.currentFrameContextId ?? void 0
+    });
+    if (!result.success && !options.optional) {
+      throw new TimeoutError(`Timeout waiting for ${selectors.join(" or ")} to be ${state}`);
+    }
+    return result.success;
+  }
+  /**
+   * Wait for navigation to complete
+   */
+  async waitForNavigation(options = {}) {
+    const { timeout = DEFAULT_TIMEOUT2 } = options;
+    const result = await waitForNavigation(this.cdp, { timeout });
+    if (!result.success && !options.optional) {
+      throw new TimeoutError("Navigation timeout");
+    }
+    this.rootNodeId = null;
+    this.refMap.clear();
+    return result.success;
+  }
+  /**
+   * Wait for network to be idle
+   */
+  async waitForNetworkIdle(options = {}) {
+    const { timeout = DEFAULT_TIMEOUT2, idleTime = 500 } = options;
+    const result = await waitForNetworkIdle(this.cdp, { timeout, idleTime });
+    if (!result.success && !options.optional) {
+      throw new TimeoutError("Network idle timeout");
+    }
+    return result.success;
+  }
+  // ============ JavaScript Execution ============
+  /**
+   * Evaluate JavaScript in the page context (or current frame context if in iframe)
+   */
+  async evaluate(expression, ...args) {
+    let script;
+    if (typeof expression === "function") {
+      const argString = args.map((a) => JSON.stringify(a)).join(", ");
+      script = `(${expression.toString()})(${argString})`;
+    } else {
+      script = expression;
+    }
+    const params = {
+      expression: script,
+      returnByValue: true,
+      awaitPromise: true
+    };
+    if (this.currentFrameContextId !== null) {
+      params["contextId"] = this.currentFrameContextId;
+    }
+    const result = await this.cdp.send("Runtime.evaluate", params);
+    if (result.exceptionDetails) {
+      throw new Error(`Evaluation failed: ${result.exceptionDetails.text}`);
+    }
+    return result.result.value;
+  }
+  // ============ Screenshots ============
+  /**
+   * Take a screenshot
+   */
+  async screenshot(options = {}) {
+    const { format = "png", quality, fullPage = false } = options;
+    let clip;
+    if (fullPage) {
+      const metrics = await this.cdp.send("Page.getLayoutMetrics");
+      clip = {
+        x: 0,
+        y: 0,
+        width: metrics.contentSize.width,
+        height: metrics.contentSize.height,
+        scale: 1
+      };
+    }
+    const result = await this.cdp.send("Page.captureScreenshot", {
+      format,
+      quality: format === "png" ? void 0 : quality,
+      clip,
+      captureBeyondViewport: fullPage
+    });
+    return result.data;
+  }
+  // ============ Text Extraction ============
+  /**
+   * Get text content from the page or a specific element
+   */
+  async text(selector) {
+    const expression = selector ? `document.querySelector(${JSON.stringify(selector)})?.innerText ?? ''` : "document.body.innerText";
+    const result = await this.evaluateInFrame(expression);
+    return result.result.value ?? "";
+  }
+  // ============ File Handling ============
+  /**
+   * Set files on a file input
+   */
+  async setInputFiles(selector, files, options = {}) {
+    const element = await this.findElement(selector, options);
+    if (!element) {
+      if (options.optional) return false;
+      throw new ElementNotFoundError(selector);
+    }
+    const fileData = await Promise.all(
+      files.map(async (f) => {
+        let base64;
+        if (typeof f.buffer === "string") {
+          base64 = f.buffer;
+        } else {
+          const bytes = new Uint8Array(f.buffer);
+          base64 = btoa(String.fromCharCode(...bytes));
+        }
+        return { name: f.name, mimeType: f.mimeType, data: base64 };
+      })
+    );
+    await this.cdp.send("Runtime.evaluate", {
+      expression: `(() => {
+        const input = document.querySelector(${JSON.stringify(element.selector)});
+        if (!input) return false;
+
+        const files = ${JSON.stringify(fileData)};
+        const dt = new DataTransfer();
+
+        for (const f of files) {
+          const bytes = Uint8Array.from(atob(f.data), c => c.charCodeAt(0));
+          const file = new File([bytes], f.name, { type: f.mimeType });
+          dt.items.add(file);
+        }
+
+        input.files = dt.files;
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+        return true;
+      })()`,
+      returnByValue: true
+    });
+    return true;
+  }
+  /**
+   * Wait for a download to complete, triggered by an action
+   */
+  async waitForDownload(trigger, options = {}) {
+    const { timeout = DEFAULT_TIMEOUT2 } = options;
+    await this.cdp.send("Browser.setDownloadBehavior", {
+      behavior: "allowAndName",
+      eventsEnabled: true
+    });
+    return new Promise((resolve, reject) => {
+      let downloadGuid;
+      let suggestedFilename;
+      let resolved = false;
+      const timeoutTimer = setTimeout(() => {
+        if (!resolved) {
+          cleanup();
+          reject(new TimeoutError(`Download timed out after ${timeout}ms`));
+        }
+      }, timeout);
+      const onDownloadWillBegin = (params) => {
+        downloadGuid = params["guid"];
+        suggestedFilename = params["suggestedFilename"];
+      };
+      const onDownloadProgress = (params) => {
+        if (params["guid"] === downloadGuid && params["state"] === "completed") {
+          resolved = true;
+          cleanup();
+          const download = {
+            filename: suggestedFilename ?? "unknown",
+            content: async () => {
+              return new ArrayBuffer(0);
+            }
+          };
+          resolve(download);
+        } else if (params["guid"] === downloadGuid && params["state"] === "canceled") {
+          resolved = true;
+          cleanup();
+          reject(new Error("Download was canceled"));
+        }
+      };
+      const cleanup = () => {
+        clearTimeout(timeoutTimer);
+        this.cdp.off("Browser.downloadWillBegin", onDownloadWillBegin);
+        this.cdp.off("Browser.downloadProgress", onDownloadProgress);
+      };
+      this.cdp.on("Browser.downloadWillBegin", onDownloadWillBegin);
+      this.cdp.on("Browser.downloadProgress", onDownloadProgress);
+      trigger().catch((err) => {
+        if (!resolved) {
+          resolved = true;
+          cleanup();
+          reject(err);
+        }
+      });
+    });
+  }
+  // ============ Snapshot ============
+  /**
+   * Get an accessibility tree snapshot of the page
+   */
+  async snapshot() {
+    const [url, title, axTree] = await Promise.all([
+      this.url(),
+      this.title(),
+      this.cdp.send("Accessibility.getFullAXTree")
+    ]);
+    const nodes = axTree.nodes.filter((n) => !n.ignored);
+    const nodeMap = new Map(nodes.map((n) => [n.nodeId, n]));
+    let refCounter = 0;
+    const nodeRefs = /* @__PURE__ */ new Map();
+    this.refMap.clear();
+    for (const node of nodes) {
+      const ref = `e${++refCounter}`;
+      nodeRefs.set(node.nodeId, ref);
+      if (node.backendDOMNodeId !== void 0) {
+        this.refMap.set(ref, node.backendDOMNodeId);
+      }
+    }
+    const buildNode = (nodeId) => {
+      const node = nodeMap.get(nodeId);
+      if (!node) return null;
+      const role = node.role?.value ?? "generic";
+      const name = node.name?.value;
+      const value = node.value?.value;
+      const ref = nodeRefs.get(nodeId);
+      const children = [];
+      if (node.childIds) {
+        for (const childId of node.childIds) {
+          const child = buildNode(childId);
+          if (child) children.push(child);
+        }
+      }
+      const disabled = node.properties?.find((p) => p.name === "disabled")?.value.value;
+      const checked = node.properties?.find((p) => p.name === "checked")?.value.value;
+      return {
+        role,
+        name,
+        value,
+        ref,
+        children: children.length > 0 ? children : void 0,
+        disabled,
+        checked
+      };
+    };
+    const rootNodes = nodes.filter((n) => !n.parentId || !nodeMap.has(n.parentId));
+    const accessibilityTree = rootNodes.map((n) => buildNode(n.nodeId)).filter((n) => n !== null);
+    const interactiveRoles = /* @__PURE__ */ new Set([
+      "button",
+      "link",
+      "textbox",
+      "checkbox",
+      "radio",
+      "combobox",
+      "listbox",
+      "menuitem",
+      "menuitemcheckbox",
+      "menuitemradio",
+      "option",
+      "searchbox",
+      "slider",
+      "spinbutton",
+      "switch",
+      "tab",
+      "treeitem"
+    ]);
+    const interactiveElements = [];
+    for (const node of nodes) {
+      const role = node.role?.value;
+      if (role && interactiveRoles.has(role)) {
+        const ref = nodeRefs.get(node.nodeId);
+        const name = node.name?.value ?? "";
+        const disabled = node.properties?.find((p) => p.name === "disabled")?.value.value;
+        const selector = node.backendDOMNodeId ? `[data-backend-node-id="${node.backendDOMNodeId}"]` : `[aria-label="${name}"]`;
+        interactiveElements.push({
+          ref,
+          role,
+          name,
+          selector,
+          disabled
+        });
+      }
+    }
+    const formatTree = (nodes2, depth = 0) => {
+      const lines = [];
+      for (const node of nodes2) {
+        let line = `${"  ".repeat(depth)}- ${node.role}`;
+        if (node.name) line += ` "${node.name}"`;
+        line += ` [ref=${node.ref}]`;
+        if (node.disabled) line += " (disabled)";
+        if (node.checked !== void 0) line += node.checked ? " (checked)" : " (unchecked)";
+        lines.push(line);
+        if (node.children) {
+          lines.push(formatTree(node.children, depth + 1));
+        }
+      }
+      return lines.join("\n");
+    };
+    const text = formatTree(accessibilityTree);
+    return {
+      url,
+      title,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      accessibilityTree,
+      interactiveElements,
+      text
+    };
+  }
+  // ============ Batch Execution ============
+  /**
+   * Execute a batch of steps
+   */
+  async batch(steps, options) {
+    return this.batchExecutor.execute(steps, options);
+  }
+  // ============ Emulation ============
+  /**
+   * Set the viewport size and device metrics
+   */
+  async setViewport(options) {
+    const {
+      width,
+      height,
+      deviceScaleFactor = 1,
+      isMobile = false,
+      hasTouch = false,
+      isLandscape = false
+    } = options;
+    await this.cdp.send("Emulation.setDeviceMetricsOverride", {
+      width,
+      height,
+      deviceScaleFactor,
+      mobile: isMobile,
+      screenWidth: width,
+      screenHeight: height,
+      screenOrientation: {
+        type: isLandscape ? "landscapePrimary" : "portraitPrimary",
+        angle: isLandscape ? 90 : 0
+      }
+    });
+    if (hasTouch) {
+      await this.cdp.send("Emulation.setTouchEmulationEnabled", {
+        enabled: true,
+        maxTouchPoints: 5
+      });
+    }
+    this.emulationState.viewport = options;
+  }
+  /**
+   * Clear viewport override, return to default
+   */
+  async clearViewport() {
+    await this.cdp.send("Emulation.clearDeviceMetricsOverride");
+    await this.cdp.send("Emulation.setTouchEmulationEnabled", { enabled: false });
+    this.emulationState.viewport = void 0;
+  }
+  /**
+   * Set the user agent string and optional metadata
+   */
+  async setUserAgent(options) {
+    const opts = typeof options === "string" ? { userAgent: options } : options;
+    await this.cdp.send("Emulation.setUserAgentOverride", {
+      userAgent: opts.userAgent,
+      acceptLanguage: opts.acceptLanguage,
+      platform: opts.platform,
+      userAgentMetadata: opts.userAgentMetadata
+    });
+    this.emulationState.userAgent = opts;
+  }
+  /**
+   * Set geolocation coordinates
+   */
+  async setGeolocation(options) {
+    const { latitude, longitude, accuracy = 1 } = options;
+    await this.cdp.send("Browser.grantPermissions", {
+      permissions: ["geolocation"]
+    });
+    await this.cdp.send("Emulation.setGeolocationOverride", {
+      latitude,
+      longitude,
+      accuracy
+    });
+    this.emulationState.geolocation = options;
+  }
+  /**
+   * Clear geolocation override
+   */
+  async clearGeolocation() {
+    await this.cdp.send("Emulation.clearGeolocationOverride");
+    this.emulationState.geolocation = void 0;
+  }
+  /**
+   * Set timezone override
+   */
+  async setTimezone(timezoneId) {
+    await this.cdp.send("Emulation.setTimezoneOverride", { timezoneId });
+    this.emulationState.timezone = timezoneId;
+  }
+  /**
+   * Set locale override
+   */
+  async setLocale(locale) {
+    await this.cdp.send("Emulation.setLocaleOverride", { locale });
+    this.emulationState.locale = locale;
+  }
+  /**
+   * Emulate a specific device
+   */
+  async emulate(device) {
+    await this.setViewport(device.viewport);
+    await this.setUserAgent(device.userAgent);
+  }
+  /**
+   * Get current emulation state
+   */
+  getEmulationState() {
+    return { ...this.emulationState };
+  }
+  // ============ Request Interception ============
+  /**
+   * Add request interception handler
+   * @param pattern URL pattern or resource type to match
+   * @param handler Handler function for matched requests
+   * @returns Unsubscribe function
+   */
+  async intercept(pattern, handler) {
+    if (!this.interceptor) {
+      this.interceptor = new RequestInterceptor(this.cdp);
+      await this.interceptor.enable();
+    }
+    const normalizedPattern = typeof pattern === "string" ? { urlPattern: pattern } : pattern;
+    return this.interceptor.addHandler(normalizedPattern, handler);
+  }
+  /**
+   * Route requests matching pattern to a mock response
+   * Convenience wrapper around intercept()
+   */
+  async route(urlPattern, options) {
+    return this.intercept({ urlPattern }, async (_request, actions) => {
+      let body = options.body;
+      const headers = { ...options.headers };
+      if (typeof body === "object") {
+        body = JSON.stringify(body);
+        headers["content-type"] ??= "application/json";
+      }
+      if (options.contentType) {
+        headers["content-type"] = options.contentType;
+      }
+      await actions.fulfill({
+        status: options.status ?? 200,
+        headers,
+        body
+      });
+    });
+  }
+  /**
+   * Block requests matching resource types
+   */
+  async blockResources(types) {
+    return this.intercept({}, async (request, actions) => {
+      if (types.includes(request.resourceType)) {
+        await actions.fail({ reason: "BlockedByClient" });
+      } else {
+        await actions.continue();
+      }
+    });
+  }
+  /**
+   * Disable all request interception
+   */
+  async disableInterception() {
+    if (this.interceptor) {
+      await this.interceptor.disable();
+      this.interceptor = null;
+    }
+  }
+  // ============ Cookies & Storage ============
+  /**
+   * Get all cookies for the current page
+   */
+  async cookies(urls) {
+    const targetUrls = urls ?? [await this.url()];
+    const result = await this.cdp.send("Network.getCookies", {
+      urls: targetUrls
+    });
+    return result.cookies;
+  }
+  /**
+   * Set a cookie
+   */
+  async setCookie(options) {
+    const { name, value, domain, path = "/", expires, httpOnly, secure, sameSite, url } = options;
+    let expireTime;
+    if (expires instanceof Date) {
+      expireTime = Math.floor(expires.getTime() / 1e3);
+    } else if (typeof expires === "number") {
+      expireTime = expires;
+    }
+    const result = await this.cdp.send("Network.setCookie", {
+      name,
+      value,
+      domain,
+      path,
+      expires: expireTime,
+      httpOnly,
+      secure,
+      sameSite,
+      url: url ?? (domain ? void 0 : await this.url())
+    });
+    return result.success;
+  }
+  /**
+   * Set multiple cookies
+   */
+  async setCookies(cookies) {
+    for (const cookie of cookies) {
+      await this.setCookie(cookie);
+    }
+  }
+  /**
+   * Delete a specific cookie
+   */
+  async deleteCookie(options) {
+    const { name, domain, path, url } = options;
+    await this.cdp.send("Network.deleteCookies", {
+      name,
+      domain,
+      path,
+      url: url ?? (domain ? void 0 : await this.url())
+    });
+  }
+  /**
+   * Delete multiple cookies
+   */
+  async deleteCookies(cookies) {
+    for (const cookie of cookies) {
+      await this.deleteCookie(cookie);
+    }
+  }
+  /**
+   * Clear all cookies
+   */
+  async clearCookies(options) {
+    if (options?.domain) {
+      const domainCookies = await this.cookies([`https://${options.domain}`]);
+      for (const cookie of domainCookies) {
+        await this.deleteCookie({
+          name: cookie.name,
+          domain: cookie.domain,
+          path: cookie.path
+        });
+      }
+    } else {
+      await this.cdp.send("Storage.clearCookies", {});
+    }
+  }
+  /**
+   * Get localStorage value
+   */
+  async getLocalStorage(key) {
+    const result = await this.cdp.send("Runtime.evaluate", {
+      expression: `localStorage.getItem(${JSON.stringify(key)})`,
+      returnByValue: true
+    });
+    return result.result.value;
+  }
+  /**
+   * Set localStorage value
+   */
+  async setLocalStorage(key, value) {
+    await this.cdp.send("Runtime.evaluate", {
+      expression: `localStorage.setItem(${JSON.stringify(key)}, ${JSON.stringify(value)})`
+    });
+  }
+  /**
+   * Remove localStorage item
+   */
+  async removeLocalStorage(key) {
+    await this.cdp.send("Runtime.evaluate", {
+      expression: `localStorage.removeItem(${JSON.stringify(key)})`
+    });
+  }
+  /**
+   * Clear localStorage
+   */
+  async clearLocalStorage() {
+    await this.cdp.send("Runtime.evaluate", {
+      expression: "localStorage.clear()"
+    });
+  }
+  /**
+   * Get sessionStorage value
+   */
+  async getSessionStorage(key) {
+    const result = await this.cdp.send("Runtime.evaluate", {
+      expression: `sessionStorage.getItem(${JSON.stringify(key)})`,
+      returnByValue: true
+    });
+    return result.result.value;
+  }
+  /**
+   * Set sessionStorage value
+   */
+  async setSessionStorage(key, value) {
+    await this.cdp.send("Runtime.evaluate", {
+      expression: `sessionStorage.setItem(${JSON.stringify(key)}, ${JSON.stringify(value)})`
+    });
+  }
+  /**
+   * Remove sessionStorage item
+   */
+  async removeSessionStorage(key) {
+    await this.cdp.send("Runtime.evaluate", {
+      expression: `sessionStorage.removeItem(${JSON.stringify(key)})`
+    });
+  }
+  /**
+   * Clear sessionStorage
+   */
+  async clearSessionStorage() {
+    await this.cdp.send("Runtime.evaluate", {
+      expression: "sessionStorage.clear()"
+    });
+  }
+  // ============ Console & Errors ============
+  /**
+   * Enable console message capture
+   */
+  async enableConsole() {
+    if (this.consoleEnabled) return;
+    this.cdp.on("Runtime.consoleAPICalled", this.handleConsoleMessage.bind(this));
+    this.cdp.on("Runtime.exceptionThrown", this.handleException.bind(this));
+    this.consoleEnabled = true;
+  }
+  /**
+   * Handle console API calls
+   */
+  handleConsoleMessage(params) {
+    const args = params["args"];
+    const stackTrace = params["stackTrace"];
+    const message = {
+      type: params["type"],
+      text: this.formatConsoleArgs(args ?? []),
+      args: args?.map((a) => a.value) ?? [],
+      timestamp: params["timestamp"],
+      stackTrace: stackTrace?.callFrames?.map((f) => `${f.url}:${f.lineNumber}`)
+    };
+    for (const handler of this.consoleHandlers) {
+      try {
+        handler(message);
+      } catch (e) {
+        console.error("[Console handler error]", e);
+      }
+    }
+  }
+  /**
+   * Handle JavaScript exceptions
+   */
+  handleException(params) {
+    const details = params["exceptionDetails"];
+    const exception = details["exception"];
+    const stackTrace = details["stackTrace"];
+    const error = {
+      message: exception?.description ?? details["text"],
+      url: details["url"],
+      lineNumber: details["lineNumber"],
+      columnNumber: details["columnNumber"],
+      timestamp: params["timestamp"],
+      stackTrace: stackTrace?.callFrames?.map((f) => `${f.url}:${f.lineNumber}`)
+    };
+    for (const handler of this.errorHandlers) {
+      try {
+        handler(error);
+      } catch (e) {
+        console.error("[Error handler error]", e);
+      }
+    }
+  }
+  /**
+   * Handle dialog opening
+   */
+  async handleDialogOpening(params) {
+    const dialog = {
+      type: params["type"],
+      message: params["message"],
+      defaultValue: params["defaultPrompt"],
+      accept: async (promptText) => {
+        await this.cdp.send("Page.handleJavaScriptDialog", {
+          accept: true,
+          promptText
+        });
+      },
+      dismiss: async () => {
+        await this.cdp.send("Page.handleJavaScriptDialog", {
+          accept: false
+        });
+      }
+    };
+    if (this.dialogHandler) {
+      try {
+        await this.dialogHandler(dialog);
+      } catch (e) {
+        console.error("[Dialog handler error]", e);
+        await dialog.dismiss();
+      }
+    } else {
+      await dialog.dismiss();
+    }
+  }
+  /**
+   * Format console arguments to string
+   */
+  formatConsoleArgs(args) {
+    return args.map((arg) => {
+      if (arg.value !== void 0) return String(arg.value);
+      if (arg.description) return arg.description;
+      return "[object]";
+    }).join(" ");
+  }
+  /**
+   * Subscribe to console messages
+   */
+  async onConsole(handler) {
+    await this.enableConsole();
+    this.consoleHandlers.add(handler);
+    return () => this.consoleHandlers.delete(handler);
+  }
+  /**
+   * Subscribe to page errors
+   */
+  async onError(handler) {
+    await this.enableConsole();
+    this.errorHandlers.add(handler);
+    return () => this.errorHandlers.delete(handler);
+  }
+  /**
+   * Set dialog handler (only one at a time)
+   */
+  async onDialog(handler) {
+    await this.enableConsole();
+    this.dialogHandler = handler;
+  }
+  /**
+   * Collect console messages during an action
+   */
+  async collectConsole(fn) {
+    const messages = [];
+    const unsubscribe = await this.onConsole((msg) => messages.push(msg));
+    try {
+      const result = await fn();
+      return { result, messages };
+    } finally {
+      unsubscribe();
+    }
+  }
+  /**
+   * Collect errors during an action
+   */
+  async collectErrors(fn) {
+    const errors = [];
+    const unsubscribe = await this.onError((err) => errors.push(err));
+    try {
+      const result = await fn();
+      return { result, errors };
+    } finally {
+      unsubscribe();
+    }
+  }
+  // ============ Lifecycle ============
+  /**
+   * Reset page state for clean test isolation
+   * - Stops any pending operations
+   * - Clears localStorage and sessionStorage
+   * - Resets internal state
+   */
+  async reset() {
+    this.rootNodeId = null;
+    this.refMap.clear();
+    this.currentFrame = null;
+    this.currentFrameContextId = null;
+    this.frameContexts.clear();
+    this.dialogHandler = null;
+    try {
+      await this.cdp.send("Page.stopLoading");
+    } catch {
+    }
+    try {
+      await this.cdp.send("Runtime.evaluate", {
+        expression: `(() => {
+          try { localStorage.clear(); } catch {}
+          try { sessionStorage.clear(); } catch {}
+        })()`
+      });
+    } catch {
+    }
+  }
+  /**
+   * Close this page (no-op for now, managed by Browser)
+   * This is a placeholder for API compatibility
+   */
+  async close() {
+  }
+  // ============ Private Helpers ============
+  /**
+   * Retry wrapper for operations that may encounter stale nodes
+   * Catches "Could not find node with given id" errors and retries
+   */
+  async withStaleNodeRetry(fn, options = {}) {
+    const { retries = 2, delay = 50 } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        return await fn();
+      } catch (e) {
+        if (e instanceof Error && (e.message.includes("Could not find node with given id") || e.message.includes("Node with given id does not belong to the document") || e.message.includes("No node with given id found"))) {
+          lastError = e;
+          if (attempt < retries) {
+            this.rootNodeId = null;
+            await sleep2(delay);
+            continue;
+          }
+        }
+        throw e;
+      }
+    }
+    throw lastError ?? new Error("Stale node retry exhausted");
+  }
+  /**
+   * Find an element using single or multiple selectors
+   * Supports ref: prefix for ref-based selectors (e.g., "ref:e4")
+   */
+  async findElement(selectors, options = {}) {
+    const { timeout = DEFAULT_TIMEOUT2 } = options;
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    for (const selector of selectorList) {
+      if (selector.startsWith("ref:")) {
+        const ref = selector.slice(4);
+        const backendNodeId = this.refMap.get(ref);
+        if (!backendNodeId) {
+          continue;
+        }
+        try {
+          await this.ensureRootNode();
+          const pushResult = await this.cdp.send(
+            "DOM.pushNodesByBackendIdsToFrontend",
+            {
+              backendNodeIds: [backendNodeId]
+            }
+          );
+          if (pushResult.nodeIds?.[0]) {
+            return {
+              nodeId: pushResult.nodeIds[0],
+              backendNodeId,
+              selector,
+              waitedMs: 0
+            };
+          }
+        } catch {
+        }
+      }
+    }
+    const cssSelectors = selectorList.filter((s) => !s.startsWith("ref:"));
+    if (cssSelectors.length === 0) {
+      return null;
+    }
+    const result = await waitForAnyElement(this.cdp, cssSelectors, {
+      state: "visible",
+      timeout,
+      contextId: this.currentFrameContextId ?? void 0
+    });
+    if (!result.success || !result.selector) {
+      return null;
+    }
+    await this.ensureRootNode();
+    const queryResult = await this.cdp.send("DOM.querySelector", {
+      nodeId: this.rootNodeId,
+      selector: result.selector
+    });
+    if (queryResult.nodeId) {
+      const describeResult2 = await this.cdp.send(
+        "DOM.describeNode",
+        { nodeId: queryResult.nodeId }
+      );
+      return {
+        nodeId: queryResult.nodeId,
+        backendNodeId: describeResult2.node.backendNodeId,
+        selector: result.selector,
+        waitedMs: result.waitedMs
+      };
+    }
+    const deepQueryResult = await this.evaluateInFrame(
+      `(() => {
+        ${DEEP_QUERY_SCRIPT}
+        return deepQuery(${JSON.stringify(result.selector)});
+      })()`,
+      { returnByValue: false }
+    );
+    if (!deepQueryResult.result.objectId) {
+      return null;
+    }
+    const nodeResult = await this.cdp.send("DOM.requestNode", {
+      objectId: deepQueryResult.result.objectId
+    });
+    if (!nodeResult.nodeId) {
+      return null;
+    }
+    const describeResult = await this.cdp.send(
+      "DOM.describeNode",
+      { nodeId: nodeResult.nodeId }
+    );
+    return {
+      nodeId: nodeResult.nodeId,
+      backendNodeId: describeResult.node.backendNodeId,
+      selector: result.selector,
+      waitedMs: result.waitedMs
+    };
+  }
+  /**
+   * Ensure we have a valid root node ID
+   */
+  async ensureRootNode() {
+    if (this.rootNodeId) return;
+    const doc = await this.cdp.send("DOM.getDocument", {
+      depth: 0
+    });
+    this.rootNodeId = doc.root.nodeId;
+  }
+  /**
+   * Execute Runtime.evaluate in the current frame context
+   * Automatically injects contextId when in an iframe
+   */
+  async evaluateInFrame(expression, options = {}) {
+    const params = {
+      expression,
+      returnByValue: options.returnByValue ?? true,
+      awaitPromise: options.awaitPromise ?? false
+    };
+    if (this.currentFrameContextId !== null) {
+      params["contextId"] = this.currentFrameContextId;
+    }
+    return this.cdp.send("Runtime.evaluate", params);
+  }
+  /**
+   * Scroll an element into view
+   */
+  async scrollIntoView(nodeId) {
+    await this.cdp.send("DOM.scrollIntoViewIfNeeded", { nodeId });
+  }
+  /**
+   * Get element box model (position and dimensions)
+   */
+  async getBoxModel(nodeId) {
+    try {
+      const result = await this.cdp.send("DOM.getBoxModel", {
+        nodeId
+      });
+      return result.model;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Click an element by node ID
+   */
+  async clickElement(nodeId) {
+    const box = await this.getBoxModel(nodeId);
+    if (!box) {
+      throw new Error("Could not get element box model for click");
+    }
+    const x = box.content[0] + box.width / 2;
+    const y = box.content[1] + box.height / 2;
+    await this.cdp.send("Input.dispatchMouseEvent", {
+      type: "mousePressed",
+      x,
+      y,
+      button: "left",
+      clickCount: 1
+    });
+    await this.cdp.send("Input.dispatchMouseEvent", {
+      type: "mouseReleased",
+      x,
+      y,
+      button: "left",
+      clickCount: 1
+    });
+  }
+};
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/browser/browser.ts
+var Browser = class _Browser {
+  cdp;
+  providerSession;
+  pages = /* @__PURE__ */ new Map();
+  constructor(cdp, _provider, providerSession, _options) {
+    this.cdp = cdp;
+    this.providerSession = providerSession;
+  }
+  /**
+   * Connect to a browser instance
+   */
+  static async connect(options) {
+    const provider = createProvider(options);
+    const session = await provider.createSession(options.session);
+    const cdp = await createCDPClient(session.wsUrl, {
+      debug: options.debug,
+      timeout: options.timeout
+    });
+    return new _Browser(cdp, provider, session, options);
+  }
+  /**
+   * Get or create a page by name
+   * If no name is provided, returns the first available page or creates a new one
+   */
+  async page(name) {
+    const pageName = name ?? "default";
+    const cached = this.pages.get(pageName);
+    if (cached) return cached;
+    const targets = await this.cdp.send("Target.getTargets");
+    const pageTargets = targets.targetInfos.filter((t) => t.type === "page");
+    let targetId;
+    if (pageTargets.length > 0) {
+      targetId = pageTargets[0].targetId;
+    } else {
+      const result = await this.cdp.send("Target.createTarget", {
+        url: "about:blank"
+      });
+      targetId = result.targetId;
+    }
+    await this.cdp.attachToTarget(targetId);
+    const page = new Page(this.cdp);
+    await page.init();
+    this.pages.set(pageName, page);
+    return page;
+  }
+  /**
+   * Create a new page (tab)
+   */
+  async newPage(url = "about:blank") {
+    const result = await this.cdp.send("Target.createTarget", {
+      url
+    });
+    await this.cdp.attachToTarget(result.targetId);
+    const page = new Page(this.cdp);
+    await page.init();
+    const name = `page-${this.pages.size + 1}`;
+    this.pages.set(name, page);
+    return page;
+  }
+  /**
+   * Close a page by name
+   */
+  async closePage(name) {
+    const page = this.pages.get(name);
+    if (!page) return;
+    const targets = await this.cdp.send("Target.getTargets");
+    const pageTargets = targets.targetInfos.filter((t) => t.type === "page");
+    if (pageTargets.length > 0) {
+      await this.cdp.send("Target.closeTarget", {
+        targetId: pageTargets[0].targetId
+      });
+    }
+    this.pages.delete(name);
+  }
+  /**
+   * Get the WebSocket URL for this browser connection
+   */
+  get wsUrl() {
+    return this.providerSession.wsUrl;
+  }
+  /**
+   * Get the provider session ID (for resumption)
+   */
+  get sessionId() {
+    return this.providerSession.sessionId;
+  }
+  /**
+   * Get provider metadata
+   */
+  get metadata() {
+    return this.providerSession.metadata;
+  }
+  /**
+   * Check if connected
+   */
+  get isConnected() {
+    return this.cdp.isConnected;
+  }
+  /**
+   * Disconnect from the browser (keeps provider session alive for reconnection)
+   */
+  async disconnect() {
+    this.pages.clear();
+    await this.cdp.close();
+  }
+  /**
+   * Close the browser session completely
+   */
+  async close() {
+    this.pages.clear();
+    await this.cdp.close();
+    await this.providerSession.close();
+  }
+  /**
+   * Get the underlying CDP client (for advanced usage)
+   */
+  get cdpClient() {
+    return this.cdp;
+  }
+};
+function connect(options) {
+  return Browser.connect(options);
+}
+
+// src/cli/session.ts
+var import_node_os = require("os");
+var import_node_path = require("path");
+var SESSION_DIR = (0, import_node_path.join)((0, import_node_os.homedir)(), ".browser-pilot", "sessions");
+async function ensureSessionDir() {
+  const fs = await import("fs/promises");
+  await fs.mkdir(SESSION_DIR, { recursive: true });
+}
+async function saveSession(session) {
+  await ensureSessionDir();
+  const fs = await import("fs/promises");
+  const filePath = (0, import_node_path.join)(SESSION_DIR, `${session.id}.json`);
+  await fs.writeFile(filePath, JSON.stringify(session, null, 2));
+}
+async function loadSession(id) {
+  const fs = await import("fs/promises");
+  const filePath = (0, import_node_path.join)(SESSION_DIR, `${id}.json`);
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Session not found: ${id}`);
+    }
+    throw error;
+  }
+}
+async function updateSession(id, updates) {
+  const session = await loadSession(id);
+  const updated = {
+    ...session,
+    ...updates,
+    lastActivity: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await saveSession(updated);
+  return updated;
+}
+async function deleteSession(id) {
+  const fs = await import("fs/promises");
+  const filePath = (0, import_node_path.join)(SESSION_DIR, `${id}.json`);
+  try {
+    await fs.unlink(filePath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+async function listSessions() {
+  await ensureSessionDir();
+  const fs = await import("fs/promises");
+  try {
+    const files = await fs.readdir(SESSION_DIR);
+    const sessions = [];
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        try {
+          const content = await fs.readFile((0, import_node_path.join)(SESSION_DIR, file), "utf-8");
+          sessions.push(JSON.parse(content));
+        } catch {
+        }
+      }
+    }
+    return sessions.sort(
+      (a, b) => new Date(b.lastActivity).getTime() - new Date(a.lastActivity).getTime()
+    );
+  } catch {
+    return [];
+  }
+}
+function generateSessionId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `${timestamp}-${random}`;
+}
+async function getDefaultSession() {
+  const sessions = await listSessions();
+  return sessions[0] ?? null;
+}
+
+// src/cli/commands/close.ts
+async function closeCommand(args, globalOptions) {
+  let session;
+  if (globalOptions.session) {
+    session = await loadSession(globalOptions.session);
+  } else if (args[0]) {
+    session = await loadSession(args[0]);
+  } else {
+    session = await getDefaultSession();
+    if (!session) {
+      throw new Error('No session found. Specify a session ID or run "bp list" to see sessions.');
+    }
+  }
+  try {
+    const browser = await connect({
+      provider: session.provider,
+      wsUrl: session.wsUrl,
+      debug: globalOptions.trace
+    });
+    await browser.close();
+  } catch {
+  }
+  await deleteSession(session.id);
+  output(
+    {
+      success: true,
+      sessionId: session.id,
+      message: "Session closed"
+    },
+    globalOptions.output
+  );
+}
+
+// src/cli/commands/connect.ts
+function parseConnectArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--provider" || arg === "-p") {
+      options.provider = args[++i];
+    } else if (arg === "--url") {
+      options.url = args[++i];
+    } else if (arg === "--name" || arg === "-n") {
+      options.name = args[++i];
+    } else if (arg === "--resume" || arg === "-r") {
+      options.resume = args[++i];
+    } else if (arg === "--api-key") {
+      options.apiKey = args[++i];
+    } else if (arg === "--project-id") {
+      options.projectId = args[++i];
+    }
+  }
+  return options;
+}
+async function connectCommand(args, globalOptions) {
+  const options = parseConnectArgs(args);
+  if (options.resume || globalOptions.session) {
+    const sessionId2 = options.resume || globalOptions.session;
+    const session2 = await loadSession(sessionId2);
+    output(
+      {
+        success: true,
+        resumed: true,
+        sessionId: session2.id,
+        provider: session2.provider,
+        currentUrl: session2.currentUrl
+      },
+      globalOptions.output
+    );
+    return;
+  }
+  const provider = options.provider ?? "generic";
+  let wsUrl = options.url;
+  if (provider === "generic" && !wsUrl) {
+    try {
+      wsUrl = await getBrowserWebSocketUrl("localhost:9222");
+    } catch {
+      throw new Error(
+        "Could not auto-discover browser. Specify --url or start Chrome with --remote-debugging-port=9222"
+      );
+    }
+  }
+  const connectOptions = {
+    provider,
+    debug: globalOptions.trace,
+    wsUrl,
+    apiKey: options.apiKey,
+    projectId: options.projectId
+  };
+  const browser = await connect(connectOptions);
+  const page = await browser.page();
+  const currentUrl = await page.url();
+  const sessionId = options.name ?? generateSessionId();
+  const session = {
+    id: sessionId,
+    provider,
+    wsUrl: browser.wsUrl,
+    providerSessionId: browser.sessionId,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastActivity: (/* @__PURE__ */ new Date()).toISOString(),
+    currentUrl,
+    metadata: browser.metadata
+  };
+  await saveSession(session);
+  await browser.disconnect();
+  output(
+    {
+      success: true,
+      sessionId,
+      provider,
+      currentUrl,
+      metadata: browser.metadata
+    },
+    globalOptions.output
+  );
+}
+
+// src/cli/commands/exec.ts
+function parseExecArgs(args) {
+  const options = {};
+  let actionsJson;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--dialog") {
+      const value = args[++i];
+      if (value === "accept" || value === "dismiss") {
+        options.dialog = value;
+      } else {
+        throw new Error('--dialog must be "accept" or "dismiss"');
+      }
+    } else if (!actionsJson && !arg.startsWith("-")) {
+      actionsJson = arg;
+    }
+  }
+  return { actionsJson, options };
+}
+async function execCommand(args, globalOptions) {
+  const { actionsJson, options: execOptions } = parseExecArgs(args);
+  let session;
+  if (globalOptions.session) {
+    session = await loadSession(globalOptions.session);
+  } else {
+    session = await getDefaultSession();
+    if (!session) {
+      throw new Error('No session found. Run "bp connect" first.');
+    }
+  }
+  if (!actionsJson) {
+    throw new Error(
+      `No actions provided. Usage: bp exec '{"action":"goto","url":"..."}'
+
+Run 'bp actions' for complete action reference.`
+    );
+  }
+  let actions;
+  try {
+    actions = JSON.parse(actionsJson);
+  } catch {
+    throw new Error(
+      "Invalid JSON. Actions must be valid JSON.\n\nRun 'bp actions' for complete action reference."
+    );
+  }
+  const browser = await connect({
+    provider: session.provider,
+    wsUrl: session.wsUrl,
+    debug: globalOptions.trace
+  });
+  try {
+    const page = addBatchToPage(await browser.page());
+    if (execOptions.dialog) {
+      await page.onDialog(async (dialog) => {
+        if (execOptions.dialog === "accept") {
+          await dialog.accept();
+        } else {
+          await dialog.dismiss();
+        }
+      });
+    }
+    const steps = Array.isArray(actions) ? actions : [actions];
+    const result = await page.batch(steps);
+    const currentUrl = await page.url();
+    await updateSession(session.id, { currentUrl });
+    output(
+      {
+        success: result.success,
+        stoppedAtIndex: result.stoppedAtIndex,
+        steps: result.steps.map((s) => ({
+          action: s.action,
+          success: s.success,
+          durationMs: s.durationMs,
+          selectorUsed: s.selectorUsed,
+          error: s.error,
+          text: s.text,
+          result: s.result
+        })),
+        totalDurationMs: result.totalDurationMs,
+        currentUrl
+      },
+      globalOptions.output
+    );
+  } finally {
+    await browser.disconnect();
+  }
+}
+
+// src/cli/commands/list.ts
+async function listCommand(_args, globalOptions) {
+  const sessions = await listSessions();
+  if (globalOptions.output === "json") {
+    output(sessions, "json");
+    return;
+  }
+  if (sessions.length === 0) {
+    console.log("No active sessions.");
+    console.log('Run "bp connect" to create a new session.');
+    return;
+  }
+  console.log("Active Sessions:\n");
+  for (const session of sessions) {
+    const age = getAge(new Date(session.lastActivity));
+    console.log(`  ${session.id}`);
+    console.log(`    Provider: ${session.provider}`);
+    console.log(`    URL: ${session.currentUrl}`);
+    console.log(`    Last activity: ${age}`);
+    console.log("");
+  }
+}
+function getAge(date) {
+  const now = Date.now();
+  const diff = now - date.getTime();
+  const seconds = Math.floor(diff / 1e3);
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+// src/cli/commands/screenshot.ts
+function parseScreenshotArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--output" || arg === "-o") {
+      options.outputPath = args[++i];
+    } else if (arg === "--format" || arg === "-f") {
+      options.format = args[++i];
+    } else if (arg === "--quality" || arg === "-q") {
+      options.quality = parseInt(args[++i], 10);
+    } else if (arg === "--full-page" || arg === "--fullpage") {
+      options.fullPage = true;
+    }
+  }
+  return options;
+}
+async function screenshotCommand(args, globalOptions) {
+  const options = parseScreenshotArgs(args);
+  let session;
+  if (globalOptions.session) {
+    session = await loadSession(globalOptions.session);
+  } else {
+    session = await getDefaultSession();
+    if (!session) {
+      throw new Error('No session found. Run "bp connect" first.');
+    }
+  }
+  const browser = await connect({
+    provider: session.provider,
+    wsUrl: session.wsUrl,
+    debug: globalOptions.trace
+  });
+  try {
+    const page = await browser.page();
+    const screenshotData = await page.screenshot({
+      format: options.format ?? "png",
+      quality: options.quality,
+      fullPage: options.fullPage ?? false
+    });
+    if (options.outputPath) {
+      const buffer = Buffer.from(screenshotData, "base64");
+      await Bun.write(options.outputPath, buffer);
+      output(
+        {
+          success: true,
+          path: options.outputPath,
+          size: buffer.length,
+          format: options.format ?? "png"
+        },
+        globalOptions.output
+      );
+    } else {
+      if (globalOptions.output === "json") {
+        output({ data: screenshotData, format: options.format ?? "png" }, "json");
+      } else {
+        console.log(screenshotData);
+      }
+    }
+  } finally {
+    await browser.disconnect();
+  }
+}
+
+// src/cli/commands/snapshot.ts
+function parseSnapshotArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--format" || arg === "-f") {
+      options.format = args[++i];
+    }
+  }
+  return options;
+}
+async function snapshotCommand(args, globalOptions) {
+  const options = parseSnapshotArgs(args);
+  let session;
+  if (globalOptions.session) {
+    session = await loadSession(globalOptions.session);
+  } else {
+    session = await getDefaultSession();
+    if (!session) {
+      throw new Error('No session found. Run "bp connect" first.');
+    }
+  }
+  const browser = await connect({
+    provider: session.provider,
+    wsUrl: session.wsUrl,
+    debug: globalOptions.trace
+  });
+  try {
+    const page = await browser.page();
+    const snapshot = await page.snapshot();
+    await updateSession(session.id, { currentUrl: snapshot.url });
+    switch (options.format) {
+      case "interactive":
+        output(snapshot.interactiveElements, globalOptions.output);
+        break;
+      case "text":
+        console.log(snapshot.text);
+        break;
+      default:
+        output(snapshot, globalOptions.output);
+        break;
+    }
+  } finally {
+    await browser.disconnect();
+  }
+}
+
+// src/cli/commands/text.ts
+function parseTextArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--selector" || arg === "-s") {
+      options.selector = args[++i];
+    }
+  }
+  return options;
+}
+async function textCommand(args, globalOptions) {
+  const options = parseTextArgs(args);
+  let session;
+  if (globalOptions.session) {
+    session = await loadSession(globalOptions.session);
+  } else {
+    session = await getDefaultSession();
+    if (!session) {
+      throw new Error('No session found. Run "bp connect" first.');
+    }
+  }
+  const browser = await connect({
+    provider: session.provider,
+    wsUrl: session.wsUrl,
+    debug: globalOptions.trace
+  });
+  try {
+    const page = await browser.page();
+    const text = await page.text(options.selector);
+    const currentUrl = await page.url();
+    await updateSession(session.id, { currentUrl });
+    if (globalOptions.output === "json") {
+      output({ text, url: currentUrl, selector: options.selector }, "json");
+    } else {
+      console.log(text);
+    }
+  } finally {
+    await browser.disconnect();
+  }
+}
+
+// src/cli/index.ts
+var HELP = `
+bp - Browser automation CLI for AI agents
+
+Usage:
+  bp <command> [options]
+
+Commands:
+  connect     Create or resume browser session
+  exec        Execute actions on current session
+  snapshot    Get page accessibility snapshot (includes element refs)
+  text        Extract text content from page
+  screenshot  Take screenshot
+  close       Close session
+  list        List all sessions
+  actions     Show all available actions with examples
+
+Global Options:
+  -s, --session <id>    Session ID to use
+  -o, --output <fmt>    Output format: json | pretty (default: pretty)
+  --trace               Enable execution tracing
+  -h, --help            Show this help message
+
+Exec Options:
+  --dialog <mode>       Auto-handle dialogs: accept | dismiss
+
+Ref Selectors (Recommended for AI Agents):
+  1. Take snapshot:     bp snapshot --format text
+     Output shows:      button "Submit" [ref=e4], textbox "Email" [ref=e5]
+  2. Use ref directly:  bp exec '{"action":"click","selector":"ref:e4"}'
+
+  Refs are stable until navigation. Combine with CSS fallbacks:
+    {"selector": ["ref:e4", "#submit", "button[type=submit]"]}
+
+Examples:
+  # Connect to browser
+  bp connect --provider generic --name dev
+
+  # Navigate and get snapshot with refs
+  bp exec '{"action":"goto","url":"https://example.com"}'
+  bp snapshot --format text
+
+  # Use ref from snapshot (most reliable)
+  bp exec '{"action":"click","selector":"ref:e4"}'
+  bp exec '{"action":"fill","selector":"ref:e5","value":"test@example.com"}'
+
+  # Handle native dialogs (alert/confirm/prompt)
+  bp exec --dialog accept '{"action":"click","selector":"#delete-btn"}'
+
+  # Batch multiple actions
+  bp exec '[
+    {"action":"fill","selector":"ref:e5","value":"user@example.com"},
+    {"action":"click","selector":"ref:e4"},
+    {"action":"snapshot"}
+  ]'
+
+Run 'bp actions' for complete action reference.
+`;
+function parseGlobalOptions(args) {
+  const options = {
+    output: "pretty"
+  };
+  const remaining = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-s" || arg === "--session") {
+      options.session = args[++i];
+    } else if (arg === "-o" || arg === "--output") {
+      options.output = args[++i];
+    } else if (arg === "--trace") {
+      options.trace = true;
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else {
+      remaining.push(arg);
+    }
+  }
+  return { options, remaining };
+}
+function output(data, format = "pretty") {
+  if (format === "json") {
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    if (typeof data === "string") {
+      console.log(data);
+    } else if (typeof data === "object" && data !== null) {
+      prettyPrint(data);
+    } else {
+      console.log(data);
+    }
+  }
+}
+function prettyPrint(obj, indent = 0) {
+  const prefix = "  ".repeat(indent);
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      console.log(`${prefix}${key}:`);
+      prettyPrint(value, indent + 1);
+    } else if (Array.isArray(value)) {
+      console.log(`${prefix}${key}: [${value.length} items]`);
+    } else {
+      console.log(`${prefix}${key}: ${value}`);
+    }
+  }
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  const command = args[0];
+  const { options, remaining } = parseGlobalOptions(args.slice(1));
+  if (options.help && !command) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  try {
+    switch (command) {
+      case "connect":
+        await connectCommand(remaining, options);
+        break;
+      case "exec":
+        await execCommand(remaining, options);
+        break;
+      case "snapshot":
+        await snapshotCommand(remaining, options);
+        break;
+      case "text":
+        await textCommand(remaining, options);
+        break;
+      case "screenshot":
+        await screenshotCommand(remaining, options);
+        break;
+      case "close":
+        await closeCommand(remaining, options);
+        break;
+      case "list":
+        await listCommand(remaining, options);
+        break;
+      case "actions":
+        await actionsCommand();
+        break;
+      case "help":
+      case "--help":
+      case "-h":
+        console.log(HELP);
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.log(HELP);
+        process.exit(1);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}
+main();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  output
+});