browser-debugger-cli 0.8.0 → 0.10.0

package/dist/runtime/dom/formDiscovery.js

@@ -18,6 +18,55 @@ export const FORM_DISCOVERY_SCRIPT = `
 (function() {
   const result = { forms: [] };
 
+  // Rendered and not visibility-hidden, ancestors included (opacity is left
+  // out: styled checkboxes and radios are often transparent)
+  function isShown(element) {
+    if (typeof element.checkVisibility === 'function') {
+      return element.checkVisibility({ visibilityProperty: true });
+    }
+    const style = window.getComputedStyle(element);
+    return style.display !== 'none' && style.visibility !== 'hidden';
+  }
+
+  // Inside an open dialog: <dialog open>, aria-modal or a dialog role, or a
+  // modal without them (DocSearch): an overlay ancestor below <body>
+  // (position fixed or absolute) that is raised (z-index > 0) or has a
+  // backdrop and whose class names a modal or dialog, or a fixed overlay over
+  // half the viewport or more that is raised or lies over other page content
+  // at the viewport centre. Static wrappers (Drupal's
+  // dialog-off-canvas-main-canvas) and fixed app shells holding the whole
+  // page are not dialogs.
+  function inDialog(element) {
+    if (element.closest('dialog[open], [aria-modal="true"], [role="dialog"], [role="alertdialog"]')) return true;
+    const viewportArea = window.innerWidth * window.innerHeight;
+    for (let node = element.parentElement; node && node !== document.body; node = node.parentElement) {
+      const style = window.getComputedStyle(node);
+      if (style.position !== 'fixed' && style.position !== 'absolute') continue;
+      const raised = parseInt(style.zIndex, 10) > 0;
+      const className = typeof node.className === 'string' ? node.className : '';
+      if (/(^|[\\s_-])(modal|dialog)($|[\\s_-])/i.test(className) && (raised || hasBackdrop(node))) return true;
+      if (style.position !== 'fixed') continue;
+      const box = node.getBoundingClientRect();
+      if (box.width * box.height >= viewportArea / 2 && (raised || coversContent(node))) return true;
+    }
+    return false;
+  }
+
+  // A backdrop element next to or inside an overlay
+  function hasBackdrop(node) {
+    const backdrop = /backdrop|overlay/i;
+    const near = [node.previousElementSibling, node.nextElementSibling, ...Array.from(node.children)];
+    return near.some((n) => n && typeof n.className === 'string' && backdrop.test(n.className));
+  }
+
+  // The overlay is on top at the viewport centre with other page content
+  // (not its ancestors) below it
+  function coversContent(node) {
+    const stack = document.elementsFromPoint(window.innerWidth / 2, window.innerHeight / 2);
+    if (!stack.length || !node.contains(stack[0])) return false;
+    return stack.some((n) => !n.contains(node) && !node.contains(n));
+  }
+
   function isUnique(selector) {
     try {
       return document.querySelectorAll(selector).length === 1;
@@ -66,9 +115,50 @@ export const FORM_DISCOVERY_SCRIPT = `
       cleaned = cleaned.replace(pattern, '');
     }
     cleaned = cleaned.replace(/\\s{2,}/g, ' ').trim();
+    cleaned = cleaned.replace(/^\\*\\s+/, '').replace(/\\s+\\*(\\s*:?)$/, '$1');
     return cleaned || text.trim();
   }
 
+  // The element labelling a field: label[for], aria-labelledby, wrapping label
+  function labelElement(element) {
+    const labelFor = element.id ? document.querySelector('label[for="' + CSS.escape(element.id) + '"]') : null;
+    const labelledBy = element.getAttribute('aria-labelledby');
+    return labelFor || (labelledBy && document.getElementById(labelledBy)) || element.closest('label');
+  }
+
+  // A standalone required star in label text: "* Name", "Name *", "Name *:"
+  // (not a footnote mark such as "Terms*")
+  function labelMarksRequired(text) {
+    return /^\\*\\s|\\s\\*\\s*:?$/.test(String(text).trim());
+  }
+
+  // Required by attribute, ARIA, or a label marked with a standalone star,
+  // or with an element of its own holding just "*" (<span aria-hidden>*</span>)
+  function isRequired(element) {
+    if (element.required || element.getAttribute('aria-required') === 'true') return true;
+    const label = labelElement(element);
+    if (!label) return false;
+    const clone = label.cloneNode(true);
+    clone.querySelectorAll('input, select, textarea, button').forEach(i => i.remove());
+    return labelMarksRequired(clone.textContent || '') ||
+      Array.from(clone.querySelectorAll('*')).some(n => n.textContent.trim() === '*');
+  }
+
+  // Name of the radio or checkbox group a field belongs to: its radiogroup's
+  // label, its fieldset's legend, or its name
+  function groupLabel(element) {
+    const type = element.type?.toLowerCase();
+    if ((type !== 'radio' && type !== 'checkbox') || !element.name) return undefined;
+    const group = element.closest('[role="radiogroup"], fieldset');
+    const named = group && (group.getAttribute('aria-label') ||
+      (group.querySelector(':scope > legend') || {}).textContent);
+    if (named && named.trim()) return cleanLabelText(named);
+    return element.name
+      .replace(/[_-]/g, ' ')
+      .replace(/([a-z])([A-Z])/g, '$1 $2')
+      .replace(/^./, s => s.toUpperCase());
+  }
+
   function extractLabel(element) {
     if (element.id) {
       const labelFor = document.querySelector('label[for="' + CSS.escape(element.id) + '"]');
@@ -237,7 +327,7 @@ export const FORM_DISCOVERY_SCRIPT = `
     score += Math.min(distinctFields * 3, 30);
     const textTypes = ['text', 'search', 'email', 'password', 'textarea', 'tel', 'url', 'number', 'textbox'];
     if (fields.some((f) => textTypes.includes(f.type))) score += 10;
-    const hasSubmit = buttons.some(b => b.type === 'submit' || b.isPrimary);
+    const hasSubmit = buttons.some(b => b.type === 'submit' || b.primaryClass);
     if (hasSubmit) score += 10;
     const style = window.getComputedStyle(formEl);
     if (style.display === 'none' || style.visibility === 'hidden') score -= 100;
@@ -377,8 +467,7 @@ export const FORM_DISCOVERY_SCRIPT = `
     const allInputs = new Set([...nativeInputs, ...customInputs]);
     let idx = startIndex;
     for (const el of allInputs) {
-      const style = window.getComputedStyle(el);
-      const isHidden = style.display === 'none' || style.visibility === 'hidden' || el.type === 'hidden';
+      const isHidden = el.type === 'hidden' || !isShown(el);
       const value = getFieldValue(el);
       fields.push({
         index: idx,
@@ -389,7 +478,8 @@ export const FORM_DISCOVERY_SCRIPT = `
         label: extractLabel(el),
         name: el.name || null,
         placeholder: el.placeholder || undefined,
-        required: el.required || el.getAttribute('aria-required') === 'true',
+        required: isRequired(el),
+        groupLabel: groupLabel(el),
         disabled: el.disabled || el.getAttribute('aria-disabled') === 'true',
         readOnly: el.readOnly || false,
         hidden: isHidden,
@@ -420,21 +510,22 @@ export const FORM_DISCOVERY_SCRIPT = `
     );
     let idx = startIndex;
     for (const el of buttonEls) {
-      const style = window.getComputedStyle(el);
-      if (style.display === 'none' || style.visibility === 'hidden') continue;
+      if (!isShown(el)) continue;
       const type = el.type?.toLowerCase() || 'button';
       const btnType = type === 'submit' ? 'submit' : type === 'reset' ? 'reset' : 'button';
-      const isPrimary = btnType === 'submit' ||
-                        el.classList.contains('primary') ||
-                        el.classList.contains('btn-primary') ||
-                        el.classList.contains('submit');
+      const explicitSubmit = btnType === 'submit' &&
+        (el.tagName === 'INPUT' || (el.getAttribute('type') || '').toLowerCase() === 'submit');
+      const formDefault = btnType === 'submit' && !explicitSubmit && Boolean(el.form);
+      const primaryClass = Array.from(el.classList).some(c => /^(btn[-_])?(primary|submit)$/i.test(c));
       buttons.push({
         index: idx,
         selector: generateSelector(el),
         label: extractButtonLabel(el),
         type: btnType,
         disabled: el.disabled || el.getAttribute('aria-disabled') === 'true',
-        isPrimary: isPrimary
+        explicitSubmit: explicitSubmit,
+        formDefault: formDefault,
+        primaryClass: primaryClass
       });
       idx++;
     }
@@ -444,9 +535,11 @@ export const FORM_DISCOVERY_SCRIPT = `
   const forms = document.querySelectorAll('form');
   let globalIndex = 0;
 
-  if (forms.length === 0) {
-    const bodyFields = discoverFields(document.body, 0, 0);
-    const bodyButtons = discoverButtons(document.body, bodyFields.length);
+  // A page still loading may not have a body yet
+  const pageRoot = document.body || document.documentElement;
+  if (forms.length === 0 && pageRoot) {
+    const bodyFields = discoverFields(pageRoot, 0, 0);
+    const bodyButtons = discoverButtons(pageRoot, bodyFields.length);
     if (bodyFields.length > 0) {
       result.forms.push({
         index: 0,
@@ -455,6 +548,8 @@ export const FORM_DISCOVERY_SCRIPT = `
         method: 'GET',
         step: null,
         relevanceScore: bodyFields.length * 3,
+        hidden: false,
+        inDialog: false,
         inIframe: false,
         fields: bodyFields,
         buttons: bodyButtons
@@ -468,6 +563,10 @@ export const FORM_DISCOVERY_SCRIPT = `
       const buttons = discoverButtons(formEl, globalIndex);
       globalIndex += buttons.length;
       const inIframe = formEl.ownerDocument !== document;
+      // Shown when a field or a button is (buttons list shown ones only), or
+      // it has neither (a form with only type=hidden inputs and no button)
+      const shown = isShown(formEl) &&
+        (fields.some((f) => !f.hidden) || buttons.length > 0 || fields.length === 0);
       result.forms.push({
         index: i,
         name: extractFormName(formEl),
@@ -475,6 +574,8 @@ export const FORM_DISCOVERY_SCRIPT = `
         method: (formEl.method || 'GET').toUpperCase(),
         step: detectFormStep(formEl),
         relevanceScore: calculateRelevance(formEl, fields, buttons),
+        hidden: !shown,
+        inDialog: shown && inDialog(formEl),
         inIframe: inIframe,
         fields: fields,
         buttons: buttons
@@ -482,8 +583,6 @@ export const FORM_DISCOVERY_SCRIPT = `
     }
   }
 
-  result.forms.sort((a, b) => b.relevanceScore - a.relevanceScore);
-
   // Forms the main document does not contain may be in its same-origin iframes
   if (result.forms.length === 0) {
     result.frameForms = [];
@@ -496,6 +595,7 @@ export const FORM_DISCOVERY_SCRIPT = `
     }
   }
 
+  result.readyState = document.readyState;
   return result;
 })()
 `;

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

@@ -19,11 +19,20 @@ export type PointerAction = 'click' | 'double' | 'right' | 'hover';
  * @returns `Input.dispatchMouseEvent` parameters, in order
  */
 export declare function mouseEvents(action: PointerAction, x: number, y: number): Array<Record<string, unknown>>;
+/**
+ * Whether the mouse press just dispatched reached the target element
+ * (see {@link readPressProbe}).
+ *
+ * @param cdp - CDP connection
+ * @returns False only when the target received no pointerdown/mousedown
+ */
+export declare function pressReachedTarget(cdp: CDPConnection): Promise<boolean>;
 /**
  * Click an element.
  */
 export declare function clickElement(cdp: CDPConnection, selector: string, options?: {
     index?: number;
     action?: PointerAction;
+    strict?: boolean;
 }): Promise<ClickResult>;
 //# sourceMappingURL=fill.d.ts.map

package/dist/runtime/dom/formFillHelpers/fill.js

@@ -5,12 +5,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { CommandError } from '../../../errors/index.js';
-import { fileNotFoundError, uploadDirectoryError, singleFileInputError, fillableElementNotFoundError, clickableElementNotFoundError, clickTargetDetachedError, unexpectedResponseFormatError, operationFailedError, } from '../../../errors/messages.js';
-import { escapeValueForJS, formatScriptExecutionError, throwIfInvalidSelector, withMultipleMatchesWarning, } from './shared.js';
-import { REACT_FILL_SCRIPT, CLICK_ELEMENT_SCRIPT, isFillResult, isClickResult, } from '../reactEventHelpers.js';
-import { FIND_ELEMENTS_JS, selectorArgsJS } from '../targetNode.js';
+import { fileNotFoundError, uploadDirectoryError, singleFileInputError, fillableElementNotFoundError, clickableElementNotFoundError, clickTargetDetachedError, unexpectedResponseFormatError, operationFailedError, pressNotReceivedError, unreachableElementError, } from '../../../errors/messages.js';
+import { escapeValueForJS, formatScriptExecutionError, throwIfInvalidSelector, withMultipleMatchesWarning, withValueMismatchWarning, } from './shared.js';
+import { FILL_READ_BACK_SCRIPT, REACT_FILL_SCRIPT, CLICK_ELEMENT_SCRIPT, isFillResult, isClickResult, } from '../reactEventHelpers.js';
+import { FIND_ELEMENTS_JS, LABEL_CONTROL_JS, selectorArgsJS } from '../targetNode.js';
 import { createLogger } from '../../../ui/logging/index.js';
-import { POINTER_ACTION_DONE, domClickFallbackWarning } from '../../../ui/messages/commands.js';
+import { CLICK_NOT_RECEIVED_WARNING, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, domClickFallbackWarning, } from '../../../ui/messages/commands.js';
 import { getErrorMessage } from '../../../utils/errors.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 const log = createLogger('dom');
@@ -38,7 +38,12 @@ export async function fillElement(cdp, selector, value, options = {}) {
         }
         if (cdpResponse.result?.value && isFillResult(cdpResponse.result.value)) {
             const result = cdpResponse.result.value;
-            return result.fileInput ? await setFileInput(cdp, selector, value, options) : result;
+            if (!result.fileInput)
+                return withValueMismatchWarning(await withReadBack(cdp, result));
+            const uploaded = await setFileInput(cdp, selector, value, options);
+            return uploaded.success && result.elementType
+                ? { ...uploaded, elementType: result.elementType }
+                : uploaded;
         }
         const err = unexpectedResponseFormatError('FillResult');
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
@@ -52,6 +57,52 @@ export async function fillElement(cdp, selector, value, options = {}) {
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
     }
 }
+/** How long reading a filled value back may take before it is skipped */
+const READ_BACK_TIMEOUT_MS = 1000;
+/**
+ * Add the read-back of a successful fill ({@link FILL_READ_BACK_SCRIPT}):
+ * `valueMismatch` when the field's value is not the one given. The fill
+ * stands without it when the read-back fails, takes longer than
+ * {@link READ_BACK_TIMEOUT_MS} or finds nothing (a change handler navigated
+ * or replaced the page).
+ *
+ * @param cdp - CDP connection
+ * @param result - Fill result
+ * @returns The result, with `valueMismatch` when the value differs
+ */
+async function withReadBack(cdp, result) {
+    if (!result.success)
+        return result;
+    let timer;
+    const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), READ_BACK_TIMEOUT_MS);
+    });
+    const readBack = cdp
+        .send('Runtime.evaluate', {
+        expression: FILL_READ_BACK_SCRIPT,
+        returnByValue: true,
+        awaitPromise: true,
+    })
+        .then((response) => response.result?.value)
+        .catch((error) => {
+        log.debug(`Filled value not read back: ${getErrorMessage(error)}`);
+        return undefined;
+    });
+    const mismatch = await Promise.race([readBack, timedOut]).finally(() => clearTimeout(timer));
+    return isValueMismatch(mismatch) ? { ...result, valueMismatch: mismatch } : result;
+}
+/**
+ * Whether a read-back value is a mismatch.
+ *
+ * @param value - Value from {@link FILL_READ_BACK_SCRIPT}
+ * @returns True for `{ expected, actual }`
+ */
+function isValueMismatch(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return typeof obj['expected'] === 'string' && typeof obj['actual'] === 'string';
+}
 /** Empties a file input as a user removing the selection would (with events). */
 const CLEAR_FILE_INPUT_FUNCTION = `function () {
   this.value = '';
@@ -125,7 +176,7 @@ async function setFileInput(cdp, selector, value, options) {
         return problem;
     try {
         const located = (await cdp.send('Runtime.evaluate', {
-            expression: `(${FIND_ELEMENTS_JS})(${selectorArgsJS(selector)})[${options.index ?? 0}]`,
+            expression: `((el) => (${LABEL_CONTROL_JS})(el) || el)((${FIND_ELEMENTS_JS})(${selectorArgsJS(selector)})[${options.index ?? 0}])`,
             objectGroup: UPLOAD_OBJECT_GROUP,
         }));
         if (located.exceptionDetails)
@@ -213,6 +264,87 @@ export function mouseEvents(action, x, y) {
     ];
     return action === 'double' ? [moved, ...press(1), ...press(2)] : [moved, ...press(1)];
 }
+/**
+ * Page script that stops the press probe installed by CLICK_ELEMENT_SCRIPT
+ * and evaluates to whether the mouse press reached the target and, when it
+ * did not, the element it landed on (if the page saw it at all).
+ */
+const PRESS_PROBE_READ_SCRIPT = `(() => {
+  const probe = window.__bdgPressProbe;
+  delete window.__bdgPressProbe;
+  if (!probe) return { reached: true };
+  probe.stop();
+  return { reached: probe.reached, landedOn: probe.landedOn };
+})()`;
+/**
+ * Read the press probe: whether the mouse press just dispatched reached the
+ * target element, and otherwise where it landed.
+ *
+ * Any doubt (no probe, evaluation failure) counts as reached, so only a
+ * press that the page provably never saw is reported.
+ *
+ * @param cdp - CDP connection
+ * @returns Outcome; not reached only when the target received no pointerdown/mousedown
+ */
+async function readPressProbe(cdp) {
+    try {
+        const response = (await cdp.send('Runtime.evaluate', {
+            expression: PRESS_PROBE_READ_SCRIPT,
+            returnByValue: true,
+        }));
+        const value = response.result?.value;
+        if (value?.reached !== false)
+            return { reached: true };
+        return typeof value.landedOn === 'string'
+            ? { reached: false, landedOn: value.landedOn }
+            : { reached: false };
+    }
+    catch (error) {
+        log.debug(`Press probe not read: ${getErrorMessage(error)}`);
+        return { reached: true };
+    }
+}
+/**
+ * Whether the mouse press just dispatched reached the target element
+ * (see {@link readPressProbe}).
+ *
+ * @param cdp - CDP connection
+ * @returns False only when the target received no pointerdown/mousedown
+ */
+export async function pressReachedTarget(cdp) {
+    return (await readPressProbe(cdp)).reached;
+}
+/**
+ * Dispatch real mouse events for an action, checking after the first press
+ * that the target received it. With `stopIfMissed`, a press that missed is
+ * only released (no further presses). If dispatching fails first, the press
+ * probe is still removed from the page.
+ *
+ * @param cdp - CDP connection
+ * @param action - What to do
+ * @param point - Page coordinates
+ * @param stopIfMissed - Stop after releasing a press that missed (--strict)
+ * @returns Whether the first press reached the target, and where it landed otherwise
+ */
+async function dispatchMouseAction(cdp, action, point, stopIfMissed) {
+    let outcome;
+    try {
+        for (const event of mouseEvents(action, point.x, point.y)) {
+            await cdp.send('Input.dispatchMouseEvent', event);
+            if (event['type'] === 'mouseReleased' && outcome?.reached === false && stopIfMissed)
+                break;
+            if (event['type'] === 'mousePressed' && outcome === undefined) {
+                outcome = await readPressProbe(cdp);
+            }
+        }
+    }
+    catch (error) {
+        if (outcome === undefined)
+            await readPressProbe(cdp);
+        throw error;
+    }
+    return outcome ?? { reached: true };
+}
 /**
  * Drop the located element from the page without waiting: right after a
  * click on a link, evaluation waits until the new page commits (seconds for a
@@ -225,30 +357,62 @@ function releaseClickTarget(cdp) {
         .send('Runtime.evaluate', { expression: 'delete window.__bdgClickTarget' })
         .catch((error) => log.debug(`Click target not released: ${getErrorMessage(error)}`));
 }
+/**
+ * Refuse a pointer action under `--strict` (exit 90, the page's state
+ * conflicts with the request): the element is unreachable by the mouse, or
+ * the press never reached it.
+ *
+ * @param result - Located click (selector and element description)
+ * @param action - What was refused
+ * @param why - Why the mouse could not reach it (nothing was sent), or the
+ *   press that was sent and missed
+ * @returns Never
+ * @throws CommandError always
+ */
+function refuseUnreachable(result, action, why) {
+    const target = { selector: result.selector ?? '', element: result.element };
+    const verb = POINTER_ACTION_NOUN[action];
+    const err = 'missed' in why
+        ? pressNotReceivedError(target, verb, why.missed.landedOn)
+        : unreachableElementError(target, why.obstruction, verb);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_CONFLICT);
+}
 /**
  * Click a located element.
  *
  * Uses real mouse events (pointerdown/mousedown/pointerup/mouseup/click, all
  * trusted) at the element's center when it is the topmost element there, so
  * components that react to pointer or mouse events (menus, selects) respond.
- * Otherwise (covered or zero-size) falls back to `el.click()` and says so.
+ * Otherwise (covered or zero-size) falls back to `el.click()` and says so,
+ * or with `strict` refuses (as it does when the press never reached it).
  * Double and right clicks, and hovering, work the same way.
  *
  * @param cdp - CDP connection
  * @param located - Locate result with center point
  * @param action - Click, double click, right click or hover
+ * @param strict - Refuse instead of falling back to DOM events
  * @returns Click result
+ * @throws CommandError under `strict` when a user could not reach the element
  */
-async function performClick(cdp, located, action) {
+async function performClick(cdp, located, action, strict) {
     const { x, y, hittable, obstruction, ...result } = located;
     if (!result.success)
         return result;
     if (hittable && x !== undefined && y !== undefined) {
-        for (const event of mouseEvents(action, x, y)) {
-            await cdp.send('Input.dispatchMouseEvent', event);
-        }
+        const press = await dispatchMouseAction(cdp, action, { x, y }, strict);
+        releaseClickTarget(cdp);
+        if (!press.reached && strict)
+            refuseUnreachable(result, action, { missed: press });
+        return withMultipleMatchesWarning({
+            ...result,
+            action,
+            method: 'mouse',
+            ...(!press.reached && { warning: CLICK_NOT_RECEIVED_WARNING }),
+        }, result.selectedIndex, `${POINTER_ACTION_DONE[action].toLowerCase()} the first visible one`);
+    }
+    if (strict) {
         releaseClickTarget(cdp);
-        return withMultipleMatchesWarning({ ...result, action, method: 'mouse' }, result.selectedIndex, `${POINTER_ACTION_DONE[action].toLowerCase()} the first visible one`);
+        refuseUnreachable(result, action, { obstruction: obstruction ?? null });
     }
     const response = (await cdp.send('Runtime.evaluate', {
         expression: domFallbackScript(action),
@@ -282,7 +446,7 @@ export async function clickElement(cdp, selector, options = {}) {
             throw new CommandError(errorMessage, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
         }
         if (cdpResponse.result?.value && isClickResult(cdpResponse.result.value)) {
-            return await performClick(cdp, cdpResponse.result.value, action);
+            return await performClick(cdp, cdpResponse.result.value, action, options.strict === true);
         }
         const err = unexpectedResponseFormatError('ClickResult');
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);

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

@@ -4,7 +4,7 @@
  * - `fill.ts`      — fillElement, clickElement
  * - `pressKey.ts`  — pressKeyElement + types
  * - `scroll.ts`    — scrollPage + types
- * - `stability.ts` — waitForActionStability
+ * - `stability.ts` — withActionStability
  * - `shared.ts`    — internal script/error helpers
  *
  * Callers keep importing from `@/commands/dom/formFillHelpers.js` which
@@ -13,5 +13,5 @@
 export { fillElement, clickElement } from './fill.js';
 export { pressKeyElement, type PressKeyOptions, type PressKeyResult, } from './pressKey.js';
 export { scrollPage, type ScrollOptions, type ScrollResult, } from './scroll.js';
-export { waitForActionStability } from './stability.js';
+export { withActionStability } from './stability.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/dom/formFillHelpers/index.js

@@ -4,7 +4,7 @@
  * - `fill.ts`      — fillElement, clickElement
  * - `pressKey.ts`  — pressKeyElement + types
  * - `scroll.ts`    — scrollPage + types
- * - `stability.ts` — waitForActionStability
+ * - `stability.ts` — withActionStability
  * - `shared.ts`    — internal script/error helpers
  *
  * Callers keep importing from `@/commands/dom/formFillHelpers.js` which
@@ -13,5 +13,5 @@
 export { fillElement, clickElement } from './fill.js';
 export { pressKeyElement, } from './pressKey.js';
 export { scrollPage, } from './scroll.js';
-export { waitForActionStability } from './stability.js';
+export { withActionStability } from './stability.js';
 //# sourceMappingURL=index.js.map

package/dist/runtime/dom/formFillHelpers/pressKey.js

@@ -4,10 +4,11 @@
  * that CDP skips (keypress / input / change / submit).
  */
 import { CommandError } from '../../../errors/index.js';
-import { keyPressFailedError, operationFailedError, unknownKeyError } from '../../../errors/messages.js';
+import { VIA_LABEL_SUFFIX, keyPressFailedError, operationFailedError, unknownKeyError, } from '../../../errors/messages.js';
+import { ELEMENT_IDENTITY_JS } from '../elementInfo.js';
 import { throwIfInvalidSelector, withMultipleMatchesWarning, } from './shared.js';
 import { describeModifiers, getKeyDefinition, impliesShift, MODIFIER_FLAGS, parseModifiers, similarKeyNames, shortcutCommands, } from '../keyMapping.js';
-import { FIND_ELEMENTS_JS, selectorArgsJS } from '../targetNode.js';
+import { FIND_ELEMENTS_JS, LABEL_CONTROL_JS, selectorArgsJS } from '../targetNode.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 const FOCUS_ELEMENT_SCRIPT = `
 (function(selector, parts, index) {
@@ -29,6 +30,9 @@ const FOCUS_ELEMENT_SCRIPT = `
   } else {
     el = allMatches[0];
   }
+  const labelControl = (${LABEL_CONTROL_JS})(el);
+  const viaLabel = labelControl ? ${JSON.stringify(VIA_LABEL_SUFFIX)} : '';
+  if (labelControl) el = labelControl;
 
   const pageLevel = el === document.body || el === document.documentElement;
   if (!pageLevel) {
@@ -61,7 +65,13 @@ const FOCUS_ELEMENT_SCRIPT = `
     }
   }
 
-  return { success: true, selector: selector, elementType: el.tagName.toLowerCase(), matchCount: allMatches.length };
+  return {
+    success: true,
+    selector: selector,
+    element: (${ELEMENT_IDENTITY_JS})(el),
+    elementType: el.tagName.toLowerCase() + viaLabel,
+    matchCount: allMatches.length
+  };
 })`;
 /** Exit codes and suggestions for focus failures, by reason. */
 const FOCUS_FAILURES = {
@@ -135,6 +145,7 @@ export async function pressKeyElement(cdp, selector, keyName, options = {}) {
             key: keyName,
             times,
             ...(modifierFlags > 0 && { modifiers: describeModifiers(modifierFlags) }),
+            ...(focusResult.element !== undefined && { element: focusResult.element }),
             elementType: focusResult.elementType,
             ...(focusResult.matchCount !== undefined && { matchCount: focusResult.matchCount }),
         }, options.index, 'pressed the key on the first');

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

@@ -6,6 +6,9 @@ import type { CDPConnection } from '../../../connection/cdp.js';
 import type { ScrollResult } from '../../../ipc/protocol/domTypes.js';
 /**
  * Scroll options.
+ *
+ * The reported viewport is the layout viewport without scrollbars and the
+ * page size the scrolling element's, as in `bdg dom layout`.
  */
 export interface ScrollOptions {
     down?: number;