browser-debugger-cli 0.11.0 → 0.13.0

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/css.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `bdg css search <text>` - find text in the page's stylesheets, including
+ * cross-origin ones that page scripts cannot read: where a token is set, which
+ * rules use `oklch(`, a class or a custom property.
+ */
+import type { Command } from 'commander';
+/**
+ * Register the `css` command group.
+ *
+ * @param program - Root command
+ */
+export declare function registerCssCommands(program: Command): void;
+//# sourceMappingURL=css.d.ts.map

package/dist/commands/css.js

@@ -0,0 +1,53 @@
+/**
+ * `bdg css search <text>` - find text in the page's stylesheets, including
+ * cross-origin ones that page scripts cannot read: where a token is set, which
+ * rules use `oklch(`, a class or a custom property.
+ */
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { integerOption } from './shared/validation.js';
+import { cssSearch } from '../ipc/client.js';
+import { formatCssSearch } from '../ui/formatters/audit.js';
+import { CSS_SEARCH_HELP_EXAMPLES } from '../ui/messages/commands.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+/**
+ * Register the `css` command group.
+ *
+ * @param program - Root command
+ */
+export function registerCssCommands(program) {
+    const css = program.command('css').description("The page's stylesheets: search <text>");
+    css
+        .command('search')
+        .description('Find text in every stylesheet of the page (cross-origin ones too), with the rule and file:line')
+        .argument('<text>', 'Text to find (case-insensitive), e.g. oklch( or .btn-primary; put -- before one that starts with - (-- --brand)')
+        .option('--limit <n>', 'Matches listed (default: 20)', integerOption(1, 500))
+        .addOption(jsonOption())
+        .addHelpText('after', CSS_SEARCH_HELP_EXAMPLES)
+        .action(async (text, options) => {
+        await runCommand(() => search(text, options), options, formatCssSearch);
+    });
+}
+/**
+ * Ask the daemon to search the stylesheets.
+ *
+ * @param text - Text to find
+ * @param options - Limit
+ * @returns Command result
+ */
+async function search(text, options) {
+    const response = await cssSearch({
+        query: text,
+        ...(options.limit !== undefined && { limit: options.limit }),
+    });
+    if (response.status === 'error' || !response.data) {
+        return {
+            success: false,
+            error: response.error ?? 'Failed to search the stylesheets',
+            exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
+            ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+        };
+    }
+    return { success: true, data: response.data };
+}
+//# sourceMappingURL=css.js.map

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/audit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `bdg dom audit [check...]` - page-wide checks without a screenshot or
+ * `dom eval`: text below a WCAG contrast level, what makes the page scroll
+ * sideways and cut-off text and scaled images, fixed and sticky layers, and
+ * running animations.
+ */
+import type { Command } from 'commander';
+/**
+ * Register `bdg dom audit`.
+ *
+ * @param dom - The `dom` command group
+ */
+export declare function registerAuditCommand(dom: Command): void;
+//# sourceMappingURL=audit.d.ts.map

package/dist/commands/dom/audit.js

@@ -0,0 +1,87 @@
+/**
+ * `bdg dom audit [check...]` - page-wide checks without a screenshot or
+ * `dom eval`: text below a WCAG contrast level, what makes the page scroll
+ * sideways and cut-off text and scaled images, fixed and sticky layers, and
+ * running animations.
+ */
+import { InvalidArgumentError } from 'commander';
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption } from '../shared/commonOptions.js';
+import { integerOption } from '../shared/validation.js';
+import { unknownAuditCheckMessage } from '../../errors/messages.js';
+import { domAudit } from '../../ipc/client.js';
+import { AUDIT_CHECKS } from '../../ipc/protocol/auditTypes.js';
+import { formatAudit } from '../../ui/formatters/audit.js';
+import { AUDIT_HELP_EXAMPLES } from '../../ui/messages/commands.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { findSimilar } from '../../utils/suggestions.js';
+/**
+ * Register `bdg dom audit`.
+ *
+ * @param dom - The `dom` command group
+ */
+export function registerAuditCommand(dom) {
+    dom
+        .command('audit')
+        .description('Page-wide checks: text below WCAG contrast, sideways scroll and cut-off text, scaled images, fixed/sticky layers, animations')
+        .argument('[checks...]', `Checks to run: ${AUDIT_CHECKS.join(', ')} (default: all)`, checkList)
+        .option('--level <level>', 'WCAG level text must reach: AA or AAA (default: AA)', levelOption)
+        .option('--limit <n>', 'Findings listed per check (default: 20)', integerOption(1, 500))
+        .addOption(jsonOption())
+        .addHelpText('after', AUDIT_HELP_EXAMPLES)
+        .action(async (checks, options) => {
+        await runCommand(() => audit(checks, options), options, formatAudit);
+    });
+}
+/**
+ * Parse the checks, rejecting unknown names with the closest one.
+ *
+ * @param value - One check name
+ * @param previous - Checks so far
+ * @returns Checks
+ * @throws InvalidArgumentError for an unknown name
+ */
+function checkList(value, previous = []) {
+    const check = AUDIT_CHECKS.find((name) => name === value.trim().toLowerCase());
+    if (!check) {
+        throw new InvalidArgumentError(unknownAuditCheckMessage(value, findSimilar(value, [...AUDIT_CHECKS]), AUDIT_CHECKS));
+    }
+    return previous.includes(check) ? previous : [...previous, check];
+}
+/**
+ * Parse `--level`.
+ *
+ * @param value - Level
+ * @returns AA or AAA
+ * @throws InvalidArgumentError for another value
+ */
+function levelOption(value) {
+    const level = value.trim().toUpperCase();
+    if (level === 'AA' || level === 'AAA')
+        return level;
+    throw new InvalidArgumentError('Use AA or AAA');
+}
+/**
+ * Ask the daemon to audit the page.
+ *
+ * @param checks - Checks given (all when none)
+ * @param options - Level and limit
+ * @returns Command result
+ */
+async function audit(checks, options) {
+    const response = await domAudit({
+        checks: checks && checks.length > 0 ? checks : [...AUDIT_CHECKS],
+        ...(options.level && { level: options.level }),
+        ...(options.limit !== undefined && { limit: options.limit }),
+    });
+    if (response.status === 'error' || !response.data) {
+        return {
+            success: false,
+            error: response.error ?? 'Failed to audit the page',
+            exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
+            ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+        };
+    }
+    return { success: true, data: response.data };
+}
+//# sourceMappingURL=audit.js.map

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,

package/dist/commands/dom/formInteraction.js

@@ -10,14 +10,15 @@ import { InvalidArgumentError } from 'commander';
 import { runElementCommand } from './helpers/runElementCommand.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.js';
+import { createErrorResult } from '../shared/dataFetcher.js';
 import { integerOption } from '../shared/validation.js';
 import { CommandError } from '../../errors/index.js';
-import { VIA_LABEL_SUFFIX, conflictingOptionsMessage, indexSourceText, internalError, scrollOptionsError, } from '../../errors/messages.js';
-import { domClick, domFill, domPressKey, domScroll, domSubmit } from '../../ipc/client.js';
+import { VIA_LABEL_SUFFIX, conflictingOptionsError, hoverOffWithTargetError, missingArgumentError, indexSourceText, internalError, scrollOptionsError, } from '../../errors/messages.js';
+import { callCDP, domClick, domFill, domPressKey, domScroll, domSubmit } from '../../ipc/client.js';
 import { findUnknownModifiers } from '../../runtime/dom/keyMapping.js';
 import { formatTriggeredRequestLines, formatTriggeredRequestsTitle, } from '../../ui/formatters/triggeredRequests.js';
 import { OutputFormatter } from '../../ui/formatting.js';
-import { CLICK_RESULT_WAIT_HELP, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, actionStatusLine, dialogConsoleText, newMessageText, pageNavigationText, shownElementText, stillChangingNote, } from '../../ui/messages/commands.js';
+import { CLICK_RESULT_WAIT_HELP, HOVER_OFF_DONE, HOVER_USAGE, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, pointerScrollText, actionStatusLine, dialogConsoleText, moreMessagesText, newMessageText, pageNavigationText, shownElementText, stillChangingNote, } from '../../ui/messages/commands.js';
 import { sessionCommand } from '../../ui/messages/sessionCommand.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /** Help of `--strict` on click and hover */
@@ -96,13 +97,18 @@ export function registerFormInteractionCommands(program) {
     });
     domCommand
         .command('hover')
-        .description('Move the mouse over an element (shows hover menus and tooltips)')
-        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
+        .description('Move the mouse over an element (shows hover menus and tooltips); --off moves it off the page')
+        .argument('[selectorOrIndex]', SELECTOR_OR_INDEX_ARGUMENT)
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
+        .option('--off', 'Move the mouse off the page instead (closes menus that open on hover)')
         .option('--strict', STRICT_OPTION_HELP)
         .option('--no-wait', 'Skip waiting for network stability after hovering')
         .addOption(jsonOption())
         .action(async (selectorOrIndex, options) => {
+        if (options.off || selectorOrIndex === undefined) {
+            await hoverOff(selectorOrIndex, options);
+            return;
+        }
         await runPointerCommand(selectorOrIndex, options, 'hover');
     });
     domCommand
@@ -260,13 +266,32 @@ function scrollOptionsProblem(selector, options) {
  * @param options - Command options
  * @param action - Pointer action
  */
+/**
+ * `bdg dom hover --off`: move the mouse off the page, so `mouseleave` and
+ * `:hover` end and menus that open on hover close.
+ *
+ * @param selectorOrIndex - Must be absent with --off
+ * @param options - Command options
+ */
+async function hoverOff(selectorOrIndex, options) {
+    await runCommand(async () => {
+        if (!options.off || selectorOrIndex !== undefined || options.index !== undefined) {
+            const err = options.off ? hoverOffWithTargetError() : missingArgumentError(HOVER_USAGE);
+            return {
+                success: false,
+                error: err.message,
+                exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+                errorContext: { suggestion: err.suggestion },
+            };
+        }
+        await callCDP('Input.dispatchMouseEvent', { type: 'mouseMoved', x: -1, y: -1 });
+        return { success: true, data: { pointer: 'off' } };
+    }, options, () => HOVER_OFF_DONE);
+}
 async function runPointerCommand(selectorOrIndex, options, action) {
+    const conflict = conflictingOptionsError('--double', '--right');
     await runCommand(() => options.double && options.right
-        ? Promise.resolve({
-            success: false,
-            error: conflictingOptionsMessage('--double', '--right'),
-            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-        })
+        ? Promise.resolve(createErrorResult(conflict.message, EXIT_CODES.INVALID_ARGUMENTS, conflict.suggestion))
         : runElementCommand({
             selectorOrIndex,
             index: options.index,
@@ -316,7 +341,10 @@ function formatActionOutput(done, details, result, options = {}) {
     fmt.keyValueList(details, keyWidth);
     if (result.navigation)
         fmt.keyValue('Page', pageNavigationText(result.navigation), keyWidth);
-    listRows(fmt, 'New text', (result.messages ?? []).map(newMessageText), keyWidth);
+    listRows(fmt, 'New text', [
+        ...(result.messages ?? []).map(newMessageText),
+        ...(result.moreMessages ? [moreMessagesText(result.moreMessages)] : []),
+    ], keyWidth);
     listRows(fmt, 'Shown', (result.shown ?? []).map(shownElementText), keyWidth);
     const omitted = result.triggeredRequestsOmitted;
     const requests = formatTriggeredRequestLines(result.triggeredRequests ?? [], omitted);
@@ -400,6 +428,9 @@ function formatClickOutput(result) {
         ...selectorRows(result),
         elementRow(result),
         ['Method', result.method === 'dom' ? 'DOM events' : 'mouse events'],
+        ...(result.scrolledBy
+            ? [['Scrolled', pointerScrollText(result.scrolledBy)]]
+            : []),
     ], result, { action: POINTER_ACTION_NOUN[result.action ?? 'click'] }).build();
 }
 /**