browser-debugger-cli 0.10.0 → 0.12.0

package/dist/runtime/dom/layout.js

@@ -81,7 +81,7 @@ const SAME_CLICK_TARGET_JS = `(node, hit) => {
 /**
  * Page function: layout of the matches in `found` (all up to `limit`, or the
  * one at `index`) and of the top-level page. An element covers another when
- * it is the topmost element at the center of the largest visible part of the
+ * it is painted above it at the center of the largest visible part of the
  * other's boxes (a wrapped link has one per line; the strip where overlay
  * scrollbars show is avoided when possible, {@link CLEAR_OF_SCROLLBAR_JS}) and does not lie inside it,
  * nor part of the element's own click target ({@link SAME_CLICK_TARGET_JS}: the link, button
@@ -91,7 +91,12 @@ const SAME_CLICK_TARGET_JS = `(node, hit) => {
  * `z-index`), as `dom click` finds: the element is in the hit-test stack below
  * the ancestor. Hit-testing goes up through the iframes, so an overlay over
  * an iframe covers the elements in it. Elements hit-testing skips
- * (`pointer-events: none`, also through an iframe) get no cover.
+ * (`pointer-events: none`, also through an iframe) get no cover. The cover
+ * named is the first element above that paints there (a sticky header's
+ * background, not the transparent logo on it; inside a shadow host, what its
+ * shadow root paints), else the topmost one, marked transparent; named by
+ * its outermost fixed or sticky ancestor that does not hold the element (the
+ * fixed banner, not a span inside it).
  */
 const LAYOUT_JS = `function (found, index, limit) {
   const geometryOf = ${ELEMENT_GEOMETRY_JS};
@@ -121,13 +126,21 @@ const LAYOUT_JS = `function (found, index, limit) {
     return false;
   };
   const sameTarget = ${SAME_CLICK_TARGET_JS};
+  const paintsAt = (n, x, y) => {
+    if (!paintsNothing(n)) return true;
+    if (!n.shadowRoot) return false;
+    return n.shadowRoot.elementsFromPoint(x, y).some((e) => e !== n && encloses(n, e) && !paintsNothing(e));
+  };
   const coverAt = (node, x, y) => {
     const root = node.getRootNode();
-    const scope = typeof root.elementFromPoint === 'function' ? root : node.ownerDocument;
-    const hit = scope.elementFromPoint(x, y);
-    if (!hit || encloses(node, hit) || sameTarget(node, hit)) return null;
-    if (!encloses(hit, node)) return hit;
-    return scope.elementsFromPoint(x, y).indexOf(node) > 0 ? hit : null;
+    const scope = typeof root.elementsFromPoint === 'function' ? root : node.ownerDocument;
+    const stack = scope.elementsFromPoint(x, y);
+    const at = stack.indexOf(node);
+    const above = (at < 0 ? stack.slice(0, 1) : stack.slice(0, at)).filter((hit) =>
+      !encloses(node, hit) && !sameTarget(node, hit) && (at >= 0 || !encloses(hit, node)));
+    if (above.length === 0) return null;
+    const painter = above.find((hit) => paintsAt(hit, x, y));
+    return { element: overlayOf(painter || above[0], node), transparent: !painter };
   };
   const visibleCenter = (el, g) => {
     const bounds = [{ x: 0, y: 0, width: page.viewport.width, height: page.viewport.height }].concat(g.clip ? [g.clip] : []);
@@ -154,7 +167,15 @@ const LAYOUT_JS = `function (found, index, limit) {
     const s = node.ownerDocument.defaultView.getComputedStyle(node);
     const clearColor = (c) => c === 'transparent' || /^rgba\\(.*,\\s*0\\)$/.test(c);
     const ownText = Array.from(node.childNodes).some((n) => n.nodeType === 3 && n.data.trim() !== '');
-    return clearColor(s.backgroundColor) && s.backgroundImage === 'none' && s.boxShadow === 'none' && !ownText;
+    const replaced = /^(img|video|canvas|iframe|embed|object|input|textarea|select)$/.test(node.localName);
+    return !replaced && clearColor(s.backgroundColor) && s.backgroundImage === 'none' && s.boxShadow === 'none' && !ownText;
+  };
+  const overlayOf = (hit, node) => {
+    let overlay = hit;
+    for (let p = hit.parentElement || (hit.parentNode && hit.parentNode.host); p && p !== p.ownerDocument.body && !encloses(p, node); p = p.parentElement || (p.parentNode && p.parentNode.host)) {
+      if (/^(fixed|sticky)$/.test(p.ownerDocument.defaultView.getComputedStyle(p).position)) overlay = p;
+    }
+    return overlay;
   };
   const hitTestable = (node) => node.ownerDocument.defaultView.getComputedStyle(node).pointerEvents !== 'none';
   const coveredBy = (el, g) => {
@@ -170,7 +191,7 @@ const LAYOUT_JS = `function (found, index, limit) {
       y += offset.y;
       cover = coverAt(view.frameElement, x, y);
     }
-    return cover ? { element: describe(cover), transparent: paintsNothing(cover) } : null;
+    return cover ? { element: describe(cover.element), transparent: cover.transparent } : null;
   };
   const elements = picked.map(([i, el]) => {
     const style = el.ownerDocument.defaultView.getComputedStyle(el);
@@ -334,6 +355,7 @@ function elementLayout(raw, page) {
         ...(inView && raw.cover?.transparent && { coverTransparent: true }),
         ...(raw.geometry.invisible && { invisible: raw.geometry.invisible }),
         ...(raw.geometry.inert && { inert: true }),
+        ...(raw.geometry.fixed && { fixed: true }),
         computed: raw.computed,
     };
 }

package/dist/runtime/dom/reactEventHelpers.d.ts

@@ -34,6 +34,13 @@ export declare const FIELD_VALUES_JS = "(field) => {\n  const fields = field.for
  * fillable kind of element. Messages are {@link FILL_REFUSALS}.
  */
 export declare const FILL_REFUSAL_JS: string;
+/**
+ * Page-side: the one text field, select or editable element in an element's
+ * open shadow root (a web component such as `<sl-input>` wrapping a native
+ * input), which `dom fill` fills in its place; null when the element is a
+ * field itself or its shadow root has none or several.
+ */
+export declare const SHADOW_FIELD_JS = "(el) => {\n  if (!el.shadowRoot || /^(input|textarea|select)$/.test(el.localName) || el.isContentEditable) return null;\n  const fields = el.shadowRoot.querySelectorAll('input:not([type=\"hidden\"]), textarea, select, [contenteditable]:not([contenteditable=\"false\"])');\n  return fields.length === 1 ? fields[0] : null;\n}";
 /**
  * JavaScript function to fill an input element in a React-compatible way.
  *

package/dist/runtime/dom/reactEventHelpers.js

@@ -94,8 +94,23 @@ export const FILL_REFUSAL_JS = `(el) => {
   if (el.closest('[inert]')) return refuse('inert', 'inside an inert element');
   if (el.getAttribute('aria-readonly') === 'true') return refuse('readOnly', 'aria-readonly="true"');
   if (el.getAttribute('aria-disabled') === 'true') return refuse('disabled', 'aria-disabled="true"');
+  if (el.shadowRoot) {
+    const fields = el.shadowRoot.querySelectorAll('input:not([type="hidden"]), textarea, select, [contenteditable]:not([contenteditable="false"])').length;
+    return refuse('notFillable', '<' + tag + '> has ' + (fields === 0 ? 'no field' : fields + ' fields') + ' in its shadow root; select the one to fill, e.g. its [part~=…] or class');
+  }
   return refuse('notFillable', '<' + tag + '> is not an input, textarea, select or contenteditable element');
 }`;
+/**
+ * Page-side: the one text field, select or editable element in an element's
+ * open shadow root (a web component such as `<sl-input>` wrapping a native
+ * input), which `dom fill` fills in its place; null when the element is a
+ * field itself or its shadow root has none or several.
+ */
+export const SHADOW_FIELD_JS = `(el) => {
+  if (!el.shadowRoot || /^(input|textarea|select)$/.test(el.localName) || el.isContentEditable) return null;
+  const fields = el.shadowRoot.querySelectorAll('input:not([type="hidden"]), textarea, select, [contenteditable]:not([contenteditable="false"])');
+  return fields.length === 1 ? fields[0] : null;
+}`;
 /**
  * JavaScript function to fill an input element in a React-compatible way.
  *
@@ -199,6 +214,9 @@ export const REACT_FILL_SCRIPT = `
   }
   const viaLabel = labelControl ? ${JSON.stringify(VIA_LABEL_SUFFIX)} : '';
   if (labelControl) el = labelControl;
+  const shadowField = (${SHADOW_FIELD_JS})(el);
+  const viaShadow = shadowField ? ' in the shadow root of <' + el.localName + '>' : '';
+  if (shadowField) el = shadowField;
 
   const tagName = el.tagName.toLowerCase();
   const inputType = el.type?.toLowerCase();
@@ -208,7 +226,7 @@ export const REACT_FILL_SCRIPT = `
     return {
       success: false,
       error: refusal.error,
-      elementType: tagName + viaLabel,
+      elementType: tagName + viaLabel + viaShadow,
       suggestion: refusal.suggestion,
       unsuitableElement: refusal.kind === 'notFillable'
     };
@@ -237,7 +255,7 @@ export const REACT_FILL_SCRIPT = `
         success: false,
         error: 'Option not found: ' + missing,
         exitCode: 81,
-        elementType: tagName + viaLabel,
+        elementType: tagName + viaLabel + viaShadow,
         suggestion: 'Available options: ' + options.slice(0, 10).map((o) => o.value || o.text.trim()).join(', ')
       };
     }
@@ -256,7 +274,7 @@ export const REACT_FILL_SCRIPT = `
         success: false,
         error: 'Option not found: ' + value,
         exitCode: 81,
-        elementType: tagName + viaLabel,
+        elementType: tagName + viaLabel + viaShadow,
         suggestion: 'Available options: ' + options.slice(0, 10).map((o) => o.value || o.text.trim()).join(', ')
       };
     }
@@ -274,7 +292,7 @@ export const REACT_FILL_SCRIPT = `
       return {
         success: false,
         error: 'Expected true or false for a ' + inputType + ', got "' + value + '"',
-        elementType: tagName + viaLabel,
+        elementType: tagName + viaLabel + viaShadow,
         inputType: inputType,
         suggestion: 'Use true/false (also yes/no, on/off, 1/0)'
       };
@@ -284,7 +302,7 @@ export const REACT_FILL_SCRIPT = `
       return {
         success: false,
         error: 'A radio button cannot be unchecked',
-        elementType: tagName + viaLabel,
+        elementType: tagName + viaLabel + viaShadow,
         inputType: inputType,
         suggestion: 'Select another option in the same group instead'
       };
@@ -297,7 +315,7 @@ export const REACT_FILL_SCRIPT = `
     return {
       success: false,
       fileInput: true,
-      elementType: tagName + viaLabel,
+      elementType: tagName + viaLabel + viaShadow,
       inputType: inputType,
       error: 'File input'
     };
@@ -323,7 +341,7 @@ export const REACT_FILL_SCRIPT = `
       return {
         success: false,
         error: 'Value is ' + value.length + ' characters; the field accepts at most ' + el.maxLength,
-        elementType: tagName + viaLabel,
+        elementType: tagName + viaLabel + viaShadow,
         inputType: inputType || null,
         suggestion: 'Shorten the value (a user could not type more than maxlength characters)'
       };
@@ -339,7 +357,7 @@ export const REACT_FILL_SCRIPT = `
       return {
         success: false,
         error: rejection.error,
-        elementType: tagName + viaLabel,
+        elementType: tagName + viaLabel + viaShadow,
         inputType: inputType,
         suggestion: rejection.suggestion
       };
@@ -368,7 +386,7 @@ export const REACT_FILL_SCRIPT = `
           ? Array.from(el.selectedOptions).map((o) => o.value).join(', ')
           : el.value,
     element: (${ELEMENT_IDENTITY_JS})(el),
-    elementType: tagName + viaLabel,
+    elementType: tagName + viaLabel + viaShadow,
     inputType: inputType || null,
     checked: inputType === 'checkbox' || inputType === 'radio' ? el.checked : undefined,
     matchCount: allMatches.length,

package/dist/runtime/page/emulation.d.ts

@@ -10,17 +10,18 @@ import type { CDPConnection } from '../../connection/cdp.js';
 import type { ColorScheme, ViewportSize } from '../../types.js';
 /**
  * `Emulation.setDeviceMetricsOverride` parameters for a session viewport: a
- * desktop viewport of that size at the display's own pixel ratio.
+ * desktop viewport of that size at the display's own pixel ratio, or a
+ * phone's (mobile layout: meta viewport, overlay scrollbars; pixel ratio 3).
  *
- * @param viewport - Viewport size in CSS px
- * @param deviceScaleFactor - Pixel ratio (0 keeps the display's)
+ * @param viewport - Viewport size in CSS px, `mobile` for a phone
+ * @param deviceScaleFactor - Pixel ratio (0 keeps the display's, or a phone's)
  * @returns CDP parameters
  */
 export declare function viewportOverride(viewport: ViewportSize, deviceScaleFactor?: number): {
     width: number;
     height: number;
     deviceScaleFactor: number;
-    mobile: false;
+    mobile: boolean;
 };
 /**
  * Apply the session's emulation to its page.
@@ -32,6 +33,14 @@ export declare function applySessionEmulation(cdp: CDPConnection, emulation: {
     viewport?: ViewportSize;
     colorScheme?: ColorScheme;
 }): Promise<void>;
+/**
+ * A mobile user agent from a desktop one: an Android platform, `Mobile`
+ * before `Safari`, and `Chrome` for `HeadlessChrome`.
+ *
+ * @param desktop - The browser's user agent
+ * @returns Mobile user agent
+ */
+export declare function mobileUserAgent(desktop: string): string;
 /** Page emulation of a session: what `--viewport` and `--color-scheme` set */
 export interface SessionEmulation {
     viewport?: ViewportSize;

package/dist/runtime/page/emulation.js

@@ -7,19 +7,29 @@
  * an attached Chrome (`--chrome-ws-url`) gets its own settings back.
  */
 import { VIEWPORT_SIZE_JS } from '../dom/elementGeometry.js';
+import { hideHeadlessUserAgent } from './userAgent.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
 const log = createLogger('session');
+/** Pixel ratio of an emulated phone (a common one) */
+const MOBILE_PIXEL_RATIO = 3;
 /**
  * `Emulation.setDeviceMetricsOverride` parameters for a session viewport: a
- * desktop viewport of that size at the display's own pixel ratio.
+ * desktop viewport of that size at the display's own pixel ratio, or a
+ * phone's (mobile layout: meta viewport, overlay scrollbars; pixel ratio 3).
  *
- * @param viewport - Viewport size in CSS px
- * @param deviceScaleFactor - Pixel ratio (0 keeps the display's)
+ * @param viewport - Viewport size in CSS px, `mobile` for a phone
+ * @param deviceScaleFactor - Pixel ratio (0 keeps the display's, or a phone's)
  * @returns CDP parameters
  */
 export function viewportOverride(viewport, deviceScaleFactor = 0) {
-    return { width: viewport.width, height: viewport.height, deviceScaleFactor, mobile: false };
+    const mobile = viewport.mobile === true;
+    return {
+        width: viewport.width,
+        height: viewport.height,
+        deviceScaleFactor: deviceScaleFactor || (mobile ? MOBILE_PIXEL_RATIO : 0),
+        mobile,
+    };
 }
 /**
  * Apply the session's emulation to its page.
@@ -30,6 +40,8 @@ export function viewportOverride(viewport, deviceScaleFactor = 0) {
 export async function applySessionEmulation(cdp, emulation) {
     if (emulation.viewport) {
         await cdp.send('Emulation.setDeviceMetricsOverride', viewportOverride(emulation.viewport));
+        if (emulation.viewport.mobile)
+            await emulatePhone(cdp, true);
     }
     if (emulation.colorScheme) {
         await cdp.send('Emulation.setEmulatedMedia', {
@@ -37,6 +49,55 @@ export async function applySessionEmulation(cdp, emulation) {
         });
     }
 }
+/**
+ * Turn the rest of a phone's emulation on or off: touch input (and
+ * `pointer: coarse`) and a mobile user agent derived from the browser's own
+ * (an Android one), or the browser's own back: the override cleared, or in
+ * headless Chrome its regular-Chrome identity ({@link hideHeadlessUserAgent}).
+ *
+ * @param cdp - Session connection
+ * @param on - Emulate a phone
+ */
+async function emulatePhone(cdp, on) {
+    await cdp.send('Emulation.setTouchEmulationEnabled', { enabled: on, maxTouchPoints: on ? 5 : 1 });
+    const { userAgent } = (await cdp.send('Browser.getVersion', {}));
+    if (!on) {
+        const headless = userAgent.includes('HeadlessChrome');
+        await cdp.send('Emulation.setUserAgentOverride', { userAgent: headless ? userAgent : '' });
+        if (headless)
+            await hideHeadlessUserAgent(cdp, log);
+        return;
+    }
+    const major = /Chrome\/(\d+)/.exec(userAgent)?.[1] ?? '';
+    await cdp.send('Emulation.setUserAgentOverride', {
+        userAgent: mobileUserAgent(userAgent.replace('HeadlessChrome/', 'Chrome/')),
+        platform: 'Android',
+        userAgentMetadata: {
+            brands: [
+                { brand: 'Google Chrome', version: major },
+                { brand: 'Chromium', version: major },
+            ],
+            platform: 'Android',
+            platformVersion: '10.0.0',
+            architecture: '',
+            model: 'K',
+            mobile: true,
+        },
+    });
+}
+/**
+ * A mobile user agent from a desktop one: an Android platform, `Mobile`
+ * before `Safari`, and `Chrome` for `HeadlessChrome`.
+ *
+ * @param desktop - The browser's user agent
+ * @returns Mobile user agent
+ */
+export function mobileUserAgent(desktop) {
+    return desktop
+        .replace(/\([^)]*\)/, '(Linux; Android 10; K)')
+        .replace('HeadlessChrome/', 'Chrome/')
+        .replace(/ (Mobile )?Safari\//, ' Mobile Safari/');
+}
 /**
  * Change the page emulation mid-session (`bdg page emulate`): set the
  * viewport or the color scheme, or clear both (back to the browser window
@@ -58,6 +119,8 @@ export async function emulatePage(cdp, current, change, record) {
     };
     const { viewport: _viewport, colorScheme, ...rest } = state;
     if (change.reset || change.viewport) {
+        const wasPhone = current.viewport?.mobile === true;
+        const isPhone = change.viewport?.mobile === true;
         await step(() => change.viewport
             ? cdp.send('Emulation.setDeviceMetricsOverride', viewportOverride(change.viewport))
             : cdp.send('Emulation.clearDeviceMetricsOverride', {}), {
@@ -65,6 +128,8 @@ export async function emulatePage(cdp, current, change, record) {
             ...(colorScheme && { colorScheme }),
             ...(change.viewport && { viewport: change.viewport }),
         });
+        if (wasPhone !== isPhone)
+            await step(() => emulatePhone(cdp, isPhone), state);
     }
     if (change.reset || change.colorScheme) {
         const { colorScheme: _scheme, ...withoutScheme } = state;

package/dist/runtime/page/userAgent.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The session's user agent in headless Chrome: regular Chrome's string and
+ * client hints, so sites serve the page a user sees.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { Logger } from '../../ui/logging/index.js';
+/**
+ * Send the user agent and client hints of regular Chrome from headless
+ * Chrome: sites serve "HeadlessChrome" a different page (or a bot
+ * challenge), so the page would not be the one a user sees. Not for a
+ * session emulating a phone, whose emulation sets a mobile user agent.
+ *
+ * @param cdp - CDP connection
+ * @param logger - Logger for failures (the session works without it)
+ */
+export declare function hideHeadlessUserAgent(cdp: CDPConnection, logger: Logger): Promise<void>;
+//# sourceMappingURL=userAgent.d.ts.map

package/dist/runtime/page/userAgent.js

@@ -0,0 +1,57 @@
+/**
+ * The session's user agent in headless Chrome: regular Chrome's string and
+ * client hints, so sites serve the page a user sees.
+ */
+import { getErrorMessage } from '../../utils/errors.js';
+/** Reads the client hints Chrome reports, renaming the HeadlessChrome brand */
+const USER_AGENT_METADATA_SCRIPT = `(async () => {
+  const data = navigator.userAgentData;
+  if (!data) return null;
+  const values = await data.getHighEntropyValues(
+    ['architecture', 'bitness', 'model', 'platformVersion', 'fullVersionList', 'wow64']
+  );
+  const rename = (list) => (list || []).map((entry) => ({
+    brand: entry.brand.replace('HeadlessChrome', 'Google Chrome'),
+    version: entry.version,
+  }));
+  return {
+    brands: rename(values.brands),
+    fullVersionList: rename(values.fullVersionList),
+    platform: values.platform,
+    platformVersion: values.platformVersion,
+    architecture: values.architecture,
+    model: values.model,
+    mobile: values.mobile,
+    bitness: values.bitness,
+    wow64: values.wow64,
+  };
+})()`;
+/**
+ * Send the user agent and client hints of regular Chrome from headless
+ * Chrome: sites serve "HeadlessChrome" a different page (or a bot
+ * challenge), so the page would not be the one a user sees. Not for a
+ * session emulating a phone, whose emulation sets a mobile user agent.
+ *
+ * @param cdp - CDP connection
+ * @param logger - Logger for failures (the session works without it)
+ */
+export async function hideHeadlessUserAgent(cdp, logger) {
+    try {
+        const { userAgent } = (await cdp.send('Browser.getVersion'));
+        if (!userAgent.includes('HeadlessChrome'))
+            return;
+        const metadata = (await cdp.send('Runtime.evaluate', {
+            expression: USER_AGENT_METADATA_SCRIPT,
+            awaitPromise: true,
+            returnByValue: true,
+        }));
+        await cdp.send('Emulation.setUserAgentOverride', {
+            userAgent: userAgent.replace('HeadlessChrome', 'Chrome'),
+            ...(metadata.result?.value ? { userAgentMetadata: metadata.result.value } : {}),
+        });
+    }
+    catch (error) {
+        logger.debug(`User agent left as is: ${getErrorMessage(error)}`);
+    }
+}
+//# sourceMappingURL=userAgent.js.map

package/dist/types.d.ts

@@ -370,6 +370,8 @@ export type ColorScheme = 'light' | 'dark';
 export interface ViewportSize {
     width: number;
     height: number;
+    /** A phone: mobile viewport (meta viewport, overlay scrollbars), touch and a mobile user agent */
+    mobile?: true;
 }
 /**
  * The page (document) request an action sent, as far as it got: still
@@ -483,6 +485,8 @@ export interface ScreenshotResult {
          * descendants) made it larger than the border box
          */
         captured?: ElementBounds;
+        /** `--padding` given: CSS px of page added around the captured area */
+        padding?: number;
     };
     /** Capture mode used */
     captureMode?: 'full_page' | 'viewport';
@@ -668,4 +672,12 @@ export interface FormDiscoveryResult {
     }>;
     brief?: boolean | undefined;
 }
+/** Agent whose skill directory receives the bdg skill (`bdg install-skill`). */
+export type SkillTarget = 'claude' | 'agents';
+/** What `bdg install-skill` did to the skill file in one agent's skill directory. */
+export interface InstalledSkill {
+    target: SkillTarget;
+    path: string;
+    status: 'installed' | 'updated' | 'unchanged';
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/ui/formatters/audit.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Human output of `bdg dom audit` and `bdg css search`.
+ */
+import type { AuditResult, CssSearchResult } from '../../ipc/protocol/auditTypes.js';
+/**
+ * Format `bdg dom audit`.
+ *
+ * @param data - Audit result
+ * @returns Output
+ */
+export declare function formatAudit(data: AuditResult): string;
+/**
+ * Format `bdg css search`.
+ *
+ * @param data - Search result
+ * @returns Output
+ */
+export declare function formatCssSearch(data: CssSearchResult): string;
+//# sourceMappingURL=audit.d.ts.map

package/dist/ui/formatters/audit.js

@@ -0,0 +1,106 @@
+/**
+ * Human output of `bdg dom audit` and `bdg css search`.
+ */
+import { truncateByLength } from '../../utils/strings.js';
+/** Width of the text quoted in a finding */
+const TEXT_WIDTH = 50;
+/**
+ * Format `bdg dom audit`.
+ *
+ * @param data - Audit result
+ * @returns Output
+ */
+export function formatAudit(data) {
+    const sections = [
+        data.contrast && contrastSection(data.contrast),
+        data.overflow && overflowSection(data.overflow),
+        data.layers && layersSection(data.layers),
+        data.animations && animationsSection(data.animations),
+    ].filter((section) => section !== undefined);
+    const capped = data.capped ? [`(stopped after ${data.walked} elements; the page has more)`] : [];
+    return [...sections.flatMap((lines) => [...lines, '']), ...capped].join('\n').trimEnd();
+}
+/**
+ * The contrast section.
+ *
+ * @param contrast - Contrast findings
+ * @returns Lines
+ */
+function contrastSection(contrast) {
+    const head = `Contrast (${contrast.level}): ${contrast.failing} of ${contrast.checked} text elements below`;
+    const rows = contrast.items.map((item) => `  ${item.ratio.toFixed(2).padStart(5)}  ${item.color} on ${item.background}  ${item.element} "${truncateByLength(item.text, TEXT_WIDTH)}" ${item.size}px${item.weight >= 700 ? ' bold' : ''}${item.inView ? '' : ' (out of view)'}${item.approximate ? ` (approximate: ${item.approximate.join(', ')})` : ''}`);
+    const more = contrast.failing - contrast.items.length;
+    return [head, ...rows, ...(more > 0 ? [`  (+${more} more; --limit to list them)`] : [])];
+}
+/**
+ * The overflow section.
+ *
+ * @param overflow - Overflow findings
+ * @returns Lines
+ */
+function overflowSection(overflow) {
+    const head = overflow.scrollsSideways
+        ? `Overflow: the page is ${overflow.pageWidth} wide in a ${overflow.viewportWidth} viewport (it scrolls sideways)`
+        : `Overflow: nothing makes the page scroll sideways (${overflow.viewportWidth} wide)`;
+    return [
+        head,
+        ...overflow.wide.map((item) => `  past the right edge: ${item.element} (to ${item.right}, ${item.width} wide)`),
+        ...overflow.truncated.map((item) => `  cut off (${item.kind}): ${item.element}${times(item.count)} "${truncateByLength(item.text, TEXT_WIDTH)}"`),
+        ...overflow.scrollers.map((item) => `  scrolls sideways inside: ${item.element} (${item.scrollWidth} of content in ${item.width})`),
+        ...overflow.images.map((image) => `  image ${[image.upscaled && `upscaled ${image.scale}x${overflow.pixelRatio > 1 ? ` at pixel ratio ${overflow.pixelRatio}` : ''}`, image.distorted && 'distorted'].filter(Boolean).join(', ')}: ${image.element}${times(image.count)} ${image.natural.w}x${image.natural.h} pixels drawn at ${image.rendered.w}x${image.rendered.h} CSS px`),
+    ];
+}
+/**
+ * How many identical findings a row stands for.
+ *
+ * @param count - Count, when 2 or more
+ * @returns e.g. ` ×5`, or empty
+ */
+function times(count) {
+    return count ? ` ×${count}` : '';
+}
+/**
+ * The layers section.
+ *
+ * @param layers - Fixed and sticky elements
+ * @returns Lines
+ */
+function layersSection(layers) {
+    if (layers.length === 0)
+        return ['Layers: no fixed or sticky elements'];
+    return [
+        `Layers: ${layers.length} fixed or sticky`,
+        ...layers.map((layer) => `  ${layer.position} z ${layer.zIndex}  ${layer.element} ${layer.rect.w}x${layer.rect.h} at ${layer.rect.x},${layer.rect.y} of the viewport${layer.inView ? '' : ' (not in view now)'}`),
+    ];
+}
+/**
+ * The animations section.
+ *
+ * @param animations - Running animations
+ * @returns Lines
+ */
+function animationsSection(animations) {
+    if (animations.length === 0)
+        return ['Animations: none running'];
+    return [
+        `Animations: ${animations.length} running`,
+        ...animations.map((animation) => `  ${animation.name} on ${animation.element}${times(animation.count)} (${animation.type}, ${typeof animation.duration === 'number' ? `${animation.duration}ms` : animation.duration}, ${animation.iterations === 'infinite' ? 'infinite' : `${animation.iterations}x`}${animation.scrollDriven ? ', scroll-driven' : ''})`),
+    ];
+}
+/**
+ * Format `bdg css search`.
+ *
+ * @param data - Search result
+ * @returns Output
+ */
+export function formatCssSearch(data) {
+    if (data.total === 0)
+        return `"${data.query}" is not in the page's ${data.sheets} stylesheets`;
+    const more = data.total - data.matches.length;
+    return [
+        `"${data.query}": ${data.total} matches in ${data.sheets} stylesheets`,
+        ...data.matches.flatMap((match) => [`  ${match.source}`, `    ${match.text}`]),
+        ...(more > 0 ? [`  (+${more} more; --limit to list them)`] : []),
+    ].join('\n');
+}
+//# sourceMappingURL=audit.js.map

package/dist/ui/formatters/dom.d.ts

@@ -127,7 +127,7 @@ export declare function formatDomFrames(data: {
  * // Output: Screenshot saved to ./page.png (viewport only - page too tall)
  *
  * // An element whose floated children overflow it
- * // Output: Screenshot saved to ./el.png (grown from 940×37 to 940×285 to include content overflowing the element)
+ * // Output: Screenshot saved to ./el.png (grown from 940×37 to 940×285 to include what it paints outside its box (…))
  * ```
  */
 export declare function formatDomScreenshot(data: ScreenshotResult): string;

package/dist/ui/formatters/dom.js

@@ -1,6 +1,6 @@
 import { keyAttributeItems } from './keyAttributes.js';
 import { OutputFormatter } from '../formatting.js';
-import { frameLabel, moreMatchesNote, framesStillLoadingNote, noFramesMessage, queryNextSteps, screenshotGrownNote, viewportPositionHint, } from '../messages/commands.js';
+import { frameLabel, moreMatchesNote, framesStillLoadingNote, noFramesMessage, queryNextSteps, screenshotGrownNote, screenshotScaledNote, viewportPositionHint, } from '../messages/commands.js';
 /** Matches listed in human output (JSON has all of them) */
 const QUERY_DISPLAY_LIMIT = 50;
 /**
@@ -212,7 +212,7 @@ export function formatDomFrames(data) {
  * // Output: Screenshot saved to ./page.png (viewport only - page too tall)
  *
  * // An element whose floated children overflow it
- * // Output: Screenshot saved to ./el.png (grown from 940×37 to 940×285 to include content overflowing the element)
+ * // Output: Screenshot saved to ./el.png (grown from 940×37 to 940×285 to include what it paints outside its box (…))
  * ```
  */
 export function formatDomScreenshot(data) {
@@ -221,7 +221,10 @@ export function formatDomScreenshot(data) {
         output += ' (viewport only - page too tall)';
     }
     if (data.element?.captured) {
-        output += ` (${screenshotGrownNote(data.element.bounds, data.element.captured)})`;
+        output += ` (${screenshotGrownNote(data.element.bounds, data.element.captured, data.element.padding)})`;
+    }
+    if (data.resized && data.originalWidth !== undefined && data.originalHeight !== undefined) {
+        output += ` (${screenshotScaledNote(data.originalWidth, data.originalHeight, data.width, data.height)})`;
     }
     return output;
 }