browser-debugger-cli 0.7.1 → 0.8.0

package/dist/runtime/dom/keyMapping.js

@@ -0,0 +1,232 @@
+/**
+ * Key name to CDP key event parameters mapping.
+ *
+ * Maps human-readable key names to Chrome DevTools Protocol Input.dispatchKeyEvent parameters.
+ */
+import { findSimilar } from '../../utils/suggestions.js';
+/**
+ * Modifier key bit flags for CDP Input.dispatchKeyEvent
+ * (Alt=1, Ctrl=2, Meta/Command=4, Shift=8).
+ */
+export const MODIFIER_FLAGS = {
+    alt: 1,
+    ctrl: 2,
+    meta: 4,
+    shift: 8,
+};
+/**
+ * Map of supported key names to their CDP parameters.
+ *
+ * Keys are case-insensitive for user convenience.
+ */
+const KEY_DEFINITIONS = {
+    enter: { code: 'Enter', key: 'Enter', keyCode: 13, text: '\r' },
+    tab: { code: 'Tab', key: 'Tab', keyCode: 9 },
+    escape: { code: 'Escape', key: 'Escape', keyCode: 27 },
+    space: { code: 'Space', key: ' ', keyCode: 32, text: ' ' },
+    backspace: { code: 'Backspace', key: 'Backspace', keyCode: 8 },
+    delete: { code: 'Delete', key: 'Delete', keyCode: 46 },
+    arrowup: { code: 'ArrowUp', key: 'ArrowUp', keyCode: 38 },
+    arrowdown: { code: 'ArrowDown', key: 'ArrowDown', keyCode: 40 },
+    arrowleft: { code: 'ArrowLeft', key: 'ArrowLeft', keyCode: 37 },
+    arrowright: { code: 'ArrowRight', key: 'ArrowRight', keyCode: 39 },
+    home: { code: 'Home', key: 'Home', keyCode: 36 },
+    end: { code: 'End', key: 'End', keyCode: 35 },
+    pageup: { code: 'PageUp', key: 'PageUp', keyCode: 33 },
+    pagedown: { code: 'PageDown', key: 'PageDown', keyCode: 34 },
+    f1: { code: 'F1', key: 'F1', keyCode: 112 },
+    f2: { code: 'F2', key: 'F2', keyCode: 113 },
+    f3: { code: 'F3', key: 'F3', keyCode: 114 },
+    f4: { code: 'F4', key: 'F4', keyCode: 115 },
+    f5: { code: 'F5', key: 'F5', keyCode: 116 },
+    f6: { code: 'F6', key: 'F6', keyCode: 117 },
+    f7: { code: 'F7', key: 'F7', keyCode: 118 },
+    f8: { code: 'F8', key: 'F8', keyCode: 119 },
+    f9: { code: 'F9', key: 'F9', keyCode: 120 },
+    f10: { code: 'F10', key: 'F10', keyCode: 121 },
+    f11: { code: 'F11', key: 'F11', keyCode: 122 },
+    f12: { code: 'F12', key: 'F12', keyCode: 123 },
+};
+for (let i = 0; i < 26; i++) {
+    const letter = String.fromCharCode(97 + i); // 'a' = 97
+    const upperLetter = letter.toUpperCase();
+    KEY_DEFINITIONS[letter] = {
+        code: `Key${upperLetter}`,
+        key: letter,
+        keyCode: 65 + i, // 'A' = 65
+        text: letter,
+    };
+}
+for (let i = 0; i < 10; i++) {
+    const digit = String(i);
+    KEY_DEFINITIONS[digit] = {
+        code: `Digit${digit}`,
+        key: digit,
+        keyCode: 48 + i, // '0' = 48
+        text: digit,
+        shiftText: ')!@#$%^&*('.charAt(i),
+    };
+}
+/**
+ * Get key definition by name (case-insensitive).
+ *
+ * @param keyName - Human-readable key name (e.g., "Enter", "Tab", "a")
+ * @returns Key definition or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const def = getKeyDefinition('Enter');
+ * // { code: 'Enter', key: 'Enter', keyCode: 13 }
+ *
+ * const letterDef = getKeyDefinition('a');
+ * // { code: 'KeyA', key: 'a', keyCode: 65 }
+ * ```
+ */
+export function getKeyDefinition(keyName) {
+    const name = keyName.toLowerCase();
+    const digit = keyName.length === 1 ? SHIFTED_DIGITS.indexOf(keyName) : -1;
+    if (digit !== -1)
+        return KEY_DEFINITIONS[String(digit)];
+    return KEY_DEFINITIONS[KEY_ALIASES[name] ?? name];
+}
+/** Other names users write for keys */
+const KEY_ALIASES = {
+    esc: 'escape',
+    return: 'enter',
+    del: 'delete',
+    spacebar: 'space',
+    ' ': 'space',
+    up: 'arrowup',
+    down: 'arrowdown',
+    left: 'arrowleft',
+    right: 'arrowright',
+    pgup: 'pageup',
+    pgdn: 'pagedown',
+    pagedn: 'pagedown',
+};
+/** Characters typed with Shift on the digit keys 0-9 (US layout) */
+const SHIFTED_DIGITS = ')!@#$%^&*(';
+/**
+ * Whether a key name needs Shift to produce it (an uppercase letter, or a
+ * symbol on a digit key such as "!").
+ *
+ * @param keyName - Key name as given
+ * @returns True if Shift is implied
+ */
+export function impliesShift(keyName) {
+    return /^[A-Z]$/.test(keyName) || (keyName.length === 1 && SHIFTED_DIGITS.includes(keyName));
+}
+/**
+ * Key names closest to an unknown one.
+ *
+ * @param keyName - Unknown key name
+ * @returns Up to three key names, in their usual spelling
+ */
+export function similarKeyNames(keyName) {
+    const names = Object.values(KEY_DEFINITIONS)
+        .map((definition) => definition.key)
+        .filter((key) => key.length > 1);
+    return findSimilar(keyName, names);
+}
+/** Accepted modifier names (and common aliases) mapped to their flag. */
+const MODIFIER_NAMES = {
+    alt: 'alt',
+    option: 'alt',
+    opt: 'alt',
+    ctrl: 'ctrl',
+    control: 'ctrl',
+    meta: 'meta',
+    cmd: 'meta',
+    command: 'meta',
+    shift: 'shift',
+};
+/**
+ * Split a comma-separated modifier list into lowercase names.
+ *
+ * @param modifiers - e.g. "Ctrl, shift"
+ * @returns Non-empty names
+ */
+function modifierNames(modifiers) {
+    return modifiers
+        .toLowerCase()
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+/**
+ * Names in a modifier list that are not recognized.
+ *
+ * @param modifiers - Comma-separated modifier names
+ * @returns Unknown names (empty when all are valid)
+ */
+export function findUnknownModifiers(modifiers) {
+    return modifierNames(modifiers).filter((name) => !(name in MODIFIER_NAMES));
+}
+/**
+ * Parse modifier string into CDP modifier flags.
+ *
+ * @param modifiers - Comma-separated modifier names (e.g., "ctrl,shift"; aliases cmd, control, option)
+ * @returns Combined modifier bit flags
+ *
+ * @example
+ * ```typescript
+ * parseModifiers('ctrl,shift'); // Returns 10 (2 + 8)
+ * parseModifiers('cmd');        // Returns 4
+ * parseModifiers('');           // Returns 0
+ * ```
+ */
+export function parseModifiers(modifiers) {
+    if (!modifiers)
+        return 0;
+    return modifierNames(modifiers).reduce((flags, name) => {
+        const flag = MODIFIER_NAMES[name];
+        return flag ? flags | MODIFIER_FLAGS[flag] : flags;
+    }, 0);
+}
+/**
+ * Human-readable names of set modifier flags.
+ *
+ * @param flags - CDP modifier bit flags
+ * @returns e.g. ["Ctrl", "Shift"]
+ */
+export function describeModifiers(flags) {
+    const labels = {
+        ctrl: 'Ctrl',
+        alt: 'Alt',
+        shift: 'Shift',
+        meta: 'Meta',
+    };
+    return Object.keys(labels)
+        .filter((name) => flags & MODIFIER_FLAGS[name])
+        .map((name) => labels[name]);
+}
+/** Editor commands of the standard Ctrl/Cmd shortcuts, by key code */
+const SHORTCUT_COMMANDS = {
+    KeyA: 'selectAll',
+    KeyC: 'copy',
+    KeyX: 'cut',
+    KeyV: 'paste',
+    KeyZ: 'undo',
+};
+/**
+ * Editor commands a key press triggers, like a physical keyboard does.
+ *
+ * Chrome only runs shortcuts such as Ctrl+A (Cmd+A on macOS) for events it
+ * gets from the OS; for CDP key events the command has to be named. Either
+ * Ctrl or Meta works, so scripts behave the same on every platform; Shift+Z
+ * redoes.
+ *
+ * @param code - Key code, e.g. "KeyA"
+ * @param flags - CDP modifier bit flags
+ * @returns Editor commands for `Input.dispatchKeyEvent`, empty if none
+ */
+export function shortcutCommands(code, flags) {
+    const command = SHORTCUT_COMMANDS[code];
+    const shortcutModifier = flags & (MODIFIER_FLAGS.ctrl | MODIFIER_FLAGS.meta);
+    if (!command || !shortcutModifier || flags & MODIFIER_FLAGS.alt)
+        return [];
+    if (command === 'undo' && flags & MODIFIER_FLAGS.shift)
+        return ['redo'];
+    return flags & MODIFIER_FLAGS.shift ? [] : [command];
+}
+//# sourceMappingURL=keyMapping.js.map

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

@@ -0,0 +1,72 @@
+/**
+ * Turning CDP event listener data into the `bdg dom listeners` report.
+ *
+ * Pure functions: the daemon collects the listeners of an element, its
+ * ancestors, its document and window (`inspectEventListeners`), and
+ * these name, place, filter and order them.
+ */
+import type { Protocol } from '../../connection/typed-cdp.js';
+import type { ElementListener, ListenerPlacement } from '../../ipc/protocol/domTypes.js';
+/** An event target on the path from the element out to its window. */
+export interface ChainEntry {
+    /** CDP class name, e.g. `HTMLDivElement`, `HTMLDocument`, `Window` */
+    className?: string | undefined;
+    /** CDP description, e.g. `div#root.app` */
+    description?: string | undefined;
+}
+/** Listeners found on one entry of the chain. */
+export interface ChainListeners {
+    /** Position in the chain: 0 is the element itself */
+    position: number;
+    entry: ChainEntry;
+    listeners: Protocol.DOMDebugger.EventListener[];
+}
+/**
+ * Where an entry of the chain sits relative to the element.
+ *
+ * @param entry - Chain entry
+ * @param position - Position in the chain (0 = the element)
+ * @returns Placement
+ */
+export declare function listenerPlacement(entry: ChainEntry, position: number): ListenerPlacement;
+/**
+ * Short description of a chain entry, e.g. `div#root.app`.
+ *
+ * @param entry - Chain entry
+ * @returns Description
+ */
+export declare function describeChainEntry(entry: ChainEntry): string;
+/**
+ * First characters of a function's source, on one line.
+ *
+ * @param source - Function source (the handler's CDP description)
+ * @returns Preview
+ */
+export declare function handlerPreview(source: string | undefined): string;
+/**
+ * Name of a function as written in its source (fallback when the page could
+ * not report `Function.name`).
+ *
+ * @param source - Function source
+ * @returns Name, or '' for anonymous and arrow functions
+ */
+export declare function functionNameFromSource(source: string | undefined): string;
+/**
+ * Build the listener report: filtered to `types` (if given), grouped by
+ * event type (alphabetically), nearest first within a type.
+ *
+ * @param found - Listeners per chain entry, in chain order
+ * @param names - Handler names in the order of the flattened listeners (missing = unknown)
+ * @param types - Event types to keep (default: all)
+ * @returns Ordered listeners
+ */
+export declare function buildListenerReport(found: ChainListeners[], names: Array<string | undefined>, types?: string[]): ElementListener[];
+/**
+ * Interaction event types that have listeners, but none on the element
+ * itself: frameworks (React, jQuery) handle these by delegation.
+ *
+ * @param listeners - Listener report
+ * @returns Event types, in report order
+ */
+export declare function delegatedOnlyTypes(listeners: ElementListener[]): string[];
+//# sourceMappingURL=listenerSummary.d.ts.map

package/dist/runtime/dom/listenerSummary.js

@@ -0,0 +1,150 @@
+/**
+ * Turning CDP event listener data into the `bdg dom listeners` report.
+ *
+ * Pure functions: the daemon collects the listeners of an element, its
+ * ancestors, its document and window (`inspectEventListeners`), and
+ * these name, place, filter and order them.
+ */
+import { truncateByLength } from '../../utils/strings.js';
+/** Longest handler source preview */
+const PREVIEW_MAX_LENGTH = 80;
+/** Longest node description (class lists can be very long) */
+const NODE_MAX_LENGTH = 60;
+/** Event types a user interaction triggers (for the delegation note) */
+const INTERACTION_EVENT_TYPES = new Set([
+    'beforeinput',
+    'blur',
+    'change',
+    'click',
+    'contextmenu',
+    'dblclick',
+    'focus',
+    'focusin',
+    'focusout',
+    'input',
+    'keydown',
+    'keypress',
+    'keyup',
+    'mousedown',
+    'mouseup',
+    'pointerdown',
+    'pointerup',
+    'submit',
+    'touchend',
+    'touchstart',
+]);
+/**
+ * Where an entry of the chain sits relative to the element.
+ *
+ * @param entry - Chain entry
+ * @param position - Position in the chain (0 = the element)
+ * @returns Placement
+ */
+export function listenerPlacement(entry, position) {
+    if (position === 0)
+        return 'target';
+    if (entry.className === 'Window')
+        return 'window';
+    if (entry.description === '#document')
+        return 'document';
+    return 'ancestor';
+}
+/**
+ * Short description of a chain entry, e.g. `div#root.app`.
+ *
+ * @param entry - Chain entry
+ * @returns Description
+ */
+export function describeChainEntry(entry) {
+    if (entry.className === 'Window')
+        return 'window';
+    if (entry.description === '#document')
+        return 'document';
+    if (entry.className === 'ShadowRoot')
+        return '#shadow-root';
+    return truncateByLength(entry.description ?? entry.className ?? '?', NODE_MAX_LENGTH);
+}
+/**
+ * First characters of a function's source, on one line.
+ *
+ * @param source - Function source (the handler's CDP description)
+ * @returns Preview
+ */
+export function handlerPreview(source) {
+    return truncateByLength((source ?? '').replace(/\s+/g, ' ').trim(), PREVIEW_MAX_LENGTH);
+}
+/**
+ * Name of a function as written in its source (fallback when the page could
+ * not report `Function.name`).
+ *
+ * @param source - Function source
+ * @returns Name, or '' for anonymous and arrow functions
+ */
+export function functionNameFromSource(source) {
+    const text = (source ?? '').trim();
+    const declared = /^(?:async\s+)?function\s*\*?\s*([\w$]+)/.exec(text);
+    if (declared?.[1])
+        return declared[1];
+    const method = /^(?:async\s+)?(?:get\s+|set\s+)?([\w$]+)\s*\(/.exec(text);
+    return method?.[1] && method[1] !== 'function' ? method[1] : '';
+}
+/**
+ * Build the report entry for one listener.
+ *
+ * @param listener - CDP listener
+ * @param found - Chain entry it is attached to
+ * @param name - Handler name reported by the page, if known
+ * @returns Listener entry
+ */
+function toElementListener(listener, found, name) {
+    const source = listener.handler?.description;
+    return {
+        type: listener.type,
+        on: listenerPlacement(found.entry, found.position),
+        node: describeChainEntry(found.entry),
+        useCapture: listener.useCapture,
+        passive: listener.passive,
+        once: listener.once,
+        handler: {
+            name: name ?? functionNameFromSource(source),
+            preview: handlerPreview(source),
+            scriptId: listener.scriptId,
+            lineNumber: listener.lineNumber,
+            columnNumber: listener.columnNumber,
+        },
+    };
+}
+/**
+ * Build the listener report: filtered to `types` (if given), grouped by
+ * event type (alphabetically), nearest first within a type.
+ *
+ * @param found - Listeners per chain entry, in chain order
+ * @param names - Handler names in the order of the flattened listeners (missing = unknown)
+ * @param types - Event types to keep (default: all)
+ * @returns Ordered listeners
+ */
+export function buildListenerReport(found, names, types) {
+    const flat = found.flatMap((entry) => entry.listeners.map((listener) => ({ entry, listener })));
+    const listeners = flat
+        .map(({ entry, listener }, i) => ({
+        position: entry.position,
+        listener: toElementListener(listener, entry, names[i]),
+    }))
+        .filter(({ listener }) => !types?.length || types.includes(listener.type));
+    return listeners
+        .sort((a, b) => a.listener.type.localeCompare(b.listener.type) || a.position - b.position)
+        .map(({ listener }) => listener);
+}
+/**
+ * Interaction event types that have listeners, but none on the element
+ * itself: frameworks (React, jQuery) handle these by delegation.
+ *
+ * @param listeners - Listener report
+ * @returns Event types, in report order
+ */
+export function delegatedOnlyTypes(listeners) {
+    const types = [...new Set(listeners.map((listener) => listener.type))];
+    return types.filter((type) => INTERACTION_EVENT_TYPES.has(type) &&
+        !listeners.some((listener) => listener.type === type && listener.on === 'target'));
+}
+//# sourceMappingURL=listenerSummary.js.map

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

@@ -0,0 +1,61 @@
+/**
+ * React-compatible event handling for form interactions.
+ *
+ * React uses synthetic events and doesn't detect direct DOM manipulation.
+ * This module provides JavaScript snippets that can be injected via Runtime.evaluate
+ * to properly trigger React's event system.
+ */
+import type { FillResult, ClickResult } from '../../ipc/protocol/domTypes.js';
+/**
+ * JavaScript function to fill an input element in a React-compatible way.
+ *
+ * This approach:
+ * 1. Uses native property setters to bypass React's value tracking
+ * 2. Dispatches input/change events that React listens for
+ * 3. Properly handles focus/blur for form validation
+ *
+ * @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";
+/**
+ * JavaScript function to locate an element for clicking.
+ *
+ * Scrolls the element into view and reports its center point and whether it
+ * is the topmost element there (`hittable`). It does not click; see
+ * `clickElement`, which dispatches real mouse events or falls back to
+ * `el.click()`.
+ *
+ * @remarks
+ * 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.
+ */
+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";
+/**
+ * Options for filling an element.
+ */
+export interface FillOptions {
+    /** Whether to blur the element after filling (default: true) */
+    blur?: boolean;
+    /** Index to use if selector matches multiple elements (0-based) */
+    index?: number;
+    /** Directory relative file paths are resolved against (file inputs) */
+    cwd?: string;
+}
+export type { FillResult, ClickResult } from '../../ipc/protocol/domTypes.js';
+/**
+ * Type guard for FillResult.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid FillResult
+ */
+export declare function isFillResult(value: unknown): value is FillResult;
+/**
+ * Type guard for ClickResult.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid ClickResult
+ */
+export declare function isClickResult(value: unknown): value is ClickResult;
+//# sourceMappingURL=reactEventHelpers.d.ts.map