browser-debugger-cli 0.7.1 → 0.8.0

package/dist/runtime/dom/eventListeners.js

@@ -0,0 +1,252 @@
+/**
+ * Event listeners that run for an element (`bdg dom listeners`).
+ *
+ * Collects the listeners of the element, every ancestor (through open shadow
+ * roots), its document and its window with `DOMDebugger.getEventListeners`,
+ * so handlers that frameworks attach by delegation (React on its root
+ * container, jQuery on `document`) are found too. The Debugger domain is not
+ * enabled: that would make `debugger;` statements pause the page.
+ */
+import { CDPProtocolError } from '../../connection/errors.js';
+import { CommandError } from '../../errors/index.js';
+import { eventListenersUnavailableError, indexOutOfRangeError, noNodesFoundError, operationFailedError, staleNodeError, } from '../../errors/messages.js';
+import { throwIfInvalidSelector, withMultipleMatchesWarning, } from './formFillHelpers/shared.js';
+import { buildListenerReport, describeChainEntry, } from './listenerSummary.js';
+import { DEEP_QUERY_JS, selectorArgsJS } from './targetNode.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+const log = createLogger('dom');
+/** JSON-RPC code Chrome returns for an unknown method */
+const METHOD_NOT_FOUND = -32601;
+/**
+ * Page function: the selector's match at `index` as `[matchCount, element]`,
+ * or just the match count when there is no such match.
+ */
+const SELECT_JS = `function (selector, parts, index) {
+  const found = (${DEEP_QUERY_JS})(selector, parts);
+  return found[index] ? [found.length, found[index]] : found.length;
+}`;
+/**
+ * Page function, called on the element: `[element, ...ancestors, document,
+ * window]`, or null when it left the page. Shadow roots lead to their host,
+ * like composed events do.
+ */
+const CHAIN_JS = `function () {
+  if (!this.isConnected) return null;
+  const chain = [];
+  const next = (node) => node.parentNode || (node.nodeType === 11 && node.host ? node.host : null);
+  for (let node = this; node; node = next(node)) chain.push(node);
+  const view = this.ownerDocument && this.ownerDocument.defaultView;
+  if (view) chain.push(view);
+  return chain;
+}`;
+/** Page function: names of the given functions (null for non-functions) */
+const NAMES_JS = `function (...fns) {
+  return fns.map((fn) => (typeof fn === 'function' ? fn.name : null));
+}`;
+/** Distinguishes the object groups of concurrent calls */
+let groupCounter = 0;
+/**
+ * List the event listeners that run for an element.
+ *
+ * @param cdp - CDP connection
+ * @param params - Selector (and index) or backend node id, optional event types
+ * @returns Listener report
+ * @throws CommandError (83) no match, (81) index out of range or invalid
+ *   selector, (87) the cached element left the page, (110) no DOMDebugger
+ */
+export async function inspectEventListeners(cdp, params) {
+    const objectGroup = `bdg-listeners-${++groupCounter}`;
+    try {
+        const { matchCount, chain } = await findEventTargetChain(cdp, params, objectGroup);
+        const found = await collectListeners(cdp, chain);
+        const handlers = found.flatMap((entry) => entry.listeners.map((l) => l.handler));
+        const names = await handlerNames(cdp, chain[0]?.objectId ?? '', handlers);
+        const result = {
+            success: true,
+            selector: params.selector,
+            ...(params.index !== undefined && { index: params.index }),
+            element: describeChainEntry(chain[0] ?? {}),
+            listeners: buildListenerReport(found, names, params.types),
+            ...(params.backendNodeId === undefined && { matchCount }),
+        };
+        return withMultipleMatchesWarning(result, params.index, 'listing the first');
+    }
+    finally {
+        void cdp
+            .send('Runtime.releaseObjectGroup', { objectGroup })
+            .catch((error) => log.debug(`Object group not released: ${getErrorMessage(error)}`));
+    }
+}
+/**
+ * Find the element and the event targets above it.
+ *
+ * The chain is built in the element's own frame: `DOMDebugger.getEventListeners`
+ * only reports handlers created in the context the object belongs to, so an
+ * element of a same-origin iframe found from the top page would show none.
+ *
+ * @param cdp - CDP connection
+ * @param params - Request
+ * @param objectGroup - Object group for the handles
+ * @returns Number of selector matches and the chain (element first, window last)
+ */
+async function findEventTargetChain(cdp, params, objectGroup) {
+    const match = params.backendNodeId === undefined
+        ? await findSelectorMatch(cdp, params, objectGroup)
+        : { matchCount: 1, backendNodeId: params.backendNodeId };
+    const chain = await nodeChain(cdp, match.backendNodeId, objectGroup);
+    if (!chain)
+        throw missingElementError(params, 0);
+    return { matchCount: match.matchCount, chain };
+}
+/**
+ * Find the selector's match at `--index` (searching open shadow roots and
+ * same-origin frames).
+ *
+ * @param cdp - CDP connection
+ * @param params - Request with the selector
+ * @param objectGroup - Object group for the handles
+ * @returns Number of matches and the backend node id of the match
+ * @throws CommandError (81) invalid selector or index out of range, (83) no match
+ */
+async function findSelectorMatch(cdp, params, objectGroup) {
+    const expression = `(${SELECT_JS})(${selectorArgsJS(params.selector)}, ${params.index ?? 0})`;
+    const response = (await cdp.send('Runtime.evaluate', {
+        expression,
+        objectGroup,
+    }));
+    if (response.exceptionDetails) {
+        throwIfInvalidSelector(response.exceptionDetails, params.selector);
+        const err = operationFailedError('find the element', response.exceptionDetails.text);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SCRIPT_ERROR);
+    }
+    if (!response.result.objectId) {
+        throw missingElementError(params, Number(response.result.value ?? 0));
+    }
+    const [count, element] = await arrayItems(cdp, response.result.objectId);
+    const { node } = (await cdp.send('DOM.describeNode', {
+        objectId: element?.objectId,
+    }));
+    return { matchCount: Number(count?.value ?? 1), backendNodeId: node.backendNodeId };
+}
+/**
+ * The element with `backendNodeId` and the event targets above it, resolved
+ * in the element's frame.
+ *
+ * @param cdp - CDP connection
+ * @param backendNodeId - Backend node id
+ * @param objectGroup - Object group for the handles
+ * @returns Chain (element first, window last), or null when the node is gone
+ */
+async function nodeChain(cdp, backendNodeId, objectGroup) {
+    const resolved = (await cdp
+        .send('DOM.resolveNode', { backendNodeId, objectGroup })
+        .catch((error) => {
+        log.debug(`Node ${backendNodeId} not resolved: ${getErrorMessage(error)}`);
+        return {};
+    }));
+    const objectId = resolved.object?.objectId;
+    if (!objectId)
+        return null;
+    const response = (await cdp.send('Runtime.callFunctionOn', {
+        objectId,
+        functionDeclaration: CHAIN_JS,
+        objectGroup,
+    }));
+    if (!response.result.objectId)
+        return null;
+    const items = await arrayItems(cdp, response.result.objectId);
+    return items.flatMap((item) => item?.objectId
+        ? [{ objectId: item.objectId, className: item.className, description: item.description }]
+        : []);
+}
+/**
+ * Error for an element that could not be found.
+ *
+ * @param params - Request
+ * @param matchCount - Elements the selector matched
+ * @returns Stale (87), out of range (81) or not found (83) error
+ */
+function missingElementError(params, matchCount) {
+    if (params.backendNodeId !== undefined) {
+        const err = staleNodeError();
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
+    }
+    if (matchCount > 0) {
+        const err = indexOutOfRangeError(params.index ?? 0, matchCount - 1);
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const err = noNodesFoundError(params.selector);
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+}
+/**
+ * Items of an array in the page, in order.
+ *
+ * @param cdp - CDP connection
+ * @param arrayId - Object id of the array
+ * @returns Its items
+ */
+async function arrayItems(cdp, arrayId) {
+    const { result } = (await cdp.send('Runtime.getProperties', {
+        objectId: arrayId,
+        ownProperties: true,
+    }));
+    return result
+        .filter((property) => /^\d+$/.test(property.name))
+        .sort((a, b) => Number(a.name) - Number(b.name))
+        .map((property) => property.value);
+}
+/**
+ * Get the listeners of every event target in the chain (in parallel).
+ *
+ * @param cdp - CDP connection
+ * @param chain - Event targets, element first
+ * @returns Listeners per target
+ * @throws CommandError (110) when the browser has no DOMDebugger.getEventListeners
+ */
+async function collectListeners(cdp, chain) {
+    try {
+        return await Promise.all(chain.map(async (entry, position) => {
+            const { listeners } = (await cdp.send('DOMDebugger.getEventListeners', {
+                objectId: entry.objectId,
+                depth: 0,
+            }));
+            return { position, entry, listeners };
+        }));
+    }
+    catch (error) {
+        if (!(error instanceof CDPProtocolError) || error.code !== METHOD_NOT_FOUND)
+            throw error;
+        const err = eventListenersUnavailableError(error.message);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
+    }
+}
+/**
+ * Ask the page for the handlers' names (`Function.name` also knows names of
+ * arrow functions assigned to variables, and `bound f` for bound functions).
+ *
+ * @param cdp - CDP connection
+ * @param elementId - Object id of the element (the page context to run in)
+ * @param handlers - Handler objects, in report order
+ * @returns Names in the same order; empty when the page could not tell
+ */
+async function handlerNames(cdp, elementId, handlers) {
+    if (handlers.length === 0)
+        return [];
+    try {
+        const response = (await cdp.send('Runtime.callFunctionOn', {
+            objectId: elementId,
+            functionDeclaration: NAMES_JS,
+            arguments: handlers.map((handler) => handler?.objectId ? { objectId: handler.objectId } : { value: null }),
+            returnByValue: true,
+        }));
+        const names = response.result.value;
+        return (names ?? []).map((name) => name ?? undefined);
+    }
+    catch (error) {
+        log.debug(`Handler names not read: ${getErrorMessage(error)}`);
+        return [];
+    }
+}
+//# sourceMappingURL=eventListeners.js.map

package/dist/runtime/dom/formDiscovery.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Form discovery script executed in page context.
+ *
+ * Discovers forms, extracts semantic labels, detects state and validation,
+ * and returns structured data for agent consumption.
+ */
+import type { RawFormData } from './formTypes.js';
+/**
+ * Page-context script for form discovery.
+ *
+ * This script runs in the browser via Runtime.evaluate and discovers:
+ * - Native form elements and inputs
+ * - Custom components with ARIA roles
+ * - Labels via priority chain (label[for], aria-label, placeholder, etc.)
+ * - Current values and validation state
+ * - Form relevance scoring for multi-form pages
+ */
+export declare const FORM_DISCOVERY_SCRIPT = "\n(function() {\n  const result = { forms: [] };\n\n  function isUnique(selector) {\n    try {\n      return document.querySelectorAll(selector).length === 1;\n    } catch (e) {\n      return false;\n    }\n  }\n\n  function generateSelector(element) {\n    if (element.id && isUnique('#' + CSS.escape(element.id))) {\n      return '#' + CSS.escape(element.id);\n    }\n    if (element.name) {\n      const byName = element.tagName.toLowerCase() + '[name=\"' + CSS.escape(element.name) + '\"]';\n      if (isUnique(byName)) return byName;\n      const byValue = byName + '[value=\"' + CSS.escape(element.getAttribute('value') || '') + '\"]';\n      if (element.hasAttribute('value') && isUnique(byValue)) return byValue;\n    }\n    const tag = element.tagName.toLowerCase();\n    const parent = element.parentElement;\n    if (!parent) return tag;\n    const siblings = Array.from(parent.children).filter(c => c.tagName === element.tagName);\n    if (siblings.length === 1) {\n      const parentSelector = generateSelector(parent);\n      return parentSelector + ' > ' + tag;\n    }\n    const index = siblings.indexOf(element);\n    const parentSelector = generateSelector(parent);\n    return parentSelector + ' > ' + tag + ':nth-of-type(' + (index + 1) + ')';\n  }\n\n  function cleanLabelText(text) {\n    if (!text) return text;\n    const patterns = [\n      /Previous\\s*arrow/gi,\n      /Next\\s*arrow/gi,\n      /\\barrow\\b/gi,\n      /\\bchevron\\b/gi,\n      /\u2190|\u2192|\u2191|\u2193|\u25B2|\u25BC|\u25C0|\u25B6/g,\n      /\\u25C0|\\u25B6|\\u25B2|\\u25BC/g,\n      /^\\s*[<>]\\s*/,\n      /\\s*[<>]\\s*$/,\n    ];\n    let cleaned = text;\n    for (const pattern of patterns) {\n      cleaned = cleaned.replace(pattern, '');\n    }\n    cleaned = cleaned.replace(/\\s{2,}/g, ' ').trim();\n    return cleaned || text.trim();\n  }\n\n  function extractLabel(element) {\n    if (element.id) {\n      const labelFor = document.querySelector('label[for=\"' + CSS.escape(element.id) + '\"]');\n      if (labelFor) return cleanLabelText(labelFor.textContent);\n    }\n    const ariaLabel = element.getAttribute('aria-label');\n    if (ariaLabel) return cleanLabelText(ariaLabel);\n    const ariaLabelledBy = element.getAttribute('aria-labelledby');\n    if (ariaLabelledBy) {\n      const labelEl = document.getElementById(ariaLabelledBy);\n      if (labelEl) return cleanLabelText(labelEl.textContent);\n    }\n    const wrappingLabel = element.closest('label');\n    if (wrappingLabel) {\n      const clone = wrappingLabel.cloneNode(true);\n      const inputs = clone.querySelectorAll('input, select, textarea, button');\n      inputs.forEach(i => i.remove());\n      const text = clone.textContent.trim();\n      if (text) return cleanLabelText(text);\n    }\n    if (element.placeholder) return cleanLabelText(element.placeholder);\n    const title = element.getAttribute('title');\n    if (title) return cleanLabelText(title);\n    if (element.name) {\n      return element.name\n        .replace(/[_-]/g, ' ')\n        .replace(/([a-z])([A-Z])/g, '$1 $2')\n        .replace(/^./, s => s.toUpperCase());\n    }\n    return 'Unlabeled field';\n  }\n\n  function extractButtonLabel(element) {\n    const ariaLabel = element.getAttribute('aria-label');\n    if (ariaLabel) return ariaLabel.trim();\n    if (element.value && element.type !== 'submit') return element.value;\n    const text = element.textContent.trim();\n    if (text) return text;\n    if (element.value) return element.value;\n    const title = element.getAttribute('title');\n    if (title) return title;\n    return 'Button';\n  }\n\n  function getFieldValue(element) {\n    const tag = element.tagName.toLowerCase();\n    const type = element.type?.toLowerCase() || 'text';\n    if (tag === 'select') {\n      if (element.multiple) {\n        return Array.from(element.selectedOptions).map(o => o.value);\n      }\n      return element.value;\n    }\n    if (type === 'checkbox' || type === 'radio') {\n      return element.checked;\n    }\n    if (element.getAttribute('role') === 'checkbox' || element.getAttribute('role') === 'switch') {\n      return element.getAttribute('aria-checked') === 'true';\n    }\n    if (element.isContentEditable) {\n      return element.textContent || '';\n    }\n    return element.value || '';\n  }\n\n  function getFieldState(element, value) {\n    const type = element.type?.toLowerCase() || 'text';\n    if (type === 'checkbox' || element.getAttribute('role') === 'checkbox' || element.getAttribute('role') === 'switch') {\n      return value ? 'checked' : 'unchecked';\n    }\n    if (type === 'radio') {\n      return value ? 'checked' : 'unchecked';\n    }\n    if (Array.isArray(value)) {\n      return value.length > 0 ? 'filled' : 'empty';\n    }\n    if (typeof value === 'string') {\n      return value.length > 0 ? 'filled' : 'empty';\n    }\n    return 'empty';\n  }\n\n  function getFieldType(element) {\n    const tag = element.tagName.toLowerCase();\n    const role = element.getAttribute('role');\n    if (role === 'textbox') return 'textbox';\n    if (role === 'checkbox') return 'checkbox';\n    if (role === 'radio') return 'radio';\n    if (role === 'combobox') return 'combobox';\n    if (role === 'listbox') return 'listbox';\n    if (role === 'switch') return 'switch';\n    if (element.isContentEditable) return 'contenteditable';\n    if (tag === 'textarea') return 'textarea';\n    if (tag === 'select') return 'select';\n    if (tag === 'input') {\n      const type = element.type?.toLowerCase() || 'text';\n      return type;\n    }\n    return 'unknown';\n  }\n\n  function isNativeInput(element) {\n    const tag = element.tagName.toLowerCase();\n    return tag === 'input' || tag === 'textarea' || tag === 'select';\n  }\n\n  function getSelectOptions(element) {\n    if (element.tagName.toLowerCase() !== 'select') return undefined;\n    return Array.from(element.options).map(opt => ({\n      value: opt.value,\n      label: opt.textContent.trim(),\n      selected: opt.selected\n    }));\n  }\n\n  function findSiblingError(element) {\n    const next = element.nextElementSibling;\n    if (next) {\n      const isError = next.classList.contains('error') ||\n                      next.classList.contains('invalid') ||\n                      next.classList.contains('field-error') ||\n                      next.classList.contains('error-message') ||\n                      next.getAttribute('role') === 'alert';\n      if (isError) return next.textContent.trim();\n    }\n    // aria-errormessage always names the error; aria-describedby does when the\n    // field is marked invalid or the description looks like an error\n    const invalid = element.getAttribute('aria-invalid') === 'true';\n    const errorIds = (element.getAttribute('aria-errormessage') || '').split(/\\s+/).filter(Boolean);\n    const describedIds = (element.getAttribute('aria-describedby') || '').split(/\\s+/).filter(Boolean);\n    for (const id of [...errorIds, ...describedIds]) {\n      const target = document.getElementById(id);\n      const looksLikeError = errorIds.includes(id) || invalid ||\n        /error|invalid|alert/i.test(target ? target.className + ' ' + (target.getAttribute('role') || '') : '');\n      if (target && looksLikeError && target.textContent.trim()) {\n        return target.textContent.trim();\n      }\n    }\n    const parent = element.parentElement;\n    const controls = parent ? parent.querySelectorAll('input, select, textarea, [contenteditable=\"true\"]') : [];\n    if (parent && controls.length === 1) {\n      const errorEl = parent.querySelector('.error-message, .field-error, [role=\"alert\"]');\n      if (errorEl && errorEl !== element) return errorEl.textContent.trim();\n    }\n    return undefined;\n  }\n\n  function calculateRelevance(formEl, fields, buttons) {\n    let score = 0;\n    const rect = formEl.getBoundingClientRect();\n    const viewportHeight = window.innerHeight;\n    const viewportWidth = window.innerWidth;\n    const centerX = rect.left + rect.width / 2;\n    const centerY = rect.top + rect.height / 2;\n    if (centerX > viewportWidth * 0.2 && centerX < viewportWidth * 0.8) score += 10;\n    if (centerY > 0 && centerY < viewportHeight) score += 5;\n    const isInMain = formEl.closest('main, [role=\"main\"], article, .main-content, #main');\n    if (isInMain) score += 15;\n    const isInHeader = formEl.closest('header, [role=\"banner\"], nav, [role=\"navigation\"]');\n    if (isInHeader) score -= 10;\n    const isInAside = formEl.closest('aside, [role=\"complementary\"], footer, [role=\"contentinfo\"]');\n    if (isInAside) score -= 5;\n    const distinctFields = new Set(\n      fields.map((f) => (f.type === 'radio' || f.type === 'checkbox') && f.name ? f.type + ':' + f.name : f.index)\n    ).size;\n    score += Math.min(distinctFields * 3, 30);\n    const textTypes = ['text', 'search', 'email', 'password', 'textarea', 'tel', 'url', 'number', 'textbox'];\n    if (fields.some((f) => textTypes.includes(f.type))) score += 10;\n    const hasSubmit = buttons.some(b => b.type === 'submit' || b.isPrimary);\n    if (hasSubmit) score += 10;\n    const style = window.getComputedStyle(formEl);\n    if (style.display === 'none' || style.visibility === 'hidden') score -= 100;\n    return score;\n  }\n\n  function detectFormStep(formEl) {\n    const stepIndicators = formEl.querySelectorAll('[aria-current=\"step\"], .step.active, .wizard-step.current');\n    if (stepIndicators.length === 0) {\n      const pageSteps = document.querySelectorAll('.step, .wizard-step, [role=\"tablist\"] [role=\"tab\"]');\n      if (pageSteps.length > 1) {\n        const activeIndex = Array.from(pageSteps).findIndex(s =>\n          s.classList.contains('active') ||\n          s.classList.contains('current') ||\n          s.getAttribute('aria-selected') === 'true'\n        );\n        if (activeIndex >= 0) {\n          return { current: activeIndex + 1, total: pageSteps.length };\n        }\n      }\n    }\n    const ariaStep = formEl.querySelector('[aria-current=\"step\"]');\n    if (ariaStep) {\n      const allSteps = formEl.querySelectorAll('[role=\"listitem\"], .step');\n      const currentIdx = Array.from(allSteps).indexOf(ariaStep);\n      if (currentIdx >= 0) {\n        return { current: currentIdx + 1, total: allSteps.length };\n      }\n    }\n    return null;\n  }\n\n  function findNearbyHeading(formEl) {\n    let sibling = formEl.previousElementSibling;\n    let distance = 0;\n    while (sibling && distance < 3) {\n      if (sibling.matches('h1, h2, h3, h4, h5, h6, [role=\"heading\"]')) {\n        return sibling.textContent.trim();\n      }\n      const heading = sibling.querySelector('h1, h2, h3, h4, h5, h6, [role=\"heading\"]');\n      if (heading) return heading.textContent.trim();\n      sibling = sibling.previousElementSibling;\n      distance++;\n    }\n    const parent = formEl.parentElement;\n    if (parent) {\n      const heading = parent.querySelector(':scope > h1, :scope > h2, :scope > h3');\n      if (heading && heading.compareDocumentPosition(formEl) & Node.DOCUMENT_POSITION_FOLLOWING) {\n        return heading.textContent.trim();\n      }\n    }\n    return null;\n  }\n\n  function matchesWord(text, word) {\n    const pattern = new RegExp('\\\\b' + word + '\\\\b', 'i');\n    return pattern.test(text);\n  }\n\n  function inferFormType(formEl) {\n    const inputs = formEl.querySelectorAll('input, textarea, select');\n    const types = Array.from(inputs).map(i => i.type?.toLowerCase() || i.tagName.toLowerCase());\n    const names = Array.from(inputs).map(i => (i.name || '').toLowerCase());\n    const allText = (Array.from(inputs).map(i => i.name + ' ' + i.placeholder + ' ' + i.id).join(' ')).toLowerCase();\n    if (types.includes('password')) {\n      if (types.filter(t => t === 'password').length >= 2) return 'Change Password';\n      if (matchesWord(allText, 'register') || matchesWord(allText, 'signup') || matchesWord(allText, 'create')) return 'Registration';\n      return 'Login';\n    }\n    const hasSearchRole = formEl.closest('[role=\"search\"]') || formEl.getAttribute('role') === 'search';\n    const hasSearchInput = formEl.querySelector('[type=\"search\"], [aria-label*=\"search\" i]');\n    if (hasSearchRole || hasSearchInput) return 'Search';\n    const interactiveTypes = types.filter(t => !['hidden', 'submit', 'button', 'reset', 'image'].includes(t));\n    if (interactiveTypes.length <= 2 && matchesWord(allText, 'search')) return 'Search';\n    if (matchesWord(allText, 'address') || matchesWord(allText, 'street') || matchesWord(allText, 'postcode') ||\n        matchesWord(allText, 'zipcode') || matchesWord(allText, 'city') || matchesWord(allText, 'county')) {\n      return 'Address';\n    }\n    if (matchesWord(allText, 'email') && (matchesWord(allText, 'message') || matchesWord(allText, 'subject'))) {\n      return 'Contact';\n    }\n    if (matchesWord(allText, 'card') || matchesWord(allText, 'cvv') || matchesWord(allText, 'expiry')) {\n      return 'Payment';\n    }\n    if (names.some(n => matchesWord(n, 'subscribe') || matchesWord(n, 'newsletter'))) {\n      return 'Newsletter';\n    }\n    return null;\n  }\n\n  function extractFormName(formEl) {\n    const ariaLabel = formEl.getAttribute('aria-label');\n    if (ariaLabel) return ariaLabel;\n    const ariaLabelledBy = formEl.getAttribute('aria-labelledby');\n    if (ariaLabelledBy) {\n      const labelEl = document.getElementById(ariaLabelledBy);\n      if (labelEl) return labelEl.textContent.trim();\n    }\n    const headings = formEl.querySelectorAll('h1, h2, h3, h4, h5, h6, [role=\"heading\"]');\n    for (const h of headings) {\n      if (!h.closest('[role=\"dialog\"], [role=\"alertdialog\"], [aria-modal=\"true\"]')) {\n        return h.textContent.trim();\n      }\n    }\n    const title = formEl.getAttribute('title');\n    if (title) return title;\n    const name = formEl.getAttribute('name');\n    if (name) {\n      return name\n        .replace(/[_-]/g, ' ')\n        .replace(/([a-z])([A-Z])/g, '$1 $2')\n        .replace(/^./, s => s.toUpperCase());\n    }\n    const nearbyHeading = findNearbyHeading(formEl);\n    if (nearbyHeading) return nearbyHeading;\n    const inferredType = inferFormType(formEl);\n    if (inferredType) return inferredType;\n    return null;\n  }\n\n  function discoverFields(container, formIndex, startIndex) {\n    const fields = [];\n    const nativeInputs = container.querySelectorAll(\n      'input:not([type=\"hidden\"]):not([type=\"submit\"]):not([type=\"button\"]):not([type=\"reset\"]):not([type=\"image\"]), ' +\n      'textarea, ' +\n      'select'\n    );\n    const customInputs = container.querySelectorAll(\n      '[role=\"textbox\"], ' +\n      '[role=\"checkbox\"]:not(input), ' +\n      '[role=\"radio\"]:not(input), ' +\n      '[role=\"combobox\"], ' +\n      '[role=\"listbox\"], ' +\n      '[role=\"switch\"], ' +\n      '[contenteditable=\"true\"]'\n    );\n    const allInputs = new Set([...nativeInputs, ...customInputs]);\n    let idx = startIndex;\n    for (const el of allInputs) {\n      const style = window.getComputedStyle(el);\n      const isHidden = style.display === 'none' || style.visibility === 'hidden' || el.type === 'hidden';\n      const value = getFieldValue(el);\n      fields.push({\n        index: idx,\n        formIndex: formIndex,\n        selector: generateSelector(el),\n        type: getFieldType(el),\n        inputType: el.type?.toLowerCase(),\n        label: extractLabel(el),\n        name: el.name || null,\n        placeholder: el.placeholder || undefined,\n        required: el.required || el.getAttribute('aria-required') === 'true',\n        disabled: el.disabled || el.getAttribute('aria-disabled') === 'true',\n        readOnly: el.readOnly || false,\n        hidden: isHidden,\n        native: isNativeInput(el),\n        value: value,\n        checked: el.checked,\n        validationMessage: el.validationMessage || undefined,\n        isValid: el.validity ? el.validity.valid : true,\n        valueMissing: el.validity ? el.validity.valueMissing : false,\n        ariaInvalid: el.getAttribute('aria-invalid') === 'true',\n        hasErrorClass: el.classList.contains('error') || el.classList.contains('invalid'),\n        siblingErrorText: findSiblingError(el),\n        options: getSelectOptions(el)\n      });\n      idx++;\n    }\n    return fields;\n  }\n\n  function discoverButtons(container, startIndex) {\n    const buttons = [];\n    const buttonEls = container.querySelectorAll(\n      'button, ' +\n      'input[type=\"submit\"], ' +\n      'input[type=\"button\"], ' +\n      'input[type=\"reset\"], ' +\n      '[role=\"button\"]'\n    );\n    let idx = startIndex;\n    for (const el of buttonEls) {\n      const style = window.getComputedStyle(el);\n      if (style.display === 'none' || style.visibility === 'hidden') continue;\n      const type = el.type?.toLowerCase() || 'button';\n      const btnType = type === 'submit' ? 'submit' : type === 'reset' ? 'reset' : 'button';\n      const isPrimary = btnType === 'submit' ||\n                        el.classList.contains('primary') ||\n                        el.classList.contains('btn-primary') ||\n                        el.classList.contains('submit');\n      buttons.push({\n        index: idx,\n        selector: generateSelector(el),\n        label: extractButtonLabel(el),\n        type: btnType,\n        disabled: el.disabled || el.getAttribute('aria-disabled') === 'true',\n        isPrimary: isPrimary\n      });\n      idx++;\n    }\n    return buttons;\n  }\n\n  const forms = document.querySelectorAll('form');\n  let globalIndex = 0;\n\n  if (forms.length === 0) {\n    const bodyFields = discoverFields(document.body, 0, 0);\n    const bodyButtons = discoverButtons(document.body, bodyFields.length);\n    if (bodyFields.length > 0) {\n      result.forms.push({\n        index: 0,\n        name: document.title || 'Page',\n        action: null,\n        method: 'GET',\n        step: null,\n        relevanceScore: bodyFields.length * 3,\n        inIframe: false,\n        fields: bodyFields,\n        buttons: bodyButtons\n      });\n    }\n  } else {\n    for (let i = 0; i < forms.length; i++) {\n      const formEl = forms[i];\n      const fields = discoverFields(formEl, i, globalIndex);\n      globalIndex += fields.length;\n      const buttons = discoverButtons(formEl, globalIndex);\n      globalIndex += buttons.length;\n      const inIframe = formEl.ownerDocument !== document;\n      result.forms.push({\n        index: i,\n        name: extractFormName(formEl),\n        action: formEl.action || null,\n        method: (formEl.method || 'GET').toUpperCase(),\n        step: detectFormStep(formEl),\n        relevanceScore: calculateRelevance(formEl, fields, buttons),\n        inIframe: inIframe,\n        fields: fields,\n        buttons: buttons\n      });\n    }\n  }\n\n  result.forms.sort((a, b) => b.relevanceScore - a.relevanceScore);\n\n  // Forms the main document does not contain may be in its same-origin iframes\n  if (result.forms.length === 0) {\n    result.frameForms = [];\n    for (const frame of document.querySelectorAll('iframe, frame')) {\n      let frameDocument = null;\n      try { frameDocument = frame.contentDocument; } catch (e) { frameDocument = null; }\n      if (frameDocument && frameDocument.querySelector('form, input:not([type=hidden]), select, textarea')) {\n        result.frameForms.push({ url: frame.src || 'about:blank' });\n      }\n    }\n  }\n\n  return result;\n})()\n";
+/**
+ * Type guard for raw form data.
+ *
+ * @param value - Unknown value to check
+ * @returns True if value matches RawFormData structure
+ */
+export declare function isRawFormData(value: unknown): value is RawFormData;
+//# sourceMappingURL=formDiscovery.d.ts.map

package/dist/{commands → runtime}/dom/formDiscovery.js

@@ -18,13 +18,23 @@ export const FORM_DISCOVERY_SCRIPT = `
 (function() {
   const result = { forms: [] };
 
+  function isUnique(selector) {
+    try {
+      return document.querySelectorAll(selector).length === 1;
+    } catch (e) {
+      return false;
+    }
+  }
+
   function generateSelector(element) {
-    if (element.id) {
+    if (element.id && isUnique('#' + CSS.escape(element.id))) {
       return '#' + CSS.escape(element.id);
     }
     if (element.name) {
-      const tag = element.tagName.toLowerCase();
-      return tag + '[name="' + CSS.escape(element.name) + '"]';
+      const byName = element.tagName.toLowerCase() + '[name="' + CSS.escape(element.name) + '"]';
+      if (isUnique(byName)) return byName;
+      const byValue = byName + '[value="' + CSS.escape(element.getAttribute('value') || '') + '"]';
+      if (element.hasAttribute('value') && isUnique(byValue)) return byValue;
     }
     const tag = element.tagName.toLowerCase();
     const parent = element.parentElement;
@@ -48,7 +58,6 @@ export const FORM_DISCOVERY_SCRIPT = `
       /\\bchevron\\b/gi,
       /←|→|↑|↓|▲|▼|◀|▶/g,
       /\\u25C0|\\u25B6|\\u25B2|\\u25BC/g,
-      /Previous|Next|Back|Forward/gi,
       /^\\s*[<>]\\s*/,
       /\\s*[<>]\\s*$/,
     ];
@@ -185,8 +194,22 @@ export const FORM_DISCOVERY_SCRIPT = `
                       next.getAttribute('role') === 'alert';
       if (isError) return next.textContent.trim();
     }
+    // aria-errormessage always names the error; aria-describedby does when the
+    // field is marked invalid or the description looks like an error
+    const invalid = element.getAttribute('aria-invalid') === 'true';
+    const errorIds = (element.getAttribute('aria-errormessage') || '').split(/\\s+/).filter(Boolean);
+    const describedIds = (element.getAttribute('aria-describedby') || '').split(/\\s+/).filter(Boolean);
+    for (const id of [...errorIds, ...describedIds]) {
+      const target = document.getElementById(id);
+      const looksLikeError = errorIds.includes(id) || invalid ||
+        /error|invalid|alert/i.test(target ? target.className + ' ' + (target.getAttribute('role') || '') : '');
+      if (target && looksLikeError && target.textContent.trim()) {
+        return target.textContent.trim();
+      }
+    }
     const parent = element.parentElement;
-    if (parent) {
+    const controls = parent ? parent.querySelectorAll('input, select, textarea, [contenteditable="true"]') : [];
+    if (parent && controls.length === 1) {
       const errorEl = parent.querySelector('.error-message, .field-error, [role="alert"]');
       if (errorEl && errorEl !== element) return errorEl.textContent.trim();
     }
@@ -208,7 +231,12 @@ export const FORM_DISCOVERY_SCRIPT = `
     if (isInHeader) score -= 10;
     const isInAside = formEl.closest('aside, [role="complementary"], footer, [role="contentinfo"]');
     if (isInAside) score -= 5;
-    score += Math.min(fields.length * 3, 30);
+    const distinctFields = new Set(
+      fields.map((f) => (f.type === 'radio' || f.type === 'checkbox') && f.name ? f.type + ':' + f.name : f.index)
+    ).size;
+    score += Math.min(distinctFields * 3, 30);
+    const textTypes = ['text', 'search', 'email', 'password', 'textarea', 'tel', 'url', 'number', 'textbox'];
+    if (fields.some((f) => textTypes.includes(f.type))) score += 10;
     const hasSubmit = buttons.some(b => b.type === 'submit' || b.isPrimary);
     if (hasSubmit) score += 10;
     const style = window.getComputedStyle(formEl);
@@ -314,8 +342,6 @@ export const FORM_DISCOVERY_SCRIPT = `
         return h.textContent.trim();
       }
     }
-    const legend = formEl.querySelector('legend');
-    if (legend) return legend.textContent.trim();
     const title = formEl.getAttribute('title');
     if (title) return title;
     const name = formEl.getAttribute('name');
@@ -371,7 +397,8 @@ export const FORM_DISCOVERY_SCRIPT = `
         value: value,
         checked: el.checked,
         validationMessage: el.validationMessage || undefined,
-        isValid: el.checkValidity ? el.checkValidity() : true,
+        isValid: el.validity ? el.validity.valid : true,
+        valueMissing: el.validity ? el.validity.valueMissing : false,
         ariaInvalid: el.getAttribute('aria-invalid') === 'true',
         hasErrorClass: el.classList.contains('error') || el.classList.contains('invalid'),
         siblingErrorText: findSiblingError(el),
@@ -457,6 +484,18 @@ export const FORM_DISCOVERY_SCRIPT = `
 
   result.forms.sort((a, b) => b.relevanceScore - a.relevanceScore);
 
+  // Forms the main document does not contain may be in its same-origin iframes
+  if (result.forms.length === 0) {
+    result.frameForms = [];
+    for (const frame of document.querySelectorAll('iframe, frame')) {
+      let frameDocument = null;
+      try { frameDocument = frame.contentDocument; } catch (e) { frameDocument = null; }
+      if (frameDocument && frameDocument.querySelector('form, input:not([type=hidden]), select, textarea')) {
+        result.frameForms.push({ url: frame.src || 'about:blank' });
+      }
+    }
+  }
+
   return result;
 })()
 `;

package/dist/runtime/dom/formFillHelpers/fill.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Fill and click operations — inject React-compatible page-context scripts
+ * and unpack structured results.
+ */
+import type { CDPConnection } from '../../../connection/cdp.js';
+import { type FillOptions, type FillResult, type ClickResult } from '../reactEventHelpers.js';
+/**
+ * Fill a form element with a value in a React-compatible way.
+ */
+export declare function fillElement(cdp: CDPConnection, selector: string, value: string, options?: FillOptions): Promise<FillResult>;
+/** How a located element is pointed at */
+export type PointerAction = 'click' | 'double' | 'right' | 'hover';
+/**
+ * Real mouse events for an action at a point.
+ *
+ * @param action - What to do
+ * @param x - Page x
+ * @param y - Page y
+ * @returns `Input.dispatchMouseEvent` parameters, in order
+ */
+export declare function mouseEvents(action: PointerAction, x: number, y: number): Array<Record<string, unknown>>;
+/**
+ * Click an element.
+ */
+export declare function clickElement(cdp: CDPConnection, selector: string, options?: {
+    index?: number;
+    action?: PointerAction;
+}): Promise<ClickResult>;
+//# sourceMappingURL=fill.d.ts.map