browser-debugger-cli 0.8.0 → 0.10.0

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,15 @@ 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)`.
+ * A hover first notes what is hidden around the element
+ * ({@link REVEAL_SNAPSHOT_JS}), so its result can say what it revealed. For
+ * a press, a probe (`window.__bdgPressProbe`) records whether the press
+ * reaches the element, and otherwise which element it landed on: a browser
+ * dialog or bubble can swallow input while the page looks normal.
  */
-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.
  */

package/dist/runtime/dom/reactEventHelpers.js

@@ -5,7 +5,97 @@
  * 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 { REVEAL_SNAPSHOT_JS } from './actionEffectsScripts.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 +104,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 +118,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 +184,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 +219,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 +237,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 +256,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 +274,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 +284,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 +297,7 @@ export const REACT_FILL_SCRIPT = `
     return {
       success: false,
       fileInput: true,
-      elementType: tagName,
+      elementType: tagName + viaLabel,
       inputType: inputType,
       error: 'File input'
     };
@@ -226,7 +323,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 +339,7 @@ export const REACT_FILL_SCRIPT = `
       return {
         success: false,
         error: rejection.error,
-        elementType: tagName,
+        elementType: tagName + viaLabel,
         inputType: inputType,
         suggestion: rejection.suggestion
       };
@@ -258,7 +355,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 +367,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 +378,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 +436,20 @@ 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)`.
+ * A hover first notes what is hidden around the element
+ * ({@link REVEAL_SNAPSHOT_JS}), so its result can say what it revealed. For
+ * a press, a probe (`window.__bdgPressProbe`) records whether the press
+ * reaches the element, and otherwise which element it landed on: a browser
+ * dialog or bubble can swallow input while the page looks normal.
  */
 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 +499,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 +516,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 +527,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 +594,25 @@ export const CLICK_ELEMENT_SCRIPT = `
   else if (!hasSize) obstruction = 'zero-size';
   else if (!hittable) obstruction = 'covered by another element' + coveredBy();
 
+  if (action === 'hover') (${REVEAL_SNAPSHOT_JS})(el);
+
+  if (hittable && action !== 'hover') {
+    const probe = { reached: false, landedOn: null };
+    const markReached = (event) => {
+      const path = event.composedPath();
+      if (path.includes(el)) probe.reached = true;
+      else if (!probe.landedOn && path[0] && path[0].nodeType === 1) probe.landedOn = describe(path[0]);
+    };
+    ['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,