browser-debugger-cli 0.6.4 → 0.6.6

package/dist/commands/dom/formFillHelpers.js

@@ -2,15 +2,50 @@
  * Form interaction helpers for filling inputs, clicking buttons, etc.
  */
 import { CommandError } from '../../ui/errors/index.js';
+import { createLogger } from '../../ui/logging/index.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
-import { REACT_FILL_SCRIPT, CLICK_ELEMENT_SCRIPT, GET_ELEMENT_BY_INDEX_SCRIPT, } from './reactEventHelpers.js';
+import { getKeyDefinition, parseModifiers } from './keyMapping.js';
+import { REACT_FILL_SCRIPT, CLICK_ELEMENT_SCRIPT, } from './reactEventHelpers.js';
+const log = createLogger('dom');
+/** Network idle threshold for post-action stability (ms) */
+const ACTION_NETWORK_IDLE_MS = 150;
+/** Maximum time to wait for post-action stability (ms) */
+const ACTION_STABILITY_TIMEOUT_MS = 2000;
+/** Check interval for stability polling (ms) */
+const STABILITY_CHECK_INTERVAL_MS = 50;
+/**
+ * Format exception details into a user-friendly error message with troubleshooting hints.
+ *
+ * @param exceptionDetails - CDP exception details
+ * @param selector - CSS selector that was used
+ * @param operationType - Type of operation (fill or click) for tailored hints
+ * @returns Formatted error message with context
+ */
+function formatScriptExecutionError(exceptionDetails, selector, operationType = 'fill') {
+    const errorText = exceptionDetails.text || 'Unknown error';
+    const location = exceptionDetails.lineNumber !== undefined && exceptionDetails.columnNumber !== undefined
+        ? ` at line ${exceptionDetails.lineNumber + 1}, column ${exceptionDetails.columnNumber + 1}`
+        : '';
+    const troubleshootingSteps = operationType === 'fill'
+        ? [
+            `1. Verify element exists: bdg dom query "${selector}"`,
+            '2. Check element is visible and not disabled',
+            `3. Try direct eval: bdg dom eval "document.querySelector('${escapeSelectorForJS(selector)}').value = 'your-value'"`,
+        ]
+        : [
+            `1. Verify element exists: bdg dom query "${selector}"`,
+            '2. Check element is visible and clickable',
+            `3. Try direct eval: bdg dom eval "document.querySelector('${escapeSelectorForJS(selector)}').click()"`,
+        ];
+    return `Script execution failed: ${errorText}${location}\n\nTroubleshooting:\n  ${troubleshootingSteps.join('\n  ')}`;
+}
 /**
  * Fill a form element with a value in a React-compatible way.
  *
  * @param cdp - CDP connection
  * @param selector - CSS selector for the element
  * @param value - Value to fill
- * @param options - Fill options
+ * @param options - Fill options including optional index for multiple matches
  * @returns Promise resolving to fill result
  *
  * @throws CommandError When element operations fail
@@ -24,18 +59,11 @@ import { REACT_FILL_SCRIPT, CLICK_ELEMENT_SCRIPT, GET_ELEMENT_BY_INDEX_SCRIPT, }
  * ```
  */
 export async function fillElement(cdp, selector, value, options = {}) {
-    let targetSelector = selector;
-    if (options.index !== undefined) {
-        const indexResult = await getElementByIndex(cdp, selector, options.index);
-        if (!indexResult.success) {
-            return indexResult;
-        }
-        if (!indexResult.uniqueSelector) {
-            throw new CommandError('Failed to resolve unique selector for element index', { note: 'Element index resolution returned no unique selector' }, EXIT_CODES.SOFTWARE_ERROR);
-        }
-        targetSelector = indexResult.uniqueSelector;
-    }
-    const expression = `(${REACT_FILL_SCRIPT})('${escapeSelectorForJS(targetSelector)}', '${escapeValueForJS(value)}', ${JSON.stringify({ blur: options.blur ?? true })})`;
+    const scriptOptions = {
+        blur: options.blur ?? true,
+        index: options.index,
+    };
+    const expression = `(${REACT_FILL_SCRIPT})('${escapeSelectorForJS(selector)}', '${escapeValueForJS(value)}', ${JSON.stringify(scriptOptions)})`;
     try {
         const response = await cdp.send('Runtime.evaluate', {
             expression,
@@ -44,7 +72,8 @@ export async function fillElement(cdp, selector, value, options = {}) {
         });
         const cdpResponse = response;
         if (cdpResponse.exceptionDetails) {
-            throw new CommandError('Script execution failed', { note: cdpResponse.exceptionDetails.text ?? 'Unknown error' }, EXIT_CODES.SOFTWARE_ERROR);
+            const errorMessage = formatScriptExecutionError(cdpResponse.exceptionDetails, selector, 'fill');
+            throw new CommandError(errorMessage, {}, EXIT_CODES.SOFTWARE_ERROR);
         }
         if (cdpResponse.result?.value) {
             return cdpResponse.result.value;
@@ -64,7 +93,7 @@ export async function fillElement(cdp, selector, value, options = {}) {
  *
  * @param cdp - CDP connection
  * @param selector - CSS selector for the element
- * @param options - Click options
+ * @param options - Click options including optional index for multiple matches
  * @returns Promise resolving to click result
  *
  * @throws CommandError When element operations fail
@@ -78,18 +107,8 @@ export async function fillElement(cdp, selector, value, options = {}) {
  * ```
  */
 export async function clickElement(cdp, selector, options = {}) {
-    let targetSelector = selector;
-    if (options.index !== undefined) {
-        const indexResult = await getElementByIndex(cdp, selector, options.index);
-        if (!indexResult.success) {
-            return indexResult;
-        }
-        if (!indexResult.uniqueSelector) {
-            throw new CommandError('Failed to resolve unique selector for element index', { note: 'Element index resolution returned no unique selector' }, EXIT_CODES.SOFTWARE_ERROR);
-        }
-        targetSelector = indexResult.uniqueSelector;
-    }
-    const expression = `(${CLICK_ELEMENT_SCRIPT})('${escapeSelectorForJS(targetSelector)}')`;
+    const indexArg = options.index ?? 'null';
+    const expression = `(${CLICK_ELEMENT_SCRIPT})('${escapeSelectorForJS(selector)}', ${indexArg})`;
     try {
         const response = await cdp.send('Runtime.evaluate', {
             expression,
@@ -98,7 +117,8 @@ export async function clickElement(cdp, selector, options = {}) {
         });
         const cdpResponse = response;
         if (cdpResponse.exceptionDetails) {
-            throw new CommandError('Script execution failed', { note: cdpResponse.exceptionDetails.text ?? 'Unknown error' }, EXIT_CODES.SOFTWARE_ERROR);
+            const errorMessage = formatScriptExecutionError(cdpResponse.exceptionDetails, selector, 'click');
+            throw new CommandError(errorMessage, {}, EXIT_CODES.SOFTWARE_ERROR);
         }
         if (cdpResponse.result?.value) {
             return cdpResponse.result.value;
@@ -114,63 +134,217 @@ export async function clickElement(cdp, selector, options = {}) {
     }
 }
 /**
- * Get element by index when selector matches multiple elements.
+ * Escape CSS selector for safe inclusion in JavaScript single-quoted string.
+ * Uses JSON.stringify for special characters, then escapes single quotes
+ * since the expression wrapper uses single quotes.
  *
- * @param cdp - CDP connection
- * @param selector - CSS selector
- * @param index - Element index (1-based)
- * @returns Promise resolving to element info
+ * @param selector - CSS selector to escape
+ * @returns Escaped selector safe for single-quoted JS string
  *
- * @throws CommandError When element operations fail
+ * @internal
+ */
+function escapeSelectorForJS(selector) {
+    return JSON.stringify(selector).slice(1, -1).replace(/'/g, "\\'");
+}
+/**
+ * Escape value for safe inclusion in JavaScript single-quoted string.
+ * Uses JSON.stringify for special characters, then escapes single quotes
+ * since the expression wrapper uses single quotes.
+ *
+ * @param value - Value to escape
+ * @returns Escaped value safe for single-quoted JS string
  *
  * @internal
  */
-async function getElementByIndex(cdp, selector, index) {
-    const expression = `(${GET_ELEMENT_BY_INDEX_SCRIPT})('${escapeSelectorForJS(selector)}', ${index})`;
+function escapeValueForJS(value) {
+    return JSON.stringify(value).slice(1, -1).replace(/'/g, "\\'");
+}
+/**
+ * Wait for page to stabilize after an action (click, fill, etc.).
+ *
+ * This is a lightweight stability check designed for post-action waiting:
+ * - Waits for network to be idle for 150ms
+ * - Times out after 2s to avoid hanging
+ * - Does not block on slow background requests
+ *
+ * @param cdp - CDP connection
+ * @returns Promise that resolves when stable or timeout reached
+ *
+ * @remarks
+ * This is intentionally less strict than page readiness on initial load.
+ * It's designed to catch immediate reactions to user actions (AJAX, re-renders)
+ * without waiting for unrelated background activity.
+ */
+export async function waitForActionStability(cdp) {
+    const deadline = Date.now() + ACTION_STABILITY_TIMEOUT_MS;
+    let activeRequests = 0;
+    let lastActivity = Date.now();
+    const requestHandler = () => {
+        activeRequests++;
+        lastActivity = Date.now();
+    };
+    const finishHandler = () => {
+        activeRequests--;
+        if (activeRequests === 0) {
+            lastActivity = Date.now();
+        }
+    };
+    await cdp.send('Network.enable');
+    const cleanupRequest = cdp.on('Network.requestWillBeSent', requestHandler);
+    const cleanupFinished = cdp.on('Network.loadingFinished', finishHandler);
+    const cleanupFailed = cdp.on('Network.loadingFailed', finishHandler);
     try {
-        const response = await cdp.send('Runtime.evaluate', {
-            expression,
+        while (Date.now() < deadline) {
+            if (activeRequests === 0) {
+                const idleTime = Date.now() - lastActivity;
+                if (idleTime >= ACTION_NETWORK_IDLE_MS) {
+                    log.debug(`Network stable after ${idleTime}ms idle`);
+                    return;
+                }
+            }
+            await delay(STABILITY_CHECK_INTERVAL_MS);
+        }
+        log.debug('Stability timeout reached, proceeding');
+    }
+    finally {
+        cleanupRequest();
+        cleanupFinished();
+        cleanupFailed();
+    }
+}
+/**
+ * Delay utility.
+ *
+ * @param ms - Milliseconds to delay
+ */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Script to focus an element by selector and optional index.
+ *
+ * @returns Object with success status and element info
+ */
+const FOCUS_ELEMENT_SCRIPT = `
+(function(selector, index) {
+  const allMatches = document.querySelectorAll(selector);
+  if (allMatches.length === 0) {
+    return { success: false, error: 'No elements found matching selector: ' + selector };
+  }
+
+  let el;
+  if (typeof index === 'number' && index > 0) {
+    if (index > allMatches.length) {
+      return { 
+        success: false, 
+        error: 'Index ' + index + ' out of range (found ' + allMatches.length + ' elements)' 
+      };
+    }
+    el = allMatches[index - 1];
+  } else {
+    el = allMatches[0];
+  }
+
+  el.focus();
+  
+  return {
+    success: true,
+    selector: selector,
+    elementType: el.tagName.toLowerCase(),
+    focused: document.activeElement === el
+  };
+})`;
+/**
+ * Press a key on an element.
+ *
+ * Focuses the element first, then dispatches keyDown and keyUp events via CDP.
+ *
+ * @param cdp - CDP connection
+ * @param selector - CSS selector for the element
+ * @param keyName - Key name (e.g., "Enter", "Tab", "a")
+ * @param options - Press key options
+ * @returns Promise resolving to press key result
+ *
+ * @throws CommandError When element or key operations fail
+ *
+ * @example
+ * ```typescript
+ * // Press Enter on a todo input
+ * const result = await pressKeyElement(cdp, '.new-todo', 'Enter');
+ *
+ * // Press Tab 3 times with Shift held
+ * const result = await pressKeyElement(cdp, 'input', 'Tab', {
+ *   times: 3,
+ *   modifiers: 'shift'
+ * });
+ * ```
+ */
+export async function pressKeyElement(cdp, selector, keyName, options = {}) {
+    const keyDef = getKeyDefinition(keyName);
+    if (!keyDef) {
+        return {
+            success: false,
+            error: `Unknown key: "${keyName}". Supported keys: Enter, Tab, Escape, Space, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown, F1-F12, a-z, 0-9`,
+        };
+    }
+    const times = options.times ?? 1;
+    const modifierFlags = parseModifiers(options.modifiers);
+    const indexArg = options.index ?? 'null';
+    const focusExpression = `(${FOCUS_ELEMENT_SCRIPT})('${escapeSelectorForJS(selector)}', ${indexArg})`;
+    try {
+        const focusResponse = await cdp.send('Runtime.evaluate', {
+            expression: focusExpression,
             returnByValue: true,
         });
-        const cdpResponse = response;
-        if (cdpResponse.exceptionDetails) {
-            throw new CommandError('Script execution failed', { note: cdpResponse.exceptionDetails.text ?? 'Unknown error' }, EXIT_CODES.SOFTWARE_ERROR);
+        const focusCdpResponse = focusResponse;
+        if (focusCdpResponse.exceptionDetails) {
+            throw new CommandError(`Failed to focus element: ${focusCdpResponse.exceptionDetails.text}`, { note: `Selector: ${selector}` }, EXIT_CODES.SOFTWARE_ERROR);
         }
-        if (cdpResponse.result?.value) {
-            return cdpResponse.result.value;
+        const focusResult = focusCdpResponse.result?.value;
+        if (!focusResult?.success) {
+            return {
+                success: false,
+                error: focusResult?.error ?? 'Failed to focus element',
+                selector,
+            };
         }
-        throw new CommandError('Unexpected response format', { note: 'CDP response missing result.value' }, EXIT_CODES.SOFTWARE_ERROR);
+        for (let i = 0; i < times; i++) {
+            await dispatchKeyEvent(cdp, 'keyDown', keyDef, modifierFlags);
+            await dispatchKeyEvent(cdp, 'keyUp', keyDef, modifierFlags);
+        }
+        return {
+            success: true,
+            selector,
+            key: keyName,
+            times,
+            modifiers: modifierFlags,
+            elementType: focusResult.elementType,
+        };
     }
     catch (error) {
         if (error instanceof CommandError) {
             throw error;
         }
         const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new CommandError('Failed to get element by index', { note: errorMessage }, EXIT_CODES.SOFTWARE_ERROR);
+        throw new CommandError('Failed to press key', { note: errorMessage }, EXIT_CODES.SOFTWARE_ERROR);
     }
 }
 /**
- * Escape CSS selector for safe inclusion in JavaScript string.
- * Uses JSON.stringify to handle all special characters safely.
- *
- * @param selector - CSS selector to escape
- * @returns Escaped selector (without surrounding quotes)
+ * Dispatch a single key event via CDP Input.dispatchKeyEvent.
  *
- * @internal
- */
-function escapeSelectorForJS(selector) {
-    return JSON.stringify(selector).slice(1, -1);
-}
-/**
- * Escape value for safe inclusion in JavaScript string.
- * Uses JSON.stringify to handle all special characters safely.
- *
- * @param value - Value to escape
- * @returns Escaped value (without surrounding quotes)
- *
- * @internal
+ * @param cdp - CDP connection
+ * @param type - Event type (keyDown or keyUp)
+ * @param keyDef - Key definition with code, key, and keyCode
+ * @param modifiers - Modifier bit flags
  */
-function escapeValueForJS(value) {
-    return JSON.stringify(value).slice(1, -1);
+async function dispatchKeyEvent(cdp, type, keyDef, modifiers) {
+    await cdp.send('Input.dispatchKeyEvent', {
+        type,
+        code: keyDef.code,
+        key: keyDef.key,
+        windowsVirtualKeyCode: keyDef.keyCode,
+        nativeVirtualKeyCode: keyDef.keyCode,
+        modifiers,
+    });
 }
 //# sourceMappingURL=formFillHelpers.js.map

package/dist/commands/dom/formFillHelpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"formFillHelpers.js","sourceRoot":"","sources":["../../../src/commands/dom/formFillHelpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"formFillHelpers.js","sourceRoot":"","sources":["../../../src/commands/dom/formFillHelpers.ts"],"names":[],"mappings":"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"}

package/dist/commands/dom/formInteraction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formInteraction.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/formInteraction.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8DzC;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgItE"}
+{"version":3,"file":"formInteraction.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/formInteraction.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqEzC;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkOtE"}

package/dist/commands/dom/formInteraction.js

@@ -1,8 +1,9 @@
 /**
  * Form interaction commands for filling inputs, clicking buttons, and submitting forms.
  */
-import { fillElement, clickElement } from '../../commands/dom/formFillHelpers.js';
+import { fillElement, clickElement, pressKeyElement, waitForActionStability, } from '../../commands/dom/formFillHelpers.js';
 import { submitForm } from '../../commands/dom/formSubmitHelpers.js';
+import { resolveElementTarget } from '../../commands/dom/helpers.js';
 import { runCommand } from '../../commands/shared/CommandRunner.js';
 import { jsonOption } from '../../commands/shared/commonOptions.js';
 import { CommandError } from '../../ui/errors/index.js';
@@ -63,20 +64,30 @@ export function registerFormInteractionCommands(program) {
     }
     domCommand
         .command('fill')
-        .description('Fill a form field with a value (React-compatible)')
-        .argument('<selector>', 'CSS selector for the element')
+        .description('Fill a form field with a value (React-compatible, waits for stability)')
+        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
         .argument('<value>', 'Value to fill')
         .option('--index <n>', 'Element index if selector matches multiple (1-based)', parseInt)
         .option('--no-blur', 'Do not blur after filling (keeps focus on element)')
+        .option('--no-wait', 'Skip waiting for network stability after fill')
         .addOption(jsonOption)
-        .action(async (selector, value, options) => {
+        .action(async (selectorOrIndex, value, options) => {
         await runCommand(async () => {
+            const target = await resolveElementTarget(selectorOrIndex, options.index);
+            if (!target.success) {
+                return {
+                    success: false,
+                    error: target.error ?? 'Failed to resolve element target',
+                    exitCode: target.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
+                    suggestion: target.suggestion,
+                };
+            }
             return await withCDPConnection(async (cdp) => {
                 const fillOptions = filterDefined({
-                    index: options.index,
+                    index: target.index,
                     blur: options.blur,
                 });
-                const result = await fillElement(cdp, selector, value, fillOptions);
+                const result = await fillElement(cdp, target.selector, value, fillOptions);
                 if (!result.success) {
                     return {
                         success: false,
@@ -86,23 +97,36 @@ export function registerFormInteractionCommands(program) {
                             : EXIT_CODES.INVALID_ARGUMENTS,
                     };
                 }
+                if (options.wait !== false) {
+                    await waitForActionStability(cdp);
+                }
                 return { success: true, data: result };
             });
         }, options, formatFillOutput);
     });
     domCommand
         .command('click')
-        .description('Click an element')
-        .argument('<selector>', 'CSS selector for the element')
+        .description('Click an element and wait for stability (accepts selector or index)')
+        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
         .option('--index <n>', 'Element index if selector matches multiple (1-based)', parseInt)
+        .option('--no-wait', 'Skip waiting for network stability after click')
         .addOption(jsonOption)
-        .action(async (selector, options) => {
+        .action(async (selectorOrIndex, options) => {
         await runCommand(async () => {
+            const target = await resolveElementTarget(selectorOrIndex, options.index);
+            if (!target.success) {
+                return {
+                    success: false,
+                    error: target.error ?? 'Failed to resolve element target',
+                    exitCode: target.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
+                    suggestion: target.suggestion,
+                };
+            }
             return await withCDPConnection(async (cdp) => {
                 const clickOptions = filterDefined({
-                    index: options.index,
+                    index: target.index,
                 });
-                const result = await clickElement(cdp, selector, clickOptions);
+                const result = await clickElement(cdp, target.selector, clickOptions);
                 if (!result.success) {
                     return {
                         success: false,
@@ -112,6 +136,9 @@ export function registerFormInteractionCommands(program) {
                             : EXIT_CODES.INVALID_ARGUMENTS,
                     };
                 }
+                if (options.wait !== false) {
+                    await waitForActionStability(cdp);
+                }
                 return { success: true, data: result };
             });
         }, options, formatClickOutput);
@@ -119,22 +146,31 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('submit')
         .description('Submit a form by clicking submit button and waiting for completion')
-        .argument('<selector>', 'CSS selector for the submit button')
+        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
         .option('--index <n>', 'Element index if selector matches multiple (1-based)', parseInt)
         .option('--wait-navigation', 'Wait for page navigation after submit')
         .option('--wait-network <ms>', 'Wait for network idle after submit (milliseconds)', '1000')
         .option('--timeout <ms>', 'Maximum time to wait (milliseconds)', '10000')
         .addOption(jsonOption)
-        .action(async (selector, options) => {
+        .action(async (selectorOrIndex, options) => {
         await runCommand(async () => {
+            const target = await resolveElementTarget(selectorOrIndex, options.index);
+            if (!target.success) {
+                return {
+                    success: false,
+                    error: target.error ?? 'Failed to resolve element target',
+                    exitCode: target.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
+                    suggestion: target.suggestion,
+                };
+            }
             return await withCDPConnection(async (cdp) => {
                 const submitOptions = filterDefined({
-                    index: options.index,
+                    index: target.index,
                     waitNavigation: options.waitNavigation,
                     waitNetwork: parseInt(options.waitNetwork, 10),
                     timeout: parseInt(options.timeout, 10),
                 });
-                const result = await submitForm(cdp, selector, submitOptions);
+                const result = await submitForm(cdp, target.selector, submitOptions);
                 if (!result.success) {
                     return {
                         success: false,
@@ -150,6 +186,50 @@ export function registerFormInteractionCommands(program) {
             });
         }, options, formatSubmitOutput);
     });
+    domCommand
+        .command('pressKey')
+        .description('Press a key on an element (for Enter-to-submit, keyboard navigation)')
+        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<key>', 'Key to press (Enter, Tab, Escape, Space, ArrowUp, etc.)')
+        .option('--index <n>', 'Element index if selector matches multiple (1-based)', parseInt)
+        .option('--times <n>', 'Press key multiple times (default: 1)', parseInt)
+        .option('--modifiers <mods>', 'Modifier keys: shift,ctrl,alt,meta (comma-separated)')
+        .option('--no-wait', 'Skip waiting for network stability after key press')
+        .addOption(jsonOption)
+        .action(async (selectorOrIndex, key, options) => {
+        await runCommand(async () => {
+            const target = await resolveElementTarget(selectorOrIndex, options.index);
+            if (!target.success) {
+                return {
+                    success: false,
+                    error: target.error ?? 'Failed to resolve element target',
+                    exitCode: target.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
+                    suggestion: target.suggestion,
+                };
+            }
+            return await withCDPConnection(async (cdp) => {
+                const pressKeyOptions = filterDefined({
+                    index: target.index,
+                    times: options.times,
+                    modifiers: options.modifiers,
+                });
+                const result = await pressKeyElement(cdp, target.selector, key, pressKeyOptions);
+                if (!result.success) {
+                    return {
+                        success: false,
+                        error: result.error ?? 'Failed to press key',
+                        exitCode: result.error?.includes('not found')
+                            ? EXIT_CODES.RESOURCE_NOT_FOUND
+                            : EXIT_CODES.INVALID_ARGUMENTS,
+                    };
+                }
+                if (options.wait !== false) {
+                    await waitForActionStability(cdp);
+                }
+                return { success: true, data: result };
+            });
+        }, options, formatPressKeyOutput);
+    });
 }
 /**
  * Format fill command output for human-readable display.
@@ -231,4 +311,37 @@ function formatSubmitOutput(result) {
     ]);
     return fmt.build();
 }
+/**
+ * Format pressKey command output for human-readable display.
+ *
+ * @param result - Press key result
+ * @returns Formatted string
+ */
+function formatPressKeyOutput(result) {
+    const fmt = new OutputFormatter();
+    fmt.text('✓ Key Pressed');
+    fmt.blank();
+    const details = [
+        ['Key', result.key ?? 'unknown'],
+        ['Selector', result.selector ?? 'unknown'],
+        ['Element Type', result.elementType ?? 'unknown'],
+    ];
+    if (result.times && result.times > 1) {
+        details.push(['Times', result.times.toString()]);
+    }
+    if (result.modifiers && result.modifiers > 0) {
+        const mods = [];
+        if (result.modifiers & 1)
+            mods.push('Shift');
+        if (result.modifiers & 2)
+            mods.push('Ctrl');
+        if (result.modifiers & 4)
+            mods.push('Alt');
+        if (result.modifiers & 8)
+            mods.push('Meta');
+        details.push(['Modifiers', mods.join('+')]);
+    }
+    fmt.keyValueList(details, 15);
+    return fmt.build();
+}
 //# sourceMappingURL=formInteraction.js.map