browser-pilot 0.0.9 → 0.0.11

package/dist/browser.cjs

@@ -463,7 +463,12 @@ var ElementNotFoundError = class extends Error {
   hints;
   constructor(selectors, hints) {
     const selectorList = Array.isArray(selectors) ? selectors : [selectors];
-    super(`Element not found: ${selectorList.join(", ")}`);
+    let msg = `Element not found: ${selectorList.join(", ")}`;
+    if (hints?.length) {
+      msg += `. Did you mean: ${hints.slice(0, 3).map((h) => `${h.element.ref} (${h.element.role} "${h.element.name}")`).join(", ")}`;
+    }
+    msg += `. Run 'bp snapshot' to see available elements.`;
+    super(msg);
     this.name = "ElementNotFoundError";
     this.selectors = selectorList;
     this.hints = hints;
@@ -471,7 +476,8 @@ var ElementNotFoundError = class extends Error {
 };
 var TimeoutError = class extends Error {
   constructor(message = "Operation timed out") {
-    super(message);
+    const msg = message.includes("bp snapshot") ? message : `${message}. Run 'bp snapshot' to check current page state.`;
+    super(msg);
     this.name = "TimeoutError";
   }
 };
@@ -554,7 +560,7 @@ var BatchExecutor = class {
       }
       case "click": {
         if (!step.selector) throw new Error("click requires selector");
-        if (step.waitForNavigation) {
+        if (step.waitForNavigation === true) {
           const navPromise = this.page.waitForNavigation({ timeout, optional });
           await this.page.click(step.selector, { timeout, optional });
           await navPromise;
@@ -569,7 +575,6 @@ var BatchExecutor = class {
         await this.page.fill(step.selector, step.value, {
           timeout,
           optional,
-          clear: step.clear ?? true,
           blur: step.blur
         });
         return { selectorUsed: this.getUsedSelector(step.selector) };
@@ -617,7 +622,8 @@ var BatchExecutor = class {
         await this.page.submit(step.selector, {
           timeout,
           optional,
-          method: step.method ?? "enter+click"
+          method: step.method ?? "enter+click",
+          waitForNavigation: step.waitForNavigation
         });
         return { selectorUsed: this.getUsedSelector(step.selector) };
       }
@@ -2347,6 +2353,335 @@ async function waitForNetworkIdle(cdp, options = {}) {
   });
 }
 
+// src/browser/actionability.ts
+var ActionabilityError = class extends Error {
+  failureType;
+  coveringElement;
+  constructor(message, failureType, coveringElement) {
+    super(message);
+    this.name = "ActionabilityError";
+    this.failureType = failureType;
+    this.coveringElement = coveringElement;
+  }
+};
+var CHECK_VISIBLE = `function() {
+  // checkVisibility handles display:none, visibility:hidden, content-visibility up the tree
+  if (typeof this.checkVisibility === 'function' && !this.checkVisibility()) {
+    return { actionable: false, reason: 'Element is not visible (checkVisibility failed). Try scrolling or check if a prior action is needed to reveal it.' };
+  }
+
+  var style = getComputedStyle(this);
+
+  if (style.visibility !== 'visible') {
+    return { actionable: false, reason: 'Element has visibility: ' + style.visibility + '. Try scrolling or check if a prior action is needed to reveal it.' };
+  }
+
+  // display:contents elements have no box themselves \u2014 check children
+  if (style.display === 'contents') {
+    var children = this.children;
+    if (children.length === 0) {
+      return { actionable: false, reason: 'Element has display:contents with no children. Try scrolling or check if a prior action is needed to reveal it.' };
+    }
+    for (var i = 0; i < children.length; i++) {
+      var childRect = children[i].getBoundingClientRect();
+      if (childRect.width > 0 && childRect.height > 0) {
+        return { actionable: true };
+      }
+    }
+    return { actionable: false, reason: 'Element has display:contents but no visible children. Try scrolling or check if a prior action is needed to reveal it.' };
+  }
+
+  var rect = this.getBoundingClientRect();
+  if (rect.width <= 0 || rect.height <= 0) {
+    return { actionable: false, reason: 'Element has zero size (' + rect.width + 'x' + rect.height + '). Try scrolling or check if a prior action is needed to reveal it.' };
+  }
+
+  return { actionable: true };
+}`;
+var CHECK_ENABLED = `function() {
+  // Native disabled property
+  var disableable = ['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'OPTION', 'OPTGROUP'];
+  if (disableable.indexOf(this.tagName) !== -1 && this.disabled) {
+    return { actionable: false, reason: 'Element is disabled. Check if a prerequisite field needs to be filled first.' };
+  }
+
+  // Check ancestor FIELDSET[disabled]
+  var parent = this.parentElement;
+  while (parent) {
+    if (parent.tagName === 'FIELDSET' && parent.disabled) {
+      // Exception: elements inside the first <legend> of a disabled fieldset are NOT disabled
+      var legend = parent.querySelector(':scope > legend');
+      if (!legend || !legend.contains(this)) {
+        return { actionable: false, reason: 'Element is inside a disabled fieldset. Check if a prerequisite field needs to be filled first.' };
+      }
+    }
+    parent = parent.parentElement;
+  }
+
+  // aria-disabled="true" walking up ancestor chain (crosses shadow DOM)
+  var node = this;
+  while (node) {
+    if (node.nodeType === 1 && node.getAttribute && node.getAttribute('aria-disabled') === 'true') {
+      return { actionable: false, reason: 'Element or ancestor has aria-disabled="true". Check if a prerequisite field needs to be filled first.' };
+    }
+    if (node.parentElement) {
+      node = node.parentElement;
+    } else if (node.getRootNode && node.getRootNode() !== node) {
+      // Cross shadow DOM boundary
+      var root = node.getRootNode();
+      node = root.host || null;
+    } else {
+      break;
+    }
+  }
+
+  return { actionable: true };
+}`;
+var CHECK_STABLE = `function() {
+  var self = this;
+  return new Promise(function(resolve) {
+    var maxFrames = 30;
+    var prev = null;
+    var frame = 0;
+    var resolved = false;
+
+    var fallbackTimer = setTimeout(function() {
+      if (!resolved) {
+        resolved = true;
+        resolve({ actionable: false, reason: 'Element stability check timed out (tab may be backgrounded)' });
+      }
+    }, 2000);
+
+    function check() {
+      if (resolved) return;
+      frame++;
+      if (frame > maxFrames) {
+        resolved = true;
+        clearTimeout(fallbackTimer);
+        resolve({ actionable: false, reason: 'Element position not stable after ' + maxFrames + ' frames' });
+        return;
+      }
+
+      var rect = self.getBoundingClientRect();
+      var cur = { x: rect.x, y: rect.y, w: rect.width, h: rect.height };
+
+      if (prev !== null &&
+          prev.x === cur.x && prev.y === cur.y &&
+          prev.w === cur.w && prev.h === cur.h) {
+        resolved = true;
+        clearTimeout(fallbackTimer);
+        resolve({ actionable: true });
+        return;
+      }
+
+      prev = cur;
+      requestAnimationFrame(check);
+    }
+
+    requestAnimationFrame(check);
+  });
+}`;
+var CHECK_HIT_TARGET = `function(x, y) {
+  // Compute click center if coordinates not provided
+  if (x === undefined || y === undefined) {
+    var rect = this.getBoundingClientRect();
+    x = rect.x + rect.width / 2;
+    y = rect.y + rect.height / 2;
+  }
+
+  function checkPoint(root, px, py) {
+    var method = root.elementsFromPoint || root.msElementsFromPoint;
+    if (!method) return [];
+    return method.call(root, px, py) || [];
+  }
+
+  // Follow only the top-most hit through nested shadow roots.
+  // Accepting any hit in the stack creates false positives for covered elements.
+  var root = document;
+  var topHits = [];
+  var seenRoots = [];
+  while (root && seenRoots.indexOf(root) === -1) {
+    seenRoots.push(root);
+    var hits = checkPoint(root, x, y);
+    if (!hits.length) break;
+    var top = hits[0];
+    topHits.push(top);
+    if (top && top.shadowRoot) {
+      root = top.shadowRoot;
+      continue;
+    }
+    break;
+  }
+
+  // Target must be the top-most hit element or an ancestor/descendant
+  for (var j = 0; j < topHits.length; j++) {
+    var hit = topHits[j];
+    if (hit === this || this.contains(hit) || hit.contains(this)) {
+      return { actionable: true };
+    }
+  }
+
+  // Report the covering element
+  var top = topHits.length > 0 ? topHits[topHits.length - 1] : null;
+  if (top) {
+    return {
+      actionable: false,
+      reason: 'Element is covered by <' + top.tagName.toLowerCase() + '>' +
+        (top.id ? '#' + top.id : '') +
+        (top.className && typeof top.className === 'string' ? '.' + top.className.split(' ').join('.') : '') +
+        '. Try dismissing overlays first.',
+      coveringElement: {
+        tag: top.tagName.toLowerCase(),
+        id: top.id || undefined,
+        className: (typeof top.className === 'string' && top.className) || undefined
+      }
+    };
+  }
+
+  return { actionable: false, reason: 'No element found at click point (' + x + ', ' + y + '). Try scrolling the element into view first.' };
+}`;
+var CHECK_EDITABLE = `function() {
+  // Must be an editable element type
+  var tag = this.tagName;
+  var isEditable = tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' ||
+    this.isContentEditable;
+  if (!isEditable) {
+    return { actionable: false, reason: 'Element is not an editable type (<' + tag.toLowerCase() + '>). Target an <input>, <textarea>, <select>, or [contenteditable] element instead.' };
+  }
+
+  // Check disabled
+  var disableable = ['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'OPTION', 'OPTGROUP'];
+  if (disableable.indexOf(tag) !== -1 && this.disabled) {
+    return { actionable: false, reason: 'Element is disabled. Check if a prerequisite field needs to be filled first.' };
+  }
+
+  // Check ancestor FIELDSET[disabled]
+  var parent = this.parentElement;
+  while (parent) {
+    if (parent.tagName === 'FIELDSET' && parent.disabled) {
+      var legend = parent.querySelector(':scope > legend');
+      if (!legend || !legend.contains(this)) {
+        return { actionable: false, reason: 'Element is inside a disabled fieldset. Check if a prerequisite field needs to be filled first.' };
+      }
+    }
+    parent = parent.parentElement;
+  }
+
+  // aria-disabled walking up (crosses shadow DOM)
+  var node = this;
+  while (node) {
+    if (node.nodeType === 1 && node.getAttribute && node.getAttribute('aria-disabled') === 'true') {
+      return { actionable: false, reason: 'Element or ancestor has aria-disabled="true". Check if a prerequisite field needs to be filled first.' };
+    }
+    if (node.parentElement) {
+      node = node.parentElement;
+    } else if (node.getRootNode && node.getRootNode() !== node) {
+      var root = node.getRootNode();
+      node = root.host || null;
+    } else {
+      break;
+    }
+  }
+
+  // Check readonly
+  if (this.hasAttribute && this.hasAttribute('readonly')) {
+    return { actionable: false, reason: 'Cannot fill a readonly input. Remove the readonly attribute or target a different element.' };
+  }
+  if (this.getAttribute && this.getAttribute('aria-readonly') === 'true') {
+    return { actionable: false, reason: 'Cannot fill a readonly input (aria-readonly="true"). Remove the attribute or target a different element.' };
+  }
+
+  return { actionable: true };
+}`;
+function sleep3(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var BACKOFF = [0, 20, 100, 100];
+async function runCheck(cdp, objectId, check, options) {
+  let script;
+  let awaitPromise = false;
+  const args = [];
+  switch (check) {
+    case "visible":
+      script = CHECK_VISIBLE;
+      break;
+    case "enabled":
+      script = CHECK_ENABLED;
+      break;
+    case "stable":
+      script = CHECK_STABLE;
+      awaitPromise = true;
+      break;
+    case "hitTarget":
+      script = CHECK_HIT_TARGET;
+      if (options?.coordinates) {
+        args.push({ value: options.coordinates.x });
+        args.push({ value: options.coordinates.y });
+      } else {
+        args.push({ value: void 0 });
+        args.push({ value: void 0 });
+      }
+      break;
+    case "editable":
+      script = CHECK_EDITABLE;
+      break;
+    default: {
+      const _exhaustive = check;
+      throw new Error(`Unknown actionability check: ${_exhaustive}`);
+    }
+  }
+  const params = {
+    functionDeclaration: script,
+    objectId,
+    returnByValue: true,
+    arguments: args
+  };
+  if (awaitPromise) {
+    params["awaitPromise"] = true;
+  }
+  const response = await cdp.send("Runtime.callFunctionOn", params);
+  if (response.exceptionDetails) {
+    return {
+      actionable: false,
+      reason: `Check "${check}" threw: ${response.exceptionDetails.text}`,
+      failureType: check
+    };
+  }
+  const result = response.result.value;
+  if (!result.actionable) {
+    result.failureType = check;
+  }
+  return result;
+}
+async function runChecks(cdp, objectId, checks, options) {
+  for (const check of checks) {
+    const result = await runCheck(cdp, objectId, check, options);
+    if (!result.actionable) {
+      return result;
+    }
+  }
+  return { actionable: true };
+}
+async function ensureActionable(cdp, objectId, checks, options) {
+  const timeout = options?.timeout ?? 3e4;
+  const start = Date.now();
+  let attempt = 0;
+  while (true) {
+    const result = await runChecks(cdp, objectId, checks, options);
+    if (result.actionable) return;
+    if (Date.now() - start >= timeout) {
+      throw new ActionabilityError(
+        `Element not actionable: ${result.reason}`,
+        result.failureType,
+        result.coveringElement
+      );
+    }
+    const delay = attempt < BACKOFF.length ? BACKOFF[attempt] ?? 0 : 500;
+    if (delay > 0) await sleep3(delay);
+    attempt++;
+  }
+}
+
 // src/browser/fuzzy-match.ts
 function jaroWinkler(a, b) {
   if (a.length === 0 && b.length === 0) return 0;
@@ -2592,8 +2927,180 @@ async function generateHints(page, failedSelectors, actionType, maxHints = 3) {
   return diversifyHints(matches, maxHints);
 }
 
+// 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 }
+};
+
 // src/browser/page.ts
 var DEFAULT_TIMEOUT2 = 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];
+  }
+
+  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;
@@ -2617,6 +3124,8 @@ var Page = class {
   currentFrameContextId = 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) */
@@ -2661,6 +3170,9 @@ 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;
         }
       }
@@ -2672,6 +3184,18 @@ var Page = class {
       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 ============
   /**
@@ -2687,6 +3211,9 @@ var Page = class {
     }
     this.rootNodeId = null;
     this.refMap.clear();
+    this.currentFrame = null;
+    this.currentFrameContextId = null;
+    this.frameContexts.clear();
   }
   /**
    * Get the current URL
@@ -2757,8 +3284,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 () => {
@@ -2770,27 +3298,45 @@ 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 };
-          }
-          return { isSubmit: false };
-        })()`
-      );
-      const isSubmit = submitResult.result.value?.isSubmit;
-      if (!isSubmit) {
-        await this.clickElement(element.nodeId);
+      const objectId = await this.resolveObjectId(element.nodeId);
+      try {
+        await ensureActionable(this.cdp, objectId, ["visible", "enabled", "stable"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT2
+        });
+      } 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 };
+      try {
+        await ensureActionable(this.cdp, objectId, ["hitTarget"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT2,
+          coordinates: hitTargetCoordinates
+        });
+      } catch (e) {
+        if (options.optional) return false;
+        throw e;
       }
+      await this.clickElement(element.nodeId);
       return true;
     });
   }
@@ -2798,7 +3344,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) {
@@ -2807,71 +3353,152 @@ 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_TIMEOUT2
+        });
+      } 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;
+      try {
+        const objectId = await this.resolveObjectId(element.nodeId);
+        await ensureActionable(this.cdp, objectId, ["visible", "enabled"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT2
+        });
+      } 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 sleep4(delay);
+        }
+      }
+      return true;
+    });
   }
   async select(selectorOrConfig, valueOrOptions, maybeOptions) {
     if (typeof selectorOrConfig === "object" && !Array.isArray(selectorOrConfig) && "trigger" in selectorOrConfig) {
@@ -2880,108 +3507,227 @@ 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_TIMEOUT2
+        });
+      } 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 this.withStaleNodeRetry(async () => {
+      await this.click(trigger, options);
+      await sleep4(100);
+      const optionSelectors = Array.isArray(option) ? option : [option];
+      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_TIMEOUT2
         }
-        return false;
-      })()`,
-      returnByValue: true
+      );
+      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_TIMEOUT2
+        });
+      } 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_TIMEOUT2
+        });
+      } 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)
@@ -2995,97 +3741,84 @@ 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_TIMEOUT2 });
-      } 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_TIMEOUT2 });
-          return true;
-        } catch {
+        } else if (shouldWait === "auto") {
+          await Promise.race([
+            this.waitForNavigation({ timeout: 1e3, optional: true }),
+            sleep4(500)
+          ]);
         }
-      } 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_TIMEOUT2 });
+            return true;
+          } catch {
+          }
+        } else if (shouldWait === "auto") {
+          const navigationDetected = await Promise.race([
+            this.waitForNavigation({ timeout: 1e3, optional: true }).then(
+              (success) => success ? "nav" : null
+            ),
+            sleep4(500).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_TIMEOUT2 });
-      } 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_TIMEOUT2 });
+        } else if (shouldWait === "auto") {
+          await sleep4(100);
+        }
       }
-    }
-    return true;
+      return true;
+    });
   }
   /**
    * Press a key
    */
   async press(key) {
-    const keyMap = {
-      Enter: { key: "Enter", code: "Enter", keyCode: 13 },
-      Tab: { key: "Tab", code: "Tab", keyCode: 9 },
-      Escape: { key: "Escape", code: "Escape", keyCode: 27 },
-      Backspace: { key: "Backspace", code: "Backspace", keyCode: 8 },
-      Delete: { key: "Delete", code: "Delete", keyCode: 46 },
-      ArrowUp: { key: "ArrowUp", code: "ArrowUp", keyCode: 38 },
-      ArrowDown: { key: "ArrowDown", code: "ArrowDown", keyCode: 40 },
-      ArrowLeft: { key: "ArrowLeft", code: "ArrowLeft", keyCode: 37 },
-      ArrowRight: { key: "ArrowRight", code: "ArrowRight", keyCode: 39 }
-    };
-    const keyInfo = keyMap[key] ?? { key, code: key, keyCode: 0 };
-    await this.cdp.send("Input.dispatchKeyEvent", {
-      type: "keyDown",
-      key: keyInfo.key,
-      code: keyInfo.code,
-      windowsVirtualKeyCode: keyInfo.keyCode
-    });
-    await this.cdp.send("Input.dispatchKeyEvent", {
-      type: "keyUp",
-      key: keyInfo.key,
-      code: keyInfo.code,
-      windowsVirtualKeyCode: keyInfo.keyCode
-    });
+    await this.dispatchKey(key);
   }
   /**
    * Focus an element
@@ -3114,6 +3847,15 @@ var Page = class {
         throw new ElementNotFoundError(selector, hints);
       }
       await this.scrollIntoView(element.nodeId);
+      try {
+        const objectId = await this.resolveObjectId(element.nodeId);
+        await ensureActionable(this.cdp, objectId, ["visible", "stable"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT2
+        });
+      } catch (e) {
+        if (options.optional) return false;
+        throw e;
+      }
       const box = await this.getBoxModel(element.nodeId);
       if (!box) {
         if (options.optional) return false;
@@ -3304,53 +4046,424 @@ var Page = class {
    * Get text content from the page or a specific element
    */
   async text(selector) {
-    const expression = selector ? `document.querySelector(${JSON.stringify(selector)})?.innerText ?? ''` : "document.body.innerText";
-    const result = await this.evaluateInFrame(expression);
-    return result.result.value ?? "";
+    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_TIMEOUT2 });
+      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 = {}) {
-    const element = await this.findElement(selector, options);
-    if (!element) {
-      if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+    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 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));
+    if (actual.length !== expected.length) {
+      return false;
+    }
+    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);
+      }
+    }
+    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
+    });
+  }
+  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;
         }
-        return { name: f.name, mimeType: f.mimeType, data: base64 };
-      })
-    );
-    await this.cdp.send("Runtime.evaluate", {
-      expression: `(() => {
-        const input = document.querySelector(${JSON.stringify(element.selector)});
-        if (!input) return false;
 
-        const files = ${JSON.stringify(fileData)};
-        const dt = new DataTransfer();
+        if (this.tagName === 'TEXTAREA') {
+          this.selectionStart = 0;
+          this.selectionEnd = this.value.length;
+          this.focus();
+          return;
+        }
 
-        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 (typeof this.select === 'function') {
+          this.select();
+        }
+        this.focus();
+      }`
+    });
+  }
+  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 ?? "";
+  }
+  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);
+    }
+  }
+  async applyRecordedSelectFallback(objectId, targetIndexes) {
+    await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function(indexes) {
+        if (!(this instanceof HTMLSelectElement)) return false;
 
-        input.files = dt.files;
-        input.dispatchEvent(new Event('change', { bubbles: true }));
+        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];
+        }
         return true;
-      })()`,
+      }`,
+      arguments: [{ value: targetIndexes }],
       returnByValue: true
     });
-    return 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;
+
+          while (node) {
+            path.push(node);
+
+            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;
+        }
+
+        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 store = currentTarget && currentTarget.__bpEventListeners;
+            var entries = store && store[type];
+            if (!Array.isArray(entries) || entries.length === 0) continue;
+
+            var phase = currentTarget === target ? 2 : capture ? 1 : 3;
+            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 result.result.value ?? false;
   }
   /**
    * Wait for a download to complete, triggered by an action
@@ -3510,7 +4623,7 @@ var Page = class {
       return lines.join("\n");
     };
     const text = formatTree(accessibilityTree);
-    return {
+    const result = {
       url,
       title,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -3518,6 +4631,8 @@ var Page = class {
       interactiveElements,
       text
     };
+    this.lastSnapshot = result;
+    return result;
   }
   /**
    * Export the current ref map for cross-exec reuse (CLI).
@@ -4046,11 +5161,13 @@ 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;
-            await sleep3(delay);
+            this.currentFrameContextId = null;
+            await sleep4(delay);
             continue;
           }
         }
@@ -4095,6 +5212,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;
@@ -4158,6 +5308,38 @@ 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) {
+              for (let i = 0; i < 10; i++) {
+                await sleep4(100);
+                contextId = this.frameExecutionContexts.get(frameResult.node.frameId);
+                if (contextId) break;
+              }
+            }
+            this.currentFrameContextId = contextId ?? null;
+          }
+          return;
+        }
+      }
+      this.currentFrame = null;
+      this.currentFrameContextId = null;
+    }
     const doc = await this.cdp.send("DOM.getDocument", {
       depth: 0
     });
@@ -4198,30 +5380,115 @@ 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
+    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
     });
-    await this.cdp.send("Input.dispatchMouseEvent", {
-      type: "mouseReleased",
-      x,
-      y,
-      button: "left",
-      clickCount: 1
+    return object.objectId;
+  }
+  async dispatchKeyDefinition(def) {
+    const downParams = {
+      type: def.text !== void 0 ? "keyDown" : "rawKeyDown",
+      key: def.key,
+      code: def.code,
+      windowsVirtualKeyCode: def.keyCode,
+      modifiers: 0,
+      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: 0,
+      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 });
+  }
   // ============ Audio I/O ============
   /**
    * Audio input controller (fake microphone).
@@ -4294,7 +5561,7 @@ var Page = class {
     const start = Date.now();
     await this.audioOutput.start();
     if (options.preDelay && options.preDelay > 0) {
-      await sleep3(options.preDelay);
+      await sleep4(options.preDelay);
     }
     const inputDone = this.audioInput.play(options.input, {
       waitForEnd: !!options.sendSelector
@@ -4322,11 +5589,27 @@ var Page = class {
     };
   }
 };
-function sleep3(ms) {
+function sleep4(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;
@@ -4348,28 +5631,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"
@@ -4379,6 +5680,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;
   }