browser-debugger-cli 0.11.0 → 0.12.0

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

@@ -10,7 +10,7 @@ import { MAX_EDGE_PX, PIXELS_PER_TOKEN, TALL_PAGE_THRESHOLD, } from './dom/scree
 /** What DOM actions report about the network requests they triggered */
 const TRIGGERED_REQUESTS_BEHAVIOR = 'Requests (and WebSocket connections) that start after the action begins are returned as triggeredRequests (method, url, status, durationMs; pending when still running at return, loading when the response arrived but its body is still streaming; with resourceType; human output lists documents, XHR/fetch and WebSockets first (up to 10) and counts static assets on one line; absent when network telemetry is off). Attribution is by time: requests a page timer or poller starts meanwhile are listed too, whether or not the action caused them';
 /** What every DOM action reports about the page besides its requests */
-const ACTION_EFFECTS_BEHAVIOR = 'The result also says what changed on the page: a navigation (Page: navigated to <url> (status), or URL changed to <url> (same document); JSON navigation { url, sameDocument, status }), and messages that appeared or changed in alert/status/aria-live elements or flash/error/toast-like classes (New text: "…" (element); JSON messages [{ text, element }], at most 3; after a navigation every message on the new page counts; texts of only digits and time units, such as clocks and counters, are left out, but other text that changes on its own, such as a rotating banner, can show up). Both are absent when nothing changed. Cost: one page script sent before the action without waiting for it and one read after it, a few ms; when the page does not answer (a pending navigation) bdg waits at most 200 ms for the snapshot and 250 ms per read, and the navigation is still reported from CDP events';
+const ACTION_EFFECTS_BEHAVIOR = 'The result also says what changed on the page: a navigation (Page: navigated to <url> (status), or URL changed to <url> (same document); JSON navigation { url, sameDocument, status }), and messages that appeared or changed in alert/status/aria-live elements or flash/error/toast-like classes (New text: "…" (element); JSON messages [{ text, element }], at most 3, with "(+N more)" and moreMessages for the rest; after a navigation every message on the new page counts; texts of only digits and time units, such as clocks and counters, are left out, but other text that changes on its own, such as a rotating banner, can show up). Both are absent when nothing changed. Cost: one page script sent before the action without waiting for it and one read after it, a few ms; when the page does not answer (a pending navigation) bdg waits at most 200 ms for the snapshot and 250 ms per read, and the navigation is still reported from CDP events';
 /** What click and pressKey report when the page was still changing as they returned */
 const STILL_CHANGING_BEHAVIOR = 'When the page was still changing as the action returned, the status line says (page still changing), a note below it says what was pending and suggests bdg dom wait <selector>, and JSON has settled: false with pending { requests (document, fetch/XHR and script requests still running), navigation (a new page still loading), loading (a loading indicator that appeared, e.g. "div#loading"), domChanging (DOM changes kept coming in bursts over a second look 250 ms later; a single render, ticking text and style animations do not count), busy (the page did not answer within 250 ms: a long script) }; absent when the page looked settled (exit code stays 0). A result a timer renders later, with no DOM change, request or loading indicator before it, is not detected. Cost: nothing extra, except 250 ms plus one read when the DOM looked busy. Not checked with --no-wait';
 /** What hover and pressKey report about elements they showed */
@@ -25,8 +25,12 @@ const NO_WAIT_TRIGGERED_REQUESTS = 'Returns immediately without waiting for netw
 const OPTION_BEHAVIORS = {
     'screenshot:--selector': {
         default: 'Captures the page (full page unless --no-full-page)',
-        whenEnabled: 'Captures one element; the selector (or a query index) can also be given as the second argument: bdg dom screenshot out.png "#sel". Both given and naming different elements exits 81',
-        automaticBehavior: 'The capture covers the border box plus content overflowing it (uncleared floats, positioned children; not what an overflow: hidden ancestor cuts off, nor fixed descendants); JSON element.bounds is the border box and element.captured the larger area when it grew, which human output notes',
+        whenEnabled: 'Captures one element; the selector (or a query index) can also be given as the second argument: bdg dom screenshot out.png "#sel". With --index it picks that match of the selector (--selector ".item" --index 2). A positional and an option naming different elements exits 81',
+        automaticBehavior: "The capture covers the border box plus what overflows it: uncleared floats, positioned children, text past a tight line height, and the element's own box shadows and outline (a focus ring); not what an overflow: hidden ancestor cuts off, nor fixed descendants. JSON element.bounds is the border box and element.captured the larger area when it grew, which human output notes. An element smaller than the viewport is scrolled into view for the capture and the page scroll put back afterwards; a larger one is captured with the page laid out at its width without scrollbars, so it does not shift",
+    },
+    'screenshot:--padding': {
+        default: 'The element capture is its painted area (border box, overflowing content, shadows, outline)',
+        whenEnabled: 'Adds that many CSS px of the page around the element capture on every side (0-500); without an element it exits 81',
     },
     'screenshot:--no-resize': {
         default: `Images auto-resized to max ${MAX_EDGE_PX}px longest edge for Claude Vision optimization (~1,600 tokens)`,
@@ -208,10 +212,16 @@ const OPTION_BEHAVIORS = {
         whenEnabled: 'Lists every listener of framework roots individually',
         tokenImpact: 'On React pages --all adds a row per event type and phase (about 140 rows, 60 KB of JSON)',
     },
+    'audit:--level': {
+        default: 'Text must reach WCAG AA: 4.5, or 3 for large text (24px, or 18.66px bold); every text-drawing element is checked, composited like dom inspect',
+        whenEnabled: '--level AAA asks 7, or 4.5 for large text',
+        automaticBehavior: 'One walk over the rendered elements (open shadow roots included, at most 20000; capped says when it stopped). Findings are sorted weakest first; --limit (default 20) lists that many per check and the rest are counted. Overflow leaves out content inside horizontal scrollers and visually-hidden 1px text; identical findings are grouped (×N)',
+        tokenImpact: 'About one line per finding; --limit bounds it',
+    },
     'layout:--index': {
         default: 'Reports every match of the selector (human output lists the first 20, JSON up to 100 plus an omitted count); a numeric argument reports that cached query element',
         whenEnabled: 'Reports only the nth match (0-based); out of range exits 81',
-        automaticBehavior: 'Coordinates are CSS px: bounds relative to the top-level page (iframe offsets and page scroll included), viewport relative to the visible area. Iframes and overflow containers (scroll lists, overflow: hidden) clip what counts as visible (clippedBy names the one cutting it off). scrollBy brings the whole element into view and is limited to how far the page can scroll: for an element out of view it centres it (aligns its start when it is larger than the viewport; human output says "to centre it"), for a partly visible one it is the smallest scroll that shows all of it (the part cut off at the top or bottom; the start of one larger than the viewport; "partly visible (87%); scroll up 5px to see all of it"). Elements a page script moves on scroll (floating menus) may move again after it; fixed and sticky elements (page scroll does not move them, or only until they stick) and ones beyond that range get offScreenReason instead, which says "page scrolling is locked (…)" when the page cannot scroll because body/html is position: fixed or overflow: hidden, so in-flow content is not called fixed; a visible dialog (dialog[open], [aria-modal=true], [role=dialog|alertdialog]) is named as the likely cause ("likely by dialog div#consent"). page.viewport is the layout viewport without scrollbars, as dom scroll reports it; page.colorScheme is the prefers-color-scheme media feature the page sees (not the theme it renders). Content in a closed <details> or under content-visibility: hidden is hidden. coveredBy is the topmost element at the center of the largest visible box (none for pointer-events: none, nor for an element of the same click target: an overlay inside the link, button or label the element is in, a link to the same URL, or the textless absolutely positioned overlay link spanning the card that holds plain content); inert elements are flagged, not hidden',
+        automaticBehavior: 'Coordinates are CSS px: bounds relative to the top-level page (iframe offsets and page scroll included), viewport relative to the visible area. Iframes and overflow containers (scroll lists, overflow: hidden) clip what counts as visible (clippedBy names the one cutting it off). scrollBy brings the whole element into view and is limited to how far the page can scroll: for an element out of view it centres it (aligns its start when it is larger than the viewport; human output says "to centre it"), for a partly visible one it is the smallest scroll that shows all of it (the part cut off at the top or bottom; the start of one larger than the viewport; "partly visible (87%); scroll up 5px to see all of it"). Elements a page script moves on scroll (floating menus) may move again after it; fixed and sticky elements (page scroll does not move them, or only until they stick) and ones beyond that range get offScreenReason instead, which says "page scrolling is locked (…)" when the page cannot scroll because body/html is position: fixed or overflow: hidden, so in-flow content is not called fixed; a visible dialog (dialog[open], [aria-modal=true], [role=dialog|alertdialog]) is named as the likely cause ("likely by dialog div#consent"). page.viewport is the layout viewport without scrollbars, as dom scroll reports it; page.colorScheme is the prefers-color-scheme media feature the page sees (not the theme it renders). Content in a closed <details> or under content-visibility: hidden is hidden. coveredBy is the first element painted above it at the center of the largest visible box that paints there (the background of a sticky header rather than the transparent logo on it; inside a shadow host, what its shadow root paints), else the topmost one with coverTransparent (none for pointer-events: none, nor for an element of the same click target: an overlay inside the link, button or label the element is in, a link to the same URL, or the textless absolutely positioned overlay link spanning the card that holds plain content); inert elements are flagged, not hidden',
         tokenImpact: 'About one line per element; a cheap alternative to screenshots for "where is it?"',
     },
     'inspect:--index': {
@@ -286,11 +296,11 @@ const OPTION_BEHAVIORS = {
     },
     'peek:-f': {
         default: 'Shows snapshot of current data',
-        whenEnabled: 'Continuous monitoring - refreshes every second (like tail -f)',
+        whenEnabled: 'Continuous monitoring (like tail -f): refreshes every second, or every --interval ms (100-60000). Replaces the deprecated bdg tail',
     },
     'peek:--follow': {
         default: 'Shows snapshot of current data',
-        whenEnabled: 'Continuous monitoring - refreshes every second (like tail -f)',
+        whenEnabled: 'Continuous monitoring (like tail -f): refreshes every second, or every --interval ms (100-60000). Replaces the deprecated bdg tail',
     },
     'peek:-v': {
         default: 'Compact output (truncated URLs, no resource types)',
@@ -326,6 +336,11 @@ const OPTION_BEHAVIORS = {
         whenEnabled: 'The page gets exactly that viewport (CSS px, e.g. 1280x800) for the whole session, through navigations and reloads (Emulation.setDeviceMetricsOverride at the display pixel ratio); a launched Chrome also opens its window at that size, so tabs the page opens get it too',
         automaticBehavior: 'Works with --chrome-ws-url: the override belongs to the session, and Chrome drops it when the session ends, so the attached browser gets its own size back. bdg status shows the resulting layout viewport without the scrollbar (Viewport: 1265×800 (emulated 1280x800)). Invalid sizes (not WxH, a side outside 1-10000) exit 81',
     },
+    'bdg:--mobile': {
+        default: 'A desktop viewport: classic scrollbars take ~15px of the width, no touch, a desktop user agent',
+        whenEnabled: 'Emulates a phone for the whole session: a mobile viewport (390x844 unless --viewport) at pixel ratio 3 with mobile layout (meta viewport, overlay scrollbars, so 100vw fits), touch (pointer: coarse, maxTouchPoints 5) and an Android Chrome user agent with mobile client hints; bdg page emulate --mobile turns it on mid-session, --viewport WxH without --mobile or --reset turns it off',
+        automaticBehavior: 'Screenshots keep the mobile layout and are taken at pixel ratio 1 (CSS px = image px); bdg status shows "(emulated 390x844, phone)"',
+    },
     'bdg:--color-scheme': {
         default: 'The page sees the system setting for prefers-color-scheme (headless Chrome follows the OS, so a dark OS renders dark pages); bdg status and dom layout show which one',
         whenEnabled: 'Emulates prefers-color-scheme: light or dark for the whole session (Emulation.setEmulatedMedia); other values exit 81 with a suggestion',

package/dist/commands/page.js

@@ -5,7 +5,7 @@
 import { Option } from 'commander';
 import { noActiveSessionError, runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
-import { parseColorScheme, parseViewport } from './start.js';
+import { parseColorScheme, requestedViewport } from './start.js';
 import { CommandError } from '../errors/index.js';
 import { javascriptNavigationError } from '../errors/messages.js';
 import { getStatus, pageEmulate, pageNavigate } from '../ipc/client.js';
@@ -127,12 +127,13 @@ async function showPageInfo(options) {
 function emulationRequest(options) {
     if (options.reset)
         return { reset: true };
-    if (options.viewport === undefined && options.colorScheme === undefined) {
+    if (options.viewport === undefined && options.colorScheme === undefined && !options.mobile) {
         const err = pageEmulateNothingError();
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
     }
+    const viewport = requestedViewport(options.viewport, options.mobile);
     return {
-        ...(options.viewport !== undefined && { viewport: parseViewport(options.viewport) }),
+        ...(viewport && { viewport }),
         ...(options.colorScheme !== undefined && {
             colorScheme: parseColorScheme(options.colorScheme),
         }),
@@ -188,11 +189,13 @@ export function registerPageCommands(program) {
     page
         .command('emulate')
         .description(PAGE_EMULATE_DESCRIPTION)
-        .option('--viewport <WxH>', 'Viewport size in CSS px, e.g. 900x700')
+        .option('--viewport <WxH>', 'Viewport size in CSS px, e.g. 900x700 (a desktop one unless --mobile)')
         .option('--color-scheme <scheme>', 'Emulate prefers-color-scheme: light or dark')
+        .option('--mobile', 'Emulate a phone: mobile viewport (390x844 unless --viewport), touch, mobile user agent')
         .addOption(new Option('--reset', 'Back to the browser window size and the system setting').conflicts([
         'viewport',
         'colorScheme',
+        'mobile',
     ]))
         .addOption(jsonOption())
         .action(async (options) => {

package/dist/commands/peek.d.ts

@@ -2,5 +2,12 @@
  * Peek command for previewing collected session data.
  */
 import type { Command } from 'commander';
+import type { PeekCommandOptions } from './shared/optionTypes.js';
+/**
+ * Watch the session data (`peek --follow`, and the deprecated `tail`).
+ *
+ * @param options - Peek options (follow implied)
+ */
+export declare function followPreview(options: PeekCommandOptions): Promise<void>;
 export declare function registerPeekCommand(program: Command): void;
 //# sourceMappingURL=peek.d.ts.map