browser-debugger-cli 0.9.0 → 0.11.0

package/dist/runtime/dom/formFillHelpers/fill.js

@@ -5,12 +5,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { CommandError } from '../../../errors/index.js';
-import { fileNotFoundError, uploadDirectoryError, singleFileInputError, fillableElementNotFoundError, clickableElementNotFoundError, clickTargetDetachedError, unexpectedResponseFormatError, operationFailedError, } from '../../../errors/messages.js';
+import { fileNotFoundError, uploadDirectoryError, singleFileInputError, fillableElementNotFoundError, clickableElementNotFoundError, clickTargetDetachedError, unexpectedResponseFormatError, operationFailedError, pressNotReceivedError, unreachableElementError, } from '../../../errors/messages.js';
 import { escapeValueForJS, formatScriptExecutionError, throwIfInvalidSelector, withMultipleMatchesWarning, withValueMismatchWarning, } from './shared.js';
 import { FILL_READ_BACK_SCRIPT, REACT_FILL_SCRIPT, CLICK_ELEMENT_SCRIPT, isFillResult, isClickResult, } from '../reactEventHelpers.js';
 import { FIND_ELEMENTS_JS, LABEL_CONTROL_JS, selectorArgsJS } from '../targetNode.js';
 import { createLogger } from '../../../ui/logging/index.js';
-import { CLICK_NOT_RECEIVED_WARNING, POINTER_ACTION_DONE, domClickFallbackWarning, } from '../../../ui/messages/commands.js';
+import { CLICK_NOT_RECEIVED_WARNING, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, domClickFallbackWarning, } from '../../../ui/messages/commands.js';
 import { getErrorMessage } from '../../../utils/errors.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 const log = createLogger('dom');
@@ -266,64 +266,84 @@ export function mouseEvents(action, x, y) {
 }
 /**
  * Page script that stops the press probe installed by CLICK_ELEMENT_SCRIPT
- * and evaluates to whether the mouse press reached the target.
+ * and evaluates to whether the mouse press reached the target and, when it
+ * did not, the element it landed on (if the page saw it at all).
  */
 const PRESS_PROBE_READ_SCRIPT = `(() => {
   const probe = window.__bdgPressProbe;
   delete window.__bdgPressProbe;
-  if (!probe) return true;
+  if (!probe) return { reached: true };
   probe.stop();
-  return probe.reached;
+  return { reached: probe.reached, landedOn: probe.landedOn };
 })()`;
 /**
- * Whether the mouse press just dispatched reached the target element.
+ * Read the press probe: whether the mouse press just dispatched reached the
+ * target element, and otherwise where it landed.
  *
  * Any doubt (no probe, evaluation failure) counts as reached, so only a
  * press that the page provably never saw is reported.
  *
  * @param cdp - CDP connection
- * @returns False only when the target received no pointerdown/mousedown
+ * @returns Outcome; not reached only when the target received no pointerdown/mousedown
  */
-export async function pressReachedTarget(cdp) {
+async function readPressProbe(cdp) {
     try {
         const response = (await cdp.send('Runtime.evaluate', {
             expression: PRESS_PROBE_READ_SCRIPT,
             returnByValue: true,
         }));
-        return response.result?.value !== false;
+        const value = response.result?.value;
+        if (value?.reached !== false)
+            return { reached: true };
+        return typeof value.landedOn === 'string'
+            ? { reached: false, landedOn: value.landedOn }
+            : { reached: false };
     }
     catch (error) {
         log.debug(`Press probe not read: ${getErrorMessage(error)}`);
-        return true;
+        return { reached: true };
     }
 }
+/**
+ * Whether the mouse press just dispatched reached the target element
+ * (see {@link readPressProbe}).
+ *
+ * @param cdp - CDP connection
+ * @returns False only when the target received no pointerdown/mousedown
+ */
+export async function pressReachedTarget(cdp) {
+    return (await readPressProbe(cdp)).reached;
+}
 /**
  * Dispatch real mouse events for an action, checking after the first press
- * that the target received it. If dispatching fails first, the press probe
- * is still removed from the page.
+ * that the target received it. With `stopIfMissed`, a press that missed is
+ * only released (no further presses). If dispatching fails first, the press
+ * probe is still removed from the page.
  *
  * @param cdp - CDP connection
  * @param action - What to do
- * @param x - Page x
- * @param y - Page y
- * @returns False if the press never reached the target
+ * @param point - Page coordinates
+ * @param stopIfMissed - Stop after releasing a press that missed (--strict)
+ * @returns Whether the first press reached the target, and where it landed otherwise
  */
-async function dispatchMouseAction(cdp, action, x, y) {
-    let reached;
+async function dispatchMouseAction(cdp, action, point, stopIfMissed) {
+    let outcome;
     try {
-        for (const event of mouseEvents(action, x, y)) {
+        for (const event of mouseEvents(action, point.x, point.y)) {
             await cdp.send('Input.dispatchMouseEvent', event);
-            if (event['type'] === 'mousePressed' && reached === undefined) {
-                reached = await pressReachedTarget(cdp);
+            if (event['type'] === 'mouseReleased' && outcome?.reached === false && stopIfMissed)
+                break;
+            if (event['type'] === 'mousePressed' && outcome === undefined) {
+                outcome = await readPressProbe(cdp);
             }
         }
     }
     catch (error) {
-        if (reached === undefined)
-            await pressReachedTarget(cdp);
+        if (outcome === undefined)
+            await readPressProbe(cdp);
         throw error;
     }
-    return reached ?? true;
+    return outcome ?? { reached: true };
 }
 /**
  * Drop the located element from the page without waiting: right after a
@@ -337,34 +357,63 @@ function releaseClickTarget(cdp) {
         .send('Runtime.evaluate', { expression: 'delete window.__bdgClickTarget' })
         .catch((error) => log.debug(`Click target not released: ${getErrorMessage(error)}`));
 }
+/**
+ * Refuse a pointer action under `--strict` (exit 90, the page's state
+ * conflicts with the request): the element is unreachable by the mouse, or
+ * the press never reached it.
+ *
+ * @param result - Located click (selector and element description)
+ * @param action - What was refused
+ * @param why - Why the mouse could not reach it (nothing was sent), or the
+ *   press that was sent and missed
+ * @returns Never
+ * @throws CommandError always
+ */
+function refuseUnreachable(result, action, why) {
+    const target = { selector: result.selector ?? '', element: result.element };
+    const verb = POINTER_ACTION_NOUN[action];
+    const err = 'missed' in why
+        ? pressNotReceivedError(target, verb, why.missed.landedOn)
+        : unreachableElementError(target, why.obstruction, verb);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_CONFLICT);
+}
 /**
  * Click a located element.
  *
  * Uses real mouse events (pointerdown/mousedown/pointerup/mouseup/click, all
  * trusted) at the element's center when it is the topmost element there, so
  * components that react to pointer or mouse events (menus, selects) respond.
- * Otherwise (covered or zero-size) falls back to `el.click()` and says so.
+ * Otherwise (covered or zero-size) falls back to `el.click()` and says so,
+ * or with `strict` refuses (as it does when the press never reached it).
  * Double and right clicks, and hovering, work the same way.
  *
  * @param cdp - CDP connection
  * @param located - Locate result with center point
  * @param action - Click, double click, right click or hover
+ * @param strict - Refuse instead of falling back to DOM events
  * @returns Click result
+ * @throws CommandError under `strict` when a user could not reach the element
  */
-async function performClick(cdp, located, action) {
+async function performClick(cdp, located, action, strict) {
     const { x, y, hittable, obstruction, ...result } = located;
     if (!result.success)
         return result;
     if (hittable && x !== undefined && y !== undefined) {
-        const reached = await dispatchMouseAction(cdp, action, x, y);
+        const press = await dispatchMouseAction(cdp, action, { x, y }, strict);
         releaseClickTarget(cdp);
+        if (!press.reached && strict)
+            refuseUnreachable(result, action, { missed: press });
         return withMultipleMatchesWarning({
             ...result,
             action,
             method: 'mouse',
-            ...(!reached && { warning: CLICK_NOT_RECEIVED_WARNING }),
+            ...(!press.reached && { warning: CLICK_NOT_RECEIVED_WARNING }),
         }, result.selectedIndex, `${POINTER_ACTION_DONE[action].toLowerCase()} the first visible one`);
     }
+    if (strict) {
+        releaseClickTarget(cdp);
+        refuseUnreachable(result, action, { obstruction: obstruction ?? null });
+    }
     const response = (await cdp.send('Runtime.evaluate', {
         expression: domFallbackScript(action),
         returnByValue: true,
@@ -397,7 +446,7 @@ export async function clickElement(cdp, selector, options = {}) {
             throw new CommandError(errorMessage, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
         }
         if (cdpResponse.result?.value && isClickResult(cdpResponse.result.value)) {
-            return await performClick(cdp, cdpResponse.result.value, action);
+            return await performClick(cdp, cdpResponse.result.value, action, options.strict === true);
         }
         const err = unexpectedResponseFormatError('ClickResult');
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);

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

@@ -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,7 +2,7 @@
  * 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`
@@ -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.
  *

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

@@ -14,17 +14,47 @@
  * all, not even to `Runtime.terminateExecution`.
  */
 import { CDPConnection } from '../../connection/cdp.js';
+import type { Protocol } from '../../connection/typed-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';
+/** The default (main-world) execution context of a frame */
+interface FrameContext {
+    /** `ExecutionContextDescription.uniqueId` */
+    uniqueId: string;
+    /** Origin its scripts run with (`"://"` when opaque) */
+    origin: string;
+}
+/** A frame with the session that owns it */
+interface FrameNode {
+    frame: Protocol.Page.Frame;
+    sessionId?: string;
+    context?: FrameContext;
+}
+/** The page's iframes as listed, and the frame id behind each index */
+export interface FrameListing {
+    frames: DomFrame[];
+    /** Frame id of each listed frame, by index */
+    frameIds: string[];
+}
+/**
+ * Iframes below the main frame, depth-first, siblings in the document order
+ * of their iframe elements (frames without a known place last, in tree order).
+ *
+ * @param nodes - All frames
+ * @param mainFrameId - The page's main frame
+ * @param rank - Place of each frame among its siblings, by id
+ * @returns Iframes in listing order
+ */
+export declare function iframesInOrder<T extends Pick<FrameNode, 'frame'>>(nodes: T[], mainFrameId: string, rank: Map<string, number>): T[];
 /**
  * List the page's iframes.
  *
  * @param page - The session's connection
  * @param wsUrl - WebSocket URL of the page target
- * @returns Iframes in listing order
+ * @returns Iframes in listing order, and the frame id behind each index
  */
-export declare function listFrames(page: CDPConnection, wsUrl: string): Promise<DomFrame[]>;
+export declare function listFrames(page: CDPConnection, wsUrl: string): Promise<FrameListing>;
 /** A frame whose script lost its context */
 export interface LostFrame {
     frameId: string;
@@ -53,9 +83,12 @@ export declare function frameContextLostError(conn: Pick<CDPConnection, 'send'>,
  * @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)
+ * @param listedIds - Frame id behind each index of the last `dom frames` listing, if any
  * @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
+ * @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 declare function evaluateInFrame(page: CDPConnection, wsUrl: string, script: string, query: string): Promise<DomEvalData>;
+export declare function evaluateInFrame(page: CDPConnection, wsUrl: string, script: string, query: string, listedIds?: string[]): Promise<DomEvalData>;
+export {};
 //# sourceMappingURL=frames.d.ts.map

package/dist/runtime/dom/frames.js

@@ -18,7 +18,7 @@ import { CDPProtocolError } from '../../connection/errors.js';
 import { frameLostDuringEvalError, frameNavigatedDuringEvalError, frameNotReadyError, frameRemovedDuringEvalError, pageClosedDuringEvalError, } from '../../errors/messages.js';
 import { evaluateScript, isContextLostError, pageStillOpen, settledWithin, withBusyPageRecovery, } from './evalHelpers.js';
 import { effectiveFrameOrigin, isCrossOrigin } from './frameOrigin.js';
-import { frameError, selectFrame } from './frameSelection.js';
+import { assertFrameIndexCurrent, frameError, selectFrame } from './frameSelection.js';
 import { attachedSessionOf } from '../../telemetry/attachedTargets.js';
 import { senderFor } from '../../telemetry/objectExpander.js';
 import { createLogger } from '../../ui/logging/index.js';
@@ -27,6 +27,32 @@ import { EXIT_CODES } from '../../utils/exitCodes.js';
 const log = createLogger('dom');
 /** Auto-attach without pausing new targets: only existing frames are needed */
 const AUTO_ATTACH = { autoAttach: true, waitForDebuggerOnStart: false, flatten: true };
+/**
+ * Page function, called with iframe elements of one document: their
+ * indices in document order. Shadow roots are walked through their host
+ * (a shadow root's content comes before the host's children, as in
+ * shadow-including tree order).
+ */
+const DOCUMENT_ORDER_JS = `function (...nodes) {
+  const path = (node) => {
+    const nodesUp = [];
+    for (let n = node; n; n = n.parentNode || (n.nodeType === 11 ? n.host : null)) nodesUp.unshift(n);
+    return nodesUp;
+  };
+  const paths = nodes.map(path);
+  const compare = (i, j) => {
+    const a = paths[i];
+    const b = paths[j];
+    let depth = 0;
+    while (depth < a.length && depth < b.length && a[depth] === b[depth]) depth++;
+    const x = a[depth];
+    const y = b[depth];
+    if (!x || !y) return a.length - b.length;
+    if (x.nodeType === 11 || y.nodeType === 11) return x.nodeType === 11 ? -1 : 1;
+    return x.compareDocumentPosition(y) & 4 ? -1 : 1;
+  };
+  return nodes.map((_, i) => i).sort(compare);
+}`;
 /**
  * Run `work` on a second connection to the page, closed afterwards.
  *
@@ -188,16 +214,20 @@ function flattenTrees(trees) {
     return nodes;
 }
 /**
- * Iframes below the main frame, depth-first.
+ * Iframes below the main frame, depth-first, siblings in the document order
+ * of their iframe elements (frames without a known place last, in tree order).
  *
  * @param nodes - All frames
  * @param mainFrameId - The page's main frame
+ * @param rank - Place of each frame among its siblings, by id
  * @returns Iframes in listing order
  */
-function iframesInOrder(nodes, mainFrameId) {
+export function iframesInOrder(nodes, mainFrameId, rank) {
     const ordered = [];
+    const place = (node) => rank.get(node.frame.id) ?? Number.MAX_SAFE_INTEGER;
     const visit = (parentId) => {
-        for (const node of nodes.filter((n) => n.frame.parentId === parentId)) {
+        const children = nodes.filter((n) => n.frame.parentId === parentId);
+        for (const node of children.sort((a, b) => place(a) - place(b))) {
             ordered.push(node);
             visit(node.frame.id);
         }
@@ -220,21 +250,26 @@ function attributeValue(attributes = [], key) {
     return undefined;
 }
 /**
- * Attributes of the iframe element of a frame (read in its parent's session).
+ * The iframe element of a frame (read in its parent's session).
  *
  * @param fc - Frame connection
  * @param frameId - Frame
  * @param ownerSession - Session of the parent frame
- * @returns `name`, `id` and `sandbox` attributes when set
+ * @returns Its node, and `name`, `id` and `sandbox` attributes when set
  */
-async function ownerAttributes(fc, frameId, ownerSession) {
+async function frameOwner(fc, frameId, ownerSession) {
     try {
         const { backendNodeId } = await sendToSession(fc, 'DOM.getFrameOwner', { frameId }, ownerSession);
         const { node } = await sendToSession(fc, 'DOM.describeNode', { backendNodeId }, ownerSession);
         const name = attributeValue(node.attributes, 'name');
         const id = attributeValue(node.attributes, 'id');
         const sandbox = attributeValue(node.attributes, 'sandbox');
-        return { ...(name && { name }), ...(id && { id }), ...(sandbox !== undefined && { sandbox }) };
+        return {
+            backendNodeId,
+            ...(name && { name }),
+            ...(id && { id }),
+            ...(sandbox !== undefined && { sandbox }),
+        };
     }
     catch (error) {
         log.debug(`No iframe element for frame ${frameId}: ${getErrorMessage(error)}`);
@@ -317,8 +352,78 @@ function initialListingState(page, sessionOf) {
     return { topOrigin, originOf: new Map([[top.id, topOrigin]]), indexOf: new Map(), sessionOf };
 }
 /**
- * Find every iframe of the page, nested and out-of-process ones included.
- * Frames that go away while they are being listed are skipped.
+ * Indices of iframe elements of one document, in document order.
+ *
+ * @param fc - Frame connection
+ * @param backendNodeIds - The iframe elements
+ * @param ownerSession - Session of the document
+ * @returns Their indices in document order
+ * @throws Errors of CDP (e.g. an element removed meanwhile)
+ */
+async function documentOrder(fc, backendNodeIds, ownerSession) {
+    const objectIds = await Promise.all(backendNodeIds.map(async (backendNodeId) => {
+        const { object } = await sendToSession(fc, 'DOM.resolveNode', { backendNodeId }, ownerSession);
+        return object.objectId ?? '';
+    }));
+    const { result } = await sendToSession(fc, 'Runtime.callFunctionOn', {
+        objectId: objectIds[0],
+        functionDeclaration: DOCUMENT_ORDER_JS,
+        arguments: objectIds.map((objectId) => ({ objectId })),
+        returnByValue: true,
+    }, ownerSession);
+    return result.value;
+}
+/**
+ * Frames grouped by their parent.
+ *
+ * @param iframes - Frames
+ * @returns Frames of each parent, by parent id
+ */
+function groupByParent(iframes) {
+    const byParent = new Map();
+    for (const node of iframes) {
+        const parentId = node.frame.parentId ?? '';
+        byParent.set(parentId, [...(byParent.get(parentId) ?? []), node]);
+    }
+    return byParent;
+}
+/**
+ * Place of each frame among its siblings, from the document order of their
+ * iframe elements. Chrome's frame tree lists frames in the order they were
+ * attached and leaves out-of-process ones to their own sessions, so neither
+ * gives a stable order. Siblings that cannot be ordered get no place.
+ *
+ * @param fc - Frame connection
+ * @param iframes - All iframes
+ * @param owners - Iframe element of each frame, by id
+ * @param sessionOf - Session of each frame, by id
+ * @returns Place of each frame among its siblings, by id
+ */
+async function siblingRanks(fc, iframes, owners, sessionOf) {
+    const rank = new Map();
+    const groups = [...groupByParent(iframes)].map(async ([parentId, siblings]) => {
+        const placed = siblings.flatMap((node) => {
+            const backendNodeId = owners.get(node.frame.id)?.backendNodeId;
+            return backendNodeId === undefined ? [] : [{ id: node.frame.id, backendNodeId }];
+        });
+        if (placed.length < 2)
+            return;
+        try {
+            const nodeIds = placed.map((item) => item.backendNodeId);
+            const order = await documentOrder(fc, nodeIds, sessionOf.get(parentId));
+            order.forEach((index, place) => rank.set(placed[index]?.id ?? '', place));
+        }
+        catch (error) {
+            log.debug(`Frames of ${parentId} not ordered: ${getErrorMessage(error)}`);
+        }
+    });
+    await Promise.all(groups);
+    return rank;
+}
+/**
+ * Find every iframe of the page, nested and out-of-process ones included,
+ * siblings in the document order of their iframe elements. Frames that go
+ * away while they are being listed are skipped.
  *
  * @param fc - Frame connection
  * @returns Iframes in listing order
@@ -327,32 +432,40 @@ async function discoverFrames(fc) {
     const [page, outOfProcess] = await Promise.all([readSession(fc), outOfProcessTrees(fc)]);
     const nodes = flattenTrees([page, ...outOfProcess]);
     const sessionOf = new Map(nodes.map((node) => [node.frame.id, node.sessionId]));
-    const iframes = iframesInOrder(nodes, page.tree.frame.id);
-    const owners = await Promise.all(iframes.map((node) => ownerAttributes(fc, node.frame.id, sessionOf.get(node.frame.parentId ?? ''))));
+    const mainFrameId = page.tree.frame.id;
+    const iframes = nodes.filter((node) => node.frame.id !== mainFrameId);
+    const owners = new Map(await Promise.all(iframes.map(async (node) => [
+        node.frame.id,
+        await frameOwner(fc, node.frame.id, sessionOf.get(node.frame.parentId ?? '')),
+    ])));
+    const rank = await siblingRanks(fc, iframes, owners, sessionOf);
     const state = initialListingState(page, sessionOf);
-    return iframes.map((node, index) => describeFrame(node, index, owners[index] ?? {}, state));
+    return iframesInOrder(iframes, mainFrameId, rank).map((node, index) => describeFrame(node, index, owners.get(node.frame.id) ?? {}, state));
 }
 /**
  * List the page's iframes.
  *
  * @param page - The session's connection
  * @param wsUrl - WebSocket URL of the page target
- * @returns Iframes in listing order
+ * @returns Iframes in listing order, and the frame id behind each index
  */
 export async function listFrames(page, wsUrl) {
     const frames = await withFrameConnection(page, wsUrl, discoverFrames);
-    return frames.map((frame) => frame.info);
+    return { frames: frames.map((frame) => frame.info), frameIds: frames.map((f) => f.frameId) };
 }
 /**
  * Find the requested frame and its default execution context.
  *
  * @param fc - Frame connection
  * @param query - Requested frame
+ * @param listedIds - Frame id behind each index of the last `dom frames` listing, if any
  * @returns The frame and its context's unique id
- * @throws CommandError (81/83) when the frame is ambiguous, missing or has no context
+ * @throws CommandError (81/83) when the frame is ambiguous, missing or has no
+ *   context, (87) when an index names another frame than when it was listed
  */
-async function resolveFrame(fc, query) {
+async function resolveFrame(fc, query, listedIds) {
     const frames = await discoverFrames(fc);
+    assertFrameIndexCurrent(query, frames.map((frame) => frame.frameId), listedIds);
     const selected = selectFrame(frames.map((frame) => frame.info), query);
     const frame = frames[selected.index];
     if (!frame.context) {
@@ -415,13 +528,15 @@ export async function frameContextLostError(conn, page, frame) {
  * @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)
+ * @param listedIds - Frame id behind each index of the last `dom frames` listing, if any
  * @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
+ * @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) {
+export async function evaluateInFrame(page, wsUrl, script, query, listedIds) {
     return withFrameConnection(page, wsUrl, async (fc) => {
-        const { frame, uniqueContextId } = await resolveFrame(fc, query);
+        const { frame, uniqueContextId } = await resolveFrame(fc, query, listedIds);
         try {
             const result = await evaluateScript(fc.conn, script, {
                 ...(frame.sessionId && { sessionId: frame.sessionId }),

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

@@ -0,0 +1,28 @@
+/**
+ * `bdg dom inspect`: what one element looks like, read in the daemon.
+ *
+ * The element is found like the other element commands find it (selector
+ * with filters through open shadow roots and same-origin iframes, or the
+ * exact cached node). Then, in parallel: one page-side walk on the element
+ * ({@link INSPECT_PAGE_JS}: text, placement in the parent, backgrounds, child
+ * tree), `dom layout`'s measurement (page position, hidden, covered,
+ * offscreen) and, once the nodes are pushed to CDP, `CSS.getComputedStyleForNode`
+ * for the element, its layout parent and its `::before`/`::after`,
+ * `CSS.getPlatformFontsForNode` for its text and `DOM.getBoxModel`. DOM and
+ * CSS are enabled on the first inspect and kept on. Matched rules are not
+ * read (no cascade).
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { DomInspectCommand } from '../../ipc/protocol/commands.js';
+import type { InspectResult } from '../../ipc/protocol/inspectTypes.js';
+/**
+ * Inspect one element.
+ *
+ * @param cdp - CDP connection
+ * @param params - Selector (and index) or backend node id, and options
+ * @returns Inspect result
+ * @throws CommandError (83) no match, (81) index out of range, invalid
+ *   selector or unknown property, (87) the cached element left the page
+ */
+export declare function inspectElement(cdp: CDPConnection, params: DomInspectCommand): Promise<InspectResult>;
+//# sourceMappingURL=inspect.d.ts.map