browser-debugger-cli 0.8.0 → 0.10.0

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

@@ -14,15 +14,67 @@
  * 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<FrameListing>;
+/** 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 listFrames(page: CDPConnection, wsUrl: string): Promise<DomFrame[]>;
+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.
@@ -30,9 +82,13 @@ export declare function listFrames(page: CDPConnection, wsUrl: string): Promise<
  * @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 URL)
+ * @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, 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

@@ -14,9 +14,11 @@
  * all, not even to `Runtime.terminateExecution`.
  */
 import { CDPConnection } from '../../connection/cdp.js';
-import { frameNotReadyError } from '../../errors/messages.js';
-import { evaluateScript, withBusyPageRecovery } from './evalHelpers.js';
-import { frameError, selectFrame } from './frameSelection.js';
+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 { 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';
@@ -25,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.
  *
@@ -70,18 +98,45 @@ function recoverySender(fc, sessionId) {
  */
 async function sendToSession(fc, method, params, sessionId) {
     const command = fc.conn.send(method, params, sessionId);
-    return (await withBusyPageRecovery(recoverySender(fc, sessionId), command));
+    const scope = sessionId === undefined ? 'page' : 'frame';
+    return (await withBusyPageRecovery(recoverySender(fc, sessionId), command, { scope }));
 }
 /**
- * Frame tree of a session.
+ * Default execution contexts of a session's frames, reported when Runtime is
+ * enabled.
+ *
+ * @param fc - Frame connection
+ * @param sessionId - Session, undefined for the page
+ * @returns Context of each frame, by frame id
+ */
+async function defaultContexts(fc, sessionId) {
+    const contexts = new Map();
+    const stop = fc.conn.on('Runtime.executionContextCreated', ({ context }, eventSession) => {
+        const auxData = (context.auxData ?? {});
+        const frameId = auxData['frameId'];
+        if (eventSession !== sessionId || !auxData['isDefault'] || typeof frameId !== 'string')
+            return;
+        contexts.set(frameId, { uniqueId: context.uniqueId, origin: context.origin });
+    });
+    try {
+        await sendToSession(fc, 'Runtime.enable', {}, sessionId);
+    }
+    finally {
+        stop();
+    }
+    return contexts;
+}
+/**
+ * Frame tree of a session and the default contexts of its frames.
  *
  * @param fc - Frame connection
  * @param sessionId - Session, undefined for the page
  * @returns The tree
  */
-async function frameTree(fc, sessionId) {
+async function readSession(fc, sessionId) {
+    const contexts = await defaultContexts(fc, sessionId);
     const { frameTree: tree } = await sendToSession(fc, 'Page.getFrameTree', {}, sessionId);
-    return { tree, ...(sessionId && { sessionId }) };
+    return { tree, contexts, ...(sessionId && { sessionId }) };
 }
 /**
  * Attach to the out-of-process iframes directly below a session. Chrome
@@ -116,38 +171,63 @@ async function attachChildFrames(fc, parentSession) {
  */
 async function outOfProcessTrees(fc, parentSession) {
     const sessions = await attachChildFrames(fc, parentSession);
-    const nested = await Promise.all(sessions.map(async (sessionId) => [
-        await frameTree(fc, sessionId),
-        ...(await outOfProcessTrees(fc, sessionId)),
-    ]));
+    const nested = await Promise.all(sessions.map((sessionId) => childSessionTrees(fc, sessionId)));
     return nested.flat();
 }
 /**
- * All frames of the trees, each with its session.
+ * Trees of an out-of-process iframe and the ones nested in it. A frame
+ * removed while the page is being listed (its session is gone) is skipped.
+ *
+ * @param fc - Frame connection
+ * @param sessionId - The iframe's session
+ * @returns Its tree and the nested ones, or none when it went away
+ */
+async function childSessionTrees(fc, sessionId) {
+    try {
+        return [await readSession(fc, sessionId), ...(await outOfProcessTrees(fc, sessionId))];
+    }
+    catch (error) {
+        if (!(error instanceof CDPProtocolError))
+            throw error;
+        log.debug(`Frame session ${sessionId} went away while listing: ${error.message}`);
+        return [];
+    }
+}
+/**
+ * All frames of the trees, each with its session and default context.
  *
  * @param trees - Frame trees
  * @returns Frames in tree order
  */
 function flattenTrees(trees) {
     const nodes = [];
-    const walk = (tree, sessionId) => {
-        nodes.push({ frame: tree.frame, ...(sessionId && { sessionId }) });
-        tree.childFrames?.forEach((child) => walk(child, sessionId));
+    const walk = (tree, owner) => {
+        const context = owner.contexts.get(tree.frame.id);
+        nodes.push({
+            frame: tree.frame,
+            ...(owner.sessionId && { sessionId: owner.sessionId }),
+            ...(context && { context }),
+        });
+        tree.childFrames?.forEach((child) => walk(child, owner));
     };
-    trees.forEach(({ tree, sessionId }) => walk(tree, sessionId));
+    trees.forEach((owner) => walk(owner.tree, owner));
     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);
         }
@@ -170,116 +250,275 @@ 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` and `id` 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');
-        return { ...(name && { name }), ...(id && { id }) };
+        const sandbox = attributeValue(node.attributes, 'sandbox');
+        return {
+            backendNodeId,
+            ...(name && { name }),
+            ...(id && { id }),
+            ...(sandbox !== undefined && { sandbox }),
+        };
     }
     catch (error) {
         log.debug(`No iframe element for frame ${frameId}: ${getErrorMessage(error)}`);
         return {};
     }
 }
+/**
+ * Where a frame sits in the listing: its origin, and the index of its parent.
+ * Parents are placed before their children, so a child can inherit its
+ * parent's origin.
+ *
+ * @param node - The frame
+ * @param index - Its position
+ * @param owner - Attributes of its iframe element
+ * @param state - Frames placed so far (updated)
+ * @returns Origin and parent index
+ */
+function placeFrame(node, index, owner, state) {
+    const { frame, context } = node;
+    const parentId = frame.parentId ?? '';
+    const origin = effectiveFrameOrigin({
+        url: frame.url,
+        securityOrigin: frame.securityOrigin,
+        contextOrigin: context?.origin,
+        parentOrigin: state.originOf.get(parentId),
+        sandbox: owner.sandbox,
+    });
+    const parentIndex = state.indexOf.get(parentId);
+    state.originOf.set(frame.id, origin);
+    state.indexOf.set(frame.id, index);
+    return { origin, ...(parentIndex !== undefined && { parentIndex }) };
+}
 /**
  * Describe an iframe for listing. Chrome names a frame after its element's
  * `id` when it has no `name`, so such a name is not repeated.
  *
- * @param fc - Frame connection
  * @param node - The frame
  * @param index - Its position
- * @param context - The page's origin and the session of each frame
+ * @param owner - Attributes of its iframe element
+ * @param state - Frames described so far (updated)
  * @returns The located frame
  */
-async function locateFrame(fc, node, index, context) {
-    const { frame, sessionId } = node;
-    const owner = await ownerAttributes(fc, frame.id, context.sessionOf.get(frame.parentId ?? ''));
+function describeFrame(node, index, owner, state) {
+    const { frame, sessionId, context } = node;
     const name = owner.name ?? (frame.name === owner.id ? undefined : frame.name);
+    const { origin, parentIndex } = placeFrame(node, index, owner, state);
     const info = {
         index,
         url: frame.url + (frame.urlFragment ?? ''),
         ...(name && { name }),
         ...(owner.id && { id: owner.id }),
-        origin: frame.securityOrigin,
-        crossOrigin: frame.securityOrigin !== context.topOrigin,
+        origin,
+        crossOrigin: isCrossOrigin(origin, state.topOrigin),
         outOfProcess: sessionId !== undefined,
+        ...(parentIndex !== undefined && { parentIndex }),
+    };
+    const ownerSession = state.sessionOf.get(frame.parentId ?? '');
+    return {
+        info,
+        frameId: frame.id,
+        ...(sessionId && { sessionId }),
+        ...(ownerSession && { ownerSession }),
+        ...(context && { context }),
     };
-    return { info, frameId: frame.id, ...(sessionId && { sessionId }) };
 }
 /**
- * Find every iframe of the page, nested and out-of-process ones included.
+ * The listing state before the first iframe: the page's own origin.
+ *
+ * @param page - The page's session tree
+ * @param sessionOf - Session of each frame
+ * @returns Initial state
+ */
+function initialListingState(page, sessionOf) {
+    const top = page.tree.frame;
+    const topOrigin = effectiveFrameOrigin({
+        url: top.url,
+        securityOrigin: top.securityOrigin,
+        contextOrigin: page.contexts.get(top.id)?.origin,
+    });
+    return { topOrigin, originOf: new Map([[top.id, topOrigin]]), indexOf: new Map(), sessionOf };
+}
+/**
+ * Indices of iframe elements of one document, in document order.
  *
  * @param fc - Frame connection
- * @returns Iframes in listing order
+ * @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 discoverFrames(fc) {
-    const [page, outOfProcess] = await Promise.all([frameTree(fc), outOfProcessTrees(fc)]);
-    const nodes = flattenTrees([page, ...outOfProcess]);
-    const sessionOf = new Map(nodes.map((node) => [node.frame.id, node.sessionId]));
-    const context = { topOrigin: page.tree.frame.securityOrigin, sessionOf };
-    const iframes = iframesInOrder(nodes, page.tree.frame.id);
-    return Promise.all(iframes.map((node, index) => locateFrame(fc, node, index, context)));
+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;
 }
 /**
- * The default (main-world) execution context of a frame, so the script sees
- * the frame's own globals.
+ * 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 frame - The frame
- * @returns The context's unique id
- * @throws CommandError (83) when the frame has no context yet
+ * @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 defaultContext(fc, frame) {
-    const contexts = [];
-    const stop = fc.conn.on('Runtime.executionContextCreated', ({ context }, sessionId) => {
-        if (sessionId === frame.sessionId)
-            contexts.push(context);
+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)}`);
+        }
     });
-    try {
-        await sendToSession(fc, 'Runtime.enable', {}, frame.sessionId);
-    }
-    finally {
-        stop();
-    }
-    const auxData = (c) => (c.auxData ?? {});
-    const context = contexts.find((c) => auxData(c)['frameId'] === frame.frameId && auxData(c)['isDefault']);
-    if (!context)
-        throw frameError(frameNotReadyError(frame.info.url), EXIT_CODES.RESOURCE_NOT_FOUND);
-    return context.uniqueId;
+    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
+ */
+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 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 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];
-    return { frame, uniqueContextId: await defaultContext(fc, frame) };
+    if (!frame.context) {
+        throw frameError(frameNotReadyError(frame.info.url), EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    return { frame, uniqueContextId: frame.context.uniqueId };
+}
+/** Chrome's messages when a frame (or the session of its parent) no longer exists */
+const FRAME_GONE_PATTERN = /not found|no frame|no node/i;
+/** How long the frame's parent gets to say whether the frame is still there */
+const OWNER_CHECK_MS = 2_000;
+/**
+ * Whether the frame's iframe element is still in its parent.
+ *
+ * @param conn - Connection the frame was found on
+ * @param frame - The frame
+ * @returns `attached`, `removed`, or `unknown` when the parent did not answer in time
+ * @throws Errors other than Chrome saying the frame is gone (e.g. a lost connection)
+ */
+async function frameOwnerState(conn, frame) {
+    try {
+        const owner = conn.send('DOM.getFrameOwner', { frameId: frame.frameId }, frame.ownerSession);
+        return (await settledWithin(owner, OWNER_CHECK_MS)).settled ? 'attached' : 'unknown';
+    }
+    catch (error) {
+        if (!(error instanceof CDPProtocolError) || !FRAME_GONE_PATTERN.test(error.message))
+            throw error;
+        log.debug(`Frame ${frame.frameId} is gone: ${error.message}`);
+        return 'removed';
+    }
+}
+/**
+ * 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 async function frameContextLostError(conn, page, frame) {
+    if (!(await pageStillOpen(page))) {
+        return frameError(pageClosedDuringEvalError(), EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    const messages = {
+        attached: frameNavigatedDuringEvalError,
+        removed: frameRemovedDuringEvalError,
+        unknown: frameLostDuringEvalError,
+    };
+    const err = messages[await frameOwnerState(conn, frame)](frame.url);
+    return frameError(err, EXIT_CODES.RESOURCE_NOT_FOUND);
 }
 /**
  * Evaluate a `bdg dom eval` script in one iframe, like {@link evaluateScript}
@@ -288,18 +527,33 @@ async function resolveFrame(fc, query) {
  * @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 URL)
+ * @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, 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 result = await evaluateScript(fc.conn, script, {
-            ...(frame.sessionId && { sessionId: frame.sessionId }),
-            uniqueContextId,
-        });
-        return { ...result, frame: frame.info.url };
+        const { frame, uniqueContextId } = await resolveFrame(fc, query, listedIds);
+        try {
+            const result = await evaluateScript(fc.conn, script, {
+                ...(frame.sessionId && { sessionId: frame.sessionId }),
+                uniqueContextId,
+                recovery: recoverySender(fc, frame.sessionId),
+            });
+            return { ...result, frame: frame.info.url };
+        }
+        catch (error) {
+            if (!isContextLostError(error))
+                throw error;
+            throw await frameContextLostError(fc.conn, fc.page, {
+                frameId: frame.frameId,
+                url: frame.info.url,
+                ...(frame.ownerSession && { ownerSession: frame.ownerSession }),
+            });
+        }
     });
 }
 //# sourceMappingURL=frames.js.map

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