browser-pilot 0.0.1

package/dist/chunk-FI55U7JS.mjs

@@ -0,0 +1,2108 @@
+import {
+  createCDPClient
+} from "./chunk-BCOZUKWS.mjs";
+import {
+  createProvider
+} from "./chunk-R3PS4PCM.mjs";
+import {
+  BatchExecutor
+} from "./chunk-YEHK2XY3.mjs";
+
+// 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_TIMEOUT = 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_TIMEOUT } = 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_TIMEOUT } = 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_TIMEOUT } = 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_TIMEOUT } = 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_TIMEOUT });
+          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_TIMEOUT });
+      } 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_TIMEOUT, 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_TIMEOUT } = 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_TIMEOUT, 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_TIMEOUT } = 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_TIMEOUT } = 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);
+}
+
+export {
+  RequestInterceptor,
+  waitForElement,
+  waitForAnyElement,
+  waitForNavigation,
+  waitForNetworkIdle,
+  ElementNotFoundError,
+  TimeoutError,
+  NavigationError,
+  Page,
+  Browser,
+  connect
+};