browser-pilot 0.0.10 → 0.0.12

package/dist/{chunk-7OSR2CAE.mjs → chunk-RUWAXHDX.mjs}

@@ -1,14 +1,17 @@
 import {
   createCDPClient
-} from "./chunk-BCOZUKWS.mjs";
+} from "./chunk-4MBSALQL.mjs";
 import {
   createProvider
-} from "./chunk-R3PS4PCM.mjs";
+} from "./chunk-BRAFQUMG.mjs";
 import {
+  ActionabilityError,
   BatchExecutor,
   ElementNotFoundError,
-  TimeoutError
-} from "./chunk-KKW2SZLV.mjs";
+  TimeoutError,
+  ensureActionable,
+  generateHints
+} from "./chunk-NLIARNEE.mjs";
 
 // src/audio/encoding.ts
 function bufferToBase64(data) {
@@ -1122,35 +1125,37 @@ var AudioOutput = class {
       let heardAudio = false;
       let lastSoundTime = 0;
       const startTime = Date.now();
-      const checkInterval = setInterval(async () => {
-        const elapsed = Date.now() - startTime;
-        if (elapsed > maxDuration) {
-          clearInterval(checkInterval);
-          this.onDiagHandler?.(`max duration reached (${maxDuration}ms), stopping`);
-          resolve(await this.stop());
-          return;
-        }
-        const latest = this.chunks[this.chunks.length - 1];
-        if (latest) {
-          const rms = calculateRMS(latest.left);
-          if (rms > silenceThreshold) {
-            if (!heardAudio) {
-              heardAudio = true;
-              this.onDiagHandler?.("first audio detected \u2014 silence countdown begins");
+      const checkInterval = setInterval(() => {
+        void (async () => {
+          const elapsed = Date.now() - startTime;
+          if (elapsed > maxDuration) {
+            clearInterval(checkInterval);
+            this.onDiagHandler?.(`max duration reached (${maxDuration}ms), stopping`);
+            resolve(await this.stop());
+            return;
+          }
+          const latest = this.chunks[this.chunks.length - 1];
+          if (latest) {
+            const rms = calculateRMS(latest.left);
+            if (rms > silenceThreshold) {
+              if (!heardAudio) {
+                heardAudio = true;
+                this.onDiagHandler?.("first audio detected \u2014 silence countdown begins");
+              }
+              lastSoundTime = Date.now();
             }
-            lastSoundTime = Date.now();
           }
-        }
-        if (!heardAudio && elapsed > noAudioTimeout) {
-          clearInterval(checkInterval);
-          this.onDiagHandler?.(`no audio detected after ${noAudioTimeout}ms, stopping early`);
-          resolve(await this.stop());
-          return;
-        }
-        if (heardAudio && Date.now() - lastSoundTime > silenceTimeout) {
-          clearInterval(checkInterval);
-          resolve(await this.stop());
-        }
+          if (!heardAudio && elapsed > noAudioTimeout) {
+            clearInterval(checkInterval);
+            this.onDiagHandler?.(`no audio detected after ${noAudioTimeout}ms, stopping early`);
+            resolve(await this.stop());
+            return;
+          }
+          if (heardAudio && Date.now() - lastSoundTime > silenceTimeout) {
+            clearInterval(checkInterval);
+            resolve(await this.stop());
+          }
+        })();
       }, 200);
     });
   }
@@ -1325,8 +1330,12 @@ var RequestInterceptor = class {
   boundHandleAuthRequired;
   constructor(cdp) {
     this.cdp = cdp;
-    this.boundHandleRequestPaused = this.handleRequestPaused.bind(this);
-    this.boundHandleAuthRequired = this.handleAuthRequired.bind(this);
+    this.boundHandleRequestPaused = (params) => {
+      void this.handleRequestPaused(params);
+    };
+    this.boundHandleAuthRequired = (params) => {
+      void this.handleAuthRequired(params);
+    };
   }
   /**
    * Enable request interception with optional patterns
@@ -1568,30 +1577,71 @@ async function isElementAttached(cdp, selector, contextId) {
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function isPageStatic(cdp, windowMs = 200, contextId) {
+  const params = {
+    expression: `new Promise(resolve => {
+      // If page is still loading, it's not static
+      if (document.readyState !== 'complete') { resolve(false); return; }
+      // Check for recent page load (navigationStart within last 1s = page just loaded)
+      try {
+        var nav = performance.getEntriesByType('navigation')[0];
+        if (nav && (performance.now() - nav.loadEventEnd) < 500) { resolve(false); return; }
+      } catch(e) {}
+      // Observe for DOM mutations
+      var seen = false;
+      var obs = new MutationObserver(function() { seen = true; });
+      obs.observe(document.documentElement, { childList: true, subtree: true, attributes: true });
+      setTimeout(function() { obs.disconnect(); resolve(!seen); }, ${windowMs});
+    })`,
+    returnByValue: true,
+    awaitPromise: true
+  };
+  if (contextId !== void 0) params["contextId"] = contextId;
+  try {
+    const result = await cdp.send("Runtime.evaluate", params);
+    return result.result.value === true;
+  } catch {
+    return false;
+  }
+}
 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;
+  const checkCondition = async () => {
     switch (state) {
       case "visible":
-        conditionMet = await isElementVisible(cdp, selector, contextId);
-        break;
+        return isElementVisible(cdp, selector, contextId);
       case "hidden":
-        conditionMet = !await isElementVisible(cdp, selector, contextId);
-        break;
+        return !await isElementVisible(cdp, selector, contextId);
       case "attached":
-        conditionMet = await isElementAttached(cdp, selector, contextId);
-        break;
+        return isElementAttached(cdp, selector, contextId);
       case "detached":
-        conditionMet = !await isElementAttached(cdp, selector, contextId);
-        break;
+        return !await isElementAttached(cdp, selector, contextId);
+      default: {
+        const _exhaustive = state;
+        throw new Error(`Unhandled wait state: ${_exhaustive}`);
+      }
     }
-    if (conditionMet) {
-      return { success: true, waitedMs: Date.now() - startTime };
+  };
+  if (await checkCondition()) {
+    return { success: true, waitedMs: Date.now() - startTime };
+  }
+  const waitingForPresence = state === "visible" || state === "attached";
+  if (waitingForPresence && timeout >= 300) {
+    const pageStatic = await isPageStatic(cdp, 200, contextId);
+    if (pageStatic) {
+      if (await checkCondition()) {
+        return { success: true, waitedMs: Date.now() - startTime };
+      }
+      return { success: false, waitedMs: Date.now() - startTime };
     }
+  }
+  while (Date.now() < deadline) {
     await sleep2(pollInterval);
+    if (await checkCondition()) {
+      return { success: true, waitedMs: Date.now() - startTime };
+    }
   }
   return { success: false, waitedMs: Date.now() - startTime };
 }
@@ -1599,28 +1649,46 @@ async function waitForAnyElement(cdp, selectors, options = {}) {
   const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
   const startTime = Date.now();
   const deadline = startTime + timeout;
+  const checkSelector = async (selector) => {
+    switch (state) {
+      case "visible":
+        return isElementVisible(cdp, selector, contextId);
+      case "hidden":
+        return !await isElementVisible(cdp, selector, contextId);
+      case "attached":
+        return isElementAttached(cdp, selector, contextId);
+      case "detached":
+        return !await isElementAttached(cdp, selector, contextId);
+      default: {
+        const _exhaustive = state;
+        throw new Error(`Unhandled wait state: ${_exhaustive}`);
+      }
+    }
+  };
+  for (const selector of selectors) {
+    if (await checkSelector(selector)) {
+      return { success: true, selector, waitedMs: Date.now() - startTime };
+    }
+  }
+  const waitingForPresence = state === "visible" || state === "attached";
+  if (waitingForPresence && timeout >= 300) {
+    const pageStatic = await isPageStatic(cdp, 200, contextId);
+    if (pageStatic) {
+      for (const selector of selectors) {
+        if (await checkSelector(selector)) {
+          return { success: true, selector, waitedMs: Date.now() - startTime };
+        }
+      }
+      return { success: false, waitedMs: Date.now() - startTime };
+    }
+  }
   while (Date.now() < deadline) {
+    await sleep2(pollInterval);
     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) {
+      if (await checkSelector(selector)) {
         return { success: true, selector, waitedMs: Date.now() - startTime };
       }
     }
-    await sleep2(pollInterval);
   }
   return { success: false, waitedMs: Date.now() - startTime };
 }
@@ -1667,6 +1735,13 @@ async function waitForNavigation(cdp, options = {}) {
       cdp.on("Page.navigatedWithinDocument", onSameDoc);
       cleanup.push(() => cdp.off("Page.navigatedWithinDocument", onSameDoc));
     }
+    const onLifecycle = (params) => {
+      if (params["name"] === "networkIdle") {
+        done(true);
+      }
+    };
+    cdp.on("Page.lifecycleEvent", onLifecycle);
+    cleanup.push(() => cdp.off("Page.lifecycleEvent", onLifecycle));
     const pollUrl = async () => {
       while (!resolved && Date.now() < startTime + timeout) {
         await sleep2(100);
@@ -1681,7 +1756,7 @@ async function waitForNavigation(cdp, options = {}) {
         }
       }
     };
-    pollUrl();
+    void pollUrl();
   });
 }
 async function waitForNetworkIdle(cdp, options = {}) {
@@ -1729,253 +1804,221 @@ async function waitForNetworkIdle(cdp, options = {}) {
   });
 }
 
-// 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;
-    }
-  }
-  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);
+// src/browser/keyboard.ts
+var US_KEYBOARD = {
+  // Letters (lowercase)
+  a: { key: "a", code: "KeyA", keyCode: 65, text: "a" },
+  b: { key: "b", code: "KeyB", keyCode: 66, text: "b" },
+  c: { key: "c", code: "KeyC", keyCode: 67, text: "c" },
+  d: { key: "d", code: "KeyD", keyCode: 68, text: "d" },
+  e: { key: "e", code: "KeyE", keyCode: 69, text: "e" },
+  f: { key: "f", code: "KeyF", keyCode: 70, text: "f" },
+  g: { key: "g", code: "KeyG", keyCode: 71, text: "g" },
+  h: { key: "h", code: "KeyH", keyCode: 72, text: "h" },
+  i: { key: "i", code: "KeyI", keyCode: 73, text: "i" },
+  j: { key: "j", code: "KeyJ", keyCode: 74, text: "j" },
+  k: { key: "k", code: "KeyK", keyCode: 75, text: "k" },
+  l: { key: "l", code: "KeyL", keyCode: 76, text: "l" },
+  m: { key: "m", code: "KeyM", keyCode: 77, text: "m" },
+  n: { key: "n", code: "KeyN", keyCode: 78, text: "n" },
+  o: { key: "o", code: "KeyO", keyCode: 79, text: "o" },
+  p: { key: "p", code: "KeyP", keyCode: 80, text: "p" },
+  q: { key: "q", code: "KeyQ", keyCode: 81, text: "q" },
+  r: { key: "r", code: "KeyR", keyCode: 82, text: "r" },
+  s: { key: "s", code: "KeyS", keyCode: 83, text: "s" },
+  t: { key: "t", code: "KeyT", keyCode: 84, text: "t" },
+  u: { key: "u", code: "KeyU", keyCode: 85, text: "u" },
+  v: { key: "v", code: "KeyV", keyCode: 86, text: "v" },
+  w: { key: "w", code: "KeyW", keyCode: 87, text: "w" },
+  x: { key: "x", code: "KeyX", keyCode: 88, text: "x" },
+  y: { key: "y", code: "KeyY", keyCode: 89, text: "y" },
+  z: { key: "z", code: "KeyZ", keyCode: 90, text: "z" },
+  // Letters (uppercase)
+  A: { key: "A", code: "KeyA", keyCode: 65, text: "A" },
+  B: { key: "B", code: "KeyB", keyCode: 66, text: "B" },
+  C: { key: "C", code: "KeyC", keyCode: 67, text: "C" },
+  D: { key: "D", code: "KeyD", keyCode: 68, text: "D" },
+  E: { key: "E", code: "KeyE", keyCode: 69, text: "E" },
+  F: { key: "F", code: "KeyF", keyCode: 70, text: "F" },
+  G: { key: "G", code: "KeyG", keyCode: 71, text: "G" },
+  H: { key: "H", code: "KeyH", keyCode: 72, text: "H" },
+  I: { key: "I", code: "KeyI", keyCode: 73, text: "I" },
+  J: { key: "J", code: "KeyJ", keyCode: 74, text: "J" },
+  K: { key: "K", code: "KeyK", keyCode: 75, text: "K" },
+  L: { key: "L", code: "KeyL", keyCode: 76, text: "L" },
+  M: { key: "M", code: "KeyM", keyCode: 77, text: "M" },
+  N: { key: "N", code: "KeyN", keyCode: 78, text: "N" },
+  O: { key: "O", code: "KeyO", keyCode: 79, text: "O" },
+  P: { key: "P", code: "KeyP", keyCode: 80, text: "P" },
+  Q: { key: "Q", code: "KeyQ", keyCode: 81, text: "Q" },
+  R: { key: "R", code: "KeyR", keyCode: 82, text: "R" },
+  S: { key: "S", code: "KeyS", keyCode: 83, text: "S" },
+  T: { key: "T", code: "KeyT", keyCode: 84, text: "T" },
+  U: { key: "U", code: "KeyU", keyCode: 85, text: "U" },
+  V: { key: "V", code: "KeyV", keyCode: 86, text: "V" },
+  W: { key: "W", code: "KeyW", keyCode: 87, text: "W" },
+  X: { key: "X", code: "KeyX", keyCode: 88, text: "X" },
+  Y: { key: "Y", code: "KeyY", keyCode: 89, text: "Y" },
+  Z: { key: "Z", code: "KeyZ", keyCode: 90, text: "Z" },
+  // Numbers
+  "0": { key: "0", code: "Digit0", keyCode: 48, text: "0" },
+  "1": { key: "1", code: "Digit1", keyCode: 49, text: "1" },
+  "2": { key: "2", code: "Digit2", keyCode: 50, text: "2" },
+  "3": { key: "3", code: "Digit3", keyCode: 51, text: "3" },
+  "4": { key: "4", code: "Digit4", keyCode: 52, text: "4" },
+  "5": { key: "5", code: "Digit5", keyCode: 53, text: "5" },
+  "6": { key: "6", code: "Digit6", keyCode: 54, text: "6" },
+  "7": { key: "7", code: "Digit7", keyCode: 55, text: "7" },
+  "8": { key: "8", code: "Digit8", keyCode: 56, text: "8" },
+  "9": { key: "9", code: "Digit9", keyCode: 57, text: "9" },
+  // Punctuation
+  " ": { key: " ", code: "Space", keyCode: 32, text: " " },
+  ".": { key: ".", code: "Period", keyCode: 190, text: "." },
+  ",": { key: ",", code: "Comma", keyCode: 188, text: "," },
+  "/": { key: "/", code: "Slash", keyCode: 191, text: "/" },
+  ";": { key: ";", code: "Semicolon", keyCode: 186, text: ";" },
+  "'": { key: "'", code: "Quote", keyCode: 222, text: "'" },
+  "[": { key: "[", code: "BracketLeft", keyCode: 219, text: "[" },
+  "]": { key: "]", code: "BracketRight", keyCode: 221, text: "]" },
+  "\\": { key: "\\", code: "Backslash", keyCode: 220, text: "\\" },
+  "-": { key: "-", code: "Minus", keyCode: 189, text: "-" },
+  "=": { key: "=", code: "Equal", keyCode: 187, text: "=" },
+  "`": { key: "`", code: "Backquote", keyCode: 192, text: "`" },
+  // Shifted punctuation
+  "!": { key: "!", code: "Digit1", keyCode: 49, text: "!" },
+  "@": { key: "@", code: "Digit2", keyCode: 50, text: "@" },
+  "#": { key: "#", code: "Digit3", keyCode: 51, text: "#" },
+  $: { key: "$", code: "Digit4", keyCode: 52, text: "$" },
+  "%": { key: "%", code: "Digit5", keyCode: 53, text: "%" },
+  "^": { key: "^", code: "Digit6", keyCode: 54, text: "^" },
+  "&": { key: "&", code: "Digit7", keyCode: 55, text: "&" },
+  "*": { key: "*", code: "Digit8", keyCode: 56, text: "*" },
+  "(": { key: "(", code: "Digit9", keyCode: 57, text: "(" },
+  ")": { key: ")", code: "Digit0", keyCode: 48, text: ")" },
+  _: { key: "_", code: "Minus", keyCode: 189, text: "_" },
+  "+": { key: "+", code: "Equal", keyCode: 187, text: "+" },
+  "{": { key: "{", code: "BracketLeft", keyCode: 219, text: "{" },
+  "}": { key: "}", code: "BracketRight", keyCode: 221, text: "}" },
+  "|": { key: "|", code: "Backslash", keyCode: 220, text: "|" },
+  ":": { key: ":", code: "Semicolon", keyCode: 186, text: ":" },
+  '"': { key: '"', code: "Quote", keyCode: 222, text: '"' },
+  "<": { key: "<", code: "Comma", keyCode: 188, text: "<" },
+  ">": { key: ">", code: "Period", keyCode: 190, text: ">" },
+  "?": { key: "?", code: "Slash", keyCode: 191, text: "?" },
+  "~": { key: "~", code: "Backquote", keyCode: 192, text: "~" },
+  // Special keys (non-text: use rawKeyDown, no text field)
+  Enter: { key: "Enter", code: "Enter", keyCode: 13 },
+  Tab: { key: "Tab", code: "Tab", keyCode: 9 },
+  Backspace: { key: "Backspace", code: "Backspace", keyCode: 8 },
+  Delete: { key: "Delete", code: "Delete", keyCode: 46 },
+  Escape: { key: "Escape", code: "Escape", keyCode: 27 },
+  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 },
+  Home: { key: "Home", code: "Home", keyCode: 36 },
+  End: { key: "End", code: "End", keyCode: 35 },
+  PageUp: { key: "PageUp", code: "PageUp", keyCode: 33 },
+  PageDown: { key: "PageDown", code: "PageDown", keyCode: 34 }
+};
+var MODIFIER_CODES = {
+  Control: "ControlLeft",
+  Shift: "ShiftLeft",
+  Alt: "AltLeft",
+  Meta: "MetaLeft"
+};
+var MODIFIER_KEY_CODES = {
+  Control: 17,
+  Shift: 16,
+  Alt: 18,
+  Meta: 91
+};
+function computeModifierBitmask(modifiers) {
+  let mask = 0;
+  if (modifiers.includes("Alt")) mask |= 1;
+  if (modifiers.includes("Control")) mask |= 2;
+  if (modifiers.includes("Meta")) mask |= 4;
+  if (modifiers.includes("Shift")) mask |= 8;
+  return mask;
 }
-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;
-    }
-  }
-  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;
+function parseShortcut(combo) {
+  const parts = combo.split("+");
+  if (parts.length < 2) {
+    throw new Error(
+      `Invalid shortcut "${combo}": must contain at least one modifier and a key (e.g. "Control+a").`
+    );
   }
-  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]);
+  const key = parts[parts.length - 1];
+  const modifiers = [];
+  const validModifiers = new Set(Object.keys(MODIFIER_CODES));
+  for (let i = 0; i < parts.length - 1; i++) {
+    const mod = parts[i];
+    if (!validModifiers.has(mod)) {
+      throw new Error(
+        `Invalid modifier "${mod}" in shortcut "${combo}". Valid modifiers: ${[...validModifiers].join(", ")}`
+      );
     }
+    modifiers.push(mod);
   }
-  patterns.sort((a, b) => b.length - a.length);
-  text = patterns[0] ?? selectors[0] ?? "";
-  return { text, patterns };
+  return { modifiers, key };
 }
-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
-        }
+
+// src/browser/page.ts
+var DEFAULT_TIMEOUT = 3e4;
+var EVENT_LISTENER_TRACKER_SCRIPT = `(() => {
+  if (globalThis.__bpEventListenerTrackerInstalled) return;
+  Object.defineProperty(globalThis, '__bpEventListenerTrackerInstalled', {
+    value: true,
+    configurable: true,
+  });
+
+  const storeKey = '__bpEventListeners';
+  const originalAddEventListener = EventTarget.prototype.addEventListener;
+  const originalRemoveEventListener = EventTarget.prototype.removeEventListener;
+
+  function ensureStore(target) {
+    if (!Object.prototype.hasOwnProperty.call(target, storeKey)) {
+      Object.defineProperty(target, storeKey, {
+        value: Object.create(null),
+        configurable: true,
       });
     }
+    return target[storeKey];
   }
-  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;
+  EventTarget.prototype.addEventListener = function(type, listener, options) {
+    try {
+      if (listener) {
+        const store = ensureStore(this);
+        const bucket = store[type] || (store[type] = []);
+        const capture =
+          typeof options === 'boolean' ? options : !!(options && options.capture);
+        const exists = bucket.some((entry) => entry.listener === listener && entry.capture === capture);
+        if (!exists) {
+          bucket.push({ listener, capture });
+        }
+      }
+    } catch {}
+
+    return originalAddEventListener.call(this, type, listener, options);
+  };
+
+  EventTarget.prototype.removeEventListener = function(type, listener, options) {
+    try {
+      const store = this[storeKey];
+      const bucket = store && store[type];
+      const capture =
+        typeof options === 'boolean' ? options : !!(options && options.capture);
+      if (Array.isArray(bucket)) {
+        store[type] = bucket.filter((entry) => {
+          return !(entry.listener === listener && entry.capture === capture);
+        });
+      }
+    } catch {}
+
+    return originalRemoveEventListener.call(this, type, listener, options);
+  };
+})();`;
 var Page = class {
   cdp;
   _targetId;
@@ -1997,8 +2040,12 @@ var Page = class {
   frameExecutionContexts = /* @__PURE__ */ new Map();
   /** Current frame's execution context ID (null = main frame default) */
   currentFrameContextId = null;
+  /** Frame selector if context acquisition failed (cross-origin/sandboxed) */
+  brokenFrame = null;
   /** Last matched selector from findElement (for selectorUsed tracking) */
   _lastMatchedSelector;
+  /** Last snapshot for stale ref recovery */
+  lastSnapshot;
   /** Audio input controller (lazy-initialized) */
   _audioInput;
   /** Audio output controller (lazy-initialized) */
@@ -2043,17 +2090,34 @@ var Page = class {
       for (const [frameId, ctxId] of this.frameExecutionContexts.entries()) {
         if (ctxId === contextId) {
           this.frameExecutionContexts.delete(frameId);
+          if (this.currentFrameContextId === contextId) {
+            this.currentFrameContextId = null;
+          }
           break;
         }
       }
     });
-    this.cdp.on("Page.javascriptDialogOpening", this.handleDialogOpening.bind(this));
+    this.cdp.on("Page.javascriptDialogOpening", (params) => {
+      void this.handleDialogOpening(params);
+    });
     await Promise.all([
       this.cdp.send("Page.enable"),
       this.cdp.send("DOM.enable"),
       this.cdp.send("Runtime.enable"),
       this.cdp.send("Network.enable")
     ]);
+    await this.installEventListenerTracker();
+  }
+  async installEventListenerTracker() {
+    await this.cdp.send("Page.addScriptToEvaluateOnNewDocument", {
+      source: EVENT_LISTENER_TRACKER_SCRIPT
+    });
+    try {
+      await this.cdp.send("Runtime.evaluate", {
+        expression: EVENT_LISTENER_TRACKER_SCRIPT
+      });
+    } catch {
+    }
   }
   // ============ Navigation ============
   /**
@@ -2069,6 +2133,9 @@ var Page = class {
     }
     this.rootNodeId = null;
     this.refMap.clear();
+    this.currentFrame = null;
+    this.currentFrameContextId = null;
+    this.frameContexts.clear();
   }
   /**
    * Get the current URL
@@ -2139,8 +2206,9 @@ var Page = class {
   /**
    * 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.
+   * Uses CDP mouse events (mouseMoved + mousePressed + mouseReleased) to
+   * simulate a real click. Real mouse events on submit buttons naturally
+   * trigger native form submission — no JS dispatch needed.
    */
   async click(selector, options = {}) {
     return this.withStaleNodeRetry(async () => {
@@ -2152,27 +2220,55 @@ var Page = class {
         throw new ElementNotFoundError(selector, hints);
       }
       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 };
+      const objectId = await this.resolveObjectId(element.nodeId);
+      try {
+        await ensureActionable(this.cdp, objectId, ["visible", "enabled", "stable"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT
+        });
+      } catch (e) {
+        if (options.optional) return false;
+        throw e;
+      }
+      let clickX;
+      let clickY;
+      try {
+        const { quads } = await this.cdp.send("DOM.getContentQuads", {
+          objectId
+        });
+        if (quads?.length > 0) {
+          const quad = quads[0];
+          clickX = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
+          clickY = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+        } else {
+          throw new Error("No quads");
+        }
+      } catch {
+        const box = await this.getBoxModel(element.nodeId);
+        if (!box) throw new Error("Could not get element position");
+        clickX = box.content[0] + box.width / 2;
+        clickY = box.content[1] + box.height / 2;
+      }
+      const hitTargetCoordinates = this.currentFrame ? void 0 : { x: clickX, y: clickY };
+      const HIT_TARGET_RETRIES = 3;
+      const HIT_TARGET_DELAY = 100;
+      for (let attempt = 0; attempt < HIT_TARGET_RETRIES; attempt++) {
+        try {
+          await ensureActionable(this.cdp, objectId, ["hitTarget"], {
+            timeout: options.timeout ?? DEFAULT_TIMEOUT,
+            coordinates: hitTargetCoordinates
+          });
+          break;
+        } catch (e) {
+          if (options.optional) return false;
+          if (e instanceof ActionabilityError && e.failureType === "hitTarget" && attempt < HIT_TARGET_RETRIES - 1) {
+            await sleep3(HIT_TARGET_DELAY);
+            await this.cdp.send("DOM.scrollIntoViewIfNeeded", { nodeId: element.nodeId });
+            continue;
           }
-          return { isSubmit: false };
-        })()`
-      );
-      const isSubmit = submitResult.result.value?.isSubmit;
-      if (!isSubmit) {
-        await this.clickElement(element.nodeId);
+          throw e;
+        }
       }
+      await this.clickElement(element.nodeId);
       return true;
     });
   }
@@ -2180,7 +2276,7 @@ var Page = class {
    * Fill an input field (clears first by default)
    */
   async fill(selector, value, options = {}) {
-    const { clear = true, blur = false } = options;
+    const { blur = false } = options;
     return this.withStaleNodeRetry(async () => {
       const element = await this.findElement(selector, options);
       if (!element) {
@@ -2189,71 +2285,158 @@ var Page = class {
         const hints = await generateHints(this, selectorList, "fill");
         throw new ElementNotFoundError(selector, hints);
       }
-      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 InputEvent('input', {
-                bubbles: true,
-                cancelable: true,
-                inputType: 'deleteContent'
-              }));
-            }
-          })()`
-        );
+      const { object } = await this.cdp.send("DOM.resolveNode", {
+        nodeId: element.nodeId
+      });
+      const objectId = object.objectId;
+      try {
+        await ensureActionable(this.cdp, objectId, ["visible", "enabled", "editable"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT
+        });
+      } catch (e) {
+        if (options.optional) return false;
+        throw e;
       }
-      await this.cdp.send("Input.insertText", { text: value });
-      await this.evaluateInFrame(
-        `(() => {
-          const el = document.querySelector(${JSON.stringify(element.selector)});
-          if (el) {
-            el.dispatchEvent(new InputEvent('input', {
-              bubbles: true,
-              cancelable: true,
-              inputType: 'insertText',
-              data: ${JSON.stringify(value)}
-            }));
-            el.dispatchEvent(new Event('change', { bubbles: true }));
+      const tagInfo = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function() {
+            return { tagName: this.tagName?.toLowerCase() || '', inputType: (this.type || '').toLowerCase() };
+          }`,
+        returnByValue: true
+      });
+      const { tagName, inputType } = tagInfo.result.value;
+      const specialInputTypes = /* @__PURE__ */ new Set([
+        "date",
+        "datetime-local",
+        "month",
+        "week",
+        "time",
+        "color",
+        "range",
+        "file"
+      ]);
+      const isSpecialInput = tagName === "input" && specialInputTypes.has(inputType);
+      if (isSpecialInput) {
+        await this.cdp.send("Runtime.callFunctionOn", {
+          objectId,
+          functionDeclaration: `function(val) {
+            this.value = val;
+            this.dispatchEvent(new Event('input', { bubbles: true }));
+            this.dispatchEvent(new Event('change', { bubbles: true }));
+          }`,
+          arguments: [{ value }],
+          returnByValue: true
+        });
+      } else {
+        await this.selectEditableContent(objectId);
+        if (value === "") {
+          await this.dispatchKey("Delete");
+        } else {
+          await this.cdp.send("Input.insertText", { text: value });
+        }
+      }
+      if (options.verify !== false) {
+        let actualValue = await this.readEditableValue(objectId);
+        if (actualValue !== value && !isSpecialInput) {
+          if (value === "") {
+            await this.clearEditableSelection(objectId, "Backspace");
+          } else {
+            await this.typeEditableFallback(element.nodeId, objectId, value);
           }
-        })()`
-      );
+          actualValue = await this.readEditableValue(objectId);
+        }
+        if (actualValue !== value) {
+          if (options.optional) return false;
+          throw new Error(
+            `Fill value did not stick. Expected ${JSON.stringify(value)} but got ${JSON.stringify(actualValue)}.`
+          );
+        }
+      }
       if (blur) {
-        await this.evaluateInFrame(
-          `document.querySelector(${JSON.stringify(element.selector)})?.blur()`
-        );
+        await this.cdp.send("Runtime.callFunctionOn", {
+          objectId,
+          functionDeclaration: "function() { this.blur(); }"
+        });
       }
       return true;
     });
   }
   /**
    * Type text character by character (for autocomplete fields, etc.)
+   *
+   * Uses proper keyDown/rawKeyDown distinction with US keyboard layout.
+   * Printable chars use 'keyDown' with text, non-text keys use 'rawKeyDown',
+   * and non-layout chars (emoji, CJK) fall back to Input.insertText.
    */
   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 sleep3(delay);
+    return this.withStaleNodeRetry(async () => {
+      const { delay = 50 } = options;
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        throw new ElementNotFoundError(selector);
       }
-    }
-    return true;
+      const objectId = await this.resolveObjectId(element.nodeId);
+      try {
+        await ensureActionable(this.cdp, objectId, ["visible", "enabled"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT
+        });
+      } catch (e) {
+        if (options.optional) return false;
+        throw e;
+      }
+      await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
+      for (const char of text) {
+        const def = US_KEYBOARD[char];
+        if (def) {
+          if (def.text !== void 0) {
+            await this.cdp.send("Input.dispatchKeyEvent", {
+              type: "keyDown",
+              key: def.key,
+              code: def.code,
+              text: def.text,
+              unmodifiedText: def.text,
+              windowsVirtualKeyCode: def.keyCode,
+              modifiers: 0,
+              autoRepeat: false,
+              location: def.location ?? 0,
+              isKeypad: false
+            });
+          } else {
+            await this.cdp.send("Input.dispatchKeyEvent", {
+              type: "rawKeyDown",
+              key: def.key,
+              code: def.code,
+              windowsVirtualKeyCode: def.keyCode,
+              modifiers: 0,
+              autoRepeat: false,
+              location: def.location ?? 0,
+              isKeypad: false
+            });
+          }
+          await this.cdp.send("Input.dispatchKeyEvent", {
+            type: "keyUp",
+            key: def.key,
+            code: def.code,
+            windowsVirtualKeyCode: def.keyCode,
+            modifiers: 0,
+            location: def.location ?? 0
+          });
+        } else {
+          await this.cdp.send("Input.insertText", { text: char });
+        }
+        if (delay > 0) {
+          await sleep3(delay);
+        }
+      }
+      if (options.blur) {
+        await this.cdp.send("Runtime.callFunctionOn", {
+          objectId,
+          functionDeclaration: "function() { this.blur(); }"
+        });
+      }
+      return true;
+    });
   }
   async select(selectorOrConfig, valueOrOptions, maybeOptions) {
     if (typeof selectorOrConfig === "object" && !Array.isArray(selectorOrConfig) && "trigger" in selectorOrConfig) {
@@ -2262,108 +2445,231 @@ var Page = class {
     const selector = selectorOrConfig;
     const value = valueOrOptions;
     const options = maybeOptions ?? {};
-    const element = await this.findElement(selector, options);
-    if (!element) {
-      if (options.optional) return false;
-      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", {
-      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 this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        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];
+      const objectId = await this.resolveObjectId(element.nodeId);
+      try {
+        await this.scrollIntoView(element.nodeId);
+        await ensureActionable(this.cdp, objectId, ["visible", "enabled"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT
+        });
+      } catch (e) {
+        if (options.optional) return false;
+        throw e;
+      }
+      const metadata = await this.getNativeSelectMetadata(objectId, values);
+      if (!metadata.isSelect) {
+        throw new Error("select() target must be a native <select> element");
+      }
+      if (metadata.missing.length > 0) {
+        throw new Error(`No option found for: ${metadata.missing.join(", ")}`);
+      }
+      if (metadata.disabled.length > 0) {
+        throw new Error(`Cannot select disabled option(s): ${metadata.disabled.join(", ")}`);
+      }
+      if (!metadata.multiple && metadata.targetIndexes.length > 1) {
+        throw new Error("Cannot select multiple values on a single-select element");
+      }
+      const expectedValues = metadata.targetIndexes.map((idx) => metadata.options[idx].value);
+      if (this.selectValuesMatch(metadata.selectedValues, expectedValues, metadata.multiple)) {
         return true;
-      })()`,
-      returnByValue: true
+      }
+      if (!metadata.multiple && metadata.targetIndexes.length === 1) {
+        await this.applyNativeSelectByKeyboard(
+          element.nodeId,
+          objectId,
+          metadata.currentIndex,
+          metadata.targetIndexes[0]
+        );
+      }
+      let selectedValues = await this.readNativeSelectValues(objectId);
+      if (!this.selectValuesMatch(selectedValues, expectedValues, metadata.multiple)) {
+        await this.applyNativeSelectFallback(objectId, metadata.targetIndexes);
+        selectedValues = await this.readNativeSelectValues(objectId);
+      }
+      if (!this.selectValuesMatch(selectedValues, expectedValues, metadata.multiple)) {
+        await this.applyRecordedSelectFallback(objectId, metadata.targetIndexes);
+        selectedValues = await this.readNativeSelectValues(objectId);
+      }
+      if (!this.selectValuesMatch(selectedValues, expectedValues, metadata.multiple)) {
+        if (options.optional) return false;
+        throw new Error(
+          `Select value did not stick. Expected ${expectedValues.join(", ") || "(empty)"} but got ${selectedValues.join(", ") || "(empty)"}.`
+        );
+      }
+      return 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 sleep3(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
+    return this.withStaleNodeRetry(async () => {
+      await this.click(trigger, options);
+      const optionSelectors = Array.isArray(option) ? option : [option];
+      await waitForAnyElement(this.cdp, optionSelectors, {
+        state: "visible",
+        timeout: 500,
+        contextId: this.currentFrameContextId ?? void 0
+      }).catch(() => sleep3(100));
+      const optionHandle = await this.evaluateInFrame(
+        `(() => {
+          const selectors = ${JSON.stringify(optionSelectors)};
+          const wanted = ${JSON.stringify(value)};
+          const mode = ${JSON.stringify(match)};
+
+          for (const selector of selectors) {
+            const candidates = document.querySelectorAll(selector);
+            for (const candidate of candidates) {
+              const text = candidate.textContent?.trim() || '';
+              const candidateValue =
+                candidate.getAttribute?.('data-value') ??
+                candidate.getAttribute?.('value') ??
+                candidate.value ??
+                '';
+              const matches =
+                mode === 'value'
+                  ? candidateValue === wanted
+                  : mode === 'contains'
+                    ? text.includes(wanted)
+                    : text === wanted;
+
+              if (matches) {
+                return candidate;
+              }
+            }
+          }
+
+          return null;
+        })()`,
+        { returnByValue: false }
+      );
+      if (!optionHandle.result.objectId) {
+        if (options.optional) return false;
+        throw new ElementNotFoundError(`Option with ${match} "${value}"`);
+      }
+      const nodeResult = await this.cdp.send("DOM.requestNode", {
+        objectId: optionHandle.result.objectId
+      });
+      if (!nodeResult.nodeId) {
+        if (options.optional) return false;
+        throw new ElementNotFoundError(`Option with ${match} "${value}"`);
+      }
+      await this.scrollIntoView(nodeResult.nodeId);
+      await ensureActionable(
+        this.cdp,
+        optionHandle.result.objectId,
+        ["visible", "enabled", "stable"],
+        {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT
+        }
+      );
+      await this.clickElement(nodeResult.nodeId);
+      return 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
+   * Check a checkbox or radio button using real mouse click.
+   * No-op if already checked. Verifies state changed after click.
    */
   async check(selector, options = {}) {
-    const element = await this.findElement(selector, options);
-    if (!element) {
-      if (options.optional) return false;
-      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: `(() => {
-        const el = document.querySelector(${JSON.stringify(element.selector)});
-        if (!el) return false;
-        if (!el.checked) el.click();
-        return true;
-      })()`,
-      returnByValue: true
+    return this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "check");
+        throw new ElementNotFoundError(selector, hints);
+      }
+      const { object } = await this.cdp.send("DOM.resolveNode", {
+        nodeId: element.nodeId
+      });
+      try {
+        await ensureActionable(this.cdp, object.objectId, ["visible", "enabled"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT
+        });
+      } catch (e) {
+        if (options.optional) return false;
+        throw e;
+      }
+      const before = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId: object.objectId,
+        functionDeclaration: "function() { return !!this.checked; }",
+        returnByValue: true
+      });
+      if (before.result.value) return true;
+      await this.scrollIntoView(element.nodeId);
+      await this.clickElement(element.nodeId);
+      const after = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId: object.objectId,
+        functionDeclaration: "function() { return !!this.checked; }",
+        returnByValue: true
+      });
+      if (!after.result.value) {
+        throw new Error("Clicking the checkbox did not change its state");
+      }
+      return true;
     });
-    return result.result.value;
   }
   /**
-   * Uncheck a checkbox
+   * Uncheck a checkbox using real mouse click.
+   * No-op if already unchecked. Radio buttons can't be unchecked (returns true).
    */
   async uncheck(selector, options = {}) {
-    const element = await this.findElement(selector, options);
-    if (!element) {
-      if (options.optional) return false;
-      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: `(() => {
-        const el = document.querySelector(${JSON.stringify(element.selector)});
-        if (!el) return false;
-        if (el.checked) el.click();
-        return true;
-      })()`,
-      returnByValue: true
+    return this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "uncheck");
+        throw new ElementNotFoundError(selector, hints);
+      }
+      const { object } = await this.cdp.send("DOM.resolveNode", {
+        nodeId: element.nodeId
+      });
+      try {
+        await ensureActionable(this.cdp, object.objectId, ["visible", "enabled"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT
+        });
+      } catch (e) {
+        if (options.optional) return false;
+        throw e;
+      }
+      const isRadio = await this.cdp.send(
+        "Runtime.callFunctionOn",
+        {
+          objectId: object.objectId,
+          functionDeclaration: 'function() { return this.type === "radio"; }',
+          returnByValue: true
+        }
+      );
+      if (isRadio.result.value) return true;
+      const before = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId: object.objectId,
+        functionDeclaration: "function() { return !!this.checked; }",
+        returnByValue: true
+      });
+      if (!before.result.value) return true;
+      await this.scrollIntoView(element.nodeId);
+      await this.clickElement(element.nodeId);
+      const after = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId: object.objectId,
+        functionDeclaration: "function() { return !!this.checked; }",
+        returnByValue: true
+      });
+      if (after.result.value) {
+        throw new Error("Clicking the checkbox did not change its state");
+      }
+      return true;
     });
-    return result.result.value;
   }
   /**
    * Submit a form (tries Enter key first, then click)
@@ -2377,97 +2683,100 @@ var Page = class {
    * 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;
-      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 }), sleep3(500)]);
+    return this.withStaleNodeRetry(async () => {
+      const { method = "enter+click", waitForNavigation: shouldWait = "auto" } = options;
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "submit");
+        throw new ElementNotFoundError(selector, hints);
       }
-      return true;
-    }
-    await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
-    if (method.includes("enter")) {
-      await this.press("Enter");
-      if (shouldWait === true) {
-        try {
+      const objectId = await this.resolveObjectId(element.nodeId);
+      const isFormElement = await this.cdp.send(
+        "Runtime.callFunctionOn",
+        {
+          objectId,
+          functionDeclaration: "function() { return this instanceof HTMLFormElement; }",
+          returnByValue: true
+        }
+      );
+      if (isFormElement.result.value) {
+        await this.cdp.send("Runtime.callFunctionOn", {
+          objectId,
+          functionDeclaration: `function() {
+            if (typeof this.requestSubmit === 'function') {
+              this.requestSubmit();
+            } else {
+              this.submit();
+            }
+          }`
+        });
+        if (shouldWait === true) {
           await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_TIMEOUT });
-          return true;
-        } catch {
+        } else if (shouldWait === "auto") {
+          await Promise.race([
+            this.waitForNavigation({ timeout: 2e3, optional: true }).then(
+              () => "navigation"
+            ),
+            this.waitForDOMMutation({ timeout: 1e3 }).then(() => "mutation"),
+            sleep3(1500).then(() => "timeout")
+          ]);
         }
-      } else if (shouldWait === "auto") {
-        const navigationDetected = await Promise.race([
-          this.waitForNavigation({ timeout: 1e3, optional: true }).then(
-            (success) => success ? "nav" : null
-          ),
-          sleep3(500).then(() => "timeout")
-        ]);
-        if (navigationDetected === "nav") {
+        return true;
+      }
+      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: 2e3, optional: true }).then(
+              (success) => success ? "nav" : null
+            ),
+            this.waitForDOMMutation({ timeout: 1e3 }).then(() => "mutation"),
+            sleep3(1500).then(() => "timeout")
+          ]);
+          if (navigationDetected === "nav") {
+            return true;
+          }
+        } else if (method === "enter") {
           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 sleep3(100);
+      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 sleep3(100);
+        }
       }
+      return true;
+    });
+  }
+  /**
+   * Press a key, optionally with modifier keys held down
+   */
+  async press(key, options) {
+    const modifiers = options?.modifiers;
+    if (modifiers && modifiers.length > 0) {
+      await this.dispatchKeyWithModifiers(key, modifiers);
+    } else {
+      await this.dispatchKey(key);
     }
-    return true;
   }
   /**
-   * Press a key
+   * Execute a keyboard shortcut (e.g. "Control+a", "Meta+Shift+z")
    */
-  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
-    });
+  async shortcut(combo) {
+    const { modifiers, key } = parseShortcut(combo);
+    await this.dispatchKeyWithModifiers(key, modifiers);
   }
   /**
    * Focus an element
@@ -2496,13 +2805,37 @@ var Page = class {
         throw new ElementNotFoundError(selector, hints);
       }
       await this.scrollIntoView(element.nodeId);
-      const box = await this.getBoxModel(element.nodeId);
-      if (!box) {
+      const objectId = await this.resolveObjectId(element.nodeId);
+      try {
+        await ensureActionable(this.cdp, objectId, ["visible", "stable"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT
+        });
+      } catch (e) {
         if (options.optional) return false;
-        throw new Error("Could not get element box model");
+        throw e;
+      }
+      let x;
+      let y;
+      try {
+        const { quads } = await this.cdp.send("DOM.getContentQuads", {
+          objectId
+        });
+        if (quads?.length > 0) {
+          const quad = quads[0];
+          x = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
+          y = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+        } else {
+          throw new Error("No quads");
+        }
+      } catch {
+        const box = await this.getBoxModel(element.nodeId);
+        if (!box) {
+          if (options.optional) return false;
+          throw new Error("Could not get element position");
+        }
+        x = box.content[0] + box.width / 2;
+        y = box.content[1] + box.height / 2;
       }
-      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,
@@ -2560,15 +2893,19 @@ var Page = class {
     if (descResult.node.frameId) {
       const frameId = descResult.node.frameId;
       const { timeout = DEFAULT_TIMEOUT } = options;
-      const pollInterval = 50;
-      const deadline = Date.now() + timeout;
       let contextId = this.frameExecutionContexts.get(frameId);
-      while (!contextId && Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
-        contextId = this.frameExecutionContexts.get(frameId);
+      if (!contextId) {
+        contextId = await this.waitForFrameContext(frameId, Math.min(timeout, 2e3));
       }
       if (contextId) {
         this.currentFrameContextId = contextId;
+        this.brokenFrame = null;
+      } else {
+        const frameKey2 = Array.isArray(selector) ? selector[0] : selector;
+        this.brokenFrame = frameKey2;
+        console.warn(
+          `[browser-pilot] Frame "${frameKey2}" execution context unavailable. JS evaluation will fail in this frame. DOM operations may still work.`
+        );
       }
     }
     this.refMap.clear();
@@ -2581,6 +2918,7 @@ var Page = class {
     this.currentFrame = null;
     this.rootNodeId = null;
     this.currentFrameContextId = null;
+    this.brokenFrame = null;
     this.refMap.clear();
   }
   /**
@@ -2630,109 +2968,491 @@ var Page = class {
     }
     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;
+  // ============ 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) {
+    if (!selector) {
+      const result = await this.evaluateInFrame(
+        "document.body.innerText"
+      );
+      return result.result.value ?? "";
+    }
+    return this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, { timeout: DEFAULT_TIMEOUT });
+      if (!element) return "";
+      const objectId = await this.resolveObjectId(element.nodeId);
+      const result = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: 'function() { return this.innerText || this.textContent || ""; }',
+        returnByValue: true
+      });
+      return result.result.value ?? "";
+    });
+  }
+  // ============ File Handling ============
+  /**
+   * Set files on a file input
+   */
+  async setInputFiles(selector, files, options = {}) {
+    return this.withStaleNodeRetry(async () => {
+      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 };
+        })
+      );
+      const objectId = await this.resolveObjectId(element.nodeId);
+      const result = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function(files) {
+          if (!(this instanceof HTMLInputElement) || this.type !== 'file') {
+            return { ok: false, fileCount: 0 };
+          }
+
+          const dt = new DataTransfer();
+          for (const f of files) {
+            const bytes = Uint8Array.from(atob(f.data), function(c) { return c.charCodeAt(0); });
+            const file = new File([bytes], f.name, { type: f.mimeType });
+            dt.items.add(file);
+          }
+
+          var descriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'files');
+          if (descriptor && descriptor.set) {
+            descriptor.set.call(this, dt.files);
+          } else {
+            this.files = dt.files;
+          }
+
+          this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+          this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+          return {
+            ok: (this.files && this.files.length === files.length) || files.length === 0,
+            fileCount: this.files ? this.files.length : 0
+          };
+        }`,
+        arguments: [{ value: fileData }],
+        returnByValue: true
+      });
+      if (!result.result.value.ok) {
+        if (options.optional) return false;
+        throw new Error("Failed to set files on input");
+      }
+      return true;
+    });
+  }
+  async getNativeSelectMetadata(objectId, targets) {
+    const result = await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function(targetValues) {
+        if (!(this instanceof HTMLSelectElement)) {
+          return {
+            currentIndex: -1,
+            currentValue: '',
+            disabled: [],
+            isSelect: false,
+            missing: Array.isArray(targetValues) ? targetValues.map(String) : [],
+            multiple: false,
+            options: [],
+            selectedValues: [],
+            targetIndexes: []
+          };
+        }
+
+        var allOptions = Array.from(this.options).map(function(opt, index) {
+          return { index: index, label: opt.label || opt.text || '', value: opt.value || '' };
+        });
+        var targetIndexes = [];
+        var missing = [];
+        var disabled = [];
+
+        for (var i = 0; i < targetValues.length; i++) {
+          var target = String(targetValues[i]);
+          var idx = -1;
+
+          for (var j = 0; j < this.options.length; j++) {
+            var opt = this.options[j];
+            if (opt.value === target || opt.text === target || opt.label === target) {
+              idx = j;
+              break;
+            }
+          }
+
+          if (idx === -1 && /^\\d+$/.test(target)) {
+            var numericIndex = parseInt(target, 10);
+            if (numericIndex >= 0 && numericIndex < this.options.length) {
+              idx = numericIndex;
+            }
+          }
+
+          if (idx === -1) {
+            missing.push(target);
+            continue;
+          }
+
+          if (this.options[idx] && this.options[idx].disabled) {
+            disabled.push(target);
+            continue;
+          }
+
+          if (targetIndexes.indexOf(idx) === -1) {
+            targetIndexes.push(idx);
+          }
+        }
+
+        return {
+          currentIndex: this.selectedIndex,
+          currentValue: this.value || '',
+          disabled: disabled,
+          isSelect: true,
+          missing: missing,
+          multiple: !!this.multiple,
+          options: allOptions,
+          selectedValues: Array.from(this.selectedOptions).map(function(opt) { return opt.value || ''; }),
+          targetIndexes: targetIndexes
+        };
+      }`,
+      arguments: [{ value: targets }],
+      returnByValue: true
+    });
+    return result.result.value;
+  }
+  async readNativeSelectValues(objectId) {
+    const result = await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: 'function() { return this instanceof HTMLSelectElement ? Array.from(this.selectedOptions).map(function(opt) { return opt.value || ""; }) : []; }',
+      returnByValue: true
+    });
+    return result.result.value ?? [];
+  }
+  selectValuesMatch(actual, expected, multiple) {
+    if (!multiple) {
+      return (actual[0] ?? "") === (expected[0] ?? "");
     }
-    const params = {
-      expression: script,
-      returnByValue: true,
-      awaitPromise: true
-    };
-    if (this.currentFrameContextId !== null) {
-      params["contextId"] = this.currentFrameContextId;
+    if (actual.length !== expected.length) {
+      return false;
     }
-    const result = await this.cdp.send("Runtime.evaluate", params);
-    if (result.exceptionDetails) {
-      throw new Error(`Evaluation failed: ${result.exceptionDetails.text}`);
+    const actualSorted = [...actual].sort();
+    const expectedSorted = [...expected].sort();
+    return actualSorted.every((value, index) => value === expectedSorted[index]);
+  }
+  async applyNativeSelectByKeyboard(nodeId, objectId, currentIndex, targetIndex) {
+    await this.cdp.send("DOM.focus", { nodeId });
+    if (targetIndex !== currentIndex) {
+      let effectiveIndex = currentIndex;
+      if (effectiveIndex < 0 || targetIndex < effectiveIndex) {
+        await this.dispatchKey("Home");
+        effectiveIndex = 0;
+      }
+      const steps = targetIndex - effectiveIndex;
+      const direction = steps >= 0 ? "ArrowDown" : "ArrowUp";
+      for (let i = 0; i < Math.abs(steps); i++) {
+        await this.dispatchKey(direction);
+      }
     }
-    return result.result.value;
+    const selectedValues = await this.readNativeSelectValues(objectId);
+    return selectedValues[0] !== void 0;
+  }
+  async applyNativeSelectFallback(objectId, targetIndexes) {
+    await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function(indexes) {
+        if (!(this instanceof HTMLSelectElement)) return false;
+
+        var wanted = new Set(indexes.map(function(index) { return Number(index); }));
+        for (var i = 0; i < this.options.length; i++) {
+          this.options[i].selected = wanted.has(i);
+        }
+        if (!this.multiple && indexes.length === 1) {
+          this.selectedIndex = indexes[0];
+        }
+        this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+        this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+        return true;
+      }`,
+      arguments: [{ value: targetIndexes }],
+      returnByValue: true
+    });
   }
-  // ============ 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
+  async selectEditableContent(objectId) {
+    await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function() {
+        if (this.isContentEditable) {
+          this.focus();
+          const range = document.createRange();
+          range.selectNodeContents(this);
+          const selection = window.getSelection();
+          if (selection) {
+            selection.removeAllRanges();
+            selection.addRange(range);
+          }
+          return;
+        }
+
+        if (this.tagName === 'TEXTAREA') {
+          this.selectionStart = 0;
+          this.selectionEnd = this.value.length;
+          this.focus();
+          return;
+        }
+
+        if (typeof this.select === 'function') {
+          this.select();
+        }
+        this.focus();
+      }`
     });
-    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);
+  async clearEditableSelection(objectId, key) {
+    await this.selectEditableContent(objectId);
+    await this.dispatchKey(key);
+  }
+  async readEditableValue(objectId) {
+    const result = await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function() {
+        if (this.isContentEditable) {
+          return this.textContent || '';
+        }
+        return this.value || '';
+      }`,
+      returnByValue: true
+    });
     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);
+  async typeEditableFallback(nodeId, objectId, value) {
+    await this.selectEditableContent(objectId);
+    await this.cdp.send("DOM.focus", { nodeId });
+    for (const char of value) {
+      await this.dispatchKey(char);
     }
-    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));
+  }
+  async applyRecordedSelectFallback(objectId, targetIndexes) {
+    await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function(indexes) {
+        if (!(this instanceof HTMLSelectElement)) return false;
+
+        var wanted = new Set(indexes.map(function(index) { return Number(index); }));
+        for (var i = 0; i < this.options.length; i++) {
+          this.options[i].selected = wanted.has(i);
         }
-        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;
+        if (!this.multiple && indexes.length === 1) {
+          this.selectedIndex = indexes[0];
+        }
+        return true;
+      }`,
+      arguments: [{ value: targetIndexes }],
+      returnByValue: true
+    });
+    return this.invokeRecordedEventListeners(objectId, ["input", "change"]);
+  }
+  async invokeRecordedEventListeners(objectId, eventTypes) {
+    const result = await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function(types) {
+        function buildPath(target) {
+          var path = [];
+          var node = target;
 
-        const files = ${JSON.stringify(fileData)};
-        const dt = new DataTransfer();
+          while (node) {
+            path.push(node);
 
-        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);
+            if (node.parentElement) {
+              node = node.parentElement;
+              continue;
+            }
+
+            if (node === document) {
+              node = window;
+              continue;
+            }
+
+            if (node.defaultView && node !== node.defaultView) {
+              node = node.defaultView;
+              continue;
+            }
+
+            if (node.ownerDocument && node !== node.ownerDocument) {
+              node = node.ownerDocument;
+              continue;
+            }
+
+            var root = node.getRootNode && node.getRootNode();
+            if (root && root !== node && root.host) {
+              node = root.host;
+              continue;
+            }
+
+            node = null;
+          }
+
+          return path;
         }
 
-        input.files = dt.files;
-        input.dispatchEvent(new Event('change', { bubbles: true }));
-        return true;
-      })()`,
+        function createEvent(type, target, currentTarget, path, phase) {
+          return {
+            type: type,
+            target: target,
+            currentTarget: currentTarget,
+            srcElement: target,
+            isTrusted: true,
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            defaultPrevented: false,
+            eventPhase: phase,
+            timeStamp: Date.now(),
+            preventDefault: function() {
+              this.defaultPrevented = true;
+            },
+            stopPropagation: function() {
+              this.__stopped = true;
+            },
+            stopImmediatePropagation: function() {
+              this.__stopped = true;
+              this.__immediateStopped = true;
+            },
+            composedPath: function() {
+              return path.slice();
+            }
+          };
+        }
+
+        function invokePhase(type, nodes, capture, target, path) {
+          var invoked = false;
+
+          for (var i = 0; i < nodes.length; i++) {
+            var currentTarget = nodes[i];
+
+            var phase = currentTarget === target ? 2 : capture ? 1 : 3;
+
+            // Invoke inline handler if present (e.g. onclick, oninput)
+            var inlineHandler = currentTarget['on' + type];
+            if (typeof inlineHandler === 'function') {
+              var inlineEvent = createEvent(type, target, currentTarget, path, phase);
+              inlineHandler.call(currentTarget, inlineEvent);
+              invoked = true;
+              if (inlineEvent.__stopped) break;
+            }
+
+            var store = currentTarget && currentTarget.__bpEventListeners;
+            var entries = store && store[type];
+            if (!Array.isArray(entries) || entries.length === 0) continue;
+
+            var event = createEvent(type, target, currentTarget, path, phase);
+
+            for (var j = 0; j < entries.length; j++) {
+              var entry = entries[j];
+              if (!!entry.capture !== capture) continue;
+
+              var listener = entry.listener;
+              if (typeof listener === 'function') {
+                listener.call(currentTarget, event);
+                invoked = true;
+              } else if (listener && typeof listener.handleEvent === 'function') {
+                listener.handleEvent(event);
+                invoked = true;
+              }
+
+              if (event.__immediateStopped) {
+                break;
+              }
+            }
+
+            if (event.__stopped) {
+              break;
+            }
+          }
+
+          return invoked;
+        }
+
+        var path = buildPath(this);
+        var capturePath = path.slice().reverse();
+        var bubblePath = path.slice();
+        var invokedAny = false;
+
+        for (var i = 0; i < types.length; i++) {
+          var type = String(types[i]);
+          if (invokePhase(type, capturePath, true, this, path)) {
+            invokedAny = true;
+          }
+          if (invokePhase(type, bubblePath, false, this, path)) {
+            invokedAny = true;
+          }
+        }
+
+        return invokedAny;
+      }`,
+      arguments: [{ value: eventTypes }],
       returnByValue: true
     });
-    return true;
+    return result.result.value ?? false;
   }
   /**
    * Wait for a download to complete, triggered by an action
@@ -2892,7 +3612,7 @@ var Page = class {
       return lines.join("\n");
     };
     const text = formatTree(accessibilityTree);
-    return {
+    const result = {
       url,
       title,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2900,6 +3620,8 @@ var Page = class {
       interactiveElements,
       text
     };
+    this.lastSnapshot = result;
+    return result;
   }
   /**
    * Export the current ref map for cross-exec reuse (CLI).
@@ -3313,8 +4035,15 @@ var Page = class {
       }
     };
     if (this.dialogHandler) {
+      const DIALOG_TIMEOUT = 5e3;
       try {
-        await this.dialogHandler(dialog);
+        await Promise.race([
+          this.dialogHandler(dialog),
+          sleep3(DIALOG_TIMEOUT).then(() => {
+            console.warn("[browser-pilot] Dialog handler timed out after 5s, auto-dismissing");
+            return dialog.dismiss();
+          })
+        ]);
       } catch (e) {
         console.error("[Dialog handler error]", e);
         await dialog.dismiss();
@@ -3394,6 +4123,7 @@ var Page = class {
     this.refMap.clear();
     this.currentFrame = null;
     this.currentFrameContextId = null;
+    this.brokenFrame = null;
     this.frameContexts.clear();
     this.dialogHandler = null;
     try {
@@ -3428,10 +4158,12 @@ var Page = class {
       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"))) {
+        const message = e instanceof Error ? e.message : "";
+        if (e instanceof Error && (message.includes("Could not find node with given id") || message.includes("Node with given id does not belong to the document") || message.includes("No node with given id found") || message.includes("Could not find object with given id") || message.includes("Cannot find context with specified id") || message.includes("Cannot find context with given id") || message.includes("Execution context was destroyed") || message.includes("No execution context with given id") || message.includes("Argument should belong to the same JavaScript world"))) {
           lastError = e;
           if (attempt < retries) {
             this.rootNodeId = null;
+            this.currentFrameContextId = null;
             await sleep3(delay);
             continue;
           }
@@ -3477,6 +4209,39 @@ var Page = class {
         }
       }
     }
+    if (selectorList.every((s) => s.startsWith("ref:")) && this.lastSnapshot) {
+      for (const selector of selectorList) {
+        const ref = selector.slice(4);
+        const originalElement = this.lastSnapshot.interactiveElements.find((e) => e.ref === ref);
+        if (!originalElement) continue;
+        const freshSnapshot = await this.snapshot();
+        const match = freshSnapshot.interactiveElements.find(
+          (e) => e.role === originalElement.role && e.name === originalElement.name
+        );
+        if (match) {
+          const newBackendNodeId = this.refMap.get(match.ref);
+          if (newBackendNodeId) {
+            try {
+              await this.ensureRootNode();
+              const pushResult = await this.cdp.send(
+                "DOM.pushNodesByBackendIdsToFrontend",
+                { backendNodeIds: [newBackendNodeId] }
+              );
+              if (pushResult.nodeIds?.[0]) {
+                this._lastMatchedSelector = `ref:${match.ref}`;
+                return {
+                  nodeId: pushResult.nodeIds[0],
+                  backendNodeId: newBackendNodeId,
+                  selector: `ref:${match.ref}`,
+                  waitedMs: 0
+                };
+              }
+            } catch {
+            }
+          }
+        }
+      }
+    }
     const cssSelectors = selectorList.filter((s) => !s.startsWith("ref:"));
     if (cssSelectors.length === 0) {
       return null;
@@ -3540,6 +4305,34 @@ var Page = class {
    */
   async ensureRootNode() {
     if (this.rootNodeId) return;
+    if (this.currentFrame) {
+      const mainDocument = await this.cdp.send("DOM.getDocument", {
+        depth: 0
+      });
+      const iframeNode = await this.cdp.send("DOM.querySelector", {
+        nodeId: mainDocument.root.nodeId,
+        selector: this.currentFrame
+      });
+      if (iframeNode.nodeId) {
+        const frameResult = await this.cdp.send("DOM.describeNode", {
+          nodeId: iframeNode.nodeId,
+          depth: 1
+        });
+        if (frameResult.node.contentDocument?.nodeId) {
+          this.rootNodeId = frameResult.node.contentDocument.nodeId;
+          if (frameResult.node.frameId) {
+            let contextId = this.frameExecutionContexts.get(frameResult.node.frameId);
+            if (!contextId) {
+              contextId = await this.waitForFrameContext(frameResult.node.frameId, 1e3);
+            }
+            this.currentFrameContextId = contextId ?? null;
+          }
+          return;
+        }
+      }
+      this.currentFrame = null;
+      this.currentFrameContextId = null;
+    }
     const doc = await this.cdp.send("DOM.getDocument", {
       depth: 0
     });
@@ -3550,6 +4343,11 @@ var Page = class {
    * Automatically injects contextId when in an iframe
    */
   async evaluateInFrame(expression, options = {}) {
+    if (this.brokenFrame && this.currentFrame) {
+      throw new Error(
+        `Cannot evaluate JavaScript in frame "${this.brokenFrame}": execution context is unavailable (cross-origin or sandboxed iframe). DOM operations (click, fill, etc.) may still work via CDP.`
+      );
+    }
     const params = {
       expression,
       returnByValue: options.returnByValue ?? true,
@@ -3561,10 +4359,43 @@ var Page = class {
     return this.cdp.send("Runtime.evaluate", params);
   }
   /**
-   * Scroll an element into view
+   * Scroll an element into view, with fallback to center-scroll if clipped by fixed headers
    */
   async scrollIntoView(nodeId) {
     await this.cdp.send("DOM.scrollIntoViewIfNeeded", { nodeId });
+    if (!await this.isInViewport(nodeId)) {
+      const objectId = await this.resolveObjectId(nodeId);
+      await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function() { this.scrollIntoView({ block: 'center', inline: 'center' }); }`
+      });
+    }
+  }
+  /**
+   * Check if element is within the visible viewport
+   */
+  async isInViewport(nodeId) {
+    try {
+      const objectId = await this.resolveObjectId(nodeId);
+      const result = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function() {
+          var rect = this.getBoundingClientRect();
+          return (
+            rect.top >= 0 &&
+            rect.left >= 0 &&
+            rect.bottom <= window.innerHeight &&
+            rect.right <= window.innerWidth &&
+            rect.width > 0 &&
+            rect.height > 0
+          );
+        }`,
+        returnByValue: true
+      });
+      return result?.result?.value === true;
+    } catch {
+      return true;
+    }
   }
   /**
    * Get element box model (position and dimensions)
@@ -3580,30 +4411,147 @@ var Page = class {
     }
   }
   /**
-   * Click an element by node ID
+   * Click an element by node ID using Playwright's 3-event sequence:
+   * mouseMoved → mousePressed → mouseReleased (sequential).
+   * Uses DOM.getContentQuads for accurate coordinates (handles CSS transforms).
+   * Falls back to JS this.click() if CDP mouse dispatch fails.
    */
   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
+    const { object } = await this.cdp.send("DOM.resolveNode", {
+      nodeId
+    });
+    let x;
+    let y;
+    try {
+      const { quads } = await this.cdp.send("DOM.getContentQuads", {
+        objectId: object.objectId
+      });
+      if (quads && quads.length > 0) {
+        const quad = quads[0];
+        x = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
+        y = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+      } else {
+        throw new Error("No quads");
+      }
+    } catch {
+      const box = await this.getBoxModel(nodeId);
+      if (!box) throw new Error("Could not get element position for click");
+      x = box.content[0] + box.width / 2;
+      y = box.content[1] + box.height / 2;
+    }
+    try {
+      await this.cdp.send("Input.dispatchMouseEvent", {
+        type: "mouseMoved",
+        x,
+        y,
+        button: "none",
+        buttons: 0,
+        modifiers: 0
+      });
+      await this.cdp.send("Input.dispatchMouseEvent", {
+        type: "mousePressed",
+        x,
+        y,
+        button: "left",
+        buttons: 1,
+        clickCount: 1,
+        modifiers: 0
+      });
+      await this.cdp.send("Input.dispatchMouseEvent", {
+        type: "mouseReleased",
+        x,
+        y,
+        button: "left",
+        buttons: 0,
+        clickCount: 1,
+        modifiers: 0
+      });
+    } catch {
+      await this.cdp.send("Runtime.callFunctionOn", {
+        objectId: object.objectId,
+        functionDeclaration: "function() { this.click(); }"
+      });
+    }
+    await this.cdp.send("Runtime.evaluate", { expression: "0" });
+  }
+  /**
+   * Resolve a nodeId to a Remote Object ID for use with Runtime.callFunctionOn
+   */
+  async resolveObjectId(nodeId) {
+    const { object } = await this.cdp.send("DOM.resolveNode", {
+      nodeId
+    });
+    return object.objectId;
+  }
+  async dispatchKeyDefinition(def, modifierBitmask = 0) {
+    const downParams = {
+      type: def.text !== void 0 ? "keyDown" : "rawKeyDown",
+      key: def.key,
+      code: def.code,
+      windowsVirtualKeyCode: def.keyCode,
+      modifiers: modifierBitmask,
+      autoRepeat: false,
+      location: def.location ?? 0,
+      isKeypad: false
+    };
+    if (def.text !== void 0) {
+      downParams["text"] = def.text;
+      downParams["unmodifiedText"] = def.text;
+    }
+    await this.cdp.send("Input.dispatchKeyEvent", downParams);
+    await this.cdp.send("Input.dispatchKeyEvent", {
+      type: "keyUp",
+      key: def.key,
+      code: def.code,
+      windowsVirtualKeyCode: def.keyCode,
+      modifiers: modifierBitmask,
+      location: def.location ?? 0
     });
   }
+  async dispatchKey(key) {
+    const def = US_KEYBOARD[key];
+    if (def) {
+      await this.dispatchKeyDefinition(def);
+      return;
+    }
+    if (key.length === 1) {
+      await this.cdp.send("Input.insertText", { text: key });
+      return;
+    }
+    await this.dispatchKeyDefinition({ key, code: key, keyCode: 0 });
+  }
+  async dispatchKeyWithModifiers(key, modifiers) {
+    const mask = computeModifierBitmask(modifiers);
+    for (const mod of modifiers) {
+      await this.cdp.send("Input.dispatchKeyEvent", {
+        type: "rawKeyDown",
+        key: mod,
+        code: MODIFIER_CODES[mod],
+        windowsVirtualKeyCode: MODIFIER_KEY_CODES[mod],
+        modifiers: mask,
+        location: 1
+      });
+    }
+    const def = US_KEYBOARD[key];
+    if (def) {
+      await this.dispatchKeyDefinition(def, mask);
+    } else if (key.length === 1) {
+      await this.dispatchKeyDefinition({ key, code: key, keyCode: 0, text: key }, mask);
+    } else {
+      await this.dispatchKeyDefinition({ key, code: key, keyCode: 0 }, mask);
+    }
+    for (let i = modifiers.length - 1; i >= 0; i--) {
+      const mod = modifiers[i];
+      await this.cdp.send("Input.dispatchKeyEvent", {
+        type: "keyUp",
+        key: mod,
+        code: MODIFIER_CODES[mod],
+        windowsVirtualKeyCode: MODIFIER_KEY_CODES[mod],
+        modifiers: 0,
+        location: 1
+      });
+    }
+  }
   // ============ Audio I/O ============
   /**
    * Audio input controller (fake microphone).
@@ -3703,12 +4651,68 @@ var Page = class {
       totalMs: Date.now() - start
     };
   }
+  /**
+   * Wait for a DOM mutation in the current frame (used for detecting client-side form handling)
+   */
+  async waitForDOMMutation(options) {
+    await this.evaluateInFrame(
+      `new Promise((resolve) => {
+        var observer = new MutationObserver(function() {
+          observer.disconnect();
+          resolve();
+        });
+        observer.observe(document.body, { childList: true, subtree: true });
+        setTimeout(function() { observer.disconnect(); resolve(); }, ${options.timeout});
+      })`
+    );
+  }
+  /**
+   * Wait for a frame execution context via Runtime.executionContextCreated event
+   */
+  async waitForFrameContext(frameId, timeout) {
+    const existing = this.frameExecutionContexts.get(frameId);
+    if (existing) return existing;
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        resolve(void 0);
+      }, timeout);
+      const handler = (params) => {
+        const context = params["context"];
+        if (context.auxData?.frameId === frameId && context.auxData?.isDefault !== false) {
+          cleanup();
+          resolve(context.id);
+        }
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.cdp.off("Runtime.executionContextCreated", handler);
+      };
+      this.cdp.on("Runtime.executionContextCreated", handler);
+    });
+  }
 };
 function sleep3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 // src/browser/browser.ts
+function scoreTarget(t) {
+  let score = 0;
+  if (t.url.startsWith("http://") || t.url.startsWith("https://")) score += 10;
+  if (t.url.startsWith("chrome://")) score -= 20;
+  if (t.url.startsWith("chrome-extension://")) score -= 15;
+  if (t.url.startsWith("devtools://")) score -= 25;
+  if (t.url === "about:blank") score -= 5;
+  if (!t.attached) score += 3;
+  if (t.title && t.title.length > 0) score += 2;
+  return score;
+}
+function pickBestTarget(targets) {
+  if (targets.length === 0) return void 0;
+  const sorted = [...targets].sort((a, b) => scoreTarget(b) - scoreTarget(a));
+  return sorted[0].targetId;
+}
 var Browser = class _Browser {
   cdp;
   providerSession;
@@ -3730,28 +4734,46 @@ var Browser = class _Browser {
     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
+   * Get or create a page by name.
+   * If no name is provided, returns the first available page or creates a new one.
+   *
+   * Target selection heuristics (when no targetId is specified):
+   * - Prefer http/https URLs over chrome://, devtools://, about:blank
+   * - Prefer unattached targets (not already controlled by another client)
+   * - Filter by targetUrl if provided
    */
   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 pageTargets = targets.targetInfos.filter((t) => t.type === "page");
+    if (options?.targetUrl) {
+      const urlFilter = options.targetUrl;
+      const filtered = pageTargets.filter((t) => t.url.includes(urlFilter));
+      if (filtered.length > 0) {
+        pageTargets = filtered;
+      } else {
+        console.warn(
+          `[browser-pilot] No targets match URL filter "${urlFilter}", falling back to all page targets`
+        );
+      }
+    }
     let targetId;
     if (options?.targetId) {
-      const targetExists = pageTargets.some((t) => t.targetId === options.targetId);
+      const targetExists = targets.targetInfos.some(
+        (t) => t.type === "page" && 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", {
+        targetId = pickBestTarget(pageTargets) ?? (await this.cdp.send("Target.createTarget", {
           url: "about:blank"
         })).targetId;
       }
     } else if (pageTargets.length > 0) {
-      targetId = pageTargets[0].targetId;
+      targetId = pickBestTarget(pageTargets);
     } else {
       const result = await this.cdp.send("Target.createTarget", {
         url: "about:blank"
@@ -3761,6 +4783,21 @@ var Browser = class _Browser {
     await this.cdp.attachToTarget(targetId);
     const page = new Page(this.cdp, targetId);
     await page.init();
+    const minViewport = options?.minViewport !== void 0 ? options.minViewport : { width: 200, height: 200 };
+    if (minViewport !== false) {
+      try {
+        const viewport = await page.evaluate(
+          "({ w: window.innerWidth, h: window.innerHeight })"
+        );
+        if (viewport.w < minViewport.width || viewport.h < minViewport.height) {
+          console.warn(
+            `[browser-pilot] Attached target has small viewport (${viewport.w}x${viewport.h}). Applying default viewport override (1280x720). Use { minViewport: false } to disable this check.`
+          );
+          await page.setViewport({ width: 1280, height: 720 });
+        }
+      } catch {
+      }
+    }
     this.pages.set(pageName, page);
     return page;
   }