browser-pilot 0.0.11 → 0.0.13

package/dist/{chunk-JHAF52FA.mjs → chunk-VDAMDOS6.mjs}

@@ -1,14 +1,17 @@
 import {
   createCDPClient
-} from "./chunk-BCOZUKWS.mjs";
+} from "./chunk-HP6R3W32.mjs";
 import {
   createProvider
 } from "./chunk-BRAFQUMG.mjs";
 import {
+  ActionabilityError,
   BatchExecutor,
   ElementNotFoundError,
-  TimeoutError
-} from "./chunk-FAUNIZR7.mjs";
+  TimeoutError,
+  ensureActionable,
+  generateHints
+} from "./chunk-A2ZRAEO3.mjs";
 
 // src/audio/encoding.ts
 function bufferToBase64(data) {
@@ -1122,35 +1125,37 @@ var AudioOutput = class {
       let heardAudio = false;
       let lastSoundTime = 0;
       const startTime = Date.now();
-      const checkInterval = setInterval(async () => {
-        const elapsed = Date.now() - startTime;
-        if (elapsed > maxDuration) {
-          clearInterval(checkInterval);
-          this.onDiagHandler?.(`max duration reached (${maxDuration}ms), stopping`);
-          resolve(await this.stop());
-          return;
-        }
-        const latest = this.chunks[this.chunks.length - 1];
-        if (latest) {
-          const rms = calculateRMS(latest.left);
-          if (rms > silenceThreshold) {
-            if (!heardAudio) {
-              heardAudio = true;
-              this.onDiagHandler?.("first audio detected \u2014 silence countdown begins");
+      const checkInterval = setInterval(() => {
+        void (async () => {
+          const elapsed = Date.now() - startTime;
+          if (elapsed > maxDuration) {
+            clearInterval(checkInterval);
+            this.onDiagHandler?.(`max duration reached (${maxDuration}ms), stopping`);
+            resolve(await this.stop());
+            return;
+          }
+          const latest = this.chunks[this.chunks.length - 1];
+          if (latest) {
+            const rms = calculateRMS(latest.left);
+            if (rms > silenceThreshold) {
+              if (!heardAudio) {
+                heardAudio = true;
+                this.onDiagHandler?.("first audio detected \u2014 silence countdown begins");
+              }
+              lastSoundTime = Date.now();
             }
-            lastSoundTime = Date.now();
           }
-        }
-        if (!heardAudio && elapsed > noAudioTimeout) {
-          clearInterval(checkInterval);
-          this.onDiagHandler?.(`no audio detected after ${noAudioTimeout}ms, stopping early`);
-          resolve(await this.stop());
-          return;
-        }
-        if (heardAudio && Date.now() - lastSoundTime > silenceTimeout) {
-          clearInterval(checkInterval);
-          resolve(await this.stop());
-        }
+          if (!heardAudio && elapsed > noAudioTimeout) {
+            clearInterval(checkInterval);
+            this.onDiagHandler?.(`no audio detected after ${noAudioTimeout}ms, stopping early`);
+            resolve(await this.stop());
+            return;
+          }
+          if (heardAudio && Date.now() - lastSoundTime > silenceTimeout) {
+            clearInterval(checkInterval);
+            resolve(await this.stop());
+          }
+        })();
       }, 200);
     });
   }
@@ -1325,8 +1330,12 @@ var RequestInterceptor = class {
   boundHandleAuthRequired;
   constructor(cdp) {
     this.cdp = cdp;
-    this.boundHandleRequestPaused = this.handleRequestPaused.bind(this);
-    this.boundHandleAuthRequired = this.handleAuthRequired.bind(this);
+    this.boundHandleRequestPaused = (params) => {
+      void this.handleRequestPaused(params);
+    };
+    this.boundHandleAuthRequired = (params) => {
+      void this.handleAuthRequired(params);
+    };
   }
   /**
    * Enable request interception with optional patterns
@@ -1498,6 +1507,285 @@ var RequestInterceptor = class {
   }
 };
 
+// src/browser/special-selectors.ts
+function stripQuotes(value) {
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function parseTextSelector(selector) {
+  if (!selector.startsWith("text:")) return null;
+  let raw = selector.slice(5).trim();
+  let exact = false;
+  if (raw.startsWith("=")) {
+    exact = true;
+    raw = raw.slice(1).trim();
+  }
+  const query = stripQuotes(raw);
+  if (!query) return null;
+  return { query, exact };
+}
+function parseRoleSelector(selector) {
+  if (!selector.startsWith("role:")) return null;
+  const body = selector.slice(5);
+  const separator = body.indexOf(":");
+  const role = (separator === -1 ? body : body.slice(0, separator)).trim().toLowerCase();
+  const name = separator === -1 ? void 0 : stripQuotes(body.slice(separator + 1).trim());
+  if (!role) return null;
+  return { role, name: name || void 0 };
+}
+var SPECIAL_SELECTOR_SCRIPT = `
+function bpNormalizeSpace(value) {
+  return String(value == null ? '' : value).replace(/\\s+/g, ' ').trim();
+}
+
+function bpCollectElements(root) {
+  var elements = [];
+
+  function visit(node) {
+    if (!node || typeof node.querySelectorAll !== 'function') return;
+    var matches = node.querySelectorAll('*');
+    for (var i = 0; i < matches.length; i++) {
+      var el = matches[i];
+      elements.push(el);
+      if (el.shadowRoot) {
+        visit(el.shadowRoot);
+      }
+    }
+  }
+
+  if (root && root.documentElement) {
+    elements.push(root.documentElement);
+  }
+
+  visit(root);
+  return elements;
+}
+
+function bpIsVisible(el) {
+  if (!el) return false;
+  var style = getComputedStyle(el);
+  if (style.display === 'none') return false;
+  if (style.visibility === 'hidden') return false;
+  if (parseFloat(style.opacity || '1') === 0) return false;
+  var rect = el.getBoundingClientRect();
+  return rect.width > 0 && rect.height > 0;
+}
+
+function bpInferRole(el) {
+  if (!el || !el.tagName) return '';
+
+  var explicitRole = bpNormalizeSpace(el.getAttribute && el.getAttribute('role'));
+  if (explicitRole) return explicitRole.toLowerCase();
+
+  var tag = el.tagName.toLowerCase();
+  if (tag === 'button') return 'button';
+  if (tag === 'a' && el.hasAttribute('href')) return 'link';
+  if (tag === 'textarea') return 'textbox';
+  if (tag === 'select') return el.multiple ? 'listbox' : 'combobox';
+  if (tag === 'option') return 'option';
+  if (tag === 'summary') return 'button';
+
+  if (tag === 'input') {
+    var type = (el.type || 'text').toLowerCase();
+    if (type === 'checkbox') return 'checkbox';
+    if (type === 'radio') return 'radio';
+    if (type === 'search') return 'searchbox';
+    if (type === 'number') return 'spinbutton';
+    if (type === 'button' || type === 'submit' || type === 'reset' || type === 'image') {
+      return 'button';
+    }
+    return 'textbox';
+  }
+
+  return '';
+}
+
+function bpTextFromIdRefs(refs) {
+  if (!refs) return '';
+  var ids = refs.split(/\\s+/).filter(Boolean);
+  var parts = [];
+  for (var i = 0; i < ids.length; i++) {
+    var node = document.getElementById(ids[i]);
+    if (!node) continue;
+    var text = bpNormalizeSpace(node.innerText || node.textContent || '');
+    if (text) parts.push(text);
+  }
+  return bpNormalizeSpace(parts.join(' '));
+}
+
+function bpAccessibleName(el) {
+  if (!el) return '';
+
+  var labelledBy = bpTextFromIdRefs(el.getAttribute && el.getAttribute('aria-labelledby'));
+  if (labelledBy) return labelledBy;
+
+  var ariaLabel = bpNormalizeSpace(el.getAttribute && el.getAttribute('aria-label'));
+  if (ariaLabel) return ariaLabel;
+
+  if (el.labels && el.labels.length) {
+    var labels = [];
+    for (var i = 0; i < el.labels.length; i++) {
+      var labelText = bpNormalizeSpace(el.labels[i].innerText || el.labels[i].textContent || '');
+      if (labelText) labels.push(labelText);
+    }
+    if (labels.length) return bpNormalizeSpace(labels.join(' '));
+  }
+
+  if (el.id) {
+    var fallbackLabel = document.querySelector('label[for="' + el.id.replace(/"/g, '\\\\"') + '"]');
+    if (fallbackLabel) {
+      var fallbackText = bpNormalizeSpace(
+        fallbackLabel.innerText || fallbackLabel.textContent || ''
+      );
+      if (fallbackText) return fallbackText;
+    }
+  }
+
+  var type = (el.type || '').toLowerCase();
+  if (
+    el.tagName === 'INPUT' &&
+    (type === 'submit' || type === 'button' || type === 'reset' || type === 'image')
+  ) {
+    var inputValue = bpNormalizeSpace(el.value || el.getAttribute('value'));
+    if (inputValue) return inputValue;
+  }
+
+  var alt = bpNormalizeSpace(el.getAttribute && el.getAttribute('alt'));
+  if (alt) return alt;
+
+  var text = bpNormalizeSpace(el.innerText || el.textContent || '');
+  if (text) return text;
+
+  var placeholder = bpNormalizeSpace(el.getAttribute && el.getAttribute('placeholder'));
+  if (placeholder) return placeholder;
+
+  var title = bpNormalizeSpace(el.getAttribute && el.getAttribute('title'));
+  if (title) return title;
+
+  var value = bpNormalizeSpace(el.value);
+  if (value) return value;
+
+  return bpNormalizeSpace(el.name || el.id || '');
+}
+
+function bpIsInteractive(role, el) {
+  if (
+    role === 'button' ||
+    role === 'link' ||
+    role === 'textbox' ||
+    role === 'checkbox' ||
+    role === 'radio' ||
+    role === 'combobox' ||
+    role === 'listbox' ||
+    role === 'option' ||
+    role === 'searchbox' ||
+    role === 'spinbutton' ||
+    role === 'switch' ||
+    role === 'tab'
+  ) {
+    return true;
+  }
+
+  if (!el || !el.tagName) return false;
+  var tag = el.tagName.toLowerCase();
+  return tag === 'button' || tag === 'a' || tag === 'input' || tag === 'select' || tag === 'textarea';
+}
+
+function bpFindByText(query, exact, includeHidden) {
+  var needle = bpNormalizeSpace(query).toLowerCase();
+  if (!needle) return null;
+
+  var best = null;
+  var bestScore = -1;
+  var elements = bpCollectElements(document);
+
+  for (var i = 0; i < elements.length; i++) {
+    var el = elements[i];
+    if (!includeHidden && !bpIsVisible(el)) continue;
+
+    var text = bpAccessibleName(el);
+    if (!text) continue;
+
+    var haystack = text.toLowerCase();
+    var matched = exact ? haystack === needle : haystack.includes(needle);
+    if (!matched) continue;
+
+    var role = bpInferRole(el);
+    var score = 0;
+    if (bpIsInteractive(role, el)) score += 100;
+    if (haystack === needle) score += 50;
+    if (role === 'button' || role === 'link') score += 10;
+
+    if (score > bestScore) {
+      best = el;
+      bestScore = score;
+    }
+  }
+
+  return best;
+}
+
+function bpFindByRole(role, name, includeHidden) {
+  var targetRole = bpNormalizeSpace(role).toLowerCase();
+  if (!targetRole) return null;
+
+  var nameNeedle = bpNormalizeSpace(name).toLowerCase();
+  var best = null;
+  var bestScore = -1;
+  var elements = bpCollectElements(document);
+
+  for (var i = 0; i < elements.length; i++) {
+    var el = elements[i];
+    if (!includeHidden && !bpIsVisible(el)) continue;
+
+    var actualRole = bpInferRole(el);
+    if (actualRole !== targetRole) continue;
+
+    var accessibleName = bpAccessibleName(el);
+    if (nameNeedle) {
+      var loweredName = accessibleName.toLowerCase();
+      if (!loweredName.includes(nameNeedle)) continue;
+    }
+
+    var score = 0;
+    if (accessibleName) score += 10;
+    if (nameNeedle && accessibleName.toLowerCase() === nameNeedle) score += 20;
+
+    if (score > bestScore) {
+      best = el;
+      bestScore = score;
+    }
+  }
+
+  return best;
+}
+`;
+function buildSpecialSelectorLookupExpression(selector, options = {}) {
+  const includeHidden = options.includeHidden === true;
+  const text = parseTextSelector(selector);
+  if (text) {
+    return `(() => {
+      ${SPECIAL_SELECTOR_SCRIPT}
+      return bpFindByText(${JSON.stringify(text.query)}, ${text.exact}, ${includeHidden});
+    })()`;
+  }
+  const role = parseRoleSelector(selector);
+  if (role) {
+    return `(() => {
+      ${SPECIAL_SELECTOR_SCRIPT}
+      return bpFindByRole(${JSON.stringify(role.role)}, ${JSON.stringify(role.name ?? "")}, ${includeHidden});
+    })()`;
+  }
+  return null;
+}
+function buildSpecialSelectorPredicateExpression(selector, options = {}) {
+  const lookup = buildSpecialSelectorLookupExpression(selector, options);
+  if (!lookup) return null;
+  return `(() => !!(${lookup}))()`;
+}
+
 // src/wait/strategies.ts
 var DEEP_QUERY_SCRIPT = `
 function deepQuery(selector, root = document) {
@@ -1531,18 +1819,19 @@ function deepQuery(selector, root = document) {
 }
 `;
 async function isElementVisible(cdp, selector, contextId) {
+  const specialExpression = buildSpecialSelectorPredicateExpression(selector);
   const params = {
-    expression: `(() => {
-      ${DEEP_QUERY_SCRIPT}
-      const el = deepQuery(${JSON.stringify(selector)});
-      if (!el) return false;
-      const style = getComputedStyle(el);
-      if (style.display === 'none') return false;
-      if (style.visibility === 'hidden') return false;
-      if (parseFloat(style.opacity) === 0) return false;
-      const rect = el.getBoundingClientRect();
-      return rect.width > 0 && rect.height > 0;
-    })()`,
+    expression: specialExpression ?? `(() => {
+        ${DEEP_QUERY_SCRIPT}
+        const el = deepQuery(${JSON.stringify(selector)});
+        if (!el) return false;
+        const style = getComputedStyle(el);
+        if (style.display === 'none') return false;
+        if (style.visibility === 'hidden') return false;
+        if (parseFloat(style.opacity) === 0) return false;
+        const rect = el.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+      })()`,
     returnByValue: true
   };
   if (contextId !== void 0) {
@@ -1552,11 +1841,14 @@ async function isElementVisible(cdp, selector, contextId) {
   return result.result.value === true;
 }
 async function isElementAttached(cdp, selector, contextId) {
+  const specialExpression = buildSpecialSelectorPredicateExpression(selector, {
+    includeHidden: true
+  });
   const params = {
-    expression: `(() => {
-      ${DEEP_QUERY_SCRIPT}
-      return deepQuery(${JSON.stringify(selector)}) !== null;
-    })()`,
+    expression: specialExpression ?? `(() => {
+        ${DEEP_QUERY_SCRIPT}
+        return deepQuery(${JSON.stringify(selector)}) !== null;
+      })()`,
     returnByValue: true
   };
   if (contextId !== void 0) {
@@ -1568,30 +1860,71 @@ async function isElementAttached(cdp, selector, contextId) {
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function isPageStatic(cdp, windowMs = 200, contextId) {
+  const params = {
+    expression: `new Promise(resolve => {
+      // If page is still loading, it's not static
+      if (document.readyState !== 'complete') { resolve(false); return; }
+      // Check for recent page load (navigationStart within last 1s = page just loaded)
+      try {
+        var nav = performance.getEntriesByType('navigation')[0];
+        if (nav && (performance.now() - nav.loadEventEnd) < 500) { resolve(false); return; }
+      } catch(e) {}
+      // Observe for DOM mutations
+      var seen = false;
+      var obs = new MutationObserver(function() { seen = true; });
+      obs.observe(document.documentElement, { childList: true, subtree: true, attributes: true });
+      setTimeout(function() { obs.disconnect(); resolve(!seen); }, ${windowMs});
+    })`,
+    returnByValue: true,
+    awaitPromise: true
+  };
+  if (contextId !== void 0) params["contextId"] = contextId;
+  try {
+    const result = await cdp.send("Runtime.evaluate", params);
+    return result.result.value === true;
+  } catch {
+    return false;
+  }
+}
 async function waitForElement(cdp, selector, options = {}) {
   const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
   const startTime = Date.now();
   const deadline = startTime + timeout;
-  while (Date.now() < deadline) {
-    let conditionMet = false;
+  const checkCondition = async () => {
     switch (state) {
       case "visible":
-        conditionMet = await isElementVisible(cdp, selector, contextId);
-        break;
+        return isElementVisible(cdp, selector, contextId);
       case "hidden":
-        conditionMet = !await isElementVisible(cdp, selector, contextId);
-        break;
+        return !await isElementVisible(cdp, selector, contextId);
       case "attached":
-        conditionMet = await isElementAttached(cdp, selector, contextId);
-        break;
+        return isElementAttached(cdp, selector, contextId);
       case "detached":
-        conditionMet = !await isElementAttached(cdp, selector, contextId);
-        break;
+        return !await isElementAttached(cdp, selector, contextId);
+      default: {
+        const _exhaustive = state;
+        throw new Error(`Unhandled wait state: ${_exhaustive}`);
+      }
     }
-    if (conditionMet) {
-      return { success: true, waitedMs: Date.now() - startTime };
+  };
+  if (await checkCondition()) {
+    return { success: true, waitedMs: Date.now() - startTime };
+  }
+  const waitingForPresence = state === "visible" || state === "attached";
+  if (waitingForPresence && timeout >= 300) {
+    const pageStatic = await isPageStatic(cdp, 200, contextId);
+    if (pageStatic) {
+      if (await checkCondition()) {
+        return { success: true, waitedMs: Date.now() - startTime };
+      }
+      return { success: false, waitedMs: Date.now() - startTime };
     }
+  }
+  while (Date.now() < deadline) {
     await sleep2(pollInterval);
+    if (await checkCondition()) {
+      return { success: true, waitedMs: Date.now() - startTime };
+    }
   }
   return { success: false, waitedMs: Date.now() - startTime };
 }
@@ -1599,28 +1932,46 @@ async function waitForAnyElement(cdp, selectors, options = {}) {
   const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
   const startTime = Date.now();
   const deadline = startTime + timeout;
+  const checkSelector = async (selector) => {
+    switch (state) {
+      case "visible":
+        return isElementVisible(cdp, selector, contextId);
+      case "hidden":
+        return !await isElementVisible(cdp, selector, contextId);
+      case "attached":
+        return isElementAttached(cdp, selector, contextId);
+      case "detached":
+        return !await isElementAttached(cdp, selector, contextId);
+      default: {
+        const _exhaustive = state;
+        throw new Error(`Unhandled wait state: ${_exhaustive}`);
+      }
+    }
+  };
+  for (const selector of selectors) {
+    if (await checkSelector(selector)) {
+      return { success: true, selector, waitedMs: Date.now() - startTime };
+    }
+  }
+  const waitingForPresence = state === "visible" || state === "attached";
+  if (waitingForPresence && timeout >= 300) {
+    const pageStatic = await isPageStatic(cdp, 200, contextId);
+    if (pageStatic) {
+      for (const selector of selectors) {
+        if (await checkSelector(selector)) {
+          return { success: true, selector, waitedMs: Date.now() - startTime };
+        }
+      }
+      return { success: false, waitedMs: Date.now() - startTime };
+    }
+  }
   while (Date.now() < deadline) {
+    await sleep2(pollInterval);
     for (const selector of selectors) {
-      let conditionMet = false;
-      switch (state) {
-        case "visible":
-          conditionMet = await isElementVisible(cdp, selector, contextId);
-          break;
-        case "hidden":
-          conditionMet = !await isElementVisible(cdp, selector, contextId);
-          break;
-        case "attached":
-          conditionMet = await isElementAttached(cdp, selector, contextId);
-          break;
-        case "detached":
-          conditionMet = !await isElementAttached(cdp, selector, contextId);
-          break;
-      }
-      if (conditionMet) {
+      if (await checkSelector(selector)) {
         return { success: true, selector, waitedMs: Date.now() - startTime };
       }
     }
-    await sleep2(pollInterval);
   }
   return { success: false, waitedMs: Date.now() - startTime };
 }
@@ -1667,6 +2018,13 @@ async function waitForNavigation(cdp, options = {}) {
       cdp.on("Page.navigatedWithinDocument", onSameDoc);
       cleanup.push(() => cdp.off("Page.navigatedWithinDocument", onSameDoc));
     }
+    const onLifecycle = (params) => {
+      if (params["name"] === "networkIdle") {
+        done(true);
+      }
+    };
+    cdp.on("Page.lifecycleEvent", onLifecycle);
+    cleanup.push(() => cdp.off("Page.lifecycleEvent", onLifecycle));
     const pollUrl = async () => {
       while (!resolved && Date.now() < startTime + timeout) {
         await sleep2(100);
@@ -1681,7 +2039,7 @@ async function waitForNavigation(cdp, options = {}) {
         }
       }
     };
-    pollUrl();
+    void pollUrl();
   });
 }
 async function waitForNetworkIdle(cdp, options = {}) {
@@ -1729,580 +2087,6 @@ async function waitForNetworkIdle(cdp, options = {}) {
   });
 }
 
-// src/browser/actionability.ts
-var ActionabilityError = class extends Error {
-  failureType;
-  coveringElement;
-  constructor(message, failureType, coveringElement) {
-    super(message);
-    this.name = "ActionabilityError";
-    this.failureType = failureType;
-    this.coveringElement = coveringElement;
-  }
-};
-var CHECK_VISIBLE = `function() {
-  // checkVisibility handles display:none, visibility:hidden, content-visibility up the tree
-  if (typeof this.checkVisibility === 'function' && !this.checkVisibility()) {
-    return { actionable: false, reason: 'Element is not visible (checkVisibility failed). Try scrolling or check if a prior action is needed to reveal it.' };
-  }
-
-  var style = getComputedStyle(this);
-
-  if (style.visibility !== 'visible') {
-    return { actionable: false, reason: 'Element has visibility: ' + style.visibility + '. Try scrolling or check if a prior action is needed to reveal it.' };
-  }
-
-  // display:contents elements have no box themselves \u2014 check children
-  if (style.display === 'contents') {
-    var children = this.children;
-    if (children.length === 0) {
-      return { actionable: false, reason: 'Element has display:contents with no children. Try scrolling or check if a prior action is needed to reveal it.' };
-    }
-    for (var i = 0; i < children.length; i++) {
-      var childRect = children[i].getBoundingClientRect();
-      if (childRect.width > 0 && childRect.height > 0) {
-        return { actionable: true };
-      }
-    }
-    return { actionable: false, reason: 'Element has display:contents but no visible children. Try scrolling or check if a prior action is needed to reveal it.' };
-  }
-
-  var rect = this.getBoundingClientRect();
-  if (rect.width <= 0 || rect.height <= 0) {
-    return { actionable: false, reason: 'Element has zero size (' + rect.width + 'x' + rect.height + '). Try scrolling or check if a prior action is needed to reveal it.' };
-  }
-
-  return { actionable: true };
-}`;
-var CHECK_ENABLED = `function() {
-  // Native disabled property
-  var disableable = ['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'OPTION', 'OPTGROUP'];
-  if (disableable.indexOf(this.tagName) !== -1 && this.disabled) {
-    return { actionable: false, reason: 'Element is disabled. Check if a prerequisite field needs to be filled first.' };
-  }
-
-  // Check ancestor FIELDSET[disabled]
-  var parent = this.parentElement;
-  while (parent) {
-    if (parent.tagName === 'FIELDSET' && parent.disabled) {
-      // Exception: elements inside the first <legend> of a disabled fieldset are NOT disabled
-      var legend = parent.querySelector(':scope > legend');
-      if (!legend || !legend.contains(this)) {
-        return { actionable: false, reason: 'Element is inside a disabled fieldset. Check if a prerequisite field needs to be filled first.' };
-      }
-    }
-    parent = parent.parentElement;
-  }
-
-  // aria-disabled="true" walking up ancestor chain (crosses shadow DOM)
-  var node = this;
-  while (node) {
-    if (node.nodeType === 1 && node.getAttribute && node.getAttribute('aria-disabled') === 'true') {
-      return { actionable: false, reason: 'Element or ancestor has aria-disabled="true". Check if a prerequisite field needs to be filled first.' };
-    }
-    if (node.parentElement) {
-      node = node.parentElement;
-    } else if (node.getRootNode && node.getRootNode() !== node) {
-      // Cross shadow DOM boundary
-      var root = node.getRootNode();
-      node = root.host || null;
-    } else {
-      break;
-    }
-  }
-
-  return { actionable: true };
-}`;
-var CHECK_STABLE = `function() {
-  var self = this;
-  return new Promise(function(resolve) {
-    var maxFrames = 30;
-    var prev = null;
-    var frame = 0;
-    var resolved = false;
-
-    var fallbackTimer = setTimeout(function() {
-      if (!resolved) {
-        resolved = true;
-        resolve({ actionable: false, reason: 'Element stability check timed out (tab may be backgrounded)' });
-      }
-    }, 2000);
-
-    function check() {
-      if (resolved) return;
-      frame++;
-      if (frame > maxFrames) {
-        resolved = true;
-        clearTimeout(fallbackTimer);
-        resolve({ actionable: false, reason: 'Element position not stable after ' + maxFrames + ' frames' });
-        return;
-      }
-
-      var rect = self.getBoundingClientRect();
-      var cur = { x: rect.x, y: rect.y, w: rect.width, h: rect.height };
-
-      if (prev !== null &&
-          prev.x === cur.x && prev.y === cur.y &&
-          prev.w === cur.w && prev.h === cur.h) {
-        resolved = true;
-        clearTimeout(fallbackTimer);
-        resolve({ actionable: true });
-        return;
-      }
-
-      prev = cur;
-      requestAnimationFrame(check);
-    }
-
-    requestAnimationFrame(check);
-  });
-}`;
-var CHECK_HIT_TARGET = `function(x, y) {
-  // Compute click center if coordinates not provided
-  if (x === undefined || y === undefined) {
-    var rect = this.getBoundingClientRect();
-    x = rect.x + rect.width / 2;
-    y = rect.y + rect.height / 2;
-  }
-
-  function checkPoint(root, px, py) {
-    var method = root.elementsFromPoint || root.msElementsFromPoint;
-    if (!method) return [];
-    return method.call(root, px, py) || [];
-  }
-
-  // Follow only the top-most hit through nested shadow roots.
-  // Accepting any hit in the stack creates false positives for covered elements.
-  var root = document;
-  var topHits = [];
-  var seenRoots = [];
-  while (root && seenRoots.indexOf(root) === -1) {
-    seenRoots.push(root);
-    var hits = checkPoint(root, x, y);
-    if (!hits.length) break;
-    var top = hits[0];
-    topHits.push(top);
-    if (top && top.shadowRoot) {
-      root = top.shadowRoot;
-      continue;
-    }
-    break;
-  }
-
-  // Target must be the top-most hit element or an ancestor/descendant
-  for (var j = 0; j < topHits.length; j++) {
-    var hit = topHits[j];
-    if (hit === this || this.contains(hit) || hit.contains(this)) {
-      return { actionable: true };
-    }
-  }
-
-  // Report the covering element
-  var top = topHits.length > 0 ? topHits[topHits.length - 1] : null;
-  if (top) {
-    return {
-      actionable: false,
-      reason: 'Element is covered by <' + top.tagName.toLowerCase() + '>' +
-        (top.id ? '#' + top.id : '') +
-        (top.className && typeof top.className === 'string' ? '.' + top.className.split(' ').join('.') : '') +
-        '. Try dismissing overlays first.',
-      coveringElement: {
-        tag: top.tagName.toLowerCase(),
-        id: top.id || undefined,
-        className: (typeof top.className === 'string' && top.className) || undefined
-      }
-    };
-  }
-
-  return { actionable: false, reason: 'No element found at click point (' + x + ', ' + y + '). Try scrolling the element into view first.' };
-}`;
-var CHECK_EDITABLE = `function() {
-  // Must be an editable element type
-  var tag = this.tagName;
-  var isEditable = tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' ||
-    this.isContentEditable;
-  if (!isEditable) {
-    return { actionable: false, reason: 'Element is not an editable type (<' + tag.toLowerCase() + '>). Target an <input>, <textarea>, <select>, or [contenteditable] element instead.' };
-  }
-
-  // Check disabled
-  var disableable = ['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'OPTION', 'OPTGROUP'];
-  if (disableable.indexOf(tag) !== -1 && this.disabled) {
-    return { actionable: false, reason: 'Element is disabled. Check if a prerequisite field needs to be filled first.' };
-  }
-
-  // Check ancestor FIELDSET[disabled]
-  var parent = this.parentElement;
-  while (parent) {
-    if (parent.tagName === 'FIELDSET' && parent.disabled) {
-      var legend = parent.querySelector(':scope > legend');
-      if (!legend || !legend.contains(this)) {
-        return { actionable: false, reason: 'Element is inside a disabled fieldset. Check if a prerequisite field needs to be filled first.' };
-      }
-    }
-    parent = parent.parentElement;
-  }
-
-  // aria-disabled walking up (crosses shadow DOM)
-  var node = this;
-  while (node) {
-    if (node.nodeType === 1 && node.getAttribute && node.getAttribute('aria-disabled') === 'true') {
-      return { actionable: false, reason: 'Element or ancestor has aria-disabled="true". Check if a prerequisite field needs to be filled first.' };
-    }
-    if (node.parentElement) {
-      node = node.parentElement;
-    } else if (node.getRootNode && node.getRootNode() !== node) {
-      var root = node.getRootNode();
-      node = root.host || null;
-    } else {
-      break;
-    }
-  }
-
-  // Check readonly
-  if (this.hasAttribute && this.hasAttribute('readonly')) {
-    return { actionable: false, reason: 'Cannot fill a readonly input. Remove the readonly attribute or target a different element.' };
-  }
-  if (this.getAttribute && this.getAttribute('aria-readonly') === 'true') {
-    return { actionable: false, reason: 'Cannot fill a readonly input (aria-readonly="true"). Remove the attribute or target a different element.' };
-  }
-
-  return { actionable: true };
-}`;
-function sleep3(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-var BACKOFF = [0, 20, 100, 100];
-async function runCheck(cdp, objectId, check, options) {
-  let script;
-  let awaitPromise = false;
-  const args = [];
-  switch (check) {
-    case "visible":
-      script = CHECK_VISIBLE;
-      break;
-    case "enabled":
-      script = CHECK_ENABLED;
-      break;
-    case "stable":
-      script = CHECK_STABLE;
-      awaitPromise = true;
-      break;
-    case "hitTarget":
-      script = CHECK_HIT_TARGET;
-      if (options?.coordinates) {
-        args.push({ value: options.coordinates.x });
-        args.push({ value: options.coordinates.y });
-      } else {
-        args.push({ value: void 0 });
-        args.push({ value: void 0 });
-      }
-      break;
-    case "editable":
-      script = CHECK_EDITABLE;
-      break;
-    default: {
-      const _exhaustive = check;
-      throw new Error(`Unknown actionability check: ${_exhaustive}`);
-    }
-  }
-  const params = {
-    functionDeclaration: script,
-    objectId,
-    returnByValue: true,
-    arguments: args
-  };
-  if (awaitPromise) {
-    params["awaitPromise"] = true;
-  }
-  const response = await cdp.send("Runtime.callFunctionOn", params);
-  if (response.exceptionDetails) {
-    return {
-      actionable: false,
-      reason: `Check "${check}" threw: ${response.exceptionDetails.text}`,
-      failureType: check
-    };
-  }
-  const result = response.result.value;
-  if (!result.actionable) {
-    result.failureType = check;
-  }
-  return result;
-}
-async function runChecks(cdp, objectId, checks, options) {
-  for (const check of checks) {
-    const result = await runCheck(cdp, objectId, check, options);
-    if (!result.actionable) {
-      return result;
-    }
-  }
-  return { actionable: true };
-}
-async function ensureActionable(cdp, objectId, checks, options) {
-  const timeout = options?.timeout ?? 3e4;
-  const start = Date.now();
-  let attempt = 0;
-  while (true) {
-    const result = await runChecks(cdp, objectId, checks, options);
-    if (result.actionable) return;
-    if (Date.now() - start >= timeout) {
-      throw new ActionabilityError(
-        `Element not actionable: ${result.reason}`,
-        result.failureType,
-        result.coveringElement
-      );
-    }
-    const delay = attempt < BACKOFF.length ? BACKOFF[attempt] ?? 0 : 500;
-    if (delay > 0) await sleep3(delay);
-    attempt++;
-  }
-}
-
-// src/browser/fuzzy-match.ts
-function jaroWinkler(a, b) {
-  if (a.length === 0 && b.length === 0) return 0;
-  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;
-  }
-  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/keyboard.ts
 var US_KEYBOARD = {
   // Letters (lowercase)
@@ -2420,6 +2204,47 @@ var US_KEYBOARD = {
   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 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 { modifiers, key };
+}
 
 // src/browser/page.ts
 var DEFAULT_TIMEOUT = 3e4;
@@ -2498,6 +2323,8 @@ 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 */
@@ -2553,7 +2380,9 @@ var Page = class {
         }
       }
     });
-    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"),
@@ -2680,6 +2509,9 @@ var Page = class {
           timeout: options.timeout ?? DEFAULT_TIMEOUT
         });
       } catch (e) {
+        if (e instanceof ActionabilityError && e.failureType === "hitTarget" && await this.tryClickAssociatedLabel(objectId)) {
+          return true;
+        }
         if (options.optional) return false;
         throw e;
       }
@@ -2703,14 +2535,24 @@ var Page = class {
         clickY = box.content[1] + box.height / 2;
       }
       const hitTargetCoordinates = this.currentFrame ? void 0 : { x: clickX, y: clickY };
-      try {
-        await ensureActionable(this.cdp, objectId, ["hitTarget"], {
-          timeout: options.timeout ?? DEFAULT_TIMEOUT,
-          coordinates: hitTargetCoordinates
-        });
-      } catch (e) {
-        if (options.optional) return false;
-        throw e;
+      const HIT_TARGET_RETRIES = 3;
+      const HIT_TARGET_DELAY = 100;
+      for (let attempt = 0; attempt < HIT_TARGET_RETRIES; attempt++) {
+        try {
+          await ensureActionable(this.cdp, objectId, ["hitTarget"], {
+            timeout: options.timeout ?? DEFAULT_TIMEOUT,
+            coordinates: hitTargetCoordinates
+          });
+          break;
+        } catch (e) {
+          if (options.optional) return false;
+          if (e instanceof ActionabilityError && e.failureType === "hitTarget" && attempt < HIT_TARGET_RETRIES - 1) {
+            await sleep3(HIT_TARGET_DELAY);
+            await this.cdp.send("DOM.scrollIntoViewIfNeeded", { nodeId: element.nodeId });
+            continue;
+          }
+          throw e;
+        }
       }
       await this.clickElement(element.nodeId);
       return true;
@@ -2820,8 +2662,8 @@ var Page = class {
         if (options.optional) return false;
         throw new ElementNotFoundError(selector);
       }
+      const objectId = await this.resolveObjectId(element.nodeId);
       try {
-        const objectId = await this.resolveObjectId(element.nodeId);
         await ensureActionable(this.cdp, objectId, ["visible", "enabled"], {
           timeout: options.timeout ?? DEFAULT_TIMEOUT
         });
@@ -2870,9 +2712,15 @@ var Page = class {
           await this.cdp.send("Input.insertText", { text: char });
         }
         if (delay > 0) {
-          await sleep4(delay);
+          await sleep3(delay);
         }
       }
+      if (options.blur) {
+        await this.cdp.send("Runtime.callFunctionOn", {
+          objectId,
+          functionDeclaration: "function() { this.blur(); }"
+        });
+      }
       return true;
     });
   }
@@ -2952,8 +2800,12 @@ var Page = class {
     const { trigger, option, value, match = "text" } = config;
     return this.withStaleNodeRetry(async () => {
       await this.click(trigger, options);
-      await sleep4(100);
       const optionSelectors = Array.isArray(option) ? option : [option];
+      await waitForAnyElement(this.cdp, optionSelectors, {
+        state: "visible",
+        timeout: 500,
+        contextId: this.currentFrameContextId ?? void 0
+      }).catch(() => sleep3(100));
       const optionHandle = await this.evaluateInFrame(
         `(() => {
           const selectors = ${JSON.stringify(optionSelectors)};
@@ -3048,7 +2900,12 @@ var Page = class {
         returnByValue: true
       });
       if (!after.result.value) {
-        throw new Error("Clicking the checkbox did not change its state");
+        if (await this.tryToggleViaLabel(object.objectId, true)) {
+          return true;
+        }
+        throw new Error(
+          "Clicking the checkbox did not change its state. Tried the associated label too."
+        );
       }
       return true;
     });
@@ -3100,7 +2957,12 @@ var Page = class {
         returnByValue: true
       });
       if (after.result.value) {
-        throw new Error("Clicking the checkbox did not change its state");
+        if (await this.tryToggleViaLabel(object.objectId, false)) {
+          return true;
+        }
+        throw new Error(
+          "Clicking the checkbox did not change its state. Tried the associated label too."
+        );
       }
       return true;
     });
@@ -3150,8 +3012,11 @@ var Page = class {
           await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_TIMEOUT });
         } else if (shouldWait === "auto") {
           await Promise.race([
-            this.waitForNavigation({ timeout: 1e3, optional: true }),
-            sleep4(500)
+            this.waitForNavigation({ timeout: 2e3, optional: true }).then(
+              () => "navigation"
+            ),
+            this.waitForDOMMutation({ timeout: 1e3 }).then(() => "mutation"),
+            sleep3(1500).then(() => "timeout")
           ]);
         }
         return true;
@@ -3167,10 +3032,11 @@ var Page = class {
           }
         } else if (shouldWait === "auto") {
           const navigationDetected = await Promise.race([
-            this.waitForNavigation({ timeout: 1e3, optional: true }).then(
+            this.waitForNavigation({ timeout: 2e3, optional: true }).then(
               (success) => success ? "nav" : null
             ),
-            sleep4(500).then(() => "timeout")
+            this.waitForDOMMutation({ timeout: 1e3 }).then(() => "mutation"),
+            sleep3(1500).then(() => "timeout")
           ]);
           if (navigationDetected === "nav") {
             return true;
@@ -3184,17 +3050,29 @@ var Page = class {
         if (shouldWait === true) {
           await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_TIMEOUT });
         } else if (shouldWait === "auto") {
-          await sleep4(100);
+          await sleep3(100);
         }
       }
       return true;
     });
   }
   /**
-   * Press a key
+   * Press a key, optionally with modifier keys held down
    */
-  async press(key) {
-    await this.dispatchKey(key);
+  async press(key, options) {
+    const modifiers = options?.modifiers;
+    if (modifiers && modifiers.length > 0) {
+      await this.dispatchKeyWithModifiers(key, modifiers);
+    } else {
+      await this.dispatchKey(key);
+    }
+  }
+  /**
+   * Execute a keyboard shortcut (e.g. "Control+a", "Meta+Shift+z")
+   */
+  async shortcut(combo) {
+    const { modifiers, key } = parseShortcut(combo);
+    await this.dispatchKeyWithModifiers(key, modifiers);
   }
   /**
    * Focus an element
@@ -3223,8 +3101,8 @@ var Page = class {
         throw new ElementNotFoundError(selector, hints);
       }
       await this.scrollIntoView(element.nodeId);
+      const objectId = await this.resolveObjectId(element.nodeId);
       try {
-        const objectId = await this.resolveObjectId(element.nodeId);
         await ensureActionable(this.cdp, objectId, ["visible", "stable"], {
           timeout: options.timeout ?? DEFAULT_TIMEOUT
         });
@@ -3232,13 +3110,28 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
-      const box = await this.getBoxModel(element.nodeId);
-      if (!box) {
-        if (options.optional) return false;
-        throw new Error("Could not get element box model");
+      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,
@@ -3296,15 +3189,19 @@ var Page = class {
     if (descResult.node.frameId) {
       const frameId = descResult.node.frameId;
       const { timeout = DEFAULT_TIMEOUT } = options;
-      const pollInterval = 50;
-      const deadline = Date.now() + timeout;
       let contextId = this.frameExecutionContexts.get(frameId);
-      while (!contextId && Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
-        contextId = this.frameExecutionContexts.get(frameId);
+      if (!contextId) {
+        contextId = await this.waitForFrameContext(frameId, Math.min(timeout, 2e3));
       }
       if (contextId) {
         this.currentFrameContextId = contextId;
+        this.brokenFrame = null;
+      } else {
+        const frameKey2 = Array.isArray(selector) ? selector[0] : selector;
+        this.brokenFrame = frameKey2;
+        console.warn(
+          `[browser-pilot] Frame "${frameKey2}" execution context unavailable. JS evaluation will fail in this frame. DOM operations may still work.`
+        );
       }
     }
     this.refMap.clear();
@@ -3317,6 +3214,7 @@ var Page = class {
     this.currentFrame = null;
     this.rootNodeId = null;
     this.currentFrameContextId = null;
+    this.brokenFrame = null;
     this.refMap.clear();
   }
   /**
@@ -3388,7 +3286,7 @@ var Page = class {
     }
     const result = await this.cdp.send("Runtime.evaluate", params);
     if (result.exceptionDetails) {
-      throw new Error(`Evaluation failed: ${result.exceptionDetails.text}`);
+      throw new Error(this.formatEvaluationError(result.exceptionDetails));
     }
     return result.result.value;
   }
@@ -3440,6 +3338,75 @@ var Page = class {
       return result.result.value ?? "";
     });
   }
+  /**
+   * Enumerate form controls on the page with labels and current state.
+   */
+  async forms() {
+    const result = await this.evaluateInFrame(
+      `(() => {
+        function normalize(value) {
+          return String(value == null ? '' : value).replace(/\\s+/g, ' ').trim();
+        }
+
+        function labelFor(el) {
+          if (!el) return '';
+          if (el.labels && el.labels.length) {
+            return normalize(
+              Array.from(el.labels)
+                .map((label) => label.innerText || label.textContent || '')
+                .join(' ')
+            );
+          }
+          var ariaLabel = normalize(el.getAttribute && el.getAttribute('aria-label'));
+          if (ariaLabel) return ariaLabel;
+          if (el.id) {
+            var byFor = document.querySelector('label[for="' + el.id.replace(/"/g, '\\\\"') + '"]');
+            if (byFor) return normalize(byFor.innerText || byFor.textContent || '');
+          }
+          var closest = el.closest && el.closest('label');
+          if (closest) return normalize(closest.innerText || closest.textContent || '');
+          return '';
+        }
+
+        return Array.from(document.querySelectorAll('input, select, textarea')).map((el) => {
+          var tag = el.tagName.toLowerCase();
+          var type = tag === 'input' ? (el.type || 'text').toLowerCase() : tag;
+          var value = null;
+
+          if (tag === 'select') {
+            value = el.multiple
+              ? Array.from(el.selectedOptions).map((opt) => opt.value)
+              : el.value || null;
+          } else if (tag === 'textarea' || tag === 'input') {
+            value = typeof el.value === 'string' ? el.value : null;
+          }
+
+          return {
+            tag: tag,
+            type: type,
+            id: el.id || undefined,
+            name: el.getAttribute('name') || undefined,
+            value: value,
+            checked: 'checked' in el ? !!el.checked : undefined,
+            required: !!el.required,
+            disabled: !!el.disabled,
+            label: labelFor(el) || undefined,
+            placeholder: normalize(el.getAttribute && el.getAttribute('placeholder')) || undefined,
+            options:
+              tag === 'select'
+                ? Array.from(el.options).map((opt) => ({
+                    value: opt.value || '',
+                    text: normalize(opt.text || opt.label || ''),
+                    selected: !!opt.selected,
+                    disabled: !!opt.disabled,
+                  }))
+                : undefined,
+          };
+        });
+      })()`
+    );
+    return result.result.value ?? [];
+  }
   // ============ File Handling ============
   /**
    * Set files on a file input
@@ -3786,11 +3753,22 @@ var Page = class {
 
           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 phase = currentTarget === target ? 2 : capture ? 1 : 3;
             var event = createEvent(type, target, currentTarget, path, phase);
 
             for (var j = 0; j < entries.length; j++) {
@@ -3901,7 +3879,8 @@ var Page = class {
   /**
    * Get an accessibility tree snapshot of the page
    */
-  async snapshot() {
+  async snapshot(options = {}) {
+    const roleFilter = new Set((options.roles ?? []).map((role) => role.trim().toLowerCase()));
     const [url, title, axTree] = await Promise.all([
       this.url(),
       this.title(),
@@ -3922,7 +3901,7 @@ var Page = class {
     const buildNode = (nodeId) => {
       const node = nodeMap.get(nodeId);
       if (!node) return null;
-      const role = node.role?.value ?? "generic";
+      const role = (node.role?.value ?? "generic").toLowerCase();
       const name = node.name?.value;
       const value = node.value?.value;
       const ref = nodeRefs.get(nodeId);
@@ -3938,7 +3917,7 @@ var Page = class {
       return {
         role,
         name,
-        value,
+        value: value !== void 0 ? String(value) : void 0,
         ref,
         children: children.length > 0 ? children : void 0,
         disabled,
@@ -3946,7 +3925,24 @@ var Page = class {
       };
     };
     const rootNodes = nodes.filter((n) => !n.parentId || !nodeMap.has(n.parentId));
-    const accessibilityTree = rootNodes.map((n) => buildNode(n.nodeId)).filter((n) => n !== null);
+    let accessibilityTree = rootNodes.map((n) => buildNode(n.nodeId)).filter((n) => n !== null);
+    if (roleFilter.size > 0) {
+      const filteredAccessibilityTree = [];
+      for (const node of nodes) {
+        if (!roleFilter.has((node.role?.value ?? "generic").toLowerCase())) {
+          continue;
+        }
+        const snapshotNode = buildNode(node.nodeId);
+        if (!snapshotNode) {
+          continue;
+        }
+        filteredAccessibilityTree.push({
+          ...snapshotNode,
+          children: void 0
+        });
+      }
+      accessibilityTree = filteredAccessibilityTree;
+    }
     const interactiveRoles = /* @__PURE__ */ new Set([
       "button",
       "link",
@@ -3968,37 +3964,44 @@ var Page = class {
     ]);
     const interactiveElements = [];
     for (const node of nodes) {
-      const role = node.role?.value;
-      if (role && interactiveRoles.has(role)) {
+      const role = (node.role?.value ?? "").toLowerCase();
+      if (role && interactiveRoles.has(role) && (roleFilter.size === 0 || roleFilter.has(role))) {
         const ref = nodeRefs.get(node.nodeId);
         const name = node.name?.value ?? "";
         const disabled = node.properties?.find((p) => p.name === "disabled")?.value.value;
+        const checked = node.properties?.find((p) => p.name === "checked")?.value.value;
+        const value = node.value?.value;
         const selector = node.backendDOMNodeId ? `[data-backend-node-id="${node.backendDOMNodeId}"]` : `[aria-label="${name}"]`;
         interactiveElements.push({
           ref,
           role,
           name,
           selector,
-          disabled
+          disabled,
+          checked,
+          value: value !== void 0 ? String(value) : void 0
         });
       }
     }
+    const formatNode = (node, depth = 0) => {
+      let line = `${"  ".repeat(depth)}- ${node.role}`;
+      if (node.name) line += ` "${node.name}"`;
+      line += ` ref:${node.ref}`;
+      if (node.disabled) line += " (disabled)";
+      if (node.checked !== void 0) line += node.checked ? " (checked)" : " (unchecked)";
+      return line;
+    };
     const formatTree = (nodes2, depth = 0) => {
       const lines = [];
       for (const node of nodes2) {
-        let line = `${"  ".repeat(depth)}- ${node.role}`;
-        if (node.name) line += ` "${node.name}"`;
-        line += ` [ref=${node.ref}]`;
-        if (node.disabled) line += " (disabled)";
-        if (node.checked !== void 0) line += node.checked ? " (checked)" : " (unchecked)";
-        lines.push(line);
+        lines.push(formatNode(node, depth));
         if (node.children) {
           lines.push(formatTree(node.children, depth + 1));
         }
       }
       return lines.join("\n");
     };
-    const text = formatTree(accessibilityTree);
+    const text = roleFilter.size > 0 ? accessibilityTree.map((node) => formatNode(node)).join("\n") : formatTree(accessibilityTree);
     const result = {
       url,
       title,
@@ -4007,7 +4010,9 @@ var Page = class {
       interactiveElements,
       text
     };
-    this.lastSnapshot = result;
+    if (roleFilter.size === 0) {
+      this.lastSnapshot = result;
+    }
     return result;
   }
   /**
@@ -4422,8 +4427,15 @@ var Page = class {
       }
     };
     if (this.dialogHandler) {
+      const DIALOG_TIMEOUT = 5e3;
       try {
-        await this.dialogHandler(dialog);
+        await Promise.race([
+          this.dialogHandler(dialog),
+          sleep3(DIALOG_TIMEOUT).then(() => {
+            console.warn("[browser-pilot] Dialog handler timed out after 5s, auto-dismissing");
+            return dialog.dismiss();
+          })
+        ]);
       } catch (e) {
         console.error("[Dialog handler error]", e);
         await dialog.dismiss();
@@ -4503,6 +4515,7 @@ var Page = class {
     this.refMap.clear();
     this.currentFrame = null;
     this.currentFrameContextId = null;
+    this.brokenFrame = null;
     this.frameContexts.clear();
     this.dialogHandler = null;
     try {
@@ -4543,7 +4556,7 @@ var Page = class {
           if (attempt < retries) {
             this.rootNodeId = null;
             this.currentFrameContextId = null;
-            await sleep4(delay);
+            await sleep3(delay);
             continue;
           }
         }
@@ -4554,7 +4567,7 @@ var Page = class {
   }
   /**
    * Find an element using single or multiple selectors
-   * Supports ref: prefix for ref-based selectors (e.g., "ref:e4")
+   * Supports ref:, text:, and role: selectors.
    */
   async findElement(selectors, options = {}) {
     const { timeout = DEFAULT_TIMEOUT } = options;
@@ -4621,11 +4634,11 @@ var Page = class {
         }
       }
     }
-    const cssSelectors = selectorList.filter((s) => !s.startsWith("ref:"));
-    if (cssSelectors.length === 0) {
+    const runtimeSelectors = selectorList.filter((s) => !s.startsWith("ref:"));
+    if (runtimeSelectors.length === 0) {
       return null;
     }
-    const result = await waitForAnyElement(this.cdp, cssSelectors, {
+    const result = await waitForAnyElement(this.cdp, runtimeSelectors, {
       state: "visible",
       timeout,
       contextId: this.currentFrameContextId ?? void 0
@@ -4633,6 +4646,14 @@ var Page = class {
     if (!result.success || !result.selector) {
       return null;
     }
+    const specialSelectorMatch = await this.resolveSpecialSelector(result.selector);
+    if (specialSelectorMatch) {
+      this._lastMatchedSelector = result.selector;
+      return {
+        ...specialSelectorMatch,
+        waitedMs: result.waitedMs
+      };
+    }
     await this.ensureRootNode();
     const queryResult = await this.cdp.send("DOM.querySelector", {
       nodeId: this.rootNodeId,
@@ -4679,6 +4700,122 @@ var Page = class {
       waitedMs: result.waitedMs
     };
   }
+  formatEvaluationError(details) {
+    const description = typeof details.exception?.description === "string" && details.exception.description || typeof details.exception?.value === "string" && details.exception.value || details.text || "Uncaught";
+    return `Evaluation failed: ${description}`;
+  }
+  async resolveSpecialSelector(selector, options = {}) {
+    const expression = buildSpecialSelectorLookupExpression(selector, options);
+    if (!expression) return null;
+    const result = await this.evaluateInFrame(expression, {
+      returnByValue: false
+    });
+    if (!result.result.objectId) {
+      return null;
+    }
+    const resolved = await this.objectIdToNode(result.result.objectId);
+    if (!resolved) {
+      return null;
+    }
+    return {
+      nodeId: resolved.nodeId,
+      backendNodeId: resolved.backendNodeId,
+      selector,
+      waitedMs: 0
+    };
+  }
+  async readCheckedState(objectId) {
+    const result = await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: "function() { return !!this.checked; }",
+      returnByValue: true
+    });
+    return result.result.value === true;
+  }
+  async readInputType(objectId) {
+    const result = await this.cdp.send(
+      "Runtime.callFunctionOn",
+      {
+        objectId,
+        functionDeclaration: 'function() { return this instanceof HTMLInputElement ? String(this.type || "").toLowerCase() : null; }',
+        returnByValue: true
+      }
+    );
+    return result.result.value ?? null;
+  }
+  async getAssociatedLabelNodeId(objectId) {
+    const result = await this.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function() {
+        if (!(this instanceof HTMLInputElement)) return null;
+
+        if (this.id) {
+          var labels = Array.from(document.querySelectorAll('label'));
+          for (var i = 0; i < labels.length; i++) {
+            if (labels[i].htmlFor === this.id) return labels[i];
+          }
+        }
+
+        return this.closest('label');
+      }`,
+      returnByValue: false
+    });
+    if (!result.result.objectId) {
+      return null;
+    }
+    return (await this.objectIdToNode(result.result.objectId))?.nodeId ?? null;
+  }
+  async objectIdToNode(objectId) {
+    const describeResult = await this.cdp.send("DOM.describeNode", {
+      objectId,
+      depth: 0
+    });
+    const backendNodeId = describeResult.node.backendNodeId;
+    if (!backendNodeId) {
+      return null;
+    }
+    if (describeResult.node.nodeId) {
+      return {
+        nodeId: describeResult.node.nodeId,
+        backendNodeId
+      };
+    }
+    await this.ensureRootNode();
+    const pushResult = await this.cdp.send(
+      "DOM.pushNodesByBackendIdsToFrontend",
+      {
+        backendNodeIds: [backendNodeId]
+      }
+    );
+    const nodeId = pushResult.nodeIds?.[0];
+    if (!nodeId) {
+      return null;
+    }
+    return { nodeId, backendNodeId };
+  }
+  async tryClickAssociatedLabel(objectId) {
+    const inputType = await this.readInputType(objectId);
+    if (inputType !== "checkbox" && inputType !== "radio") {
+      return false;
+    }
+    const labelNodeId = await this.getAssociatedLabelNodeId(objectId);
+    if (!labelNodeId) {
+      return false;
+    }
+    try {
+      await this.scrollIntoView(labelNodeId);
+      await this.clickElement(labelNodeId);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async tryToggleViaLabel(objectId, desiredChecked) {
+    if (!await this.tryClickAssociatedLabel(objectId)) {
+      return false;
+    }
+    return await this.readCheckedState(objectId) === desiredChecked;
+  }
   /**
    * Ensure we have a valid root node ID
    */
@@ -4702,11 +4839,7 @@ var Page = class {
           if (frameResult.node.frameId) {
             let contextId = this.frameExecutionContexts.get(frameResult.node.frameId);
             if (!contextId) {
-              for (let i = 0; i < 10; i++) {
-                await sleep4(100);
-                contextId = this.frameExecutionContexts.get(frameResult.node.frameId);
-                if (contextId) break;
-              }
+              contextId = await this.waitForFrameContext(frameResult.node.frameId, 1e3);
             }
             this.currentFrameContextId = contextId ?? null;
           }
@@ -4726,6 +4859,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,
@@ -4737,10 +4875,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)
@@ -4828,13 +4999,13 @@ var Page = class {
     });
     return object.objectId;
   }
-  async dispatchKeyDefinition(def) {
+  async dispatchKeyDefinition(def, modifierBitmask = 0) {
     const downParams = {
       type: def.text !== void 0 ? "keyDown" : "rawKeyDown",
       key: def.key,
       code: def.code,
       windowsVirtualKeyCode: def.keyCode,
-      modifiers: 0,
+      modifiers: modifierBitmask,
       autoRepeat: false,
       location: def.location ?? 0,
       isKeypad: false
@@ -4849,7 +5020,7 @@ var Page = class {
       key: def.key,
       code: def.code,
       windowsVirtualKeyCode: def.keyCode,
-      modifiers: 0,
+      modifiers: modifierBitmask,
       location: def.location ?? 0
     });
   }
@@ -4859,12 +5030,44 @@ var Page = class {
       await this.dispatchKeyDefinition(def);
       return;
     }
-    if ([...key].length === 1) {
+    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).
@@ -4937,7 +5140,7 @@ var Page = class {
     const start = Date.now();
     await this.audioOutput.start();
     if (options.preDelay && options.preDelay > 0) {
-      await sleep4(options.preDelay);
+      await sleep3(options.preDelay);
     }
     const inputDone = this.audioInput.play(options.input, {
       waitForEnd: !!options.sendSelector
@@ -4964,8 +5167,48 @@ 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 sleep4(ms) {
+function sleep3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
@@ -4990,6 +5233,7 @@ var Browser = class _Browser {
   cdp;
   providerSession;
   pages = /* @__PURE__ */ new Map();
+  pageCounter = 0;
   constructor(cdp, _provider, providerSession, _options) {
     this.cdp = cdp;
     this.providerSession = providerSession;
@@ -5019,7 +5263,11 @@ var Browser = class _Browser {
     const pageName = name ?? "default";
     const cached = this.pages.get(pageName);
     if (cached) return cached;
-    const targets = await this.cdp.send("Target.getTargets");
+    const targets = await this.cdp.send(
+      "Target.getTargets",
+      void 0,
+      null
+    );
     let pageTargets = targets.targetInfos.filter((t) => t.type === "page");
     if (options?.targetUrl) {
       const urlFilter = options.targetUrl;
@@ -5041,16 +5289,24 @@ var Browser = class _Browser {
         targetId = options.targetId;
       } else {
         console.warn(`[browser-pilot] Target ${options.targetId} no longer exists, falling back`);
-        targetId = pickBestTarget(pageTargets) ?? (await this.cdp.send("Target.createTarget", {
-          url: "about:blank"
-        })).targetId;
+        targetId = pickBestTarget(pageTargets) ?? (await this.cdp.send(
+          "Target.createTarget",
+          {
+            url: "about:blank"
+          },
+          null
+        )).targetId;
       }
     } else if (pageTargets.length > 0) {
       targetId = pickBestTarget(pageTargets);
     } else {
-      const result = await this.cdp.send("Target.createTarget", {
-        url: "about:blank"
-      });
+      const result = await this.cdp.send(
+        "Target.createTarget",
+        {
+          url: "about:blank"
+        },
+        null
+      );
       targetId = result.targetId;
     }
     await this.cdp.attachToTarget(targetId);
@@ -5078,13 +5334,17 @@ var Browser = class _Browser {
    * Create a new page (tab)
    */
   async newPage(url = "about:blank") {
-    const result = await this.cdp.send("Target.createTarget", {
-      url
-    });
+    const result = await this.cdp.send(
+      "Target.createTarget",
+      {
+        url
+      },
+      null
+    );
     await this.cdp.attachToTarget(result.targetId);
     const page = new Page(this.cdp, result.targetId);
     await page.init();
-    const name = `page-${this.pages.size + 1}`;
+    const name = `page-${++this.pageCounter}`;
     this.pages.set(name, page);
     return page;
   }
@@ -5094,14 +5354,30 @@ var Browser = class _Browser {
   async closePage(name) {
     const page = this.pages.get(name);
     if (!page) return;
-    const targets = await this.cdp.send("Target.getTargets");
-    const pageTargets = targets.targetInfos.filter((t) => t.type === "page");
-    if (pageTargets.length > 0) {
-      await this.cdp.send("Target.closeTarget", {
-        targetId: pageTargets[0].targetId
-      });
-    }
+    const targetId = page.targetId;
+    await this.cdp.send("Target.closeTarget", { targetId }, null);
     this.pages.delete(name);
+    const deadline = Date.now() + 5e3;
+    while (Date.now() < deadline) {
+      const { targetInfos } = await this.cdp.send(
+        "Target.getTargets",
+        void 0,
+        null
+      );
+      if (!targetInfos.some((t) => t.targetId === targetId)) return;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+  /**
+   * List all page targets in the connected browser.
+   */
+  async listTargets() {
+    const { targetInfos } = await this.cdp.send(
+      "Target.getTargets",
+      void 0,
+      null
+    );
+    return targetInfos.filter((target) => target.type === "page");
   }
   /**
    * Get the WebSocket URL for this browser connection