browser-pilot 0.0.12 → 0.0.13

package/dist/index.cjs

@@ -998,6 +998,9 @@ var BatchExecutor = class {
         const snapshot = await this.page.snapshot();
         return { value: snapshot };
       }
+      case "forms": {
+        return { value: await this.page.forms() };
+      }
       case "screenshot": {
         const data = await this.page.screenshot({
           format: step.format,
@@ -1017,6 +1020,21 @@ var BatchExecutor = class {
         const text = await this.page.text(selector);
         return { text, selectorUsed: selector };
       }
+      case "newTab": {
+        const { targetId } = await this.page.cdpClient.send(
+          "Target.createTarget",
+          {
+            url: step.url ?? "about:blank"
+          },
+          null
+        );
+        return { value: { targetId } };
+      }
+      case "closeTab": {
+        const targetId = step.targetId ?? this.page.targetId;
+        await this.page.cdpClient.send("Target.closeTarget", { targetId }, null);
+        return { value: { targetId, closedCurrent: targetId === this.page.targetId } };
+      }
       case "switchFrame": {
         if (!step.selector) throw new Error("switchFrame requires selector");
         await this.page.switchToFrame(step.selector, { timeout, optional });
@@ -1131,10 +1149,15 @@ var BatchExecutor = class {
           snap: "snapshot",
           accessibility: "snapshot",
           a11y: "snapshot",
+          formslist: "forms",
           image: "screenshot",
           pic: "screenshot",
           frame: "switchFrame",
           iframe: "switchFrame",
+          newtab: "newTab",
+          opentab: "newTab",
+          createtab: "newTab",
+          closetab: "closeTab",
           assert_visible: "assertVisible",
           assert_exists: "assertExists",
           assert_text: "assertText",
@@ -1148,7 +1171,7 @@ var BatchExecutor = class {
         };
         const suggestion = aliases[action.toLowerCase()];
         const hint = suggestion ? ` Did you mean "${suggestion}"?` : "";
-        const valid = "goto, click, fill, type, select, check, uncheck, submit, press, shortcut, focus, hover, scroll, wait, snapshot, screenshot, evaluate, text, switchFrame, switchToMain, assertVisible, assertExists, assertText, assertUrl, assertValue";
+        const valid = "goto, click, fill, type, select, check, uncheck, submit, press, shortcut, focus, hover, scroll, wait, snapshot, forms, screenshot, evaluate, text, newTab, closeTab, switchFrame, switchToMain, assertVisible, assertExists, assertText, assertUrl, assertValue";
         throw new Error(`Unknown action "${action}".${hint}
 
 Valid actions: ${valid}`);
@@ -1219,6 +1242,11 @@ var ACTION_ALIASES = {
   pic: "screenshot",
   frame: "switchFrame",
   iframe: "switchFrame",
+  formslist: "forms",
+  newtab: "newTab",
+  opentab: "newTab",
+  createtab: "newTab",
+  closetab: "closeTab",
   assert_visible: "assertVisible",
   assert_exists: "assertExists",
   assert_text: "assertText",
@@ -1255,7 +1283,8 @@ var PROPERTY_ALIASES = {
   button: "key",
   address: "url",
   page: "url",
-  path: "url"
+  path: "url",
+  tabId: "targetId"
 };
 var ACTION_RULES = {
   goto: {
@@ -1356,6 +1385,10 @@ var ACTION_RULES = {
       fullPage: { type: "boolean" }
     }
   },
+  forms: {
+    required: {},
+    optional: {}
+  },
   evaluate: {
     required: { value: { type: "string" } },
     optional: {}
@@ -1370,6 +1403,18 @@ var ACTION_RULES = {
     required: { selector: { type: "string|string[]" } },
     optional: {}
   },
+  newTab: {
+    required: {},
+    optional: {
+      url: { type: "string" }
+    }
+  },
+  closeTab: {
+    required: {},
+    optional: {
+      targetId: { type: "string" }
+    }
+  },
   switchToMain: {
     required: {},
     optional: {}
@@ -1412,6 +1457,7 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "selector",
   "url",
   "value",
+  "targetId",
   "key",
   "combo",
   "modifiers",
@@ -1566,15 +1612,22 @@ function validateSteps(steps) {
     const rule = ACTION_RULES[action];
     for (const key of Object.keys(obj)) {
       if (key === "action") continue;
-      if (!KNOWN_STEP_FIELDS.has(key)) {
-        const suggestion = suggestProperty(key);
-        errors.push({
-          stepIndex: i,
-          field: key,
-          message: suggestion ? `unknown property "${key}". Did you mean "${suggestion}"?` : `unknown property "${key}".`,
-          suggestion: suggestion ? `Did you mean "${suggestion}"?` : void 0
-        });
+      if (KNOWN_STEP_FIELDS.has(key)) continue;
+      const canonical = PROPERTY_ALIASES[key];
+      if (canonical) {
+        if (!(canonical in obj)) {
+          obj[canonical] = obj[key];
+        }
+        delete obj[key];
+        continue;
       }
+      const suggestion = suggestProperty(key);
+      errors.push({
+        stepIndex: i,
+        field: key,
+        message: suggestion ? `unknown property "${key}". Did you mean "${suggestion}"?` : `unknown property "${key}".`,
+        suggestion: suggestion ? `Did you mean "${suggestion}"?` : void 0
+      });
     }
     for (const [field, fieldRule] of Object.entries(rule.required)) {
       if (!(field in obj) || obj[field] === void 0) {
@@ -3311,7 +3364,7 @@ async function createCDPClient(wsUrl, options = {}) {
         throw new Error("CDP client is not connected");
       }
       const id = ++messageId;
-      const effectiveSessionId = sessionId ?? currentSessionId;
+      const effectiveSessionId = sessionId === null ? void 0 : sessionId ?? currentSessionId;
       const request = { id, method };
       if (params !== void 0) {
         request.params = params;
@@ -3793,6 +3846,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) {
@@ -3826,18 +4158,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) {
@@ -3847,11 +4180,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) {
@@ -4512,6 +4848,9 @@ var Page = class {
           timeout: options.timeout ?? DEFAULT_TIMEOUT2
         });
       } catch (e) {
+        if (e instanceof ActionabilityError && e.failureType === "hitTarget" && await this.tryClickAssociatedLabel(objectId)) {
+          return true;
+        }
         if (options.optional) return false;
         throw e;
       }
@@ -4900,7 +5239,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;
     });
@@ -4952,7 +5296,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;
     });
@@ -5276,7 +5625,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;
   }
@@ -5328,6 +5677,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
@@ -5800,7 +6218,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(),
@@ -5821,7 +6240,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);
@@ -5837,7 +6256,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,
@@ -5845,7 +6264,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",
@@ -5867,37 +6303,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,
@@ -5906,7 +6349,9 @@ var Page = class {
       interactiveElements,
       text
     };
-    this.lastSnapshot = result;
+    if (roleFilter.size === 0) {
+      this.lastSnapshot = result;
+    }
     return result;
   }
   /**
@@ -6461,7 +6906,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_TIMEOUT2 } = options;
@@ -6528,11 +6973,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
@@ -6540,6 +6985,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,
@@ -6586,6 +7039,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
    */
@@ -7003,6 +7572,7 @@ var Browser = class _Browser {
   cdp;
   providerSession;
   pages = /* @__PURE__ */ new Map();
+  pageCounter = 0;
   constructor(cdp, _provider, providerSession, _options) {
     this.cdp = cdp;
     this.providerSession = providerSession;
@@ -7032,7 +7602,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;
@@ -7054,16 +7628,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);
@@ -7091,13 +7673,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;
   }
@@ -7107,14 +7693,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