browser-debugger-cli 0.8.0 → 0.9.0

package/dist/runtime/dom/reactEventHelpers.js

@@ -5,7 +5,96 @@
  * This module provides JavaScript snippets that can be injected via Runtime.evaluate
  * to properly trigger React's event system.
  */
-import { FIND_ELEMENTS_JS } from './targetNode.js';
+import { FILL_REFUSALS, LABEL_WITHOUT_CONTROL, NAME_QUERY_PLACEHOLDER, VIA_LABEL_SUFFIX, } from '../../errors/messages.js';
+import { ELEMENT_DESCRIPTION_JS, ELEMENT_IDENTITY_JS } from './elementInfo.js';
+import { FIND_ELEMENTS_JS, LABEL_CONTROL_JS } from './targetNode.js';
+/**
+ * Page-side read-back of a filled field: a mismatch when its value is not
+ * what was asked for (the page rejected, reformatted or moved the input),
+ * undefined when it is. Values are compared as the browser normalises them:
+ * colors case-insensitively, numbers and ranges as numbers, email trimmed,
+ * textarea line endings as `\n`, times and local date-times without zero
+ * seconds and with `T` (`2024-01-05 10:00:00` is `2024-01-05T10:00`).
+ * Checkboxes and radios compare as `checked`/`unchecked`, a multiple select
+ * as its selected values joined by ", ", contenteditable text with
+ * whitespace collapsed. A value cut to the field's maxlength sets
+ * `truncatedTo`; a password mismatch gives masked values and both lengths.
+ */
+export const FILL_VALUE_MISMATCH_JS = `(field, expected) => {
+  const type = (field.type || '').toLowerCase();
+  const actual = field.isContentEditable
+    ? (field.textContent || '')
+    : type === 'checkbox' || type === 'radio'
+      ? (field.checked ? 'checked' : 'unchecked')
+      : field.localName === 'select' && field.multiple
+        ? Array.from(field.selectedOptions).map((o) => o.value).join(', ')
+        : String(field.value);
+  const time = (text) => text.trim().replace(' ', 'T').replace(/(\\d\\d:\\d\\d):00(\\.0+)?$/, '$1');
+  const normalize = (text) => {
+    text = String(text);
+    if (field.isContentEditable) return text.replace(/\\s+/g, ' ').trim();
+    if (field.localName === 'textarea') return text.replace(/\\r\\n?/g, '\\n');
+    if (type === 'color') return text.trim().toLowerCase();
+    if (type === 'email') return text.trim();
+    if (type === 'time' || type === 'datetime-local') return time(text);
+    return text;
+  };
+  const numeric = (type === 'number' || type === 'range') && actual.trim() !== '' && String(expected).trim() !== '';
+  const same = numeric ? Number(actual) === Number(expected) : normalize(actual) === normalize(expected);
+  if (same) return undefined;
+  if (type === 'password') {
+    const mask = (text) => (text === '' ? '' : '********');
+    return { expected: mask(expected), actual: mask(actual), expectedLength: expected.length, actualLength: actual.length };
+  }
+  const cut = field.maxLength > 0 && actual.length === field.maxLength && expected.length > actual.length &&
+    expected.startsWith(actual);
+  return cut ? { expected: expected, actual: actual, truncatedTo: actual.length } : { expected: expected, actual: actual };
+}`;
+/**
+ * Page-side list of the other text-like fields of a field's form (of the
+ * document when it has none), with their values: taken before a fill, so
+ * {@link MOVED_VALUE_JS} can tell which one the page changed.
+ */
+export const FIELD_VALUES_JS = `(field) => {
+  const fields = field.form ? Array.from(field.form.elements) : Array.from(field.ownerDocument.querySelectorAll('input, textarea'));
+  return new Map(fields
+    .filter((f) => f !== field && /^(input|textarea)$/.test(f.localName) &&
+      !/^(checkbox|radio|password|hidden|submit|button|reset|file|image)$/i.test(f.type || ''))
+    .map((f) => [f, String(f.value)]));
+}`;
+/**
+ * Page-side reason `dom fill` cannot fill an element, or null when it can:
+ * a disabled or read-only form control (naming the attribute or the disabled
+ * `<fieldset>`), or for any other element the switch that keeps it from being
+ * editable: `contenteditable="false"` (on it or the editor around it), an
+ * `inert` ancestor, `aria-readonly` or `aria-disabled`; otherwise it is not a
+ * fillable kind of element. Messages are {@link FILL_REFUSALS}.
+ */
+export const FILL_REFUSAL_JS = `(el) => {
+  const describe = ${ELEMENT_DESCRIPTION_JS};
+  const refusals = ${JSON.stringify(FILL_REFUSALS)};
+  const refuse = (kind, cause) => ({
+    kind: kind,
+    error: refusals[kind].message + (cause ? ' (' + cause + ')' : ''),
+    suggestion: refusals[kind].suggestion
+  });
+  const tag = el.localName;
+  if (tag === 'input' || tag === 'textarea' || tag === 'select') {
+    if (el.disabled || el.matches(':disabled')) {
+      return refuse('disabled', el.hasAttribute('disabled') ? 'disabled attribute' : el.closest('fieldset[disabled]') ? 'inside a disabled <fieldset>' : '');
+    }
+    return el.readOnly ? refuse('readOnly', 'readonly attribute') : null;
+  }
+  if (el.isContentEditable) return null;
+  const host = el.closest('[contenteditable]');
+  if (host && String(host.getAttribute('contenteditable')).trim().toLowerCase() === 'false') {
+    return refuse('readOnly', 'contenteditable="false"' + (host === el ? '' : ' on ' + describe(host)));
+  }
+  if (el.closest('[inert]')) return refuse('inert', 'inside an inert element');
+  if (el.getAttribute('aria-readonly') === 'true') return refuse('readOnly', 'aria-readonly="true"');
+  if (el.getAttribute('aria-disabled') === 'true') return refuse('disabled', 'aria-disabled="true"');
+  return refuse('notFillable', '<' + tag + '> is not an input, textarea, select or contenteditable element');
+}`;
 /**
  * JavaScript function to fill an input element in a React-compatible way.
  *
@@ -14,6 +103,13 @@ import { FIND_ELEMENTS_JS } from './targetNode.js';
  * 2. Dispatches input/change events that React listens for
  * 3. Properly handles focus/blur for form validation
  *
+ * A `<label>` is filled through its control ({@link LABEL_CONTROL_JS}),
+ * reported as e.g. `input (via label)`.
+ *
+ * The result is returned right away (a change handler may navigate). The
+ * field and the value to expect are left in `window.__bdgFillCheck` for
+ * {@link FILL_READ_BACK_SCRIPT}, which reads the value back a moment later.
+ *
  * @remarks
  * Works with React, Vue, Angular, and vanilla JS applications.
  */
@@ -21,11 +117,14 @@ export const REACT_FILL_SCRIPT = `
 (function(selector, parts, value, options) {
   const allMatches = (${FIND_ELEMENTS_JS})(selector, parts);
   const warnings = [];
+  let expected = value;
   // Why a user could not reach the field (the value is still set, so scripted
   // flows keep working, but the result may not be what a user would see)
   const unreachableReason = (field) => {
     if (field.closest('[inert]')) return 'inert';
-    const modal = field.ownerDocument.querySelector('dialog:modal');
+    const shown = (node) => !node.checkVisibility || node.checkVisibility();
+    const modal = field.ownerDocument.querySelector('dialog:modal') ||
+      Array.from(field.ownerDocument.querySelectorAll('[aria-modal="true"]')).find(shown);
     if (modal && !modal.contains(field)) return 'behind an open modal dialog';
     if (field.checkVisibility && !field.checkVisibility({ visibilityProperty: true, opacityProperty: true })) return 'hidden';
     return null;
@@ -84,40 +183,33 @@ export const REACT_FILL_SCRIPT = `
   } else {
     el = allMatches[0];
   }
-  
-  const tagName = el.tagName.toLowerCase();
-  const inputType = el.type?.toLowerCase();
-  
-  const isFillable = (
-    tagName === 'input' || 
-    tagName === 'textarea' || 
-    tagName === 'select' ||
-    el.isContentEditable
-  );
-  
-  if (!isFillable) {
-    return {
-      success: false,
-      error: 'Element is not fillable',
-      elementType: tagName,
-      suggestion: 'Only input, textarea, select, and contenteditable elements can be filled'
-    };
-  }
 
-  if (el.disabled || el.matches(':disabled')) {
+  const labelControl = (${LABEL_CONTROL_JS})(el);
+  if (el.localName === 'label' && !labelControl) {
+    const quote = (text) => "'" + String(text).split("'").join("'\\\\''") + "'";
+    const labelText = (el.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 60);
     return {
       success: false,
-      error: 'Element is disabled',
-      elementType: tagName,
-      suggestion: 'Enable the field first (it may depend on another input)'
+      error: ${JSON.stringify(LABEL_WITHOUT_CONTROL.message)},
+      elementType: 'label',
+      unsuitableElement: true,
+      suggestion: ${JSON.stringify(LABEL_WITHOUT_CONTROL.suggestion)}.split(${JSON.stringify(NAME_QUERY_PLACEHOLDER)}).join(quote('name=' + labelText))
     };
   }
-  if (el.readOnly) {
+  const viaLabel = labelControl ? ${JSON.stringify(VIA_LABEL_SUFFIX)} : '';
+  if (labelControl) el = labelControl;
+
+  const tagName = el.tagName.toLowerCase();
+  const inputType = el.type?.toLowerCase();
+
+  const refusal = (${FILL_REFUSAL_JS})(el);
+  if (refusal) {
     return {
       success: false,
-      error: 'Element is read-only',
-      elementType: tagName,
-      suggestion: 'Read-only fields cannot be filled'
+      error: refusal.error,
+      elementType: tagName + viaLabel,
+      suggestion: refusal.suggestion,
+      unsuitableElement: refusal.kind === 'notFillable'
     };
   }
 
@@ -126,6 +218,7 @@ export const REACT_FILL_SCRIPT = `
     warnings.push('The field is ' + unreachable + '; a user could not fill it (the value was set anyway)');
   }
 
+  const fieldsBefore = (${FIELD_VALUES_JS})(el);
   el.focus();
 
   if (tagName === 'select' && el.multiple) {
@@ -143,11 +236,12 @@ export const REACT_FILL_SCRIPT = `
         success: false,
         error: 'Option not found: ' + missing,
         exitCode: 81,
-        elementType: tagName,
+        elementType: tagName + viaLabel,
         suggestion: 'Available options: ' + options.slice(0, 10).map((o) => o.value || o.text.trim()).join(', ')
       };
     }
     options.forEach((o) => { o.selected = chosen.includes(o); });
+    expected = chosen.map((o) => o.value).join(', ');
     el.dispatchEvent(new Event('input', { bubbles: true }));
     el.dispatchEvent(new Event('change', { bubbles: true }));
   } else if (tagName === 'select') {
@@ -161,11 +255,12 @@ export const REACT_FILL_SCRIPT = `
         success: false,
         error: 'Option not found: ' + value,
         exitCode: 81,
-        elementType: tagName,
+        elementType: tagName + viaLabel,
         suggestion: 'Available options: ' + options.slice(0, 10).map((o) => o.value || o.text.trim()).join(', ')
       };
     }
     el.value = option.value;
+    expected = option.value;
     el.dispatchEvent(new Event('input', { bubbles: true }));
     el.dispatchEvent(new Event('change', { bubbles: true }));
   } else if (inputType === 'checkbox' || inputType === 'radio') {
@@ -178,7 +273,7 @@ export const REACT_FILL_SCRIPT = `
       return {
         success: false,
         error: 'Expected true or false for a ' + inputType + ', got "' + value + '"',
-        elementType: tagName,
+        elementType: tagName + viaLabel,
         inputType: inputType,
         suggestion: 'Use true/false (also yes/no, on/off, 1/0)'
       };
@@ -188,11 +283,12 @@ export const REACT_FILL_SCRIPT = `
       return {
         success: false,
         error: 'A radio button cannot be unchecked',
-        elementType: tagName,
+        elementType: tagName + viaLabel,
         inputType: inputType,
         suggestion: 'Select another option in the same group instead'
       };
     }
+    expected = shouldCheck ? 'checked' : 'unchecked';
     if (el.checked !== shouldCheck) {
       el.click();
     }
@@ -200,7 +296,7 @@ export const REACT_FILL_SCRIPT = `
     return {
       success: false,
       fileInput: true,
-      elementType: tagName,
+      elementType: tagName + viaLabel,
       inputType: inputType,
       error: 'File input'
     };
@@ -226,7 +322,7 @@ export const REACT_FILL_SCRIPT = `
       return {
         success: false,
         error: 'Value is ' + value.length + ' characters; the field accepts at most ' + el.maxLength,
-        elementType: tagName,
+        elementType: tagName + viaLabel,
         inputType: inputType || null,
         suggestion: 'Shorten the value (a user could not type more than maxlength characters)'
       };
@@ -242,7 +338,7 @@ export const REACT_FILL_SCRIPT = `
       return {
         success: false,
         error: rejection.error,
-        elementType: tagName,
+        elementType: tagName + viaLabel,
         inputType: inputType,
         suggestion: rejection.suggestion
       };
@@ -258,7 +354,8 @@ export const REACT_FILL_SCRIPT = `
   if (options.blur !== false) {
     el.blur();
   }
-  
+  window.__bdgFillCheck = { el: el, expected: expected, before: fieldsBefore };
+
   return {
     success: true,
     selector: selector,
@@ -269,7 +366,8 @@ export const REACT_FILL_SCRIPT = `
         : tagName === 'select' && el.multiple
           ? Array.from(el.selectedOptions).map((o) => o.value).join(', ')
           : el.value,
-    elementType: tagName,
+    element: (${ELEMENT_IDENTITY_JS})(el),
+    elementType: tagName + viaLabel,
     inputType: inputType || null,
     checked: inputType === 'checkbox' || inputType === 'radio' ? el.checked : undefined,
     matchCount: allMatches.length,
@@ -279,6 +377,52 @@ export const REACT_FILL_SCRIPT = `
   };
 })
 `;
+/**
+ * Page-side search for the field a moved value went to: one of the fields
+ * recorded before the fill ({@link FIELD_VALUES_JS}) whose value changed to
+ * the one given (trimmed, at least 2 characters). Evaluates to its id or
+ * name (`input#first-name`, `input[name="first"]`) or else its
+ * description, or undefined. Passwords are never searched for.
+ */
+export const MOVED_VALUE_JS = `(field, expected, before) => {
+  const wanted = String(expected).trim();
+  if (!before || wanted.length < 2 || (field.type || '').toLowerCase() === 'password') return undefined;
+  const other = Array.from(before.keys()).find((f) =>
+    String(f.value).trim() === wanted && String(before.get(f)).trim() !== wanted);
+  if (!other) return undefined;
+  if (other.id) return other.localName + '#' + other.id;
+  return other.name ? other.localName + '[name="' + other.name + '"]' : (${ELEMENT_DESCRIPTION_JS})(other);
+}`;
+/**
+ * Page script reading back the field the last fill left in
+ * `window.__bdgFillCheck`, after one macrotask (so frameworks that render
+ * asynchronously have updated it). The macrotask comes from a
+ * `MessageChannel`, which fake timers and page code rarely replace. Evaluates
+ * to the mismatch ({@link FILL_VALUE_MISMATCH_JS}), with `movedTo` when the
+ * value turned up in another field ({@link MOVED_VALUE_JS}), or null when the
+ * value matches, nothing was left (the page navigated) or the field left the
+ * page.
+ */
+export const FILL_READ_BACK_SCRIPT = `(() => {
+  const check = window.__bdgFillCheck;
+  delete window.__bdgFillCheck;
+  if (!check) return null;
+  const readBack = () => {
+    if (!check.el.isConnected) return null;
+    const mismatch = (${FILL_VALUE_MISMATCH_JS})(check.el, check.expected);
+    if (!mismatch) return null;
+    const movedTo = (${MOVED_VALUE_JS})(check.el, check.expected, check.before);
+    return movedTo ? Object.assign(mismatch, { movedTo: movedTo }) : mismatch;
+  };
+  return new Promise((resolve) => {
+    const channel = new MessageChannel();
+    channel.port1.onmessage = () => {
+      channel.port1.close();
+      resolve(readBack());
+    };
+    channel.port2.postMessage(null);
+  });
+})()`;
 /**
  * JavaScript function to locate an element for clicking.
  *
@@ -291,9 +435,15 @@ export const REACT_FILL_SCRIPT = `
  * Handles both direct selector matching and indexed selection.
  * When index is provided, selects the nth matching element (0-based).
  * When selector matches multiple elements without index, prioritizes visible ones.
+ * A `<label>` is clicked (and double-clicked) through its control when that
+ * is visible ({@link LABEL_CONTROL_JS}), reported as e.g. `input (via label)`.
  */
 export const CLICK_ELEMENT_SCRIPT = `
 (function(selector, parts, index, action) {
+  if (window.__bdgPressProbe) {
+    window.__bdgPressProbe.stop();
+    delete window.__bdgPressProbe;
+  }
   const allMatches = (${FIND_ELEMENTS_JS})(selector, parts);
   
   if (allMatches.length === 0) {
@@ -343,6 +493,14 @@ export const CLICK_ELEMENT_SCRIPT = `
     }
   }
   
+  const labelControl = action === 'click' || action === 'double' ? (${LABEL_CONTROL_JS})(el) : null;
+  const viaLabel = labelControl &&
+    (typeof labelControl.checkVisibility !== 'function' || labelControl.checkVisibility({ visibilityProperty: true, opacityProperty: true })) &&
+    labelControl.getClientRects().length > 0
+    ? ${JSON.stringify(VIA_LABEL_SUFFIX)}
+    : '';
+  if (viaLabel) el = labelControl;
+
   const tagName = el.tagName.toLowerCase();
   if (tagName === 'option') {
     const quote = (text) => "'" + String(text).split("'").join("'\\\\''") + "'";
@@ -352,7 +510,7 @@ export const CLICK_ELEMENT_SCRIPT = `
       success: false,
       error: 'An <option> is chosen through its <select>, not clicked',
       selector: selector,
-      elementType: tagName,
+      elementType: tagName + viaLabel,
       exitCode: 81,
       suggestion: 'bdg dom fill ' + quote(target) + ' ' + quote(el.value || el.text.trim())
     };
@@ -363,7 +521,7 @@ export const CLICK_ELEMENT_SCRIPT = `
       success: false,
       error: 'Element is disabled',
       selector: selector,
-      elementType: tagName,
+      elementType: tagName + viaLabel,
       suggestion: 'A user cannot click a disabled element; enable it first (it may depend on other fields)'
     };
   }
@@ -430,10 +588,23 @@ export const CLICK_ELEMENT_SCRIPT = `
   else if (!hasSize) obstruction = 'zero-size';
   else if (!hittable) obstruction = 'covered by another element' + coveredBy();
 
+  // Records whether the coming mouse press reaches the element at all; a
+  // browser dialog or bubble can swallow input while the page looks normal.
+  if (hittable && action !== 'hover') {
+    const probe = { reached: false };
+    const markReached = (event) => {
+      if (event.composedPath().includes(el)) probe.reached = true;
+    };
+    ['pointerdown', 'mousedown'].forEach((type) => view.addEventListener(type, markReached, true));
+    probe.stop = () => ['pointerdown', 'mousedown'].forEach((type) => view.removeEventListener(type, markReached, true));
+    window.__bdgPressProbe = probe;
+  }
+
   return {
     success: true,
     selector: selector,
-    elementType: tagName,
+    element: (${ELEMENT_IDENTITY_JS})(el),
+    elementType: tagName + viaLabel,
     matchCount: allMatches.length,
     selectedIndex: typeof index === 'number' ? index : undefined,
     x: x,

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

@@ -9,27 +9,75 @@
  * {@link BOUND_TARGET_SELECTOR}.
  */
 import type { CDPConnection } from '../../connection/cdp.js';
+import { CommandError } from '../../errors/index.js';
 /** Selector placeholder that makes page scripts use the bound node. */
 export declare const BOUND_TARGET_SELECTOR = "__bdg_bound_target__";
+/** Removes the node bound for index-based commands from the window it was stored on */
+export declare const UNBIND_TARGET_SCRIPT = "delete window.__bdgTarget";
+/**
+ * Page-side matching of filters ({@link SelectorFilter}) and scoped steps
+ * ({@link ScopedStep}): called with the open shadow roots of the page, returns
+ * `{ passesAll, descend }`.
+ *
+ * Visible means rendered (`checkVisibility()`: not inside a closed
+ * `<details>` or under `content-visibility: hidden`), a non-empty box and
+ * `visibility: visible`, as in Playwright (`opacity: 0` still counts as
+ * visible). Text is the rendered text (`innerText`) of visible elements and
+ * the text nodes of hidden ones (display or visibility; not those of
+ * `<script>`, `<style>` or `<noscript>`), so text filters match hidden
+ * elements like Playwright's and `:visible` decides visibility; button inputs
+ * use their value. Whitespace is collapsed; filter texts arrive normalized
+ * (`has-text` lowercased). `:visible` is checked before the text filters,
+ * which read the text.
+ *
+ * Steps and `:has()` match CSS relative to an element (`:scope > css`). A
+ * descendant step also searches the open shadow roots under the element (the
+ * whole step CSS inside one shadow tree); a child step stays in the
+ * element's own tree.
+ */
+export declare const FILTER_MATCHING_JS = "(shadowRoots) => {\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const walker = el.ownerDocument.createTreeWalker(el, 5, {\n      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)\n    });\n    let text = '';\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.nodeType === 3) text += node.data;\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n}";
 /**
  * Page-side selector search that also reaches into open shadow roots and
  * same-origin iframes (recursively), like a user sees the page.
  *
  * Takes the selector and, when it has text or visibility filters, its parts
  * from {@link parseSelectorFilters}: their CSS runs as one selector list and
- * a match is kept when it passes the filters of a part it matches.
- * Matches of the document come first, then those of each shadow root and
- * frame in document order. Cross-origin iframes are separate processes and
- * cannot be searched. Throws a `SyntaxError` for an invalid selector.
+ * a match is kept when it passes the filters of a part it matches; a part
+ * with scoped steps contributes the steps' matches under it instead (each
+ * element once). Matches come in document order: those of the document
+ * first, then those of each shadow root and frame in the order they are
+ * reached. Cross-origin iframes are separate processes and cannot be
+ * searched. Throws a `SyntaxError` for an invalid selector.
  */
-export declare const DEEP_QUERY_JS = "function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const visit = (root) => {\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const passes = (el, filter) => {\n  if (filter.kind === 'visible') {\n    const rect = el.getBoundingClientRect();\n    return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n  }\n  const text = (typeof el.innerText === 'string' ? el.innerText : el.textContent || '').replace(/\\s+/g, ' ').trim();\n  return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n};\n  return found.filter((el) => parts.some((part) => el.matches(part.css) && part.filters.every((filter) => passes(el, filter))));\n}";
+export declare const DEEP_QUERY_JS = "function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const walker = el.ownerDocument.createTreeWalker(el, 5, {\n      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)\n    });\n    let text = '';\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.nodeType === 3) text += node.data;\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n}";
 /**
  * Page-side element lookup shared by the interaction scripts.
  *
  * Returns the bound node (if still in the page) for the placeholder selector,
  * otherwise all matches of the selector ({@link DEEP_QUERY_JS}).
  */
-export declare const FIND_ELEMENTS_JS = "function (selector, parts) {\n  if (selector === '__bdg_bound_target__') {\n    const el = window.__bdgTarget;\n    return el && el.isConnected ? [el] : [];\n  }\n  return (function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const visit = (root) => {\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const passes = (el, filter) => {\n  if (filter.kind === 'visible') {\n    const rect = el.getBoundingClientRect();\n    return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n  }\n  const text = (typeof el.innerText === 'string' ? el.innerText : el.textContent || '').replace(/\\s+/g, ' ').trim();\n  return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n};\n  return found.filter((el) => parts.some((part) => el.matches(part.css) && part.filters.every((filter) => passes(el, filter))));\n})(selector, parts);\n}";
+export declare const FIND_ELEMENTS_JS = "function (selector, parts) {\n  if (selector === '__bdg_bound_target__') {\n    const el = window.__bdgTarget;\n    return el && el.isConnected ? [el] : [];\n  }\n  return (function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const walker = el.ownerDocument.createTreeWalker(el, 5, {\n      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)\n    });\n    let text = '';\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.nodeType === 3) text += node.data;\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n})(selector, parts);\n}";
+/**
+ * Page-side check of what selectors cannot search in the top document:
+ * iframes whose document cannot be read (cross-origin) and `<object>`/`<embed>`
+ * elements. Cheap: no frame is entered.
+ */
+export declare const UNSEARCHED_CONTENT_JS = "(() => {\n  const frames = Array.from(document.querySelectorAll('iframe, frame'));\n  const unreadable = (frame) => {\n    try { return !frame.contentDocument; } catch (e) { return true; }\n  };\n  return { crossOriginFrames: frames.some(unreadable), embeds: !!document.querySelector('object, embed') };\n})()";
+/**
+ * Page-side ids (`kind` "id") or classes (`kind` "class") in the top
+ * document, from the first {@link NAME_SCAN_LIMIT} elements that have one.
+ *
+ * @param kind - Which names to read
+ * @returns Expression evaluating to the distinct names
+ */
+export declare function pageNamesJS(kind: 'id' | 'class'): string;
+/**
+ * Page-side: the form control a `<label>` stands for (`label.control`: its
+ * `for` target or the control inside it), or null for other elements and
+ * labels without one. Fill, click and key presses act on that control, like
+ * Playwright.
+ */
+export declare const LABEL_CONTROL_JS = "(el) => (el && el.localName === 'label' ? el.control : null)";
 /**
  * Arguments for {@link DEEP_QUERY_JS} / {@link FIND_ELEMENTS_JS} and the page
  * scripts built on them: the selector as a JS string literal and its parts
@@ -37,42 +85,47 @@ export declare const FIND_ELEMENTS_JS = "function (selector, parts) {\n  if (sel
  *
  * @param selector - Selector as the user gave it (or the bound-node placeholder)
  * @returns JS source of the two arguments, e.g. `"li:visible", [{...}]`
- * @throws CommandError (81) for a misplaced or malformed filter
+ * @throws CommandError (81) for an empty selector or a misplaced or malformed filter
  */
 export declare function selectorArgsJS(selector: string): string;
-/** Selector and index the page scripts should use. */
+/** Selector and index the page scripts should use, and the connection to run them on. */
 export interface ScriptTarget {
     selector: string;
     index?: number;
+    /** Connection for the page scripts (scoped to the element's frame when the top page cannot reach it) */
+    cdp: CDPConnection;
 }
 /**
- * Make the node with `backendNodeId` the target of the next page script.
- *
- * @param cdp - CDP connection
- * @param backendNodeId - Backend node id from the query cache
- * @throws CommandError (exit 87) when the node no longer exists in the page
- */
-export declare function bindTargetNode(cdp: CDPConnection, backendNodeId: number): Promise<void>;
-/**
- * Resolve what a page script should target for an interaction request.
+ * Run an interaction on the element a request targets. Results and errors
+ * never show the internal placeholder: a bound node the page scripts could
+ * not find is reported as stale (87), and results carry the user's selector.
  *
  * @param cdp - CDP connection
  * @param params - Request with a selector (and optional index) or a backend node id
- * @returns Selector/index for the page script
+ * @param work - The interaction, given the script target
+ * @returns The interaction's result
+ * @throws CommandError (87) when the bound node left the page during the action
  */
-export declare function resolveScriptTarget(cdp: CDPConnection, params: {
+export declare function onScriptTarget<T extends {
+    selector?: string;
+    error?: string;
+    suggestion?: string;
+    exitCode?: number;
+}>(cdp: CDPConnection, params: {
     selector?: string;
     index?: number;
     backendNodeId?: number;
-}): Promise<ScriptTarget>;
+}, work: (target: ScriptTarget) => Promise<T>): Promise<T>;
 /**
- * Report the user's selector instead of the internal placeholder.
+ * Error for an element a command could not find.
  *
- * @param result - Script result
- * @param selector - Selector the user gave (or the cached query's selector)
- * @returns Result with the placeholder replaced
+ * @param target - Selector (and index) or backend node id the command was given
+ * @param matchCount - Elements the selector matched
+ * @returns Stale (87), out of range (81) or not found (83) error
  */
-export declare function withUserSelector<T extends {
-    selector?: string;
-}>(result: T, selector: string | undefined): T;
+export declare function missingElementError(target: {
+    selector: string;
+    index?: number;
+    backendNodeId?: number;
+}, matchCount: number): CommandError;
 //# sourceMappingURL=targetNode.d.ts.map