browser-pilot 0.0.12 → 0.0.13

package/dist/cli.mjs

@@ -72,6 +72,12 @@ CONTENT EXTRACTION
   {"action": "snapshot"}
     Get accessibility tree (best for understanding page structure).
 
+  {"action": "forms"}
+    List form controls with labels, values, checked state, and options metadata.
+
+  {"action": "text"}
+    Extract visible page text.
+
   {"action": "screenshot"}
   {"action": "screenshot", "fullPage": true, "format": "jpeg", "quality": 80}
     Capture screenshot. Formats: png | jpeg | webp.
@@ -79,6 +85,15 @@ CONTENT EXTRACTION
   {"action": "evaluate", "value": "document.title"}
     Run JavaScript and return result.
 
+TAB MANAGEMENT
+  {"action": "newTab"}
+  {"action": "newTab", "url": "https://example.com"}
+    Create a new tab and optionally navigate it. Returns { targetId }.
+
+  {"action": "closeTab"}
+  {"action": "closeTab", "targetId": "TARGET_ID"}
+    Close the current tab or a specific target by ID.
+
 IFRAME NAVIGATION
   {"action": "switchFrame", "selector": "iframe#checkout"}
     Switch context to an iframe. All subsequent actions target the iframe content.
@@ -110,13 +125,19 @@ COMMON OPTIONS (all actions)
 
 REF SELECTORS (from snapshot)
   After taking a snapshot, use refs directly:
-    bp snapshot -s dev --format text   # Shows: button "Submit" [ref=e4]
+    bp snapshot -s dev --format text   # Shows: button "Submit" ref:e4
     bp exec '{"action":"click","selector":"ref:e4"}'
 
   Refs are stable until navigation. Prefix with "ref:" to use.
   CLI caches refs per session+URL after snapshot, so they can be reused across exec calls.
   Example: {"action":"fill","selector":"ref:e23","value":"hello"}
 
+TEXT / ROLE SELECTORS
+  text:Continue              Match by accessible text/name (partial match)
+  text:="Save Draft"         Exact text match
+  role:button:Continue       Match by role and optional accessible name
+  role:textbox:Email         Useful when stable CSS selectors are missing
+
 MULTI-SELECTOR PATTERN
   All selectors accept arrays: ["#id", ".class", "[aria-label=X]"]
   Tries each in order until one succeeds.
@@ -129,6 +150,14 @@ SELECTOR PRIORITY (Most to Least Reliable)
   4. [aria-label="..."]   - Good for buttons without testids
   5. Multi-selector array - Fallback pattern for compatibility
 
+ASSERTIONS
+  {"action":"assertVisible","selector":"#success"}
+  {"action":"assertExists","selector":"#mounted-node"}
+  {"action":"assertText","expect":"Welcome back"}
+  {"action":"assertUrl","expect":"/dashboard"}
+  {"action":"assertValue","selector":"#email","expect":"user@example.com"}
+    Assertion steps verify state inline inside a batch workflow.
+
 SHADOW DOM
   Selectors automatically pierce shadow DOM (1-2 levels). No special syntax needed.
   For deeper nesting (3+ levels), use refs from snapshot - they work at any depth.
@@ -1289,6 +1318,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,
@@ -1308,6 +1340,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 });
@@ -1422,10 +1469,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",
@@ -1439,7 +1491,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}`);
@@ -1510,6 +1562,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",
@@ -1546,7 +1603,8 @@ var PROPERTY_ALIASES = {
   button: "key",
   address: "url",
   page: "url",
-  path: "url"
+  path: "url",
+  tabId: "targetId"
 };
 var ACTION_RULES = {
   goto: {
@@ -1647,6 +1705,10 @@ var ACTION_RULES = {
       fullPage: { type: "boolean" }
     }
   },
+  forms: {
+    required: {},
+    optional: {}
+  },
   evaluate: {
     required: { value: { type: "string" } },
     optional: {}
@@ -1661,6 +1723,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: {}
@@ -1703,6 +1777,7 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "selector",
   "url",
   "value",
+  "targetId",
   "key",
   "combo",
   "modifiers",
@@ -1857,15 +1932,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) {
@@ -3370,7 +3452,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;
@@ -3849,6 +3931,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) {
@@ -3882,18 +4243,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) {
@@ -3903,11 +4265,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) {
@@ -4527,6 +4892,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;
       }
@@ -4915,7 +5283,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;
     });
@@ -4967,7 +5340,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;
     });
@@ -5291,7 +5669,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;
   }
@@ -5343,6 +5721,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
@@ -5815,7 +6262,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(),
@@ -5836,7 +6284,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);
@@ -5852,7 +6300,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,
@@ -5860,7 +6308,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",
@@ -5882,37 +6347,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,
@@ -5921,7 +6393,9 @@ var Page = class {
       interactiveElements,
       text
     };
-    this.lastSnapshot = result;
+    if (roleFilter.size === 0) {
+      this.lastSnapshot = result;
+    }
     return result;
   }
   /**
@@ -6476,7 +6950,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;
@@ -6543,11 +7017,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
@@ -6555,6 +7029,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,
@@ -6601,6 +7083,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
    */
@@ -7018,6 +7616,7 @@ var Browser = class _Browser {
   cdp;
   providerSession;
   pages = /* @__PURE__ */ new Map();
+  pageCounter = 0;
   constructor(cdp, _provider, providerSession, _options) {
     this.cdp = cdp;
     this.providerSession = providerSession;
@@ -7047,7 +7646,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;
@@ -7069,16 +7672,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);
@@ -7106,13 +7717,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;
   }
@@ -7122,14 +7737,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
@@ -8039,9 +8670,12 @@ Usage:
 
 Options:
   -p, --provider <type>   Provider: generic | browserbase | browserless (default: generic)
-  --url <ws-url>          WebSocket URL (auto-discovered for generic provider)
+  --url <value>           Browser WebSocket URL, or page URL when used with --new-tab
+  --browser-url <ws-url>  Explicit browser WebSocket URL
+  --page-url <url>        URL to open in the attached page/new tab
   -n, --name <id>         Custom session name (default: auto-generated)
   -r, --resume <id>       Resume an existing session by ID
+  --new-tab               Create and attach to a fresh tab instead of reusing an existing one
   --target-url <str>      Filter targets to those whose URL contains this string
   --api-key <key>         API key for cloud providers
   --project-id <id>       Project ID for BrowserBase provider
@@ -8056,6 +8690,7 @@ Examples:
   bp connect --url ws://localhost:9222/devtools  # Explicit WebSocket URL
   bp connect --resume dev                       # Resume a previous session
   bp connect --target-url localhost:3000         # Attach to tab matching URL
+  bp connect --new-tab --url https://example.com # Create and attach to a fresh tab
 `.trimEnd();
 function parseConnectArgs(args) {
   const options = {};
@@ -8065,10 +8700,16 @@ function parseConnectArgs(args) {
       options.provider = args[++i];
     } else if (arg === "--url") {
       options.url = args[++i];
+    } else if (arg === "--browser-url") {
+      options.browserUrl = args[++i];
+    } else if (arg === "--page-url") {
+      options.pageUrl = args[++i];
     } else if (arg === "--name" || arg === "-n") {
       options.name = args[++i];
     } else if (arg === "--resume" || arg === "-r") {
       options.resume = args[++i];
+    } else if (arg === "--new-tab") {
+      options.newTab = true;
     } else if (arg === "--target-url") {
       options.targetUrl = args[++i];
     } else if (arg === "--api-key") {
@@ -8103,7 +8744,14 @@ async function connectCommand(args, globalOptions) {
     return;
   }
   const provider = options.provider ?? "generic";
-  let wsUrl = options.url;
+  let wsUrl = options.browserUrl ?? options.url;
+  let pageUrl = options.pageUrl;
+  if (options.newTab && options.url && !options.url.startsWith("ws://") && !options.url.startsWith("wss://")) {
+    pageUrl = options.url;
+    if (!options.browserUrl) {
+      wsUrl = void 0;
+    }
+  }
   if (provider === "generic" && !wsUrl) {
     try {
       wsUrl = await getBrowserWebSocketUrl("localhost:9222");
@@ -8121,8 +8769,10 @@ async function connectCommand(args, globalOptions) {
     projectId: options.projectId
   };
   const browser = await connect(connectOptions);
-  const pageOptions = options.targetUrl ? { targetUrl: options.targetUrl } : void 0;
-  const page = await browser.page(void 0, pageOptions);
+  const page = options.newTab ? await browser.newPage(pageUrl ?? "about:blank") : await browser.page(
+    void 0,
+    options.targetUrl ? { targetUrl: options.targetUrl } : void 0
+  );
   const currentUrl = await page.url();
   const sessionId = options.name ?? generateSessionId();
   const session = {
@@ -8835,6 +9485,7 @@ Usage:
 
 Options:
   -f, --file <path>    Read JavaScript from a file
+  --wrap               Wrap the expression in an async IIFE
   -s, --session <id>   Session to use (default: most recent)
   -f, --format <fmt>   Output format: json | pretty (default: pretty)
   --json               Alias for -f json
@@ -8853,12 +9504,25 @@ function parseEvalArgs(args) {
     const arg = args[i];
     if (arg === "-f" || arg === "--file") {
       options.file = args[++i];
+    } else if (arg === "--wrap") {
+      options.wrap = true;
     } else if (!expression && !arg.startsWith("-")) {
       expression = arg;
     }
   }
   return { expression, options };
 }
+function normalizeEvalExpression(expression, wrap = false) {
+  const trimmed = expression.trim();
+  const needsWrap = wrap || trimmed.includes("=>") || /\bawait\b/.test(trimmed);
+  if (!needsWrap) {
+    return trimmed;
+  }
+  if (wrap || /\bawait\b/.test(trimmed)) {
+    return `(async () => (${trimmed}))()`;
+  }
+  return `(() => (${trimmed}))()`;
+}
 async function evalCommand(args, globalOptions) {
   if (globalOptions.help) {
     console.log(EVAL_HELP);
@@ -8885,7 +9549,10 @@ async function evalCommand(args, globalOptions) {
   const session = await resolveSession(globalOptions.session);
   const { browser, page } = await attachSession(session, { trace: globalOptions.trace });
   try {
-    const step = { action: "evaluate", value: expression };
+    const step = {
+      action: "evaluate",
+      value: normalizeEvalExpression(expression, evalOptions.wrap)
+    };
     const result = await page.batch([step]);
     const stepResult = result.steps[0];
     if (!stepResult.success) {
@@ -9079,6 +9746,7 @@ Usage:
 
 Options:
   -f, --file <path>    Read actions from a JSON file
+  -o, --output <path>  Write command output to a file instead of stdout
   --dialog <mode>      Handle native dialogs: accept | dismiss
   -s, --session <id>   Session to use (default: most recent)
   -f, --format <fmt>   Output format: json | pretty (default: pretty)
@@ -9109,12 +9777,33 @@ function parseExecArgs(args) {
       }
     } else if (arg === "-f" || arg === "--file") {
       options.file = args[++i];
+    } else if (arg === "-o" || arg === "--output") {
+      options.outputFile = args[++i];
     } else if (!actionsJson && !arg.startsWith("-")) {
       actionsJson = arg;
     }
   }
   return { actionsJson, options };
 }
+async function getCurrentUrlSafe(page, fallback) {
+  try {
+    return await page.url();
+  } catch {
+    return fallback;
+  }
+}
+async function captureFinalUrl(page, steps, fallback) {
+  const currentUrl = await getCurrentUrlSafe(page, fallback);
+  if (currentUrl !== fallback) {
+    return currentUrl;
+  }
+  const mightNavigate = steps.some((step) => step.action === "click" || step.action === "submit");
+  if (!mightNavigate) {
+    return currentUrl;
+  }
+  await new Promise((resolve3) => setTimeout(resolve3, 200));
+  return getCurrentUrlSafe(page, currentUrl);
+}
 async function execCommand(args, globalOptions) {
   if (globalOptions.help) {
     console.log(EXEC_HELP);
@@ -9173,8 +9862,12 @@ Run 'bp actions' for complete action reference.${evalTip}`
     }
     const steps = Array.isArray(actions) ? actions : [actions];
     const urlBefore = await page.url();
+    const currentTargetId = page.targetId;
+    const closesCurrentTarget = steps.some(
+      (step) => step.action === "closeTab" && (!step.targetId || step.targetId === currentTargetId)
+    );
     const result = await page.batch(steps);
-    const urlAfter = await page.url();
+    const urlAfter = closesCurrentTarget ? urlBefore : await captureFinalUrl(page, steps, urlBefore);
     for (const stepResult of result.steps) {
       logger.logCommand(
         stepResult.action,
@@ -9196,9 +9889,14 @@ Run 'bp actions' for complete action reference.${evalTip}`
       urlBefore,
       urlAfter
     });
-    const currentUrl = await page.url();
+    const currentUrl = closesCurrentTarget ? urlBefore : await captureFinalUrl(page, steps, urlAfter);
     const hasSnapshot = steps.some((step) => step.action === "snapshot");
-    if (hasSnapshot) {
+    if (closesCurrentTarget) {
+      await updateSession(session.id, {
+        currentUrl,
+        targetId: void 0
+      });
+    } else if (hasSnapshot) {
       await updateSession(session.id, {
         currentUrl,
         metadata: {
@@ -9221,16 +9919,21 @@ Run 'bp actions' for complete action reference.${evalTip}`
       text: s.text,
       result: s.result
     }));
-    output(
-      {
-        success: result.success,
-        stoppedAtIndex: result.stoppedAtIndex,
-        steps: outputSteps,
-        totalDurationMs: result.totalDurationMs,
-        currentUrl
-      },
-      globalOptions.format
-    );
+    const payload = {
+      success: result.success,
+      stoppedAtIndex: result.stoppedAtIndex,
+      steps: outputSteps,
+      totalDurationMs: result.totalDurationMs,
+      currentUrl
+    };
+    if (execOptions.outputFile) {
+      const fs3 = await import("fs/promises");
+      await fs3.writeFile(execOptions.outputFile, renderOutput(payload, globalOptions.format));
+      process.stderr.write(`Wrote output to ${execOptions.outputFile}
+`);
+    } else {
+      output(payload, globalOptions.format);
+    }
     const failedEval = result.steps.find((s) => s.action === "evaluate" && !s.success);
     if (failedEval) {
       console.error(
@@ -9243,6 +9946,116 @@ Tip: Use "bp eval 'expression'" for simpler JavaScript inspection/debugging (no
   }
 }
 
+// src/cli/commands/form-utils.ts
+function fieldIdentifier(field) {
+  if (field.id) return `#${field.id}`;
+  if (field.name) return `name=${field.name}`;
+  return `<${field.tag}>`;
+}
+function fieldState(field) {
+  if (field.type === "checkbox" || field.type === "radio") {
+    return field.checked ? "checked" : "unchecked";
+  }
+  if (Array.isArray(field.value)) {
+    return field.value.length > 0 ? field.value.join(", ") : '""';
+  }
+  if (typeof field.value === "string") {
+    return JSON.stringify(field.value);
+  }
+  return '""';
+}
+function fieldMeta(field) {
+  const bits = [field.label];
+  if (field.required) bits.push("required");
+  if (field.disabled) bits.push("disabled");
+  return bits.filter(Boolean).join(" | ");
+}
+function formatFormFieldsPretty(fields) {
+  const lines = [];
+  const seenRadioGroups = /* @__PURE__ */ new Set();
+  for (const field of fields) {
+    if (field.type === "radio" && field.name) {
+      if (seenRadioGroups.has(field.name)) continue;
+      seenRadioGroups.add(field.name);
+      const group = fields.filter(
+        (candidate) => candidate.type === "radio" && candidate.name === field.name
+      );
+      const options = group.map((candidate) => {
+        const label = candidate.label || candidate.value || candidate.id || "(unnamed)";
+        return candidate.checked ? `${label} [checked]` : label;
+      }).join(" | ");
+      const meta2 = fieldMeta(group.find((candidate) => candidate.label) ?? field);
+      lines.push(`  ${fieldIdentifier(field)}  radio  ${options}${meta2 ? `  ${meta2}` : ""}`);
+      continue;
+    }
+    let state = fieldState(field);
+    if (field.options?.length) {
+      const options = field.options.map((option) => option.selected ? `${option.text} [selected]` : option.text).join(" | ");
+      state += options ? `  ${options}` : "";
+    }
+    const meta = fieldMeta(field);
+    lines.push(`  ${fieldIdentifier(field)}  ${field.type}  ${state}${meta ? `  ${meta}` : ""}`);
+  }
+  return lines;
+}
+function formatInteractiveElementsPretty(elements, limit = elements.length) {
+  return elements.slice(0, limit).map((element) => {
+    let line = `  ref:${element.ref} ${element.role}`;
+    if (element.name) {
+      line += ` "${element.name}"`;
+    }
+    if (element.disabled) {
+      line += " (disabled)";
+    }
+    if (element.checked !== void 0) {
+      line += element.checked ? " (checked)" : " (unchecked)";
+    }
+    return line;
+  });
+}
+
+// src/cli/commands/forms.ts
+var FORMS_HELP = `
+bp forms - List form controls on the current page
+
+Usage:
+  bp forms [options]
+
+Options:
+  -s, --session <id>   Session to use (default: most recent)
+  -f, --format <fmt>   json | pretty (default: pretty)
+  --json               Alias for -f json
+  --trace              Enable debug tracing
+  -h, --help           Show this help
+
+Examples:
+  bp forms
+  bp forms --json
+`.trimEnd();
+async function formsCommand(_args, globalOptions) {
+  if (globalOptions.help) {
+    process.stdout.write(`${FORMS_HELP}
+`);
+    return;
+  }
+  const session = await resolveSession(globalOptions.session);
+  const { browser, page } = await attachSession(session, { trace: globalOptions.trace });
+  try {
+    const [forms, currentUrl] = await Promise.all([page.forms(), page.url()]);
+    if (globalOptions.format === "json") {
+      output(forms, "json");
+    } else if (forms.length === 0) {
+      process.stdout.write("No form controls found.\n");
+    } else {
+      process.stdout.write(`${formatFormFieldsPretty(forms).join("\n")}
+`);
+    }
+    await updateSession(session.id, { currentUrl });
+  } finally {
+    await browser.disconnect();
+  }
+}
+
 // src/cli/commands/list.ts
 var HELP = `
 bp list - List sessions and view action logs
@@ -9781,6 +10594,91 @@ Timeout reached (${options.timeout}ms).`);
   }
 }
 
+// src/cli/commands/page.ts
+var PAGE_HELP = `
+bp page - Show a compact overview of the current page
+
+Usage:
+  bp page [options]
+
+Options:
+  -s, --session <id>   Session to use (default: most recent)
+  -f, --format <fmt>   json | pretty (default: pretty)
+  --json               Alias for -f json
+  --trace              Enable debug tracing
+  -h, --help           Show this help
+
+Examples:
+  bp page
+  bp page --json
+`.trimEnd();
+async function getHeadings(page) {
+  return page.evaluate(`(() => {
+    return Array.from(document.querySelectorAll('h1, h2, h3'))
+      .map((el) => ({
+        level: el.tagName.toLowerCase(),
+        text: (el.innerText || el.textContent || '').replace(/\\s+/g, ' ').trim(),
+      }))
+      .filter((heading) => heading.text);
+  })()`);
+}
+function formatPageSummary(summary) {
+  const lines = [`URL: ${summary.url}`, `Title: ${summary.title}`];
+  lines.push("", "Headings:");
+  if (summary.headings.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const heading of summary.headings) {
+      lines.push(`  ${heading.level}: ${heading.text}`);
+    }
+  }
+  lines.push("", "Form fields:");
+  if (summary.forms.length === 0) {
+    lines.push("  (none)");
+  } else {
+    lines.push(...formatFormFieldsPretty(summary.forms));
+  }
+  lines.push("", "Actions:");
+  if (summary.interactiveElements.length === 0) {
+    lines.push("  (none)");
+  } else {
+    lines.push(...formatInteractiveElementsPretty(summary.interactiveElements, 20));
+  }
+  return lines.join("\n");
+}
+async function pageCommand(_args, globalOptions) {
+  if (globalOptions.help) {
+    process.stdout.write(`${PAGE_HELP}
+`);
+    return;
+  }
+  const session = await resolveSession(globalOptions.session);
+  const { browser, page } = await attachSession(session, { trace: globalOptions.trace });
+  try {
+    const [url, title, headings, forms, snapshot] = await Promise.all([
+      page.url(),
+      page.title(),
+      getHeadings(page),
+      page.forms(),
+      page.snapshot()
+    ]);
+    const summary = {
+      url,
+      title,
+      headings,
+      forms,
+      interactiveElements: snapshot.interactiveElements
+    };
+    output(
+      globalOptions.format === "json" ? summary : formatPageSummary(summary),
+      globalOptions.format
+    );
+    await updateSession(session.id, { currentUrl: url });
+  } finally {
+    await browser.disconnect();
+  }
+}
+
 // src/cli/commands/quickstart.ts
 var QUICKSTART = `
 browser-pilot CLI - Quick Start Guide
@@ -9797,13 +10695,13 @@ STEP 3: GET PAGE SNAPSHOT
   bp snapshot -i
 
   Shows only interactive elements (buttons, inputs, links) with refs:
-    button "Sign In" [ref=e2]
-    textbox "Email" [ref=e3]
-    link "Forgot password?" [ref=e6]
+    button "Sign In" ref:e2
+    textbox "Email" ref:e3
+    link "Forgot password?" ref:e6
 
   Other formats:
     bp snapshot --format text    # Full accessibility tree (all elements)
-    bp snapshot                  # Full snapshot as JSON
+    bp snapshot --json           # Full snapshot as JSON
 
 STEP 4: INTERACT USING REFS
   bp exec '{"action":"fill","selector":"ref:e3","value":"test@example.com"}'
@@ -9822,6 +10720,13 @@ FOR AI AGENTS
     bp snapshot -i --json
     bp exec '{"action":"click","selector":"ref:e3"}' --json
 
+PAGE DISCOVERY SHORTCUTS
+  bp page              # URL, title, headings, forms, and interactive controls
+  bp forms             # Structured list of form fields only
+  bp targets           # All available browser tabs
+  bp connect --new-tab --url https://example.com
+                      # Start from a fresh tab instead of reusing one
+
 TIPS
   \u2022 Refs (e1, e2...) are stable within a page - prefer them over CSS selectors
   \u2022 After navigation, take a new snapshot to get updated refs
@@ -11636,7 +12541,9 @@ Usage:
 
 Options:
   -i, --interactive      Show only interactive elements (buttons, inputs, links)
-  -f, --format <type>    Output format: full | interactive | text (default: full)
+  -f, --format <type>    Output format: full | interactive | text (default: text)
+  --role <roles>         Filter snapshot to accessibility roles (for example: radio,checkbox)
+  -o, --output <path>    Write command output to a file instead of stdout
   -d, --diff <file>      Compare current page against a saved snapshot JSON
   --inspect              Inject visual ref labels onto the page (auto-removes after 10s)
   --keep                 Keep visual ref labels visible (use with --inspect)
@@ -11647,22 +12554,31 @@ Options:
   -h, --help             Show this help
 
 Examples:
+  bp snapshot                       # Full accessibility tree as readable text
   bp snapshot -i                    # Interactive elements only (best for AI agents)
-  bp snapshot --format text         # Full accessibility tree as text
+  bp snapshot --role radio,checkbox # Focus on specific control roles
   bp snapshot --json > page.json    # Save full snapshot to file
   bp snapshot --diff before.json    # Show what changed since before.json
   bp snapshot --inspect             # Visual ref labels on the page
 `.trimEnd();
 function parseSnapshotArgs(args) {
-  const options = {};
+  const options = {
+    format: "text"
+  };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--format" || arg === "-f") {
       options.format = args[++i];
+      options.formatExplicit = true;
     } else if (arg === "--diff" || arg === "-d") {
       options.diffFile = args[++i];
     } else if (arg === "--interactive" || arg === "-i") {
       options.format = "interactive";
+      options.formatExplicit = true;
+    } else if (arg === "--role") {
+      options.roles = args[++i]?.split(",").map((role) => role.trim().toLowerCase()).filter(Boolean);
+    } else if (arg === "--output" || arg === "-o") {
+      options.outputFile = args[++i];
     } else if (arg === "--inspect") {
       options.inspect = true;
     } else if (arg === "--keep") {
@@ -11673,6 +12589,11 @@ function parseSnapshotArgs(args) {
   }
   return options;
 }
+function writeInfo(message, asStderr = false) {
+  const stream = asStderr ? process.stderr : process.stdout;
+  stream.write(message.endsWith("\n") ? message : `${message}
+`);
+}
 function sleep7(ms) {
   return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
@@ -11698,7 +12619,8 @@ async function snapshotCommand(args, globalOptions) {
   });
   try {
     const page = await browser.page(void 0, { targetId: session.targetId });
-    const snapshot = await page.snapshot();
+    const snapshot = await page.snapshot(options.roles?.length ? { roles: options.roles } : {});
+    const infoToStderr = globalOptions.format === "json" || !!options.outputFile;
     await updateSession(session.id, {
       currentUrl: snapshot.url,
       metadata: {
@@ -11716,43 +12638,117 @@ async function snapshotCommand(args, globalOptions) {
       const beforeContent = fs2.readFileSync(options.diffFile, "utf-8");
       const beforeSnapshot = JSON.parse(beforeContent);
       const diff = diffSnapshots(beforeSnapshot, snapshot);
-      if (globalOptions.format === "json") {
+      if (options.outputFile) {
+        fs2.writeFileSync(options.outputFile, renderOutput(diff, globalOptions.format));
+        writeInfo(`Wrote output to ${options.outputFile}`, true);
+      } else if (globalOptions.format === "json") {
         output(diff, "json");
       } else {
-        console.log(formatDiffPretty(diff));
+        writeInfo(formatDiffPretty(diff));
       }
       return;
     }
     if (options.inspect) {
       await injectRefOverlay(page, snapshot);
-      console.log("Overlay injected. Element refs are now visible on the page.");
+      writeInfo("Overlay injected. Element refs are now visible on the page.", infoToStderr);
       if (options.keep) {
-        console.log(
-          "Overlay will remain visible. Use removeRefOverlay() or refresh the page to remove."
+        writeInfo(
+          "Overlay will remain visible. Use removeRefOverlay() or refresh the page to remove.",
+          infoToStderr
         );
       } else {
-        console.log("Overlay will be removed in 10 seconds...");
+        writeInfo("Overlay will be removed in 10 seconds...", infoToStderr);
         await sleep7(1e4);
         await removeRefOverlay(page);
-        console.log("Overlay removed.");
+        writeInfo("Overlay removed.", infoToStderr);
       }
     }
-    switch (options.format) {
-      case "interactive":
-        output(snapshot.interactiveElements, globalOptions.format);
-        break;
-      case "text":
-        console.log(snapshot.text);
-        break;
-      default:
-        output(snapshot, globalOptions.format);
-        break;
+    const shouldForceFullJson = globalOptions.format === "json" && !options.formatExplicit;
+    let payload = snapshot;
+    if (!shouldForceFullJson) {
+      switch (options.format) {
+        case "interactive":
+          payload = snapshot.interactiveElements;
+          break;
+        case "text":
+          payload = snapshot.text;
+          break;
+        default:
+          payload = snapshot;
+          break;
+      }
+    }
+    if (options.outputFile) {
+      fs2.writeFileSync(options.outputFile, renderOutput(payload, globalOptions.format));
+      writeInfo(`Wrote output to ${options.outputFile}`, true);
+    } else {
+      output(payload, globalOptions.format);
     }
   } finally {
     await browser.disconnect();
   }
 }
 
+// src/cli/commands/targets.ts
+var TARGETS_HELP = `
+bp targets - List page tabs available in the connected browser
+
+Usage:
+  bp targets [options]
+
+Options:
+  -s, --session <id>   Session to use (default: most recent)
+  -f, --format <fmt>   json | pretty (default: pretty)
+  --json               Alias for -f json
+  --trace              Enable debug tracing
+  -h, --help           Show this help
+
+Examples:
+  bp targets
+  bp targets --json
+`.trimEnd();
+function formatTargetsPretty(targets) {
+  if (targets.length === 0) {
+    return "No page targets found.";
+  }
+  return targets.map((target) => {
+    const lines = [
+      `${target.title || "(untitled)"}`,
+      `  targetId: ${target.targetId}`,
+      `  url: ${target.url}`
+    ];
+    if (target.attached) {
+      lines.push("  attached: true");
+    }
+    return lines.join("\n");
+  }).join("\n\n");
+}
+async function targetsCommand(_args, globalOptions) {
+  if (globalOptions.help) {
+    process.stdout.write(`${TARGETS_HELP}
+`);
+    return;
+  }
+  const session = globalOptions.session ? await loadSession(globalOptions.session) : await getDefaultSession();
+  if (!session) {
+    throw new Error('No session found. Run "bp connect" first.');
+  }
+  const browser = await connect({
+    provider: session.provider,
+    wsUrl: session.wsUrl,
+    debug: globalOptions.trace
+  });
+  try {
+    const targets = await browser.listTargets();
+    output(
+      globalOptions.format === "json" ? targets : formatTargetsPretty(targets),
+      globalOptions.format
+    );
+  } finally {
+    await browser.disconnect();
+  }
+}
+
 // src/cli/commands/text.ts
 var TEXT_HELP = `
 bp text - Extract text content from the current page
@@ -11832,6 +12828,9 @@ Commands:
   connect     Create browser session
   exec        Execute actions
   eval        Evaluate JavaScript expression
+  page        Show a compact page overview
+  forms       List form controls on the page
+  targets     List available browser tabs
   run         Run a workflow file (JSON steps)
   record      Record browser actions to JSON
   audio       Audio I/O for voice agent testing
@@ -11896,34 +12895,43 @@ function parseGlobalOptions(args) {
   return { options, remaining };
 }
 function output(data, format = "pretty") {
+  const text = renderOutput(data, format);
+  process.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+}
+function renderOutput(data, format = "pretty") {
   if (format === "json") {
-    console.log(JSON.stringify(data, null, 2));
-  } else {
-    if (typeof data === "string") {
-      console.log(data);
-    } else if (typeof data === "object" && data !== null) {
-      const { truncated } = prettyPrint(data);
-      if (truncated) {
-        console.log("\n(Output truncated. Use --json for full data)");
-      }
-    } else {
-      console.log(data);
+    return JSON.stringify(data, null, 2);
+  }
+  if (typeof data === "string") {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return JSON.stringify(data, null, 2);
+  }
+  if (typeof data === "object" && data !== null) {
+    const lines = [];
+    const { truncated } = prettyPrint(data, lines);
+    if (truncated) {
+      lines.push("", "(Output truncated. Use --json for full data)");
     }
+    return lines.join("\n");
   }
+  return String(data);
 }
-function prettyPrint(obj, indent = 0) {
+function prettyPrint(obj, lines, indent = 0) {
   const prefix = "  ".repeat(indent);
   let truncated = false;
   for (const [key, value] of Object.entries(obj)) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-      console.log(`${prefix}${key}:`);
-      const result = prettyPrint(value, indent + 1);
+      lines.push(`${prefix}${key}:`);
+      const result = prettyPrint(value, lines, indent + 1);
       if (result.truncated) truncated = true;
     } else if (Array.isArray(value)) {
-      console.log(`${prefix}${key}: [${value.length} items]`);
+      lines.push(`${prefix}${key}: [${value.length} items]`);
       truncated = true;
     } else {
-      console.log(`${prefix}${key}: ${value}`);
+      lines.push(`${prefix}${key}: ${value}`);
     }
   }
   return { truncated };
@@ -11954,6 +12962,15 @@ async function main() {
       case "eval":
         await evalCommand(remaining, options);
         break;
+      case "page":
+        await pageCommand(remaining, options);
+        break;
+      case "forms":
+        await formsCommand(remaining, options);
+        break;
+      case "targets":
+        await targetsCommand(remaining, options);
+        break;
       case "snapshot":
         await snapshotCommand(remaining, options);
         break;
@@ -12011,5 +13028,6 @@ if (import.meta.main) {
 }
 export {
   output,
-  parseGlobalOptions
+  parseGlobalOptions,
+  renderOutput
 };