browser-debugger-cli 0.7.2 → 0.9.0

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

@@ -0,0 +1,92 @@
+/**
+ * Run the interaction scripts inside the frame of a cached element that the
+ * top page cannot reach.
+ *
+ * An element from `bdg dom a11y query` may be in a cross-origin iframe that
+ * shares the page's process (same site, e.g. a consent dialog served from a
+ * subdomain). The top page cannot hold it, so its page scripts run in the
+ * element's own frame instead: every `Runtime.evaluate` becomes a
+ * `Runtime.callFunctionOn` on the element (which runs in the element's
+ * context), and mouse events, whose coordinates the scripts measure in the
+ * frame's viewport, are mapped into the top-level viewport
+ * ({@link FrameMapping}).
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { LayoutBox, LayoutPoint } from '../../ipc/protocol/domTypes.js';
+/**
+ * How a point in a frame's viewport maps into the top-level viewport:
+ * `top = origin + frame * scale` per axis (the scale is not 1 when the
+ * iframe, or an ancestor of it, is scaled with `transform` or `zoom`).
+ */
+export interface FrameMapping {
+    /** Where the frame viewport's (0, 0) lies in the top-level viewport (border and padding included) */
+    origin: LayoutPoint;
+    scaleX: number;
+    scaleY: number;
+}
+/** A box as the frame and as CDP (top-level viewport) see it */
+interface ReferenceBox {
+    /** `getBoundingClientRect()` in the frame */
+    rect: LayoutBox;
+    /** `DOM.getContentQuads` (top-level viewport), each as x1,y1,…,x4,y4 */
+    quads: number[][];
+}
+/**
+ * `Runtime.callFunctionOn` parameters that evaluate an expression in the
+ * context of the element `objectId` refers to.
+ *
+ * @param params - `Runtime.evaluate` parameters
+ * @param objectId - Remote object of the element
+ * @returns Parameters for `Runtime.callFunctionOn`
+ * @throws Error for a parameter `Runtime.callFunctionOn` has no counterpart for
+ *   (e.g. `timeout`), so it is not dropped silently
+ */
+export declare function evaluateOnNodeParams(params: Record<string, unknown>, objectId: string): Record<string, unknown>;
+/**
+ * How the frame maps into the top-level viewport, from one box seen both ways.
+ *
+ * @param box - The reference box in the frame and in the top-level viewport
+ * @returns The mapping
+ * @throws CommandError (83) when the box has no quads or size, or is rotated or skewed
+ */
+export declare function frameMappingFrom(box: ReferenceBox): FrameMapping;
+/**
+ * Map a point of the frame's viewport into the top-level viewport.
+ *
+ * @param mapping - Frame mapping
+ * @param point - Point in the frame's viewport
+ * @returns Point in the top-level viewport
+ */
+export declare function mapPoint(mapping: FrameMapping, point: LayoutPoint): LayoutPoint;
+/**
+ * Map a box of the frame's viewport into the top-level viewport.
+ *
+ * @param mapping - Frame mapping
+ * @param box - Box in the frame's viewport
+ * @returns Box in the top-level viewport
+ */
+export declare function mapBox(mapping: FrameMapping, box: LayoutBox): LayoutBox;
+/**
+ * How the element's frame maps into the top-level viewport.
+ *
+ * @param cdp - CDP connection
+ * @param objectId - Remote object of the element
+ * @returns The mapping
+ * @throws CommandError (83) when the frame cannot be measured or is rotated or skewed
+ */
+export declare function measureFrameMapping(cdp: CDPConnection, objectId: string): Promise<FrameMapping>;
+/**
+ * A view of the session's connection whose page scripts run in the frame of
+ * one element and whose mouse events land on that frame.
+ *
+ * The mapping is measured at the first mouse event (after the scripts scrolled
+ * the element into view) and kept for the rest of the action; a failed
+ * measurement is not kept (the next event measures again) and fails the event.
+ *
+ * @param cdp - Session connection
+ * @param objectId - Remote object of the element
+ * @returns Connection to hand to the interaction functions
+ */
+export declare function frameScopedConnection(cdp: CDPConnection, objectId: string): CDPConnection;
+export {};
+//# sourceMappingURL=frameScopedConnection.d.ts.map

package/dist/runtime/dom/frameScopedConnection.js

@@ -0,0 +1,252 @@
+/**
+ * Run the interaction scripts inside the frame of a cached element that the
+ * top page cannot reach.
+ *
+ * An element from `bdg dom a11y query` may be in a cross-origin iframe that
+ * shares the page's process (same site, e.g. a consent dialog served from a
+ * subdomain). The top page cannot hold it, so its page scripts run in the
+ * element's own frame instead: every `Runtime.evaluate` becomes a
+ * `Runtime.callFunctionOn` on the element (which runs in the element's
+ * context), and mouse events, whose coordinates the scripts measure in the
+ * frame's viewport, are mapped into the top-level viewport
+ * ({@link FrameMapping}).
+ */
+import { CommandError } from '../../errors/index.js';
+import { frameMappingError } from '../../errors/messages.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/** `Runtime.evaluate` parameters that `Runtime.callFunctionOn` takes too */
+const SHARED_EVALUATE_PARAMS = [
+    'returnByValue',
+    'userGesture',
+    'awaitPromise',
+    'objectGroup',
+    'silent',
+    'generatePreview',
+    'throwOnSideEffect',
+    'serializationOptions',
+];
+/** `Runtime.evaluate` parameters with no `Runtime.callFunctionOn` counterpart */
+const UNSUPPORTED_EVALUATE_PARAMS = [
+    'timeout',
+    'contextId',
+    'uniqueContextId',
+    'includeCommandLineAPI',
+    'replMode',
+    'disableBreaks',
+    'allowUnsafeEvalBlockedByCSP',
+];
+/** Slack (CSS px) for rounding when telling a scaled frame from an unscaled one */
+const SCALE_SLACK_PX = 0.5;
+/**
+ * `Runtime.callFunctionOn` parameters that evaluate an expression in the
+ * context of the element `objectId` refers to.
+ *
+ * @param params - `Runtime.evaluate` parameters
+ * @param objectId - Remote object of the element
+ * @returns Parameters for `Runtime.callFunctionOn`
+ * @throws Error for a parameter `Runtime.callFunctionOn` has no counterpart for
+ *   (e.g. `timeout`), so it is not dropped silently
+ */
+export function evaluateOnNodeParams(params, objectId) {
+    const unsupported = UNSUPPORTED_EVALUATE_PARAMS.filter((key) => params[key] !== undefined);
+    if (unsupported.length > 0) {
+        throw new Error(`Runtime.evaluate in a frame cannot take ${unsupported.join(', ')}`);
+    }
+    const shared = Object.fromEntries(SHARED_EVALUATE_PARAMS.filter((key) => params[key] !== undefined).map((key) => [
+        key,
+        params[key],
+    ]));
+    return {
+        ...shared,
+        objectId,
+        functionDeclaration: `function () { return (\n${String(params['expression'])}\n); }`,
+    };
+}
+/**
+ * Error for a frame that cannot be placed in the top-level viewport.
+ *
+ * @param problem - What went wrong
+ * @param detail - Underlying error, if any
+ * @returns Not found (83) error
+ */
+function mappingError(problem, detail) {
+    const err = frameMappingError(problem, detail);
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+}
+/**
+ * Whether a quad is an axis-aligned rectangle (not rotated or skewed).
+ *
+ * @param quad - x1,y1,…,x4,y4 clockwise from the top left
+ * @returns True when its edges are horizontal and vertical
+ */
+function axisAligned(quad) {
+    const [x1, y1, x2, y2, x3, y3, x4, y4] = quad;
+    const near = (a, b) => Math.abs(a - b) <= SCALE_SLACK_PX;
+    return near(y1, y2) && near(x2, x3) && near(y3, y4) && near(x4, x1);
+}
+/**
+ * Scale along one axis: the length in the top-level viewport over the length
+ * in the frame, 1 when they differ by no more than rounding.
+ *
+ * @param top - Length in the top-level viewport
+ * @param frame - Length in the frame
+ * @returns Scale factor
+ */
+function axisScale(top, frame) {
+    return Math.abs(top - frame) <= SCALE_SLACK_PX ? 1 : top / frame;
+}
+/**
+ * How the frame maps into the top-level viewport, from one box seen both ways.
+ *
+ * @param box - The reference box in the frame and in the top-level viewport
+ * @returns The mapping
+ * @throws CommandError (83) when the box has no quads or size, or is rotated or skewed
+ */
+export function frameMappingFrom(box) {
+    const { rect, quads } = box;
+    if (quads.length === 0 || quads.some((quad) => quad.length !== 8))
+        throw mappingError('no-box');
+    if (rect.width <= 0 || rect.height <= 0)
+        throw mappingError('no-box');
+    if (!quads.every(axisAligned))
+        throw mappingError('rotated');
+    const xs = quads.flatMap((quad) => quad.filter((_, i) => i % 2 === 0));
+    const ys = quads.flatMap((quad) => quad.filter((_, i) => i % 2 === 1));
+    const left = Math.min(...xs);
+    const top = Math.min(...ys);
+    const scaleX = axisScale(Math.max(...xs) - left, rect.width);
+    const scaleY = axisScale(Math.max(...ys) - top, rect.height);
+    return { origin: { x: left - rect.x * scaleX, y: top - rect.y * scaleY }, scaleX, scaleY };
+}
+/**
+ * Map a point of the frame's viewport into the top-level viewport.
+ *
+ * @param mapping - Frame mapping
+ * @param point - Point in the frame's viewport
+ * @returns Point in the top-level viewport
+ */
+export function mapPoint(mapping, point) {
+    return {
+        x: mapping.origin.x + point.x * mapping.scaleX,
+        y: mapping.origin.y + point.y * mapping.scaleY,
+    };
+}
+/**
+ * Map a box of the frame's viewport into the top-level viewport.
+ *
+ * @param mapping - Frame mapping
+ * @param box - Box in the frame's viewport
+ * @returns Box in the top-level viewport
+ */
+export function mapBox(mapping, box) {
+    return {
+        ...mapPoint(mapping, box),
+        width: box.width * mapping.scaleX,
+        height: box.height * mapping.scaleY,
+    };
+}
+/**
+ * Page-side choice of the box to measure: the element's, or its document's
+ * root element when the element has no size (hidden, collapsed).
+ */
+const REFERENCE_NODE_FUNCTION = `function () {
+  const r = this.getBoundingClientRect();
+  return r.width > 0 && r.height > 0 ? this : this.ownerDocument.documentElement;
+}`;
+/** Page-side `getBoundingClientRect()` as a plain box */
+const CLIENT_RECT_FUNCTION = 'function () { const r = this.getBoundingClientRect(); return { x: r.left, y: r.top, width: r.width, height: r.height }; }';
+/**
+ * Measure a box of the element's frame both in the frame and through CDP.
+ *
+ * @param cdp - CDP connection
+ * @param objectId - Remote object of the element
+ * @returns The reference box
+ * @throws CommandError (83) when it cannot be read
+ */
+async function measureReferenceBox(cdp, objectId) {
+    try {
+        const reference = (await cdp.send('Runtime.callFunctionOn', {
+            objectId,
+            functionDeclaration: REFERENCE_NODE_FUNCTION,
+        }));
+        const referenceId = reference.result.objectId;
+        if (!referenceId)
+            throw mappingError('no-box');
+        const [quads, rect] = await Promise.all([
+            cdp.send('DOM.getContentQuads', {
+                objectId: referenceId,
+            }),
+            cdp.send('Runtime.callFunctionOn', {
+                objectId: referenceId,
+                functionDeclaration: CLIENT_RECT_FUNCTION,
+                returnByValue: true,
+            }),
+        ]);
+        const box = rect.result?.value;
+        if (!box)
+            throw mappingError('no-box');
+        return { rect: box, quads: quads.quads };
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        throw mappingError('unreadable', getErrorMessage(error));
+    }
+}
+/**
+ * How the element's frame maps into the top-level viewport.
+ *
+ * @param cdp - CDP connection
+ * @param objectId - Remote object of the element
+ * @returns The mapping
+ * @throws CommandError (83) when the frame cannot be measured or is rotated or skewed
+ */
+export async function measureFrameMapping(cdp, objectId) {
+    return frameMappingFrom(await measureReferenceBox(cdp, objectId));
+}
+/**
+ * A view of the session's connection whose page scripts run in the frame of
+ * one element and whose mouse events land on that frame.
+ *
+ * The mapping is measured at the first mouse event (after the scripts scrolled
+ * the element into view) and kept for the rest of the action; a failed
+ * measurement is not kept (the next event measures again) and fails the event.
+ *
+ * @param cdp - Session connection
+ * @param objectId - Remote object of the element
+ * @returns Connection to hand to the interaction functions
+ */
+export function frameScopedConnection(cdp, objectId) {
+    let mapping;
+    const measured = () => {
+        mapping ??= measureFrameMapping(cdp, objectId).catch((error) => {
+            mapping = undefined;
+            throw error;
+        });
+        return mapping;
+    };
+    const send = async (method, params = {}, sessionId) => {
+        if (sessionId !== undefined)
+            return cdp.send(method, params, sessionId);
+        if (method === 'Runtime.evaluate') {
+            return cdp.send('Runtime.callFunctionOn', evaluateOnNodeParams(params, objectId));
+        }
+        if (method === 'Input.dispatchMouseEvent') {
+            const point = mapPoint(await measured(), { x: Number(params['x']), y: Number(params['y']) });
+            return cdp.send(method, { ...params, ...point });
+        }
+        return cdp.send(method, params);
+    };
+    return new Proxy(cdp, {
+        get(target, property) {
+            if (property === 'send')
+                return send;
+            const value = Reflect.get(target, property, target);
+            return typeof value === 'function'
+                ? value.bind(target)
+                : value;
+        },
+    });
+}
+//# sourceMappingURL=frameScopedConnection.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * Which iframe a `bdg dom eval --frame` value names.
+ */
+import { CommandError } from '../../errors/index.js';
+import type { DomFrame } from '../../ipc/protocol/commands.js';
+/**
+ * Pick the frame a `--frame` value names: a 0-based index, an exact `name`
+ * or `id` attribute, or else a case-insensitive part of the name, id or URL.
+ *
+ * @param frames - Frames of the page
+ * @param query - Requested frame
+ * @returns The matching frame
+ * @throws CommandError (81) when empty or ambiguous, (83) when nothing matches
+ */
+export declare function selectFrame(frames: DomFrame[], query: string): DomFrame;
+/**
+ * Build a CommandError from a message and suggestion.
+ *
+ * @param err - Message and suggestion
+ * @param exitCode - Exit code
+ * @returns The error
+ */
+export declare function frameError(err: {
+    message: string;
+    suggestion: string;
+}, exitCode: number): CommandError;
+//# sourceMappingURL=frameSelection.d.ts.map

package/dist/runtime/dom/frameSelection.js

@@ -0,0 +1,66 @@
+/**
+ * Which iframe a `bdg dom eval --frame` value names.
+ */
+import { CommandError } from '../../errors/index.js';
+import { ambiguousFrameError, emptyFrameError, frameNotFoundError } from '../../errors/messages.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * Pick the frame a `--frame` value names: a 0-based index, an exact `name`
+ * or `id` attribute, or else a case-insensitive part of the name, id or URL.
+ *
+ * @param frames - Frames of the page
+ * @param query - Requested frame
+ * @returns The matching frame
+ * @throws CommandError (81) when empty or ambiguous, (83) when nothing matches
+ */
+export function selectFrame(frames, query) {
+    const wanted = query.trim();
+    if (!wanted)
+        throw frameError(emptyFrameError(), EXIT_CODES.INVALID_ARGUMENTS);
+    return single(frames, wanted, candidatesFor(frames, wanted));
+}
+/**
+ * Frames a non-empty `--frame` value matches, by the first rule that applies.
+ *
+ * @param frames - Frames of the page
+ * @param wanted - Requested frame, trimmed
+ * @returns Matching frames
+ */
+function candidatesFor(frames, wanted) {
+    if (/^\d+$/.test(wanted))
+        return frames.filter((frame) => frame.index === Number(wanted));
+    const named = frames.filter((frame) => frame.name === wanted || frame.id === wanted);
+    if (named.length > 0)
+        return named;
+    const needle = wanted.toLowerCase();
+    return frames.filter((frame) => [frame.name, frame.id, frame.url].some((text) => text?.toLowerCase().includes(needle)));
+}
+/**
+ * The only candidate, or an error listing the frames.
+ *
+ * @param frames - All frames (listed when nothing matches)
+ * @param query - Requested frame
+ * @param candidates - Matching frames
+ * @returns The candidate
+ * @throws CommandError (81) for several candidates, (83) for none
+ */
+function single(frames, query, candidates) {
+    const [first] = candidates;
+    if (candidates.length > 1) {
+        throw frameError(ambiguousFrameError(query, candidates), EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    if (!first)
+        throw frameError(frameNotFoundError(query, frames), EXIT_CODES.RESOURCE_NOT_FOUND);
+    return first;
+}
+/**
+ * Build a CommandError from a message and suggestion.
+ *
+ * @param err - Message and suggestion
+ * @param exitCode - Exit code
+ * @returns The error
+ */
+export function frameError(err, exitCode) {
+    return new CommandError(err.message, { suggestion: err.suggestion }, exitCode);
+}
+//# sourceMappingURL=frameSelection.js.map

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

@@ -0,0 +1,61 @@
+/**
+ * Iframes of the page for `bdg dom frames` and `bdg dom eval --frame`.
+ *
+ * Works on a short-lived second connection to the page target, so enabling
+ * Runtime (which replays the page's console messages) and attaching to
+ * out-of-process iframes never reach the session's collectors. In-process
+ * frames come from the page's frame tree; out-of-process (cross-site) frames
+ * from flattened auto-attach, each with its own session and frame tree.
+ * Execution context ids are shared by all sessions of a renderer, so a
+ * frame's default (main-world) context is found by enabling Runtime.
+ *
+ * A frame kept busy by its own scripts is recovered through the session's
+ * connection: a session attached while the target is busy gets no answer at
+ * all, not even to `Runtime.terminateExecution`.
+ */
+import { CDPConnection } from '../../connection/cdp.js';
+import type { CommandError } from '../../errors/index.js';
+import type { DomEvalData, DomFrame } from '../../ipc/protocol/commands.js';
+import { type CDPSender } from '../../telemetry/objectExpander.js';
+/**
+ * List the page's iframes.
+ *
+ * @param page - The session's connection
+ * @param wsUrl - WebSocket URL of the page target
+ * @returns Iframes in listing order
+ */
+export declare function listFrames(page: CDPConnection, wsUrl: string): Promise<DomFrame[]>;
+/** A frame whose script lost its context */
+export interface LostFrame {
+    frameId: string;
+    /** Session of the parent frame, which owns the iframe element */
+    ownerSession?: string;
+    /** Frame URL when the script started */
+    url: string;
+}
+/**
+ * The error for a script whose frame context went away: the page was
+ * closed, the frame navigated (its iframe element is still there) or was
+ * removed.
+ *
+ * @param conn - Connection the frame was found on
+ * @param page - The session's connection to the page
+ * @param frame - The frame
+ * @returns Command error (83)
+ * @throws Errors of the checks other than Chrome saying the frame is gone
+ */
+export declare function frameContextLostError(conn: Pick<CDPConnection, 'send'>, page: CDPSender, frame: LostFrame): Promise<CommandError>;
+/**
+ * Evaluate a `bdg dom eval` script in one iframe, like {@link evaluateScript}
+ * does in the page.
+ *
+ * @param page - The session's connection
+ * @param wsUrl - WebSocket URL of the page target
+ * @param script - JavaScript expression
+ * @param query - Requested frame (index, name/id attribute, or part of the name, id or URL)
+ * @returns Value, type and the frame's URL
+ * @throws CommandError (81/83) when the frame is ambiguous or missing, (83)
+ *   when it navigated or was removed while the script ran, else as evaluateScript
+ */
+export declare function evaluateInFrame(page: CDPConnection, wsUrl: string, script: string, query: string): Promise<DomEvalData>;
+//# sourceMappingURL=frames.d.ts.map