browser-pilot 0.0.6 → 0.0.8

package/dist/browser.d.cts

@@ -1,7 +1,7 @@
 import { C as CDPClient } from './client-7Nqka5MV.cjs';
 import { C as ConnectOptions } from './types-D_uDqh0Z.cjs';
-import { P as Page } from './types-TVlTA7nH.cjs';
-export { d as ActionOptions, e as ActionResult, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, h as CustomSelectConfig, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, F as FileInput, o as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, p as NetworkIdleOptions, q as PageError, r as PageSnapshot, s as SnapshotNode, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-TVlTA7nH.cjs';
+import { P as Page } from './types-DklIxnbO.cjs';
+export { d as ActionOptions, e as ActionResult, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, h as CustomSelectConfig, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, a5 as FailureHint, F as FileInput, o as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, p as NetworkIdleOptions, q as PageError, r as PageSnapshot, s as SnapshotNode, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-DklIxnbO.cjs';
 
 /**
  * Browser class - manages CDP connection and pages
@@ -11,6 +11,10 @@ interface BrowserOptions extends ConnectOptions {
     /** Enable debug logging */
     debug?: boolean;
 }
+interface PageOptions {
+    /** Specific target ID to attach to */
+    targetId?: string;
+}
 declare class Browser {
     private cdp;
     private providerSession;
@@ -24,7 +28,7 @@ declare class Browser {
      * Get or create a page by name
      * If no name is provided, returns the first available page or creates a new one
      */
-    page(name?: string): Promise<Page>;
+    page(name?: string, options?: PageOptions): Promise<Page>;
     /**
      * Create a new page (tab)
      */

package/dist/browser.d.ts

@@ -1,7 +1,7 @@
 import { C as CDPClient } from './client-7Nqka5MV.js';
 import { C as ConnectOptions } from './types-D_uDqh0Z.js';
-import { P as Page } from './types-CbdmaocU.js';
-export { d as ActionOptions, e as ActionResult, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, h as CustomSelectConfig, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, F as FileInput, o as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, p as NetworkIdleOptions, q as PageError, r as PageSnapshot, s as SnapshotNode, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-CbdmaocU.js';
+import { P as Page } from './types-Pv8KzZ6l.js';
+export { d as ActionOptions, e as ActionResult, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, h as CustomSelectConfig, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, a5 as FailureHint, F as FileInput, o as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, p as NetworkIdleOptions, q as PageError, r as PageSnapshot, s as SnapshotNode, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-Pv8KzZ6l.js';
 
 /**
  * Browser class - manages CDP connection and pages
@@ -11,6 +11,10 @@ interface BrowserOptions extends ConnectOptions {
     /** Enable debug logging */
     debug?: boolean;
 }
+interface PageOptions {
+    /** Specific target ID to attach to */
+    targetId?: string;
+}
 declare class Browser {
     private cdp;
     private providerSession;
@@ -24,7 +28,7 @@ declare class Browser {
      * Get or create a page by name
      * If no name is provided, returns the first available page or creates a new one
      */
-    page(name?: string): Promise<Page>;
+    page(name?: string, options?: PageOptions): Promise<Page>;
     /**
      * Create a new page (tab)
      */

package/dist/browser.mjs

@@ -1,14 +1,15 @@
 import {
   Browser,
-  ElementNotFoundError,
-  NavigationError,
   Page,
-  TimeoutError,
   connect
-} from "./chunk-PCNEJAJ7.mjs";
+} from "./chunk-JN44FHTK.mjs";
 import "./chunk-BCOZUKWS.mjs";
 import "./chunk-R3PS4PCM.mjs";
-import "./chunk-6RB3GKQP.mjs";
+import {
+  ElementNotFoundError,
+  NavigationError,
+  TimeoutError
+} from "./chunk-ZTQ37YQT.mjs";
 export {
   Browser,
   ElementNotFoundError,

package/dist/{chunk-PCNEJAJ7.mjs → chunk-JN44FHTK.mjs}

@@ -5,8 +5,10 @@ import {
   createProvider
 } from "./chunk-R3PS4PCM.mjs";
 import {
-  BatchExecutor
-} from "./chunk-6RB3GKQP.mjs";
+  BatchExecutor,
+  ElementNotFoundError,
+  TimeoutError
+} from "./chunk-ZTQ37YQT.mjs";
 
 // src/network/interceptor.ts
 var RequestInterceptor = class {
@@ -422,33 +424,256 @@ async function waitForNetworkIdle(cdp, options = {}) {
   });
 }
 
-// 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;
+// src/browser/fuzzy-match.ts
+function jaroWinkler(a, b) {
+  if (a.length === 0 && b.length === 0) return 0;
+  if (a.length === 0 || b.length === 0) return 0;
+  if (a === b) return 1;
+  const s1 = a.toLowerCase();
+  const s2 = b.toLowerCase();
+  const matchWindow = Math.max(0, Math.floor(Math.max(s1.length, s2.length) / 2) - 1);
+  const s1Matches = new Array(s1.length).fill(false);
+  const s2Matches = new Array(s2.length).fill(false);
+  let matches = 0;
+  let transpositions = 0;
+  for (let i = 0; i < s1.length; i++) {
+    const start = Math.max(0, i - matchWindow);
+    const end = Math.min(i + matchWindow + 1, s2.length);
+    for (let j = start; j < end; j++) {
+      if (s2Matches[j] || s1[i] !== s2[j]) continue;
+      s1Matches[i] = true;
+      s2Matches[j] = true;
+      matches++;
+      break;
+    }
+  }
+  if (matches === 0) return 0;
+  let k = 0;
+  for (let i = 0; i < s1.length; i++) {
+    if (!s1Matches[i]) continue;
+    while (!s2Matches[k]) k++;
+    if (s1[i] !== s2[k]) transpositions++;
+    k++;
+  }
+  const jaro = (matches / s1.length + matches / s2.length + (matches - transpositions / 2) / matches) / 3;
+  let prefix = 0;
+  for (let i = 0; i < Math.min(4, Math.min(s1.length, s2.length)); i++) {
+    if (s1[i] === s2[i]) {
+      prefix++;
+    } else {
+      break;
+    }
   }
-};
-var TimeoutError = class extends Error {
-  constructor(message = "Operation timed out") {
-    super(message);
-    this.name = "TimeoutError";
+  const WINKLER_SCALING = 0.1;
+  return jaro + prefix * WINKLER_SCALING * (1 - jaro);
+}
+function stringSimilarity(a, b) {
+  if (a.length === 0 || b.length === 0) return 0;
+  const lowerA = a.toLowerCase();
+  const lowerB = b.toLowerCase();
+  if (lowerA === lowerB) return 1;
+  const jw = jaroWinkler(a, b);
+  let containsBonus = 0;
+  if (lowerB.includes(lowerA)) {
+    containsBonus = 0.2;
+  } else if (lowerA.includes(lowerB)) {
+    containsBonus = 0.1;
+  }
+  return Math.min(1, jw + containsBonus);
+}
+function scoreElement(query, element) {
+  const lowerQuery = query.toLowerCase();
+  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
+  let nameScore = 0;
+  if (element.name) {
+    const lowerName = element.name.toLowerCase();
+    if (lowerName === lowerQuery) {
+      nameScore = 1;
+    } else if (lowerName.includes(lowerQuery)) {
+      nameScore = 0.8;
+    } else if (words.length > 0) {
+      const matchedWords = words.filter((w) => lowerName.includes(w));
+      nameScore = matchedWords.length / words.length * 0.7;
+    } else {
+      nameScore = stringSimilarity(query, element.name) * 0.6;
+    }
   }
-};
-var NavigationError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "NavigationError";
+  let roleScore = 0;
+  const lowerRole = element.role.toLowerCase();
+  if (lowerRole === lowerQuery || lowerQuery.includes(lowerRole)) {
+    roleScore = 0.3;
+  } else if (words.some((w) => lowerRole.includes(w))) {
+    roleScore = 0.2;
+  }
+  let selectorScore = 0;
+  const lowerSelector = element.selector.toLowerCase();
+  if (words.some((w) => lowerSelector.includes(w))) {
+    selectorScore = 0.2;
   }
+  const totalScore = nameScore * 0.6 + roleScore * 0.25 + selectorScore * 0.15;
+  return totalScore;
+}
+function explainMatch(query, element, score) {
+  const reasons = [];
+  const lowerQuery = query.toLowerCase();
+  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
+  if (element.name) {
+    const lowerName = element.name.toLowerCase();
+    if (lowerName === lowerQuery) {
+      reasons.push("exact name match");
+    } else if (lowerName.includes(lowerQuery)) {
+      reasons.push("name contains query");
+    } else if (words.some((w) => lowerName.includes(w))) {
+      const matchedWords = words.filter((w) => lowerName.includes(w));
+      reasons.push(`name contains: ${matchedWords.join(", ")}`);
+    } else if (stringSimilarity(query, element.name) > 0.5) {
+      reasons.push("similar name");
+    }
+  }
+  const lowerRole = element.role.toLowerCase();
+  if (lowerRole === lowerQuery || words.some((w) => w === lowerRole)) {
+    reasons.push(`role: ${element.role}`);
+  }
+  if (words.some((w) => element.selector.toLowerCase().includes(w))) {
+    reasons.push("selector match");
+  }
+  if (reasons.length === 0) {
+    reasons.push(`fuzzy match (score: ${score.toFixed(2)})`);
+  }
+  return reasons.join(", ");
+}
+function fuzzyMatchElements(query, elements, maxResults = 5) {
+  if (!query || query.length === 0) {
+    return [];
+  }
+  const THRESHOLD = 0.3;
+  const scored = elements.map((element) => ({
+    element,
+    score: scoreElement(query, element)
+  }));
+  return scored.filter((s) => s.score >= THRESHOLD).sort((a, b) => b.score - a.score).slice(0, maxResults).map((s) => ({
+    element: s.element,
+    score: s.score,
+    matchReason: explainMatch(query, s.element, s.score)
+  }));
+}
+
+// src/browser/hint-generator.ts
+var ACTION_ROLE_MAP = {
+  click: ["button", "link", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "option"],
+  fill: ["textbox", "searchbox", "textarea"],
+  type: ["textbox", "searchbox", "textarea"],
+  submit: ["button", "form"],
+  select: ["combobox", "listbox", "option"],
+  check: ["checkbox", "radio", "switch"],
+  uncheck: ["checkbox", "switch"],
+  focus: [],
+  // Any focusable element
+  hover: [],
+  // Any element
+  clear: ["textbox", "searchbox", "textarea"]
 };
+function extractIntent(selectors) {
+  const patterns = [];
+  let text = "";
+  for (const selector of selectors) {
+    if (selector.startsWith("ref:")) {
+      continue;
+    }
+    const idMatch = selector.match(/#([a-zA-Z0-9_-]+)/);
+    if (idMatch) {
+      patterns.push(idMatch[1]);
+    }
+    const ariaMatch = selector.match(/\[aria-label=["']([^"']+)["']\]/);
+    if (ariaMatch) {
+      patterns.push(ariaMatch[1]);
+    }
+    const testidMatch = selector.match(/\[data-testid=["']([^"']+)["']\]/);
+    if (testidMatch) {
+      patterns.push(testidMatch[1]);
+    }
+    const classMatch = selector.match(/\.([a-zA-Z0-9_-]+)/);
+    if (classMatch) {
+      patterns.push(classMatch[1]);
+    }
+  }
+  patterns.sort((a, b) => b.length - a.length);
+  text = patterns[0] ?? selectors[0] ?? "";
+  return { text, patterns };
+}
+function getHintType(selector) {
+  if (selector.startsWith("ref:")) return "ref";
+  if (selector.includes("data-testid")) return "testid";
+  if (selector.includes("aria-label")) return "aria";
+  if (selector.startsWith("#")) return "id";
+  return "css";
+}
+function getConfidence(score) {
+  if (score >= 0.8) return "high";
+  if (score >= 0.5) return "medium";
+  return "low";
+}
+function diversifyHints(candidates, maxHints) {
+  const hints = [];
+  const usedTypes = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    if (hints.length >= maxHints) break;
+    const refSelector = `ref:${candidate.element.ref}`;
+    const hintType = getHintType(refSelector);
+    if (!usedTypes.has(hintType)) {
+      hints.push({
+        selector: refSelector,
+        reason: candidate.matchReason,
+        confidence: getConfidence(candidate.score),
+        element: {
+          ref: candidate.element.ref,
+          role: candidate.element.role,
+          name: candidate.element.name,
+          disabled: candidate.element.disabled
+        }
+      });
+      usedTypes.add(hintType);
+    } else if (hints.length < maxHints) {
+      hints.push({
+        selector: refSelector,
+        reason: candidate.matchReason,
+        confidence: getConfidence(candidate.score),
+        element: {
+          ref: candidate.element.ref,
+          role: candidate.element.role,
+          name: candidate.element.name,
+          disabled: candidate.element.disabled
+        }
+      });
+    }
+  }
+  return hints;
+}
+async function generateHints(page, failedSelectors, actionType, maxHints = 3) {
+  let snapshot;
+  try {
+    snapshot = await page.snapshot();
+  } catch {
+    return [];
+  }
+  const intent = extractIntent(failedSelectors);
+  const roleFilter = ACTION_ROLE_MAP[actionType] ?? [];
+  let candidates = snapshot.interactiveElements;
+  if (roleFilter.length > 0) {
+    candidates = candidates.filter((el) => roleFilter.includes(el.role));
+  }
+  const matches = fuzzyMatchElements(intent.text, candidates, maxHints * 2);
+  if (matches.length === 0) {
+    return [];
+  }
+  return diversifyHints(matches, maxHints);
+}
 
 // src/browser/page.ts
 var DEFAULT_TIMEOUT = 3e4;
 var Page = class {
   cdp;
+  _targetId;
   rootNodeId = null;
   batchExecutor;
   emulationState = {};
@@ -467,10 +692,19 @@ var Page = class {
   frameExecutionContexts = /* @__PURE__ */ new Map();
   /** Current frame's execution context ID (null = main frame default) */
   currentFrameContextId = null;
-  constructor(cdp) {
+  /** Last matched selector from findElement (for selectorUsed tracking) */
+  _lastMatchedSelector;
+  constructor(cdp, targetId) {
     this.cdp = cdp;
+    this._targetId = targetId;
     this.batchExecutor = new BatchExecutor(this);
   }
+  /**
+   * Get the CDP target ID for this page
+   */
+  get targetId() {
+    return this._targetId;
+  }
   /**
    * Get the underlying CDP client for advanced operations.
    * Use with caution - prefer high-level Page methods when possible.
@@ -478,6 +712,13 @@ var Page = class {
   get cdpClient() {
     return this.cdp;
   }
+  /**
+   * Get the last matched selector from findElement (for selectorUsed tracking).
+   * Returns undefined if no selector has been matched yet.
+   */
+  getLastMatchedSelector() {
+    return this._lastMatchedSelector;
+  }
   /**
    * Initialize the page (enable required CDP domains)
    */
@@ -597,7 +838,9 @@ var Page = class {
       const element = await this.findElement(selector, options);
       if (!element) {
         if (options.optional) return false;
-        throw new ElementNotFoundError(selector);
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "click");
+        throw new ElementNotFoundError(selector, hints);
       }
       await this.scrollIntoView(element.nodeId);
       const submitResult = await this.evaluateInFrame(
@@ -633,7 +876,9 @@ var Page = class {
       const element = await this.findElement(selector, options);
       if (!element) {
         if (options.optional) return false;
-        throw new ElementNotFoundError(selector);
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "fill");
+        throw new ElementNotFoundError(selector, hints);
       }
       await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
       if (clear) {
@@ -711,7 +956,9 @@ var Page = class {
     const element = await this.findElement(selector, options);
     if (!element) {
       if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "select");
+      throw new ElementNotFoundError(selector, hints);
     }
     const values = Array.isArray(value) ? value : [value];
     await this.cdp.send("Runtime.evaluate", {
@@ -772,7 +1019,9 @@ var Page = class {
     const element = await this.findElement(selector, options);
     if (!element) {
       if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "check");
+      throw new ElementNotFoundError(selector, hints);
     }
     const result = await this.cdp.send("Runtime.evaluate", {
       expression: `(() => {
@@ -792,7 +1041,9 @@ var Page = class {
     const element = await this.findElement(selector, options);
     if (!element) {
       if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "uncheck");
+      throw new ElementNotFoundError(selector, hints);
     }
     const result = await this.cdp.send("Runtime.evaluate", {
       expression: `(() => {
@@ -812,13 +1063,40 @@ var Page = class {
    * - '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)
+   *
+   * When targeting a <form> element directly, uses form.requestSubmit() which fires
+   * the submit event and triggers HTML5 validation.
    */
   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);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "submit");
+      throw new ElementNotFoundError(selector, hints);
+    }
+    const isFormElement = await this.evaluateInFrame(
+      `(() => {
+        const el = document.querySelector(${JSON.stringify(element.selector)});
+        return el instanceof HTMLFormElement;
+      })()`
+    );
+    if (isFormElement.result.value) {
+      await this.evaluateInFrame(
+        `(() => {
+          const form = document.querySelector(${JSON.stringify(element.selector)});
+          if (form && form instanceof HTMLFormElement) {
+            form.requestSubmit();
+          }
+        })()`
+      );
+      if (shouldWait === true) {
+        await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_TIMEOUT });
+      } else if (shouldWait === "auto") {
+        await Promise.race([this.waitForNavigation({ timeout: 1e3, optional: true }), sleep2(500)]);
+      }
+      return true;
     }
     await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
     if (method.includes("enter")) {
@@ -889,7 +1167,9 @@ var Page = class {
     const element = await this.findElement(selector, options);
     if (!element) {
       if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "focus");
+      throw new ElementNotFoundError(selector, hints);
     }
     await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
     return true;
@@ -902,7 +1182,9 @@ var Page = class {
       const element = await this.findElement(selector, options);
       if (!element) {
         if (options.optional) return false;
-        throw new ElementNotFoundError(selector);
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "hover");
+        throw new ElementNotFoundError(selector, hints);
       }
       await this.scrollIntoView(element.nodeId);
       const box = await this.getBoxModel(element.nodeId);
@@ -1857,6 +2139,7 @@ var Page = class {
   async findElement(selectors, options = {}) {
     const { timeout = DEFAULT_TIMEOUT } = options;
     const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    this._lastMatchedSelector = void 0;
     for (const selector of selectorList) {
       if (selector.startsWith("ref:")) {
         const ref = selector.slice(4);
@@ -1873,6 +2156,7 @@ var Page = class {
             }
           );
           if (pushResult.nodeIds?.[0]) {
+            this._lastMatchedSelector = selector;
             return {
               nodeId: pushResult.nodeIds[0],
               backendNodeId,
@@ -1906,6 +2190,7 @@ var Page = class {
         "DOM.describeNode",
         { nodeId: queryResult.nodeId }
       );
+      this._lastMatchedSelector = result.selector;
       return {
         nodeId: queryResult.nodeId,
         backendNodeId: describeResult2.node.backendNodeId,
@@ -1933,6 +2218,7 @@ var Page = class {
       "DOM.describeNode",
       { nodeId: nodeResult.nodeId }
     );
+    this._lastMatchedSelector = result.selector;
     return {
       nodeId: nodeResult.nodeId,
       backendNodeId: describeResult.node.backendNodeId,
@@ -2039,14 +2325,24 @@ var Browser = class _Browser {
    * 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) {
+  async page(name, options) {
     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) {
+    if (options?.targetId) {
+      const targetExists = pageTargets.some((t) => t.targetId === options.targetId);
+      if (targetExists) {
+        targetId = options.targetId;
+      } else {
+        console.warn(`[browser-pilot] Target ${options.targetId} no longer exists, falling back`);
+        targetId = pageTargets.length > 0 ? pageTargets[0].targetId : (await this.cdp.send("Target.createTarget", {
+          url: "about:blank"
+        })).targetId;
+      }
+    } else if (pageTargets.length > 0) {
       targetId = pageTargets[0].targetId;
     } else {
       const result = await this.cdp.send("Target.createTarget", {
@@ -2055,7 +2351,7 @@ var Browser = class _Browser {
       targetId = result.targetId;
     }
     await this.cdp.attachToTarget(targetId);
-    const page = new Page(this.cdp);
+    const page = new Page(this.cdp, targetId);
     await page.init();
     this.pages.set(pageName, page);
     return page;
@@ -2068,7 +2364,7 @@ var Browser = class _Browser {
       url
     });
     await this.cdp.attachToTarget(result.targetId);
-    const page = new Page(this.cdp);
+    const page = new Page(this.cdp, result.targetId);
     await page.init();
     const name = `page-${this.pages.size + 1}`;
     this.pages.set(name, page);
@@ -2141,13 +2437,12 @@ function connect(options) {
 
 export {
   RequestInterceptor,
+  DEEP_QUERY_SCRIPT,
   waitForElement,
   waitForAnyElement,
   waitForNavigation,
   waitForNetworkIdle,
-  ElementNotFoundError,
-  TimeoutError,
-  NavigationError,
+  fuzzyMatchElements,
   Page,
   Browser,
   connect

package/dist/{chunk-6RB3GKQP.mjs → chunk-ZTQ37YQT.mjs}

@@ -1,3 +1,28 @@
+// src/browser/types.ts
+var ElementNotFoundError = class extends Error {
+  selectors;
+  hints;
+  constructor(selectors, hints) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    super(`Element not found: ${selectorList.join(", ")}`);
+    this.name = "ElementNotFoundError";
+    this.selectors = selectorList;
+    this.hints = hints;
+  }
+};
+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/actions/executor.ts
 var DEFAULT_TIMEOUT = 3e4;
 var BatchExecutor = class {
@@ -29,13 +54,15 @@ var BatchExecutor = class {
         });
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
+        const hints = error instanceof ElementNotFoundError ? error.hints : void 0;
         results.push({
           index: i,
           action: step.action,
           selector: step.selector,
           success: false,
           durationMs: Date.now() - stepStart,
-          error: errorMessage
+          error: errorMessage,
+          hints
         });
         if (onFail === "stop" && !step.optional) {
           return {
@@ -231,10 +258,12 @@ var BatchExecutor = class {
     }
   }
   /**
-   * Get the first selector if multiple were provided
-   * (actual used selector tracking would need to be implemented in Page)
+   * Get the actual selector that matched the element.
+   * Uses the last matched selector tracked by Page, falls back to first selector if unavailable.
    */
   getUsedSelector(selector) {
+    const matched = this.page.getLastMatchedSelector();
+    if (matched) return matched;
     return Array.isArray(selector) ? selector[0] : selector;
   }
 };
@@ -246,6 +275,9 @@ function addBatchToPage(page) {
 }
 
 export {
+  ElementNotFoundError,
+  TimeoutError,
+  NavigationError,
   BatchExecutor,
   addBatchToPage
 };