browser-debugger-cli 0.11.0 → 0.13.0

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

@@ -9,7 +9,7 @@ import { writeOutputFile } from '../../shared/outputFile.js';
 import { CDPConnectionError } from '../../../connection/errors.js';
 import { CommandError } from '../../../errors/index.js';
 import { noNodesFoundError, elementNotVisibleError, elementZeroDimensionsError, } from '../../../errors/messages.js';
-import { callCDP } from '../../../ipc/client.js';
+import { callBdgScript, callCDP } from '../../../ipc/client.js';
 import { DEEP_QUERY_JS, selectorArgsJS } from '../../../runtime/dom/targetNode.js';
 import { viewportOverride } from '../../../runtime/page/emulation.js';
 import { readSessionMetadata } from '../../../session/metadata.js';
@@ -26,7 +26,7 @@ const STABILITY_CHECK_INTERVAL_MS = 50;
  */
 async function waitForPostScrollStability() {
     const deadline = Date.now() + POST_SCROLL_MAX_WAIT_MS;
-    await callCDP('Runtime.evaluate', {
+    await callBdgScript('Runtime.evaluate', {
         expression: `
       (() => {
         window.__bdg_scrollStability = {
@@ -66,7 +66,7 @@ async function waitForPostScrollStability() {
     });
     try {
         while (Date.now() < deadline) {
-            const checkResult = await callCDP('Runtime.evaluate', {
+            const checkResult = await callBdgScript('Runtime.evaluate', {
                 expression: `
           (() => {
             const state = window.__bdg_scrollStability;
@@ -91,7 +91,7 @@ async function waitForPostScrollStability() {
         log.debug('Post-scroll stability timeout, proceeding anyway');
     }
     finally {
-        await callCDP('Runtime.evaluate', {
+        await callBdgScript('Runtime.evaluate', {
             expression: `
         (() => {
           const state = window.__bdg_scrollStability;
@@ -111,7 +111,7 @@ async function waitForPostScrollStability() {
  * position so it can be restored afterwards.
  */
 async function scrollToElement(selector) {
-    const result = await callCDP('Runtime.evaluate', {
+    const result = await callBdgScript('Runtime.evaluate', {
         expression: `
       (() => {
         const el = (${DEEP_QUERY_JS})(${selectorArgsJS(selector)})[0];
@@ -133,7 +133,7 @@ async function scrollToElement(selector) {
     return { x: value.originalX ?? 0, y: value.originalY ?? 0 };
 }
 async function restoreScrollPosition(position) {
-    await callCDP('Runtime.evaluate', {
+    await callBdgScript('Runtime.evaluate', {
         expression: `window.scrollTo(${position.x}, ${position.y})`,
         returnByValue: true,
     });
@@ -147,7 +147,7 @@ async function restoreScrollPosition(position) {
  * @returns Width and height in CSS px
  */
 async function windowSize(viewport) {
-    const response = await callCDP('Runtime.evaluate', {
+    const response = await callBdgScript('Runtime.evaluate', {
         expression: '[window.innerWidth, window.innerHeight]',
         returnByValue: true,
     });
@@ -175,14 +175,22 @@ async function useUnitPixelRatio(devicePixelRatio, viewport) {
     const sessionViewport = readSessionMetadata()?.viewport;
     const size = sessionViewport ?? (await windowSize(viewport));
     await callCDP('Emulation.setDeviceMetricsOverride', viewportOverride(size, 1));
-    return async () => {
-        if (sessionViewport) {
-            await callCDP('Emulation.setDeviceMetricsOverride', viewportOverride(sessionViewport));
-        }
-        else {
-            await callCDP('Emulation.clearDeviceMetricsOverride', {});
-        }
-    };
+    return restoreSessionMetrics;
+}
+/**
+ * Put back the session's device metrics: its `--viewport` (and a phone's
+ * touch input, which a capture beyond the viewport turns off), else none.
+ */
+async function restoreSessionMetrics() {
+    const sessionViewport = readSessionMetadata()?.viewport;
+    if (!sessionViewport) {
+        await callCDP('Emulation.clearDeviceMetricsOverride', {});
+        return;
+    }
+    await callCDP('Emulation.setDeviceMetricsOverride', viewportOverride(sessionViewport));
+    if (sessionViewport.mobile) {
+        await callCDP('Emulation.setTouchEmulationEnabled', { enabled: true, maxTouchPoints: 5 });
+    }
 }
 /**
  * Get the bounding box (border box, so padding and border are included) of an
@@ -237,7 +245,7 @@ export async function capturePageScreenshot(outputPath, options = {}) {
     if (options.scroll) {
         originalScrollPosition = await scrollToElement(options.scroll);
     }
-    const dprResponse = await callCDP('Runtime.evaluate', {
+    const dprResponse = await callBdgScript('Runtime.evaluate', {
         expression: 'window.devicePixelRatio',
         returnByValue: true,
     });
@@ -258,7 +266,7 @@ export async function capturePageScreenshot(outputPath, options = {}) {
     const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, viewport);
     if (devicePixelRatio !== 1) {
         if (options.scroll) {
-            await callCDP('Runtime.evaluate', {
+            await callBdgScript('Runtime.evaluate', {
                 expression: `(${DEEP_QUERY_JS})(${selectorArgsJS(options.scroll)})[0]?.scrollIntoView({ block: 'center', behavior: 'instant' })`,
                 returnByValue: true,
             });
@@ -334,13 +342,17 @@ export async function capturePageScreenshot(outputPath, options = {}) {
 /** Descendants {@link CONTENT_OVERFLOW_JS} looks at, so a huge element stays cheap */
 const OVERFLOW_SCAN_LIMIT = 2000;
 /**
- * Page-side distances (CSS px, never negative) by which an element's rendered
- * descendants reach beyond its border box on each side: uncleared floats,
- * absolutely positioned and transformed children. Descendants of an element
- * that clips its overflow (`overflow` other than `visible`) are cut off by it
- * and not counted, nor are fixed ones (they belong to the viewport) or what
- * lies outside the document (skip links at -9999px). Zero everywhere when the
- * element clips its own overflow.
+ * Page-side distances (CSS px, never negative) by which what an element
+ * paints reaches beyond its border box on each side: its rendered
+ * descendants (uncleared floats, absolutely positioned and transformed
+ * children), its text (descenders past a tight line height, read from its
+ * scroll size beyond its client size, in transformed px, to the left on an
+ * RTL element), and its own outer box shadows and outline (a focus ring).
+ * Descendants of an element that clips its overflow (`overflow` other than
+ * `visible`) are cut off by it and not counted, nor are fixed ones (they
+ * belong to the viewport) or what lies outside the document (skip links at
+ * -9999px). Only the shadows and outline count when the element clips its
+ * own overflow.
  */
 const CONTENT_OVERFLOW_JS = `function () {
   const view = this.ownerDocument.defaultView;
@@ -365,8 +377,37 @@ const CONTENT_OVERFLOW_JS = `function () {
       if (!clips(style)) walk(child);
     }
   };
-  if (!clips(view.getComputedStyle(this))) walk(this);
-  return { left: own.left - reach.left, top: own.top - reach.top, right: reach.right - own.right, bottom: reach.bottom - own.bottom };
+  const ownStyle = view.getComputedStyle(this);
+  if (!clips(ownStyle)) {
+    walk(this);
+    const scaleX = this.offsetWidth ? own.width / this.offsetWidth : 1;
+    const scaleY = this.offsetHeight ? own.height / this.offsetHeight : 1;
+    const wider = Math.max(0, this.scrollWidth - this.clientWidth) * scaleX;
+    const taller = Math.max(0, this.scrollHeight - this.clientHeight) * scaleY;
+    if (ownStyle.direction === 'rtl') reach.left = Math.min(reach.left, own.left - wider);
+    else reach.right = Math.max(reach.right, own.right + wider);
+    reach.bottom = Math.max(reach.bottom, own.bottom + taller);
+  }
+  const ink = { left: 0, top: 0, right: 0, bottom: 0 };
+  const grow = (side, amount) => { ink[side] = Math.max(ink[side], amount); };
+  for (const layer of ownStyle.boxShadow === 'none' ? [] : ownStyle.boxShadow.split(/,(?![^(]*\\))/)) {
+    if (/\\binset\\b/.test(layer)) continue;
+    const [x = 0, y = 0, blur = 0, spread = 0] = (layer.replace(/(rgba?|hsla?|color|oklch|lab|lch)\\([^)]*\\)/g, '').match(/-?[\\d.]+px/g) || []).map(parseFloat);
+    grow('left', blur + spread - x);
+    grow('right', blur + spread + x);
+    grow('top', blur + spread - y);
+    grow('bottom', blur + spread + y);
+  }
+  if (ownStyle.outlineStyle !== 'none') {
+    const outline = parseFloat(ownStyle.outlineWidth) + parseFloat(ownStyle.outlineOffset);
+    ['left', 'top', 'right', 'bottom'].forEach((side) => grow(side, outline));
+  }
+  return {
+    left: Math.max(own.left - reach.left, ink.left),
+    top: Math.max(own.top - reach.top, ink.top),
+    right: Math.max(reach.right - own.right, ink.right),
+    bottom: Math.max(reach.bottom - own.bottom, ink.bottom)
+  };
 }`;
 /**
  * The visible viewport (without scrollbars) in CSS px.
@@ -393,27 +434,80 @@ function insideView(area, view) {
 }
 /**
  * Measure the area to capture and, when it fits in the viewport but is not
- * in view, scroll it to the middle first. A capture inside the viewport
- * keeps the page as it is; one beyond it makes Chrome lay the page out
- * without its scrollbar, which moves centered content by half the
- * scrollbar's width, so it is used only for areas larger than the viewport.
+ * in view, scroll it to the middle first (the returned position puts the
+ * page back). A capture inside the viewport keeps the page as it is; one
+ * beyond it makes Chrome lay the page out without its scrollbar, so for an
+ * area larger than the viewport the scrollbars are hidden first and the
+ * area measured in that layout (centered content would else move by half
+ * the scrollbar's width).
  *
  * @param ref - Node reference
- * @returns Border box, area to capture (viewport coordinates) and whether it is in view
+ * @param padding - Extra space around the area (CSS px)
+ * @returns Border box, area to capture (viewport coordinates), whether it is
+ *   in view, and the scroll position to restore when it scrolled
  */
-async function measureInView(ref) {
+async function measureInView(ref, padding) {
     const view = await visibleViewport();
     let box = await getElementBounds(ref);
-    let bounds = await captureArea(ref, box);
+    let bounds = await captureArea(ref, box, padding);
     const fits = bounds.width <= view.width && bounds.height <= view.height;
-    if (fits && !insideView(bounds, view)) {
-        const dx = bounds.x + bounds.width / 2 - view.width / 2;
-        const dy = bounds.y + bounds.height / 2 - view.height / 2;
-        await callCDP('Runtime.evaluate', { expression: `window.scrollBy(${dx}, ${dy})` });
+    if (!fits) {
+        await keepLayoutWithoutScrollbars(view);
         box = await getElementBounds(ref);
-        bounds = await captureArea(ref, box);
+        return { box, bounds: await captureArea(ref, box, padding), inView: false };
     }
-    return { box, bounds, inView: insideView(bounds, view) };
+    if (insideView(bounds, view))
+        return { box, bounds, inView: true };
+    const scrolledFrom = await scrollPosition();
+    const dx = bounds.x + bounds.width / 2 - view.width / 2;
+    const dy = bounds.y + bounds.height / 2 - view.height / 2;
+    await callBdgScript('Runtime.evaluate', { expression: `window.scrollBy(${dx}, ${dy})` });
+    try {
+        box = await getElementBounds(ref);
+        bounds = await captureArea(ref, box, padding);
+    }
+    catch (error) {
+        await restoreScrollPosition(scrolledFrom);
+        throw error;
+    }
+    return { box, bounds, inView: insideView(bounds, view), scrolledFrom };
+}
+/**
+ * Lay the page out at its current width without scrollbars: a capture
+ * beyond the viewport hides them, and without this the page would widen by
+ * the scrollbar and centered content move after it was measured. The
+ * viewport is overridden at the visible width (CSS px, pixel ratio 1; still
+ * a phone in a `--mobile` session) until
+ * {@link restoreViewport}.
+ *
+ * @param view - Visible viewport size
+ */
+async function keepLayoutWithoutScrollbars(view) {
+    const phone = readSessionMetadata()?.viewport?.mobile;
+    await callCDP('Emulation.setScrollbarsHidden', { hidden: true });
+    await callCDP('Emulation.setDeviceMetricsOverride', viewportOverride({ ...view, ...(phone && { mobile: true }) }, 1));
+}
+/**
+ * Put back the viewport a capture changed: the session's `--viewport`, else
+ * none, with scrollbars shown.
+ */
+async function restoreViewport() {
+    await callCDP('Emulation.setScrollbarsHidden', { hidden: false });
+    await restoreSessionMetrics();
+}
+/**
+ * The page's scroll position.
+ *
+ * @returns Scroll offsets in CSS px
+ */
+async function scrollPosition() {
+    const response = await callBdgScript('Runtime.evaluate', {
+        expression: '[window.scrollX, window.scrollY]',
+        returnByValue: true,
+    });
+    const value = response.data?.result?.result?.value;
+    const [x, y] = Array.isArray(value) ? value : [];
+    return { x: x ?? 0, y: y ?? 0 };
 }
 /** Overflow (px) below which the capture keeps to the border box (subpixel rounding) */
 const OVERFLOW_SLACK = 1;
@@ -424,12 +518,33 @@ const OVERFLOW_SLACK = 1;
  *
  * @param ref - Node reference
  * @param bounds - Border box (DOM.getBoxModel coordinates)
- * @returns The area, or the border box when nothing overflows (or the page cannot be asked)
+ * @param padding - Extra space around it (CSS px)
+ * @returns The area, or the border box (with the padding) when nothing
+ *   overflows (or the page cannot be asked)
  */
-async function captureArea(ref, bounds) {
+async function captureArea(ref, bounds, padding) {
+    const area = await paintedArea(ref, bounds);
+    return padding > 0
+        ? {
+            x: area.x - padding,
+            y: area.y - padding,
+            width: area.width + 2 * padding,
+            height: area.height + 2 * padding,
+        }
+        : area;
+}
+/**
+ * The border box grown to what the element paints beyond it
+ * ({@link CONTENT_OVERFLOW_JS}).
+ *
+ * @param ref - Node reference
+ * @param bounds - Border box
+ * @returns The area
+ */
+async function paintedArea(ref, bounds) {
     const objectGroup = `bdg-shot-${process.pid}`;
     try {
-        const resolved = await callCDP('DOM.resolveNode', { ...ref, objectGroup });
+        const resolved = await callBdgScript('DOM.resolveNode', { ...ref, objectGroup });
         const objectId = resolved.data?.result?.object
             .objectId;
         if (!objectId)
@@ -471,23 +586,27 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
     const format = options.format ?? 'png';
     const quality = format === 'jpeg' ? (options.quality ?? 90) : undefined;
     const noResize = options.noResize ?? false;
-    const dprResponse = await callCDP('Runtime.evaluate', {
+    const dprResponse = await callBdgScript('Runtime.evaluate', {
         expression: 'window.devicePixelRatio',
         returnByValue: true,
     });
     const devicePixelRatio = dprResponse.data?.result?.result?.value ?? 1;
     const before = (await callCDP('Page.getLayoutMetrics', {})).data?.result;
     const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, before?.visualViewport ?? { clientWidth: 800, clientHeight: 600 });
-    let box;
-    let bounds;
-    let inView;
+    const restore = async (wide, scrolledFrom) => {
+        await (wide ? restoreViewport() : restoreMetrics());
+        if (scrolledFrom)
+            await restoreScrollPosition(scrolledFrom);
+    };
+    let measured;
     try {
-        ({ box, bounds, inView } = await measureInView(ref));
+        measured = await measureInView(ref, options.padding ?? 0);
     }
     catch (error) {
-        await restoreMetrics();
+        await restoreViewport();
         throw error;
     }
+    const { box, bounds, inView, scrolledFrom } = measured;
     const originalWidth = bounds.width;
     const originalHeight = bounds.height;
     const resized = shouldResize(originalWidth, originalHeight, noResize);
@@ -514,7 +633,7 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
         screenshotResult = screenshotResponse.data?.result;
     }
     finally {
-        await restoreMetrics();
+        await restore(!inView, scrolledFrom);
     }
     if (!screenshotResult?.data) {
         throw new CDPConnectionError('No screenshot data returned', new Error('Empty response'));
@@ -532,6 +651,7 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
         element: {
             bounds: roundBounds(onPage(box)),
             ...(bounds !== box && { captured: roundBounds(clip) }),
+            ...(options.padding && { padding: options.padding }),
         },
     };
     if (quality !== undefined) {

package/dist/commands/dom/index.js

@@ -17,14 +17,16 @@
  */
 import { Option } from 'commander';
 import { registerA11yCommands } from './a11y.js';
+import { registerAuditCommand } from './audit.js';
 import { handleDomEval } from './eval.js';
 import { registerFormCommand } from './form.js';
 import { handleDomFrames } from './frames.js';
 import { DOM_GET_DEFAULT_SELECTOR, handleDomGet } from './get.js';
+import { QUERY_CACHE_LIMIT } from './helpers/query.js';
 import { registerInspectCommand } from './inspect.js';
 import { registerLayoutCommand } from './layout.js';
 import { registerListenersCommand } from './listeners.js';
-import { handleDomQuery } from './query.js';
+import { handleDomQuery, QUERY_LIST_LIMIT } from './query.js';
 import { handleDomScreenshot } from './screenshot.js';
 import { registerWaitCommand } from './wait.js';
 import { SELECTOR_OR_INDEX_ARGUMENT, SELECTOR_SCOPE_HELP, } from '../shared/commonOptions.js';
@@ -41,12 +43,14 @@ export function registerDomCommands(program) {
     registerFormCommand(dom);
     registerListenersCommand(dom);
     registerLayoutCommand(dom);
+    registerAuditCommand(dom);
     registerInspectCommand(dom);
     registerWaitCommand(dom);
     dom
         .command('query')
         .description('Find elements by CSS selector')
         .argument('<selector>', 'CSS selector (e.g., ".error", "#app", "button")')
+        .option('--limit <n>', `Matches to list (default: ${QUERY_LIST_LIMIT}, ${QUERY_CACHE_LIMIT} with --json; 0 = all); the first ${QUERY_CACHE_LIMIT} (or more with a higher limit) are indexed`, integerOption(0))
         .option('-j, --json', 'Output as JSON')
         .addHelpText('after', SELECTOR_SCOPE_HELP)
         .action(async (selector, options) => {
@@ -97,7 +101,8 @@ export function registerDomCommands(program) {
         .argument('<path>', 'Output file path, or directory for --follow mode')
         .argument('[selector]', 'Element to capture: CSS selector or index from a query (same as --selector / --index)')
         .option('--selector <selector>', 'CSS selector for element capture')
-        .option('--index <number>', 'Cached element index (0-based) from previous query', integerOption(0))
+        .option('--index <number>', 'Cached element index (0-based) from a previous query; with --selector, which match', integerOption(0))
+        .option('--padding <px>', 'Element capture: extra space around it (shadows and focus rings are included anyway)', integerOption(0, 500))
         .option('--format <format>', 'Image format: png or jpeg/jpg (default: from the file extension, else png)', screenshotFormatOption)
         .option('--quality <number>', 'JPEG quality 0-100 (default: 90)', integerOption(0, 100))
         .option('--no-full-page', 'Capture viewport only (default: full page)')

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

@@ -2,13 +2,30 @@
  * `bdg dom query` — find elements by CSS selector and populate the query cache.
  */
 import type { DomQueryCommandOptions } from '../shared/optionTypes.js';
+import type { DomQueryResult } from '../../types.js';
+/** Matches `dom query` lists without `--limit` (human output) */
+export declare const QUERY_LIST_LIMIT = 50;
 /**
  * Handle `bdg dom query <selector>`.
  *
- * Runs the selector, caches the result set so later commands can reference
- * elements by index, and renders the result either as JSON or human output.
+ * Runs the selector, caches the described matches so later commands can
+ * reference elements by index, and lists the first `--limit` of them (50,
+ * or {@link QUERY_CACHE_LIMIT} with `--json`; 0 = all) with the total count.
  * No match exits 83, like `dom get` and `dom a11y`, and clears the cache so
  * indices of an earlier query are not used by mistake.
  */
 export declare function handleDomQuery(selector: string, options: DomQueryCommandOptions): Promise<void>;
+/**
+ * The matches to list: the first `limit` (all with 0), with how many were
+ * left out and, when not every match was described, how many can be used by
+ * index. Nothing is added when the limit cut nothing (a match that could not
+ * be described is just missing, as before). When more than
+ * {@link VIEWPORT_HINT_LIMIT} are listed, `viewportChecked` says that only
+ * the first ones have a viewport position.
+ *
+ * @param result - Query result with every described match
+ * @param limit - Matches to list (0 = all)
+ * @returns Result to output
+ */
+export declare function listedMatches(result: DomQueryResult, limit: number): DomQueryResult;
 //# sourceMappingURL=query.d.ts.map

package/dist/commands/dom/query.js

@@ -1,22 +1,28 @@
 /**
  * `bdg dom query` — find elements by CSS selector and populate the query cache.
  */
-import { noMatchesError, queryDOMElements } from './helpers/index.js';
+import { noMatchesError, pageDocumentId, queryDOMElements } from './helpers/index.js';
+import { QUERY_CACHE_LIMIT, VIEWPORT_HINT_LIMIT } from './helpers/query.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { formatDomQuery } from '../../ui/formatters/dom.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+/** Matches `dom query` lists without `--limit` (human output) */
+export const QUERY_LIST_LIMIT = 50;
 /**
  * Handle `bdg dom query <selector>`.
  *
- * Runs the selector, caches the result set so later commands can reference
- * elements by index, and renders the result either as JSON or human output.
+ * Runs the selector, caches the described matches so later commands can
+ * reference elements by index, and lists the first `--limit` of them (50,
+ * or {@link QUERY_CACHE_LIMIT} with `--json`; 0 = all) with the total count.
  * No match exits 83, like `dom get` and `dom a11y`, and clears the cache so
  * indices of an earlier query are not used by mistake.
  */
 export async function handleDomQuery(selector, options) {
+    const limit = options.limit ?? (options.json ? QUERY_CACHE_LIMIT : QUERY_LIST_LIMIT);
     await runCommand(async () => {
-        const result = await queryDOMElements(selector);
+        const document = await pageDocumentId();
+        const result = await queryDOMElements(selector, limit);
         const cache = QueryCacheManager.getInstance();
         if (result.count === 0) {
             await cache.clear();
@@ -28,8 +34,33 @@ export async function handleDomQuery(selector, options) {
                 errorContext: { suggestion: err.suggestion },
             };
         }
-        await cache.set(result);
-        return { success: true, data: result };
+        await cache.set(result, document);
+        return { success: true, data: listedMatches(result, limit) };
     }, options, formatDomQuery);
 }
+/**
+ * The matches to list: the first `limit` (all with 0), with how many were
+ * left out and, when not every match was described, how many can be used by
+ * index. Nothing is added when the limit cut nothing (a match that could not
+ * be described is just missing, as before). When more than
+ * {@link VIEWPORT_HINT_LIMIT} are listed, `viewportChecked` says that only
+ * the first ones have a viewport position.
+ *
+ * @param result - Query result with every described match
+ * @param limit - Matches to list (0 = all)
+ * @returns Result to output
+ */
+export function listedMatches(result, limit) {
+    const listed = limit === 0 || result.count <= limit
+        ? result
+        : {
+            ...result,
+            nodes: result.nodes.slice(0, limit),
+            omitted: result.count - Math.min(limit, result.nodes.length),
+            ...(result.nodes.length < result.count && { indexed: result.nodes.length }),
+        };
+    return listed.nodes.length > VIEWPORT_HINT_LIMIT
+        ? { ...listed, viewportChecked: VIEWPORT_HINT_LIMIT }
+        : listed;
+}
 //# sourceMappingURL=query.js.map

package/dist/commands/dom/screenshot.js

@@ -3,17 +3,18 @@
  */
 import { extname } from 'path';
 import { DomElementResolver } from './DomElementResolver.js';
-import { capturePageScreenshot, captureElementScreenshot, resolveSelector, } from './helpers/index.js';
+import { capturePageScreenshot, captureElementScreenshot, resolveSelector, selectMatch, } from './helpers/index.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { assertFilePath, outputPathError } from '../shared/outputFile.js';
 import { positiveIntRule } from '../shared/validation.js';
 import { CommandError } from '../../errors/index.js';
-import { conflictingOptionsMessage, conflictingTargetError, genericError, } from '../../errors/messages.js';
+import { conflictingTargetError, genericError } from '../../errors/messages.js';
 import { missingArgumentError } from '../../errors/messages.js';
 import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
 import { formatDomScreenshot } from '../../ui/formatters/dom.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { delay } from '../../utils/async.js';
+import { makeDirectory } from '../../utils/directories.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
@@ -60,12 +61,16 @@ function buildElementScreenshotOptions(options) {
         format: options.format,
         quality: options.quality,
         noResize: options.resize === false,
+        padding: options.padding,
     });
 }
 function hasElementTarget(options) {
     return options.selector !== undefined || options.index !== undefined;
 }
 async function resolveElementNodeId(options) {
+    if (options.selector !== undefined && options.index !== undefined) {
+        return { backendNodeId: await selectMatch(options.selector, options.index) };
+    }
     if (options.index !== undefined) {
         const resolver = DomElementResolver.getInstance();
         const node = await resolver.getNodeIdForIndex(options.index);
@@ -106,7 +111,7 @@ function ensureDirectory(dirPath, fs) {
         throw new CommandError(`--follow needs a directory, but ${dirPath} is a file`, { suggestion: 'Give a directory for the frames, e.g. bdg dom screenshot ./frames --follow' }, EXIT_CODES.INVALID_ARGUMENTS);
     }
     try {
-        fs.mkdirSync(dirPath, { recursive: true });
+        makeDirectory(dirPath);
     }
     catch (error) {
         throw outputPathError(dirPath, error);
@@ -207,8 +212,8 @@ function reportSequenceError(error, captured, json) {
     process.exit(exitCode);
 }
 /**
- * Reject options that would be ignored: `--selector` with `--index` (the
- * index already names an element), and `--quality` for a PNG.
+ * Reject options that would be ignored: `--quality` for a PNG, and
+ * `--padding` without an element.
  *
  * @param outputPath - File to write
  * @param options - Command options
@@ -216,8 +221,8 @@ function reportSequenceError(error, captured, json) {
  */
 function assertScreenshotOptions(outputPath, options) {
     let message;
-    if (options.selector !== undefined && options.index !== undefined) {
-        message = conflictingOptionsMessage('--selector', '--index');
+    if (options.padding !== undefined && !hasElementTarget(options)) {
+        message = '--padding applies to element captures; name an element (selector or index)';
     }
     else if (options.quality !== undefined &&
         !options.follow &&

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

@@ -21,10 +21,11 @@ export interface SemanticNodeWithContext {
  * link's href, a field's type and name), like `dom query` does, and is
  * followed by up to 500 characters of the element's text
  * (all of it with `dom get --full`) when it is longer than the one-line
- * preview, or, for an element without text or name, what it holds.
+ * preview or the role line shows an accessible name other than the text,
+ * or, for an element without text or name, what it holds.
  *
  * @param data - Accessibility node and optional DOM context
- * @returns Role line, plus a text line for elements with longer text
+ * @returns Role line, plus a text line for elements with longer or differently named text
  */
 export declare function formatSemanticNodeWithContext(data: SemanticNodeWithContext): string;
 /**