browser-debugger-cli 0.12.0 → 0.13.0

package/.claude/skills/bdg/SKILL.md

@@ -16,8 +16,8 @@ bdg stop                         # End session
 ## Session Management
 
 ```bash
-bdg <url>                  # Start session (1920x1080, headless if no display)
-bdg <url> --headless       # Force headless mode
+bdg <url>                  # Start session (a window on a Mac or Linux desktop; headless over SSH, with CI set, on servers)
+bdg <url> --headless       # Force headless mode (do this when running unattended)
 bdg <url> --no-headless    # Force visible browser window
 bdg status                 # Check session status
 bdg peek                   # Preview collected telemetry
@@ -98,7 +98,7 @@ Selectors search open shadow roots and same-origin iframes, and accept `:has-tex
 ### Look Without a Screenshot
 
 ```bash
-bdg dom inspect "button.primary"   # Box, layout, rendered font, colors + WCAG contrast, borders, state (~60-100 tokens)
+bdg dom inspect "button.primary"   # Box, layout, rendered font, colors + WCAG contrast, borders, state (~80-130 tokens; --no-hints drops the hints)
 bdg dom inspect ".card" --why color  # Which CSS rule set a property, and what it overrode
 bdg dom layout ".card"             # Positions/sizes of every match: above/below the fold, hidden, covered
 bdg dom listeners "#save"          # Event listeners that run for an element (incl. delegated, React/Preact)
@@ -176,7 +176,7 @@ bdg cdp Runtime.evaluate --params '{
 
 ## JSON Output and Exit Codes
 
-Add `--json` (`-j`) to any command for `{ version, success, data }` (or `{ success: false, error, exitCode, suggestion }`). `bdg --help --json` lists every command, flag and exit code.
+Add `--json` (`-j`) to any command for `{ version, success, data }` (or `{ success: false, error, exitCode, suggestion }`). `bdg --help --json` lists every command, flag and exit code; `bdg <command> --help --json` describes one command in full (option behaviors, defaults, examples).
 
 | Code | Meaning | Action |
 |------|---------|--------|

package/README.md

@@ -81,6 +81,7 @@ No docs to paste into the prompt. The agent asks bdg:
 
 ```bash
 bdg --help --json                          # Every command, flag and exit code, plus "task → command" mappings
+bdg dom query --help --json                # One command in full: option behaviors, defaults, examples
 bdg cdp --search cookie                    # 13 matching methods across all CDP domains, each with an example call
 bdg cdp Network.getCookies --describe      # Parameters, return types, an example
 ```

package/dist/commands/cdp.d.ts

@@ -1,4 +1,7 @@
-import type { Command } from 'commander';
+import { type Command } from 'commander';
+import { type CommandResult } from './shared/CommandRunner.js';
+import type { CdpCommandOptions } from './shared/optionTypes.js';
+import { type CdpExecuteData } from '../ui/formatters/cdp.js';
 /**
  * Register CDP command with full introspection support.
  *
@@ -14,4 +17,22 @@ import type { Command } from 'commander';
  * @param program - Commander.js Command instance to register commands on
  */
 export declare function registerCdpCommand(program: Command): void;
+/**
+ * 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 declare function isBareDomain(method: string, options: CdpCommandOptions): boolean;
+/**
+ * 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 declare function pageExceptionResult(result: unknown): CommandResult<CdpExecuteData> | undefined;
 //# sourceMappingURL=cdp.d.ts.map

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,12 @@ 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 { 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 +38,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,10 +116,15 @@ 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 {
+        ...(options.last !== undefined && { groupLimit: lastN }),
+        ...(dropped && { dropped }),
+        ...(pageCrashedAt !== undefined && { pageCrashedAt }),
         json: options.json,
         list: listsMessages(options),
         follow: options.follow,
@@ -99,13 +136,15 @@ function buildFormatOptions(options, lastN, 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 +154,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,9 +164,13 @@ 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,
+                });
+                console.log(JSON.stringify(buildSuccessResponse(data)));
             }
         }
         else {
@@ -137,6 +181,8 @@ async function runFollowMode(options, lastN) {
             });
             if (text)
                 console.log(text);
+            if (crashedAt !== undefined)
+                console.log(pageCrashedNote(crashedAt));
         }
         started = true;
         return undefined;
@@ -196,19 +242,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.js

@@ -9,7 +9,7 @@
  * 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';
@@ -85,6 +85,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,7 +102,7 @@ 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)),

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

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

package/dist/commands/dom/eval.js

@@ -10,12 +10,13 @@ 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 { evalFrameLine, warningMessage } 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.
+ * 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.
  */
 export async function handleDomEval(script, options) {
     await runCommand(async () => {
@@ -38,7 +39,11 @@ 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: {
@@ -46,8 +51,9 @@ export async function handleDomEval(script, options) {
                 type,
                 ...(subtype && { subtype }),
                 ...(frame !== undefined && { frame }),
+                ...(warning && { warning }),
             },
-            ...(frame !== undefined && !options.json && { hint: evalFrameLine(frame) }),
+            ...(hint && !options.json && { hint }),
         };
     }, options, formatDomEval);
 }

package/dist/commands/dom/form.js

@@ -5,11 +5,12 @@
  * validation state, and suggested commands for agent consumption.
  */
 import { calculateSummary, orderForms, primaryButtonIndex } from './formSummary.js';
-import { resolveBackendNodeIds } from './helpers/index.js';
+import { pageDocumentId, resolveBackendNodeIds } from './helpers/index.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
 import { noFormsFoundError, formInIframeError } from '../../errors/messages.js';
 import { domFormDiscover } from '../../ipc/client.js';
+import { MASKED_VALUE } from '../../runtime/dom/elementInfo.js';
 import { FORM_DISCOVERY_CACHE_SELECTOR, QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { formatFormDiscovery } from '../../ui/formatters/form.js';
 import { createLogger } from '../../ui/logging/index.js';
@@ -84,16 +85,14 @@ function buildFieldState(raw) {
     return 'empty';
 }
 /**
- * Build masked value for password fields.
+ * The masked value of a sensitive field (the page script never sends its
+ * real value).
  *
  * @param raw - Raw field data
  * @returns Masked value string
  */
 function buildMaskedValue(raw) {
-    if (raw.inputType === 'password' && typeof raw.value === 'string' && raw.value.length > 0) {
-        return '•'.repeat(Math.min(raw.value.length, 8));
-    }
-    return undefined;
+    return raw.value === MASKED_VALUE ? MASKED_VALUE : undefined;
 }
 /**
  * Build interaction warning for non-native fields.
@@ -244,8 +243,9 @@ function transformForm(raw) {
  * the selector later.
  *
  * @param forms - Discovered forms
+ * @param document - Identity of the page document they were found in, read before discovery
  */
-async function cacheFormElements(forms) {
+async function cacheFormElements(forms, document) {
     const elements = forms.flatMap((form) => [...form.fields, ...form.buttons]);
     const backendNodeIds = await resolveBackendNodeIds(elements.map((el) => el.selector)).catch((error) => {
         log.debug(`Form fields not cached by node: ${getErrorMessage(error)}`);
@@ -259,7 +259,7 @@ async function cacheFormElements(forms) {
             nodeId: backendNodeIds[i] ?? 0,
             selector: el.selector,
         })),
-    });
+    }, document);
     log.debug(`Cached ${elements.length} form elements`);
 }
 /**
@@ -269,6 +269,7 @@ async function cacheFormElements(forms) {
  */
 async function handleFormCommand(options) {
     await runCommand(async () => {
+        const document = await pageDocumentId();
         const response = await domFormDiscover();
         if (response.status === 'error' || !response.data) {
             return {
@@ -311,7 +312,7 @@ async function handleFormCommand(options) {
         const allForms = orderForms(rawData.forms).map(transformForm);
         const forms = options.all ? allForms : [allForms[0]];
         // Cache ALL forms so global indices work with bdg dom fill/click
-        await cacheFormElements(allForms);
+        await cacheFormElements(allForms, document);
         const result = {
             formCount: rawData.forms.length,
             selectedForm: 0,