browser-debugger-cli 0.12.0 → 0.14.0

package/dist/commands/cdp.js

@@ -1,10 +1,14 @@
+import { Option } from 'commander';
 import { normalizeMethod } from '../cdp/protocol.js';
 import { getAllDomainSummaries, getDomainMethods, getProtocolCounts, getDomainSummary, getMethodSchema, } from '../cdp/schema.js';
 import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
 import { CommandError } from '../errors/index.js';
+import { emptyCdpSearchError, missingArgumentError, scriptExecutionError, } from '../errors/messages.js';
 import { callCDP } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
+import { describeException } from '../runtime/dom/evalHelpers.js';
+import { formatCdpDescription, formatCdpDomainMethods, formatCdpDomains, formatCdpResult, formatCdpSearch, isEmptyCdpResult, } from '../ui/formatters/cdp.js';
 import { formatHint } from '../ui/messages/hints.js';
 import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
@@ -26,6 +30,8 @@ const DOMAIN_NOTES = {
     Tracing: 'Performance tracing. Call Tracing.start, perform actions, then Tracing.end. ' +
         'Data arrives via Tracing.dataCollected events.',
 };
+/** Usage of `bdg cdp`, suggested when it gets neither a method nor a flag */
+const CDP_USAGE = 'Usage: bdg cdp [method] [--params <json>] [--list] [--describe] [--search <query>]';
 /**
  * Domain and method counts of the bundled protocol, for the help text.
  *
@@ -44,18 +50,6 @@ const METHOD_NOTES = {
     'Profiler.start': 'Starts CPU profiling. Returns empty. Call Profiler.stop to get the profile data.',
     'Tracing.start': 'Starts tracing. Returns empty. Data arrives via events after Tracing.end.',
 };
-/**
- * Check if a CDP result is empty (null, undefined, or empty object).
- */
-function isEmptyResult(result) {
-    if (result === null || result === undefined) {
-        return true;
-    }
-    if (typeof result === 'object' && Object.keys(result).length === 0) {
-        return true;
-    }
-    return false;
-}
 /**
  * Get contextual hint for a method based on domain notes and result.
  */
@@ -64,7 +58,7 @@ function getMethodHint(methodName, result) {
         return METHOD_NOTES[methodName];
     }
     const domain = methodName.split('.')[0];
-    if (domain && DOMAIN_NOTES[domain] && isEmptyResult(result)) {
+    if (domain && DOMAIN_NOTES[domain] && isEmptyCdpResult(result)) {
         return DOMAIN_NOTES[domain];
     }
     return undefined;
@@ -90,35 +84,87 @@ export function registerCdpCommand(program) {
         '  Discovery: --list, --search, --describe\n' +
         '  Execution: case-insensitive (network.getcookies works)')
         .argument('[method]', 'CDP method name (e.g., Network.getCookies, network.getcookies)')
-        .option('--params <json>', 'Method parameters as JSON')
-        .option('--list', 'List all domains or methods in a domain')
-        .option('--describe', 'Show method signature and parameters')
-        .option('--search <query>', 'Search methods by keyword')
-        .addOption(jsonOption().hideHelp())
+        .addOption(new Option('--params <json>', 'Method parameters as JSON'))
+        .addOption(new Option('--list', 'List all domains or methods in a domain').conflicts([
+        'describe',
+        'params',
+    ]))
+        .addOption(new Option('--describe', 'Show method signature and parameters').conflicts('params'))
+        .addOption(new Option('--search <query>', 'Search methods by keyword').conflicts([
+        'list',
+        'describe',
+        'params',
+    ]))
+        .addOption(jsonOption())
         .addHelpText('after', () => `\nBundled protocol: ${cdpCountsText()}`)
         .action(async (method, options) => {
-        await runCommand(async (opts) => {
-            if (opts.search) {
-                return await handleSearch(opts.search, method);
-            }
-            if (opts.list && !method) {
-                return handleListDomains();
-            }
-            if (opts.list && method) {
-                return handleListDomainMethods(method);
-            }
-            if (opts.describe && method) {
-                return handleDescribeMethod(method);
-            }
-            if (method) {
-                return await handleExecuteMethod(method, opts.params);
-            }
-            throw new CommandError('Missing required argument or flag', {
-                suggestion: 'Usage: bdg cdp [method] [--params <json>] [--list] [--describe] [--search <query>]',
-            }, EXIT_CODES.INVALID_ARGUMENTS);
-        }, { ...options, json: true });
+        await runCdpCommand(method, options);
     });
 }
+/**
+ * Run the `bdg cdp` mode the options select, with its human-readable output.
+ *
+ * @param method - Method or domain argument
+ * @param options - Command options (exits 81 when neither a method nor a
+ *   discovery flag is given)
+ */
+async function runCdpCommand(method, options) {
+    if (options.search !== undefined) {
+        const query = options.search;
+        return runCommand(async () => handleSearch(query, method), options, formatCdpSearch);
+    }
+    if (method && (options.list || isBareDomain(method, options))) {
+        return runCommand(async () => handleListDomainMethods(method), options, formatCdpDomainMethods);
+    }
+    if (options.list)
+        return runCommand(async () => handleListDomains(), options, formatCdpDomains);
+    if (options.describe && method) {
+        return runCommand(async () => handleDescribeMethod(method), options, formatCdpDescription);
+    }
+    if (method) {
+        return runCommand(async () => handleExecuteMethod(method, options.params), options, formatCdpResult);
+    }
+    return runCommand(async () => {
+        const err = missingArgumentError(CDP_USAGE);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }, options);
+}
+/**
+ * Whether the argument names a domain without a method and nothing asks to
+ * run it (`bdg cdp Network`): its methods are listed, as with `--list`.
+ *
+ * @param method - Method or domain argument
+ * @param options - Command options
+ * @returns True for a bare domain name
+ */
+export function isBareDomain(method, options) {
+    return (!method.includes('.') &&
+        options.params === undefined &&
+        !options.describe &&
+        getDomainSummary(method) !== undefined);
+}
+/**
+ * The page exception a method reported in its result (`Runtime.evaluate`,
+ * `Runtime.callFunctionOn`, ... answer a script that threw with
+ * `exceptionDetails`), as an error result like `dom eval`'s (exit 91).
+ *
+ * @param result - Method result
+ * @returns Error result, or undefined when the result has no exception
+ */
+export function pageExceptionResult(result) {
+    if (typeof result !== 'object' || result === null || !('exceptionDetails' in result)) {
+        return undefined;
+    }
+    const details = result
+        .exceptionDetails;
+    const err = scriptExecutionError(describeException(details));
+    return {
+        success: false,
+        error: err.message,
+        exitCode: EXIT_CODES.SCRIPT_ERROR,
+        errorContext: { suggestion: err.suggestion },
+    };
+}
 /**
  * Find similar methods to suggest when a method is not found.
  * Returns up to 3 closest matches based on edit distance.
@@ -177,6 +223,15 @@ function blockedAlternative(methodName) {
  * @returns Success result with matching methods
  */
 async function handleSearch(query, domain) {
+    if (!query.trim()) {
+        const err = emptyCdpSearchError();
+        return {
+            success: false,
+            error: err.message,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: err.suggestion },
+        };
+    }
     if (domain !== undefined && !getDomainSummary(domain)) {
         return {
             success: false,
@@ -186,11 +241,11 @@ async function handleSearch(query, domain) {
         };
     }
     const { searchMethods } = await import('../cdp/schema.js');
-    const results = searchMethods(query).filter((m) => domain === undefined || m.domain.toLowerCase() === domain.toLowerCase());
+    const results = searchMethods(query.trim()).filter((m) => domain === undefined || m.domain.toLowerCase() === domain.toLowerCase());
     return {
         success: true,
         data: {
-            query,
+            query: query.trim(),
             count: results.length,
             methods: results.map((m) => ({
                 name: m.name,
@@ -338,6 +393,7 @@ function handleDescribeMethod(methodName) {
         };
     }
     const methodNote = METHOD_NOTES[schema.name] ?? DOMAIN_NOTES[schema.domain];
+    const alternative = blockedAlternative(schema.name);
     return {
         success: true,
         data: {
@@ -365,9 +421,7 @@ function handleDescribeMethod(methodName) {
                 description: r.description,
                 items: r.items,
             })),
-            example: blockedAlternative(schema.name)
-                ? { command: blockedAlternative(schema.name) }
-                : schema.example,
+            example: alternative ? { command: alternative } : schema.example,
         },
     };
 }
@@ -443,6 +497,9 @@ async function handleExecuteMethod(methodName, paramsJson) {
     const response = await callCDP(normalized, params);
     validateIPCResponse(response);
     const cdpResult = response.data?.result;
+    const exception = pageExceptionResult(cdpResult);
+    if (exception)
+        return exception;
     const result = {
         success: true,
         data: {

package/dist/commands/console.d.ts

@@ -22,6 +22,18 @@ export declare function listsMessages(options: Pick<ConsoleCommandOptions, 'list
  * @returns Messages of the current page (empty if it logged nothing)
  */
 export declare function filterByCurrentNavigation(messages: ConsoleMessage[], currentNavigationId?: number): ConsoleMessage[];
+/**
+ * Dropped messages that could have been in the view: all of them with
+ * `--history`; for the current page only while the oldest kept message is
+ * that page's (else every dropped one came from an earlier page).
+ *
+ * @param messages - All kept messages, oldest first
+ * @param dropped - Oldest messages the session dropped at its limit
+ * @param options - `--history`
+ * @param currentNavigationId - Navigation id of the current page, if known
+ * @returns Dropped count to warn about (0: none of the view's)
+ */
+export declare function droppedInView(messages: ConsoleMessage[], dropped: number, options: Pick<ConsoleCommandOptions, 'history'>, currentNavigationId?: number): number;
 export declare function filterByLevel(messages: ConsoleMessage[], level: ConsoleLevel): ConsoleMessage[];
 /**
  * Messages the filters left out between the first and the last listed

package/dist/commands/console.js

@@ -6,11 +6,13 @@ import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
 import { noteFollowConnected } from './shared/daemonErrorHandler.js';
 import { fetchConsoleMessages, createErrorResult } from './shared/dataFetcher.js';
-import { followFetchFailure, setupFollowMode, } from './shared/followMode.js';
+import { followFetchFailure, newPageCrashes, setupFollowMode, } from './shared/followMode.js';
 import { handleValidationError } from './shared/handleValidationError.js';
 import { consoleLevelOption, positiveIntRule } from './shared/validation.js';
+import { MAX_CONSOLE_JSON_TEXT_LENGTH, MAX_CONSOLE_TEXT_LENGTH } from '../constants.js';
 import { buildSuccessResponse } from '../ui/OutputBuilder.js';
 import { buildConsoleJsonOutput, formatConsole, formatConsoleFollowLines, LEVEL_MAP, lastMessages, } from '../ui/formatters/console.js';
+import { pageCrashedNote } from '../ui/messages/commands.js';
 import { followingConsoleMessage, stoppedFollowingConsoleMessage, } from '../ui/messages/consoleMessages.js';
 const MIN_LAST = 0;
 const MAX_LAST = 10000;
@@ -37,9 +39,40 @@ export function listsMessages(options) {
 export function filterByCurrentNavigation(messages, currentNavigationId) {
     if (messages.length === 0)
         return messages;
-    const navId = currentNavigationId ?? Math.max(...messages.map((m) => m.navigationId ?? 0));
+    const navId = shownNavigationId(messages, currentNavigationId);
     return messages.filter((m) => (m.navigationId ?? 0) === navId);
 }
+/**
+ * Navigation id of the page whose messages are shown without `--history`.
+ *
+ * @param messages - All captured messages
+ * @param currentNavigationId - Navigation id of the current page, if known
+ * @returns That id, else the newest navigation id among the messages
+ */
+function shownNavigationId(messages, currentNavigationId) {
+    return currentNavigationId ?? Math.max(...messages.map((m) => m.navigationId ?? 0));
+}
+/**
+ * Dropped messages that could have been in the view: all of them with
+ * `--history`; for the current page only while the oldest kept message is
+ * that page's (else every dropped one came from an earlier page).
+ *
+ * @param messages - All kept messages, oldest first
+ * @param dropped - Oldest messages the session dropped at its limit
+ * @param options - `--history`
+ * @param currentNavigationId - Navigation id of the current page, if known
+ * @returns Dropped count to warn about (0: none of the view's)
+ */
+export function droppedInView(messages, dropped, options, currentNavigationId) {
+    if (dropped === 0 || options.history)
+        return dropped;
+    const oldest = messages[0];
+    if (!oldest)
+        return dropped;
+    return (oldest.navigationId ?? 0) === shownNavigationId(messages, currentNavigationId)
+        ? dropped
+        : 0;
+}
 export function filterByLevel(messages, level) {
     return messages.filter((m) => LEVEL_MAP[m.type] === level);
 }
@@ -84,28 +117,35 @@ export function skippedMessages(all, listed) {
  * @param options - Command options
  * @param lastN - `--last` value
  * @param skipped - Messages the filters left out between the listed ones
+ * @param dropped - Oldest messages the session dropped at its limit
+ * @param pageCrashedAt - When the page crashed, while it is not loaded again
  * @returns Formatting options
  */
-function buildFormatOptions(options, lastN, skipped) {
+function buildFormatOptions(options, lastN, skipped, dropped, pageCrashedAt) {
     return {
-        json: options.json,
+        ...(options.last !== undefined && { groupLimit: lastN }),
+        ...(dropped && { dropped }),
+        ...(pageCrashedAt !== undefined && { pageCrashedAt }),
         list: listsMessages(options),
         follow: options.follow,
         last: lastN,
         history: options.history,
         level: options.level,
+        full: options.full,
         skipped,
     };
 }
 /**
  * Stream console messages: the last `lastN` at start, then each new message
- * once (like `tail -f`), with a separator when the page navigates.
+ * once (like `tail -f`), with a separator when the page navigates and a
+ * warning (JSON `pageCrashedAt`) once when the page crashes.
  *
  * @param options - Command options
  * @param lastN - Messages to show at start (0 = all)
  */
 async function runFollowMode(options, lastN) {
     const shown = new Set();
+    const newCrash = newPageCrashes();
     let navigationId;
     let started = false;
     const showConsole = async () => {
@@ -115,6 +155,7 @@ async function runFollowMode(options, lastN) {
         }
         noteFollowConnected();
         const { messages, currentNavigationId } = result.data;
+        const crashedAt = newCrash(result.data.pageCrashedAt);
         const matching = applyFilters(messages, options, currentNavigationId);
         const keys = messageKeys(matching);
         const fresh = matching.filter((_message, i) => !shown.has(keys[i]));
@@ -124,19 +165,27 @@ async function runFollowMode(options, lastN) {
         const navigated = started && navigationId !== currentNavigationId;
         navigationId = currentNavigationId;
         if (options.json) {
-            if (!started || backlog.length > 0) {
-                const data = buildConsoleJsonOutput(backlog, { list: true, last: 0 });
-                console.log(JSON.stringify(buildSuccessResponse(data), null, 2));
+            if (!started || backlog.length > 0 || crashedAt !== undefined) {
+                const data = buildConsoleJsonOutput(backlog, {
+                    list: true,
+                    last: 0,
+                    pageCrashedAt: crashedAt,
+                    full: options.full,
+                });
+                console.log(JSON.stringify(buildSuccessResponse(data)));
             }
         }
         else {
             const text = formatConsoleFollowLines(backlog, {
                 header: !started,
+                full: options.full,
                 ...(navigated &&
                     currentNavigationId !== undefined && { navigationId: currentNavigationId }),
             });
             if (text)
                 console.log(text);
+            if (crashedAt !== undefined)
+                console.log(pageCrashedNote(crashedAt));
         }
         started = true;
         return undefined;
@@ -173,6 +222,7 @@ export function registerConsoleCommand(program) {
         .addOption(new Option('-H, --history', 'Show messages from all page loads (default: current only)').default(false))
         .addOption(new Option('--level <level>', 'Filter by message level: error, warning, info (includes log), debug; any case').argParser(consoleLevelOption))
         .addOption(consoleLastOption)
+        .addOption(new Option('--full', `Print message texts whole (default: the first ${MAX_CONSOLE_TEXT_LENGTH} characters, ${MAX_CONSOLE_JSON_TEXT_LENGTH} in JSON)`).default(false))
         .addOption(jsonOption())
         .action(async (options) => {
         let lastN;
@@ -196,19 +246,23 @@ export function registerConsoleCommand(program) {
             if (!result.success) {
                 return createErrorResult(result.error, result.exitCode, result.suggestion);
             }
-            const { messages, currentNavigationId } = result.data;
+            const { messages, currentNavigationId, dropped, pageCrashedAt } = result.data;
             const filtered = applyFilters(messages, options, currentNavigationId);
             if (options.json) {
                 return {
                     success: true,
-                    data: buildConsoleJsonOutput(filtered, buildFormatOptions(options, lastN)),
+                    data: buildConsoleJsonOutput(filtered, buildFormatOptions(options, lastN, undefined, dropped, pageCrashedAt)),
                 };
             }
-            return { success: true, data: { messages, filtered } };
+            const droppedShown = droppedInView(messages, dropped, options, currentNavigationId);
+            return {
+                success: true,
+                data: { messages, filtered, dropped: droppedShown, pageCrashedAt },
+            };
         }, options, (data) => {
-            const { messages, filtered } = data;
+            const { messages, filtered, dropped, pageCrashedAt } = data;
             const skipped = skippedMessages(messages, lastMessages(filtered, lastN));
-            return formatConsole(filtered, buildFormatOptions(options, lastN, skipped));
+            return formatConsole(filtered, buildFormatOptions(options, lastN, skipped, dropped, pageCrashedAt));
         });
     });
 }

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

@@ -109,7 +109,9 @@ export declare class DomElementResolver {
      *
      * @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
+     * @throws CommandError (83) without a session, (81) without a usable cache,
+     *   (87) for an index outside the cached results or of a page document
+     *   that has since been replaced (another page's elements reuse its node ids)
      */
     private lookup;
 }

package/dist/commands/dom/DomElementResolver.js

@@ -18,6 +18,7 @@
  * // { success: true, selector: 'button.submit' }
  * ```
  */
+import { pageDocumentId } from './helpers/query.js';
 import { noActiveSessionError } from '../shared/CommandRunner.js';
 import { CommandError } from '../../errors/index.js';
 import { cachedIndexOutOfRangeError, indexWithIndexOptionError, staleNodeError, } from '../../errors/messages.js';
@@ -136,7 +137,9 @@ export class DomElementResolver {
      *
      * @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
+     * @throws CommandError (83) without a session, (81) without a usable cache,
+     *   (87) for an index outside the cached results or of a page document
+     *   that has since been replaced (another page's elements reuse its node ids)
      */
     async lookup(index) {
         const validation = await this.cacheManager.validate();
@@ -145,11 +148,15 @@ export class DomElementResolver {
                 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 { nodes, selector, count, document } = validation.cache;
         const source = indexSourceOf(index, selector);
+        if (document !== undefined && (await pageDocumentId()) !== document) {
+            const err = staleNodeError(index, source);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
+        }
         const node = nodes.find((n) => n.index === index);
         if (!node) {
-            const err = cachedIndexOutOfRangeError(source, nodes.length);
+            const err = cachedIndexOutOfRangeError(source, nodes.length, count);
             throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
         }
         return { node, selector, source };

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

@@ -2,7 +2,7 @@
  * Accessibility tree inspection commands for semantic element queries.
  *
  * Provides three core commands:
- * - tree: Dump full accessibility tree
+ * - tree: List the accessibility tree (bounded by --limit / --depth)
  * - query: Search by role/name/description patterns
  * - describe: Get A11y properties for CSS selector
  *

package/dist/commands/dom/a11y.js

@@ -2,50 +2,48 @@
  * Accessibility tree inspection commands for semantic element queries.
  *
  * Provides three core commands:
- * - tree: Dump full accessibility tree
+ * - tree: List the accessibility tree (bounded by --limit / --depth)
  * - query: Search by role/name/description patterns
  * - describe: Get A11y properties for CSS selector
  *
  * Uses IPC/callCDP pattern for consistency with other DOM commands.
  */
 import { DomElementResolver } from './DomElementResolver.js';
-import { getDomContext, resolveBackendNodeIds } from './helpers/index.js';
+import { getDomContext, pageDocumentId, resolveBackendNodeIds, } from './helpers/index.js';
 import { withSecretMasked } from './semanticUtils.js';
 import { runCommand, runJsonCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
 import { integerOption } from '../shared/validation.js';
+import { QUERY_JSON_LIST_LIMIT } from '../../constants.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 { a11yIgnoredReasons, collectA11yTree, listA11yTree, queryA11yTree, parseQueryPattern, resolveA11yNode, } from '../../telemetry/a11y.js';
 import { formatA11yTree, formatA11yQueryResult, formatA11yNodeWithContext, } from '../../ui/formatters/a11y.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) */
+/** Matches `dom a11y query` lists by default in human output (a page can have hundreds of links) */
 const A11Y_QUERY_LIMIT = 50;
+/** Nodes `dom a11y tree` lists by default, in human and JSON output */
+const A11Y_TREE_LIMIT = 50;
 /**
  * Handle bdg dom a11y tree command
  *
- * Dumps the full accessibility tree for the current page via IPC.
- * Filters out ignored nodes for cleaner output.
+ * Lists the accessibility tree depth-first, the first `--limit` meaningful
+ * nodes (default {@link A11Y_TREE_LIMIT}, 0 = all) down to `--depth`, in
+ * human and JSON output; `count` is the whole tree, `omitted` the nodes cut
+ * and `skipped` the noise never listed.
  *
- * JSON output returns nodes as an array for natural jq filtering:
- *   bdg dom a11y tree --json | jq '.data.nodes[] | select(.role == "checkbox")'
- *   bdg dom a11y tree --json | jq '.data.nodes[0]'
+ * JSON output returns nodes as an array (each with its `depth`) for jq:
+ *   bdg dom a11y tree --json --limit 0 | jq '.data.nodes[] | select(.role == "checkbox")'
  *
  * @param options - Command options
  */
 async function handleA11yTree(options) {
+    const listTree = async () => listA11yTree(await collectA11yTree(), options.limit ?? A11Y_TREE_LIMIT, options.depth);
     if (options.json) {
-        await runJsonCommand(async () => {
-            const tree = await collectA11yTree();
-            return {
-                root: tree.root,
-                nodes: Array.from(tree.nodes.values()),
-                count: tree.count,
-            };
-        });
+        await runJsonCommand(listTree);
     }
-    await runCommand(async () => ({ success: true, data: await collectA11yTree() }), options, formatA11yTree);
+    await runCommand(async () => ({ success: true, data: await listTree() }), options, formatA11yTree);
 }
 /**
  * Quote a search text for a query pattern, keeping the quotes it contains
@@ -85,6 +83,7 @@ async function handleA11yQuery(pattern, options) {
             const err = invalidQueryPatternError(pattern);
             throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
         }
+        const document = await pageDocumentId();
         const tree = await collectA11yTree();
         const result = queryA11yTree(tree, queryPattern);
         if (result.count === 0) {
@@ -101,10 +100,10 @@ async function handleA11yQuery(pattern, options) {
                 tag: node.role,
                 ...(node.name && { preview: node.name }),
             })),
-        });
+        }, document);
         return {
             success: true,
-            data: limitMatches(indexed, options.limit ?? (options.json ? 0 : A11Y_QUERY_LIMIT)),
+            data: limitMatches(indexed, options.limit ?? (options.json ? QUERY_JSON_LIST_LIMIT : A11Y_QUERY_LIMIT)),
         };
     }, options, formatA11yQueryResult);
 }
@@ -206,7 +205,9 @@ export function registerA11yCommands(domCmd) {
     });
     a11y
         .command('tree')
-        .description('Dump full accessibility tree (filters ignored nodes)')
+        .description('List the accessibility tree depth-first (ignored nodes, text boxes, repeated text and nameless wrappers left out)')
+        .option('--limit <n>', `Nodes to list (default: ${A11Y_TREE_LIMIT}, also with --json; 0 = all listed nodes (text boxes and empty wrappers are always skipped))`, integerOption(0))
+        .option('--depth <n>', 'Levels below the root to list (0 = root only; default: all)', integerOption(0))
         .addOption(jsonOption())
         .action(async (options) => {
         await handleA11yTree(options);
@@ -215,7 +216,7 @@ export function registerA11yCommands(domCmd) {
         .command('query')
         .description('Query elements by accessibility properties (e.g., "role:button", "name:Submit")')
         .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))
+        .option('--limit <n>', `Matches to list (default: ${A11Y_QUERY_LIMIT}, ${QUERY_JSON_LIST_LIMIT} 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

@@ -8,8 +8,10 @@
 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.
+ * frame the script ran in is a `Frame:` line on stderr (JSON: `frame`), and
+ * a warning about how the result was copied goes there too (JSON:
+ * `warning`), so stdout stays the bare value for pipes. Long values are cut
+ * (a string result in JSON with `truncatedFrom`) unless `--full`.
  */
 export declare function handleDomEval(script: string, options: DomEvalCommandOptions): Promise<void>;
 //# sourceMappingURL=eval.d.ts.map

package/dist/commands/dom/eval.js

@@ -7,15 +7,19 @@
  */
 import { documentReadyState } from './helpers/query.js';
 import { runCommand } from '../shared/CommandRunner.js';
+import { MAX_VALUE_LENGTH } from '../../constants.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 { evalFrameLine, warningMessage } from '../../ui/messages/commands.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { capLength } from '../../utils/strings.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.
+ * frame the script ran in is a `Frame:` line on stderr (JSON: `frame`), and
+ * a warning about how the result was copied goes there too (JSON:
+ * `warning`), so stdout stays the bare value for pipes. Long values are cut
+ * (a string result in JSON with `truncatedFrom`) unless `--full`.
  */
 export async function handleDomEval(script, options) {
     await runCommand(async () => {
@@ -38,18 +42,38 @@ export async function handleDomEval(script, options) {
                 ...(suggestion && { errorContext: { suggestion } }),
             };
         }
-        const { value, type, subtype, frame } = response.data;
+        const { value, type, subtype, frame, warning } = response.data;
+        const hint = [
+            ...(frame !== undefined ? [evalFrameLine(frame)] : []),
+            ...(warning ? [warningMessage(warning)] : []),
+        ].join('\n');
         return {
             success: true,
             data: {
-                result: value,
+                ...jsonResult(value, options),
                 type,
                 ...(subtype && { subtype }),
                 ...(frame !== undefined && { frame }),
+                ...(warning && { warning }),
             },
-            ...(frame !== undefined && !options.json && { hint: evalFrameLine(frame) }),
+            ...(hint && !options.json && { hint }),
         };
-    }, options, formatDomEval);
+    }, options, (data) => formatDomEval(data, { full: options.full }));
+}
+/**
+ * The result field of the output: a string result in JSON cut to
+ * {@link MAX_VALUE_LENGTH} characters with `truncatedFrom`, unless `--full`
+ * (human output is cut when formatted).
+ *
+ * @param value - Evaluated value
+ * @param options - `--json`, `--full`
+ * @returns `result`, and `truncatedFrom` when cut
+ */
+function jsonResult(value, options) {
+    if (!options.json || options.full || typeof value !== 'string')
+        return { result: value };
+    const { text, truncatedFrom } = capLength(value, MAX_VALUE_LENGTH);
+    return { result: text, ...(truncatedFrom !== undefined && { truncatedFrom }) };
 }
 /**
  * Suggestion of a failed eval; a frame not found (83) while the page is