browser-debugger-cli 0.8.0 → 0.9.0

package/dist/runtime/dom/pageActivity.js

@@ -0,0 +1,123 @@
+/**
+ * CDP events a DOM action causes, for its "what changed" report: main-frame
+ * navigations (with document statuses), requests and new windows.
+ */
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('dom');
+/**
+ * Listen for the main frame's navigations, document responses, requests
+ * and new windows. Events of attached child targets (out-of-process frames,
+ * workers) are not main-frame navigations, but their requests count.
+ * `Network.enable` is sent without waiting (see `withActionStability`): the
+ * session's network collector usually has the domain enabled already.
+ *
+ * @param cdp - CDP connection
+ * @returns Live listener
+ */
+export function listenForActivity(cdp) {
+    const state = {
+        events: { statusByLoader: new Map() },
+        mainFrame: new Set(),
+        requests: 0,
+        opened: false,
+        loading: false,
+    };
+    const cleanups = [
+        ...listenForNavigation(cdp, state),
+        ...listenForRequests(cdp, state),
+        ...listenForWindows(cdp, state),
+    ];
+    findMainFrame(cdp, state);
+    return {
+        events: state.events,
+        activity: () => ({ requests: state.requests, opened: state.opened }),
+        navigationPending: () => state.loading,
+        dispose: () => cleanups.forEach((cleanup) => cleanup()),
+    };
+}
+/**
+ * Main-frame navigations: new documents, same-document URL changes, and
+ * whether a load is pending (started, not committed or stopped yet).
+ *
+ * @param cdp - CDP connection
+ * @param state - State to record into
+ * @returns Listener cleanups
+ */
+function listenForNavigation(cdp, state) {
+    const isMain = (frameId, sessionId) => sessionId === undefined && state.mainFrame.has(frameId);
+    return [
+        cdp.on('Page.frameNavigated', ({ frame }, sessionId) => {
+            if (sessionId !== undefined || frame.parentId !== undefined)
+                return;
+            state.mainFrame.add(frame.id);
+            state.loading = false;
+            const url = frame.url + (frame.urlFragment ?? '');
+            state.events.document = { url, loaderId: frame.loaderId };
+        }),
+        cdp.on('Page.navigatedWithinDocument', (params, session) => {
+            if (isMain(params.frameId, session))
+                state.events.withinDocumentUrl = params.url;
+        }),
+        cdp.on('Page.frameStartedLoading', ({ frameId }, sessionId) => {
+            if (isMain(frameId, sessionId))
+                state.loading = true;
+        }),
+        cdp.on('Page.frameStoppedLoading', ({ frameId }, sessionId) => {
+            if (isMain(frameId, sessionId))
+                state.loading = false;
+        }),
+    ];
+}
+/**
+ * Requests (any target) and the statuses of documents.
+ *
+ * @param cdp - CDP connection
+ * @param state - State to record into
+ * @returns Listener cleanups
+ */
+function listenForRequests(cdp, state) {
+    void cdp
+        .send('Network.enable')
+        .catch((error) => log.debug(`Network.enable failed: ${getErrorMessage(error)}`));
+    return [
+        cdp.on('Network.responseReceived', ({ type, loaderId, response }) => {
+            if (type === 'Document' && loaderId) {
+                state.events.statusByLoader.set(loaderId, response.status);
+            }
+        }),
+        cdp.on('Network.requestWillBeSent', () => {
+            state.requests++;
+        }),
+    ];
+}
+/**
+ * New windows, tabs and downloads.
+ *
+ * @param cdp - CDP connection
+ * @param state - State to record into
+ * @returns Listener cleanups
+ */
+function listenForWindows(cdp, state) {
+    const opened = () => {
+        state.opened = true;
+    };
+    return [cdp.on('Page.windowOpen', opened), cdp.on('Page.downloadWillBegin', opened)];
+}
+/**
+ * Learn the main frame's id (until a navigation reports it), without waiting.
+ *
+ * @param cdp - CDP connection
+ * @param state - State to record into
+ */
+function findMainFrame(cdp, state) {
+    void cdp
+        .send('Page.getFrameTree')
+        .then((tree) => {
+        const id = tree.frameTree?.frame?.id;
+        if (id)
+            state.mainFrame.add(id);
+    })
+        .catch((error) => log.debug(`No frame tree: ${getErrorMessage(error)}`));
+}
+//# sourceMappingURL=pageActivity.js.map

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

@@ -6,6 +6,34 @@
  * to properly trigger React's event system.
  */
 import type { FillResult, ClickResult } from '../../ipc/protocol/domTypes.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 declare const FILL_VALUE_MISMATCH_JS = "(field, expected) => {\n  const type = (field.type || '').toLowerCase();\n  const actual = field.isContentEditable\n    ? (field.textContent || '')\n    : type === 'checkbox' || type === 'radio'\n      ? (field.checked ? 'checked' : 'unchecked')\n      : field.localName === 'select' && field.multiple\n        ? Array.from(field.selectedOptions).map((o) => o.value).join(', ')\n        : String(field.value);\n  const time = (text) => text.trim().replace(' ', 'T').replace(/(\\d\\d:\\d\\d):00(\\.0+)?$/, '$1');\n  const normalize = (text) => {\n    text = String(text);\n    if (field.isContentEditable) return text.replace(/\\s+/g, ' ').trim();\n    if (field.localName === 'textarea') return text.replace(/\\r\\n?/g, '\\n');\n    if (type === 'color') return text.trim().toLowerCase();\n    if (type === 'email') return text.trim();\n    if (type === 'time' || type === 'datetime-local') return time(text);\n    return text;\n  };\n  const numeric = (type === 'number' || type === 'range') && actual.trim() !== '' && String(expected).trim() !== '';\n  const same = numeric ? Number(actual) === Number(expected) : normalize(actual) === normalize(expected);\n  if (same) return undefined;\n  if (type === 'password') {\n    const mask = (text) => (text === '' ? '' : '********');\n    return { expected: mask(expected), actual: mask(actual), expectedLength: expected.length, actualLength: actual.length };\n  }\n  const cut = field.maxLength > 0 && actual.length === field.maxLength && expected.length > actual.length &&\n    expected.startsWith(actual);\n  return cut ? { expected: expected, actual: actual, truncatedTo: actual.length } : { expected: expected, actual: actual };\n}";
+/**
+ * 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 declare const FIELD_VALUES_JS = "(field) => {\n  const fields = field.form ? Array.from(field.form.elements) : Array.from(field.ownerDocument.querySelectorAll('input, textarea'));\n  return new Map(fields\n    .filter((f) => f !== field && /^(input|textarea)$/.test(f.localName) &&\n      !/^(checkbox|radio|password|hidden|submit|button|reset|file|image)$/i.test(f.type || ''))\n    .map((f) => [f, String(f.value)]));\n}";
+/**
+ * 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 declare const FILL_REFUSAL_JS: string;
 /**
  * JavaScript function to fill an input element in a React-compatible way.
  *
@@ -14,10 +42,36 @@ import type { FillResult, ClickResult } from '../../ipc/protocol/domTypes.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.
  */
-export declare const REACT_FILL_SCRIPT = "\n(function(selector, parts, value, options) {\n  const allMatches = (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})(selector, parts);\n  const warnings = [];\n  // Why a user could not reach the field (the value is still set, so scripted\n  // flows keep working, but the result may not be what a user would see)\n  const unreachableReason = (field) => {\n    if (field.closest('[inert]')) return 'inert';\n    const modal = field.ownerDocument.querySelector('dialog:modal');\n    if (modal && !modal.contains(field)) return 'behind an open modal dialog';\n    if (field.checkVisibility && !field.checkVisibility({ visibilityProperty: true, opacityProperty: true })) return 'hidden';\n    return null;\n  };\n  // Why the browser did not take the value as given (it sanitizes instead of\n  // throwing: bad dates become \"\", colors #000000, ranges are clamped)\n  const rejectedValue = (field, type, text) => {\n    const formats = {\n      number: 'a number',\n      date: 'YYYY-MM-DD',\n      time: 'HH:MM',\n      'datetime-local': 'YYYY-MM-DDTHH:MM',\n      month: 'YYYY-MM',\n      week: 'YYYY-Www'\n    };\n    const rejected = 'The browser rejected \"' + text + '\" for a ' + type + ' field (it keeps its previous value)';\n    if (formats[type] && text.trim() !== '' && field.value === '') {\n      return { error: rejected, suggestion: 'Expected ' + formats[type] };\n    }\n    if (type === 'color' && field.value.toLowerCase() !== text.trim().toLowerCase()) {\n      return { error: rejected, suggestion: 'Expected a hex color like #1a2b3c' };\n    }\n    if (type === 'range' && Number(field.value) !== Number(text)) {\n      return {\n        error: 'The browser would set ' + field.value + ' instead of \"' + text + '\" (range ' + (field.min || 0) + ' to ' + (field.max || 100) + ', step ' + (field.step || 1) + ')',\n        suggestion: 'Use a value within the range that matches the step'\n      };\n    }\n    return null;\n  };\n  \n  if (allMatches.length === 0) {\n    return { \n      success: false, \n      error: 'Element not found: ' + selector,\n      selector: selector\n    };\n  }\n  \n  let el;\n  const index = options.index;\n  \n  // If index is provided, use it directly (0-based)\n  if (typeof index === 'number' && index >= 0) {\n    if (index >= allMatches.length) {\n      return {\n        success: false,\n        error: 'Index out of range',\n        selector: selector,\n        matchCount: allMatches.length,\n        requestedIndex: index,\n        suggestion: 'Use --index between 0 and ' + (allMatches.length - 1)\n      };\n    }\n    el = allMatches[index];\n  } else {\n    el = allMatches[0];\n  }\n  \n  const tagName = el.tagName.toLowerCase();\n  const inputType = el.type?.toLowerCase();\n  \n  const isFillable = (\n    tagName === 'input' || \n    tagName === 'textarea' || \n    tagName === 'select' ||\n    el.isContentEditable\n  );\n  \n  if (!isFillable) {\n    return {\n      success: false,\n      error: 'Element is not fillable',\n      elementType: tagName,\n      suggestion: 'Only input, textarea, select, and contenteditable elements can be filled'\n    };\n  }\n\n  if (el.disabled || el.matches(':disabled')) {\n    return {\n      success: false,\n      error: 'Element is disabled',\n      elementType: tagName,\n      suggestion: 'Enable the field first (it may depend on another input)'\n    };\n  }\n  if (el.readOnly) {\n    return {\n      success: false,\n      error: 'Element is read-only',\n      elementType: tagName,\n      suggestion: 'Read-only fields cannot be filled'\n    };\n  }\n\n  const unreachable = unreachableReason(el);\n  if (unreachable) {\n    warnings.push('The field is ' + unreachable + '; a user could not fill it (the value was set anyway)');\n  }\n\n  el.focus();\n\n  if (tagName === 'select' && el.multiple) {\n    // Several options, separated by commas (an option whose value contains a\n    // comma matches as a whole); \"\" selects none\n    const options = Array.from(el.options);\n    const whole = options.some((o) => o.value === value || o.text.trim() === value);\n    const wanted = whole ? [value] : value.split(',').map((part) => part.trim()).filter(Boolean);\n    const chosen = wanted.map((part) =>\n      options.find((o) => o.value === part) || options.find((o) => o.text.trim() === part)\n    );\n    const missing = wanted.find((part, i) => !chosen[i]);\n    if (missing !== undefined) {\n      return {\n        success: false,\n        error: 'Option not found: ' + missing,\n        exitCode: 81,\n        elementType: tagName,\n        suggestion: 'Available options: ' + options.slice(0, 10).map((o) => o.value || o.text.trim()).join(', ')\n      };\n    }\n    options.forEach((o) => { o.selected = chosen.includes(o); });\n    el.dispatchEvent(new Event('input', { bubbles: true }));\n    el.dispatchEvent(new Event('change', { bubbles: true }));\n  } else if (tagName === 'select') {\n    // Match by option value first, then by visible label\n    const options = Array.from(el.options);\n    const option =\n      options.find((o) => o.value === value) ||\n      options.find((o) => o.text.trim() === value);\n    if (!option) {\n      return {\n        success: false,\n        error: 'Option not found: ' + value,\n        exitCode: 81,\n        elementType: tagName,\n        suggestion: 'Available options: ' + options.slice(0, 10).map((o) => o.value || o.text.trim()).join(', ')\n      };\n    }\n    el.value = option.value;\n    el.dispatchEvent(new Event('input', { bubbles: true }));\n    el.dispatchEvent(new Event('change', { bubbles: true }));\n  } else if (inputType === 'checkbox' || inputType === 'radio') {\n    // Toggle through a click, like a user: frameworks (React) track checkable\n    // state via click events and revert a programmatic `checked` assignment\n    const normalized = String(value).trim().toLowerCase();\n    const truthy = ['true', '1', 'yes', 'on', 'checked'];\n    const falsy = ['false', '0', 'no', 'off', 'unchecked'];\n    if (!truthy.includes(normalized) && !falsy.includes(normalized)) {\n      return {\n        success: false,\n        error: 'Expected true or false for a ' + inputType + ', got \"' + value + '\"',\n        elementType: tagName,\n        inputType: inputType,\n        suggestion: 'Use true/false (also yes/no, on/off, 1/0)'\n      };\n    }\n    const shouldCheck = truthy.includes(normalized);\n    if (inputType === 'radio' && !shouldCheck) {\n      return {\n        success: false,\n        error: 'A radio button cannot be unchecked',\n        elementType: tagName,\n        inputType: inputType,\n        suggestion: 'Select another option in the same group instead'\n      };\n    }\n    if (el.checked !== shouldCheck) {\n      el.click();\n    }\n  } else if (inputType === 'file') {\n    return {\n      success: false,\n      fileInput: true,\n      elementType: tagName,\n      inputType: inputType,\n      error: 'File input'\n    };\n  } else if (el.isContentEditable) {\n    el.textContent = value;\n    el.dispatchEvent(new Event('input', { bubbles: true }));\n  } else {\n    const nativeInputValueSetter = Object.getOwnPropertyDescriptor(\n      el.ownerDocument.defaultView.HTMLInputElement.prototype,\n      'value'\n    )?.set;\n    \n    const nativeTextAreaValueSetter = Object.getOwnPropertyDescriptor(\n      el.ownerDocument.defaultView.HTMLTextAreaElement.prototype,\n      'value'\n    )?.set;\n    \n    const setter = tagName === 'textarea' \n      ? nativeTextAreaValueSetter \n      : nativeInputValueSetter;\n\n    if (el.maxLength > 0 && value.length > el.maxLength) {\n      return {\n        success: false,\n        error: 'Value is ' + value.length + ' characters; the field accepts at most ' + el.maxLength,\n        elementType: tagName,\n        inputType: inputType || null,\n        suggestion: 'Shorten the value (a user could not type more than maxlength characters)'\n      };\n    }\n    \n    const setValue = (text) => (setter ? setter.call(el, text) : (el.value = text));\n    const previous = el.value;\n    setValue(value);\n    const rejection = rejectedValue(el, inputType, value);\n    if (rejection) {\n      setValue(previous);\n      if (options.blur !== false) el.blur();\n      return {\n        success: false,\n        error: rejection.error,\n        elementType: tagName,\n        inputType: inputType,\n        suggestion: rejection.suggestion\n      };\n    }\n\n    el.dispatchEvent(new Event('input', { bubbles: true }));\n    el.dispatchEvent(new Event('change', { bubbles: true }));\n    if (el.validity && (el.validity.rangeOverflow || el.validity.rangeUnderflow)) {\n      warnings.push('The value is outside the allowed range (' + (el.min || 'no minimum') + ' to ' + (el.max || 'no maximum') + '); the form will not submit until it is fixed');\n    }\n  }\n  \n  if (options.blur !== false) {\n    el.blur();\n  }\n  \n  return {\n    success: true,\n    selector: selector,\n    value: el.isContentEditable\n      ? el.textContent\n      : inputType === 'password'\n        ? '********'\n        : tagName === 'select' && el.multiple\n          ? Array.from(el.selectedOptions).map((o) => o.value).join(', ')\n          : el.value,\n    elementType: tagName,\n    inputType: inputType || null,\n    checked: inputType === 'checkbox' || inputType === 'radio' ? el.checked : undefined,\n    matchCount: allMatches.length,\n    warning: warnings.concat(allMatches.length > 1 && typeof index !== 'number'\n      ? [allMatches.length + ' elements match; filled the first (use --index or a more specific selector)']\n      : []).join('; ') || undefined\n  };\n})\n";
+export declare const REACT_FILL_SCRIPT: string;
+/**
+ * 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 declare const MOVED_VALUE_JS = "(field, expected, before) => {\n  const wanted = String(expected).trim();\n  if (!before || wanted.length < 2 || (field.type || '').toLowerCase() === 'password') return undefined;\n  const other = Array.from(before.keys()).find((f) =>\n    String(f.value).trim() === wanted && String(before.get(f)).trim() !== wanted);\n  if (!other) return undefined;\n  if (other.id) return other.localName + '#' + other.id;\n  return other.name ? other.localName + '[name=\"' + other.name + '\"]' : ((node) => node.tagName.toLowerCase() +\n  (node.id ? '#' + node.id : '') +\n  (node.classList && node.classList.length ? '.' + Array.from(node.classList).slice(0, 2).join('.') : ''))(other);\n}";
+/**
+ * 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 declare const FILL_READ_BACK_SCRIPT = "(() => {\n  const check = window.__bdgFillCheck;\n  delete window.__bdgFillCheck;\n  if (!check) return null;\n  const readBack = () => {\n    if (!check.el.isConnected) return null;\n    const mismatch = ((field, expected) => {\n  const type = (field.type || '').toLowerCase();\n  const actual = field.isContentEditable\n    ? (field.textContent || '')\n    : type === 'checkbox' || type === 'radio'\n      ? (field.checked ? 'checked' : 'unchecked')\n      : field.localName === 'select' && field.multiple\n        ? Array.from(field.selectedOptions).map((o) => o.value).join(', ')\n        : String(field.value);\n  const time = (text) => text.trim().replace(' ', 'T').replace(/(\\d\\d:\\d\\d):00(\\.0+)?$/, '$1');\n  const normalize = (text) => {\n    text = String(text);\n    if (field.isContentEditable) return text.replace(/\\s+/g, ' ').trim();\n    if (field.localName === 'textarea') return text.replace(/\\r\\n?/g, '\\n');\n    if (type === 'color') return text.trim().toLowerCase();\n    if (type === 'email') return text.trim();\n    if (type === 'time' || type === 'datetime-local') return time(text);\n    return text;\n  };\n  const numeric = (type === 'number' || type === 'range') && actual.trim() !== '' && String(expected).trim() !== '';\n  const same = numeric ? Number(actual) === Number(expected) : normalize(actual) === normalize(expected);\n  if (same) return undefined;\n  if (type === 'password') {\n    const mask = (text) => (text === '' ? '' : '********');\n    return { expected: mask(expected), actual: mask(actual), expectedLength: expected.length, actualLength: actual.length };\n  }\n  const cut = field.maxLength > 0 && actual.length === field.maxLength && expected.length > actual.length &&\n    expected.startsWith(actual);\n  return cut ? { expected: expected, actual: actual, truncatedTo: actual.length } : { expected: expected, actual: actual };\n})(check.el, check.expected);\n    if (!mismatch) return null;\n    const movedTo = ((field, expected, before) => {\n  const wanted = String(expected).trim();\n  if (!before || wanted.length < 2 || (field.type || '').toLowerCase() === 'password') return undefined;\n  const other = Array.from(before.keys()).find((f) =>\n    String(f.value).trim() === wanted && String(before.get(f)).trim() !== wanted);\n  if (!other) return undefined;\n  if (other.id) return other.localName + '#' + other.id;\n  return other.name ? other.localName + '[name=\"' + other.name + '\"]' : ((node) => node.tagName.toLowerCase() +\n  (node.id ? '#' + node.id : '') +\n  (node.classList && node.classList.length ? '.' + Array.from(node.classList).slice(0, 2).join('.') : ''))(other);\n})(check.el, check.expected, check.before);\n    return movedTo ? Object.assign(mismatch, { movedTo: movedTo }) : mismatch;\n  };\n  return new Promise((resolve) => {\n    const channel = new MessageChannel();\n    channel.port1.onmessage = () => {\n      channel.port1.close();\n      resolve(readBack());\n    };\n    channel.port2.postMessage(null);\n  });\n})()";
 /**
  * JavaScript function to locate an element for clicking.
  *
@@ -30,8 +84,10 @@ export declare const REACT_FILL_SCRIPT = "\n(function(selector, parts, value, op
  * 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 declare const CLICK_ELEMENT_SCRIPT = "\n(function(selector, parts, index, action) {\n  const allMatches = (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})(selector, parts);\n  \n  if (allMatches.length === 0) {\n    return {\n      success: false,\n      error: 'Element not found: ' + selector,\n      selector: selector\n    };\n  }\n  \n  let el;\n  \n  // If index is provided, use it directly (0-based)\n  if (typeof index === 'number' && index >= 0) {\n    if (index >= allMatches.length) {\n      return {\n        success: false,\n        error: 'Index out of range',\n        selector: selector,\n        matchCount: allMatches.length,\n        requestedIndex: index,\n        suggestion: 'Use --index between 0 and ' + (allMatches.length - 1)\n      };\n    }\n    el = allMatches[index];\n  } else if (allMatches.length === 1) {\n    // Single match - use it directly\n    el = allMatches[0];\n  } else {\n    // Multiple matches without index - find first visible one\n    el = allMatches[0];\n    for (const candidate of allMatches) {\n      const style = candidate.ownerDocument.defaultView.getComputedStyle(candidate);\n      const rect = candidate.getBoundingClientRect();\n      \n      const hasSize = rect.width > 0 && rect.height > 0;\n      const isDisplayed = style.display !== 'none' && style.visibility !== 'hidden';\n      const isOpaque = parseFloat(style.opacity) > 0;\n      const isPositioned = candidate.offsetParent !== null || style.position === 'fixed';\n      \n      const isVisible = hasSize && isDisplayed && isOpaque && isPositioned;\n      \n      if (isVisible) {\n        el = candidate;\n        break;\n      }\n    }\n  }\n  \n  const tagName = el.tagName.toLowerCase();\n  if (tagName === 'option') {\n    const quote = (text) => \"'\" + String(text).split(\"'\").join(\"'\\\\''\") + \"'\";\n    const select = el.closest('select');\n    const target = select && select.id ? '#' + select.id : select && select.name ? 'select[name=\"' + select.name + '\"]' : 'select';\n    return {\n      success: false,\n      error: 'An <option> is chosen through its <select>, not clicked',\n      selector: selector,\n      elementType: tagName,\n      exitCode: 81,\n      suggestion: 'bdg dom fill ' + quote(target) + ' ' + quote(el.value || el.text.trim())\n    };\n  }\n  // Disabled elements still get hover (tooltips often explain why)\n  if (action !== 'hover' && (el.disabled || el.matches(':disabled'))) {\n    return {\n      success: false,\n      error: 'Element is disabled',\n      selector: selector,\n      elementType: tagName,\n      suggestion: 'A user cannot click a disabled element; enable it first (it may depend on other fields)'\n    };\n  }\n  el.scrollIntoView({ behavior: 'auto', block: 'center' });\n\n  // The caller clicks with real mouse events at (x, y) when the element is the\n  // topmost thing there; otherwise it falls back to el.click() via this handle.\n  // Hit-testing happens in the element's own root (shadow root or frame\n  // document), then in each enclosing document at the frame's position, so an\n  // overlay over the iframe counts as covering it. The mouse events need\n  // top-page coordinates: frame offsets (border and padding) are added.\n  window.__bdgClickTarget = el;\n  const rect = el.getBoundingClientRect();\n  const view = el.ownerDocument.defaultView;\n  const hitTest = (node, px, py) => {\n    const root = node.getRootNode();\n    const hit = (typeof root.elementFromPoint === 'function' ? root : node.ownerDocument).elementFromPoint(px, py);\n    return hit !== null && (hit === node || node.contains(hit));\n  };\n  const toTopPage = (px, py) => {\n    let hittable = hitTest(el, px, py);\n    for (let frameWindow = view; frameWindow && frameWindow.frameElement; frameWindow = frameWindow.parent) {\n      const frame = frameWindow.frameElement;\n      const frameRect = frame.getBoundingClientRect();\n      const frameStyle = frame.ownerDocument.defaultView.getComputedStyle(frame);\n      px += frameRect.left + frame.clientLeft + parseFloat(frameStyle.paddingLeft);\n      py += frameRect.top + frame.clientTop + parseFloat(frameStyle.paddingTop);\n      hittable = hittable && hitTest(frame, px, py);\n    }\n    return { x: px, y: py, hittable: hittable };\n  };\n  const left = Math.max(rect.left, 0);\n  const right = Math.min(rect.right, view.innerWidth);\n  const top = Math.max(rect.top, 0);\n  const bottom = Math.min(rect.bottom, view.innerHeight);\n  const area = right > left && bottom > top\n    ? { left: left, top: top, width: right - left, height: bottom - top }\n    : { left: rect.left, top: rect.top, width: rect.width, height: rect.height };\n  const fractions = [[0.5, 0.5], [0.5, 0.25], [0.5, 0.75], [0.25, 0.5], [0.75, 0.5], [0.25, 0.25], [0.75, 0.25], [0.25, 0.75], [0.75, 0.75]];\n  const hasSize = rect.width > 0 && rect.height > 0;\n  let point = null;\n  for (const [fx, fy] of hasSize ? fractions : [[0.5, 0.5]]) {\n    const candidate = toTopPage(area.left + area.width * fx, area.top + area.height * fy);\n    point = point || candidate;\n    if (hasSize && candidate.hittable) { point = candidate; break; }\n  }\n  const x = point.x;\n  const y = point.y;\n  const hittable = hasSize && point.hittable;\n  const describe = (node) => node.tagName.toLowerCase() + (node.id ? '#' + node.id : '') +\n    (node.classList && node.classList.length ? '.' + Array.from(node.classList).slice(0, 2).join('.') : '');\n  const coveredBy = () => {\n    const root = el.getRootNode();\n    const hit = (typeof root.elementFromPoint === 'function' ? root : el.ownerDocument)\n      .elementFromPoint(area.left + area.width / 2, area.top + area.height / 2);\n    return hit && !el.contains(hit) ? ' (' + describe(hit) + ')' : '';\n  };\n  const style = view.getComputedStyle(el);\n  let obstruction = null;\n  if (style.display === 'none' || el.getClientRects().length === 0) obstruction = 'not rendered (display: none)';\n  else if (style.visibility === 'hidden') obstruction = 'hidden (visibility: hidden)';\n  else if (el.closest('[inert]')) obstruction = 'inert (the page made it non-interactive)';\n  else if (style.pointerEvents === 'none') obstruction = 'not clickable (pointer-events: none)';\n  else if (!hasSize) obstruction = 'zero-size';\n  else if (!hittable) obstruction = 'covered by another element' + coveredBy();\n\n  return {\n    success: true,\n    selector: selector,\n    elementType: tagName,\n    matchCount: allMatches.length,\n    selectedIndex: typeof index === 'number' ? index : undefined,\n    x: x,\n    y: y,\n    hittable: hittable,\n    obstruction: obstruction\n  };\n})\n";
+export declare const CLICK_ELEMENT_SCRIPT: string;
 /**
  * Options for filling an element.
  */