browser-debugger-cli 0.11.0 → 0.12.0

package/README.md

@@ -1,127 +1,190 @@
-# Browser Debugger CLI
+# bdg - Browser Debugger CLI
 
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/szymdzum/browser-debugger-cli/pulls)
+[![npm downloads](https://img.shields.io/npm/dt/browser-debugger-cli?color=blue)](https://www.npmjs.com/package/browser-debugger-cli)
 [![CI](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/ci.yml)
 [![Security](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/security.yml/badge.svg)](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/security.yml)
-[![npm downloads](https://img.shields.io/npm/dt/browser-debugger-cli?color=blue)](https://www.npmjs.com/package/browser-debugger-cli)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/szymdzum/browser-debugger-cli/pulls)
 
-Chrome DevTools Protocol in your terminal. Opens a persistent connection to Chrome where commands can be executed sequentially via Unix pipes. **Designed for AI agents** and developers who want direct browser control without framework overhead.
+**Give your AI agent a real browser. And the DevTools to go with it.**
 
-## Why bdg?
+📖 **[Wiki](https://github.com/szymdzum/browser-debugger-cli/wiki)**: [Getting Started](https://github.com/szymdzum/browser-debugger-cli/wiki/Getting-Started) · [Commands](https://github.com/szymdzum/browser-debugger-cli/wiki/Commands) · [For AI Agents](https://github.com/szymdzum/browser-debugger-cli/wiki/For-AI-Agents) · [Recipes](https://github.com/szymdzum/browser-debugger-cli/wiki/Recipes) · [Quick Reference](https://github.com/szymdzum/browser-debugger-cli/wiki/Quick-Reference) · [Troubleshooting](https://github.com/szymdzum/browser-debugger-cli/wiki/Troubleshooting) · [CLI reference](docs/CLI_REFERENCE.md)
 
-- **Raw CDP access** - Every [protocol method](https://chromedevtools.github.io/devtools-protocol/) available directly
-- **Token efficient** - No overhead from MCP tool definitions; progressive discovery loads only what's needed
-- **Self-correcting** - Errors clearly exposed with semantic exit codes and suggestions
-- **Composable** - Unix philosophy: pipes, jq, shell scripts work naturally
+bdg keeps a browser session open in the background and lets you drive it one shell command at a time. Click, fill, navigate, then read what actually happened: requests, console errors, layout and styles. It is built for coding agents like Claude Code, Codex and Gemini CLI, and it's just as handy in your own terminal. Every command is a plain process with compact output, so it pipes into `jq` and costs an agent few tokens.
 
-**When to use alternatives:**
-- **Puppeteer/Playwright**: Complex multi-step scripts, mature testing ecosystem
-- **Chrome DevTools MCP**: Already invested in MCP infrastructure
+```bash
+npm install -g browser-debugger-cli
+bdg localhost:3000
+```
 
-**Built for agents:** Self-discovery (`--list`, `--search`), semantic exit codes, structured errors, case-insensitive commands, token-efficient output.
+## Two ways to use it
 
-## Benchmark: CLI vs MCP for AI Agents
+### Debug a page: browser telemetry on demand
 
-We benchmarked bdg against Chrome DevTools MCP Server on real developer debugging tasks.
+![The cart button does nothing; bdg shows the 500 response, the console error and the missing cookie](https://raw.githubusercontent.com/szymdzum/browser-debugger-cli/main/docs/assets/demo-debug.gif)
 
+The cart button does nothing, and the page doesn't say why. Three commands later the agent knows: the click fired a POST that returned 500, the console says the `cart_id` cookie is missing, and the cookie jar confirms it. Network, console, cookies and the DOM are there whenever the agent asks, without a debugger UI.
 
-**[Full benchmark analysis →](docs/benchmarks/ARTICLE_MCP_VS_CLI_FOR_AGENTS.md)**
+### Automate without writing a script
 
-**Key findings:** CLI provided 33% better token efficiency through selective queries vs full accessibility tree dumps, plus capabilities MCP doesn't expose (memory profiling, HAR export, batch JS execution).
+![An agent fills a form, clicks Subscribe, reads the confirmation and inspects the button](https://raw.githubusercontent.com/szymdzum/browser-debugger-cli/main/docs/assets/demo-automate.gif)
 
+No Playwright script written up front. The agent runs one command, reads what the browser reports back, and picks the next step from that: the click says which text appeared, `dom inspect` says what the button looks like. When the page does something unexpected, the agent adapts on the spot instead of failing at line 40 of a test.
 
-## Install
+## More examples
+
+### Reuse the browser's login from the shell
+
+```console
+$ bdg network getCookies
+[1] session_id
+  Value: s%3A9f8e7d6c
+  HttpOnly: Yes
+  SameSite: Lax
+
+$ bdg network headers 89565.2 --header authorization
+Request Headers:
+  Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZGEifQ.demo
+
+$ bdg eval "localStorage.getItem('access_token')"
+eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZGEifQ.demo
+```
+
+`HttpOnly` cookies are included, even though the page's own JavaScript can't read them. Log in once in the browser, then reuse the session from the shell:
 
 ```bash
-npm install -g browser-debugger-cli
+COOKIES=$(bdg network getCookies --json | jq -r '[.data[] | "\(.name)=\(.value)"] | join("; ")')
+curl -H "Cookie: $COOKIES" localhost:3000/api/me
+```
+
+### The rest of DevTools
+
+```console
+$ bdg dom a11y tree
+[RootWebArea] "My App" (focused)
+  [Heading] "My App"
+  [Button] "Sign in" (focusable)
+  [Image]                                         ← no accessible name
+
+$ bdg cdp Performance.enable
+$ bdg cdp Performance.getMetrics --json | jq '.data.result.metrics | from_entries'
+{ "Nodes": 51, "LayoutDuration": 0.000115, "ScriptDuration": 0.000775, "JSHeapUsedSize": 772124, ... }
+
+$ bdg cdp Emulation.setCPUThrottlingRate --params '{"rate":4}'    # Slow CPU
+$ bdg cdp Network.emulateNetworkConditions --params '{"offline":false,"latency":400,"downloadThroughput":50000,"uploadThroughput":20000}'
+```
+
+Accessibility, performance metrics, CPU profiling, heap snapshots, code coverage, throttling, storage, service workers: everything Chrome DevTools can do, bdg can do too, through raw CDP. Can't find the method you need? `bdg cdp --search heap`.
+
+## Agents learn it on their own
+
+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 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
 ```
 
-**Requirements:** Node.js 22.12+ and Chrome (or Chromium).
+And when it gets something wrong, bdg tells it what it meant:
+
+```console
+$ bdg dom clik "a"
+error: unknown command 'clik'
+(Did you mean click?)
+
+$ bdg cdp Network.getCookie
+  "error": "Method 'Network.getCookie' not found",
+  "suggestion": "... Did you mean: Network.getCookies, Network.setCookie, Network.setCookies"
+```
+
+Each mistake exits with code 81 (invalid arguments), so the agent knows to fix the call rather than retry it. CDP method names are case-insensitive, and raw CDP calls point to the friendlier command when one exists. More in the [Agent-Friendly Tools](docs/principles/AGENT_FRIENDLY_TOOLS.md) principles bdg follows.
+
+## Benchmark: CLI vs MCP
+
+We gave an AI agent five real debugging tasks, from a single JS error up to a memory leak, and ran each one with bdg and with the official Chrome DevTools MCP server (November 2025).
 
-**Platform Support:**
-- ✅ macOS and Linux
-- ✅ Windows via WSL
-- ❌ PowerShell/Git Bash (not yet)
+| | bdg | Chrome DevTools MCP |
+|---|---|---|
+| **Score** | **77 / 100** | 60 / 100 |
+| **Token efficiency** | **202** | 152 |
+| Tokens used | ~38.1K | ~39.4K |
 
-## Use with Claude Code and Other Agents
+bdg scored 17 points higher on about the same token budget, so its token efficiency was 33% better. Part of the gap is reach: memory profiling, HAR export and batch JS execution have no MCP equivalent. [Read the full analysis →](docs/benchmarks/ARTICLE_MCP_VS_CLI_FOR_AGENTS.md)
 
-bdg ships an agent skill (`SKILL.md`) that teaches the workflow: start once, act, read what the action changed, inspect without screenshots, check network and console.
+## Use it with your agent
+
+bdg ships an agent skill that teaches the workflow: start once, act, read what changed, inspect without screenshots, check network and console.
 
 ```bash
-bdg install-skill            # ~/.claude/skills/bdg (Claude Code) + ~/.agents/skills/bdg (Codex, Gemini CLI, ...)
+bdg install-skill            # Claude Code (~/.claude/skills) + Codex, Gemini CLI, ... (~/.agents/skills)
 bdg install-skill --claude   # Claude Code only
 ```
 
-Start a new agent session afterwards, and re-run `bdg install-skill` after upgrading bdg. In Claude Code the skill loads when a task needs a browser, or on demand with `/bdg`.
+Start a new agent session afterwards. In Claude Code the skill loads when a task needs a browser, or on demand with `/bdg`. Re-run `bdg install-skill` after upgrading bdg.
 
-## Quick Start
+## Quick start
 
 ```bash
-bdg example.com                    # Start session
-bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"  # Self-signed certs
-bdg https://localhost:5173 --chrome-flags="--disable-web-security"       # Disable CORS
-bdg cdp --search cookie            # Discover commands
-bdg cdp Network.getCookies         # Run any CDP method
-bdg dom query "button"             # High-level helpers
-bdg dom fill 'input[name="q"]' "shoes"
+bdg example.com                              # Start a session (the browser stays open)
+bdg dom fill 'input[name="q"]' "shoes"       # Interact
 bdg dom click 'button:has-text("Search")'
-bdg page navigate example.com/about
-bdg eval "document.title"          # Run JavaScript in the page (--frame for iframes)
-bdg network list --preset errors   # Network requests, console: bdg console
-bdg dom listeners "#save"          # Which event listeners run for an element
-bdg dom layout "#save"             # Where it is, whether it is visible or covered
-bdg dom inspect "#save"            # What it looks like (Figma-like styles), no screenshot
-bdg dom inspect "#save" --why color   # Which CSS rule sets a value, and what it beats
-bdg page emulate --viewport 900x700   # Responsive check mid-session (or --color-scheme)
-bdg dom wait "#result" --visible   # Wait for an element instead of sleeping
-bdg example.com --session agent2 --viewport 1280x800   # A second, independent session
-bdg stop                           # End session
+bdg dom wait "#result" --visible             # Wait for an element instead of sleeping
+bdg network list --preset errors             # Failed requests
+bdg console                                  # Console messages
+bdg dom layout "#save"                       # Where is it? Visible? Covered?
+bdg dom inspect "#save" --why color          # Which CSS rule sets the color
+bdg dom audit contrast                       # Page-wide: text below WCAG AA, weakest first
+bdg css search -- --brand                    # Where a token is set, in every stylesheet
+bdg dom listeners "#save"                    # Which event listeners run
+bdg page emulate --viewport 900x700          # Responsive check mid-session (--mobile for a phone)
+bdg eval "document.title"                    # Run JavaScript (--frame for iframes)
+bdg cdp Network.getCookies                   # Any CDP method
+bdg stop                                     # End the session
 ```
 
-## Current State
+Local dev servers with self-signed certificates: `bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"`. Need parallel sessions? `bdg example.com --session agent2`.
 
-**Raw CDP access is complete.** Every protocol method works now. High-level commands cover the common work: page navigation, DOM queries and interaction (click, fill, hover, keys, forms, shadow DOM and iframes), accessibility tree, screenshots, element styles with the CSS cascade (`dom inspect`: what an element looks like, which rule sets each value, and declarations that have no effect), network requests and HAR export, console messages and event listeners. Actions report what they changed (navigation, new messages, requests, or no visible effect), and several named sessions can run side by side. See the [CLI reference](docs/CLI_REFERENCE.md) for every command, and `bdg --help --json` for the machine-readable version.
+## What it covers
 
-## Agent Discovery Pattern
+| Area | Commands |
+|---|---|
+| **Page** | navigate, reload, back/forward, viewport, phone (`--mobile`) and color-scheme emulation |
+| **Interaction** | click (double, right), fill (React-compatible, file inputs), hover, keys, forms, scroll, wait; shadow DOM and iframes included |
+| **Inspection** | element styles with the CSS cascade, layout and visibility, page-wide audits (contrast, overflow, layers, animations), stylesheet search, accessibility tree, event listeners, screenshots |
+| **Telemetry** | network requests and headers (incl. `Authorization`), HAR export, cookies (incl. `HttpOnly`), console messages, live `peek --follow` |
+| **Accessibility** | accessibility tree, semantic queries (`role:button name:Submit`), contrast checks |
+| **Performance** | metrics, CPU and heap profiling, tracing, CPU and network throttling (raw CDP) |
+| **Sessions** | several named sessions side by side, or attach to a browser you already have open (`--chrome-ws-url`) |
+| **Everything else** | raw CDP: `bdg cdp --list`, `--search`, `--describe` |
 
-```bash
-# Agent explores what's possible (no docs needed)
-bdg cdp --list                              # All domains
-bdg cdp Network --list                      # Methods in one domain
-bdg cdp Network.getCookies --describe       # Full schema + examples
-bdg cdp Network.getCookies                  # Execute
-
-# Search across all domains
-bdg cdp --search screenshot                 # Find relevant methods
-bdg cdp --search cookie                     # methods mentioning cookies
-```
+The [CLI reference](docs/CLI_REFERENCE.md) documents every command. `bdg --help --json` gives agents the machine-readable version.
+
+## Install
 
-## Documentation
+**Requirements:** Node.js 22.12+ and a Chromium-based browser: Chrome, Chromium or Microsoft Edge.
 
-📖 **[Wiki](https://github.com/szymdzum/browser-debugger-cli/wiki)** - Guides, command reference, recipes
+**Platforms:** macOS, Linux and Windows via WSL. Native PowerShell and Git Bash are not supported yet.
 
-- [Getting Started](https://github.com/szymdzum/browser-debugger-cli/wiki/Getting-Started)
-- [Commands](https://github.com/szymdzum/browser-debugger-cli/wiki/Commands)
-- [For AI Agents](https://github.com/szymdzum/browser-debugger-cli/wiki/For-AI-Agents)
-- [Recipes](https://github.com/szymdzum/browser-debugger-cli/wiki/Recipes)
-- [Quick Reference](https://github.com/szymdzum/browser-debugger-cli/wiki/Quick-Reference)
-- [Architecture](https://github.com/szymdzum/browser-debugger-cli/wiki/Architecture)
-- [Troubleshooting](https://github.com/szymdzum/browser-debugger-cli/wiki/Troubleshooting)
+**Browsers:** bdg launches Chrome by default. To use Edge, point `CHROME_PATH` at its binary, or attach to an Edge you started with `--remote-debugging-port`:
 
-## Design Principles
+```bash
+CHROME_PATH="/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" bdg example.com   # macOS
+CHROME_PATH=/usr/bin/microsoft-edge bdg example.com                                         # Linux
+bdg example.com --chrome-ws-url 9222                                                        # Attach to a running browser
+```
 
-This tool implements [Agent-Friendly Tools](docs/principles/AGENT_FRIENDLY_TOOLS.md):
+Firefox and Safari are not supported: bdg speaks the Chrome DevTools Protocol, which they do not implement.
 
-- **Self-documenting** - Tools teach themselves via `--list`, `--describe`
-- **Semantic exit codes** - Machine-parseable error handling
-- **Structured output** - JSON by default, human-readable optional
-- **Progressive disclosure** - Simple commands, deep capabilities
+## When to use something else
 
-## Contributing
+- **Playwright / Puppeteer**: long scripted test suites and a mature testing ecosystem.
+- **Chrome DevTools MCP**: if your setup is already built around MCP servers.
 
-[Issues](https://github.com/szymdzum/browser-debugger-cli/issues) for bugs, [Discussions](https://github.com/szymdzum/browser-debugger-cli/discussions) for ideas. PRs welcome.
+bdg is for when an agent or a developer needs to poke at a live page, step by step, and understand what is going on.
+
+## Contributing
 
-See `docs/` for architecture and contributor guides.
+[Issues](https://github.com/szymdzum/browser-debugger-cli/issues) for bugs, [Discussions](https://github.com/szymdzum/browser-debugger-cli/discussions) for ideas. PRs welcome. See the [Architecture](https://github.com/szymdzum/browser-debugger-cli/wiki/Architecture) page and `docs/` for contributor guides.
 
 ## License
 

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/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/formInteraction.js

@@ -12,12 +12,12 @@ import { runCommand } from '../shared/CommandRunner.js';
 import { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.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, conflictingOptionsMessage, 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, 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 +96,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,6 +265,28 @@ 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) {
     await runCommand(() => options.double && options.right
         ? Promise.resolve({
@@ -316,7 +343,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);

package/dist/commands/dom/helpers/keyAttributes.d.ts

@@ -5,8 +5,9 @@
  */
 import type { ElementState, KeyAttributes } from '../../../types.js';
 /**
- * The key attributes of an element: the identifying attributes of its type
- * that are set (empty ones left out) and the live state of a form control
+ * The key attributes of an element: its shadow `part` name (how a page's CSS
+ * reaches it with `::part()`), the identifying attributes of its type that
+ * are set (empty ones left out) and the live state of a form control
  * (type, current value, checked, selected options). Values arrive masked
  * from the page (`ELEMENT_STATE_JS`); a hidden input's value is never read,
  * and a sensitive field's value is masked here again in case it was not.

package/dist/commands/dom/helpers/keyAttributes.js

@@ -16,8 +16,9 @@ const ATTRIBUTES_BY_TAG = {
     form: ['action', 'method'],
 };
 /**
- * The key attributes of an element: the identifying attributes of its type
- * that are set (empty ones left out) and the live state of a form control
+ * The key attributes of an element: its shadow `part` name (how a page's CSS
+ * reaches it with `::part()`), the identifying attributes of its type that
+ * are set (empty ones left out) and the live state of a form control
  * (type, current value, checked, selected options). Values arrive masked
  * from the page (`ELEMENT_STATE_JS`); a hidden input's value is never read,
  * and a sensitive field's value is masked here again in case it was not.
@@ -29,9 +30,10 @@ const ATTRIBUTES_BY_TAG = {
  */
 export function keyAttributes(tag, attributes, state = {}) {
     const names = ATTRIBUTES_BY_TAG[tag];
+    const part = attributes['part'];
     if (!names)
-        return undefined;
-    const result = {};
+        return part ? { part } : undefined;
+    const result = part ? { part } : {};
     const type = state.type ?? attributes['type'];
     if (type)
         result['type'] = type;

package/dist/commands/dom/helpers/screenshot.d.ts

@@ -29,5 +29,6 @@ export declare function captureElementScreenshot(outputPath: string, ref: NodeRe
     format?: 'png' | 'jpeg';
     quality?: number;
     noResize?: boolean;
+    padding?: number;
 }): Promise<ScreenshotResult>;
 //# sourceMappingURL=screenshot.d.ts.map