browser-debugger-cli 0.14.0 → 0.16.0

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

@@ -1,682 +1,64 @@
 /**
- * CDP-relay helpers for screenshot capture.
- *
- * Covers page, element, and element-bounds operations plus the scroll-into-
- * view primitives used by page screenshots with `--scroll`.
+ * Screenshot capture for `bdg dom screenshot`: the daemon measures, captures
+ * and puts back the page's emulation (`dom_screenshot`); this writes the image
+ * it returns.
  */
-import { calculateImageTokens, calculateResizeScale, isTallPage, shouldResize, } from '../screenshotResize.js';
+import { interruptExitCode, interruptSignal, unlessInterrupted, } from '../../shared/interrupt.js';
 import { writeOutputFile } from '../../shared/outputFile.js';
-import { CDPConnectionError } from '../../../connection/errors.js';
 import { CommandError } from '../../../errors/index.js';
-import { noNodesFoundError, elementNotVisibleError, elementZeroDimensionsError, } from '../../../errors/messages.js';
-import { callBdgScript, callCDP } from '../../../ipc/client.js';
-import { DEEP_QUERY_JS, selectorArgsJS } from '../../../runtime/dom/targetNode.js';
-import { viewportOverride } from '../../../runtime/page/emulation.js';
-import { readSessionMetadata } from '../../../session/metadata.js';
-import { createLogger } from '../../../ui/logging/index.js';
+import { operationFailedError, screenshotInterruptedError } from '../../../errors/messages.js';
+import { domScreenshot } from '../../../ipc/client.js';
+import { sessionCommand } from '../../../ui/messages/sessionCommand.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
-const log = createLogger('dom');
-const POST_SCROLL_NETWORK_IDLE_MS = 150;
-const POST_SCROLL_DOM_STABLE_MS = 200;
-const POST_SCROLL_MAX_WAIT_MS = 2000;
-const STABILITY_CHECK_INTERVAL_MS = 50;
-/**
- * Wait for the page to settle after a programmatic scroll (lazy-load idle +
- * DOM mutation idle). Uses shorter thresholds than full page load.
- */
-async function waitForPostScrollStability() {
-    const deadline = Date.now() + POST_SCROLL_MAX_WAIT_MS;
-    await callBdgScript('Runtime.evaluate', {
-        expression: `
-      (() => {
-        window.__bdg_scrollStability = {
-          lastNetworkActivity: Date.now(),
-          lastDomMutation: Date.now(),
-          activeRequests: 0
-        };
-
-        const state = window.__bdg_scrollStability;
-
-        if (window.PerformanceObserver) {
-          const perfObserver = new PerformanceObserver((list) => {
-            for (const entry of list.getEntries()) {
-              if (entry.entryType === 'resource') {
-                state.lastNetworkActivity = Date.now();
-              }
-            }
-          });
-          try {
-            perfObserver.observe({ entryTypes: ['resource'] });
-            state.perfObserver = perfObserver;
-          } catch (e) {}
-        }
-
-        const mutationObserver = new MutationObserver(() => {
-          state.lastDomMutation = Date.now();
-        });
-        mutationObserver.observe(document.body || document.documentElement, {
-          childList: true,
-          subtree: true,
-          attributes: true
-        });
-        state.mutationObserver = mutationObserver;
-      })()
-    `,
-        returnByValue: true,
-    });
-    try {
-        while (Date.now() < deadline) {
-            const checkResult = await callBdgScript('Runtime.evaluate', {
-                expression: `
-          (() => {
-            const state = window.__bdg_scrollStability;
-            if (!state) return { networkIdle: 999, domIdle: 999 };
-            return {
-              networkIdle: Date.now() - state.lastNetworkActivity,
-              domIdle: Date.now() - state.lastDomMutation
-            };
-          })()
-        `,
-                returnByValue: true,
-            });
-            const value = checkResult.data?.result?.result?.value;
-            const networkIdle = value?.networkIdle ?? 0;
-            const domIdle = value?.domIdle ?? 0;
-            if (networkIdle >= POST_SCROLL_NETWORK_IDLE_MS && domIdle >= POST_SCROLL_DOM_STABLE_MS) {
-                log.debug(`Post-scroll stable: network ${networkIdle}ms, DOM ${domIdle}ms`);
-                return;
-            }
-            await new Promise((resolve) => setTimeout(resolve, STABILITY_CHECK_INTERVAL_MS));
-        }
-        log.debug('Post-scroll stability timeout, proceeding anyway');
-    }
-    finally {
-        await callBdgScript('Runtime.evaluate', {
-            expression: `
-        (() => {
-          const state = window.__bdg_scrollStability;
-          if (state) {
-            state.perfObserver?.disconnect();
-            state.mutationObserver?.disconnect();
-            delete window.__bdg_scrollStability;
-          }
-        })()
-      `,
-            returnByValue: true,
-        });
-    }
-}
-/**
- * Scroll an element into view before capture; returns the original scroll
- * position so it can be restored afterwards.
- */
-async function scrollToElement(selector) {
-    const result = await callBdgScript('Runtime.evaluate', {
-        expression: `
-      (() => {
-        const el = (${DEEP_QUERY_JS})(${selectorArgsJS(selector)})[0];
-        if (!el) return { found: false };
-        const originalX = window.scrollX;
-        const originalY = window.scrollY;
-        el.scrollIntoView({ block: 'center', behavior: 'instant' });
-        return { found: true, originalX, originalY };
-      })()
-    `,
-        returnByValue: true,
-    });
-    const value = result.data?.result?.result?.value;
-    if (!value?.found) {
-        const err = noNodesFoundError(selector);
-        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
-    }
-    await waitForPostScrollStability();
-    return { x: value.originalX ?? 0, y: value.originalY ?? 0 };
-}
-async function restoreScrollPosition(position) {
-    await callBdgScript('Runtime.evaluate', {
-        expression: `window.scrollTo(${position.x}, ${position.y})`,
-        returnByValue: true,
-    });
-}
-/**
- * The window's size with its scrollbars (`innerWidth`/`innerHeight`): an
- * override at this size keeps the page's layout, where the visible size
- * (without scrollbars) would narrow it and move centered content.
- *
- * @param viewport - Visible viewport size, used when the page does not answer
- * @returns Width and height in CSS px
- */
-async function windowSize(viewport) {
-    const response = await callBdgScript('Runtime.evaluate', {
-        expression: '[window.innerWidth, window.innerHeight]',
-        returnByValue: true,
-    });
-    const value = response.data?.result?.result?.value;
-    const [width, height] = Array.isArray(value) ? value : [];
-    return {
-        width: Math.round(width ?? viewport.clientWidth),
-        height: Math.round(height ?? viewport.clientHeight),
-    };
-}
-/**
- * Capture at a pixel ratio of 1 (CSS px = image px) on a high-DPI display:
- * the viewport is overridden at the window's size (the session's
- * `--viewport`, else the window with its scrollbars, so the layout does not
- * change) until the returned function puts back what was there before, the
- * session's viewport or none.
- *
- * @param devicePixelRatio - Page's pixel ratio
- * @param viewport - Visible viewport size
- * @returns Function restoring the device metrics
- */
-async function useUnitPixelRatio(devicePixelRatio, viewport) {
-    if (devicePixelRatio === 1)
-        return () => Promise.resolve();
-    const sessionViewport = readSessionMetadata()?.viewport;
-    const size = sessionViewport ?? (await windowSize(viewport));
-    await callCDP('Emulation.setDeviceMetricsOverride', viewportOverride(size, 1));
-    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
- * element via CDP DOM.getBoxModel.
- *
- * @param ref - Node reference
- * @returns Element bounds in CSS pixels
- */
-export async function getElementBounds(ref) {
-    const response = await callCDP('DOM.getBoxModel', ref);
-    const boxModel = response.data?.result;
-    if (!boxModel?.model?.border) {
-        const err = elementNotVisibleError();
-        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
-    }
-    const border = boxModel.model.border;
-    const x = border[0] ?? 0;
-    const y = border[1] ?? 0;
-    const width = (border[2] ?? 0) - x;
-    const height = (border[5] ?? 0) - y;
-    if (width <= 0 || height <= 0) {
-        const err = elementZeroDimensionsError();
-        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
-    }
-    return { x, y, width, height };
-}
-/**
- * Page coordinates of the visible area's top-left corner. A capture clip is
- * in page coordinates, so a viewport capture must start at the scroll
- * position, not at the page origin (which shows nothing once scrolled). Read
- * after any metrics override, which can move the scroll position.
- *
- * @returns Scroll offset of the visual viewport in CSS pixels
- */
-async function visibleAreaOrigin() {
-    const response = await callCDP('Page.getLayoutMetrics', {});
-    const metrics = response.data?.result;
-    const viewport = metrics?.cssVisualViewport;
-    return { x: viewport?.pageX ?? 0, y: viewport?.pageY ?? 0 };
-}
-/**
- * Capture a screenshot of the page. Auto-resizes oversized pages by default
- * to keep Claude Vision token cost bounded; falls back to viewport capture
- * when the page is taller than the tall-page threshold.
- */
-export async function capturePageScreenshot(outputPath, options = {}) {
-    const format = options.format ?? 'png';
-    const quality = format === 'jpeg' ? (options.quality ?? 90) : undefined;
-    const requestedFullPage = options.fullPage ?? true;
-    const noResize = options.noResize ?? false;
-    let originalScrollPosition;
-    if (options.scroll) {
-        originalScrollPosition = await scrollToElement(options.scroll);
-    }
-    const dprResponse = await callBdgScript('Runtime.evaluate', {
-        expression: 'window.devicePixelRatio',
-        returnByValue: true,
-    });
-    const devicePixelRatio = dprResponse.data?.result?.result?.value ?? 1;
-    const metricsResponse = await callCDP('Page.getLayoutMetrics', {});
-    const metricsResult = metricsResponse.data?.result;
-    const contentSize = metricsResult?.contentSize ?? { width: 0, height: 0 };
-    const viewport = metricsResult?.visualViewport ?? { clientWidth: 0, clientHeight: 0 };
-    const pageIsTooTall = !noResize && requestedFullPage && isTallPage(contentSize.width, contentSize.height);
-    const useScroll = options.scroll !== undefined;
-    const effectiveFullPage = useScroll ? false : pageIsTooTall ? false : requestedFullPage;
-    const captureWidth = effectiveFullPage ? contentSize.width : viewport.clientWidth;
-    const captureHeight = effectiveFullPage ? contentSize.height : viewport.clientHeight;
-    const resized = shouldResize(captureWidth, captureHeight, noResize);
-    const scale = resized ? calculateResizeScale(captureWidth, captureHeight) : 1;
-    const finalWidth = Math.round(captureWidth * scale);
-    const finalHeight = Math.round(captureHeight * scale);
-    const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, viewport);
-    if (devicePixelRatio !== 1) {
-        if (options.scroll) {
-            await callBdgScript('Runtime.evaluate', {
-                expression: `(${DEEP_QUERY_JS})(${selectorArgsJS(options.scroll)})[0]?.scrollIntoView({ block: 'center', behavior: 'instant' })`,
-                returnByValue: true,
-            });
-        }
-    }
-    const clipOrigin = effectiveFullPage ? { x: 0, y: 0 } : await visibleAreaOrigin();
-    let screenshotResult;
-    try {
-        const screenshotResponse = await callCDP('Page.captureScreenshot', {
-            format,
-            ...(quality !== undefined && { quality }),
-            captureBeyondViewport: effectiveFullPage,
-            clip: {
-                x: clipOrigin.x,
-                y: clipOrigin.y,
-                width: captureWidth,
-                height: captureHeight,
-                scale,
-            },
-        });
-        screenshotResult = screenshotResponse.data?.result;
-    }
-    finally {
-        await restoreMetrics();
-    }
-    if (!screenshotResult?.data) {
-        throw new CDPConnectionError('No screenshot data returned', new Error('Empty response'));
-    }
-    const buffer = Buffer.from(screenshotResult.data, 'base64');
-    const absolutePath = await writeOutputFile(outputPath, buffer);
-    const result = {
-        path: absolutePath,
-        format,
-        width: finalWidth,
-        height: finalHeight,
-        size: buffer.length,
-        fullPage: effectiveFullPage,
-        captureMode: effectiveFullPage ? 'full_page' : 'viewport',
-        finalTokens: calculateImageTokens(finalWidth, finalHeight),
-    };
-    if (quality !== undefined) {
-        result.quality = quality;
-    }
-    if (!effectiveFullPage) {
-        result.viewport = {
-            width: viewport.clientWidth,
-            height: viewport.clientHeight,
-        };
-    }
-    if (resized) {
-        result.resized = true;
-        result.originalWidth = captureWidth;
-        result.originalHeight = captureHeight;
-        result.originalTokens = calculateImageTokens(captureWidth, captureHeight);
-    }
-    if (pageIsTooTall && !useScroll) {
-        const aspectRatio = Math.round((contentSize.height / contentSize.width) * 10) / 10;
-        result.fullPageSkipped = {
-            reason: 'page_too_tall',
-            originalHeight: contentSize.height,
-            aspectRatio,
-        };
-        result.warning = `Full page capture skipped: page too tall (${aspectRatio}:1 aspect ratio). Only viewport captured.`;
-    }
-    if (useScroll && options.scroll) {
-        result.scrolledTo = options.scroll;
-    }
-    if (originalScrollPosition) {
-        await restoreScrollPosition(originalScrollPosition);
-    }
-    return result;
-}
-/** 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 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;
-  const scroller = this.ownerDocument.scrollingElement || this.ownerDocument.documentElement;
-  const own = this.getBoundingClientRect();
-  const reach = { left: own.left, top: own.top, right: own.right, bottom: own.bottom };
-  const page = { left: -view.scrollX, top: -view.scrollY, right: scroller.scrollWidth - view.scrollX, bottom: scroller.scrollHeight - view.scrollY };
-  const clips = (style) => style.overflowX !== 'visible' || style.overflowY !== 'visible';
-  let budget = ${OVERFLOW_SCAN_LIMIT};
-  const walk = (el) => {
-    for (const child of el.children) {
-      if (--budget < 0) return;
-      const style = view.getComputedStyle(child);
-      if (style.display === 'none' || style.position === 'fixed') continue;
-      const r = child.getBoundingClientRect();
-      if (r.width > 0 && r.height > 0 && style.visibility === 'visible') {
-        reach.left = Math.min(reach.left, Math.max(r.left, page.left));
-        reach.top = Math.min(reach.top, Math.max(r.top, page.top));
-        reach.right = Math.max(reach.right, Math.min(r.right, page.right));
-        reach.bottom = Math.max(reach.bottom, Math.min(r.bottom, page.bottom));
-      }
-      if (!clips(style)) walk(child);
-    }
-  };
-  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.
- *
- * @returns Width and height
- */
-async function visibleViewport() {
-    const metrics = (await callCDP('Page.getLayoutMetrics', {})).data?.result;
-    const view = metrics?.cssVisualViewport ?? metrics?.visualViewport;
-    return { width: view?.clientWidth ?? 0, height: view?.clientHeight ?? 0 };
-}
-/**
- * Whether an area (viewport coordinates) lies inside the viewport.
- *
- * @param area - Area
- * @param view - Viewport size
- * @returns True when fully inside
- */
-function insideView(area, view) {
-    return (area.x >= 0 &&
-        area.y >= 0 &&
-        area.x + area.width <= view.width &&
-        area.y + area.height <= view.height);
-}
 /**
- * Measure the area to capture and, when it fits in the viewport but is not
- * 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).
+ * The error of a screenshot interrupted by Ctrl-C or SIGTERM.
  *
- * @param ref - Node reference
- * @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
+ * @param signal - The signal
+ * @returns Command error (exit 130, or 143 for SIGTERM)
  */
-async function measureInView(ref, padding) {
-    const view = await visibleViewport();
-    let box = await getElementBounds(ref);
-    let bounds = await captureArea(ref, box, padding);
-    const fits = bounds.width <= view.width && bounds.height <= view.height;
-    if (!fits) {
-        await keepLayoutWithoutScrollbars(view);
-        box = await getElementBounds(ref);
-        return { box, bounds: await captureArea(ref, box, padding), inView: false };
-    }
-    if (insideView(bounds, view))
-        return { box, bounds, inView: true };
-    const scrolledFrom = await scrollPosition();
-    const dx = bounds.x + bounds.width / 2 - view.width / 2;
-    const dy = bounds.y + bounds.height / 2 - view.height / 2;
-    await callBdgScript('Runtime.evaluate', { expression: `window.scrollBy(${dx}, ${dy})` });
-    try {
-        box = await getElementBounds(ref);
-        bounds = await captureArea(ref, box, padding);
-    }
-    catch (error) {
-        await restoreScrollPosition(scrolledFrom);
-        throw error;
-    }
-    return { box, bounds, inView: insideView(bounds, view), scrolledFrom };
+export function screenshotInterrupted(signal) {
+    const err = screenshotInterruptedError(signal);
+    return new CommandError(err.message, { suggestion: err.suggestion }, interruptExitCode(signal));
 }
 /**
- * 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}.
+ * Ask the daemon for the capture. An interrupt ends the wait at once and
+ * closes the connection: the daemon skips the capture if it has not started,
+ * and puts the emulation back before it runs any later page command, so this
+ * need not wait.
  *
- * @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.
+ * @param request - What to capture and how
+ * @param interrupt - Aborted on Ctrl-C or SIGTERM
+ * @returns The daemon's response
+ * @throws CommandError (130/143) once interrupted
+ */
+async function requestCapture(request, interrupt) {
+    if (!interrupt)
+        return domScreenshot(request);
+    const capture = domScreenshot(request, interrupt);
+    const response = await unlessInterrupted(capture, interrupt, screenshotInterrupted);
+    if (interrupt.aborted)
+        throw screenshotInterrupted(interruptSignal(interrupt));
+    return response;
+}
+/**
+ * Capture the page (or the element `backendNodeId` names) and write the
+ * image.
  *
- * @returns Scroll offsets in CSS px
- */
-async function scrollPosition() {
-    const response = await callBdgScript('Runtime.evaluate', {
-        expression: '[window.scrollX, window.scrollY]',
-        returnByValue: true,
-    });
-    const value = response.data?.result?.result?.value;
-    const [x, y] = Array.isArray(value) ? value : [];
-    return { x: x ?? 0, y: y ?? 0 };
-}
-/** Overflow (px) below which the capture keeps to the border box (subpixel rounding) */
-const OVERFLOW_SLACK = 1;
-/**
- * Area an element screenshot captures: the border box, grown to the content
- * that overflows it ({@link CONTENT_OVERFLOW_JS}), so floated children are
- * not cropped away.
- *
- * @param ref - Node reference
- * @param bounds - Border box (DOM.getBoxModel coordinates)
- * @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 paintedArea(ref, bounds) {
-    const objectGroup = `bdg-shot-${process.pid}`;
-    try {
-        const resolved = await callBdgScript('DOM.resolveNode', { ...ref, objectGroup });
-        const objectId = resolved.data?.result?.object
-            .objectId;
-        if (!objectId)
-            return bounds;
-        const response = await callCDP('Runtime.callFunctionOn', {
-            objectId,
-            functionDeclaration: CONTENT_OVERFLOW_JS,
-            returnByValue: true,
-        });
-        const overflow = response.data?.result
-            ?.result?.value;
-        if (!overflow)
-            return bounds;
-        const [left, top, right, bottom] = ['left', 'top', 'right', 'bottom'].map((side) => Math.max(0, overflow[side] ?? 0));
-        if (Math.max(left, top, right, bottom) <= OVERFLOW_SLACK)
-            return bounds;
-        return {
-            x: bounds.x - left,
-            y: bounds.y - top,
-            width: bounds.width + left + right,
-            height: bounds.height + top + bottom,
-        };
-    }
-    catch (error) {
-        log.debug(`Could not measure overflowing content: ${String(error)}`);
-        return bounds;
-    }
-    finally {
-        await callCDP('Runtime.releaseObjectGroup', { objectGroup }).catch(() => undefined);
-    }
-}
-/**
- * Capture a screenshot of a single element: its border box, grown to include
- * content overflowing it ({@link captureArea}). The box model is relative to
- * the viewport and the capture clip to the page, so the page scroll is added
- * (the reported bounds are page coordinates, like `dom layout`'s).
- */
-export async function captureElementScreenshot(outputPath, ref, options = {}) {
-    const format = options.format ?? 'png';
-    const quality = format === 'jpeg' ? (options.quality ?? 90) : undefined;
-    const noResize = options.noResize ?? false;
-    const dprResponse = await callBdgScript('Runtime.evaluate', {
-        expression: 'window.devicePixelRatio',
-        returnByValue: true,
-    });
-    const devicePixelRatio = dprResponse.data?.result?.result?.value ?? 1;
-    const before = (await callCDP('Page.getLayoutMetrics', {})).data?.result;
-    const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, before?.visualViewport ?? { clientWidth: 800, clientHeight: 600 });
-    const restore = async (wide, scrolledFrom) => {
-        await (wide ? restoreViewport() : restoreMetrics());
-        if (scrolledFrom)
-            await restoreScrollPosition(scrolledFrom);
-    };
-    let measured;
-    try {
-        measured = await measureInView(ref, options.padding ?? 0);
-    }
-    catch (error) {
-        await restoreViewport();
-        throw error;
-    }
-    const { box, bounds, inView, scrolledFrom } = measured;
-    const originalWidth = bounds.width;
-    const originalHeight = bounds.height;
-    const resized = shouldResize(originalWidth, originalHeight, noResize);
-    const scale = resized ? calculateResizeScale(originalWidth, originalHeight) : 1;
-    const finalWidth = Math.round(originalWidth * scale);
-    const finalHeight = Math.round(originalHeight * scale);
-    const metricsResponse = await callCDP('Page.getLayoutMetrics', {});
-    const metricsResult = metricsResponse.data?.result;
-    const scroll = metricsResult?.cssLayoutViewport ?? { pageX: 0, pageY: 0 };
-    const onPage = (area) => ({
-        ...area,
-        x: area.x + scroll.pageX,
-        y: area.y + scroll.pageY,
-    });
-    const clip = onPage(bounds);
-    let screenshotResult;
-    try {
-        const screenshotResponse = await callCDP('Page.captureScreenshot', {
-            format,
-            ...(quality !== undefined && { quality }),
-            clip: { ...clip, scale },
-            captureBeyondViewport: !inView,
-        });
-        screenshotResult = screenshotResponse.data?.result;
-    }
-    finally {
-        await restore(!inView, scrolledFrom);
-    }
-    if (!screenshotResult?.data) {
-        throw new CDPConnectionError('No screenshot data returned', new Error('Empty response'));
-    }
-    const buffer = Buffer.from(screenshotResult.data, 'base64');
-    const absolutePath = await writeOutputFile(outputPath, buffer);
-    const result = {
-        path: absolutePath,
-        format,
-        width: finalWidth,
-        height: finalHeight,
-        size: buffer.length,
-        fullPage: false,
-        finalTokens: calculateImageTokens(finalWidth, finalHeight),
-        element: {
-            bounds: roundBounds(onPage(box)),
-            ...(bounds !== box && { captured: roundBounds(clip) }),
-            ...(options.padding && { padding: options.padding }),
-        },
-    };
-    if (quality !== undefined) {
-        result.quality = quality;
-    }
-    if (resized) {
-        result.resized = true;
-        result.originalWidth = originalWidth;
-        result.originalHeight = originalHeight;
-        result.originalTokens = calculateImageTokens(originalWidth, originalHeight);
-    }
-    return result;
-}
-/**
- * Bounds in whole pixels.
- *
- * @param bounds - Bounds
- * @returns Rounded bounds
- */
-function roundBounds(bounds) {
-    return {
-        x: Math.round(bounds.x),
-        y: Math.round(bounds.y),
-        width: Math.round(bounds.width),
-        height: Math.round(bounds.height),
-    };
+ * @param outputPath - File to write
+ * @param request - What to capture and how
+ * @param interrupt - Aborted on Ctrl-C or SIGTERM: the capture is cancelled
+ * @returns What was captured, with the file's absolute path
+ * @throws CommandError with the daemon's error (Chrome's, when the capture
+ *   failed) and exit code, or 130/143 when interrupted
+ */
+export async function captureScreenshot(outputPath, request, interrupt) {
+    const response = await requestCapture(request, interrupt);
+    if (response.status === 'error' || !response.data) {
+        const fallback = operationFailedError('take the screenshot', `Check the session: ${sessionCommand('bdg status')}`);
+        const suggestion = response.error === undefined ? fallback.suggestion : response.suggestion;
+        throw new CommandError(response.error ?? fallback.message, suggestion ? { suggestion } : {}, response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE);
+    }
+    const path = await writeOutputFile(outputPath, Buffer.from(response.data.image, 'base64'));
+    return { path, ...response.data.screenshot };
 }
 //# sourceMappingURL=screenshot.js.map