browser-pilot 0.0.1

package/dist/index.cjs

@@ -0,0 +1,3074 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  BatchExecutor: () => BatchExecutor,
+  Browser: () => Browser,
+  BrowserBaseProvider: () => BrowserBaseProvider,
+  BrowserlessProvider: () => BrowserlessProvider,
+  CDPError: () => CDPError,
+  ElementNotFoundError: () => ElementNotFoundError,
+  GenericProvider: () => GenericProvider,
+  NavigationError: () => NavigationError,
+  Page: () => Page,
+  RequestInterceptor: () => RequestInterceptor,
+  TimeoutError: () => TimeoutError,
+  Tracer: () => Tracer,
+  addBatchToPage: () => addBatchToPage,
+  connect: () => connect,
+  createCDPClient: () => createCDPClient,
+  createProvider: () => createProvider,
+  devices: () => devices,
+  disableTracing: () => disableTracing,
+  discoverTargets: () => discoverTargets,
+  enableTracing: () => enableTracing,
+  getBrowserWebSocketUrl: () => getBrowserWebSocketUrl,
+  getTracer: () => getTracer,
+  waitForAnyElement: () => waitForAnyElement,
+  waitForElement: () => waitForElement,
+  waitForNavigation: () => waitForNavigation,
+  waitForNetworkIdle: () => waitForNetworkIdle
+});
+module.exports = __toCommonJS(src_exports);
+
+// 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 discoverTargets(host = "localhost:9222") {
+  const protocol = host.includes("://") ? "" : "http://";
+  const response = await fetch(`${protocol}${host}/json/list`);
+  if (!response.ok) {
+    throw new Error(`Failed to discover targets: ${response.status}`);
+  }
+  return await response.json();
+}
+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 waitForElement(cdp, selector, options = {}) {
+  const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
+  const startTime = Date.now();
+  const deadline = startTime + timeout;
+  while (Date.now() < deadline) {
+    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, waitedMs: Date.now() - startTime };
+    }
+    await sleep(pollInterval);
+  }
+  return { success: false, waitedMs: Date.now() - startTime };
+}
+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";
+  }
+};
+var NavigationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NavigationError";
+  }
+};
+
+// 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/emulation/devices.ts
+var devices = {
+  "iPhone 14": {
+    name: "iPhone 14",
+    viewport: {
+      width: 390,
+      height: 844,
+      deviceScaleFactor: 3,
+      isMobile: true,
+      hasTouch: true
+    },
+    userAgent: {
+      userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1",
+      platform: "iPhone",
+      userAgentMetadata: {
+        mobile: true,
+        platform: "iOS",
+        platformVersion: "16.0"
+      }
+    }
+  },
+  "iPhone 14 Pro Max": {
+    name: "iPhone 14 Pro Max",
+    viewport: {
+      width: 430,
+      height: 932,
+      deviceScaleFactor: 3,
+      isMobile: true,
+      hasTouch: true
+    },
+    userAgent: {
+      userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1",
+      platform: "iPhone"
+    }
+  },
+  "Pixel 7": {
+    name: "Pixel 7",
+    viewport: {
+      width: 412,
+      height: 915,
+      deviceScaleFactor: 2.625,
+      isMobile: true,
+      hasTouch: true
+    },
+    userAgent: {
+      userAgent: "Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36",
+      platform: "Linux armv8l",
+      userAgentMetadata: {
+        mobile: true,
+        platform: "Android",
+        platformVersion: "13",
+        model: "Pixel 7"
+      }
+    }
+  },
+  "iPad Pro 11": {
+    name: "iPad Pro 11",
+    viewport: {
+      width: 834,
+      height: 1194,
+      deviceScaleFactor: 2,
+      isMobile: true,
+      hasTouch: true
+    },
+    userAgent: {
+      userAgent: "Mozilla/5.0 (iPad; CPU OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1",
+      platform: "iPad"
+    }
+  },
+  "Desktop Chrome": {
+    name: "Desktop Chrome",
+    viewport: {
+      width: 1920,
+      height: 1080,
+      deviceScaleFactor: 1,
+      isMobile: false,
+      hasTouch: false
+    },
+    userAgent: {
+      userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+      platform: "Win32",
+      userAgentMetadata: {
+        brands: [
+          { brand: "Not_A Brand", version: "8" },
+          { brand: "Chromium", version: "120" },
+          { brand: "Google Chrome", version: "120" }
+        ],
+        platform: "Windows",
+        platformVersion: "10.0.0",
+        architecture: "x86",
+        bitness: "64",
+        mobile: false
+      }
+    }
+  },
+  "Desktop Firefox": {
+    name: "Desktop Firefox",
+    viewport: {
+      width: 1920,
+      height: 1080,
+      deviceScaleFactor: 1,
+      isMobile: false,
+      hasTouch: false
+    },
+    userAgent: {
+      userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0",
+      platform: "Win32"
+    }
+  }
+};
+
+// src/trace/tracer.ts
+var LEVEL_ORDER = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var Tracer = class _Tracer {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      enabled: options.enabled ?? false,
+      output: options.output ?? "console",
+      callback: options.callback,
+      level: options.level ?? "info",
+      includeTimings: options.includeTimings ?? true
+    };
+  }
+  /**
+   * Emit a trace event
+   */
+  emit(event) {
+    if (!this.options.enabled) return;
+    if (LEVEL_ORDER[event.level] < LEVEL_ORDER[this.options.level]) {
+      return;
+    }
+    const fullEvent = {
+      ...event,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    switch (this.options.output) {
+      case "console":
+        this.logToConsole(fullEvent);
+        break;
+      case "callback":
+        this.options.callback?.(fullEvent);
+        break;
+      case "silent":
+        break;
+    }
+  }
+  /**
+   * Log event to console
+   */
+  logToConsole(event) {
+    const { level, category, action, selectorUsed, success, durationMs, error } = event;
+    const icon = success === true ? "\u2713" : success === false ? "\u2717" : "\u25CB";
+    const timing = this.options.includeTimings && durationMs !== void 0 ? ` (${durationMs}ms)` : "";
+    const selector = selectorUsed ? ` ${selectorUsed}` : "";
+    const errorStr = error ? ` - ${error}` : "";
+    const message = `[${level.toUpperCase()}] [${category}] ${icon} ${action}${selector}${timing}${errorStr}`;
+    switch (level) {
+      case "debug":
+        console.debug(message);
+        break;
+      case "info":
+        console.info(message);
+        break;
+      case "warn":
+        console.warn(message);
+        break;
+      case "error":
+        console.error(message);
+        break;
+    }
+  }
+  /**
+   * Create a child tracer with modified options
+   */
+  child(options) {
+    return new _Tracer({ ...this.options, ...options });
+  }
+  /**
+   * Enable tracing
+   */
+  enable() {
+    this.options.enabled = true;
+  }
+  /**
+   * Disable tracing
+   */
+  disable() {
+    this.options.enabled = false;
+  }
+  /**
+   * Check if tracing is enabled
+   */
+  get isEnabled() {
+    return this.options.enabled;
+  }
+};
+var globalTracer = null;
+function getTracer() {
+  if (!globalTracer) {
+    globalTracer = new Tracer({ enabled: false });
+  }
+  return globalTracer;
+}
+function enableTracing(options = {}) {
+  globalTracer = new Tracer({ ...options, enabled: true });
+  return globalTracer;
+}
+function disableTracing() {
+  if (globalTracer) {
+    globalTracer.disable();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BatchExecutor,
+  Browser,
+  BrowserBaseProvider,
+  BrowserlessProvider,
+  CDPError,
+  ElementNotFoundError,
+  GenericProvider,
+  NavigationError,
+  Page,
+  RequestInterceptor,
+  TimeoutError,
+  Tracer,
+  addBatchToPage,
+  connect,
+  createCDPClient,
+  createProvider,
+  devices,
+  disableTracing,
+  discoverTargets,
+  enableTracing,
+  getBrowserWebSocketUrl,
+  getTracer,
+  waitForAnyElement,
+  waitForElement,
+  waitForNavigation,
+  waitForNetworkIdle
+});