browser-debugger-cli 0.7.1 → 0.8.0

package/dist/commands/details.js

@@ -1,5 +1,5 @@
-import { runCommand } from '../commands/shared/CommandRunner.js';
-import { jsonOption } from '../commands/shared/commonOptions.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
 import { getDetails } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
 import { formatNetworkDetails, formatConsoleDetails } from '../ui/formatters/details.js';
@@ -46,6 +46,16 @@ export function registerDetailsCommand(program) {
                     },
                 };
             }
+            if (!opts.id.trim()) {
+                return {
+                    success: false,
+                    error: `The ${opts.type === 'network' ? 'request id' : 'message index'} is empty`,
+                    exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+                    errorContext: {
+                        suggestion: 'Usage: bdg details network <requestId> or bdg details console <index>',
+                    },
+                };
+            }
             const response = await getDetails(opts.type, opts.id);
             validateIPCResponse(response);
             if (!response.data?.item) {
@@ -55,7 +65,7 @@ export function registerDetailsCommand(program) {
                     exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                     errorContext: {
                         suggestion: opts.type === 'network'
-                            ? 'Use bdg peek --network to see available request IDs'
+                            ? 'Use bdg network list to see available request IDs'
                             : 'Use bdg peek --console to see available console message indices',
                     },
                 };

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

@@ -1,28 +1,21 @@
 /**
  * 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 }
+ * // { success: true, selector: '.cached-selector', backendNodeId: 42 }
  *
- * // Resolve CSS selector directly
  * const target = await resolver.resolve('button.submit');
  * // { 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';
@@ -32,10 +25,12 @@ import { QueryCacheManager } from '../../session/QueryCacheManager.js';
 export interface ElementTargetSuccess {
     /** Resolution succeeded */
     success: true;
-    /** CSS selector to use */
+    /** CSS selector (for an index: the selector shown to the user) */
     selector: string;
-    /** 0-based index for selector (if resolved from cached query) */
+    /** 0-based index among the selector's matches (selector arguments only) */
     index?: number | undefined;
+    /** Exact element from the query cache (index arguments only) */
+    backendNodeId?: number | undefined;
 }
 /**
  * Failed result of resolving a selector or index argument.
@@ -52,14 +47,10 @@ export interface ElementTargetFailure {
 }
 /**
  * Result of resolving a selector or index argument to an element target.
- * Discriminated union that guarantees selector exists when success is true.
  */
 export type ElementTargetResult = ElementTargetSuccess | ElementTargetFailure;
 /**
  * Singleton resolver for DOM element access patterns.
- *
- * Centralizes element resolution with cache validation, automatic refresh,
- * and consistent error handling.
  */
 export declare class DomElementResolver {
     private static instance;
@@ -70,16 +61,6 @@ export declare class DomElementResolver {
      * @param cacheManager - Query cache manager (defaults to singleton)
      */
     constructor(cacheManager?: QueryCacheManager);
-    /**
-     * 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
-     */
-    private refreshCache;
     /**
      * Get the singleton instance.
      *
@@ -93,56 +74,22 @@ export declare 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)
+     * @returns Resolution result
      */
     resolve(selectorOrIndex: string, explicitIndex?: number): Promise<ElementTargetResult>;
     /**
-     * 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)
      */
     getNodeIdForIndex(index: number): Promise<{
         nodeId: number;
     }>;
-    /**
-     * 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
-     */
-    getElementCount(): Promise<number>;
     /**
      * Check if the argument is a numeric index.
      *
@@ -150,5 +97,13 @@ export declare class DomElementResolver {
      * @returns True if the string is a numeric index
      */
     isNumericIndex(selectorOrIndex: string): boolean;
+    /**
+     * 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
+     */
+    private lookup;
 }
 //# sourceMappingURL=DomElementResolver.d.ts.map

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 }
+ * // { success: true, selector: '.cached-selector', backendNodeId: 42 }
  *
- * // Resolve CSS selector directly
  * const target = await resolver.resolve('button.submit');
  * // { success: true, selector: 'button.submit' }
- *
- * // Get nodeId for cached index (throws if invalid)
- * const nodeId = await resolver.getNodeIdForIndex(0);
  * ```
  */
+import { noActiveSessionError } from '../shared/CommandRunner.js';
+import { CommandError } from '../../errors/index.js';
+import { indexOutOfRangeError, indexWithIndexOptionError, staleNodeError, } from '../../errors/messages.js';
 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 { 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,65 @@ 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)
+     * @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;
+        if (!this.isNumericIndex(selectorOrIndex)) {
+            return { success: true, selector: selectorOrIndex, index: explicitIndex };
+        }
+        if (explicitIndex !== undefined) {
+            const err = indexWithIndexOptionError(selectorOrIndex);
+            return {
+                success: false,
+                error: err.message,
+                exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+                suggestion: err.suggestion,
+            };
+        }
+        try {
             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);
+            const { node, selector } = await this.lookup(index);
+            if (node.nodeId <= 0) {
+                const err = staleNodeError(index);
                 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: node.selector ?? selector, backendNodeId: node.nodeId };
+        }
+        catch (error) {
+            if (!(error instanceof CommandError))
+                throw error;
             return {
-                success: true,
-                selector: resolvedSelector,
-                index: resolvedIndex,
+                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 } = await this.lookup(index);
+        if (node.nodeId <= 0) {
+            const err = staleNodeError(index);
             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, index);
+        return node;
     }
     /**
      * Check if the argument is a numeric index.
@@ -238,5 +125,27 @@ 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 node = nodes.find((n) => n.index === index);
+        if (!node) {
+            const err = indexOutOfRangeError(index, nodes.length - 1);
+            throw new CommandError(`${err.message} in the last query ("${selector}")`, { suggestion: nodes.length > 0 ? err.suggestion : 'Re-run the query' }, EXIT_CODES.STALE_CACHE);
+        }
+        return { node, selector };
+    }
 }
 //# sourceMappingURL=DomElementResolver.js.map

package/dist/commands/dom/a11y.js

@@ -8,14 +8,15 @@
  *
  * 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 { CommandError } from '../../errors/index.js';
+import { elementNotFoundError, invalidQueryPatternError, noA11yNodesFoundError, notInAccessibilityTreeError, } from '../../errors/messages.js';
+import { 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';
 /**
  * Handle bdg dom a11y tree command
@@ -40,8 +41,21 @@ 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
@@ -72,7 +86,17 @@ 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 ${pattern}`,
+            count: indexed.count,
+            nodes: indexed.nodes.map((node) => ({
+                index: node.index,
+                nodeId: node.backendDOMNodeId ?? 0,
+                tag: node.role,
+            })),
+        });
+        return { success: true, data: indexed };
     }, options, formatA11yQueryResult);
 }
 /**
@@ -101,28 +125,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 +164,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 +179,7 @@ export function registerA11yCommands(domCmd) {
             await handleA11yQuery(search, options);
         }
         else {
-            await handleA11yQuery(`name:*${search}*`, options);
+            await handleA11yQuery(`name:${quoteQueryValue(search)}`, options);
         }
     });
     a11y
@@ -173,7 +192,7 @@ 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 (e.g. "role:button name:Submit", "role=link,name=Google Chrome")')
         .addOption(jsonOption())
         .action(async (pattern, options) => {
         await handleA11yQuery(pattern, options);

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

@@ -0,0 +1,13 @@
+/**
+ * `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>]`.
+ */
+export declare function handleDomEval(script: string, options: DomEvalCommandOptions): Promise<void>;
+//# sourceMappingURL=eval.d.ts.map