browser-pilot 0.0.12 → 0.0.14

package/dist/{chunk-RUWAXHDX.mjs → chunk-IN5HPAPB.mjs}

@@ -1,6 +1,7 @@
 import {
-  createCDPClient
-} from "./chunk-4MBSALQL.mjs";
+  createCDPClient,
+  stringifyUnknown
+} from "./chunk-KIFB526Y.mjs";
 import {
   createProvider
 } from "./chunk-BRAFQUMG.mjs";
@@ -11,7 +12,7 @@ import {
   TimeoutError,
   ensureActionable,
   generateHints
-} from "./chunk-NLIARNEE.mjs";
+} from "./chunk-XMJABKCF.mjs";
 
 // src/audio/encoding.ts
 function bufferToBase64(data) {
@@ -1507,6 +1508,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) {
@@ -1540,18 +1820,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) {
@@ -1561,11 +1842,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) {
@@ -2044,6 +2328,9 @@ var Page = class {
   brokenFrame = null;
   /** Last matched selector from findElement (for selectorUsed tracking) */
   _lastMatchedSelector;
+  _lastActionCoordinates = null;
+  _lastActionBoundingBox = null;
+  _lastActionTargetMetadata = null;
   /** Last snapshot for stale ref recovery */
   lastSnapshot;
   /** Audio input controller (lazy-initialized) */
@@ -2075,6 +2362,76 @@ var Page = class {
   getLastMatchedSelector() {
     return this._lastMatchedSelector;
   }
+  async getActionTargetMetadata(identifiers) {
+    try {
+      const objectId = identifiers.objectId ?? (identifiers.nodeId ? await this.resolveObjectId(identifiers.nodeId) : void 0);
+      if (!objectId) return null;
+      const response = await this.cdp.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function() {
+          const tagName = this.tagName?.toLowerCase?.() || '';
+          const inputType =
+            tagName === 'input' && typeof this.type === 'string' ? this.type.toLowerCase() : '';
+          const autocomplete =
+            typeof this.autocomplete === 'string' ? this.autocomplete.toLowerCase() : '';
+          return { tagName, inputType, autocomplete };
+        }`,
+        returnByValue: true
+      });
+      return response.result.value ?? null;
+    } catch {
+      return null;
+    }
+  }
+  async getElementPosition(identifiers) {
+    try {
+      const { quads } = await this.cdp.send(
+        "DOM.getContentQuads",
+        identifiers
+      );
+      if (quads?.length > 0) {
+        const q = quads[0];
+        const minX = Math.min(q[0], q[2], q[4], q[6]);
+        const maxX = Math.max(q[0], q[2], q[4], q[6]);
+        const minY = Math.min(q[1], q[3], q[5], q[7]);
+        const maxY = Math.max(q[1], q[3], q[5], q[7]);
+        return {
+          center: { x: (minX + maxX) / 2, y: (minY + maxY) / 2 },
+          bbox: { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+        };
+      }
+    } catch {
+    }
+    if (identifiers.nodeId) {
+      const box = await this.getBoxModel(identifiers.nodeId);
+      if (box) {
+        return {
+          center: { x: box.content[0] + box.width / 2, y: box.content[1] + box.height / 2 },
+          bbox: { x: box.content[0], y: box.content[1], width: box.width, height: box.height }
+        };
+      }
+    }
+    return null;
+  }
+  setLastActionPosition(coords, bbox) {
+    this._lastActionCoordinates = coords;
+    this._lastActionBoundingBox = bbox;
+  }
+  getLastActionCoordinates() {
+    return this._lastActionCoordinates;
+  }
+  getLastActionBoundingBox() {
+    return this._lastActionBoundingBox;
+  }
+  getLastActionTargetMetadata() {
+    return this._lastActionTargetMetadata;
+  }
+  /** Reset position tracking (call before each executor step) */
+  resetLastActionPosition() {
+    this._lastActionCoordinates = null;
+    this._lastActionBoundingBox = null;
+    this._lastActionTargetMetadata = null;
+  }
   /**
    * Initialize the page (enable required CDP domains)
    */
@@ -2226,6 +2583,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;
       }
@@ -2239,6 +2599,14 @@ var Page = class {
           const quad = quads[0];
           clickX = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
           clickY = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+          const minX = Math.min(quad[0], quad[2], quad[4], quad[6]);
+          const maxX = Math.max(quad[0], quad[2], quad[4], quad[6]);
+          const minY = Math.min(quad[1], quad[3], quad[5], quad[7]);
+          const maxY = Math.max(quad[1], quad[3], quad[5], quad[7]);
+          this.setLastActionPosition(
+            { x: clickX, y: clickY },
+            { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+          );
         } else {
           throw new Error("No quads");
         }
@@ -2247,6 +2615,10 @@ var Page = class {
         if (!box) throw new Error("Could not get element position");
         clickX = box.content[0] + box.width / 2;
         clickY = box.content[1] + box.height / 2;
+        this.setLastActionPosition(
+          { x: clickX, y: clickY },
+          { x: box.content[0], y: box.content[1], width: box.width, height: box.height }
+        );
       }
       const hitTargetCoordinates = this.currentFrame ? void 0 : { x: clickX, y: clickY };
       const HIT_TARGET_RETRIES = 3;
@@ -2297,13 +2669,20 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const fillPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (fillPos) this.setLastActionPosition(fillPos.center, fillPos.bbox);
       const tagInfo = await this.cdp.send("Runtime.callFunctionOn", {
         objectId,
         functionDeclaration: `function() {
-            return { tagName: this.tagName?.toLowerCase() || '', inputType: (this.type || '').toLowerCase() };
+            return {
+              tagName: this.tagName?.toLowerCase() || '',
+              inputType: (this.type || '').toLowerCase(),
+              autocomplete: typeof this.autocomplete === 'string' ? this.autocomplete.toLowerCase() : '',
+            };
           }`,
         returnByValue: true
       });
+      this._lastActionTargetMetadata = tagInfo.result.value;
       const { tagName, inputType } = tagInfo.result.value;
       const specialInputTypes = /* @__PURE__ */ new Set([
         "date",
@@ -2385,6 +2764,9 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const typePos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (typePos) this.setLastActionPosition(typePos.center, typePos.bbox);
+      this._lastActionTargetMetadata = await this.getActionTargetMetadata({ objectId });
       await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
       for (const char of text) {
         const def = US_KEYBOARD[char];
@@ -2464,6 +2846,9 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const selectPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (selectPos) this.setLastActionPosition(selectPos.center, selectPos.bbox);
+      this._lastActionTargetMetadata = await this.getActionTargetMetadata({ objectId });
       const metadata = await this.getNativeSelectMetadata(objectId, values);
       if (!metadata.isSelect) {
         throw new Error("select() target must be a native <select> element");
@@ -2600,6 +2985,8 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const checkPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (checkPos) this.setLastActionPosition(checkPos.center, checkPos.bbox);
       const before = await this.cdp.send("Runtime.callFunctionOn", {
         objectId: object.objectId,
         functionDeclaration: "function() { return !!this.checked; }",
@@ -2614,7 +3001,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;
     });
@@ -2643,6 +3035,8 @@ var Page = class {
         if (options.optional) return false;
         throw e;
       }
+      const uncheckPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (uncheckPos) this.setLastActionPosition(uncheckPos.center, uncheckPos.bbox);
       const isRadio = await this.cdp.send(
         "Runtime.callFunctionOn",
         {
@@ -2666,7 +3060,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;
     });
@@ -2693,6 +3092,8 @@ var Page = class {
         throw new ElementNotFoundError(selector, hints);
       }
       const objectId = await this.resolveObjectId(element.nodeId);
+      const submitPos = await this.getElementPosition({ nodeId: element.nodeId });
+      if (submitPos) this.setLastActionPosition(submitPos.center, submitPos.bbox);
       const isFormElement = await this.cdp.send(
         "Runtime.callFunctionOn",
         {
@@ -2789,6 +3190,8 @@ var Page = class {
       const hints = await generateHints(this, selectorList, "focus");
       throw new ElementNotFoundError(selector, hints);
     }
+    const focusPos = await this.getElementPosition({ nodeId: element.nodeId });
+    if (focusPos) this.setLastActionPosition(focusPos.center, focusPos.bbox);
     await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
     return true;
   }
@@ -2824,6 +3227,14 @@ var Page = class {
           const quad = quads[0];
           x = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
           y = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+          const minX = Math.min(quad[0], quad[2], quad[4], quad[6]);
+          const maxX = Math.max(quad[0], quad[2], quad[4], quad[6]);
+          const minY = Math.min(quad[1], quad[3], quad[5], quad[7]);
+          const maxY = Math.max(quad[1], quad[3], quad[5], quad[7]);
+          this.setLastActionPosition(
+            { x, y },
+            { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+          );
         } else {
           throw new Error("No quads");
         }
@@ -2835,6 +3246,10 @@ var Page = class {
         }
         x = box.content[0] + box.width / 2;
         y = box.content[1] + box.height / 2;
+        this.setLastActionPosition(
+          { x, y },
+          { x: box.content[0], y: box.content[1], width: box.width, height: box.height }
+        );
       }
       await this.cdp.send("Input.dispatchMouseEvent", {
         type: "mouseMoved",
@@ -2860,6 +3275,8 @@ var Page = class {
       if (options.optional) return false;
       throw new ElementNotFoundError(selector);
     }
+    const scrollPos = await this.getElementPosition({ nodeId: element.nodeId });
+    if (scrollPos) this.setLastActionPosition(scrollPos.center, scrollPos.bbox);
     await this.scrollIntoView(element.nodeId);
     return true;
   }
@@ -2990,7 +3407,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;
   }
@@ -3042,6 +3459,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
@@ -3514,7 +4000,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(),
@@ -3535,7 +4022,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);
@@ -3551,7 +4038,7 @@ var Page = class {
       return {
         role,
         name,
-        value,
+        value: value !== void 0 ? stringifyUnknown(value) : void 0,
         ref,
         children: children.length > 0 ? children : void 0,
         disabled,
@@ -3559,7 +4046,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",
@@ -3581,37 +4085,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 ? stringifyUnknown(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,
@@ -3620,7 +4131,9 @@ var Page = class {
       interactiveElements,
       text
     };
-    this.lastSnapshot = result;
+    if (roleFilter.size === 0) {
+      this.lastSnapshot = result;
+    }
     return result;
   }
   /**
@@ -4057,7 +4570,7 @@ var Page = class {
    */
   formatConsoleArgs(args) {
     return args.map((arg) => {
-      if (arg.value !== void 0) return String(arg.value);
+      if (arg.value !== void 0) return stringifyUnknown(arg.value);
       if (arg.description) return arg.description;
       return "[object]";
     }).join(" ");
@@ -4175,7 +4688,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;
@@ -4242,11 +4755,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
@@ -4254,6 +4767,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,
@@ -4300,6 +4821,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
    */
@@ -4717,10 +5354,30 @@ var Browser = class _Browser {
   cdp;
   providerSession;
   pages = /* @__PURE__ */ new Map();
+  pageCounter = 0;
   constructor(cdp, _provider, providerSession, _options) {
     this.cdp = cdp;
     this.providerSession = providerSession;
   }
+  /**
+   * Create a Browser from an existing CDPClient (used by daemon fast-path).
+   * The caller is responsible for the CDP connection lifecycle.
+   */
+  static fromCDP(cdp, sessionInfo) {
+    const providerSession = {
+      wsUrl: sessionInfo.wsUrl,
+      sessionId: sessionInfo.sessionId,
+      async close() {
+      }
+    };
+    const provider = {
+      name: sessionInfo.provider ?? "daemon",
+      async createSession() {
+        return providerSession;
+      }
+    };
+    return new _Browser(cdp, provider, providerSession, { provider: "generic" });
+  }
   /**
    * Connect to a browser instance
    */
@@ -4746,7 +5403,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;
@@ -4768,16 +5429,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);
@@ -4805,13 +5474,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;
   }
@@ -4821,14 +5494,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