browser-debugger-cli 0.14.0 → 0.16.0

package/dist/runtime/dom/frames.js

@@ -529,12 +529,13 @@ export async function frameContextLostError(conn, page, frame) {
  * @param script - JavaScript expression
  * @param query - Requested frame (index, name/id attribute, or part of the name, id or URL)
  * @param listedIds - Frame id behind each index of the last `dom frames` listing, if any
+ * @param full - `--full`: copy the result with every entry
  * @returns Value, type and the frame's URL
  * @throws CommandError (81/83) when the frame is ambiguous or missing, (87)
  *   when an index names another frame than when it was listed, (83) when it
  *   navigated or was removed while the script ran, else as evaluateScript
  */
-export async function evaluateInFrame(page, wsUrl, script, query, listedIds) {
+export async function evaluateInFrame(page, wsUrl, script, query, listedIds, full = false) {
     return withFrameConnection(page, wsUrl, async (fc) => {
         const { frame, uniqueContextId } = await resolveFrame(fc, query, listedIds);
         try {
@@ -542,6 +543,7 @@ export async function evaluateInFrame(page, wsUrl, script, query, listedIds) {
                 ...(frame.sessionId && { sessionId: frame.sessionId }),
                 uniqueContextId,
                 recovery: recoverySender(fc, frame.sessionId),
+                full,
             });
             return { ...result, frame: frame.info.url };
         }

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

@@ -23,6 +23,15 @@ import type { Protocol } from '../../connection/typed-cdp.js';
 type PageConnection = Pick<CDPConnection, 'send'> & Partial<Pick<CDPConnection, 'on'>>;
 /** Name of bdg's isolated world (shown in DevTools' context selector) */
 export declare const BDG_WORLD_NAME = "bdg";
+/**
+ * Whether bdg's world is known for a connection: created or being created,
+ * and not forgotten since (the top frame navigated, or its contexts were
+ * cleared). Scripts left in a forgotten world went with its document.
+ *
+ * @param cdp - Connection to the page
+ * @returns True while the world is known
+ */
+export declare function hasBdgWorld(cdp: PageConnection): boolean;
 /**
  * `Runtime.evaluate` in bdg's world of the top frame. A call that names its
  * own context is sent as it is.

package/dist/runtime/page/bdgWorld.js

@@ -37,6 +37,17 @@ function worldContext(cdp) {
     worlds.set(cdp, created);
     return created;
 }
+/**
+ * Whether bdg's world is known for a connection: created or being created,
+ * and not forgotten since (the top frame navigated, or its contexts were
+ * cleared). Scripts left in a forgotten world went with its document.
+ *
+ * @param cdp - Connection to the page
+ * @returns True while the world is known
+ */
+export function hasBdgWorld(cdp) {
+    return worlds.has(cdp);
+}
 /**
  * Create the world in the top frame and forget it when the page changes.
  *

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

@@ -0,0 +1,119 @@
+/**
+ * Page emulation a screenshot changes for its capture, and puts back.
+ *
+ * A capture at a pixel ratio of 1 on a high-DPI page, and one beyond the
+ * viewport, override the device metrics (and hide the scrollbars). Each
+ * change is recorded before it is sent, so {@link CaptureEmulation.restore}
+ * (called once the capture ended, however it ended) undoes exactly what may
+ * have been changed: the session's emulation is put back from the daemon's
+ * own record of it as it is then (a `page emulate` during the capture
+ * counts), not from a file.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { ViewportSize } from '../../types.js';
+/** Width and height in CSS px */
+export interface Size {
+    width: number;
+    height: number;
+}
+/** A page position in CSS px */
+export interface ScrollPosition {
+    x: number;
+    y: number;
+}
+/**
+ * Evaluate one of bdg's page scripts and return its value.
+ *
+ * @param cdp - Session connection
+ * @param expression - Script
+ * @returns Its value, or undefined when it threw
+ */
+export declare function evaluateValue(cdp: CDPConnection, expression: string): Promise<unknown>;
+/**
+ * Two numbers a page script returned as an array.
+ *
+ * @param cdp - Session connection
+ * @param expression - Script returning `[a, b]`
+ * @returns The numbers, undefined where the page did not answer
+ */
+export declare function evaluatePair(cdp: CDPConnection, expression: string): Promise<[number | undefined, number | undefined]>;
+/**
+ * The page's scroll position.
+ *
+ * @param cdp - Session connection
+ * @returns Scroll offsets in CSS px
+ */
+export declare function scrollPosition(cdp: CDPConnection): Promise<ScrollPosition>;
+/**
+ * The emulation changes of one capture, undone by {@link restore}.
+ */
+export declare class CaptureEmulation {
+    private readonly connection;
+    private readonly sessionViewport;
+    private readonly cdp;
+    private metricsChanged;
+    private scrollbarsHidden;
+    private scrolledFrom;
+    /**
+     * @param connection - Session connection
+     * @param sessionViewport - Reads the session's emulated viewport
+     *   (`--viewport`, `--mobile`, `page emulate`) as it is now; put back
+     *   afterwards, none clears the override
+     */
+    constructor(connection: CDPConnection, sessionViewport: () => ViewportSize | undefined);
+    /**
+     * Capture at a pixel ratio of 1 (CSS px = image px) on a high-DPI page:
+     * the viewport is overridden at the session's viewport, else the window's
+     * size with its scrollbars (so the layout does not change).
+     *
+     * @param devicePixelRatio - Page's pixel ratio
+     * @param viewport - Visible viewport size, used when the page does not answer
+     */
+    useUnitPixelRatio(devicePixelRatio: number, viewport: Size): Promise<void>;
+    /**
+     * 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 size (CSS px, pixel ratio 1; still
+     * a phone in a phone session).
+     *
+     * @param view - Visible viewport size
+     */
+    keepLayoutWithoutScrollbars(view: Size): Promise<void>;
+    /**
+     * Record where the page was scrolled before the capture moved it, to
+     * scroll it back afterwards (the first position recorded wins).
+     *
+     * @param position - Scroll position before the capture
+     */
+    scrolledAwayFrom(position: ScrollPosition): void;
+    /**
+     * Put back what the capture changed: scrollbars shown, the session's
+     * device metrics (its viewport and a phone's touch input, which a capture
+     * beyond the viewport turns off), else none, and the scroll position. Each
+     * step runs even when an earlier one failed.
+     *
+     * @throws The first step's error, once every step ran
+     */
+    restore(): Promise<void>;
+    /**
+     * The steps {@link restore} runs, for what the capture changed.
+     *
+     * @returns Named steps, in order
+     */
+    private restoreSteps;
+    /**
+     * Put back the session's device metrics, or clear the override.
+     */
+    private restoreSessionMetrics;
+    /**
+     * 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
+     */
+    private windowSize;
+}
+//# sourceMappingURL=captureEmulation.d.ts.map

package/dist/runtime/page/captureEmulation.js

@@ -0,0 +1,189 @@
+/**
+ * Page emulation a screenshot changes for its capture, and puts back.
+ *
+ * A capture at a pixel ratio of 1 on a high-DPI page, and one beyond the
+ * viewport, override the device metrics (and hide the scrollbars). Each
+ * change is recorded before it is sent, so {@link CaptureEmulation.restore}
+ * (called once the capture ended, however it ended) undoes exactly what may
+ * have been changed: the session's emulation is put back from the daemon's
+ * own record of it as it is then (a `page emulate` during the capture
+ * counts), not from a file.
+ */
+import { TypedCDPConnection } from '../../connection/typed-cdp.js';
+import { evaluateInBdgWorld } from './bdgWorld.js';
+import { viewportOverride } from './emulation.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('dom');
+/**
+ * Evaluate one of bdg's page scripts and return its value.
+ *
+ * @param cdp - Session connection
+ * @param expression - Script
+ * @returns Its value, or undefined when it threw
+ */
+export async function evaluateValue(cdp, expression) {
+    const response = await evaluateInBdgWorld(cdp, { expression, returnByValue: true });
+    return response.result.value;
+}
+/**
+ * Two numbers a page script returned as an array.
+ *
+ * @param cdp - Session connection
+ * @param expression - Script returning `[a, b]`
+ * @returns The numbers, undefined where the page did not answer
+ */
+export async function evaluatePair(cdp, expression) {
+    const value = await evaluateValue(cdp, expression);
+    const [a, b] = Array.isArray(value) ? value : [];
+    return [a, b];
+}
+/**
+ * The page's scroll position.
+ *
+ * @param cdp - Session connection
+ * @returns Scroll offsets in CSS px
+ */
+export async function scrollPosition(cdp) {
+    const [x, y] = await evaluatePair(cdp, '[window.scrollX, window.scrollY]');
+    return { x: x ?? 0, y: y ?? 0 };
+}
+/**
+ * The emulation changes of one capture, undone by {@link restore}.
+ */
+export class CaptureEmulation {
+    connection;
+    sessionViewport;
+    cdp;
+    metricsChanged = false;
+    scrollbarsHidden = false;
+    scrolledFrom;
+    /**
+     * @param connection - Session connection
+     * @param sessionViewport - Reads the session's emulated viewport
+     *   (`--viewport`, `--mobile`, `page emulate`) as it is now; put back
+     *   afterwards, none clears the override
+     */
+    constructor(connection, sessionViewport) {
+        this.connection = connection;
+        this.sessionViewport = sessionViewport;
+        this.cdp = new TypedCDPConnection(connection);
+    }
+    /**
+     * Capture at a pixel ratio of 1 (CSS px = image px) on a high-DPI page:
+     * the viewport is overridden at the session's viewport, else the window's
+     * size with its scrollbars (so the layout does not change).
+     *
+     * @param devicePixelRatio - Page's pixel ratio
+     * @param viewport - Visible viewport size, used when the page does not answer
+     */
+    async useUnitPixelRatio(devicePixelRatio, viewport) {
+        if (devicePixelRatio === 1)
+            return;
+        const size = this.sessionViewport() ?? (await this.windowSize(viewport));
+        this.metricsChanged = true;
+        await this.cdp.send('Emulation.setDeviceMetricsOverride', viewportOverride(size, 1));
+    }
+    /**
+     * 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 size (CSS px, pixel ratio 1; still
+     * a phone in a phone session).
+     *
+     * @param view - Visible viewport size
+     */
+    async keepLayoutWithoutScrollbars(view) {
+        const phone = this.sessionViewport()?.mobile;
+        this.scrollbarsHidden = true;
+        await this.cdp.send('Emulation.setScrollbarsHidden', { hidden: true });
+        this.metricsChanged = true;
+        await this.cdp.send('Emulation.setDeviceMetricsOverride', viewportOverride({ ...view, ...(phone && { mobile: true }) }, 1));
+    }
+    /**
+     * Record where the page was scrolled before the capture moved it, to
+     * scroll it back afterwards (the first position recorded wins).
+     *
+     * @param position - Scroll position before the capture
+     */
+    scrolledAwayFrom(position) {
+        this.scrolledFrom ??= position;
+    }
+    /**
+     * Put back what the capture changed: scrollbars shown, the session's
+     * device metrics (its viewport and a phone's touch input, which a capture
+     * beyond the viewport turns off), else none, and the scroll position. Each
+     * step runs even when an earlier one failed.
+     *
+     * @throws The first step's error, once every step ran
+     */
+    async restore() {
+        const failures = [];
+        for (const [name, step] of this.restoreSteps()) {
+            try {
+                await step();
+            }
+            catch (error) {
+                log.debug(`Screenshot restore (${name}) failed: ${getErrorMessage(error)}`);
+                failures.push(error);
+            }
+        }
+        if (failures.length > 0)
+            throw failures[0];
+    }
+    /**
+     * The steps {@link restore} runs, for what the capture changed.
+     *
+     * @returns Named steps, in order
+     */
+    restoreSteps() {
+        const steps = [];
+        if (this.scrollbarsHidden) {
+            steps.push([
+                'scrollbars',
+                () => this.cdp.send('Emulation.setScrollbarsHidden', { hidden: false }),
+            ]);
+        }
+        if (this.metricsChanged)
+            steps.push(['device metrics', () => this.restoreSessionMetrics()]);
+        const scrolledFrom = this.scrolledFrom;
+        if (scrolledFrom) {
+            const { x, y } = scrolledFrom;
+            steps.push(['scroll', () => evaluateValue(this.connection, `window.scrollTo(${x}, ${y})`)]);
+        }
+        return steps;
+    }
+    /**
+     * Put back the session's device metrics, or clear the override.
+     */
+    async restoreSessionMetrics() {
+        const viewport = this.sessionViewport();
+        if (!viewport) {
+            await this.cdp.send('Emulation.clearDeviceMetricsOverride', {});
+            return;
+        }
+        await this.cdp.send('Emulation.setDeviceMetricsOverride', viewportOverride(viewport));
+        if (viewport.mobile) {
+            await this.cdp.send('Emulation.setTouchEmulationEnabled', {
+                enabled: true,
+                maxTouchPoints: 5,
+            });
+        }
+    }
+    /**
+     * 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 windowSize(viewport) {
+        const [width, height] = await evaluatePair(this.connection, '[window.innerWidth, window.innerHeight]');
+        return {
+            width: Math.round(width ?? viewport.width),
+            height: Math.round(height ?? viewport.height),
+        };
+    }
+}
+//# sourceMappingURL=captureEmulation.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Scrolling an element into view for a page screenshot (`--scroll`), and
+ * waiting for the page to settle afterwards (lazy loading, mutations).
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import { type ScrollPosition } from './captureEmulation.js';
+/**
+ * Scroll an element into view (centered) and wait for the page to settle.
+ *
+ * @param cdp - Session connection
+ * @param selector - The element
+ * @returns Scroll position before, to put the page back afterwards
+ * @throws CommandError (83) when nothing matches
+ */
+export declare function scrollToElement(cdp: CDPConnection, selector: string): Promise<ScrollPosition>;
+/**
+ * Scroll an element into view again (centered), e.g. after an override moved
+ * the page.
+ *
+ * @param cdp - Session connection
+ * @param selector - The element
+ */
+export declare function scrollIntoViewAgain(cdp: CDPConnection, selector: string): Promise<void>;
+//# sourceMappingURL=captureScroll.d.ts.map

package/dist/runtime/page/captureScroll.js

@@ -0,0 +1,124 @@
+/**
+ * Scrolling an element into view for a page screenshot (`--scroll`), and
+ * waiting for the page to settle afterwards (lazy loading, mutations).
+ */
+import { CommandError } from '../../errors/index.js';
+import { noNodesFoundError } from '../../errors/messages.js';
+import { DEEP_QUERY_JS, selectorArgsJS } from '../dom/targetNode.js';
+import { evaluateValue } from './captureEmulation.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { delay } from '../../utils/async.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;
+/** Page-side: start recording resource loads and DOM mutations */
+const WATCH_STABILITY_JS = `(() => {
+  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;
+})()`;
+/** Page-side: milliseconds since the last resource load and DOM mutation */
+const STABILITY_JS = `(() => {
+  const state = window.__bdg_scrollStability;
+  if (!state) return { networkIdle: 999, domIdle: 999 };
+  return {
+    networkIdle: Date.now() - state.lastNetworkActivity,
+    domIdle: Date.now() - state.lastDomMutation
+  };
+})()`;
+/** Page-side: stop recording */
+const UNWATCH_STABILITY_JS = `(() => {
+  const state = window.__bdg_scrollStability;
+  if (state) {
+    state.perfObserver?.disconnect();
+    state.mutationObserver?.disconnect();
+    delete window.__bdg_scrollStability;
+  }
+})()`;
+/**
+ * Wait for the page to settle after a programmatic scroll (lazy-load idle +
+ * DOM mutation idle). Uses shorter thresholds than full page load.
+ *
+ * @param cdp - Session connection
+ */
+async function waitForPostScrollStability(cdp) {
+    const deadline = Date.now() + POST_SCROLL_MAX_WAIT_MS;
+    await evaluateValue(cdp, WATCH_STABILITY_JS);
+    try {
+        while (Date.now() < deadline) {
+            const value = (await evaluateValue(cdp, STABILITY_JS));
+            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 delay(STABILITY_CHECK_INTERVAL_MS);
+        }
+        log.debug('Post-scroll stability timeout, proceeding anyway');
+    }
+    finally {
+        await evaluateValue(cdp, UNWATCH_STABILITY_JS);
+    }
+}
+/**
+ * Scroll an element into view (centered) and wait for the page to settle.
+ *
+ * @param cdp - Session connection
+ * @param selector - The element
+ * @returns Scroll position before, to put the page back afterwards
+ * @throws CommandError (83) when nothing matches
+ */
+export async function scrollToElement(cdp, selector) {
+    const value = (await evaluateValue(cdp, `(() => {
+      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 };
+    })()`));
+    if (!value?.found) {
+        const err = noNodesFoundError(selector);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    await waitForPostScrollStability(cdp);
+    return { x: value.originalX ?? 0, y: value.originalY ?? 0 };
+}
+/**
+ * Scroll an element into view again (centered), e.g. after an override moved
+ * the page.
+ *
+ * @param cdp - Session connection
+ * @param selector - The element
+ */
+export async function scrollIntoViewAgain(cdp, selector) {
+    await evaluateValue(cdp, `(${DEEP_QUERY_JS})(${selectorArgsJS(selector)})[0]?.scrollIntoView({ block: 'center', behavior: 'instant' })`);
+}
+//# sourceMappingURL=captureScroll.js.map

package/dist/runtime/page/emulation.js

@@ -60,12 +60,13 @@ export async function applySessionEmulation(cdp, emulation) {
  */
 async function emulatePhone(cdp, on) {
     await cdp.send('Emulation.setTouchEmulationEnabled', { enabled: on, maxTouchPoints: on ? 5 : 1 });
-    const { userAgent } = (await cdp.send('Browser.getVersion', {}));
+    const version = (await cdp.send('Browser.getVersion', {}));
+    const { userAgent } = version;
     if (!on) {
-        const headless = userAgent.includes('HeadlessChrome');
-        await cdp.send('Emulation.setUserAgentOverride', { userAgent: headless ? userAgent : '' });
-        if (headless)
-            await hideHeadlessUserAgent(cdp, log);
+        if (userAgent.includes('HeadlessChrome'))
+            await hideHeadlessUserAgent(cdp, log, version);
+        else
+            await cdp.send('Emulation.setUserAgentOverride', { userAgent: '' });
         return;
     }
     const major = /Chrome\/(\d+)/.exec(userAgent)?.[1] ?? '';

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

@@ -0,0 +1,41 @@
+/**
+ * Screenshots of the page or one element (`bdg dom screenshot`), taken in the
+ * daemon: measuring, the emulation changes the capture needs, the capture and
+ * putting the emulation back all happen here, inside one `try`/`finally`, so
+ * a CLI interrupted mid-capture (Ctrl-C) cannot leave the page changed. The
+ * CLI only writes the returned image.
+ *
+ * The image travels base64-encoded in one IPC line: Chrome sends it the same
+ * way over its WebSocket (100 MiB at most), well below the IPC line limit
+ * (`MAX_JSONL_BUFFER_SIZE`).
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { DomScreenshotCommand, DomScreenshotData } from '../../ipc/protocol/commands.js';
+import { type BusyRecoveryOptions } from '../dom/evalHelpers.js';
+import type { ViewportSize } from '../../types.js';
+/** How a screenshot is run */
+export interface ScreenshotOptions {
+    /** Aborted when the requesting client disconnects: the capture is skipped, the restore runs */
+    abandoned?: AbortSignal | undefined;
+    /** When a busy page is checked */
+    recovery?: BusyRecoveryOptions;
+}
+/**
+ * Take a screenshot: of the element `backendNodeId` names, else of the page.
+ * Whatever emulation the capture changed is put back before this returns or
+ * throws, from the session's record of its emulation at that time.
+ *
+ * A page whose scripts keep it busy gets them terminated
+ * ({@link withBusyPageRecovery}, exit 102); the capture then ends, and the
+ * error is reported once its emulation is back, so the next command does not
+ * race the restore. A capture whose client left (Ctrl-C) is not taken once
+ * that is known: only the restore runs.
+ *
+ * @param cdp - Session connection
+ * @param params - What to capture and how
+ * @param sessionViewport - Reads the session's emulated viewport, if any
+ * @param options - When the client left, and when a busy page is checked (tests shorten it)
+ * @returns The image (base64) and what was captured
+ */
+export declare function takeScreenshot(cdp: CDPConnection, params: DomScreenshotCommand, sessionViewport: () => ViewportSize | undefined, options?: ScreenshotOptions): Promise<DomScreenshotData>;
+//# sourceMappingURL=screenshot.d.ts.map