browser-pilot 0.0.10 → 0.0.12

package/dist/index.cjs

@@ -62,13 +62,599 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// 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) {
+    // If tab is backgrounded, RAF won't fire reliably \u2014 skip stability check
+    if (document.visibilityState === 'hidden') {
+      var rect = self.getBoundingClientRect();
+      resolve({ actionable: rect.width > 0 && rect.height > 0 });
+      return;
+    }
+
+    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 sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var BACKOFF = [0, 20, 100, 100];
+async function runCheck(cdp, objectId, check, options) {
+  let script;
+  let awaitPromise = false;
+  const args = [];
+  switch (check) {
+    case "visible":
+      script = CHECK_VISIBLE;
+      break;
+    case "enabled":
+      script = CHECK_ENABLED;
+      break;
+    case "stable":
+      script = CHECK_STABLE;
+      awaitPromise = true;
+      break;
+    case "hitTarget":
+      script = CHECK_HIT_TARGET;
+      if (options?.coordinates) {
+        args.push({ value: options.coordinates.x });
+        args.push({ value: options.coordinates.y });
+      } else {
+        args.push({ value: void 0 });
+        args.push({ value: void 0 });
+      }
+      break;
+    case "editable":
+      script = CHECK_EDITABLE;
+      break;
+    default: {
+      const _exhaustive = check;
+      throw new Error(`Unknown actionability check: ${_exhaustive}`);
+    }
+  }
+  const params = {
+    functionDeclaration: script,
+    objectId,
+    returnByValue: true,
+    arguments: args
+  };
+  if (awaitPromise) {
+    params["awaitPromise"] = true;
+  }
+  const response = await cdp.send("Runtime.callFunctionOn", params);
+  if (response.exceptionDetails) {
+    return {
+      actionable: false,
+      reason: `Check "${check}" threw: ${response.exceptionDetails.text}`,
+      failureType: check
+    };
+  }
+  const result = response.result.value;
+  if (!result.actionable) {
+    result.failureType = check;
+  }
+  return result;
+}
+async function runChecks(cdp, objectId, checks, options) {
+  for (const check of checks) {
+    const result = await runCheck(cdp, objectId, check, options);
+    if (!result.actionable) {
+      return result;
+    }
+  }
+  return { actionable: true };
+}
+async function ensureActionable(cdp, objectId, checks, options) {
+  const timeout = options?.timeout ?? 3e4;
+  const start = Date.now();
+  let attempt = 0;
+  while (true) {
+    const result = await runChecks(cdp, objectId, checks, options);
+    if (result.actionable) return;
+    if (Date.now() - start >= timeout) {
+      throw new ActionabilityError(
+        `Element not actionable: ${result.reason}`,
+        result.failureType,
+        result.coveringElement
+      );
+    }
+    const delay = attempt < BACKOFF.length ? BACKOFF[attempt] ?? 0 : 500;
+    if (delay > 0) await sleep(delay);
+    attempt++;
+  }
+}
+
+// src/browser/fuzzy-match.ts
+function jaroWinkler(a, b) {
+  if (a.length === 0 && b.length === 0) return 0;
+  if (a.length === 0 || b.length === 0) return 0;
+  if (a === b) return 1;
+  const s1 = a.toLowerCase();
+  const s2 = b.toLowerCase();
+  const matchWindow = Math.max(0, Math.floor(Math.max(s1.length, s2.length) / 2) - 1);
+  const s1Matches = Array.from({ length: s1.length }, () => false);
+  const s2Matches = Array.from({ length: s2.length }, () => false);
+  let matches = 0;
+  let transpositions = 0;
+  for (let i = 0; i < s1.length; i++) {
+    const start = Math.max(0, i - matchWindow);
+    const end = Math.min(i + matchWindow + 1, s2.length);
+    for (let j = start; j < end; j++) {
+      if (s2Matches[j] || s1[i] !== s2[j]) continue;
+      s1Matches[i] = true;
+      s2Matches[j] = true;
+      matches++;
+      break;
+    }
+  }
+  if (matches === 0) return 0;
+  let k = 0;
+  for (let i = 0; i < s1.length; i++) {
+    if (!s1Matches[i]) continue;
+    while (!s2Matches[k]) k++;
+    if (s1[i] !== s2[k]) transpositions++;
+    k++;
+  }
+  const jaro = (matches / s1.length + matches / s2.length + (matches - transpositions / 2) / matches) / 3;
+  let prefix = 0;
+  for (let i = 0; i < Math.min(4, Math.min(s1.length, s2.length)); i++) {
+    if (s1[i] === s2[i]) {
+      prefix++;
+    } else {
+      break;
+    }
+  }
+  const WINKLER_SCALING = 0.1;
+  return jaro + prefix * WINKLER_SCALING * (1 - jaro);
+}
+function stringSimilarity(a, b) {
+  if (a.length === 0 || b.length === 0) return 0;
+  const lowerA = a.toLowerCase();
+  const lowerB = b.toLowerCase();
+  if (lowerA === lowerB) return 1;
+  const jw = jaroWinkler(a, b);
+  let containsBonus = 0;
+  if (lowerB.includes(lowerA)) {
+    containsBonus = 0.2;
+  } else if (lowerA.includes(lowerB)) {
+    containsBonus = 0.1;
+  }
+  return Math.min(1, jw + containsBonus);
+}
+function scoreElement(query, element) {
+  const lowerQuery = query.toLowerCase();
+  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
+  let nameScore = 0;
+  if (element.name) {
+    const lowerName = element.name.toLowerCase();
+    if (lowerName === lowerQuery) {
+      nameScore = 1;
+    } else if (lowerName.includes(lowerQuery)) {
+      nameScore = 0.8;
+    } else if (words.length > 0) {
+      const matchedWords = words.filter((w) => lowerName.includes(w));
+      nameScore = matchedWords.length / words.length * 0.7;
+    } else {
+      nameScore = stringSimilarity(query, element.name) * 0.6;
+    }
+  }
+  let roleScore = 0;
+  const lowerRole = element.role.toLowerCase();
+  if (lowerRole === lowerQuery || lowerQuery.includes(lowerRole)) {
+    roleScore = 0.3;
+  } else if (words.some((w) => lowerRole.includes(w))) {
+    roleScore = 0.2;
+  }
+  let selectorScore = 0;
+  const lowerSelector = element.selector.toLowerCase();
+  if (words.some((w) => lowerSelector.includes(w))) {
+    selectorScore = 0.2;
+  }
+  const totalScore = nameScore * 0.6 + roleScore * 0.25 + selectorScore * 0.15;
+  return totalScore;
+}
+function explainMatch(query, element, score) {
+  const reasons = [];
+  const lowerQuery = query.toLowerCase();
+  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
+  if (element.name) {
+    const lowerName = element.name.toLowerCase();
+    if (lowerName === lowerQuery) {
+      reasons.push("exact name match");
+    } else if (lowerName.includes(lowerQuery)) {
+      reasons.push("name contains query");
+    } else if (words.some((w) => lowerName.includes(w))) {
+      const matchedWords = words.filter((w) => lowerName.includes(w));
+      reasons.push(`name contains: ${matchedWords.join(", ")}`);
+    } else if (stringSimilarity(query, element.name) > 0.5) {
+      reasons.push("similar name");
+    }
+  }
+  const lowerRole = element.role.toLowerCase();
+  if (lowerRole === lowerQuery || words.some((w) => w === lowerRole)) {
+    reasons.push(`role: ${element.role}`);
+  }
+  if (words.some((w) => element.selector.toLowerCase().includes(w))) {
+    reasons.push("selector match");
+  }
+  if (reasons.length === 0) {
+    reasons.push(`fuzzy match (score: ${score.toFixed(2)})`);
+  }
+  return reasons.join(", ");
+}
+function fuzzyMatchElements(query, elements, maxResults = 5) {
+  if (!query || query.length === 0) {
+    return [];
+  }
+  const THRESHOLD = 0.3;
+  const scored = elements.map((element) => ({
+    element,
+    score: scoreElement(query, element)
+  }));
+  return scored.filter((s) => s.score >= THRESHOLD).sort((a, b) => b.score - a.score).slice(0, maxResults).map((s) => ({
+    element: s.element,
+    score: s.score,
+    matchReason: explainMatch(query, s.element, s.score)
+  }));
+}
+
+// src/browser/hint-generator.ts
+var ACTION_ROLE_MAP = {
+  click: ["button", "link", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "option"],
+  fill: ["textbox", "searchbox", "textarea"],
+  type: ["textbox", "searchbox", "textarea"],
+  submit: ["button", "form"],
+  select: ["combobox", "listbox", "option"],
+  check: ["checkbox", "radio", "switch"],
+  uncheck: ["checkbox", "switch"],
+  focus: [],
+  // Any focusable element
+  hover: [],
+  // Any element
+  clear: ["textbox", "searchbox", "textarea"]
+};
+function extractIntent(selectors) {
+  const patterns = [];
+  let text = "";
+  for (const selector of selectors) {
+    if (selector.startsWith("ref:")) {
+      continue;
+    }
+    const idMatch = selector.match(/#([a-zA-Z0-9_-]+)/);
+    if (idMatch) {
+      patterns.push(idMatch[1]);
+    }
+    const ariaMatch = selector.match(/\[aria-label=["']([^"']+)["']\]/);
+    if (ariaMatch) {
+      patterns.push(ariaMatch[1]);
+    }
+    const testidMatch = selector.match(/\[data-testid=["']([^"']+)["']\]/);
+    if (testidMatch) {
+      patterns.push(testidMatch[1]);
+    }
+    const classMatch = selector.match(/\.([a-zA-Z0-9_-]+)/);
+    if (classMatch) {
+      patterns.push(classMatch[1]);
+    }
+  }
+  patterns.sort((a, b) => b.length - a.length);
+  text = patterns[0] ?? selectors[0] ?? "";
+  return { text, patterns };
+}
+function getHintType(selector) {
+  if (selector.startsWith("ref:")) return "ref";
+  if (selector.includes("data-testid")) return "testid";
+  if (selector.includes("aria-label")) return "aria";
+  if (selector.startsWith("#")) return "id";
+  return "css";
+}
+function getConfidence(score) {
+  if (score >= 0.8) return "high";
+  if (score >= 0.5) return "medium";
+  return "low";
+}
+function diversifyHints(candidates, maxHints) {
+  const hints = [];
+  const usedTypes = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    if (hints.length >= maxHints) break;
+    const refSelector = `ref:${candidate.element.ref}`;
+    const hintType = getHintType(refSelector);
+    if (!usedTypes.has(hintType)) {
+      hints.push({
+        selector: refSelector,
+        reason: candidate.matchReason,
+        confidence: getConfidence(candidate.score),
+        element: {
+          ref: candidate.element.ref,
+          role: candidate.element.role,
+          name: candidate.element.name,
+          disabled: candidate.element.disabled
+        }
+      });
+      usedTypes.add(hintType);
+    } else if (hints.length < maxHints) {
+      hints.push({
+        selector: refSelector,
+        reason: candidate.matchReason,
+        confidence: getConfidence(candidate.score),
+        element: {
+          ref: candidate.element.ref,
+          role: candidate.element.role,
+          name: candidate.element.name,
+          disabled: candidate.element.disabled
+        }
+      });
+    }
+  }
+  return hints;
+}
+async function generateHints(page, failedSelectors, actionType, maxHints = 3) {
+  let snapshot;
+  try {
+    snapshot = await page.snapshot();
+  } catch {
+    return [];
+  }
+  const intent = extractIntent(failedSelectors);
+  const roleFilter = ACTION_ROLE_MAP[actionType] ?? [];
+  let candidates = snapshot.interactiveElements;
+  if (roleFilter.length > 0) {
+    candidates = candidates.filter((el) => roleFilter.includes(el.role));
+  }
+  const matches = fuzzyMatchElements(intent.text, candidates, maxHints * 2);
+  if (matches.length === 0) {
+    return [];
+  }
+  return diversifyHints(matches, maxHints);
+}
+
 // src/browser/types.ts
 var ElementNotFoundError = class extends Error {
   selectors;
   hints;
   constructor(selectors, hints) {
     const selectorList = Array.isArray(selectors) ? selectors : [selectors];
-    super(`Element not found: ${selectorList.join(", ")}`);
+    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;
@@ -76,7 +662,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";
   }
 };
@@ -87,8 +674,87 @@ var NavigationError = class extends Error {
   }
 };
 
+// src/cdp/protocol.ts
+var CDPError = class extends Error {
+  code;
+  data;
+  constructor(error) {
+    super(error.message);
+    this.name = "CDPError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+};
+
 // src/actions/executor.ts
 var DEFAULT_TIMEOUT = 3e4;
+function classifyFailure(error) {
+  if (error instanceof ElementNotFoundError) {
+    return { reason: "missing" };
+  }
+  if (error instanceof ActionabilityError) {
+    switch (error.failureType) {
+      case "visible":
+        return { reason: "hidden" };
+      case "hitTarget":
+        return { reason: "covered", coveringElement: error.coveringElement };
+      case "enabled":
+        return { reason: "disabled" };
+      case "editable":
+        return { reason: error.message?.includes("readonly") ? "readonly" : "notEditable" };
+      case "stable":
+        return { reason: "replaced" };
+      default:
+        return { reason: "unknown" };
+    }
+  }
+  if (error instanceof TimeoutError) {
+    return { reason: "timeout" };
+  }
+  if (error instanceof NavigationError) {
+    return { reason: "navigation" };
+  }
+  if (error instanceof CDPError) {
+    return { reason: "cdpError" };
+  }
+  const msg = String(error?.message ?? error);
+  if (msg.includes("Could not find node") || msg.includes("does not belong to the document")) {
+    return { reason: "detached" };
+  }
+  return { reason: "unknown" };
+}
+function getSuggestion(reason) {
+  switch (reason) {
+    case "missing":
+      return "Element not found. Run 'snapshot' to see available elements, or try alternative selectors.";
+    case "hidden":
+      return "Element exists but is not visible. Try 'scroll' or wait for it to appear.";
+    case "covered":
+      return "Element is blocked by another element. Dismiss the covering element first.";
+    case "disabled":
+      return "Element is disabled. Complete prerequisite steps to enable it.";
+    case "readonly":
+      return "Element is readonly and cannot be edited directly.";
+    case "detached":
+      return "Element was removed from the DOM. Run 'snapshot' for fresh element refs.";
+    case "replaced":
+      return "Element was replaced in the DOM. Run 'snapshot' to get updated refs.";
+    case "notEditable":
+      return "Element is not an editable field. Try a different selector targeting an input or textarea.";
+    case "timeout":
+      return "Timed out waiting. The page may still be loading. Try increasing timeout.";
+    case "navigation":
+      return "Navigation failed. Check the URL and network connectivity.";
+    case "cdpError":
+      return "Browser connection error. Try 'bp connect' again.";
+    case "unknown":
+      return "Unexpected error. Run 'snapshot' to check page state.";
+    default: {
+      const _exhaustive = reason;
+      return `Unknown failure: ${_exhaustive}`;
+    }
+  }
+}
 var BatchExecutor = class {
   page;
   constructor(page) {
@@ -104,21 +770,46 @@ var BatchExecutor = class {
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
       const stepStart = Date.now();
-      try {
-        const result = await this.executeStep(step, timeout);
-        results.push({
-          index: i,
-          action: step.action,
-          selector: step.selector,
-          selectorUsed: result.selectorUsed,
-          success: true,
-          durationMs: Date.now() - stepStart,
-          result: result.value,
-          text: result.text
-        });
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        const hints = error instanceof ElementNotFoundError ? error.hints : void 0;
+      const maxAttempts = (step.retry ?? 0) + 1;
+      const retryDelay = step.retryDelay ?? 500;
+      let lastError;
+      let succeeded = false;
+      for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        if (attempt > 0) {
+          await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        }
+        try {
+          const result = await this.executeStep(step, timeout);
+          results.push({
+            index: i,
+            action: step.action,
+            selector: step.selector,
+            selectorUsed: result.selectorUsed,
+            success: true,
+            durationMs: Date.now() - stepStart,
+            result: result.value,
+            text: result.text
+          });
+          succeeded = true;
+          break;
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+        }
+      }
+      if (!succeeded) {
+        const errorMessage = lastError?.message ?? "Unknown error";
+        let hints = lastError instanceof ElementNotFoundError ? lastError.hints : void 0;
+        const { reason, coveringElement } = classifyFailure(lastError);
+        if (step.selector && !step.optional && ["missing", "hidden", "covered", "disabled", "detached", "replaced"].includes(reason)) {
+          try {
+            const selectors = Array.isArray(step.selector) ? step.selector : [step.selector];
+            const autoHints = await generateHints(this.page, selectors, step.action, 3);
+            if (autoHints.length > 0) {
+              hints = autoHints;
+            }
+          } catch {
+          }
+        }
         results.push({
           index: i,
           action: step.action,
@@ -126,7 +817,10 @@ var BatchExecutor = class {
           success: false,
           durationMs: Date.now() - stepStart,
           error: errorMessage,
-          hints
+          hints,
+          failureReason: reason,
+          coveringElement,
+          suggestion: getSuggestion(reason)
         });
         if (onFail === "stop" && !step.optional) {
           return {
@@ -159,7 +853,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;
@@ -174,7 +868,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) };
@@ -222,13 +915,31 @@ 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) };
       }
       case "press": {
         if (!step.key) throw new Error("press requires key");
-        await this.page.press(step.key);
+        try {
+          await this.page.press(step.key, {
+            modifiers: step.modifiers
+          });
+        } catch (e) {
+          if (optional) return {};
+          throw e;
+        }
+        return {};
+      }
+      case "shortcut": {
+        if (!step.combo) throw new Error("shortcut requires combo");
+        try {
+          await this.page.shortcut(step.combo);
+        } catch (e) {
+          if (optional) return {};
+          throw e;
+        }
         return {};
       }
       case "focus": {
@@ -315,6 +1026,80 @@ var BatchExecutor = class {
         await this.page.switchToMain();
         return {};
       }
+      case "assertVisible": {
+        if (!step.selector) throw new Error("assertVisible requires selector");
+        const el = await this.page.waitFor(step.selector, {
+          timeout,
+          optional: true,
+          state: "visible"
+        });
+        if (!el) {
+          throw new Error(
+            `Assertion failed: selector ${JSON.stringify(step.selector)} is not visible`
+          );
+        }
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "assertExists": {
+        if (!step.selector) throw new Error("assertExists requires selector");
+        const el = await this.page.waitFor(step.selector, {
+          timeout,
+          optional: true,
+          state: "attached"
+        });
+        if (!el) {
+          throw new Error(
+            `Assertion failed: selector ${JSON.stringify(step.selector)} does not exist`
+          );
+        }
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "assertText": {
+        const selector = Array.isArray(step.selector) ? step.selector[0] : step.selector;
+        const text = await this.page.text(selector);
+        const expected = step.expect ?? step.value;
+        if (typeof expected !== "string") throw new Error("assertText requires expect or value");
+        if (!text.includes(expected)) {
+          throw new Error(
+            `Assertion failed: text does not contain ${JSON.stringify(expected)}. Got: ${JSON.stringify(text.slice(0, 200))}`
+          );
+        }
+        return { selectorUsed: selector, text };
+      }
+      case "assertUrl": {
+        const currentUrl = await this.page.url();
+        const expected = step.expect ?? step.url;
+        if (typeof expected !== "string") throw new Error("assertUrl requires expect or url");
+        if (!currentUrl.includes(expected)) {
+          throw new Error(
+            `Assertion failed: URL does not contain ${JSON.stringify(expected)}. Got: ${JSON.stringify(currentUrl)}`
+          );
+        }
+        return { value: currentUrl };
+      }
+      case "assertValue": {
+        if (!step.selector) throw new Error("assertValue requires selector");
+        const expected = step.expect ?? step.value;
+        if (typeof expected !== "string") throw new Error("assertValue requires expect or value");
+        const found = await this.page.waitFor(step.selector, {
+          timeout,
+          optional: true,
+          state: "attached"
+        });
+        if (!found) {
+          throw new Error(`Assertion failed: selector ${JSON.stringify(step.selector)} not found`);
+        }
+        const usedSelector = this.getUsedSelector(step.selector);
+        const actual = await this.page.evaluate(
+          `(function() { var el = document.querySelector(${JSON.stringify(usedSelector)}); return el ? el.value : null; })()`
+        );
+        if (actual !== expected) {
+          throw new Error(
+            `Assertion failed: value of ${JSON.stringify(usedSelector)} is ${JSON.stringify(actual)}, expected ${JSON.stringify(expected)}`
+          );
+        }
+        return { selectorUsed: usedSelector, value: actual };
+      }
       default: {
         const action = step.action;
         const aliases = {
@@ -327,16 +1112,43 @@ var BatchExecutor = class {
           capture: "screenshot",
           inspect: "snapshot",
           enter: "press",
+          keypress: "press",
+          hotkey: "shortcut",
+          keybinding: "shortcut",
+          nav: "goto",
           open: "goto",
           visit: "goto",
+          browse: "goto",
+          load: "goto",
+          write: "fill",
+          set: "fill",
+          pick: "select",
+          choose: "select",
+          send: "press",
           eval: "evaluate",
           js: "evaluate",
+          script: "evaluate",
           snap: "snapshot",
-          frame: "switchFrame"
+          accessibility: "snapshot",
+          a11y: "snapshot",
+          image: "screenshot",
+          pic: "screenshot",
+          frame: "switchFrame",
+          iframe: "switchFrame",
+          assert_visible: "assertVisible",
+          assert_exists: "assertExists",
+          assert_text: "assertText",
+          assert_url: "assertUrl",
+          assert_value: "assertValue",
+          checkvisible: "assertVisible",
+          checkexists: "assertExists",
+          checktext: "assertText",
+          checkurl: "assertUrl",
+          checkvalue: "assertValue"
         };
         const suggestion = aliases[action.toLowerCase()];
         const hint = suggestion ? ` Did you mean "${suggestion}"?` : "";
-        const valid = "goto, click, fill, type, select, check, uncheck, submit, press, focus, hover, scroll, wait, snapshot, screenshot, evaluate, text, switchFrame, switchToMain";
+        const valid = "goto, click, fill, type, select, check, uncheck, submit, press, shortcut, focus, hover, scroll, wait, snapshot, screenshot, evaluate, text, switchFrame, switchToMain, assertVisible, assertExists, assertText, assertUrl, assertValue";
         throw new Error(`Unknown action "${action}".${hint}
 
 Valid actions: ${valid}`);
@@ -385,6 +1197,8 @@ var ACTION_ALIASES = {
   inspect: "snapshot",
   enter: "press",
   keypress: "press",
+  hotkey: "shortcut",
+  keybinding: "shortcut",
   nav: "goto",
   open: "goto",
   visit: "goto",
@@ -404,7 +1218,17 @@ var ACTION_ALIASES = {
   image: "screenshot",
   pic: "screenshot",
   frame: "switchFrame",
-  iframe: "switchFrame"
+  iframe: "switchFrame",
+  assert_visible: "assertVisible",
+  assert_exists: "assertExists",
+  assert_text: "assertText",
+  assert_url: "assertUrl",
+  assert_value: "assertValue",
+  checkvisible: "assertVisible",
+  checkexists: "assertExists",
+  checktext: "assertText",
+  checkurl: "assertUrl",
+  checkvalue: "assertValue"
 };
 var PROPERTY_ALIASES = {
   expression: "value",
@@ -425,6 +1249,9 @@ var PROPERTY_ALIASES = {
   input: "value",
   content: "value",
   keys: "key",
+  shortcutKey: "combo",
+  hotkey: "combo",
+  keybinding: "combo",
   button: "key",
   address: "url",
   page: "url",
@@ -438,20 +1265,20 @@ var ACTION_RULES = {
   click: {
     required: { selector: { type: "string|string[]" } },
     optional: {
-      waitForNavigation: { type: "boolean" }
+      waitForNavigation: { type: "boolean|auto" }
     }
   },
   fill: {
     required: { selector: { type: "string|string[]" }, value: { type: "string" } },
     optional: {
-      clear: { type: "boolean" },
       blur: { type: "boolean" }
     }
   },
   type: {
     required: { selector: { type: "string|string[]" }, value: { type: "string" } },
     optional: {
-      delay: { type: "number" }
+      delay: { type: "number" },
+      blur: { type: "boolean" }
     }
   },
   select: {
@@ -475,11 +1302,18 @@ 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: {
     required: { key: { type: "string" } },
+    optional: {
+      modifiers: { type: "string|string[]" }
+    }
+  },
+  shortcut: {
+    required: { combo: { type: "string" } },
     optional: {}
   },
   focus: {
@@ -539,6 +1373,36 @@ var ACTION_RULES = {
   switchToMain: {
     required: {},
     optional: {}
+  },
+  assertVisible: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {}
+  },
+  assertExists: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {}
+  },
+  assertText: {
+    required: {},
+    optional: {
+      selector: { type: "string|string[]" },
+      expect: { type: "string" },
+      value: { type: "string" }
+    }
+  },
+  assertUrl: {
+    required: {},
+    optional: {
+      expect: { type: "string" },
+      url: { type: "string" }
+    }
+  },
+  assertValue: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {
+      expect: { type: "string" },
+      value: { type: "string" }
+    }
   }
 };
 var VALID_ACTIONS = Object.keys(ACTION_RULES);
@@ -549,11 +1413,12 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "url",
   "value",
   "key",
+  "combo",
+  "modifiers",
   "waitFor",
   "timeout",
   "optional",
   "method",
-  "clear",
   "blur",
   "delay",
   "waitForNavigation",
@@ -566,7 +1431,10 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "amount",
   "format",
   "quality",
-  "fullPage"
+  "fullPage",
+  "expect",
+  "retry",
+  "retryDelay"
 ]);
 function resolveAction(name) {
   if (VALID_ACTIONS.includes(name)) {
@@ -634,6 +1502,15 @@ 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;
+    default: {
+      const _exhaustive = rule.type;
+      return `unknown type: ${_exhaustive}`;
+    }
   }
 }
 function validateSteps(steps) {
@@ -747,6 +1624,51 @@ function validateSteps(steps) {
         });
       }
     }
+    if ("retry" in obj && obj["retry"] !== void 0) {
+      if (typeof obj["retry"] !== "number") {
+        errors.push({
+          stepIndex: i,
+          field: "retry",
+          message: `"retry" expected number, got ${typeof obj["retry"]}.`
+        });
+      }
+    }
+    if ("retryDelay" in obj && obj["retryDelay"] !== void 0) {
+      if (typeof obj["retryDelay"] !== "number") {
+        errors.push({
+          stepIndex: i,
+          field: "retryDelay",
+          message: `"retryDelay" expected number, got ${typeof obj["retryDelay"]}.`
+        });
+      }
+    }
+    if (action === "assertText") {
+      if (!("expect" in obj) && !("value" in obj)) {
+        errors.push({
+          stepIndex: i,
+          field: "expect",
+          message: 'assertText requires "expect" or "value" containing the expected text.'
+        });
+      }
+    }
+    if (action === "assertUrl") {
+      if (!("expect" in obj) && !("url" in obj)) {
+        errors.push({
+          stepIndex: i,
+          field: "expect",
+          message: 'assertUrl requires "expect" or "url" containing the expected URL substring.'
+        });
+      }
+    }
+    if (action === "assertValue") {
+      if (!("expect" in obj) && !("value" in obj)) {
+        errors.push({
+          stepIndex: i,
+          field: "expect",
+          message: 'assertValue requires "expect" or "value" containing the expected value.'
+        });
+      }
+    }
     if (action === "select") {
       const hasNative = "selector" in obj && "value" in obj;
       const hasCustom = "trigger" in obj && "option" in obj && "value" in obj;
@@ -1899,7 +2821,7 @@ var AudioOutput = class {
       awaitPromise: false
     });
     this.capturing = false;
-    await sleep(250);
+    await sleep2(250);
     return this.mergeChunks();
   }
   /**
@@ -1924,35 +2846,37 @@ var AudioOutput = class {
       let heardAudio = false;
       let lastSoundTime = 0;
       const startTime = Date.now();
-      const checkInterval = setInterval(async () => {
-        const elapsed = Date.now() - startTime;
-        if (elapsed > maxDuration) {
-          clearInterval(checkInterval);
-          this.onDiagHandler?.(`max duration reached (${maxDuration}ms), stopping`);
-          resolve(await this.stop());
-          return;
-        }
-        const latest = this.chunks[this.chunks.length - 1];
-        if (latest) {
-          const rms = calculateRMS(latest.left);
-          if (rms > silenceThreshold) {
-            if (!heardAudio) {
-              heardAudio = true;
-              this.onDiagHandler?.("first audio detected \u2014 silence countdown begins");
+      const checkInterval = setInterval(() => {
+        void (async () => {
+          const elapsed = Date.now() - startTime;
+          if (elapsed > maxDuration) {
+            clearInterval(checkInterval);
+            this.onDiagHandler?.(`max duration reached (${maxDuration}ms), stopping`);
+            resolve(await this.stop());
+            return;
+          }
+          const latest = this.chunks[this.chunks.length - 1];
+          if (latest) {
+            const rms = calculateRMS(latest.left);
+            if (rms > silenceThreshold) {
+              if (!heardAudio) {
+                heardAudio = true;
+                this.onDiagHandler?.("first audio detected \u2014 silence countdown begins");
+              }
+              lastSoundTime = Date.now();
             }
-            lastSoundTime = Date.now();
           }
-        }
-        if (!heardAudio && elapsed > noAudioTimeout) {
-          clearInterval(checkInterval);
-          this.onDiagHandler?.(`no audio detected after ${noAudioTimeout}ms, stopping early`);
-          resolve(await this.stop());
-          return;
-        }
-        if (heardAudio && Date.now() - lastSoundTime > silenceTimeout) {
-          clearInterval(checkInterval);
-          resolve(await this.stop());
-        }
+          if (!heardAudio && elapsed > noAudioTimeout) {
+            clearInterval(checkInterval);
+            this.onDiagHandler?.(`no audio detected after ${noAudioTimeout}ms, stopping early`);
+            resolve(await this.stop());
+            return;
+          }
+          if (heardAudio && Date.now() - lastSoundTime > silenceTimeout) {
+            clearInterval(checkInterval);
+            resolve(await this.stop());
+          }
+        })();
       }, 200);
     });
   }
@@ -2113,7 +3037,7 @@ function emptyCaptureResult() {
     chunkCount: 0
   };
 }
-function sleep(ms) {
+function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
@@ -2212,18 +3136,6 @@ Content-Type: ${contentType}\r
   parts.push(data);
 }
 
-// src/cdp/protocol.ts
-var CDPError = class extends Error {
-  code;
-  data;
-  constructor(error) {
-    super(error.message);
-    this.name = "CDPError";
-    this.code = error.code;
-    this.data = error.data;
-  }
-};
-
 // src/cdp/transport.ts
 function createTransport(wsUrl, options = {}) {
   const { timeout = 3e4 } = options;
@@ -2253,13 +3165,28 @@ function createTransport(wsUrl, options = {}) {
               resolveClose();
               return;
             }
-            const onClose = () => {
+            let settled = false;
+            let fallbackTimer;
+            const finish = () => {
+              if (settled) return;
+              settled = true;
+              if (fallbackTimer) clearTimeout(fallbackTimer);
               ws.removeEventListener("close", onClose);
               resolveClose();
             };
+            const onClose = () => {
+              finish();
+            };
             ws.addEventListener("close", onClose);
-            ws.close();
-            setTimeout(resolveClose, 5e3);
+            try {
+              if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                ws.close();
+              }
+            } catch {
+              finish();
+              return;
+            }
+            fallbackTimer = setTimeout(finish, 200);
           });
         },
         onMessage(handler) {
@@ -2589,6 +3516,34 @@ var BrowserlessProvider = class {
 };
 
 // src/providers/generic.ts
+function sleep3(ms) {
+  return new Promise((resolve) => setTimeout(resolve, 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 sleep3(delayMs);
+      delayMs = Math.min(delayMs * 2, maxDelayMs);
+    }
+  }
+  throw lastError ?? new Error(errorPrefix);
+}
 var GenericProvider = class {
   name = "generic";
   wsUrl;
@@ -2607,20 +3562,14 @@ var GenericProvider = class {
   }
 };
 async function discoverTargets(host = "localhost:9222") {
-  const protocol = host.includes("://") ? "" : "http://";
-  const response = await fetch(`${protocol}${host}/json/list`);
-  if (!response.ok) {
-    throw new Error(`Failed to discover targets: ${response.status}`);
-  }
-  return await response.json();
+  return fetchDevToolsJson(host, "/json/list", "Failed to discover targets");
 }
 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;
 }
 
@@ -2667,8 +3616,12 @@ var RequestInterceptor = class {
   boundHandleAuthRequired;
   constructor(cdp) {
     this.cdp = cdp;
-    this.boundHandleRequestPaused = this.handleRequestPaused.bind(this);
-    this.boundHandleAuthRequired = this.handleAuthRequired.bind(this);
+    this.boundHandleRequestPaused = (params) => {
+      void this.handleRequestPaused(params);
+    };
+    this.boundHandleAuthRequired = (params) => {
+      void this.handleAuthRequired(params);
+    };
   }
   /**
    * Enable request interception with optional patterns
@@ -2895,429 +3848,463 @@ async function isElementVisible(cdp, selector, contextId) {
 }
 async function isElementAttached(cdp, selector, contextId) {
   const params = {
-    expression: `(() => {
-      ${DEEP_QUERY_SCRIPT}
-      return deepQuery(${JSON.stringify(selector)}) !== null;
-    })()`,
-    returnByValue: true
-  };
-  if (contextId !== void 0) {
-    params["contextId"] = contextId;
-  }
-  const result = await cdp.send("Runtime.evaluate", params);
-  return result.result.value === true;
-}
-function sleep2(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-async function waitForElement(cdp, selector, options = {}) {
-  const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
-  const startTime = Date.now();
-  const deadline = startTime + timeout;
-  while (Date.now() < deadline) {
-    let conditionMet = false;
-    switch (state) {
-      case "visible":
-        conditionMet = await isElementVisible(cdp, selector, contextId);
-        break;
-      case "hidden":
-        conditionMet = !await isElementVisible(cdp, selector, contextId);
-        break;
-      case "attached":
-        conditionMet = await isElementAttached(cdp, selector, contextId);
-        break;
-      case "detached":
-        conditionMet = !await isElementAttached(cdp, selector, contextId);
-        break;
-    }
-    if (conditionMet) {
-      return { success: true, waitedMs: Date.now() - startTime };
-    }
-    await sleep2(pollInterval);
-  }
-  return { success: false, waitedMs: Date.now() - startTime };
-}
-async function waitForAnyElement(cdp, selectors, options = {}) {
-  const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
-  const startTime = Date.now();
-  const deadline = startTime + timeout;
-  while (Date.now() < deadline) {
-    for (const selector of selectors) {
-      let conditionMet = false;
-      switch (state) {
-        case "visible":
-          conditionMet = await isElementVisible(cdp, selector, contextId);
-          break;
-        case "hidden":
-          conditionMet = !await isElementVisible(cdp, selector, contextId);
-          break;
-        case "attached":
-          conditionMet = await isElementAttached(cdp, selector, contextId);
-          break;
-        case "detached":
-          conditionMet = !await isElementAttached(cdp, selector, contextId);
-          break;
-      }
-      if (conditionMet) {
-        return { success: true, selector, waitedMs: Date.now() - startTime };
-      }
-    }
-    await sleep2(pollInterval);
-  }
-  return { success: false, waitedMs: Date.now() - startTime };
-}
-async function getCurrentUrl(cdp) {
-  const result = await cdp.send("Runtime.evaluate", {
-    expression: "location.href",
-    returnByValue: true
-  });
-  return result.result.value;
-}
-async function waitForNavigation(cdp, options = {}) {
-  const { timeout = 3e4, allowSameDocument = true } = options;
-  const startTime = Date.now();
-  let startUrl;
-  try {
-    startUrl = await getCurrentUrl(cdp);
-  } catch {
-    startUrl = "";
-  }
-  return new Promise((resolve) => {
-    let resolved = false;
-    const cleanup = [];
-    const done = (success) => {
-      if (resolved) return;
-      resolved = true;
-      for (const fn of cleanup) fn();
-      resolve({ success, waitedMs: Date.now() - startTime });
-    };
-    const timer = setTimeout(() => done(false), timeout);
-    cleanup.push(() => clearTimeout(timer));
-    const onLoad = () => done(true);
-    cdp.on("Page.loadEventFired", onLoad);
-    cleanup.push(() => cdp.off("Page.loadEventFired", onLoad));
-    const onFrameNavigated = (params) => {
-      const frame = params["frame"];
-      if (frame && !frame.parentId && frame.url !== startUrl) {
-        done(true);
-      }
-    };
-    cdp.on("Page.frameNavigated", onFrameNavigated);
-    cleanup.push(() => cdp.off("Page.frameNavigated", onFrameNavigated));
-    if (allowSameDocument) {
-      const onSameDoc = () => done(true);
-      cdp.on("Page.navigatedWithinDocument", onSameDoc);
-      cleanup.push(() => cdp.off("Page.navigatedWithinDocument", onSameDoc));
-    }
-    const pollUrl = async () => {
-      while (!resolved && Date.now() < startTime + timeout) {
-        await sleep2(100);
-        if (resolved) return;
-        try {
-          const currentUrl = await getCurrentUrl(cdp);
-          if (startUrl && currentUrl !== startUrl) {
-            done(true);
-            return;
-          }
-        } catch {
-        }
-      }
-    };
-    pollUrl();
-  });
-}
-async function waitForNetworkIdle(cdp, options = {}) {
-  const { timeout = 3e4, idleTime = 500 } = options;
-  const startTime = Date.now();
-  await cdp.send("Network.enable");
-  return new Promise((resolve) => {
-    let inFlight = 0;
-    let idleTimer = null;
-    const timeoutTimer = setTimeout(() => {
-      cleanup();
-      resolve({ success: false, waitedMs: Date.now() - startTime });
-    }, timeout);
-    const checkIdle = () => {
-      if (inFlight === 0) {
-        if (idleTimer) clearTimeout(idleTimer);
-        idleTimer = setTimeout(() => {
-          cleanup();
-          resolve({ success: true, waitedMs: Date.now() - startTime });
-        }, idleTime);
-      }
-    };
-    const onRequestStart = () => {
-      inFlight++;
-      if (idleTimer) {
-        clearTimeout(idleTimer);
-        idleTimer = null;
-      }
-    };
-    const onRequestEnd = () => {
-      inFlight = Math.max(0, inFlight - 1);
-      checkIdle();
-    };
-    const cleanup = () => {
-      clearTimeout(timeoutTimer);
-      if (idleTimer) clearTimeout(idleTimer);
-      cdp.off("Network.requestWillBeSent", onRequestStart);
-      cdp.off("Network.loadingFinished", onRequestEnd);
-      cdp.off("Network.loadingFailed", onRequestEnd);
-    };
-    cdp.on("Network.requestWillBeSent", onRequestStart);
-    cdp.on("Network.loadingFinished", onRequestEnd);
-    cdp.on("Network.loadingFailed", onRequestEnd);
-    checkIdle();
-  });
-}
-
-// src/browser/fuzzy-match.ts
-function jaroWinkler(a, b) {
-  if (a.length === 0 && b.length === 0) return 0;
-  if (a.length === 0 || b.length === 0) return 0;
-  if (a === b) return 1;
-  const s1 = a.toLowerCase();
-  const s2 = b.toLowerCase();
-  const matchWindow = Math.max(0, Math.floor(Math.max(s1.length, s2.length) / 2) - 1);
-  const s1Matches = new Array(s1.length).fill(false);
-  const s2Matches = new Array(s2.length).fill(false);
-  let matches = 0;
-  let transpositions = 0;
-  for (let i = 0; i < s1.length; i++) {
-    const start = Math.max(0, i - matchWindow);
-    const end = Math.min(i + matchWindow + 1, s2.length);
-    for (let j = start; j < end; j++) {
-      if (s2Matches[j] || s1[i] !== s2[j]) continue;
-      s1Matches[i] = true;
-      s2Matches[j] = true;
-      matches++;
-      break;
-    }
-  }
-  if (matches === 0) return 0;
-  let k = 0;
-  for (let i = 0; i < s1.length; i++) {
-    if (!s1Matches[i]) continue;
-    while (!s2Matches[k]) k++;
-    if (s1[i] !== s2[k]) transpositions++;
-    k++;
-  }
-  const jaro = (matches / s1.length + matches / s2.length + (matches - transpositions / 2) / matches) / 3;
-  let prefix = 0;
-  for (let i = 0; i < Math.min(4, Math.min(s1.length, s2.length)); i++) {
-    if (s1[i] === s2[i]) {
-      prefix++;
-    } else {
-      break;
-    }
-  }
-  const WINKLER_SCALING = 0.1;
-  return jaro + prefix * WINKLER_SCALING * (1 - jaro);
-}
-function stringSimilarity(a, b) {
-  if (a.length === 0 || b.length === 0) return 0;
-  const lowerA = a.toLowerCase();
-  const lowerB = b.toLowerCase();
-  if (lowerA === lowerB) return 1;
-  const jw = jaroWinkler(a, b);
-  let containsBonus = 0;
-  if (lowerB.includes(lowerA)) {
-    containsBonus = 0.2;
-  } else if (lowerA.includes(lowerB)) {
-    containsBonus = 0.1;
-  }
-  return Math.min(1, jw + containsBonus);
-}
-function scoreElement(query, element) {
-  const lowerQuery = query.toLowerCase();
-  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
-  let nameScore = 0;
-  if (element.name) {
-    const lowerName = element.name.toLowerCase();
-    if (lowerName === lowerQuery) {
-      nameScore = 1;
-    } else if (lowerName.includes(lowerQuery)) {
-      nameScore = 0.8;
-    } else if (words.length > 0) {
-      const matchedWords = words.filter((w) => lowerName.includes(w));
-      nameScore = matchedWords.length / words.length * 0.7;
-    } else {
-      nameScore = stringSimilarity(query, element.name) * 0.6;
-    }
-  }
-  let roleScore = 0;
-  const lowerRole = element.role.toLowerCase();
-  if (lowerRole === lowerQuery || lowerQuery.includes(lowerRole)) {
-    roleScore = 0.3;
-  } else if (words.some((w) => lowerRole.includes(w))) {
-    roleScore = 0.2;
+    expression: `(() => {
+      ${DEEP_QUERY_SCRIPT}
+      return deepQuery(${JSON.stringify(selector)}) !== null;
+    })()`,
+    returnByValue: true
+  };
+  if (contextId !== void 0) {
+    params["contextId"] = contextId;
   }
-  let selectorScore = 0;
-  const lowerSelector = element.selector.toLowerCase();
-  if (words.some((w) => lowerSelector.includes(w))) {
-    selectorScore = 0.2;
+  const result = await cdp.send("Runtime.evaluate", params);
+  return result.result.value === true;
+}
+function sleep4(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function isPageStatic(cdp, windowMs = 200, contextId) {
+  const params = {
+    expression: `new Promise(resolve => {
+      // If page is still loading, it's not static
+      if (document.readyState !== 'complete') { resolve(false); return; }
+      // Check for recent page load (navigationStart within last 1s = page just loaded)
+      try {
+        var nav = performance.getEntriesByType('navigation')[0];
+        if (nav && (performance.now() - nav.loadEventEnd) < 500) { resolve(false); return; }
+      } catch(e) {}
+      // Observe for DOM mutations
+      var seen = false;
+      var obs = new MutationObserver(function() { seen = true; });
+      obs.observe(document.documentElement, { childList: true, subtree: true, attributes: true });
+      setTimeout(function() { obs.disconnect(); resolve(!seen); }, ${windowMs});
+    })`,
+    returnByValue: true,
+    awaitPromise: true
+  };
+  if (contextId !== void 0) params["contextId"] = contextId;
+  try {
+    const result = await cdp.send("Runtime.evaluate", params);
+    return result.result.value === true;
+  } catch {
+    return false;
   }
-  const totalScore = nameScore * 0.6 + roleScore * 0.25 + selectorScore * 0.15;
-  return totalScore;
 }
-function explainMatch(query, element, score) {
-  const reasons = [];
-  const lowerQuery = query.toLowerCase();
-  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
-  if (element.name) {
-    const lowerName = element.name.toLowerCase();
-    if (lowerName === lowerQuery) {
-      reasons.push("exact name match");
-    } else if (lowerName.includes(lowerQuery)) {
-      reasons.push("name contains query");
-    } else if (words.some((w) => lowerName.includes(w))) {
-      const matchedWords = words.filter((w) => lowerName.includes(w));
-      reasons.push(`name contains: ${matchedWords.join(", ")}`);
-    } else if (stringSimilarity(query, element.name) > 0.5) {
-      reasons.push("similar name");
+async function waitForElement(cdp, selector, options = {}) {
+  const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
+  const startTime = Date.now();
+  const deadline = startTime + timeout;
+  const checkCondition = async () => {
+    switch (state) {
+      case "visible":
+        return isElementVisible(cdp, selector, contextId);
+      case "hidden":
+        return !await isElementVisible(cdp, selector, contextId);
+      case "attached":
+        return isElementAttached(cdp, selector, contextId);
+      case "detached":
+        return !await isElementAttached(cdp, selector, contextId);
+      default: {
+        const _exhaustive = state;
+        throw new Error(`Unhandled wait state: ${_exhaustive}`);
+      }
     }
+  };
+  if (await checkCondition()) {
+    return { success: true, waitedMs: Date.now() - startTime };
   }
-  const lowerRole = element.role.toLowerCase();
-  if (lowerRole === lowerQuery || words.some((w) => w === lowerRole)) {
-    reasons.push(`role: ${element.role}`);
-  }
-  if (words.some((w) => element.selector.toLowerCase().includes(w))) {
-    reasons.push("selector match");
-  }
-  if (reasons.length === 0) {
-    reasons.push(`fuzzy match (score: ${score.toFixed(2)})`);
+  const waitingForPresence = state === "visible" || state === "attached";
+  if (waitingForPresence && timeout >= 300) {
+    const pageStatic = await isPageStatic(cdp, 200, contextId);
+    if (pageStatic) {
+      if (await checkCondition()) {
+        return { success: true, waitedMs: Date.now() - startTime };
+      }
+      return { success: false, waitedMs: Date.now() - startTime };
+    }
   }
-  return reasons.join(", ");
-}
-function fuzzyMatchElements(query, elements, maxResults = 5) {
-  if (!query || query.length === 0) {
-    return [];
+  while (Date.now() < deadline) {
+    await sleep4(pollInterval);
+    if (await checkCondition()) {
+      return { success: true, waitedMs: Date.now() - startTime };
+    }
   }
-  const THRESHOLD = 0.3;
-  const scored = elements.map((element) => ({
-    element,
-    score: scoreElement(query, element)
-  }));
-  return scored.filter((s) => s.score >= THRESHOLD).sort((a, b) => b.score - a.score).slice(0, maxResults).map((s) => ({
-    element: s.element,
-    score: s.score,
-    matchReason: explainMatch(query, s.element, s.score)
-  }));
+  return { success: false, waitedMs: Date.now() - startTime };
 }
-
-// src/browser/hint-generator.ts
-var ACTION_ROLE_MAP = {
-  click: ["button", "link", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "option"],
-  fill: ["textbox", "searchbox", "textarea"],
-  type: ["textbox", "searchbox", "textarea"],
-  submit: ["button", "form"],
-  select: ["combobox", "listbox", "option"],
-  check: ["checkbox", "radio", "switch"],
-  uncheck: ["checkbox", "switch"],
-  focus: [],
-  // Any focusable element
-  hover: [],
-  // Any element
-  clear: ["textbox", "searchbox", "textarea"]
-};
-function extractIntent(selectors) {
-  const patterns = [];
-  let text = "";
-  for (const selector of selectors) {
-    if (selector.startsWith("ref:")) {
-      continue;
-    }
-    const idMatch = selector.match(/#([a-zA-Z0-9_-]+)/);
-    if (idMatch) {
-      patterns.push(idMatch[1]);
+async function waitForAnyElement(cdp, selectors, options = {}) {
+  const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
+  const startTime = Date.now();
+  const deadline = startTime + timeout;
+  const checkSelector = async (selector) => {
+    switch (state) {
+      case "visible":
+        return isElementVisible(cdp, selector, contextId);
+      case "hidden":
+        return !await isElementVisible(cdp, selector, contextId);
+      case "attached":
+        return isElementAttached(cdp, selector, contextId);
+      case "detached":
+        return !await isElementAttached(cdp, selector, contextId);
+      default: {
+        const _exhaustive = state;
+        throw new Error(`Unhandled wait state: ${_exhaustive}`);
+      }
     }
-    const ariaMatch = selector.match(/\[aria-label=["']([^"']+)["']\]/);
-    if (ariaMatch) {
-      patterns.push(ariaMatch[1]);
+  };
+  for (const selector of selectors) {
+    if (await checkSelector(selector)) {
+      return { success: true, selector, waitedMs: Date.now() - startTime };
     }
-    const testidMatch = selector.match(/\[data-testid=["']([^"']+)["']\]/);
-    if (testidMatch) {
-      patterns.push(testidMatch[1]);
+  }
+  const waitingForPresence = state === "visible" || state === "attached";
+  if (waitingForPresence && timeout >= 300) {
+    const pageStatic = await isPageStatic(cdp, 200, contextId);
+    if (pageStatic) {
+      for (const selector of selectors) {
+        if (await checkSelector(selector)) {
+          return { success: true, selector, waitedMs: Date.now() - startTime };
+        }
+      }
+      return { success: false, waitedMs: Date.now() - startTime };
     }
-    const classMatch = selector.match(/\.([a-zA-Z0-9_-]+)/);
-    if (classMatch) {
-      patterns.push(classMatch[1]);
+  }
+  while (Date.now() < deadline) {
+    await sleep4(pollInterval);
+    for (const selector of selectors) {
+      if (await checkSelector(selector)) {
+        return { success: true, selector, waitedMs: Date.now() - startTime };
+      }
     }
   }
-  patterns.sort((a, b) => b.length - a.length);
-  text = patterns[0] ?? selectors[0] ?? "";
-  return { text, patterns };
-}
-function getHintType(selector) {
-  if (selector.startsWith("ref:")) return "ref";
-  if (selector.includes("data-testid")) return "testid";
-  if (selector.includes("aria-label")) return "aria";
-  if (selector.startsWith("#")) return "id";
-  return "css";
+  return { success: false, waitedMs: Date.now() - startTime };
 }
-function getConfidence(score) {
-  if (score >= 0.8) return "high";
-  if (score >= 0.5) return "medium";
-  return "low";
+async function getCurrentUrl(cdp) {
+  const result = await cdp.send("Runtime.evaluate", {
+    expression: "location.href",
+    returnByValue: true
+  });
+  return result.result.value;
 }
-function diversifyHints(candidates, maxHints) {
-  const hints = [];
-  const usedTypes = /* @__PURE__ */ new Set();
-  for (const candidate of candidates) {
-    if (hints.length >= maxHints) break;
-    const refSelector = `ref:${candidate.element.ref}`;
-    const hintType = getHintType(refSelector);
-    if (!usedTypes.has(hintType)) {
-      hints.push({
-        selector: refSelector,
-        reason: candidate.matchReason,
-        confidence: getConfidence(candidate.score),
-        element: {
-          ref: candidate.element.ref,
-          role: candidate.element.role,
-          name: candidate.element.name,
-          disabled: candidate.element.disabled
-        }
-      });
-      usedTypes.add(hintType);
-    } else if (hints.length < maxHints) {
-      hints.push({
-        selector: refSelector,
-        reason: candidate.matchReason,
-        confidence: getConfidence(candidate.score),
-        element: {
-          ref: candidate.element.ref,
-          role: candidate.element.role,
-          name: candidate.element.name,
-          disabled: candidate.element.disabled
-        }
-      });
-    }
+async function waitForNavigation(cdp, options = {}) {
+  const { timeout = 3e4, allowSameDocument = true } = options;
+  const startTime = Date.now();
+  let startUrl;
+  try {
+    startUrl = await getCurrentUrl(cdp);
+  } catch {
+    startUrl = "";
   }
-  return hints;
+  return new Promise((resolve) => {
+    let resolved = false;
+    const cleanup = [];
+    const done = (success) => {
+      if (resolved) return;
+      resolved = true;
+      for (const fn of cleanup) fn();
+      resolve({ success, waitedMs: Date.now() - startTime });
+    };
+    const timer = setTimeout(() => done(false), timeout);
+    cleanup.push(() => clearTimeout(timer));
+    const onLoad = () => done(true);
+    cdp.on("Page.loadEventFired", onLoad);
+    cleanup.push(() => cdp.off("Page.loadEventFired", onLoad));
+    const onFrameNavigated = (params) => {
+      const frame = params["frame"];
+      if (frame && !frame.parentId && frame.url !== startUrl) {
+        done(true);
+      }
+    };
+    cdp.on("Page.frameNavigated", onFrameNavigated);
+    cleanup.push(() => cdp.off("Page.frameNavigated", onFrameNavigated));
+    if (allowSameDocument) {
+      const onSameDoc = () => done(true);
+      cdp.on("Page.navigatedWithinDocument", onSameDoc);
+      cleanup.push(() => cdp.off("Page.navigatedWithinDocument", onSameDoc));
+    }
+    const onLifecycle = (params) => {
+      if (params["name"] === "networkIdle") {
+        done(true);
+      }
+    };
+    cdp.on("Page.lifecycleEvent", onLifecycle);
+    cleanup.push(() => cdp.off("Page.lifecycleEvent", onLifecycle));
+    const pollUrl = async () => {
+      while (!resolved && Date.now() < startTime + timeout) {
+        await sleep4(100);
+        if (resolved) return;
+        try {
+          const currentUrl = await getCurrentUrl(cdp);
+          if (startUrl && currentUrl !== startUrl) {
+            done(true);
+            return;
+          }
+        } catch {
+        }
+      }
+    };
+    void pollUrl();
+  });
+}
+async function waitForNetworkIdle(cdp, options = {}) {
+  const { timeout = 3e4, idleTime = 500 } = options;
+  const startTime = Date.now();
+  await cdp.send("Network.enable");
+  return new Promise((resolve) => {
+    let inFlight = 0;
+    let idleTimer = null;
+    const timeoutTimer = setTimeout(() => {
+      cleanup();
+      resolve({ success: false, waitedMs: Date.now() - startTime });
+    }, timeout);
+    const checkIdle = () => {
+      if (inFlight === 0) {
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+          cleanup();
+          resolve({ success: true, waitedMs: Date.now() - startTime });
+        }, idleTime);
+      }
+    };
+    const onRequestStart = () => {
+      inFlight++;
+      if (idleTimer) {
+        clearTimeout(idleTimer);
+        idleTimer = null;
+      }
+    };
+    const onRequestEnd = () => {
+      inFlight = Math.max(0, inFlight - 1);
+      checkIdle();
+    };
+    const cleanup = () => {
+      clearTimeout(timeoutTimer);
+      if (idleTimer) clearTimeout(idleTimer);
+      cdp.off("Network.requestWillBeSent", onRequestStart);
+      cdp.off("Network.loadingFinished", onRequestEnd);
+      cdp.off("Network.loadingFailed", onRequestEnd);
+    };
+    cdp.on("Network.requestWillBeSent", onRequestStart);
+    cdp.on("Network.loadingFinished", onRequestEnd);
+    cdp.on("Network.loadingFailed", onRequestEnd);
+    checkIdle();
+  });
 }
-async function generateHints(page, failedSelectors, actionType, maxHints = 3) {
-  let snapshot;
-  try {
-    snapshot = await page.snapshot();
-  } catch {
-    return [];
-  }
-  const intent = extractIntent(failedSelectors);
-  const roleFilter = ACTION_ROLE_MAP[actionType] ?? [];
-  let candidates = snapshot.interactiveElements;
-  if (roleFilter.length > 0) {
-    candidates = candidates.filter((el) => roleFilter.includes(el.role));
+
+// src/browser/keyboard.ts
+var US_KEYBOARD = {
+  // Letters (lowercase)
+  a: { key: "a", code: "KeyA", keyCode: 65, text: "a" },
+  b: { key: "b", code: "KeyB", keyCode: 66, text: "b" },
+  c: { key: "c", code: "KeyC", keyCode: 67, text: "c" },
+  d: { key: "d", code: "KeyD", keyCode: 68, text: "d" },
+  e: { key: "e", code: "KeyE", keyCode: 69, text: "e" },
+  f: { key: "f", code: "KeyF", keyCode: 70, text: "f" },
+  g: { key: "g", code: "KeyG", keyCode: 71, text: "g" },
+  h: { key: "h", code: "KeyH", keyCode: 72, text: "h" },
+  i: { key: "i", code: "KeyI", keyCode: 73, text: "i" },
+  j: { key: "j", code: "KeyJ", keyCode: 74, text: "j" },
+  k: { key: "k", code: "KeyK", keyCode: 75, text: "k" },
+  l: { key: "l", code: "KeyL", keyCode: 76, text: "l" },
+  m: { key: "m", code: "KeyM", keyCode: 77, text: "m" },
+  n: { key: "n", code: "KeyN", keyCode: 78, text: "n" },
+  o: { key: "o", code: "KeyO", keyCode: 79, text: "o" },
+  p: { key: "p", code: "KeyP", keyCode: 80, text: "p" },
+  q: { key: "q", code: "KeyQ", keyCode: 81, text: "q" },
+  r: { key: "r", code: "KeyR", keyCode: 82, text: "r" },
+  s: { key: "s", code: "KeyS", keyCode: 83, text: "s" },
+  t: { key: "t", code: "KeyT", keyCode: 84, text: "t" },
+  u: { key: "u", code: "KeyU", keyCode: 85, text: "u" },
+  v: { key: "v", code: "KeyV", keyCode: 86, text: "v" },
+  w: { key: "w", code: "KeyW", keyCode: 87, text: "w" },
+  x: { key: "x", code: "KeyX", keyCode: 88, text: "x" },
+  y: { key: "y", code: "KeyY", keyCode: 89, text: "y" },
+  z: { key: "z", code: "KeyZ", keyCode: 90, text: "z" },
+  // Letters (uppercase)
+  A: { key: "A", code: "KeyA", keyCode: 65, text: "A" },
+  B: { key: "B", code: "KeyB", keyCode: 66, text: "B" },
+  C: { key: "C", code: "KeyC", keyCode: 67, text: "C" },
+  D: { key: "D", code: "KeyD", keyCode: 68, text: "D" },
+  E: { key: "E", code: "KeyE", keyCode: 69, text: "E" },
+  F: { key: "F", code: "KeyF", keyCode: 70, text: "F" },
+  G: { key: "G", code: "KeyG", keyCode: 71, text: "G" },
+  H: { key: "H", code: "KeyH", keyCode: 72, text: "H" },
+  I: { key: "I", code: "KeyI", keyCode: 73, text: "I" },
+  J: { key: "J", code: "KeyJ", keyCode: 74, text: "J" },
+  K: { key: "K", code: "KeyK", keyCode: 75, text: "K" },
+  L: { key: "L", code: "KeyL", keyCode: 76, text: "L" },
+  M: { key: "M", code: "KeyM", keyCode: 77, text: "M" },
+  N: { key: "N", code: "KeyN", keyCode: 78, text: "N" },
+  O: { key: "O", code: "KeyO", keyCode: 79, text: "O" },
+  P: { key: "P", code: "KeyP", keyCode: 80, text: "P" },
+  Q: { key: "Q", code: "KeyQ", keyCode: 81, text: "Q" },
+  R: { key: "R", code: "KeyR", keyCode: 82, text: "R" },
+  S: { key: "S", code: "KeyS", keyCode: 83, text: "S" },
+  T: { key: "T", code: "KeyT", keyCode: 84, text: "T" },
+  U: { key: "U", code: "KeyU", keyCode: 85, text: "U" },
+  V: { key: "V", code: "KeyV", keyCode: 86, text: "V" },
+  W: { key: "W", code: "KeyW", keyCode: 87, text: "W" },
+  X: { key: "X", code: "KeyX", keyCode: 88, text: "X" },
+  Y: { key: "Y", code: "KeyY", keyCode: 89, text: "Y" },
+  Z: { key: "Z", code: "KeyZ", keyCode: 90, text: "Z" },
+  // Numbers
+  "0": { key: "0", code: "Digit0", keyCode: 48, text: "0" },
+  "1": { key: "1", code: "Digit1", keyCode: 49, text: "1" },
+  "2": { key: "2", code: "Digit2", keyCode: 50, text: "2" },
+  "3": { key: "3", code: "Digit3", keyCode: 51, text: "3" },
+  "4": { key: "4", code: "Digit4", keyCode: 52, text: "4" },
+  "5": { key: "5", code: "Digit5", keyCode: 53, text: "5" },
+  "6": { key: "6", code: "Digit6", keyCode: 54, text: "6" },
+  "7": { key: "7", code: "Digit7", keyCode: 55, text: "7" },
+  "8": { key: "8", code: "Digit8", keyCode: 56, text: "8" },
+  "9": { key: "9", code: "Digit9", keyCode: 57, text: "9" },
+  // Punctuation
+  " ": { key: " ", code: "Space", keyCode: 32, text: " " },
+  ".": { key: ".", code: "Period", keyCode: 190, text: "." },
+  ",": { key: ",", code: "Comma", keyCode: 188, text: "," },
+  "/": { key: "/", code: "Slash", keyCode: 191, text: "/" },
+  ";": { key: ";", code: "Semicolon", keyCode: 186, text: ";" },
+  "'": { key: "'", code: "Quote", keyCode: 222, text: "'" },
+  "[": { key: "[", code: "BracketLeft", keyCode: 219, text: "[" },
+  "]": { key: "]", code: "BracketRight", keyCode: 221, text: "]" },
+  "\\": { key: "\\", code: "Backslash", keyCode: 220, text: "\\" },
+  "-": { key: "-", code: "Minus", keyCode: 189, text: "-" },
+  "=": { key: "=", code: "Equal", keyCode: 187, text: "=" },
+  "`": { key: "`", code: "Backquote", keyCode: 192, text: "`" },
+  // Shifted punctuation
+  "!": { key: "!", code: "Digit1", keyCode: 49, text: "!" },
+  "@": { key: "@", code: "Digit2", keyCode: 50, text: "@" },
+  "#": { key: "#", code: "Digit3", keyCode: 51, text: "#" },
+  $: { key: "$", code: "Digit4", keyCode: 52, text: "$" },
+  "%": { key: "%", code: "Digit5", keyCode: 53, text: "%" },
+  "^": { key: "^", code: "Digit6", keyCode: 54, text: "^" },
+  "&": { key: "&", code: "Digit7", keyCode: 55, text: "&" },
+  "*": { key: "*", code: "Digit8", keyCode: 56, text: "*" },
+  "(": { key: "(", code: "Digit9", keyCode: 57, text: "(" },
+  ")": { key: ")", code: "Digit0", keyCode: 48, text: ")" },
+  _: { key: "_", code: "Minus", keyCode: 189, text: "_" },
+  "+": { key: "+", code: "Equal", keyCode: 187, text: "+" },
+  "{": { key: "{", code: "BracketLeft", keyCode: 219, text: "{" },
+  "}": { key: "}", code: "BracketRight", keyCode: 221, text: "}" },
+  "|": { key: "|", code: "Backslash", keyCode: 220, text: "|" },
+  ":": { key: ":", code: "Semicolon", keyCode: 186, text: ":" },
+  '"': { key: '"', code: "Quote", keyCode: 222, text: '"' },
+  "<": { key: "<", code: "Comma", keyCode: 188, text: "<" },
+  ">": { key: ">", code: "Period", keyCode: 190, text: ">" },
+  "?": { key: "?", code: "Slash", keyCode: 191, text: "?" },
+  "~": { key: "~", code: "Backquote", keyCode: 192, text: "~" },
+  // Special keys (non-text: use rawKeyDown, no text field)
+  Enter: { key: "Enter", code: "Enter", keyCode: 13 },
+  Tab: { key: "Tab", code: "Tab", keyCode: 9 },
+  Backspace: { key: "Backspace", code: "Backspace", keyCode: 8 },
+  Delete: { key: "Delete", code: "Delete", keyCode: 46 },
+  Escape: { key: "Escape", code: "Escape", keyCode: 27 },
+  ArrowUp: { key: "ArrowUp", code: "ArrowUp", keyCode: 38 },
+  ArrowDown: { key: "ArrowDown", code: "ArrowDown", keyCode: 40 },
+  ArrowLeft: { key: "ArrowLeft", code: "ArrowLeft", keyCode: 37 },
+  ArrowRight: { key: "ArrowRight", code: "ArrowRight", keyCode: 39 },
+  Home: { key: "Home", code: "Home", keyCode: 36 },
+  End: { key: "End", code: "End", keyCode: 35 },
+  PageUp: { key: "PageUp", code: "PageUp", keyCode: 33 },
+  PageDown: { key: "PageDown", code: "PageDown", keyCode: 34 }
+};
+var MODIFIER_CODES = {
+  Control: "ControlLeft",
+  Shift: "ShiftLeft",
+  Alt: "AltLeft",
+  Meta: "MetaLeft"
+};
+var MODIFIER_KEY_CODES = {
+  Control: 17,
+  Shift: 16,
+  Alt: 18,
+  Meta: 91
+};
+function computeModifierBitmask(modifiers) {
+  let mask = 0;
+  if (modifiers.includes("Alt")) mask |= 1;
+  if (modifiers.includes("Control")) mask |= 2;
+  if (modifiers.includes("Meta")) mask |= 4;
+  if (modifiers.includes("Shift")) mask |= 8;
+  return mask;
+}
+function parseShortcut(combo) {
+  const parts = combo.split("+");
+  if (parts.length < 2) {
+    throw new Error(
+      `Invalid shortcut "${combo}": must contain at least one modifier and a key (e.g. "Control+a").`
+    );
   }
-  const matches = fuzzyMatchElements(intent.text, candidates, maxHints * 2);
-  if (matches.length === 0) {
-    return [];
+  const key = parts[parts.length - 1];
+  const modifiers = [];
+  const validModifiers = new Set(Object.keys(MODIFIER_CODES));
+  for (let i = 0; i < parts.length - 1; i++) {
+    const mod = parts[i];
+    if (!validModifiers.has(mod)) {
+      throw new Error(
+        `Invalid modifier "${mod}" in shortcut "${combo}". Valid modifiers: ${[...validModifiers].join(", ")}`
+      );
+    }
+    modifiers.push(mod);
   }
-  return diversifyHints(matches, maxHints);
+  return { modifiers, key };
 }
 
 // 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;
@@ -3339,8 +4326,12 @@ var Page = class {
   frameExecutionContexts = /* @__PURE__ */ new Map();
   /** Current frame's execution context ID (null = main frame default) */
   currentFrameContextId = null;
+  /** Frame selector if context acquisition failed (cross-origin/sandboxed) */
+  brokenFrame = null;
   /** Last matched selector from findElement (for selectorUsed tracking) */
   _lastMatchedSelector;
+  /** Last snapshot for stale ref recovery */
+  lastSnapshot;
   /** Audio input controller (lazy-initialized) */
   _audioInput;
   /** Audio output controller (lazy-initialized) */
@@ -3385,17 +4376,34 @@ var Page = class {
       for (const [frameId, ctxId] of this.frameExecutionContexts.entries()) {
         if (ctxId === contextId) {
           this.frameExecutionContexts.delete(frameId);
+          if (this.currentFrameContextId === contextId) {
+            this.currentFrameContextId = null;
+          }
           break;
         }
       }
     });
-    this.cdp.on("Page.javascriptDialogOpening", this.handleDialogOpening.bind(this));
+    this.cdp.on("Page.javascriptDialogOpening", (params) => {
+      void this.handleDialogOpening(params);
+    });
     await Promise.all([
       this.cdp.send("Page.enable"),
       this.cdp.send("DOM.enable"),
       this.cdp.send("Runtime.enable"),
       this.cdp.send("Network.enable")
     ]);
+    await this.installEventListenerTracker();
+  }
+  async installEventListenerTracker() {
+    await this.cdp.send("Page.addScriptToEvaluateOnNewDocument", {
+      source: EVENT_LISTENER_TRACKER_SCRIPT
+    });
+    try {
+      await this.cdp.send("Runtime.evaluate", {
+        expression: EVENT_LISTENER_TRACKER_SCRIPT
+      });
+    } catch {
+    }
   }
   // ============ Navigation ============
   /**
@@ -3411,6 +4419,9 @@ var Page = class {
     }
     this.rootNodeId = null;
     this.refMap.clear();
+    this.currentFrame = null;
+    this.currentFrameContextId = null;
+    this.frameContexts.clear();
   }
   /**
    * Get the current URL
@@ -3481,8 +4492,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 () => {
@@ -3494,27 +4506,55 @@ var Page = class {
         throw new ElementNotFoundError(selector, hints);
       }
       await this.scrollIntoView(element.nodeId);
-      const submitResult = await this.evaluateInFrame(
-        `(() => {
-          const el = document.querySelector(${JSON.stringify(element.selector)});
-          if (!el) return { isSubmit: false };
-
-          // Check if this is a form submit button
-          const isSubmitButton = (el instanceof HTMLButtonElement && (el.type === 'submit' || (el.form && el.type !== 'button'))) ||
-                                 (el instanceof HTMLInputElement && el.type === 'submit');
-
-          if (isSubmitButton && el.form) {
-            // Dispatch submit event directly - works reliably in headless Chrome
-            el.form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
-            return { isSubmit: true };
+      const objectId = await this.resolveObjectId(element.nodeId);
+      try {
+        await ensureActionable(this.cdp, objectId, ["visible", "enabled", "stable"], {
+          timeout: options.timeout ?? DEFAULT_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 };
+      const HIT_TARGET_RETRIES = 3;
+      const HIT_TARGET_DELAY = 100;
+      for (let attempt = 0; attempt < HIT_TARGET_RETRIES; attempt++) {
+        try {
+          await ensureActionable(this.cdp, objectId, ["hitTarget"], {
+            timeout: options.timeout ?? DEFAULT_TIMEOUT2,
+            coordinates: hitTargetCoordinates
+          });
+          break;
+        } catch (e) {
+          if (options.optional) return false;
+          if (e instanceof ActionabilityError && e.failureType === "hitTarget" && attempt < HIT_TARGET_RETRIES - 1) {
+            await sleep5(HIT_TARGET_DELAY);
+            await this.cdp.send("DOM.scrollIntoViewIfNeeded", { nodeId: element.nodeId });
+            continue;
           }
-          return { isSubmit: false };
-        })()`
-      );
-      const isSubmit = submitResult.result.value?.isSubmit;
-      if (!isSubmit) {
-        await this.clickElement(element.nodeId);
+          throw e;
+        }
       }
+      await this.clickElement(element.nodeId);
       return true;
     });
   }
@@ -3522,7 +4562,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) {
@@ -3531,71 +4571,158 @@ var Page = class {
         const hints = await generateHints(this, selectorList, "fill");
         throw new ElementNotFoundError(selector, hints);
       }
-      await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
-      if (clear) {
-        await this.evaluateInFrame(
-          `(() => {
-            const el = document.querySelector(${JSON.stringify(element.selector)});
-            if (el) {
-              el.value = '';
-              el.dispatchEvent(new InputEvent('input', {
-                bubbles: true,
-                cancelable: true,
-                inputType: 'deleteContent'
-              }));
-            }
-          })()`
-        );
+      const { object } = await this.cdp.send("DOM.resolveNode", {
+        nodeId: element.nodeId
+      });
+      const objectId = object.objectId;
+      try {
+        await ensureActionable(this.cdp, objectId, ["visible", "enabled", "editable"], {
+          timeout: options.timeout ?? DEFAULT_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;
+      const objectId = await this.resolveObjectId(element.nodeId);
+      try {
+        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);
+        }
+      }
+      if (options.blur) {
+        await this.cdp.send("Runtime.callFunctionOn", {
+          objectId,
+          functionDeclaration: "function() { this.blur(); }"
+        });
+      }
+      return true;
+    });
   }
   async select(selectorOrConfig, valueOrOptions, maybeOptions) {
     if (typeof selectorOrConfig === "object" && !Array.isArray(selectorOrConfig) && "trigger" in selectorOrConfig) {
@@ -3604,108 +4731,231 @@ var Page = class {
     const selector = selectorOrConfig;
     const value = valueOrOptions;
     const options = maybeOptions ?? {};
-    const element = await this.findElement(selector, options);
-    if (!element) {
-      if (options.optional) return false;
-      const selectorList = Array.isArray(selector) ? selector : [selector];
-      const hints = await generateHints(this, selectorList, "select");
-      throw new ElementNotFoundError(selector, hints);
-    }
-    const values = Array.isArray(value) ? value : [value];
-    await this.cdp.send("Runtime.evaluate", {
-      expression: `(() => {
-        const el = document.querySelector(${JSON.stringify(element.selector)});
-        if (!el || el.tagName !== 'SELECT') return false;
-        const values = ${JSON.stringify(values)};
-        for (const opt of el.options) {
-          opt.selected = values.includes(opt.value) || values.includes(opt.text);
-        }
-        el.dispatchEvent(new Event('change', { bubbles: true }));
+    return this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "select");
+        throw new ElementNotFoundError(selector, hints);
+      }
+      const values = Array.isArray(value) ? value : [value];
+      const objectId = await this.resolveObjectId(element.nodeId);
+      try {
+        await this.scrollIntoView(element.nodeId);
+        await ensureActionable(this.cdp, objectId, ["visible", "enabled"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT2
+        });
+      } catch (e) {
+        if (options.optional) return false;
+        throw e;
+      }
+      const metadata = await this.getNativeSelectMetadata(objectId, values);
+      if (!metadata.isSelect) {
+        throw new Error("select() target must be a native <select> element");
+      }
+      if (metadata.missing.length > 0) {
+        throw new Error(`No option found for: ${metadata.missing.join(", ")}`);
+      }
+      if (metadata.disabled.length > 0) {
+        throw new Error(`Cannot select disabled option(s): ${metadata.disabled.join(", ")}`);
+      }
+      if (!metadata.multiple && metadata.targetIndexes.length > 1) {
+        throw new Error("Cannot select multiple values on a single-select element");
+      }
+      const expectedValues = metadata.targetIndexes.map((idx) => metadata.options[idx].value);
+      if (this.selectValuesMatch(metadata.selectedValues, expectedValues, metadata.multiple)) {
         return true;
-      })()`,
-      returnByValue: true
+      }
+      if (!metadata.multiple && metadata.targetIndexes.length === 1) {
+        await this.applyNativeSelectByKeyboard(
+          element.nodeId,
+          objectId,
+          metadata.currentIndex,
+          metadata.targetIndexes[0]
+        );
+      }
+      let selectedValues = await this.readNativeSelectValues(objectId);
+      if (!this.selectValuesMatch(selectedValues, expectedValues, metadata.multiple)) {
+        await this.applyNativeSelectFallback(objectId, metadata.targetIndexes);
+        selectedValues = await this.readNativeSelectValues(objectId);
+      }
+      if (!this.selectValuesMatch(selectedValues, expectedValues, metadata.multiple)) {
+        await this.applyRecordedSelectFallback(objectId, metadata.targetIndexes);
+        selectedValues = await this.readNativeSelectValues(objectId);
+      }
+      if (!this.selectValuesMatch(selectedValues, expectedValues, metadata.multiple)) {
+        if (options.optional) return false;
+        throw new Error(
+          `Select value did not stick. Expected ${expectedValues.join(", ") || "(empty)"} but got ${selectedValues.join(", ") || "(empty)"}.`
+        );
+      }
+      return true;
     });
-    return true;
   }
   /**
    * Handle custom (non-native) select/dropdown components
    */
   async selectCustom(config, options = {}) {
     const { trigger, option, value, match = "text" } = config;
-    await this.click(trigger, options);
-    await sleep3(100);
-    let optionSelector;
-    const optionSelectors = Array.isArray(option) ? option : [option];
-    if (match === "contains") {
-      optionSelector = optionSelectors.map((s) => `${s}:has-text("${value}")`).join(", ");
-    } else if (match === "value") {
-      optionSelector = optionSelectors.map((s) => `${s}[data-value="${value}"], ${s}[value="${value}"]`).join(", ");
-    } else {
-      optionSelector = optionSelectors.map((s) => `${s}`).join(", ");
-    }
-    const result = await this.cdp.send("Runtime.evaluate", {
-      expression: `(() => {
-        const options = document.querySelectorAll(${JSON.stringify(optionSelector)});
-        for (const opt of options) {
-          const text = opt.textContent?.trim();
-          if (${match === "text" ? `text === ${JSON.stringify(value)}` : match === "contains" ? `text?.includes(${JSON.stringify(value)})` : "true"}) {
-            opt.click();
-            return true;
+    return this.withStaleNodeRetry(async () => {
+      await this.click(trigger, options);
+      const optionSelectors = Array.isArray(option) ? option : [option];
+      await waitForAnyElement(this.cdp, optionSelectors, {
+        state: "visible",
+        timeout: 500,
+        contextId: this.currentFrameContextId ?? void 0
+      }).catch(() => sleep5(100));
+      const optionHandle = await this.evaluateInFrame(
+        `(() => {
+          const selectors = ${JSON.stringify(optionSelectors)};
+          const wanted = ${JSON.stringify(value)};
+          const mode = ${JSON.stringify(match)};
+
+          for (const selector of selectors) {
+            const candidates = document.querySelectorAll(selector);
+            for (const candidate of candidates) {
+              const text = candidate.textContent?.trim() || '';
+              const candidateValue =
+                candidate.getAttribute?.('data-value') ??
+                candidate.getAttribute?.('value') ??
+                candidate.value ??
+                '';
+              const matches =
+                mode === 'value'
+                  ? candidateValue === wanted
+                  : mode === 'contains'
+                    ? text.includes(wanted)
+                    : text === wanted;
+
+              if (matches) {
+                return candidate;
+              }
+            }
           }
+
+          return null;
+        })()`,
+        { returnByValue: false }
+      );
+      if (!optionHandle.result.objectId) {
+        if (options.optional) return false;
+        throw new ElementNotFoundError(`Option with ${match} "${value}"`);
+      }
+      const nodeResult = await this.cdp.send("DOM.requestNode", {
+        objectId: optionHandle.result.objectId
+      });
+      if (!nodeResult.nodeId) {
+        if (options.optional) return false;
+        throw new ElementNotFoundError(`Option with ${match} "${value}"`);
+      }
+      await this.scrollIntoView(nodeResult.nodeId);
+      await ensureActionable(
+        this.cdp,
+        optionHandle.result.objectId,
+        ["visible", "enabled", "stable"],
+        {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT2
         }
-        return false;
-      })()`,
-      returnByValue: true
-    });
-    if (!result.result.value) {
-      if (options.optional) return false;
-      throw new ElementNotFoundError(`Option with ${match} "${value}"`);
-    }
-    return true;
-  }
-  /**
-   * Check a checkbox or radio button
-   */
-  async check(selector, options = {}) {
-    const element = await this.findElement(selector, options);
-    if (!element) {
-      if (options.optional) return false;
-      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
+      );
+      await this.clickElement(nodeResult.nodeId);
+      return true;
+    });
+  }
+  /**
+   * Check a checkbox or radio button using real mouse click.
+   * No-op if already checked. Verifies state changed after click.
+   */
+  async check(selector, 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, "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)
@@ -3719,97 +4969,100 @@ var Page = class {
    * the submit event and triggers HTML5 validation.
    */
   async submit(selector, options = {}) {
-    const { method = "enter+click", waitForNavigation: shouldWait = "auto" } = options;
-    const element = await this.findElement(selector, options);
-    if (!element) {
-      if (options.optional) return false;
-      const selectorList = Array.isArray(selector) ? selector : [selector];
-      const hints = await generateHints(this, selectorList, "submit");
-      throw new ElementNotFoundError(selector, hints);
-    }
-    const isFormElement = await this.evaluateInFrame(
-      `(() => {
-        const el = document.querySelector(${JSON.stringify(element.selector)});
-        return el instanceof HTMLFormElement;
-      })()`
-    );
-    if (isFormElement.result.value) {
-      await this.evaluateInFrame(
-        `(() => {
-          const form = document.querySelector(${JSON.stringify(element.selector)});
-          if (form && form instanceof HTMLFormElement) {
-            form.requestSubmit();
-          }
-        })()`
-      );
-      if (shouldWait === true) {
-        await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_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: 2e3, optional: true }).then(
+              () => "navigation"
+            ),
+            this.waitForDOMMutation({ timeout: 1e3 }).then(() => "mutation"),
+            sleep5(1500).then(() => "timeout")
+          ]);
         }
-      } else if (shouldWait === "auto") {
-        const navigationDetected = await Promise.race([
-          this.waitForNavigation({ timeout: 1e3, optional: true }).then(
-            (success) => success ? "nav" : null
-          ),
-          sleep3(500).then(() => "timeout")
-        ]);
-        if (navigationDetected === "nav") {
+        return true;
+      }
+      await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
+      if (method.includes("enter")) {
+        await this.press("Enter");
+        if (shouldWait === true) {
+          try {
+            await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_TIMEOUT2 });
+            return true;
+          } catch {
+          }
+        } else if (shouldWait === "auto") {
+          const navigationDetected = await Promise.race([
+            this.waitForNavigation({ timeout: 2e3, optional: true }).then(
+              (success) => success ? "nav" : null
+            ),
+            this.waitForDOMMutation({ timeout: 1e3 }).then(() => "mutation"),
+            sleep5(1500).then(() => "timeout")
+          ]);
+          if (navigationDetected === "nav") {
+            return true;
+          }
+        } else if (method === "enter") {
           return true;
         }
-      } else {
-        if (method === "enter") return true;
       }
-    }
-    if (method.includes("click")) {
-      await this.click(element.selector, { ...options, optional: false });
-      if (shouldWait === true) {
-        await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_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;
+    });
+  }
+  /**
+   * Press a key, optionally with modifier keys held down
+   */
+  async press(key, options) {
+    const modifiers = options?.modifiers;
+    if (modifiers && modifiers.length > 0) {
+      await this.dispatchKeyWithModifiers(key, modifiers);
+    } else {
+      await this.dispatchKey(key);
     }
-    return true;
   }
   /**
-   * Press a key
+   * Execute a keyboard shortcut (e.g. "Control+a", "Meta+Shift+z")
    */
-  async press(key) {
-    const keyMap = {
-      Enter: { key: "Enter", code: "Enter", keyCode: 13 },
-      Tab: { key: "Tab", code: "Tab", keyCode: 9 },
-      Escape: { key: "Escape", code: "Escape", keyCode: 27 },
-      Backspace: { key: "Backspace", code: "Backspace", keyCode: 8 },
-      Delete: { key: "Delete", code: "Delete", keyCode: 46 },
-      ArrowUp: { key: "ArrowUp", code: "ArrowUp", keyCode: 38 },
-      ArrowDown: { key: "ArrowDown", code: "ArrowDown", keyCode: 40 },
-      ArrowLeft: { key: "ArrowLeft", code: "ArrowLeft", keyCode: 37 },
-      ArrowRight: { key: "ArrowRight", code: "ArrowRight", keyCode: 39 }
-    };
-    const keyInfo = keyMap[key] ?? { key, code: key, keyCode: 0 };
-    await this.cdp.send("Input.dispatchKeyEvent", {
-      type: "keyDown",
-      key: keyInfo.key,
-      code: keyInfo.code,
-      windowsVirtualKeyCode: keyInfo.keyCode
-    });
-    await this.cdp.send("Input.dispatchKeyEvent", {
-      type: "keyUp",
-      key: keyInfo.key,
-      code: keyInfo.code,
-      windowsVirtualKeyCode: keyInfo.keyCode
-    });
+  async shortcut(combo) {
+    const { modifiers, key } = parseShortcut(combo);
+    await this.dispatchKeyWithModifiers(key, modifiers);
   }
   /**
    * Focus an element
@@ -3838,13 +5091,37 @@ var Page = class {
         throw new ElementNotFoundError(selector, hints);
       }
       await this.scrollIntoView(element.nodeId);
-      const box = await this.getBoxModel(element.nodeId);
-      if (!box) {
+      const objectId = await this.resolveObjectId(element.nodeId);
+      try {
+        await ensureActionable(this.cdp, objectId, ["visible", "stable"], {
+          timeout: options.timeout ?? DEFAULT_TIMEOUT2
+        });
+      } catch (e) {
         if (options.optional) return false;
-        throw new Error("Could not get element box model");
+        throw e;
+      }
+      let x;
+      let y;
+      try {
+        const { quads } = await this.cdp.send("DOM.getContentQuads", {
+          objectId
+        });
+        if (quads?.length > 0) {
+          const quad = quads[0];
+          x = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
+          y = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+        } else {
+          throw new Error("No quads");
+        }
+      } catch {
+        const box = await this.getBoxModel(element.nodeId);
+        if (!box) {
+          if (options.optional) return false;
+          throw new Error("Could not get element position");
+        }
+        x = box.content[0] + box.width / 2;
+        y = box.content[1] + box.height / 2;
       }
-      const x = box.content[0] + box.width / 2;
-      const y = box.content[1] + box.height / 2;
       await this.cdp.send("Input.dispatchMouseEvent", {
         type: "mouseMoved",
         x,
@@ -3902,15 +5179,19 @@ var Page = class {
     if (descResult.node.frameId) {
       const frameId = descResult.node.frameId;
       const { timeout = DEFAULT_TIMEOUT2 } = options;
-      const pollInterval = 50;
-      const deadline = Date.now() + timeout;
       let contextId = this.frameExecutionContexts.get(frameId);
-      while (!contextId && Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
-        contextId = this.frameExecutionContexts.get(frameId);
+      if (!contextId) {
+        contextId = await this.waitForFrameContext(frameId, Math.min(timeout, 2e3));
       }
       if (contextId) {
         this.currentFrameContextId = contextId;
+        this.brokenFrame = null;
+      } else {
+        const frameKey2 = Array.isArray(selector) ? selector[0] : selector;
+        this.brokenFrame = frameKey2;
+        console.warn(
+          `[browser-pilot] Frame "${frameKey2}" execution context unavailable. JS evaluation will fail in this frame. DOM operations may still work.`
+        );
       }
     }
     this.refMap.clear();
@@ -3923,6 +5204,7 @@ var Page = class {
     this.currentFrame = null;
     this.rootNodeId = null;
     this.currentFrameContextId = null;
+    this.brokenFrame = null;
     this.refMap.clear();
   }
   /**
@@ -3972,109 +5254,491 @@ var Page = class {
     }
     return result.success;
   }
-  // ============ JavaScript Execution ============
-  /**
-   * Evaluate JavaScript in the page context (or current frame context if in iframe)
-   */
-  async evaluate(expression, ...args) {
-    let script;
-    if (typeof expression === "function") {
-      const argString = args.map((a) => JSON.stringify(a)).join(", ");
-      script = `(${expression.toString()})(${argString})`;
-    } else {
-      script = expression;
-    }
-    const params = {
-      expression: script,
-      returnByValue: true,
-      awaitPromise: true
-    };
-    if (this.currentFrameContextId !== null) {
-      params["contextId"] = this.currentFrameContextId;
+  // ============ JavaScript Execution ============
+  /**
+   * Evaluate JavaScript in the page context (or current frame context if in iframe)
+   */
+  async evaluate(expression, ...args) {
+    let script;
+    if (typeof expression === "function") {
+      const argString = args.map((a) => JSON.stringify(a)).join(", ");
+      script = `(${expression.toString()})(${argString})`;
+    } else {
+      script = expression;
+    }
+    const params = {
+      expression: script,
+      returnByValue: true,
+      awaitPromise: true
+    };
+    if (this.currentFrameContextId !== null) {
+      params["contextId"] = this.currentFrameContextId;
+    }
+    const result = await this.cdp.send("Runtime.evaluate", params);
+    if (result.exceptionDetails) {
+      throw new Error(`Evaluation failed: ${result.exceptionDetails.text}`);
+    }
+    return result.result.value;
+  }
+  // ============ Screenshots ============
+  /**
+   * Take a screenshot
+   */
+  async screenshot(options = {}) {
+    const { format = "png", quality, fullPage = false } = options;
+    let clip;
+    if (fullPage) {
+      const metrics = await this.cdp.send("Page.getLayoutMetrics");
+      clip = {
+        x: 0,
+        y: 0,
+        width: metrics.contentSize.width,
+        height: metrics.contentSize.height,
+        scale: 1
+      };
+    }
+    const result = await this.cdp.send("Page.captureScreenshot", {
+      format,
+      quality: format === "png" ? void 0 : quality,
+      clip,
+      captureBeyondViewport: fullPage
+    });
+    return result.data;
+  }
+  // ============ Text Extraction ============
+  /**
+   * Get text content from the page or a specific element
+   */
+  async text(selector) {
+    if (!selector) {
+      const result = await this.evaluateInFrame(
+        "document.body.innerText"
+      );
+      return result.result.value ?? "";
+    }
+    return this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, { timeout: DEFAULT_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 = {}) {
+    return this.withStaleNodeRetry(async () => {
+      const element = await this.findElement(selector, options);
+      if (!element) {
+        if (options.optional) return false;
+        throw new ElementNotFoundError(selector);
+      }
+      const fileData = await Promise.all(
+        files.map(async (f) => {
+          let base64;
+          if (typeof f.buffer === "string") {
+            base64 = f.buffer;
+          } else {
+            const bytes = new Uint8Array(f.buffer);
+            base64 = btoa(String.fromCharCode(...bytes));
+          }
+          return { name: f.name, mimeType: f.mimeType, data: base64 };
+        })
+      );
+      const objectId = await this.resolveObjectId(element.nodeId);
+      const result = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function(files) {
+          if (!(this instanceof HTMLInputElement) || this.type !== 'file') {
+            return { ok: false, fileCount: 0 };
+          }
+
+          const dt = new DataTransfer();
+          for (const f of files) {
+            const bytes = Uint8Array.from(atob(f.data), function(c) { return c.charCodeAt(0); });
+            const file = new File([bytes], f.name, { type: f.mimeType });
+            dt.items.add(file);
+          }
+
+          var descriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'files');
+          if (descriptor && descriptor.set) {
+            descriptor.set.call(this, dt.files);
+          } else {
+            this.files = dt.files;
+          }
+
+          this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+          this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+          return {
+            ok: (this.files && this.files.length === files.length) || files.length === 0,
+            fileCount: this.files ? this.files.length : 0
+          };
+        }`,
+        arguments: [{ value: fileData }],
+        returnByValue: true
+      });
+      if (!result.result.value.ok) {
+        if (options.optional) return false;
+        throw new Error("Failed to set files on input");
+      }
+      return true;
+    });
+  }
+  async getNativeSelectMetadata(objectId, targets) {
+    const result = await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function(targetValues) {
+        if (!(this instanceof HTMLSelectElement)) {
+          return {
+            currentIndex: -1,
+            currentValue: '',
+            disabled: [],
+            isSelect: false,
+            missing: Array.isArray(targetValues) ? targetValues.map(String) : [],
+            multiple: false,
+            options: [],
+            selectedValues: [],
+            targetIndexes: []
+          };
+        }
+
+        var allOptions = Array.from(this.options).map(function(opt, index) {
+          return { index: index, label: opt.label || opt.text || '', value: opt.value || '' };
+        });
+        var targetIndexes = [];
+        var missing = [];
+        var disabled = [];
+
+        for (var i = 0; i < targetValues.length; i++) {
+          var target = String(targetValues[i]);
+          var idx = -1;
+
+          for (var j = 0; j < this.options.length; j++) {
+            var opt = this.options[j];
+            if (opt.value === target || opt.text === target || opt.label === target) {
+              idx = j;
+              break;
+            }
+          }
+
+          if (idx === -1 && /^\\d+$/.test(target)) {
+            var numericIndex = parseInt(target, 10);
+            if (numericIndex >= 0 && numericIndex < this.options.length) {
+              idx = numericIndex;
+            }
+          }
+
+          if (idx === -1) {
+            missing.push(target);
+            continue;
+          }
+
+          if (this.options[idx] && this.options[idx].disabled) {
+            disabled.push(target);
+            continue;
+          }
+
+          if (targetIndexes.indexOf(idx) === -1) {
+            targetIndexes.push(idx);
+          }
+        }
+
+        return {
+          currentIndex: this.selectedIndex,
+          currentValue: this.value || '',
+          disabled: disabled,
+          isSelect: true,
+          missing: missing,
+          multiple: !!this.multiple,
+          options: allOptions,
+          selectedValues: Array.from(this.selectedOptions).map(function(opt) { return opt.value || ''; }),
+          targetIndexes: targetIndexes
+        };
+      }`,
+      arguments: [{ value: targets }],
+      returnByValue: true
+    });
+    return result.result.value;
+  }
+  async readNativeSelectValues(objectId) {
+    const result = await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: 'function() { return this instanceof HTMLSelectElement ? Array.from(this.selectedOptions).map(function(opt) { return opt.value || ""; }) : []; }',
+      returnByValue: true
+    });
+    return result.result.value ?? [];
+  }
+  selectValuesMatch(actual, expected, multiple) {
+    if (!multiple) {
+      return (actual[0] ?? "") === (expected[0] ?? "");
     }
-    const result = await this.cdp.send("Runtime.evaluate", params);
-    if (result.exceptionDetails) {
-      throw new Error(`Evaluation failed: ${result.exceptionDetails.text}`);
+    if (actual.length !== expected.length) {
+      return false;
     }
-    return result.result.value;
+    const actualSorted = [...actual].sort();
+    const expectedSorted = [...expected].sort();
+    return actualSorted.every((value, index) => value === expectedSorted[index]);
   }
-  // ============ Screenshots ============
-  /**
-   * Take a screenshot
-   */
-  async screenshot(options = {}) {
-    const { format = "png", quality, fullPage = false } = options;
-    let clip;
-    if (fullPage) {
-      const metrics = await this.cdp.send("Page.getLayoutMetrics");
-      clip = {
-        x: 0,
-        y: 0,
-        width: metrics.contentSize.width,
-        height: metrics.contentSize.height,
-        scale: 1
-      };
+  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 result = await this.cdp.send("Page.captureScreenshot", {
-      format,
-      quality: format === "png" ? void 0 : quality,
-      clip,
-      captureBeyondViewport: fullPage
+    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
     });
-    return result.data;
   }
-  // ============ Text Extraction ============
-  /**
-   * Get text content from the page or a specific element
-   */
-  async text(selector) {
-    const expression = selector ? `document.querySelector(${JSON.stringify(selector)})?.innerText ?? ''` : "document.body.innerText";
-    const result = await this.evaluateInFrame(expression);
+  async 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 ?? "";
   }
-  // ============ File Handling ============
-  /**
-   * Set files on a file input
-   */
-  async setInputFiles(selector, files, options = {}) {
-    const element = await this.findElement(selector, options);
-    if (!element) {
-      if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+  async typeEditableFallback(nodeId, objectId, value) {
+    await this.selectEditableContent(objectId);
+    await this.cdp.send("DOM.focus", { nodeId });
+    for (const char of value) {
+      await this.dispatchKey(char);
     }
-    const fileData = await Promise.all(
-      files.map(async (f) => {
-        let base64;
-        if (typeof f.buffer === "string") {
-          base64 = f.buffer;
-        } else {
-          const bytes = new Uint8Array(f.buffer);
-          base64 = btoa(String.fromCharCode(...bytes));
+  }
+  async applyRecordedSelectFallback(objectId, targetIndexes) {
+    await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function(indexes) {
+        if (!(this instanceof HTMLSelectElement)) return false;
+
+        var wanted = new Set(indexes.map(function(index) { return Number(index); }));
+        for (var i = 0; i < this.options.length; i++) {
+          this.options[i].selected = wanted.has(i);
         }
-        return { name: f.name, mimeType: f.mimeType, data: base64 };
-      })
-    );
-    await this.cdp.send("Runtime.evaluate", {
-      expression: `(() => {
-        const input = document.querySelector(${JSON.stringify(element.selector)});
-        if (!input) return false;
+        if (!this.multiple && indexes.length === 1) {
+          this.selectedIndex = indexes[0];
+        }
+        return true;
+      }`,
+      arguments: [{ value: targetIndexes }],
+      returnByValue: true
+    });
+    return this.invokeRecordedEventListeners(objectId, ["input", "change"]);
+  }
+  async invokeRecordedEventListeners(objectId, eventTypes) {
+    const result = await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function(types) {
+        function buildPath(target) {
+          var path = [];
+          var node = target;
+
+          while (node) {
+            path.push(node);
+
+            if (node.parentElement) {
+              node = node.parentElement;
+              continue;
+            }
+
+            if (node === document) {
+              node = window;
+              continue;
+            }
+
+            if (node.defaultView && node !== node.defaultView) {
+              node = node.defaultView;
+              continue;
+            }
+
+            if (node.ownerDocument && node !== node.ownerDocument) {
+              node = node.ownerDocument;
+              continue;
+            }
+
+            var root = node.getRootNode && node.getRootNode();
+            if (root && root !== node && root.host) {
+              node = root.host;
+              continue;
+            }
 
-        const files = ${JSON.stringify(fileData)};
-        const dt = new DataTransfer();
+            node = null;
+          }
 
-        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);
+          return path;
         }
 
-        input.files = dt.files;
-        input.dispatchEvent(new Event('change', { bubbles: true }));
-        return true;
-      })()`,
+        function createEvent(type, target, currentTarget, path, phase) {
+          return {
+            type: type,
+            target: target,
+            currentTarget: currentTarget,
+            srcElement: target,
+            isTrusted: true,
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            defaultPrevented: false,
+            eventPhase: phase,
+            timeStamp: Date.now(),
+            preventDefault: function() {
+              this.defaultPrevented = true;
+            },
+            stopPropagation: function() {
+              this.__stopped = true;
+            },
+            stopImmediatePropagation: function() {
+              this.__stopped = true;
+              this.__immediateStopped = true;
+            },
+            composedPath: function() {
+              return path.slice();
+            }
+          };
+        }
+
+        function invokePhase(type, nodes, capture, target, path) {
+          var invoked = false;
+
+          for (var i = 0; i < nodes.length; i++) {
+            var currentTarget = nodes[i];
+
+            var phase = currentTarget === target ? 2 : capture ? 1 : 3;
+
+            // Invoke inline handler if present (e.g. onclick, oninput)
+            var inlineHandler = currentTarget['on' + type];
+            if (typeof inlineHandler === 'function') {
+              var inlineEvent = createEvent(type, target, currentTarget, path, phase);
+              inlineHandler.call(currentTarget, inlineEvent);
+              invoked = true;
+              if (inlineEvent.__stopped) break;
+            }
+
+            var store = currentTarget && currentTarget.__bpEventListeners;
+            var entries = store && store[type];
+            if (!Array.isArray(entries) || entries.length === 0) continue;
+
+            var event = createEvent(type, target, currentTarget, path, phase);
+
+            for (var j = 0; j < entries.length; j++) {
+              var entry = entries[j];
+              if (!!entry.capture !== capture) continue;
+
+              var listener = entry.listener;
+              if (typeof listener === 'function') {
+                listener.call(currentTarget, event);
+                invoked = true;
+              } else if (listener && typeof listener.handleEvent === 'function') {
+                listener.handleEvent(event);
+                invoked = true;
+              }
+
+              if (event.__immediateStopped) {
+                break;
+              }
+            }
+
+            if (event.__stopped) {
+              break;
+            }
+          }
+
+          return invoked;
+        }
+
+        var path = buildPath(this);
+        var capturePath = path.slice().reverse();
+        var bubblePath = path.slice();
+        var invokedAny = false;
+
+        for (var i = 0; i < types.length; i++) {
+          var type = String(types[i]);
+          if (invokePhase(type, capturePath, true, this, path)) {
+            invokedAny = true;
+          }
+          if (invokePhase(type, bubblePath, false, this, path)) {
+            invokedAny = true;
+          }
+        }
+
+        return invokedAny;
+      }`,
+      arguments: [{ value: eventTypes }],
       returnByValue: true
     });
-    return true;
+    return result.result.value ?? false;
   }
   /**
    * Wait for a download to complete, triggered by an action
@@ -4234,7 +5898,7 @@ var Page = class {
       return lines.join("\n");
     };
     const text = formatTree(accessibilityTree);
-    return {
+    const result = {
       url,
       title,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -4242,6 +5906,8 @@ var Page = class {
       interactiveElements,
       text
     };
+    this.lastSnapshot = result;
+    return result;
   }
   /**
    * Export the current ref map for cross-exec reuse (CLI).
@@ -4655,8 +6321,15 @@ var Page = class {
       }
     };
     if (this.dialogHandler) {
+      const DIALOG_TIMEOUT = 5e3;
       try {
-        await this.dialogHandler(dialog);
+        await Promise.race([
+          this.dialogHandler(dialog),
+          sleep5(DIALOG_TIMEOUT).then(() => {
+            console.warn("[browser-pilot] Dialog handler timed out after 5s, auto-dismissing");
+            return dialog.dismiss();
+          })
+        ]);
       } catch (e) {
         console.error("[Dialog handler error]", e);
         await dialog.dismiss();
@@ -4736,6 +6409,7 @@ var Page = class {
     this.refMap.clear();
     this.currentFrame = null;
     this.currentFrameContextId = null;
+    this.brokenFrame = null;
     this.frameContexts.clear();
     this.dialogHandler = null;
     try {
@@ -4770,11 +6444,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;
           }
         }
@@ -4819,6 +6495,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;
@@ -4882,6 +6591,34 @@ var Page = class {
    */
   async ensureRootNode() {
     if (this.rootNodeId) return;
+    if (this.currentFrame) {
+      const mainDocument = await this.cdp.send("DOM.getDocument", {
+        depth: 0
+      });
+      const iframeNode = await this.cdp.send("DOM.querySelector", {
+        nodeId: mainDocument.root.nodeId,
+        selector: this.currentFrame
+      });
+      if (iframeNode.nodeId) {
+        const frameResult = await this.cdp.send("DOM.describeNode", {
+          nodeId: iframeNode.nodeId,
+          depth: 1
+        });
+        if (frameResult.node.contentDocument?.nodeId) {
+          this.rootNodeId = frameResult.node.contentDocument.nodeId;
+          if (frameResult.node.frameId) {
+            let contextId = this.frameExecutionContexts.get(frameResult.node.frameId);
+            if (!contextId) {
+              contextId = await this.waitForFrameContext(frameResult.node.frameId, 1e3);
+            }
+            this.currentFrameContextId = contextId ?? null;
+          }
+          return;
+        }
+      }
+      this.currentFrame = null;
+      this.currentFrameContextId = null;
+    }
     const doc = await this.cdp.send("DOM.getDocument", {
       depth: 0
     });
@@ -4892,6 +6629,11 @@ var Page = class {
    * Automatically injects contextId when in an iframe
    */
   async evaluateInFrame(expression, options = {}) {
+    if (this.brokenFrame && this.currentFrame) {
+      throw new Error(
+        `Cannot evaluate JavaScript in frame "${this.brokenFrame}": execution context is unavailable (cross-origin or sandboxed iframe). DOM operations (click, fill, etc.) may still work via CDP.`
+      );
+    }
     const params = {
       expression,
       returnByValue: options.returnByValue ?? true,
@@ -4903,10 +6645,43 @@ var Page = class {
     return this.cdp.send("Runtime.evaluate", params);
   }
   /**
-   * Scroll an element into view
+   * Scroll an element into view, with fallback to center-scroll if clipped by fixed headers
    */
   async scrollIntoView(nodeId) {
     await this.cdp.send("DOM.scrollIntoViewIfNeeded", { nodeId });
+    if (!await this.isInViewport(nodeId)) {
+      const objectId = await this.resolveObjectId(nodeId);
+      await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function() { this.scrollIntoView({ block: 'center', inline: 'center' }); }`
+      });
+    }
+  }
+  /**
+   * Check if element is within the visible viewport
+   */
+  async isInViewport(nodeId) {
+    try {
+      const objectId = await this.resolveObjectId(nodeId);
+      const result = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function() {
+          var rect = this.getBoundingClientRect();
+          return (
+            rect.top >= 0 &&
+            rect.left >= 0 &&
+            rect.bottom <= window.innerHeight &&
+            rect.right <= window.innerWidth &&
+            rect.width > 0 &&
+            rect.height > 0
+          );
+        }`,
+        returnByValue: true
+      });
+      return result?.result?.value === true;
+    } catch {
+      return true;
+    }
   }
   /**
    * Get element box model (position and dimensions)
@@ -4922,30 +6697,147 @@ var Page = class {
     }
   }
   /**
-   * Click an element by node ID
+   * Click an element by node ID using Playwright's 3-event sequence:
+   * mouseMoved → mousePressed → mouseReleased (sequential).
+   * Uses DOM.getContentQuads for accurate coordinates (handles CSS transforms).
+   * Falls back to JS this.click() if CDP mouse dispatch fails.
    */
   async clickElement(nodeId) {
-    const box = await this.getBoxModel(nodeId);
-    if (!box) {
-      throw new Error("Could not get element box model for click");
-    }
-    const x = box.content[0] + box.width / 2;
-    const y = box.content[1] + box.height / 2;
-    await this.cdp.send("Input.dispatchMouseEvent", {
-      type: "mousePressed",
-      x,
-      y,
-      button: "left",
-      clickCount: 1
+    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, modifierBitmask = 0) {
+    const downParams = {
+      type: def.text !== void 0 ? "keyDown" : "rawKeyDown",
+      key: def.key,
+      code: def.code,
+      windowsVirtualKeyCode: def.keyCode,
+      modifiers: modifierBitmask,
+      autoRepeat: false,
+      location: def.location ?? 0,
+      isKeypad: false
+    };
+    if (def.text !== void 0) {
+      downParams["text"] = def.text;
+      downParams["unmodifiedText"] = def.text;
+    }
+    await this.cdp.send("Input.dispatchKeyEvent", downParams);
+    await this.cdp.send("Input.dispatchKeyEvent", {
+      type: "keyUp",
+      key: def.key,
+      code: def.code,
+      windowsVirtualKeyCode: def.keyCode,
+      modifiers: modifierBitmask,
+      location: def.location ?? 0
     });
   }
+  async dispatchKey(key) {
+    const def = US_KEYBOARD[key];
+    if (def) {
+      await this.dispatchKeyDefinition(def);
+      return;
+    }
+    if (key.length === 1) {
+      await this.cdp.send("Input.insertText", { text: key });
+      return;
+    }
+    await this.dispatchKeyDefinition({ key, code: key, keyCode: 0 });
+  }
+  async dispatchKeyWithModifiers(key, modifiers) {
+    const mask = computeModifierBitmask(modifiers);
+    for (const mod of modifiers) {
+      await this.cdp.send("Input.dispatchKeyEvent", {
+        type: "rawKeyDown",
+        key: mod,
+        code: MODIFIER_CODES[mod],
+        windowsVirtualKeyCode: MODIFIER_KEY_CODES[mod],
+        modifiers: mask,
+        location: 1
+      });
+    }
+    const def = US_KEYBOARD[key];
+    if (def) {
+      await this.dispatchKeyDefinition(def, mask);
+    } else if (key.length === 1) {
+      await this.dispatchKeyDefinition({ key, code: key, keyCode: 0, text: key }, mask);
+    } else {
+      await this.dispatchKeyDefinition({ key, code: key, keyCode: 0 }, mask);
+    }
+    for (let i = modifiers.length - 1; i >= 0; i--) {
+      const mod = modifiers[i];
+      await this.cdp.send("Input.dispatchKeyEvent", {
+        type: "keyUp",
+        key: mod,
+        code: MODIFIER_CODES[mod],
+        windowsVirtualKeyCode: MODIFIER_KEY_CODES[mod],
+        modifiers: 0,
+        location: 1
+      });
+    }
+  }
   // ============ Audio I/O ============
   /**
    * Audio input controller (fake microphone).
@@ -5018,7 +6910,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
@@ -5045,12 +6937,68 @@ var Page = class {
       totalMs: Date.now() - start
     };
   }
+  /**
+   * Wait for a DOM mutation in the current frame (used for detecting client-side form handling)
+   */
+  async waitForDOMMutation(options) {
+    await this.evaluateInFrame(
+      `new Promise((resolve) => {
+        var observer = new MutationObserver(function() {
+          observer.disconnect();
+          resolve();
+        });
+        observer.observe(document.body, { childList: true, subtree: true });
+        setTimeout(function() { observer.disconnect(); resolve(); }, ${options.timeout});
+      })`
+    );
+  }
+  /**
+   * Wait for a frame execution context via Runtime.executionContextCreated event
+   */
+  async waitForFrameContext(frameId, timeout) {
+    const existing = this.frameExecutionContexts.get(frameId);
+    if (existing) return existing;
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        resolve(void 0);
+      }, timeout);
+      const handler = (params) => {
+        const context = params["context"];
+        if (context.auxData?.frameId === frameId && context.auxData?.isDefault !== false) {
+          cleanup();
+          resolve(context.id);
+        }
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.cdp.off("Runtime.executionContextCreated", handler);
+      };
+      this.cdp.on("Runtime.executionContextCreated", handler);
+    });
+  }
 };
-function sleep3(ms) {
+function sleep5(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 // src/browser/browser.ts
+function scoreTarget(t) {
+  let score = 0;
+  if (t.url.startsWith("http://") || t.url.startsWith("https://")) score += 10;
+  if (t.url.startsWith("chrome://")) score -= 20;
+  if (t.url.startsWith("chrome-extension://")) score -= 15;
+  if (t.url.startsWith("devtools://")) score -= 25;
+  if (t.url === "about:blank") score -= 5;
+  if (!t.attached) score += 3;
+  if (t.title && t.title.length > 0) score += 2;
+  return score;
+}
+function pickBestTarget(targets) {
+  if (targets.length === 0) return void 0;
+  const sorted = [...targets].sort((a, b) => scoreTarget(b) - scoreTarget(a));
+  return sorted[0].targetId;
+}
 var Browser = class _Browser {
   cdp;
   providerSession;
@@ -5072,28 +7020,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"
@@ -5103,6 +7069,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;
   }