browser-debugger-cli 0.7.2 → 0.9.0

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

@@ -0,0 +1,414 @@
+/**
+ * Fill and click operations — inject React-compatible page-context scripts
+ * and unpack structured results.
+ */
+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, 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 { CLICK_NOT_RECEIVED_WARNING, POINTER_ACTION_DONE, domClickFallbackWarning, } from '../../../ui/messages/commands.js';
+import { getErrorMessage } from '../../../utils/errors.js';
+import { EXIT_CODES } from '../../../utils/exitCodes.js';
+const log = createLogger('dom');
+/**
+ * Fill a form element with a value in a React-compatible way.
+ */
+export async function fillElement(cdp, selector, value, options = {}) {
+    const scriptOptions = {
+        blur: options.blur ?? true,
+        index: options.index,
+    };
+    const expression = `(${REACT_FILL_SCRIPT})(${selectorArgsJS(selector)}, '${escapeValueForJS(value)}', ${JSON.stringify(scriptOptions)})`;
+    try {
+        const response = await cdp.send('Runtime.evaluate', {
+            expression,
+            returnByValue: true,
+            userGesture: true,
+        });
+        const cdpResponse = response;
+        if (cdpResponse.exceptionDetails) {
+            throwIfInvalidSelector(cdpResponse.exceptionDetails, selector);
+            const errorMessage = formatScriptExecutionError(cdpResponse.exceptionDetails, selector, 'fill', expression);
+            const err = fillableElementNotFoundError(selector);
+            throw new CommandError(errorMessage, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
+        }
+        if (cdpResponse.result?.value && isFillResult(cdpResponse.result.value)) {
+            const result = cdpResponse.result.value;
+            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);
+    }
+    catch (error) {
+        if (error instanceof CommandError) {
+            throw error;
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const err = operationFailedError('fill element', errorMessage);
+        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 = '';
+  this.dispatchEvent(new Event('input', { bubbles: true }));
+  this.dispatchEvent(new Event('change', { bubbles: true }));
+}`;
+/** Object group for remote objects created while selecting files. */
+const UPLOAD_OBJECT_GROUP = 'bdg-upload';
+/**
+ * Resolve the files of a file-input value: one path (even with commas in its
+ * name, when that file exists), several separated by commas, or none for "".
+ *
+ * @param value - Value given to `dom fill`
+ * @param cwd - Directory relative paths are resolved against
+ * @returns Absolute paths (empty clears the input)
+ */
+function uploadPaths(value, cwd) {
+    if (!value.trim())
+        return [];
+    const whole = path.resolve(cwd, value.trim());
+    if (fs.existsSync(whole))
+        return [whole];
+    return value
+        .split(',')
+        .map((file) => file.trim())
+        .filter(Boolean)
+        .map((file) => path.resolve(cwd, file));
+}
+/**
+ * The first file that cannot be uploaded, as a failed fill result.
+ *
+ * @param files - Absolute paths
+ * @returns Failure, or null when all are readable files
+ */
+function uploadProblem(files) {
+    for (const file of files) {
+        if (!fs.existsSync(file)) {
+            const err = fileNotFoundError(file);
+            return {
+                success: false,
+                error: err.message,
+                suggestion: err.suggestion,
+                exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+            };
+        }
+        if (fs.statSync(file).isDirectory()) {
+            const err = uploadDirectoryError(file);
+            return {
+                success: false,
+                error: err.message,
+                suggestion: err.suggestion,
+                exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Select files in a file input, as a user picking them in the file dialog.
+ *
+ * @param cdp - CDP connection
+ * @param selector - Selector (or bound-node placeholder) of the file input
+ * @param value - File path, several separated by commas, or "" to clear the input
+ * @param options - Fill options (index, cwd for relative paths)
+ * @returns Fill result
+ */
+async function setFileInput(cdp, selector, value, options) {
+    const files = uploadPaths(value, options.cwd ?? process.cwd());
+    const problem = uploadProblem(files);
+    if (problem)
+        return problem;
+    try {
+        const located = (await cdp.send('Runtime.evaluate', {
+            expression: `((el) => (${LABEL_CONTROL_JS})(el) || el)((${FIND_ELEMENTS_JS})(${selectorArgsJS(selector)})[${options.index ?? 0}])`,
+            objectGroup: UPLOAD_OBJECT_GROUP,
+        }));
+        if (located.exceptionDetails)
+            throwIfInvalidSelector(located.exceptionDetails, selector);
+        const objectId = located.result?.objectId;
+        if (!objectId) {
+            const err = fillableElementNotFoundError(selector);
+            return { success: false, error: err.message, suggestion: err.suggestion };
+        }
+        const multiple = (await cdp.send('Runtime.callFunctionOn', {
+            objectId,
+            functionDeclaration: 'function () { return this.multiple; }',
+            returnByValue: true,
+        }));
+        if (files.length > 1 && multiple.result?.value !== true) {
+            const err = singleFileInputError(files.length);
+            return {
+                success: false,
+                error: err.message,
+                suggestion: err.suggestion,
+                exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            };
+        }
+        if (files.length > 0)
+            await cdp.send('DOM.setFileInputFiles', { files, objectId });
+        else {
+            await cdp.send('Runtime.callFunctionOn', {
+                objectId,
+                functionDeclaration: CLEAR_FILE_INPUT_FUNCTION,
+            });
+        }
+    }
+    finally {
+        await cdp
+            .send('Runtime.releaseObjectGroup', { objectGroup: UPLOAD_OBJECT_GROUP })
+            .catch((error) => log.debug(`Could not release upload objects: ${getErrorMessage(error)}`));
+    }
+    return {
+        success: true,
+        selector,
+        value: files.length > 0 ? files.map((file) => path.basename(file)).join(', ') : '(cleared)',
+        elementType: 'input',
+        inputType: 'file',
+    };
+}
+/**
+ * Page script doing an action on the located target with DOM events (when
+ * the mouse cannot reach it); evaluates to false if the target is gone.
+ *
+ * @param action - What to do
+ * @returns Script
+ */
+function domFallbackScript(action) {
+    const events = {
+        click: 'el.click();',
+        double: "el.click(); el.click(); el.dispatchEvent(new MouseEvent('dblclick', init));",
+        right: "el.dispatchEvent(new MouseEvent('contextmenu', { ...init, button: 2 }));",
+        hover: "['pointerover', 'pointerenter', 'mouseover', 'mouseenter', 'mousemove'].forEach((type) => el.dispatchEvent(new MouseEvent(type, init)));",
+    };
+    return `(() => {
+  const el = window.__bdgClickTarget;
+  delete window.__bdgClickTarget;
+  if (!el || !el.isConnected) return false;
+  const init = { bubbles: true, cancelable: true, composed: true, view: el.ownerDocument.defaultView };
+  ${events[action]}
+  return true;
+})()`;
+}
+/**
+ * Real mouse events for an action at a point.
+ *
+ * @param action - What to do
+ * @param x - Page x
+ * @param y - Page y
+ * @returns `Input.dispatchMouseEvent` parameters, in order
+ */
+export function mouseEvents(action, x, y) {
+    const moved = { type: 'mouseMoved', x, y };
+    if (action === 'hover')
+        return [moved];
+    const button = action === 'right' ? 'right' : 'left';
+    const press = (clickCount) => [
+        { type: 'mousePressed', x, y, button, clickCount },
+        { type: 'mouseReleased', x, y, button, clickCount },
+    ];
+    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.
+ */
+const PRESS_PROBE_READ_SCRIPT = `(() => {
+  const probe = window.__bdgPressProbe;
+  delete window.__bdgPressProbe;
+  if (!probe) return true;
+  probe.stop();
+  return probe.reached;
+})()`;
+/**
+ * Whether the mouse press just dispatched reached the target element.
+ *
+ * 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 False only when the target received no pointerdown/mousedown
+ */
+export async function pressReachedTarget(cdp) {
+    try {
+        const response = (await cdp.send('Runtime.evaluate', {
+            expression: PRESS_PROBE_READ_SCRIPT,
+            returnByValue: true,
+        }));
+        return response.result?.value !== false;
+    }
+    catch (error) {
+        log.debug(`Press probe not read: ${getErrorMessage(error)}`);
+        return true;
+    }
+}
+/**
+ * Dispatch real mouse events for an action, checking after the first press
+ * that the target received it. If dispatching fails first, the press probe
+ * is still removed from the page.
+ *
+ * @param cdp - CDP connection
+ * @param action - What to do
+ * @param x - Page x
+ * @param y - Page y
+ * @returns False if the press never reached the target
+ */
+async function dispatchMouseAction(cdp, action, x, y) {
+    let reached;
+    try {
+        for (const event of mouseEvents(action, x, y)) {
+            await cdp.send('Input.dispatchMouseEvent', event);
+            if (event['type'] === 'mousePressed' && reached === undefined) {
+                reached = await pressReachedTarget(cdp);
+            }
+        }
+    }
+    catch (error) {
+        if (reached === undefined)
+            await pressReachedTarget(cdp);
+        throw error;
+    }
+    return 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
+ * slow server), which `--no-wait` must not.
+ *
+ * @param cdp - CDP connection
+ */
+function releaseClickTarget(cdp) {
+    void cdp
+        .send('Runtime.evaluate', { expression: 'delete window.__bdgClickTarget' })
+        .catch((error) => log.debug(`Click target not released: ${getErrorMessage(error)}`));
+}
+/**
+ * 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.
+ * 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
+ * @returns Click result
+ */
+async function performClick(cdp, located, action) {
+    const { x, y, hittable, obstruction, ...result } = located;
+    if (!result.success)
+        return result;
+    if (hittable && x !== undefined && y !== undefined) {
+        const reached = await dispatchMouseAction(cdp, action, x, y);
+        releaseClickTarget(cdp);
+        return withMultipleMatchesWarning({
+            ...result,
+            action,
+            method: 'mouse',
+            ...(!reached && { warning: CLICK_NOT_RECEIVED_WARNING }),
+        }, result.selectedIndex, `${POINTER_ACTION_DONE[action].toLowerCase()} the first visible one`);
+    }
+    const response = (await cdp.send('Runtime.evaluate', {
+        expression: domFallbackScript(action),
+        returnByValue: true,
+        userGesture: true,
+    }));
+    if (response.result?.value !== true) {
+        const err = clickTargetDetachedError(result.selector ?? '');
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    return withMultipleMatchesWarning({ ...result, action, method: 'dom', warning: domClickFallbackWarning(obstruction) }, result.selectedIndex, `${POINTER_ACTION_DONE[action].toLowerCase()} the first visible one`);
+}
+/**
+ * Click an element.
+ */
+export async function clickElement(cdp, selector, options = {}) {
+    const indexArg = options.index ?? 'null';
+    const action = options.action ?? 'click';
+    const expression = `(${CLICK_ELEMENT_SCRIPT})(${selectorArgsJS(selector)}, ${indexArg}, '${action}')`;
+    try {
+        const response = await cdp.send('Runtime.evaluate', {
+            expression,
+            returnByValue: true,
+            userGesture: true,
+        });
+        const cdpResponse = response;
+        if (cdpResponse.exceptionDetails) {
+            throwIfInvalidSelector(cdpResponse.exceptionDetails, selector);
+            const errorMessage = formatScriptExecutionError(cdpResponse.exceptionDetails, selector, 'click', expression);
+            const err = clickableElementNotFoundError(selector);
+            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);
+        }
+        const err = unexpectedResponseFormatError('ClickResult');
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
+    }
+    catch (error) {
+        if (error instanceof CommandError) {
+            throw error;
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const err = operationFailedError('click element', errorMessage);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
+    }
+}
+//# sourceMappingURL=fill.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * Form-fill helper barrel. Splits the former formFillHelpers.ts into:
+ *
+ * - `fill.ts`      — fillElement, clickElement
+ * - `pressKey.ts`  — pressKeyElement + types
+ * - `scroll.ts`    — scrollPage + types
+ * - `stability.ts` — withActionStability
+ * - `shared.ts`    — internal script/error helpers
+ *
+ * Callers keep importing from `@/commands/dom/formFillHelpers.js` which
+ * resolves to this barrel.
+ */
+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 { withActionStability } from './stability.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,17 @@
+/**
+ * Form-fill helper barrel. Splits the former formFillHelpers.ts into:
+ *
+ * - `fill.ts`      — fillElement, clickElement
+ * - `pressKey.ts`  — pressKeyElement + types
+ * - `scroll.ts`    — scrollPage + types
+ * - `stability.ts` — withActionStability
+ * - `shared.ts`    — internal script/error helpers
+ *
+ * Callers keep importing from `@/commands/dom/formFillHelpers.js` which
+ * resolves to this barrel.
+ */
+export { fillElement, clickElement } from './fill.js';
+export { pressKeyElement, } from './pressKey.js';
+export { scrollPage, } from './scroll.js';
+export { withActionStability } from './stability.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,28 @@
+/**
+ * Key press on a focused element — focuses the element, then dispatches
+ * CDP Input.dispatchKeyEvent pairs plus synthetic browser-level events
+ * that CDP skips (keypress / input / change / submit).
+ */
+import type { CDPConnection } from '../../../connection/cdp.js';
+import type { PressKeyResult } from '../../../ipc/protocol/domTypes.js';
+/**
+ * Options for pressing a key on an element.
+ */
+export interface PressKeyOptions {
+    index?: number;
+    times?: number;
+    modifiers?: string;
+}
+export type { PressKeyResult } from '../../../ipc/protocol/domTypes.js';
+/**
+ * Press a key on an element: focus it, then dispatch a real keyDown/keyUp
+ * pair through CDP. Repeats `times` times with the given modifiers.
+ *
+ * Keys that type text (letters, digits, Space, Enter) carry `text`, so the
+ * browser performs the key's default action exactly like a physical key:
+ * the character is inserted (with trusted keypress/input events), Enter adds
+ * a newline in a textarea or submits the form once from an input, and Tab
+ * moves focus. No synthetic events are fired.
+ */
+export declare function pressKeyElement(cdp: CDPConnection, selector: string, keyName: string, options?: PressKeyOptions): Promise<PressKeyResult>;
+//# sourceMappingURL=pressKey.d.ts.map

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

@@ -0,0 +1,206 @@
+/**
+ * Key press on a focused element — focuses the element, then dispatches
+ * CDP Input.dispatchKeyEvent pairs plus synthetic browser-level events
+ * that CDP skips (keypress / input / change / submit).
+ */
+import { CommandError } from '../../../errors/index.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, LABEL_CONTROL_JS, selectorArgsJS } from '../targetNode.js';
+import { EXIT_CODES } from '../../../utils/exitCodes.js';
+const FOCUS_ELEMENT_SCRIPT = `
+(function(selector, parts, index) {
+  const allMatches = (${FIND_ELEMENTS_JS})(selector, parts);
+  if (allMatches.length === 0) {
+    return { success: false, reason: 'not-found', error: 'Element not found: ' + selector };
+  }
+
+  let el;
+  if (typeof index === 'number' && index >= 0) {
+    if (index >= allMatches.length) {
+      return {
+        success: false,
+        reason: 'range',
+        error: 'Index ' + index + ' out of range (found ' + allMatches.length + ' nodes, use 0-' + (allMatches.length - 1) + ')'
+      };
+    }
+    el = allMatches[index];
+  } 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) {
+    const wasFocused = el.getRootNode().activeElement === el;
+    el.focus();
+    // A user clicking into a field before typing lands at the end of its text
+    if (!wasFocused) {
+      try {
+        if (typeof el.setSelectionRange === 'function' && typeof el.value === 'string') {
+          el.setSelectionRange(el.value.length, el.value.length);
+        } else if (el.isContentEditable) {
+          const range = el.ownerDocument.createRange();
+          range.selectNodeContents(el);
+          range.collapse(false);
+          const selection = el.ownerDocument.getSelection();
+          selection.removeAllRanges();
+          selection.addRange(range);
+        }
+      } catch (e) {
+        // Inputs without a caret (number, email, checkbox) keep theirs
+      }
+    }
+    const focused = el.getRootNode().activeElement;
+    if (focused !== el && !el.contains(focused)) {
+      return {
+        success: false,
+        reason: 'not-focusable',
+        error: 'Element <' + el.tagName.toLowerCase() + '> cannot receive keyboard focus' + (el.matches(':disabled') ? ' (it is disabled)' : '')
+      };
+    }
+  }
+
+  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 = {
+    'not-found': {
+        exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+        suggestion: 'Verify the selector matches a focusable element',
+    },
+    range: {
+        exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+        suggestion: 'Use an --index within the matches',
+    },
+    'not-focusable': {
+        exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+        suggestion: 'Target an input, textarea, button, link or [tabindex] element; use "body" for page-level keys like Escape',
+    },
+};
+/**
+ * Press a key on an element: focus it, then dispatch a real keyDown/keyUp
+ * pair through CDP. Repeats `times` times with the given modifiers.
+ *
+ * Keys that type text (letters, digits, Space, Enter) carry `text`, so the
+ * browser performs the key's default action exactly like a physical key:
+ * the character is inserted (with trusted keypress/input events), Enter adds
+ * a newline in a textarea or submits the form once from an input, and Tab
+ * moves focus. No synthetic events are fired.
+ */
+export async function pressKeyElement(cdp, selector, keyName, options = {}) {
+    const keyDef = getKeyDefinition(keyName);
+    if (!keyDef) {
+        const err = unknownKeyError(keyName, similarKeyNames(keyName));
+        return {
+            success: false,
+            error: err.message,
+            suggestion: err.suggestion,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+        };
+    }
+    const times = options.times ?? 1;
+    const implicitShift = impliesShift(keyName) ? MODIFIER_FLAGS.shift : 0;
+    const modifierFlags = parseModifiers(options.modifiers) | implicitShift;
+    const indexArg = options.index ?? 'null';
+    const focusExpression = `(${FOCUS_ELEMENT_SCRIPT})(${selectorArgsJS(selector)}, ${indexArg})`;
+    try {
+        const focusResponse = await cdp.send('Runtime.evaluate', {
+            expression: focusExpression,
+            returnByValue: true,
+        });
+        const focusCdpResponse = focusResponse;
+        if (focusCdpResponse.exceptionDetails) {
+            throwIfInvalidSelector(focusCdpResponse.exceptionDetails, selector);
+            const err = keyPressFailedError(`focus: ${focusCdpResponse.exceptionDetails.text}`);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
+        }
+        const focusResult = focusCdpResponse.result?.value;
+        if (!focusResult?.success) {
+            const failure = FOCUS_FAILURES[focusResult?.reason ?? ''];
+            return {
+                success: false,
+                error: focusResult?.error ?? 'Failed to focus element',
+                selector,
+                ...(failure && { exitCode: failure.exitCode, suggestion: failure.suggestion }),
+            };
+        }
+        for (let i = 0; i < times; i++) {
+            await dispatchKeyEvent(cdp, 'keyDown', keyDef, modifierFlags);
+            await dispatchKeyEvent(cdp, 'keyUp', keyDef, modifierFlags);
+        }
+        return withMultipleMatchesWarning({
+            success: true,
+            selector,
+            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');
+    }
+    catch (error) {
+        if (error instanceof CommandError) {
+            throw error;
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const err = operationFailedError('press key', errorMessage);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
+    }
+}
+/**
+ * Text a key types with the given modifiers, or undefined for shortcuts and
+ * non-text keys.
+ *
+ * @param keyDef - Key definition
+ * @param modifiers - CDP modifier bit flags
+ * @returns Text to insert, if any
+ */
+function keyText(keyDef, modifiers) {
+    if (!keyDef.text)
+        return undefined;
+    const shortcut = MODIFIER_FLAGS.ctrl | MODIFIER_FLAGS.meta | MODIFIER_FLAGS.alt;
+    if (modifiers & shortcut)
+        return undefined;
+    if (!(modifiers & MODIFIER_FLAGS.shift))
+        return keyDef.text;
+    return keyDef.shiftText ?? keyDef.text.toUpperCase();
+}
+/**
+ * Dispatch one key event through CDP.
+ *
+ * A keyDown with text is sent as `keyDown` (the browser generates the
+ * keypress/input and default action); without text as `rawKeyDown`. Editing
+ * shortcuts (Ctrl/Cmd+A, C, X, V, Z) name their editor command.
+ *
+ * @param cdp - CDP connection
+ * @param type - Event phase
+ * @param keyDef - Key definition
+ * @param modifiers - CDP modifier bit flags
+ */
+async function dispatchKeyEvent(cdp, type, keyDef, modifiers) {
+    const text = keyText(keyDef, modifiers);
+    const key = text && text !== '\r' ? text : keyDef.key;
+    const commands = type === 'keyDown' ? shortcutCommands(keyDef.code, modifiers) : [];
+    await cdp.send('Input.dispatchKeyEvent', {
+        type: type === 'keyDown' && !text ? 'rawKeyDown' : type,
+        code: keyDef.code,
+        key,
+        windowsVirtualKeyCode: keyDef.keyCode,
+        modifiers,
+        ...(type === 'keyDown' && text && { text, unmodifiedText: keyDef.text }),
+        ...(commands.length > 0 && { commands }),
+    });
+}
+//# sourceMappingURL=pressKey.js.map