browser-debugger-cli 0.8.0 → 0.10.0

package/dist/runtime/dom/frameLayout.js

@@ -0,0 +1,140 @@
+/**
+ * Layout of an element inside a cross-origin iframe that shares the page's
+ * process (an a11y query can return those).
+ *
+ * The element is measured in its own frame, whose scripts cannot see the top
+ * page, so its measurements are relative to the frame's viewport. The
+ * iframe element holding the frame is measured in its own document, and the
+ * element is placed in the top-level viewport through it: mapped by the
+ * frame's position and scale, clipped to the frame's viewport and to what clips the
+ * iframe, and fixed, scrolled or hidden as the iframe is.
+ */
+import { mapBox } from './frameScopedConnection.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('dom');
+/**
+ * Ids of all frames below a frame tree's root.
+ *
+ * @param tree - Frame tree
+ * @returns Frame ids, depth-first
+ */
+export function childFrameIds(tree) {
+    return (tree?.childFrames ?? []).flatMap((child) => [child.frame.id, ...childFrameIds(child)]);
+}
+/**
+ * Backend node id of the document holding an element.
+ *
+ * @param cdp - CDP connection
+ * @param objectId - Remote object of the element
+ * @returns The document's backend node id, if it could be read
+ */
+async function ownerDocumentId(cdp, objectId) {
+    const doc = (await cdp.send('Runtime.callFunctionOn', {
+        objectId,
+        functionDeclaration: 'function () { return this.ownerDocument; }',
+    }));
+    if (!doc.result.objectId)
+        return undefined;
+    const { node } = (await cdp.send('DOM.describeNode', {
+        objectId: doc.result.objectId,
+    }));
+    return node.backendNodeId;
+}
+/**
+ * The iframe element whose document holds an element.
+ *
+ * @param cdp - CDP connection
+ * @param objectId - Remote object of the element
+ * @returns Backend node id of the iframe element, undefined when not found
+ */
+export async function findFrameOwner(cdp, objectId) {
+    try {
+        const documentId = await ownerDocumentId(cdp, objectId);
+        const { frameTree } = (await cdp.send('Page.getFrameTree'));
+        for (const frameId of childFrameIds(frameTree)) {
+            const owner = (await cdp.send('DOM.getFrameOwner', {
+                frameId,
+            }));
+            const { node } = (await cdp.send('DOM.describeNode', {
+                backendNodeId: owner.backendNodeId,
+            }));
+            if (node.contentDocument?.backendNodeId === documentId)
+                return owner.backendNodeId;
+        }
+    }
+    catch (error) {
+        log.debug(`Frame owner not found: ${getErrorMessage(error)}`);
+    }
+    return undefined;
+}
+/**
+ * Overlap of boxes.
+ *
+ * @param boxes - Boxes (null ones are left out)
+ * @returns Overlap (zero size when they do not overlap)
+ */
+export function intersection(...boxes) {
+    const present = boxes.filter((box) => box !== null);
+    const left = Math.max(...present.map((box) => box.x));
+    const top = Math.max(...present.map((box) => box.y));
+    const right = Math.min(...present.map((box) => box.x + box.width));
+    const bottom = Math.min(...present.map((box) => box.y + box.height));
+    return { x: left, y: top, width: Math.max(0, right - left), height: Math.max(0, bottom - top) };
+}
+/**
+ * Whether a box lies inside another.
+ *
+ * @param inner - Inner box
+ * @param outer - Outer box
+ * @returns True when it does
+ */
+export function inside(inner, outer) {
+    return (inner.x >= outer.x &&
+        inner.y >= outer.y &&
+        inner.x + inner.width <= outer.x + outer.width &&
+        inner.y + inner.height <= outer.y + outer.height);
+}
+/**
+ * Place an element measured inside a cross-origin frame in the top-level
+ * viewport, through the measurements of the frame's iframe element: mapped by
+ * the frame's position and scale (border, padding, `transform`, `zoom`),
+ * clipped to the frame's viewport and to what clips the iframe.
+ *
+ * @param raw - The element, measured in its frame
+ * @param owner - The iframe element, measured in its document
+ * @param mapping - How the frame's viewport maps into the top-level viewport
+ * @returns The element's layout in the top-level page (unchanged when the
+ *   iframe could not be measured)
+ */
+export function placeInOwnerFrame(raw, owner, mapping) {
+    const frame = owner.elements[0];
+    if (!raw.page || !owner.page || !frame)
+        return raw;
+    const frameView = mapBox(mapping, { x: 0, y: 0, ...raw.page.viewport });
+    const elements = raw.elements.map((element) => {
+        const inner = element.geometry;
+        const outer = frame.geometry;
+        const rect = mapBox(mapping, inner.rect);
+        const ownClip = inner.clip ? mapBox(mapping, inner.clip) : null;
+        return {
+            ...element,
+            context: [frame.element, element.context].filter(Boolean).join(' > '),
+            geometry: {
+                ...inner,
+                rect,
+                clip: intersection(ownClip, frameView, outer.clip),
+                clipper: inner.clipper ?? (inside(rect, frameView) ? outer.clipper : frame.element),
+                hidden: inner.hidden ?? (outer.hidden ? 'inside a hidden iframe' : null),
+                invisible: inner.invisible ?? outer.invisible,
+                fixed: outer.fixed,
+                sticky: outer.sticky ?? false,
+                pageScroll: outer.pageScroll,
+                scrollLock: outer.scrollLock ?? null,
+                offset: mapping.origin,
+            },
+        };
+    });
+    return { ...raw, page: owner.page, elements, crossOriginFrame: false };
+}
+//# sourceMappingURL=frameLayout.js.map

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

@@ -0,0 +1,50 @@
+/**
+ * The origin a frame's scripts really run with, for `bdg dom frames`.
+ *
+ * Chrome reports `securityOrigin: "://"` for frames without an origin of
+ * their own (srcdoc, about:blank, data:) and the URL's origin for sandboxed
+ * frames, so neither tells whether the parent can reach the frame's
+ * document. The frame's default execution context knows: it reports the
+ * inherited origin for srcdoc and about:blank, and `"://"` for opaque ones
+ * (data: URLs, sandboxes without `allow-same-origin`). A frame that has no
+ * context yet falls back to the rules below; a frame inside an opaque one
+ * counts as opaque too (sandbox flags are inherited).
+ */
+/** Origin of documents that share no origin with anything */
+export declare const OPAQUE_ORIGIN = "null";
+/** What is known about a frame's origin */
+export interface FrameOriginFacts {
+    /** Frame URL */
+    url: string;
+    /** `Page.Frame.securityOrigin` */
+    securityOrigin: string;
+    /** Origin of the frame's default execution context, when it has one */
+    contextOrigin?: string | undefined;
+    /** Origin of the parent frame (already resolved) */
+    parentOrigin?: string | undefined;
+    /** `sandbox` attribute of the frame's element, when present */
+    sandbox?: string | undefined;
+}
+/**
+ * Whether a `sandbox` attribute makes the frame's origin opaque.
+ *
+ * @param sandbox - Attribute value (undefined when the attribute is missing)
+ * @returns True unless the attribute is missing or allows same-origin
+ */
+export declare function isOpaqueSandbox(sandbox: string | undefined): boolean;
+/**
+ * The origin a frame's scripts run with.
+ *
+ * @param facts - What Chrome reports about the frame
+ * @returns e.g. `https://example.com`, or `"null"` for an opaque origin
+ */
+export declare function effectiveFrameOrigin(facts: FrameOriginFacts): string;
+/**
+ * Whether the top page's scripts cannot reach a frame's document.
+ *
+ * @param origin - The frame's effective origin
+ * @param topOrigin - The page's effective origin
+ * @returns True for a different or opaque origin
+ */
+export declare function isCrossOrigin(origin: string, topOrigin: string): boolean;
+//# sourceMappingURL=frameOrigin.d.ts.map

package/dist/runtime/dom/frameOrigin.js

@@ -0,0 +1,62 @@
+/**
+ * The origin a frame's scripts really run with, for `bdg dom frames`.
+ *
+ * Chrome reports `securityOrigin: "://"` for frames without an origin of
+ * their own (srcdoc, about:blank, data:) and the URL's origin for sandboxed
+ * frames, so neither tells whether the parent can reach the frame's
+ * document. The frame's default execution context knows: it reports the
+ * inherited origin for srcdoc and about:blank, and `"://"` for opaque ones
+ * (data: URLs, sandboxes without `allow-same-origin`). A frame that has no
+ * context yet falls back to the rules below; a frame inside an opaque one
+ * counts as opaque too (sandbox flags are inherited).
+ */
+/** Origin of documents that share no origin with anything */
+export const OPAQUE_ORIGIN = 'null';
+/**
+ * Whether a reported origin names a real (tuple) origin.
+ *
+ * @param origin - Origin as Chrome reports it
+ * @returns False for `"://"`, `"null"` and empty
+ */
+function isTupleOrigin(origin) {
+    return origin !== undefined && origin !== '' && origin !== '://' && origin !== OPAQUE_ORIGIN;
+}
+/**
+ * Whether a `sandbox` attribute makes the frame's origin opaque.
+ *
+ * @param sandbox - Attribute value (undefined when the attribute is missing)
+ * @returns True unless the attribute is missing or allows same-origin
+ */
+export function isOpaqueSandbox(sandbox) {
+    if (sandbox === undefined)
+        return false;
+    return !sandbox.toLowerCase().split(/\s+/).includes('allow-same-origin');
+}
+/**
+ * The origin a frame's scripts run with.
+ *
+ * @param facts - What Chrome reports about the frame
+ * @returns e.g. `https://example.com`, or `"null"` for an opaque origin
+ */
+export function effectiveFrameOrigin(facts) {
+    if (facts.contextOrigin !== undefined) {
+        return isTupleOrigin(facts.contextOrigin) ? facts.contextOrigin : OPAQUE_ORIGIN;
+    }
+    if (isOpaqueSandbox(facts.sandbox) || facts.parentOrigin === OPAQUE_ORIGIN)
+        return OPAQUE_ORIGIN;
+    if (isTupleOrigin(facts.securityOrigin))
+        return facts.securityOrigin;
+    const inherits = facts.url === '' || facts.url.startsWith('about:');
+    return inherits && isTupleOrigin(facts.parentOrigin) ? facts.parentOrigin : OPAQUE_ORIGIN;
+}
+/**
+ * Whether the top page's scripts cannot reach a frame's document.
+ *
+ * @param origin - The frame's effective origin
+ * @param topOrigin - The page's effective origin
+ * @returns True for a different or opaque origin
+ */
+export function isCrossOrigin(origin, topOrigin) {
+    return origin === OPAQUE_ORIGIN || origin !== topOrigin;
+}
+//# sourceMappingURL=frameOrigin.js.map

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

@@ -5,7 +5,7 @@ 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 URL.
+ * 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
@@ -13,6 +13,17 @@ import type { DomFrame } from '../../ipc/protocol/commands.js';
  * @throws CommandError (81) when empty or ambiguous, (83) when nothing matches
  */
 export declare function selectFrame(frames: DomFrame[], query: string): DomFrame;
+/**
+ * Check that a `--frame` index still names the frame the last
+ * `bdg dom frames` listed at that index (frames added, removed or
+ * reordered since shift the indices; a navigation replaces every frame).
+ *
+ * @param query - Requested frame
+ * @param currentIds - Frame id of each frame now, by index
+ * @param listedIds - Frame id of each frame when last listed, undefined when never listed
+ * @throws CommandError (87) when the index names another frame (or none) now
+ */
+export declare function assertFrameIndexCurrent(query: string, currentIds: string[], listedIds: string[] | undefined): void;
 /**
  * Build a CommandError from a message and suggestion.
  *

package/dist/runtime/dom/frameSelection.js

@@ -2,11 +2,11 @@
  * Which iframe a `bdg dom eval --frame` value names.
  */
 import { CommandError } from '../../errors/index.js';
-import { ambiguousFrameError, emptyFrameError, frameNotFoundError } from '../../errors/messages.js';
+import { ambiguousFrameError, emptyFrameError, frameNotFoundError, staleFrameIndexError, } 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 URL.
+ * 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
@@ -19,6 +19,25 @@ export function selectFrame(frames, query) {
         throw frameError(emptyFrameError(), EXIT_CODES.INVALID_ARGUMENTS);
     return single(frames, wanted, candidatesFor(frames, wanted));
 }
+/**
+ * Check that a `--frame` index still names the frame the last
+ * `bdg dom frames` listed at that index (frames added, removed or
+ * reordered since shift the indices; a navigation replaces every frame).
+ *
+ * @param query - Requested frame
+ * @param currentIds - Frame id of each frame now, by index
+ * @param listedIds - Frame id of each frame when last listed, undefined when never listed
+ * @throws CommandError (87) when the index names another frame (or none) now
+ */
+export function assertFrameIndexCurrent(query, currentIds, listedIds) {
+    const wanted = query.trim();
+    if (!listedIds || !/^\d+$/.test(wanted))
+        return;
+    const index = Number(wanted);
+    if (currentIds[index] === listedIds[index])
+        return;
+    throw frameError(staleFrameIndexError(index), EXIT_CODES.STALE_CACHE);
+}
 /**
  * Frames a non-empty `--frame` value matches, by the first rule that applies.
  *
@@ -33,7 +52,7 @@ function candidatesFor(frames, wanted) {
     if (named.length > 0)
         return named;
     const needle = wanted.toLowerCase();
-    return frames.filter((frame) => frame.url.toLowerCase().includes(needle));
+    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.