browser-debugger-cli 0.9.0 → 0.11.0

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

@@ -0,0 +1,268 @@
+---
+name: bdg
+description: Use bdg CLI to drive and debug a real Chrome via Chrome DevTools Protocol - navigate, click, fill and submit forms, check what an action changed (navigation, new messages, pending requests), inspect elements without screenshots (box, layout, fonts, colors, a11y), read network requests and console errors, and call any CDP method. Use this skill when you need to verify a UI change in a running app, debug a page, automate a browser flow, or scrape dynamic content.
+---
+
+# bdg - Browser Automation CLI
+
+## Quick Start
+
+```bash
+bdg https://example.com          # Start session (launches Chrome)
+bdg dom screenshot /tmp/page.png # Take screenshot
+bdg stop                         # End session
+```
+
+## Session Management
+
+```bash
+bdg <url>                  # Start session (1920x1080, headless if no display)
+bdg <url> --headless       # Force headless mode
+bdg <url> --no-headless    # Force visible browser window
+bdg status                 # Check session status
+bdg peek                   # Preview collected telemetry
+bdg stop                   # End session (use sparingly)
+bdg cleanup                # Clean up after a crashed session
+bdg cleanup --force        # Kill a stuck session (daemon + its Chrome)
+```
+
+**Sessions run indefinitely by default** (no timeout). With HMR/hot-reload dev servers, keep the session running:
+
+```bash
+bdg http://localhost:5173      # Start once
+# ... make code changes, HMR updates the page ...
+bdg dom screenshot /tmp/s.png  # Check anytime
+bdg peek                       # Preview collected data
+# No need to stop/restart - Chrome stays on the page
+```
+
+**Don't stop sessions prematurely** - use `bdg peek` to inspect data. Only call `bdg stop` when completely done with browser automation.
+
+## Screenshots
+
+Always use `bdg dom screenshot` (raw CDP is blocked):
+
+```bash
+bdg dom screenshot /tmp/page.png                    # Full page
+bdg dom screenshot /tmp/viewport.png --no-full-page # Viewport only
+bdg dom screenshot /tmp/el.png --selector "#main"   # Element only
+bdg dom screenshot /tmp/scroll.png --scroll "#target" # Scroll to element first
+```
+
+## Actions Report What Changed
+
+`dom click`, `fill`, `submit`, `pressKey`, `hover` and `scroll` wait for the requests the action starts, then say what happened. Read this before reaching for a screenshot:
+
+```text
+✓ Element Clicked
+Page: navigated to https://app.test/secure (200)    # navigation (or "URL changed ... (same document)")
+New text: "Your password is invalid!" (div#flash)   # alert/status/aria-live messages that appeared
+⚠ Element Clicked (no visible effect observed ...)  # nothing changed - wrong element or a broken handler
+```
+
+- In `--json`: `navigation`, `messages`, `effect: "none"` and pending work (timers, spinners) are fields on `data`.
+- Results the page shows later are not waited for: follow up with `bdg dom wait` (below).
+
+## Form Interaction
+
+```bash
+# Discover forms
+bdg dom form --brief              # Quick scan: field names, types, required
+
+# Fill and interact
+bdg dom fill "input[name='user']" "myuser"    # Fill by selector
+bdg dom fill 0 "value"                         # Fill by index (from query)
+bdg dom click "button.submit"                  # Click element
+bdg dom submit "form" --wait-navigation        # Submit and wait for page load
+bdg dom pressKey "input" Enter                 # Press Enter key
+
+# Options
+--no-wait          # Skip network stability wait
+--wait-navigation  # Wait for page navigation (traditional forms)
+--wait-network <ms> # Wait for network idle (SPA forms)
+--index <n>        # Select nth element when multiple match
+```
+
+## DOM Inspection
+
+```bash
+bdg dom query "selector"     # Find elements, returns [0], [1], [2]... (0-based)
+bdg dom get "selector"       # Get semantic a11y info (token-efficient)
+bdg dom get "selector" --raw # Get full HTML
+bdg dom eval "js expression" # Run JavaScript
+bdg dom a11y "role:button"   # Query by accessibility role/name
+```
+
+Selectors search open shadow roots and same-origin iframes, and accept `:has-text("...")` and `:visible`.
+
+### 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 ".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)
+bdg page emulate --viewport 390x844 --color-scheme dark   # Responsive/theme check mid-session
+```
+
+### Wait for Something
+
+```bash
+bdg dom wait '#result' --visible       # Appears and is visible
+bdg dom wait '.toast' --text 'Saved'   # Contains text
+bdg dom wait '#loading' --gone         # Spinner went away
+bdg dom wait --load                    # Page finished loading
+```
+
+## Network and Console
+
+```bash
+bdg network list                              # Requests (DevTools-style)
+bdg network list --filter "status-code:>=400" # Failed requests
+bdg details network <id>                      # Headers, timing, body of one request
+bdg console --level error                     # Console errors on the current page
+bdg console --follow                          # Stream messages live
+bdg network har /tmp/session.har              # Export HAR 1.2
+```
+
+## CDP Access
+
+Direct access to Chrome DevTools Protocol:
+
+```bash
+# Execute any CDP method
+bdg cdp Runtime.evaluate --params '{"expression": "document.title", "returnByValue": true}'
+bdg cdp Page.navigate --params '{"url": "https://example.com"}'
+bdg cdp Page.reload --params '{"ignoreCache": true}'
+
+# Discovery
+bdg cdp --list                    # List all domains
+bdg cdp Network --list            # List methods in domain
+bdg cdp Network.getCookies --describe  # Show method schema
+bdg cdp --search cookie           # Search methods
+```
+
+**Important**: Always use `returnByValue: true` for Runtime.evaluate to get serialized values.
+
+## Common Patterns
+
+### Login Flow
+```bash
+bdg https://example.com/login
+bdg dom form --brief
+bdg dom fill "input[name='username']" "$USER"
+bdg dom fill "input[name='password']" "$PASS"
+bdg dom submit "button[type='submit']" --wait-navigation
+bdg dom screenshot /tmp/result.png
+bdg stop
+```
+
+### Verify a UI Change (dev server with HMR)
+```bash
+bdg http://localhost:5173                 # Once; keep the session running
+bdg dom click "button.save"               # Read the reported effect
+bdg dom wait '.toast' --text 'Saved'
+bdg console --level error                 # Anything thrown?
+bdg dom inspect ".toast"                  # Looks right? (no screenshot needed)
+```
+
+### Extract Data
+```bash
+bdg cdp Runtime.evaluate --params '{
+  "expression": "Array.from(document.querySelectorAll(\"a\")).map(a => ({text: a.textContent, href: a.href}))",
+  "returnByValue": true
+}' | jq '.data.result.result.value'
+```
+
+## 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.
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 0 | Success | - |
+| 81 | Invalid arguments (incl. blocked raw CDP methods) | Read the suggestion, use the alternative |
+| 83 | Resource not found | Element/session doesn't exist |
+| 85 | Session busy (still starting/stopping) | Retry shortly |
+| 87 | Stale index (page changed since `dom query`) | Re-run the query |
+| 91 | `dom eval` script threw | Fix the JavaScript |
+| 101 | CDP connection failure | Run `bdg cleanup --force` and retry |
+| 102 | Timeout (CDP, or `dom wait --timeout`) | Increase timeout or check page load |
+
+## Troubleshooting
+
+```bash
+bdg status --verbose      # Full diagnostics
+bdg cleanup               # Clean up after a crashed session
+bdg cleanup --force       # Kill a stuck session (daemon + its Chrome)
+```
+
+**Chrome won't launch?** Run `bdg cleanup --force` then retry.
+
+**Session stuck?** Run `bdg cleanup --force` to reset.
+
+### Custom Chrome Flags
+
+Use `--chrome-flags` or `BDG_CHROME_FLAGS` for self-signed certificates, CORS, etc.:
+
+```bash
+# CLI option
+bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"
+
+# Environment variable
+BDG_CHROME_FLAGS="--ignore-certificate-errors" bdg https://localhost:5173
+
+# Multiple flags
+bdg https://example.com --chrome-flags="--ignore-certificate-errors --disable-web-security"
+```
+
+**Common flags for development:**
+- `--ignore-certificate-errors` - Self-signed SSL certs
+- `--disable-web-security` - CORS issues in development
+- `--allow-insecure-localhost` - Insecure localhost
+- `--disable-features=IsolateOrigins,site-per-process` - Cross-origin iframes
+
+## Verification Best Practices
+
+**Prefer DOM queries over screenshots** for verification:
+
+```bash
+# GOOD: Fast, precise, scriptable
+bdg cdp Runtime.evaluate --params '{
+  "expression": "document.querySelector(\".error-message\")?.textContent",
+  "returnByValue": true
+}'
+
+# GOOD: Check element exists
+bdg dom query ".submit-btn"
+
+# GOOD: Check text content
+bdg cdp Runtime.evaluate --params '{
+  "expression": "document.body.innerText.includes(\"Success\")",
+  "returnByValue": true
+}'
+
+# AVOID: Screenshots for simple verification (slow, requires visual inspection)
+bdg dom screenshot /tmp/check.png  # Only use when you need visual proof
+```
+
+**When to use screenshots:**
+- Visual regression testing
+- Capturing proof for user review
+- Debugging layout issues
+- When DOM structure is unknown
+
+**When to use DOM queries:**
+- Verifying text content appeared
+- Checking element exists/visible
+- Validating form state
+- Counting elements
+- Any programmatic assertion
+
+## When NOT to Use bdg
+
+- **Static HTML** - Use `curl` + `htmlq`/`pq`
+- **API calls** - Use `curl` + `jq`
+- **Simple HTTP** - Use `wget`/`curl`
+
+Use bdg when you need: JavaScript execution, dynamic content, browser APIs, screenshots, or network manipulation.

package/README.md

@@ -43,6 +43,17 @@ npm install -g browser-debugger-cli
 - ✅ Windows via WSL
 - ❌ PowerShell/Git Bash (not yet)
 
+## Use with Claude Code and Other Agents
+
+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.
+
+```bash
+bdg install-skill            # ~/.claude/skills/bdg (Claude Code) + ~/.agents/skills/bdg (Codex, Gemini CLI, ...)
+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`.
+
 ## Quick Start
 
 ```bash
@@ -59,6 +70,9 @@ bdg eval "document.title"          # Run JavaScript in the page (--frame for ifr
 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
@@ -66,7 +80,7 @@ bdg stop                           # End session
 
 ## Current State
 
-**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, 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.
+**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.
 
 ## Agent Discovery Pattern
 

package/dist/commands/dom/a11y.js

@@ -10,6 +10,7 @@
  */
 import { DomElementResolver } from './DomElementResolver.js';
 import { getDomContext, resolveBackendNodeIds } from './helpers/index.js';
+import { withSecretMasked } from './semanticUtils.js';
 import { runCommand, runJsonCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
 import { integerOption } from '../shared/validation.js';
@@ -164,7 +165,7 @@ async function handleA11yDescribe(selectorOrIndex, options) {
         if (domNodeId) {
             domContext = await getDomContext({ backendNodeId: domNodeId });
         }
-        return { node, domContext };
+        return { node: withSecretMasked(node, domContext), domContext };
     }
     if (options.json) {
         await runJsonCommand(fetchA11yNodeData);

package/dist/commands/dom/formInteraction.js

@@ -9,7 +9,7 @@
 import { InvalidArgumentError } from 'commander';
 import { runElementCommand } from './helpers/runElementCommand.js';
 import { runCommand } from '../shared/CommandRunner.js';
-import { jsonOption } from '../shared/commonOptions.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';
@@ -17,9 +17,11 @@ import { domClick, domFill, domPressKey, domScroll, domSubmit } from '../../ipc/
 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, actionStatusLine, dialogConsoleText, newMessageText, pageNavigationText, } from '../../ui/messages/commands.js';
+import { CLICK_RESULT_WAIT_HELP, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, actionStatusLine, dialogConsoleText, 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 */
+const STRICT_OPTION_HELP = 'Fail (exit 90) instead of using DOM events when a real mouse cannot reach the element (covered, hidden, zero-size)';
 /**
  * Commander parser for `--modifiers`: rejects unknown names instead of
  * silently pressing the bare key.
@@ -54,7 +56,7 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('fill')
         .description('Fill a form field with a value (React-compatible, waits for stability)')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .argument('<value>', 'Value to fill (file inputs: paths separated by commas, "" clears)')
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--no-blur', 'Do not blur after filling (keeps focus on element)')
@@ -80,10 +82,11 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('click')
         .description('Click an element and wait for stability (accepts selector or index)')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--double', 'Double-click')
         .option('--right', 'Right-click (opens the context menu)')
+        .option('--strict', STRICT_OPTION_HELP)
         .option('--no-wait', 'Skip waiting for network stability after click')
         .addOption(jsonOption())
         .addHelpText('after', CLICK_RESULT_WAIT_HELP)
@@ -94,8 +97,9 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('hover')
         .description('Move the mouse over an element (shows hover menus and tooltips)')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
+        .option('--strict', STRICT_OPTION_HELP)
         .option('--no-wait', 'Skip waiting for network stability after hovering')
         .addOption(jsonOption())
         .action(async (selectorOrIndex, options) => {
@@ -104,7 +108,7 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('submit')
         .description('Submit a form by clicking submit button and waiting for completion')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--wait-navigation', 'Wait for page navigation after submit')
         .option('--wait-network <ms>', 'Wait for network idle after submit (milliseconds)', integerOption(0), 1000)
@@ -132,7 +136,7 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('pressKey')
         .description('Press a key on an element (for Enter-to-submit, keyboard navigation)')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .argument('<key>', 'Key to press (Enter, Tab, Escape, Space, ArrowUp, etc.)')
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--times <n>', 'Press key multiple times (default: 1)', integerOption(1, 1000))
@@ -270,6 +274,7 @@ async function runPointerCommand(selectorOrIndex, options, action) {
                 ...target,
                 wait: options.wait !== false,
                 ...(action !== 'click' && { action }),
+                ...(options.strict && { strict: true }),
             }),
             call: domClick,
             command: action === 'hover' ? 'hover' : 'click',
@@ -279,34 +284,40 @@ async function runPointerCommand(selectorOrIndex, options, action) {
 }
 /**
  * Build an action's output: the status line ("✓ Element Clicked",
- * "⚠ Element Clicked (with warnings)" with the warning right below it, or
- * "⚠ Element Clicked (no visible effect: …)"), the details, what changed on
- * the page (`Page:` navigation, `New text:` messages), then the network
- * requests it triggered and the dialogs it caused. No request list is shown
- * when there were none (JSON has an empty `triggeredRequests` then).
+ * "⚠ Element Clicked (with warnings)" with the warning right below it,
+ * "⚠ Element Clicked (page still changing)" with what it was still working
+ * on, or "⚠ Element Clicked (no visible effect: …)"), the details, what
+ * changed on the page (`Page:` navigation, `New text:` messages, `Shown:`
+ * elements), then the network requests it triggered and the dialogs it
+ * caused. No request list is shown when there were none (JSON has an empty
+ * `triggeredRequests` then).
  *
  * @param done - What was done, e.g. "Element Clicked"
  * @param details - Label/value rows
  * @param result - Action result
- * @param keyWidth - Width of the labels
+ * @param options - Width of the labels; what the action is called in notes (e.g. "click")
  * @returns Output being built (more can be appended)
  */
-function formatActionOutput(done, details, result, keyWidth = 15) {
+function formatActionOutput(done, details, result, options = {}) {
+    const keyWidth = options.keyWidth ?? 15;
     const fmt = new OutputFormatter();
-    fmt.text(actionStatusLine(done, result.warning !== undefined, result.effect === 'none'));
+    const stillChanging = result.settled === false && result.pending !== undefined;
+    fmt.text(actionStatusLine(done, {
+        warned: result.warning !== undefined,
+        noEffect: result.effect === 'none',
+        stillChanging,
+    }));
     if (result.warning)
         fmt.text(`⚠ Warning: ${result.warning}`);
+    if (stillChanging && result.pending) {
+        fmt.text(`⚠ ${stillChangingNote(options.action ?? 'action', result.pending)}`);
+    }
     fmt.blank();
     fmt.keyValueList(details, keyWidth);
     if (result.navigation)
         fmt.keyValue('Page', pageNavigationText(result.navigation), keyWidth);
-    (result.messages ?? []).forEach((message, index) => {
-        const text = newMessageText(message);
-        if (index === 0)
-            fmt.keyValue('New text', text, keyWidth);
-        else
-            fmt.text(' '.repeat(keyWidth) + text);
-    });
+    listRows(fmt, 'New text', (result.messages ?? []).map(newMessageText), keyWidth);
+    listRows(fmt, 'Shown', (result.shown ?? []).map(shownElementText), keyWidth);
     const omitted = result.triggeredRequestsOmitted;
     const requests = formatTriggeredRequestLines(result.triggeredRequests ?? [], omitted);
     if (requests.length > 0) {
@@ -320,6 +331,23 @@ function formatActionOutput(done, details, result, keyWidth = 15) {
     }
     return fmt;
 }
+/**
+ * Rows of a list under one label: the label on the first row, the rest
+ * indented below it.
+ *
+ * @param fmt - Output being built
+ * @param label - Label, e.g. "New text"
+ * @param texts - One text per row
+ * @param keyWidth - Width of the labels
+ */
+function listRows(fmt, label, texts, keyWidth) {
+    texts.forEach((text, index) => {
+        if (index === 0)
+            fmt.keyValue(label, text, keyWidth);
+        else
+            fmt.text(' '.repeat(keyWidth) + text);
+    });
+}
 /**
  * Row naming the element an action hit, e.g.
  * `Element: input.toggle in div.view "Write report"` (just its tag when the
@@ -372,7 +400,7 @@ function formatClickOutput(result) {
         ...selectorRows(result),
         elementRow(result),
         ['Method', result.method === 'dom' ? 'DOM events' : 'mouse events'],
-    ], result).build();
+    ], result, { action: POINTER_ACTION_NOUN[result.action ?? 'click'] }).build();
 }
 /**
  * Format submit command output for human-readable display.
@@ -391,7 +419,10 @@ function formatSubmitOutput(result) {
         details.push(['Navigation', 'yes']);
     if (result.waitTimeMs !== undefined)
         details.push(['Wait Time', `${result.waitTimeMs}ms`]);
-    const fmt = formatActionOutput('Form Submitted', details, result, 20);
+    const fmt = formatActionOutput('Form Submitted', details, result, {
+        keyWidth: 20,
+        action: 'submit',
+    });
     fmt.hints('Next steps:', [
         `${sessionCommand('bdg network list --last 10').padEnd(32)} Check network requests`,
         `${sessionCommand('bdg console --last 5').padEnd(32)} Check console messages`,
@@ -412,7 +443,7 @@ function formatPressKeyOutput(result) {
         details.push(['Times', result.times.toString()]);
     if (result.modifiers?.length)
         details.push(['Modifiers', result.modifiers.join('+')]);
-    return formatActionOutput('Key Pressed', details, result).build();
+    return formatActionOutput('Key Pressed', details, result, { action: 'key press' }).build();
 }
 /**
  * Format scroll command output for human-readable display.

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

@@ -0,0 +1,20 @@
+/**
+ * The attributes that identify an element by its type (an image's `src`, a
+ * link's `href`, a field's name and value), shown by `dom query`, `dom get`
+ * and `dom a11y describe`.
+ */
+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
+ * (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.
+ *
+ * @param tag - Lower-case tag name
+ * @param attributes - Element attributes
+ * @param state - Live state read in the page (`ELEMENT_STATE_JS`)
+ * @returns Key attributes, or undefined for an element type without any
+ */
+export declare function keyAttributes(tag: string, attributes: Record<string, string>, state?: ElementState): KeyAttributes | undefined;
+//# sourceMappingURL=keyAttributes.d.ts.map

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

@@ -0,0 +1,54 @@
+/**
+ * The attributes that identify an element by its type (an image's `src`, a
+ * link's `href`, a field's name and value), shown by `dom query`, `dom get`
+ * and `dom a11y describe`.
+ */
+import { MASKED_VALUE } from '../../../runtime/dom/elementInfo.js';
+/** Attributes read for each element type (live state is added for form controls) */
+const ATTRIBUTES_BY_TAG = {
+    img: ['src', 'alt'],
+    a: ['href'],
+    input: ['name', 'placeholder'],
+    textarea: ['name', 'placeholder'],
+    button: ['name'],
+    select: ['name'],
+    iframe: ['src'],
+    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
+ * (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.
+ *
+ * @param tag - Lower-case tag name
+ * @param attributes - Element attributes
+ * @param state - Live state read in the page (`ELEMENT_STATE_JS`)
+ * @returns Key attributes, or undefined for an element type without any
+ */
+export function keyAttributes(tag, attributes, state = {}) {
+    const names = ATTRIBUTES_BY_TAG[tag];
+    if (!names)
+        return undefined;
+    const result = {};
+    const type = state.type ?? attributes['type'];
+    if (type)
+        result['type'] = type;
+    for (const name of names) {
+        const value = attributes[name];
+        if (value)
+            result[name] = value;
+    }
+    if (type === 'hidden')
+        return result;
+    const secret = state.sensitive === true || type === 'password';
+    if (state.value)
+        result['value'] = secret ? MASKED_VALUE : state.value;
+    if (state.checked !== undefined)
+        result['checked'] = state.checked;
+    if (state.selected)
+        result['selected'] = secret ? MASKED_VALUE : state.selected;
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+//# sourceMappingURL=keyAttributes.js.map

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

@@ -46,7 +46,7 @@ export declare function documentReadyState(): Promise<string | undefined>;
  */
 export declare function queryDOMElements(selector: string): Promise<DomQueryResult>;
 /**
- * Get DOM context (tag, classes, text preview) for a node: a one-line
+ * Get DOM context (tag, classes, key attributes, text preview) for a node: a one-line
  * preview, and up to {@link ELEMENT_TEXT_LENGTH} characters of text when it
  * is longer (all of it with `full`).
  *