browser-debugger-cli 0.6.5 → 0.6.7

package/dist/commands/dom/a11y.js

@@ -8,11 +8,13 @@
  *
  * Uses IPC/callCDP pattern for consistency with other DOM commands.
  */
+import { DomElementResolver } from '../../commands/dom/DomElementResolver.js';
+import { getDomContext } from '../../commands/dom/helpers.js';
 import { runCommand } from '../../commands/shared/CommandRunner.js';
 import { jsonOption } from '../../commands/shared/commonOptions.js';
 import { collectA11yTree, queryA11yTree, parseQueryPattern, resolveA11yNode, } from '../../telemetry/a11y.js';
 import { CommandError } from '../../ui/errors/index.js';
-import { formatA11yTree, formatA11yQueryResult, formatA11yNode } from '../../ui/formatters/a11y.js';
+import { formatA11yTree, formatA11yQueryResult, formatA11yNodeWithContext, } from '../../ui/formatters/a11y.js';
 import { elementNotFoundError } from '../../ui/messages/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /**
@@ -72,38 +74,13 @@ async function handleA11yQuery(pattern, options) {
         return { success: true, data: result };
     }, options, formatA11yQueryResult);
 }
-/**
- * Retrieve cached node by index with validation.
- *
- * @param index - Zero-based index from query results
- * @returns Node from cache
- * @throws CommandError if cache missing, index out of range, or node not found
- */
-async function getCachedNodeByIndex(index) {
-    const { getSessionQueryCache } = await import('../../session/queryCache.js');
-    const cachedQuery = getSessionQueryCache();
-    if (!cachedQuery) {
-        throw new CommandError('No cached query results found', {
-            suggestion: 'Run "bdg dom query <selector>" first to generate indexed results',
-        }, EXIT_CODES.INVALID_ARGUMENTS);
-    }
-    if (index < 0 || index >= cachedQuery.nodes.length) {
-        throw new CommandError(`Index ${index} out of range (found ${cachedQuery.nodes.length} elements)`, {
-            suggestion: `Use an index between 0 and ${cachedQuery.nodes.length - 1}`,
-        }, EXIT_CODES.INVALID_ARGUMENTS);
-    }
-    const targetNode = cachedQuery.nodes[index];
-    if (!targetNode) {
-        throw new CommandError(`Element at index ${index} not found`, {}, EXIT_CODES.RESOURCE_NOT_FOUND);
-    }
-    return targetNode;
-}
 /**
  * Handle bdg dom a11y describe <selectorOrIndex> command
  *
  * Gets accessibility properties for a DOM element by CSS selector or numeric index.
  * Supports index-based access from query results (e.g., "bdg dom a11y describe 0").
  * Useful for understanding how an element is exposed to assistive technologies.
+ * Includes DOM context (tag, classes, text preview) when a11y data is sparse.
  *
  * @param selectorOrIndex - CSS selector (e.g., "button.submit") or numeric index from query results
  * @param options - Command options
@@ -117,13 +94,16 @@ async function getCachedNodeByIndex(index) {
  * ```
  */
 async function handleA11yDescribe(selectorOrIndex, options) {
-    const isNumericIndex = /^\d+$/.test(selectorOrIndex);
+    const resolver = DomElementResolver.getInstance();
+    const isNumericIndex = resolver.isNumericIndex(selectorOrIndex);
     await runCommand(async () => {
         let node;
+        let nodeId;
         if (isNumericIndex) {
             const index = parseInt(selectorOrIndex, 10);
-            const targetNode = await getCachedNodeByIndex(index);
-            node = await resolveA11yNode('', targetNode.nodeId);
+            const targetNode = await resolver.getNodeIdForIndex(index);
+            nodeId = targetNode.nodeId;
+            node = await resolveA11yNode('', nodeId);
         }
         else {
             node = await resolveA11yNode(selectorOrIndex);
@@ -131,8 +111,13 @@ async function handleA11yDescribe(selectorOrIndex, options) {
         if (!node) {
             throw new CommandError(elementNotFoundError(selectorOrIndex), {}, EXIT_CODES.RESOURCE_NOT_FOUND);
         }
-        return { success: true, data: node };
-    }, options, formatA11yNode);
+        let domContext = null;
+        const domNodeId = node.backendDOMNodeId ?? nodeId;
+        if (domNodeId) {
+            domContext = await getDomContext(domNodeId);
+        }
+        return { success: true, data: { node, domContext } };
+    }, options, formatA11yNodeWithContext);
 }
 /**
  * Register accessibility commands under 'bdg dom a11y'
@@ -142,7 +127,26 @@ async function handleA11yDescribe(selectorOrIndex, options) {
 export function registerA11yCommands(domCmd) {
     const a11y = domCmd
         .command('a11y')
-        .description('Accessibility tree inspection and semantic queries');
+        .description('Accessibility tree inspection and semantic queries')
+        .argument('[search]', 'Quick search: index (describe), pattern with ":" (query), or name search')
+        .addOption(jsonOption)
+        .action(async (search, options) => {
+        if (!search) {
+            a11y.help();
+            return;
+        }
+        const isNumericIndex = /^\d+$/.test(search);
+        const isPatternQuery = search.includes(':') || search.includes('=');
+        if (isNumericIndex) {
+            await handleA11yDescribe(search, options);
+        }
+        else if (isPatternQuery) {
+            await handleA11yQuery(search, options);
+        }
+        else {
+            await handleA11yQuery(`name:*${search}*`, options);
+        }
+    });
     a11y
         .command('tree')
         .description('Dump full accessibility tree (filters ignored nodes)')

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"evalHelpers.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/evalHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAuDlF;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAU9C;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,eAAe,CAY7D;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB/F;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAyB5C"}
+{"version":3,"file":"evalHelpers.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/evalHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAuDlF;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAU9C;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,eAAe,CAY7D;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB/F;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,gBAAgB,CAAC,CA6B5C"}

package/dist/commands/dom/evalHelpers.js

@@ -111,7 +111,7 @@ export async function executeScript(cdp, script) {
     }
     if (response.exceptionDetails) {
         const errorMsg = response.exceptionDetails.exception?.description ?? 'Unknown error executing script';
-        throw new Error(errorMsg);
+        throw new CommandError(errorMsg, { note: 'Script execution failed in browser context' }, EXIT_CODES.SOFTWARE_ERROR);
     }
     return response;
 }

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

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

package/dist/commands/dom/formFillHelpers.d.ts

@@ -9,7 +9,7 @@ import { type FillOptions, type FillResult, type ClickResult } from './reactEven
  * @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
@@ -28,7 +28,7 @@ export declare function fillElement(cdp: CDPConnection, selector: string, value:
  *
  * @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
@@ -44,4 +44,70 @@ export declare function fillElement(cdp: CDPConnection, selector: string, value:
 export declare function clickElement(cdp: CDPConnection, selector: string, options?: {
     index?: number;
 }): Promise<ClickResult>;
+/**
+ * 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 declare function waitForActionStability(cdp: CDPConnection): Promise<void>;
+/**
+ * Options for pressing a key on an element.
+ */
+export interface PressKeyOptions {
+    /** Element index if selector matches multiple (1-based) */
+    index?: number;
+    /** Number of times to press the key (default: 1) */
+    times?: number;
+    /** Comma-separated modifier keys (shift, ctrl, alt, meta) */
+    modifiers?: string;
+}
+/**
+ * Result of pressing a key.
+ */
+export interface PressKeyResult {
+    success: boolean;
+    error?: string;
+    selector?: string;
+    key?: string;
+    times?: number;
+    modifiers?: number;
+    elementType?: string | undefined;
+}
+/**
+ * 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 declare function pressKeyElement(cdp: CDPConnection, selector: string, keyName: string, options?: PressKeyOptions): Promise<PressKeyResult>;
 //# sourceMappingURL=formFillHelpers.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"formFillHelpers.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/formFillHelpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKzD,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,WAAW,EAEjB,MAAM,wBAAwB,CAAC;AAqChC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CA6DrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,WAAW,CAAC,CAyDtB"}
+{"version":3,"file":"formFillHelpers.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/formFillHelpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOzD,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,wBAAwB,CAAC;AA8ChC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CAiDrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,WAAW,CAAC,CA6CtB;AA8BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA2C9E;AAWD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAuEzB"}

package/dist/commands/dom/formFillHelpers.js

@@ -2,8 +2,17 @@
  * 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, isFillResult, isClickResult, } 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.
  *
@@ -36,7 +45,7 @@ function formatScriptExecutionError(exceptionDetails, selector, operationType =
  * @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
@@ -50,33 +59,26 @@ function formatScriptExecutionError(exceptionDetails, selector, operationType =
  * ```
  */
 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,
             returnByValue: true,
-            userGesture: true, // Treat as user-initiated action
+            userGesture: true,
         });
         const cdpResponse = response;
         if (cdpResponse.exceptionDetails) {
             const errorMessage = formatScriptExecutionError(cdpResponse.exceptionDetails, selector, 'fill');
             throw new CommandError(errorMessage, {}, EXIT_CODES.SOFTWARE_ERROR);
         }
-        if (cdpResponse.result?.value) {
+        if (cdpResponse.result?.value && isFillResult(cdpResponse.result.value)) {
             return cdpResponse.result.value;
         }
-        throw new CommandError('Unexpected response format', { note: 'CDP response missing result.value' }, EXIT_CODES.SOFTWARE_ERROR);
+        throw new CommandError('Unexpected response format', { note: 'CDP response missing result.value or invalid FillResult structure' }, EXIT_CODES.SOFTWARE_ERROR);
     }
     catch (error) {
         if (error instanceof CommandError) {
@@ -91,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
@@ -105,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,
@@ -125,13 +117,13 @@ export async function clickElement(cdp, selector, options = {}) {
         });
         const cdpResponse = response;
         if (cdpResponse.exceptionDetails) {
-            const errorMessage = formatScriptExecutionError(cdpResponse.exceptionDetails, selector);
+            const errorMessage = formatScriptExecutionError(cdpResponse.exceptionDetails, selector, 'click');
             throw new CommandError(errorMessage, {}, EXIT_CODES.SOFTWARE_ERROR);
         }
-        if (cdpResponse.result?.value) {
+        if (cdpResponse.result?.value && isClickResult(cdpResponse.result.value)) {
             return cdpResponse.result.value;
         }
-        throw new CommandError('Unexpected response format', { note: 'CDP response missing result.value' }, EXIT_CODES.SOFTWARE_ERROR);
+        throw new CommandError('Unexpected response format', { note: 'CDP response missing result.value or invalid ClickResult structure' }, EXIT_CODES.SOFTWARE_ERROR);
     }
     catch (error) {
         if (error instanceof CommandError) {
@@ -142,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 onRequestStarted = () => {
+        activeRequests++;
+        lastActivity = Date.now();
+    };
+    const onRequestFinished = () => {
+        activeRequests--;
+        if (activeRequests === 0) {
+            lastActivity = Date.now();
+        }
+    };
+    await cdp.send('Network.enable');
+    const cleanupRequest = cdp.on('Network.requestWillBeSent', onRequestStarted);
+    const cleanupFinished = cdp.on('Network.loadingFinished', onRequestFinished);
+    const cleanupFailed = cdp.on('Network.loadingFailed', onRequestFinished);
     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.
+ * Dispatch a single key event via CDP Input.dispatchKeyEvent.
  *
- * @param selector - CSS selector to escape
- * @returns Escaped selector (without surrounding quotes)
- *
- * @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