browser-debugger-cli 0.7.2 → 0.9.0

package/dist/commands/dom/DomElementResolver.js

@@ -1,41 +1,31 @@
 /**
  * DOM element resolver for index and selector-based access.
  *
- * Provides centralized resolution of DOM elements from:
- * - Numeric indices (referencing cached query results)
- * - CSS selectors (used directly)
- *
- * Handles cache validation, staleness detection, and automatic refresh.
- * When cache is stale due to navigation, automatically re-runs the original
- * query to provide seamless "just works" experience.
+ * A numeric argument is an index into the last `bdg dom query` / `bdg dom form`
+ * result and resolves to that exact element (its backend node id). Whether the
+ * element still exists is checked where it is used: if the page navigated or
+ * the element was removed, commands fail with exit 87 instead of acting on a
+ * different element that happens to match the selector now.
  *
  * @example
  * ```typescript
  * const resolver = DomElementResolver.getInstance();
  *
- * // Resolve index from cached query
- * const target = await resolver.resolve('0');
- * // { success: true, selector: '.cached-selector', index: 1 }
+ * const target = await resolver.resolve('0', undefined, 'click');
+ * // { success: true, selector: '.cached-selector', backendNodeId: 42 }
  *
- * // Resolve CSS selector directly
- * const target = await resolver.resolve('button.submit');
+ * const target = await resolver.resolve('button.submit', undefined, 'click');
  * // { success: true, selector: 'button.submit' }
- *
- * // Get nodeId for cached index (throws if invalid)
- * const nodeId = await resolver.getNodeIdForIndex(0);
  * ```
  */
-import { QueryCacheManager } from '../../session/QueryCacheManager.js';
-import { CommandError } from '../../ui/errors/index.js';
-import { createLogger } from '../../ui/logging/index.js';
-import { elementAtIndexNotFoundError, indexOutOfRangeError } from '../../ui/messages/errors.js';
+import { noActiveSessionError } from '../shared/CommandRunner.js';
+import { CommandError } from '../../errors/index.js';
+import { cachedIndexOutOfRangeError, indexWithIndexOptionError, staleNodeError, } from '../../errors/messages.js';
+import { QueryCacheManager, indexSourceOf, } from '../../session/QueryCacheManager.js';
+import { isDaemonAlive } from '../../session/daemonSocket.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
-const log = createLogger('dom');
 /**
  * Singleton resolver for DOM element access patterns.
- *
- * Centralizes element resolution with cache validation, automatic refresh,
- * and consistent error handling.
  */
 export class DomElementResolver {
     static instance = null;
@@ -48,28 +38,6 @@ export class DomElementResolver {
     constructor(cacheManager) {
         this.cacheManager = cacheManager ?? QueryCacheManager.getInstance();
     }
-    /**
-     * Refresh stale cache by re-running the original query.
-     *
-     * Called automatically when cache validation fails due to navigation.
-     * Re-queries using the stored selector and updates the cache with fresh results.
-     *
-     * @param selector - Original CSS selector from stale cache
-     * @returns Fresh query result
-     */
-    async refreshCache(selector) {
-        log.debug(`Cache stale, auto-refreshing query "${selector}"`);
-        const { queryDOMElements } = await import('../../commands/dom/helpers.js');
-        const result = await queryDOMElements(selector);
-        const navigationId = await this.cacheManager.getCurrentNavigationId();
-        const resultWithNavId = {
-            ...result,
-            ...(navigationId !== null && { navigationId }),
-        };
-        await this.cacheManager.set(resultWithNavId);
-        this.cacheManager.invalidateNavigationCache();
-        log.debug(`Cache refreshed: found ${result.count} elements`);
-    }
     /**
      * Get the singleton instance.
      *
@@ -88,146 +56,71 @@ export class DomElementResolver {
     /**
      * Resolve a selectorOrIndex argument to an element target.
      *
-     * Handles the common pattern of accepting either:
-     * - A CSS selector string (used directly)
-     * - A numeric index (resolved from cached query results)
-     *
-     * Automatically refreshes stale cache by re-running the original query.
-     * This provides a "just works" experience where navigation doesn't break
-     * index-based access.
-     *
      * @param selectorOrIndex - CSS selector or numeric index from query results
-     * @param explicitIndex - Optional explicit --index flag value (0-based)
-     * @returns Resolution result with selector and optional index
-     *
-     * @example
-     * ```typescript
-     * const target = await resolver.resolve('button');
-     * // { success: true, selector: 'button' }
-     *
-     * const target = await resolver.resolve('0');
-     * // { success: true, selector: '.cached-selector', index: 1 }
-     * ```
+     * @param explicitIndex - Optional explicit --index flag value (0-based, selectors only)
+     * @param command - `bdg dom` subcommand being run, e.g. "click" (for suggestions)
+     * @returns Resolution result
      */
-    async resolve(selectorOrIndex, explicitIndex) {
-        const isNumericIndex = /^\d+$/.test(selectorOrIndex);
-        if (isNumericIndex) {
-            let validation = await this.cacheManager.validate();
-            // Auto-refresh: if cache is stale but has selector, re-run query
-            if (!validation.valid && validation.cache?.selector) {
-                await this.refreshCache(validation.cache.selector);
-                validation = await this.cacheManager.validate();
-            }
-            if (!validation.valid || !validation.cache) {
-                return {
-                    success: false,
-                    error: validation.error ?? 'No cached query results found',
-                    exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-                    suggestion: validation.suggestion,
-                };
-            }
-            const cachedQuery = validation.cache;
-            const index = parseInt(selectorOrIndex, 10);
-            // Find node by index property (supports non-sequential indices from form discovery)
-            const targetNode = cachedQuery.nodes.find((n) => n.index === index);
-            if (!targetNode) {
-                // Fall back to array-position lookup for sequential indices (standard queries)
-                if (index >= 0 && index < cachedQuery.nodes.length) {
-                    const nodeByPosition = cachedQuery.nodes[index];
-                    if (nodeByPosition) {
-                        const fallbackSelector = nodeByPosition.preview ?? cachedQuery.selector;
-                        const fallbackIndex = nodeByPosition.preview ? undefined : index + 1;
-                        return {
-                            success: true,
-                            selector: fallbackSelector,
-                            index: fallbackIndex,
-                        };
-                    }
-                }
-                const validIndices = cachedQuery.nodes.map((n) => n.index).sort((a, b) => a - b);
+    async resolve(selectorOrIndex, explicitIndex, command) {
+        if (!this.isNumericIndex(selectorOrIndex)) {
+            return { success: true, selector: selectorOrIndex, index: explicitIndex };
+        }
+        if (explicitIndex !== undefined) {
+            const err = indexWithIndexOptionError(selectorOrIndex, command);
+            return {
+                success: false,
+                error: err.message,
+                exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+                suggestion: err.suggestion,
+            };
+        }
+        try {
+            const { node, selector, source } = await this.lookup(parseInt(selectorOrIndex, 10));
+            if (node.nodeId <= 0) {
+                const err = staleNodeError(source.index, source);
                 return {
                     success: false,
-                    error: `Index ${index} not found in cached results (query "${cachedQuery.selector}")`,
+                    error: err.message,
                     exitCode: EXIT_CODES.STALE_CACHE,
-                    suggestion: validIndices.length === 0
-                        ? `No elements found. The selector "${cachedQuery.selector}" may no longer match any elements.`
-                        : `Valid indices: ${validIndices.join(', ')}`,
+                    suggestion: err.suggestion,
                 };
             }
-            // Use node's preview selector if available (from form discovery), otherwise original selector
-            const resolvedSelector = targetNode.preview ?? cachedQuery.selector;
-            // If using preview selector (unique element), don't pass index
-            // Index is only needed when original selector matches multiple elements
-            const resolvedIndex = targetNode.preview ? undefined : index + 1;
             return {
                 success: true,
-                selector: resolvedSelector,
-                index: resolvedIndex,
+                selector: node.selector ?? selector,
+                backendNodeId: node.nodeId,
+                source,
+                preview: cachedNodePreview(node),
+            };
+        }
+        catch (error) {
+            if (!(error instanceof CommandError))
+                throw error;
+            return {
+                success: false,
+                error: error.message,
+                exitCode: error.exitCode,
+                suggestion: error.metadata.suggestion,
             };
         }
-        return {
-            success: true,
-            selector: selectorOrIndex,
-            index: explicitIndex,
-        };
     }
     /**
-     * Get nodeId for a cached index.
-     *
-     * Automatically refreshes stale cache by re-running the original query.
-     * Throws CommandError only if refresh fails or index is out of range after refresh.
+     * Get the backend node id for a cached index, checking the element still exists.
      *
      * @param index - Zero-based index from query results
-     * @returns Node with nodeId from cache
-     * @throws CommandError if cache missing, index out of range after refresh, or node not found
-     *
-     * @example
-     * ```typescript
-     * const node = await resolver.getNodeIdForIndex(0);
-     * console.log(node.nodeId); // CDP node ID
-     * ```
+     * @returns Cached node; `nodeId` is its backend node id
+     * @throws CommandError if there is no usable cache, the index is out of range,
+     *   or the element is no longer in the page (87)
      */
     async getNodeIdForIndex(index) {
-        let validation = await this.cacheManager.validate();
-        // Auto-refresh: if cache is stale but has selector, re-run query
-        if (!validation.valid && validation.cache?.selector) {
-            await this.refreshCache(validation.cache.selector);
-            validation = await this.cacheManager.validate();
-        }
-        if (!validation.valid || !validation.cache) {
-            throw new CommandError(validation.error ?? 'No cached query results found', validation.suggestion ? { suggestion: validation.suggestion } : {}, EXIT_CODES.INVALID_ARGUMENTS);
-        }
-        const cachedQuery = validation.cache;
-        if (index < 0 || index >= cachedQuery.nodes.length) {
-            const err = indexOutOfRangeError(index, cachedQuery.nodes.length - 1);
+        const { node, source } = await this.lookup(index);
+        if (node.nodeId <= 0) {
+            const err = staleNodeError(index, source);
             throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
         }
-        const targetNode = cachedQuery.nodes[index];
-        if (!targetNode) {
-            const err = elementAtIndexNotFoundError(index, cachedQuery.selector);
-            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
-        }
-        return targetNode;
-    }
-    /**
-     * Get the count of cached elements.
-     *
-     * Automatically refreshes stale cache by re-running the original query.
-     *
-     * @returns Number of cached elements
-     * @throws CommandError if cache is missing or refresh fails
-     */
-    async getElementCount() {
-        let validation = await this.cacheManager.validate();
-        // Auto-refresh: if cache is stale but has selector, re-run query
-        if (!validation.valid && validation.cache?.selector) {
-            await this.refreshCache(validation.cache.selector);
-            validation = await this.cacheManager.validate();
-        }
-        if (!validation.valid || !validation.cache) {
-            throw new CommandError(validation.error ?? 'No cached query results found', validation.suggestion ? { suggestion: validation.suggestion } : {}, EXIT_CODES.INVALID_ARGUMENTS);
-        }
-        return validation.cache.nodes.length;
+        const { assertNodeAttached } = await import('./helpers/index.js');
+        await assertNodeAttached(node.nodeId, source);
+        return { nodeId: node.nodeId, source };
     }
     /**
      * Check if the argument is a numeric index.
@@ -238,5 +131,39 @@ export class DomElementResolver {
     isNumericIndex(selectorOrIndex) {
         return /^\d+$/.test(selectorOrIndex);
     }
+    /**
+     * Find a cached node by index.
+     *
+     * @param index - Zero-based index
+     * @returns Cached node and the query's selector
+     * @throws CommandError (83) without a session, (81) without a usable cache, (87) for an index outside the cached results
+     */
+    async lookup(index) {
+        const validation = await this.cacheManager.validate();
+        if (!validation.valid || !validation.cache) {
+            if (!(await isDaemonAlive()))
+                throw noActiveSessionError();
+            throw new CommandError(validation.error ?? 'No cached query results found', validation.suggestion ? { suggestion: validation.suggestion } : {}, EXIT_CODES.INVALID_ARGUMENTS);
+        }
+        const { nodes, selector } = validation.cache;
+        const source = indexSourceOf(index, selector);
+        const node = nodes.find((n) => n.index === index);
+        if (!node) {
+            const err = cachedIndexOutOfRangeError(source, nodes.length);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
+        }
+        return { node, selector, source };
+    }
+}
+/**
+ * What a cached element was when it was listed.
+ *
+ * @param node - Cached node
+ * @returns e.g. `h3 "Welcome"`, `button`; undefined without a tag
+ */
+function cachedNodePreview(node) {
+    if (!node.tag)
+        return undefined;
+    return node.preview ? `${node.tag} "${node.preview}"` : node.tag;
 }
 //# sourceMappingURL=DomElementResolver.js.map

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

@@ -9,6 +9,16 @@
  * Uses IPC/callCDP pattern for consistency with other DOM commands.
  */
 import type { Command } from 'commander';
+import type { A11yQueryResult } from '../../types.js';
+/**
+ * The matches to list: the first `limit` (all with 0), counting the rest as
+ * omitted. All of them are cached, so their indices work either way.
+ *
+ * @param result - Query result
+ * @param limit - Matches to list (0 = all)
+ * @returns The result with the listed matches
+ */
+export declare function limitMatches(result: A11yQueryResult, limit: number): A11yQueryResult;
 /**
  * Register accessibility commands under 'bdg dom a11y'
  *

package/dist/commands/dom/a11y.js

@@ -8,15 +8,19 @@
  *
  * 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, runJsonCommand } 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 { DomElementResolver } from './DomElementResolver.js';
+import { getDomContext, resolveBackendNodeIds } from './helpers/index.js';
+import { runCommand, runJsonCommand } from '../shared/CommandRunner.js';
+import { jsonOption } from '../shared/commonOptions.js';
+import { integerOption } from '../shared/validation.js';
+import { CommandError } from '../../errors/index.js';
+import { elementNotFoundError, invalidQueryPatternError, noA11yNodesFoundError, notInAccessibilityTreeError, } from '../../errors/messages.js';
+import { A11Y_CACHE_SELECTOR_PREFIX, QueryCacheManager } from '../../session/QueryCacheManager.js';
+import { a11yIgnoredReasons, collectA11yTree, queryA11yTree, parseQueryPattern, resolveA11yNode, } from '../../telemetry/a11y.js';
 import { formatA11yTree, formatA11yQueryResult, formatA11yNodeWithContext, } from '../../ui/formatters/a11y.js';
-import { elementNotFoundError, invalidQueryPatternError, noA11yNodesFoundError, elementNotAccessibleError, } from '../../ui/messages/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+/** Matches `dom a11y query` lists by default in human output (a page can have hundreds of links; JSON lists all) */
+const A11Y_QUERY_LIMIT = 50;
 /**
  * Handle bdg dom a11y tree command
  *
@@ -40,14 +44,28 @@ async function handleA11yTree(options) {
             };
         });
     }
-    const tree = await collectA11yTree();
-    await runCommand(() => Promise.resolve({ success: true, data: tree }), options, formatA11yTree);
+    await runCommand(async () => ({ success: true, data: await collectA11yTree() }), options, formatA11yTree);
+}
+/**
+ * Quote a search text for a query pattern, keeping the quotes it contains
+ * (`Say "hi"` is searched as is).
+ *
+ * @param text - Accessible name to search for
+ * @returns Quoted value (unquoted only if it contains both kinds of quotes)
+ */
+function quoteQueryValue(text) {
+    if (!text.includes('"'))
+        return `"${text}"`;
+    if (!text.includes("'"))
+        return `'${text}'`;
+    return text;
 }
 /**
  * Handle bdg dom a11y query <pattern> command
  *
  * Queries the accessibility tree using role/name/description patterns via IPC.
- * Pattern format: "role:button name:Submit" (space-separated key:value pairs)
+ * Pattern format: "role:button name:Submit" (key:value or key=value pairs; a
+ * name or description may contain spaces and colons)
  *
  * @param pattern - Query pattern string
  * @param options - Command options
@@ -72,9 +90,36 @@ async function handleA11yQuery(pattern, options) {
             const err = noA11yNodesFoundError(pattern);
             throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
         }
-        return { success: true, data: result };
+        const indexed = { ...result, nodes: result.nodes.map((node, index) => ({ ...node, index })) };
+        await QueryCacheManager.getInstance().set({
+            selector: `${A11Y_CACHE_SELECTOR_PREFIX}${pattern}`,
+            count: indexed.count,
+            nodes: indexed.nodes.map((node) => ({
+                index: node.index,
+                nodeId: node.backendDOMNodeId ?? 0,
+                tag: node.role,
+                ...(node.name && { preview: node.name }),
+            })),
+        });
+        return {
+            success: true,
+            data: limitMatches(indexed, options.limit ?? (options.json ? 0 : A11Y_QUERY_LIMIT)),
+        };
     }, options, formatA11yQueryResult);
 }
+/**
+ * The matches to list: the first `limit` (all with 0), counting the rest as
+ * omitted. All of them are cached, so their indices work either way.
+ *
+ * @param result - Query result
+ * @param limit - Matches to list (0 = all)
+ * @returns The result with the listed matches
+ */
+export function limitMatches(result, limit) {
+    if (limit === 0 || result.nodes.length <= limit)
+        return result;
+    return { ...result, nodes: result.nodes.slice(0, limit), omitted: result.nodes.length - limit };
+}
 /**
  * Handle bdg dom a11y describe <selectorOrIndex> command
  *
@@ -101,28 +146,23 @@ async function handleA11yDescribe(selectorOrIndex, options) {
      * Fetch a11y node data for a given selector or index.
      */
     async function fetchA11yNodeData() {
-        let node;
-        let nodeId;
-        if (isNumericIndex) {
-            const index = parseInt(selectorOrIndex, 10);
-            const targetNode = await resolver.getNodeIdForIndex(index);
-            nodeId = targetNode.nodeId;
-            node = await resolveA11yNode('', nodeId);
-        }
-        else {
-            node = await resolveA11yNode(selectorOrIndex);
+        const backendNodeId = isNumericIndex
+            ? (await resolver.getNodeIdForIndex(parseInt(selectorOrIndex, 10))).nodeId
+            : (await resolveBackendNodeIds([selectorOrIndex]))[0];
+        if (backendNodeId === undefined) {
+            const err = elementNotFoundError(selectorOrIndex);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
         }
+        const node = await resolveA11yNode({ backendNodeId });
         if (!node) {
-            if (isNumericIndex) {
-                const err = elementNotAccessibleError(parseInt(selectorOrIndex, 10));
-                throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
-            }
-            throw new CommandError(elementNotFoundError(selectorOrIndex), {}, EXIT_CODES.RESOURCE_NOT_FOUND);
+            const reasons = await a11yIgnoredReasons({ backendNodeId });
+            const err = notInAccessibilityTreeError(selectorOrIndex, reasons);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
         }
         let domContext = null;
-        const domNodeId = node.backendDOMNodeId ?? nodeId;
+        const domNodeId = node.backendDOMNodeId ?? backendNodeId;
         if (domNodeId) {
-            domContext = await getDomContext(domNodeId);
+            domContext = await getDomContext({ backendNodeId: domNodeId });
         }
         return { node, domContext };
     }
@@ -145,14 +185,14 @@ export function registerA11yCommands(domCmd) {
         .description('Accessibility tree inspection and semantic queries')
         .argument('[search]', 'Quick search: index (describe), CSS selector (#id, .class), pattern with ":" (query), or name search')
         .enablePositionalOptions()
+        .addOption(jsonOption())
         .action(async (search, options) => {
         if (!search) {
-            a11y.help();
-            return;
+            return a11y.help({ error: true });
         }
         const isNumericIndex = /^\d+$/.test(search);
-        const isCssSelector = /^[#.[]/u.test(search) || search.includes(' ');
-        const isPatternQuery = search.includes(':') || search.includes('=');
+        const isCssSelector = /^[#.[]/u.test(search);
+        const isPatternQuery = /^(role|name|description|desc)\s*[:=]/i.test(search);
         if (isNumericIndex || isCssSelector) {
             await handleA11yDescribe(search, options);
         }
@@ -160,7 +200,7 @@ export function registerA11yCommands(domCmd) {
             await handleA11yQuery(search, options);
         }
         else {
-            await handleA11yQuery(`name:*${search}*`, options);
+            await handleA11yQuery(`name:${quoteQueryValue(search)}`, options);
         }
     });
     a11y
@@ -173,7 +213,8 @@ export function registerA11yCommands(domCmd) {
     a11y
         .command('query')
         .description('Query elements by accessibility properties (e.g., "role:button", "name:Submit")')
-        .argument('<pattern>', 'Pattern with field prefix - role:button, name:Submit, name:*search* (supports wildcards)')
+        .argument('<pattern>', "Fields role, name, description as key:value or key=value, separated by spaces or commas; * is a wildcard. A name or description runs to the next field or the end, so it may contain spaces and colons; quote the whole pattern (e.g. 'role=button name=Sign in', 'name=E-mail address:')")
+        .option('--limit <n>', `Matches to list (default: ${A11Y_QUERY_LIMIT}, all with --json; 0 = all); all are indexed`, integerOption(0))
         .addOption(jsonOption())
         .action(async (pattern, options) => {
         await handleA11yQuery(pattern, options);

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

@@ -0,0 +1,15 @@
+/**
+ * `bdg dom eval` — evaluate a JavaScript expression in the page context, or
+ * in one of its iframes with `--frame`.
+ *
+ * CLI-side handler. Actual evaluation happens in the daemon via the
+ * `dom_eval` IPC command so the session's persistent CDP connection is reused.
+ */
+import type { DomEvalCommandOptions } from '../shared/optionTypes.js';
+/**
+ * Handle `bdg dom eval <script> [--frame <frame>]`. With `--frame`, the
+ * frame the script ran in is a `Frame:` line on stderr (JSON: `frame`), so
+ * stdout stays the bare value for pipes.
+ */
+export declare function handleDomEval(script: string, options: DomEvalCommandOptions): Promise<void>;
+//# sourceMappingURL=eval.d.ts.map

package/dist/commands/dom/eval.js

@@ -0,0 +1,68 @@
+/**
+ * `bdg dom eval` — evaluate a JavaScript expression in the page context, or
+ * in one of its iframes with `--frame`.
+ *
+ * CLI-side handler. Actual evaluation happens in the daemon via the
+ * `dom_eval` IPC command so the session's persistent CDP connection is reused.
+ */
+import { documentReadyState } from './helpers/query.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { emptyScriptError, withLoadingHint } from '../../errors/messages.js';
+import { domEval } from '../../ipc/client.js';
+import { formatDomEval } from '../../ui/formatters/dom.js';
+import { evalFrameLine } from '../../ui/messages/commands.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * Handle `bdg dom eval <script> [--frame <frame>]`. With `--frame`, the
+ * frame the script ran in is a `Frame:` line on stderr (JSON: `frame`), so
+ * stdout stays the bare value for pipes.
+ */
+export async function handleDomEval(script, options) {
+    await runCommand(async () => {
+        if (!script.trim()) {
+            const err = emptyScriptError();
+            return {
+                success: false,
+                error: err.message,
+                exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+                errorContext: { suggestion: err.suggestion },
+            };
+        }
+        const response = await domEval(script, options.frame);
+        if (response.status === 'error' || !response.data) {
+            const suggestion = await frameErrorSuggestion(response, options.frame);
+            return {
+                success: false,
+                error: response.error ?? 'Failed to evaluate script',
+                exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
+                ...(suggestion && { errorContext: { suggestion } }),
+            };
+        }
+        const { value, type, subtype, frame } = response.data;
+        return {
+            success: true,
+            data: {
+                result: value,
+                type,
+                ...(subtype && { subtype }),
+                ...(frame !== undefined && { frame }),
+            },
+            ...(frame !== undefined && !options.json && { hint: evalFrameLine(frame) }),
+        };
+    }, options, formatDomEval);
+}
+/**
+ * Suggestion of a failed eval; a frame not found (83) while the page is
+ * still loading says so (its iframes may not exist yet).
+ *
+ * @param response - Error response
+ * @param frame - The --frame given, if any
+ * @returns Suggestion, if any
+ */
+async function frameErrorSuggestion(response, frame) {
+    if (frame === undefined || response.exitCode !== EXIT_CODES.RESOURCE_NOT_FOUND) {
+        return response.suggestion;
+    }
+    return withLoadingHint(response.suggestion ?? '', await documentReadyState()) || undefined;
+}
+//# sourceMappingURL=eval.js.map