browser-debugger-cli 0.10.0 → 0.12.0

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

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

@@ -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
@@ -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 callCDP('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 callCDP('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,9 +518,30 @@ 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, 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 captureArea(ref, bounds) {
+async function paintedArea(ref, bounds) {
     const objectGroup = `bdg-shot-${process.pid}`;
     try {
         const resolved = await callCDP('DOM.resolveNode', { ...ref, objectGroup });
@@ -478,16 +593,20 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
     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

@@ -22,6 +22,7 @@ import { registerFormCommand } from './form.js';
 import { handleDomFrames } from './frames.js';
 import { DOM_GET_DEFAULT_SELECTOR, handleDomGet } from './get.js';
 import { registerInspectCommand } from './inspect.js';
+import { registerAuditCommand } from './audit.js';
 import { registerLayoutCommand } from './layout.js';
 import { registerListenersCommand } from './listeners.js';
 import { handleDomQuery } from './query.js';
@@ -41,6 +42,7 @@ export function registerDomCommands(program) {
     registerFormCommand(dom);
     registerListenersCommand(dom);
     registerLayoutCommand(dom);
+    registerAuditCommand(dom);
     registerInspectCommand(dom);
     registerWaitCommand(dom);
     dom
@@ -97,7 +99,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/screenshot.js

@@ -3,12 +3,12 @@
  */
 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';
@@ -60,12 +60,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);
@@ -207,8 +211,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 +220,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/wait.js

@@ -24,7 +24,7 @@ export function registerWaitCommand(dom) {
     dom
         .command('wait')
         .description('Wait until elements appear, become visible, contain a text or are gone (or the page loads)')
-        .argument('[selector]', 'CSS selector (:has-text, :visible allowed; shadow DOM and same-origin iframes searched); optional with --load')
+        .argument('[selector]', 'CSS selector (:has-text, :visible allowed; shadow DOM and same-origin iframes searched); without one, waits for the page to load (--load)')
         .option('--text <text>', 'A match must contain this text (case-insensitive)')
         .option('--visible', 'Only count visible matches')
         .option('--gone', 'Wait until no element matches (none visible, with --visible)')
@@ -44,7 +44,9 @@ export function registerWaitCommand(dom) {
  * @returns Command result
  */
 async function waitFor(selector, options) {
-    const needsSelector = options.text !== undefined || options.gone === true || !options.load;
+    const load = options.load === true ||
+        (selector === undefined && options.text === undefined && !options.gone && !options.visible);
+    const needsSelector = options.text !== undefined || options.gone === true || !load;
     if (selector === undefined && needsSelector) {
         const err = waitTargetRequiredError();
         return {
@@ -58,7 +60,7 @@ async function waitFor(selector, options) {
         ...filterDefined({ selector, text: options.text }),
         ...(options.gone && { gone: true }),
         ...(options.visible && { visible: true }),
-        ...(options.load && { load: true }),
+        ...(load && { load: true }),
         timeout: options.timeout,
     });
     if (response.status === 'error' || !response.data) {

package/dist/commands/helpJson.js

@@ -97,7 +97,7 @@ function convertCommand(command) {
 function generateRuntimeState() {
     const sessionActive = readLiveDaemonPid() !== null;
     const availableCommands = sessionActive
-        ? ['peek', 'tail', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'sessions', 'stop']
+        ? ['peek', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'sessions', 'stop']
         : ['bdg <url>', 'sessions', 'cleanup', '--help', '--version'];
     return {
         sessionActive,

package/dist/commands/installSkill.d.ts

@@ -0,0 +1,20 @@
+import type { Command } from 'commander';
+import type { InstalledSkill, SkillTarget } from '../types.js';
+/**
+ * Copy the bdg skill into each target's skill directory, overwriting an
+ * older copy.
+ *
+ * @param targets - Agents to install for
+ * @param home - Home directory the skill roots are relative to
+ * @param source - SKILL.md to copy
+ * @returns One entry per target, in the given order
+ * @throws CommandError when the source is missing (83) or a write fails (82)
+ */
+export declare function installSkill(targets: SkillTarget[], home?: string, source?: string): InstalledSkill[];
+/**
+ * Register the install-skill command.
+ *
+ * @param program - Commander.js Command instance to register commands on
+ */
+export declare function registerInstallSkillCommand(program: Command): void;
+//# sourceMappingURL=installSkill.d.ts.map