browser-pilot 0.0.10 → 0.0.11

package/dist/cli.mjs

@@ -25,8 +25,7 @@ INTERACTION
     Click element. Multi-selector tries each until success.
 
   {"action": "fill", "selector": "#input", "value": "text"}
-  {"action": "fill", "selector": "#input", "value": "text", "clear": false}
-    Fill input field. Clears first by default.
+    Fill input field. Always selects all text before inserting.
 
   {"action": "type", "selector": "#input", "value": "text", "delay": 50}
     Type character-by-character (for autocomplete).
@@ -360,7 +359,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;
@@ -368,7 +372,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";
   }
 };
@@ -445,7 +450,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;
@@ -460,7 +465,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) };
@@ -508,7 +512,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) };
       }
@@ -730,7 +735,6 @@ var ACTION_RULES = {
   fill: {
     required: { selector: { type: "string|string[]" }, value: { type: "string" } },
     optional: {
-      clear: { type: "boolean" },
       blur: { type: "boolean" }
     }
   },
@@ -761,7 +765,8 @@ var ACTION_RULES = {
   submit: {
     required: { selector: { type: "string|string[]" } },
     optional: {
-      method: { type: "string", enum: ["enter", "click", "enter+click"] }
+      method: { type: "string", enum: ["enter", "click", "enter+click"] },
+      waitForNavigation: { type: "boolean|auto" }
     }
   },
   press: {
@@ -839,7 +844,6 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "timeout",
   "optional",
   "method",
-  "clear",
   "blur",
   "delay",
   "waitForNavigation",
@@ -920,6 +924,11 @@ function checkFieldType(value, rule) {
     case "boolean":
       if (typeof value !== "boolean") return `expected boolean, got ${typeof value}`;
       return null;
+    case "boolean|auto":
+      if (typeof value !== "boolean" && value !== "auto") {
+        return `expected boolean or "auto", got ${typeof value}`;
+      }
+      return null;
   }
 }
 function validateSteps(steps) {
@@ -2643,6 +2652,34 @@ var BrowserlessProvider = class {
 };
 
 // src/providers/generic.ts
+function sleep2(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function fetchDevToolsJson(host, path, errorPrefix, options = {}) {
+  const protocol = host.includes("://") ? "" : "http://";
+  const attempts = options.attempts ?? 1;
+  let delayMs = options.initialDelayMs ?? 50;
+  const maxDelayMs = options.maxDelayMs ?? 250;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      const response = await fetch(`${protocol}${host}${path}`);
+      if (response.ok) {
+        return await response.json();
+      }
+      lastError = new Error(`${errorPrefix}: ${response.status}`);
+    } catch (error) {
+      lastError = new Error(
+        `${errorPrefix}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    if (attempt < attempts) {
+      await sleep2(delayMs);
+      delayMs = Math.min(delayMs * 2, maxDelayMs);
+    }
+  }
+  throw lastError ?? new Error(errorPrefix);
+}
 var GenericProvider = class {
   name = "generic";
   wsUrl;
@@ -2661,12 +2698,11 @@ var GenericProvider = class {
   }
 };
 async function getBrowserWebSocketUrl(host = "localhost:9222") {
-  const protocol = host.includes("://") ? "" : "http://";
-  const response = await fetch(`${protocol}${host}/json/version`);
-  if (!response.ok) {
-    throw new Error(`Failed to get browser info: ${response.status}`);
-  }
-  const info = await response.json();
+  const info = await fetchDevToolsJson(host, "/json/version", "Failed to get browser info", {
+    attempts: 10,
+    initialDelayMs: 50,
+    maxDelayMs: 250
+  });
   return info.webSocketDebuggerUrl;
 }
 
@@ -2953,7 +2989,7 @@ async function isElementAttached(cdp, selector, contextId) {
   const result = await cdp.send("Runtime.evaluate", params);
   return result.result.value === true;
 }
-function sleep2(ms) {
+function sleep3(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 async function waitForAnyElement(cdp, selectors, options = {}) {
@@ -2981,7 +3017,7 @@ async function waitForAnyElement(cdp, selectors, options = {}) {
         return { success: true, selector, waitedMs: Date.now() - startTime };
       }
     }
-    await sleep2(pollInterval);
+    await sleep3(pollInterval);
   }
   return { success: false, waitedMs: Date.now() - startTime };
 }
@@ -3030,7 +3066,7 @@ async function waitForNavigation(cdp, options = {}) {
     }
     const pollUrl = async () => {
       while (!resolved && Date.now() < startTime + timeout) {
-        await sleep2(100);
+        await sleep3(100);
         if (resolved) return;
         try {
           const currentUrl = await getCurrentUrl(cdp);
@@ -3090,6 +3126,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 sleep4(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, 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 sleep4(delay);
+    attempt++;
+  }
+}
+
 // src/browser/fuzzy-match.ts
 function jaroWinkler(a, b) {
   if (a.length === 0 && b.length === 0) return 0;
@@ -3335,8 +3700,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;
@@ -3360,6 +3897,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) */
@@ -3404,6 +3943,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;
         }
       }
@@ -3415,6 +3957,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 ============
   /**
@@ -3430,6 +3984,9 @@ var Page = class {
     }
     this.rootNodeId = null;
     this.refMap.clear();
+    this.currentFrame = null;
+    this.currentFrameContextId = null;
+    this.frameContexts.clear();
   }
   /**
    * Get the current URL
@@ -3500,8 +4057,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 () => {
@@ -3513,27 +4071,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;
     });
   }
@@ -3541,7 +4117,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) {
@@ -3550,71 +4126,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 sleep5(delay);
+        }
+      }
+      return true;
+    });
   }
   async select(selectorOrConfig, valueOrOptions, maybeOptions) {
     if (typeof selectorOrConfig === "object" && !Array.isArray(selectorOrConfig) && "trigger" in selectorOrConfig) {
@@ -3623,108 +4280,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 true;
-      })()`,
-      returnByValue: true
-    });
-    return true;
-  }
-  /**
-   * Handle custom (non-native) select/dropdown components
-   */
-  async selectCustom(config, options = {}) {
+    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;
+      }
+      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;
+    });
+  }
+  /**
+   * 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 sleep5(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)
@@ -3738,97 +4514,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 }),
+            sleep5(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
+            ),
+            sleep5(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 sleep5(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
@@ -3857,6 +4620,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;
@@ -4047,53 +4819,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] ?? "");
+    }
+    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;
+        }
+
+        if (this.tagName === 'TEXTAREA') {
+          this.selectionStart = 0;
+          this.selectionEnd = this.value.length;
+          this.focus();
+          return;
+        }
+
+        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);
     }
-    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 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 true;
+    return result.result.value ?? false;
   }
   /**
    * Wait for a download to complete, triggered by an action
@@ -4253,7 +5396,7 @@ var Page = class {
       return lines.join("\n");
     };
     const text = formatTree(accessibilityTree);
-    return {
+    const result = {
       url,
       title,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -4261,6 +5404,8 @@ var Page = class {
       interactiveElements,
       text
     };
+    this.lastSnapshot = result;
+    return result;
   }
   /**
    * Export the current ref map for cross-exec reuse (CLI).
@@ -4789,11 +5934,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 sleep5(delay);
             continue;
           }
         }
@@ -4838,6 +5985,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;
@@ -4901,6 +6081,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 sleep5(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
     });
@@ -4941,30 +6153,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).
@@ -5037,7 +6334,7 @@ var Page = class {
     const start = Date.now();
     await this.audioOutput.start();
     if (options.preDelay && options.preDelay > 0) {
-      await sleep3(options.preDelay);
+      await sleep5(options.preDelay);
     }
     const inputDone = this.audioInput.play(options.input, {
       waitForEnd: !!options.sendSelector
@@ -5065,11 +6362,27 @@ var Page = class {
     };
   }
 };
-function sleep3(ms) {
+function sleep5(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, 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;
@@ -5091,28 +6404,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"
@@ -5122,6 +6453,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;
   }
@@ -5764,7 +7110,7 @@ async function audioCommand(args, globalOptions) {
         let capture;
         if (options.duration && options.duration > 0) {
           await page.audioOutput.start();
-          await sleep4(options.duration);
+          await sleep6(options.duration);
           capture = await page.audioOutput.stop();
         } else {
           capture = await page.audioOutput.captureUntilSilence({
@@ -5914,7 +7260,7 @@ Available: setup, play, capture, roundtrip, check`
     await browser.disconnect();
   }
 }
-function sleep4(ms) {
+function sleep6(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
@@ -6065,6 +7411,7 @@ Options:
   --url <ws-url>          WebSocket URL (auto-discovered for generic provider)
   -n, --name <id>         Custom session name (default: auto-generated)
   -r, --resume <id>       Resume an existing session by ID
+  --target-url <str>      Filter targets to those whose URL contains this string
   --api-key <key>         API key for cloud providers
   --project-id <id>       Project ID for BrowserBase provider
   --export-log <path>     Export session log to file on close
@@ -6077,6 +7424,7 @@ Examples:
   bp connect --provider generic --name dev      # Connect with custom session name
   bp connect --url ws://localhost:9222/devtools  # Explicit WebSocket URL
   bp connect --resume dev                       # Resume a previous session
+  bp connect --target-url localhost:3000         # Attach to tab matching URL
 `.trimEnd();
 function parseConnectArgs(args) {
   const options = {};
@@ -6090,6 +7438,8 @@ function parseConnectArgs(args) {
       options.name = args[++i];
     } else if (arg === "--resume" || arg === "-r") {
       options.resume = args[++i];
+    } else if (arg === "--target-url") {
+      options.targetUrl = args[++i];
     } else if (arg === "--api-key") {
       options.apiKey = args[++i];
     } else if (arg === "--project-id") {
@@ -6140,7 +7490,8 @@ async function connectCommand(args, globalOptions) {
     projectId: options.projectId
   };
   const browser = await connect(connectOptions);
-  const page = await browser.page();
+  const pageOptions = options.targetUrl ? { targetUrl: options.targetUrl } : void 0;
+  const page = await browser.page(void 0, pageOptions);
   const currentUrl = await page.url();
   const sessionId = options.name ?? generateSessionId();
   const session = {
@@ -7176,7 +8527,7 @@ Run 'bp actions' for complete action reference.`
   } catch {
     const snippet = actionsJson.substring(0, 80);
     const looksLikeEvaluate = /evaluate/i.test(actionsJson);
-    const evalTip = looksLikeEvaluate ? "\n\nTip: For JavaScript evaluation, use 'bp eval' instead \u2014 no JSON wrapping needed:\n  bp eval 'your.expression.here'" : "";
+    const evalTip = looksLikeEvaluate ? "\n\nTip: If you truly need raw JavaScript evaluation, use 'bp eval' instead \u2014 no JSON wrapping needed:\n  bp eval 'your.expression.here'\nUse high-level actions plus refs first whenever possible." : "";
     throw new Error(
       `Invalid JSON: ${snippet}${actionsJson.length > 80 ? "..." : ""}
 
@@ -7292,7 +8643,7 @@ Session file has been cleaned up. Run "bp connect" to create a new session.`
     if (failedEval) {
       console.error(
         `
-Tip: Use "bp eval 'expression'" for simpler JavaScript evaluation (no JSON escaping needed).`
+Tip: Use "bp eval 'expression'" for simpler JavaScript inspection/debugging (no JSON escaping needed). Prefer high-level actions for interactions.`
       );
     }
   } finally {
@@ -8674,13 +10025,26 @@ var RECORDER_SCRIPT = `(function() {
 // src/recording/recorder.ts
 var Recorder = class {
   cdp;
+  options;
   events = [];
   recording = false;
   startTime = 0;
   startUrl = "";
   bindingHandler = null;
-  constructor(cdp) {
+  // Network capture state
+  listenOpts = null;
+  networkRequests = [];
+  networkResponses = [];
+  wsEvents = [];
+  wsFrames = [];
+  networkHandlers = [];
+  matchRegex = null;
+  pendingBodies = [];
+  wsUrls = /* @__PURE__ */ new Map();
+  httpUrls = /* @__PURE__ */ new Map();
+  constructor(cdp, options) {
     this.cdp = cdp;
+    this.options = options ?? {};
   }
   /**
    * Check if recording is currently active.
@@ -8726,6 +10090,13 @@ var Recorder = class {
       }
     };
     this.cdp.on("Runtime.bindingCalled", this.bindingHandler);
+    if (this.options.listen) {
+      const listenOpts = typeof this.options.listen === "boolean" ? { mode: "all" } : this.options.listen;
+      this.listenOpts = listenOpts;
+      this.matchRegex = listenOpts.match ? globToRegex2(listenOpts.match) : null;
+      await this.cdp.send("Network.enable");
+      this.setupNetworkListeners(listenOpts);
+    }
   }
   /**
    * Stop recording and return aggregated output.
@@ -8742,13 +10113,39 @@ var Recorder = class {
       this.cdp.off("Runtime.bindingCalled", this.bindingHandler);
       this.bindingHandler = null;
     }
+    for (const { event, handler } of this.networkHandlers) {
+      this.cdp.off(event, handler);
+    }
+    this.networkHandlers = [];
+    if (this.listenOpts) {
+      await this.cdp.send("Network.disable");
+    }
+    await Promise.allSettled(this.pendingBodies);
+    this.pendingBodies = [];
     const steps = aggregateEvents(this.events, this.startUrl);
-    return {
+    const result = {
       recordedAt: new Date(this.startTime).toISOString(),
       startUrl: this.startUrl,
       duration,
       steps
     };
+    if (this.listenOpts) {
+      const mode = this.listenOpts.mode ?? "all";
+      if (mode === "http" || mode === "all") {
+        result.network = {
+          requests: this.networkRequests,
+          responses: this.networkResponses
+        };
+      }
+      if (mode === "ws" || mode === "all") {
+        result.websockets = {
+          events: this.wsEvents,
+          frames: this.wsFrames
+        };
+      }
+      result.timeline = this.buildTimeline();
+    }
+    return result;
   }
   /**
    * Get raw recorded events (for debugging).
@@ -8767,7 +10164,201 @@ var Recorder = class {
     } catch {
     }
   }
+  /** Subscribe to a CDP event, tracking for cleanup. */
+  subscribeNetwork(event, handler) {
+    this.cdp.on(event, handler);
+    this.networkHandlers.push({ event, handler });
+  }
+  /** Check if a URL matches the configured filter. */
+  matchesUrl(url) {
+    if (!this.matchRegex) return true;
+    return this.matchRegex.test(url);
+  }
+  /** Elapsed milliseconds since recording started. */
+  elapsed() {
+    return Date.now() - this.startTime;
+  }
+  /** Format a WebSocket payload, truncating or replacing binary data. */
+  formatPayload(payloadData, opcode) {
+    const data = payloadData ?? "";
+    const maxPayload = this.listenOpts?.maxPayload ?? 256;
+    if (opcode === 2) {
+      const byteLength = Math.floor(data.length * 3 / 4);
+      return { payload: `[binary: ${byteLength} bytes]`, length: data.length };
+    }
+    const length = data.length;
+    if (length > maxPayload) {
+      return {
+        payload: `${data.slice(0, maxPayload)}... [truncated, ${length} total]`,
+        length
+      };
+    }
+    return { payload: data, length };
+  }
+  /** Set up CDP event listeners for network traffic capture. */
+  setupNetworkListeners(opts) {
+    const mode = opts.mode ?? "all";
+    if (mode === "ws" || mode === "all") {
+      this.subscribeNetwork("Network.webSocketCreated", (params) => {
+        const url = params["url"];
+        const requestId = params["requestId"];
+        if (!this.matchesUrl(url)) return;
+        this.wsUrls.set(requestId, url);
+        const now = Date.now();
+        this.wsEvents.push({
+          requestId,
+          timestamp: now,
+          elapsedMs: this.elapsed(),
+          type: "created",
+          url
+        });
+      });
+      this.subscribeNetwork("Network.webSocketFrameSent", (params) => {
+        const requestId = params["requestId"];
+        if (!this.wsUrls.has(requestId)) return;
+        const response = params["response"];
+        const opcode = response?.opcode ?? 1;
+        const { payload, length } = this.formatPayload(response?.payloadData, opcode);
+        const now = Date.now();
+        this.wsFrames.push({
+          requestId,
+          timestamp: now,
+          elapsedMs: this.elapsed(),
+          direction: "sent",
+          opcode,
+          payload,
+          length
+        });
+      });
+      this.subscribeNetwork("Network.webSocketFrameReceived", (params) => {
+        const requestId = params["requestId"];
+        if (!this.wsUrls.has(requestId)) return;
+        const response = params["response"];
+        const opcode = response?.opcode ?? 1;
+        const { payload, length } = this.formatPayload(response?.payloadData, opcode);
+        const now = Date.now();
+        this.wsFrames.push({
+          requestId,
+          timestamp: now,
+          elapsedMs: this.elapsed(),
+          direction: "received",
+          opcode,
+          payload,
+          length
+        });
+      });
+      this.subscribeNetwork("Network.webSocketClosed", (params) => {
+        const requestId = params["requestId"];
+        if (!this.wsUrls.has(requestId)) return;
+        this.wsUrls.delete(requestId);
+        const now = Date.now();
+        this.wsEvents.push({
+          requestId,
+          timestamp: now,
+          elapsedMs: this.elapsed(),
+          type: "closed"
+        });
+      });
+    }
+    if (mode === "http" || mode === "all") {
+      this.subscribeNetwork("Network.requestWillBeSent", (params) => {
+        const request = params["request"];
+        const url = request?.url ?? "";
+        const requestId = params["requestId"];
+        if (!this.matchesUrl(url)) return;
+        this.httpUrls.set(requestId, url);
+        const now = Date.now();
+        this.networkRequests.push({
+          requestId,
+          timestamp: now,
+          elapsedMs: this.elapsed(),
+          method: request?.method ?? "GET",
+          url,
+          headers: request?.headers,
+          body: request?.postData
+        });
+      });
+      this.subscribeNetwork("Network.responseReceived", (params) => {
+        const requestId = params["requestId"];
+        if (!this.httpUrls.has(requestId)) return;
+        const response = params["response"];
+        const now = Date.now();
+        this.networkResponses.push({
+          requestId,
+          timestamp: now,
+          elapsedMs: this.elapsed(),
+          status: response?.status ?? 0,
+          headers: response?.headers,
+          mimeType: response?.mimeType
+        });
+        if (this.listenOpts?.captureResponseBodies) {
+          const bodyPromise = this.cdp.send("Network.getResponseBody", {
+            requestId
+          }).then((result) => {
+            const resp = this.networkResponses.find((r) => r.requestId === requestId);
+            if (resp) {
+              resp.body = result.base64Encoded ? `[base64: ${result.body.length} chars]` : result.body;
+              resp.bodySize = result.body.length;
+            }
+          }).catch(() => {
+          });
+          this.pendingBodies.push(bodyPromise);
+        }
+      });
+    }
+  }
+  /** Build a merged timeline from action events and network events. */
+  buildTimeline() {
+    const entries = [];
+    for (const event of this.events) {
+      entries.push({
+        timestamp: event.timestamp,
+        elapsedMs: event.timestamp - this.startTime,
+        type: "action",
+        data: { kind: event.kind, url: event.url, selectors: event.selectors, value: event.value }
+      });
+    }
+    for (const req of this.networkRequests) {
+      entries.push({
+        timestamp: req.timestamp,
+        elapsedMs: req.elapsedMs,
+        type: "network-request",
+        data: req
+      });
+    }
+    for (const resp of this.networkResponses) {
+      entries.push({
+        timestamp: resp.timestamp,
+        elapsedMs: resp.elapsedMs,
+        type: "network-response",
+        data: resp
+      });
+    }
+    for (const evt of this.wsEvents) {
+      entries.push({
+        timestamp: evt.timestamp,
+        elapsedMs: evt.elapsedMs,
+        type: "ws-event",
+        data: evt
+      });
+    }
+    for (const frame of this.wsFrames) {
+      entries.push({
+        timestamp: frame.timestamp,
+        elapsedMs: frame.elapsedMs,
+        type: "ws-frame",
+        data: frame
+      });
+    }
+    entries.sort((a, b) => a.timestamp - b.timestamp);
+    return entries;
+  }
 };
+function globToRegex2(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const withWildcards = escaped.replace(/\*/g, ".*");
+  return new RegExp(`^${withWildcards}$`);
+}
 
 // src/cli/commands/record.ts
 var RECORD_HELP = `
@@ -8783,16 +10374,25 @@ Options:
                         - -s <id>: use specific session
   -f, --file <path>   Output file (default: recording.json)
   --timeout <ms>      Auto-stop after timeout (optional)
+  --listen [mode]     Capture network traffic: ws, http, or all (default: all)
+  --bodies            Capture HTTP response bodies (requires --listen)
+  -m, --match <glob>  Filter network URLs by glob pattern (requires --listen)
+  --max-payload <n>   Max WebSocket payload preview length (default: 256)
   -h, --help          Show this help
 
 Examples:
-  bp record                        # Auto-connect to local Chrome
-  bp record -s                     # Use most recent session
-  bp record -s mysession           # Use specific session
-  bp record -f login.json          # Save to specific file
-  bp record --timeout 60000        # Auto-stop after 60s
+  bp record                              # Auto-connect to local Chrome
+  bp record -s                           # Use most recent session
+  bp record -s mysession                 # Use specific session
+  bp record -f login.json                # Save to specific file
+  bp record --timeout 60000              # Auto-stop after 60s
+  bp record --listen                     # Record actions + all network traffic
+  bp record --listen ws -m "*voice*"     # Record actions + matching WS traffic
+  bp record --listen http --bodies       # Record actions + HTTP with bodies
 
 Recording captures: clicks, inputs, form submissions, navigation.
+When --listen is enabled, network traffic is captured alongside actions
+and merged into a unified timeline in the output file.
 Password fields are automatically redacted as [REDACTED].
 
 Press Ctrl+C to stop recording and save.
@@ -8812,6 +10412,20 @@ function parseRecordArgs(args) {
       if (!nextArg || nextArg.startsWith("-")) {
         options.useLatestSession = true;
       }
+    } else if (arg === "--listen") {
+      const nextArg = args[i + 1];
+      if (nextArg && (nextArg === "ws" || nextArg === "http" || nextArg === "all")) {
+        options.listen = nextArg;
+        i++;
+      } else {
+        options.listen = true;
+      }
+    } else if (arg === "--bodies") {
+      options.bodies = true;
+    } else if (arg === "-m" || arg === "--match") {
+      options.match = args[++i];
+    } else if (arg === "--max-payload") {
+      options.maxPayload = Number.parseInt(args[++i] ?? "", 10);
     }
   }
   return options;
@@ -8884,7 +10498,17 @@ async function recordCommand(args, globalOptions) {
   }
   const page = await browser.page();
   const cdp = page.cdpClient;
-  const recorder = new Recorder(cdp);
+  let listenConfig;
+  if (options.listen) {
+    const listenOpts = {
+      mode: typeof options.listen === "string" ? options.listen : "all",
+      match: options.match,
+      captureResponseBodies: options.bodies,
+      maxPayload: options.maxPayload
+    };
+    listenConfig = listenOpts;
+  }
+  const recorder = new Recorder(cdp, listenConfig ? { listen: listenConfig } : void 0);
   let stopping = false;
   async function stopAndSave() {
     if (stopping) return;
@@ -8896,15 +10520,23 @@ async function recordCommand(args, globalOptions) {
       const currentUrl = await page.url();
       await updateSession(session.id, { currentUrl });
       await browser.disconnect();
-      console.log(`
-Saved ${recording.steps.length} steps to ${outputFile}`);
+      const networkInfo = recording.network ? `, ${recording.network.requests.length} HTTP requests` : "";
+      const wsInfo = recording.websockets ? `, ${recording.websockets.frames.length} WS frames` : "";
+      const timelineInfo = recording.timeline ? ` (${recording.timeline.length} timeline entries)` : "";
+      console.log(
+        `
+Saved ${recording.steps.length} steps${networkInfo}${wsInfo}${timelineInfo} to ${outputFile}`
+      );
       if (globalOptions.format === "json") {
         output(
           {
             success: true,
             file: outputFile,
             steps: recording.steps.length,
-            duration: recording.duration
+            duration: recording.duration,
+            networkRequests: recording.network?.requests.length ?? 0,
+            wsFrames: recording.websockets?.frames.length ?? 0,
+            timelineEntries: recording.timeline?.length ?? 0
           },
           "json"
         );
@@ -8915,13 +10547,24 @@ Saved ${recording.steps.length} steps to ${outputFile}`);
       process.exit(1);
     }
   }
-  process.on("SIGINT", stopAndSave);
-  process.on("SIGTERM", stopAndSave);
+  const handleSignal = () => {
+    stopAndSave().catch((err) => {
+      console.error("Error during shutdown:", err);
+      process.exit(1);
+    });
+  };
+  process.on("SIGINT", handleSignal);
+  process.on("SIGTERM", handleSignal);
   if (options.timeout && options.timeout > 0) {
     setTimeout(stopAndSave, options.timeout);
   }
   await recorder.start();
   console.log(`Recording... Press Ctrl+C to stop and save to ${outputFile}`);
+  if (options.listen) {
+    const listenMode = typeof options.listen === "string" ? options.listen : "all";
+    const matchLabel = options.match ? ` matching "${options.match}"` : "";
+    console.log(`Network capture: ${listenMode} traffic${matchLabel}`);
+  }
   console.log(`Session: ${session.id}`);
   console.log(`URL: ${await page.url()}`);
 }
@@ -9313,7 +10956,7 @@ function parseSnapshotArgs(args) {
   }
   return options;
 }
-function sleep5(ms) {
+function sleep7(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 async function snapshotCommand(args, globalOptions) {
@@ -9372,7 +11015,7 @@ async function snapshotCommand(args, globalOptions) {
         );
       } else {
         console.log("Overlay will be removed in 10 seconds...");
-        await sleep5(1e4);
+        await sleep7(1e4);
         await removeRefOverlay(page);
         console.log("Overlay removed.");
       }