browser-debugger-cli 0.8.0 → 0.9.0

package/dist/runtime/dom/frames.js

@@ -14,8 +14,10 @@
  * 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 { 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 { attachedSessionOf } from '../../telemetry/attachedTargets.js';
 import { senderFor } from '../../telemetry/objectExpander.js';
@@ -70,18 +72,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,25 +145,46 @@ 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;
 }
 /**
@@ -175,7 +225,7 @@ function attributeValue(attributes = [], key) {
  * @param fc - Frame connection
  * @param frameId - Frame
  * @param ownerSession - Session of the parent frame
- * @returns `name` and `id` attributes when set
+ * @returns `name`, `id` and `sandbox` attributes when set
  */
 async function ownerAttributes(fc, frameId, ownerSession) {
     try {
@@ -183,78 +233,104 @@ async function ownerAttributes(fc, 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 { ...(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 }) };
+}
+/**
+ * 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 };
 }
 /**
  * Find every iframe of the page, nested and out-of-process ones included.
+ * 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([frameTree(fc), outOfProcessTrees(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 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)));
-}
-/**
- * The default (main-world) execution context of a frame, so the script sees
- * the frame's own globals.
- *
- * @param fc - Frame connection
- * @param frame - The frame
- * @returns The context's unique id
- * @throws CommandError (83) when the frame has no context yet
- */
-async function defaultContext(fc, frame) {
-    const contexts = [];
-    const stop = fc.conn.on('Runtime.executionContextCreated', ({ context }, sessionId) => {
-        if (sessionId === frame.sessionId)
-            contexts.push(context);
-    });
-    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;
+    const owners = await Promise.all(iframes.map((node) => ownerAttributes(fc, node.frame.id, sessionOf.get(node.frame.parentId ?? ''))));
+    const state = initialListingState(page, sessionOf);
+    return iframes.map((node, index) => describeFrame(node, index, owners[index] ?? {}, state));
 }
 /**
  * List the page's iframes.
@@ -279,7 +355,57 @@ async function resolveFrame(fc, query) {
     const frames = await discoverFrames(fc);
     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 +414,31 @@ 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)
  * @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, (83)
+ *   when it navigated or was removed while the script ran, else as evaluateScript
  */
 export async function evaluateInFrame(page, wsUrl, script, query) {
     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 };
+        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/layout.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Positions, sizes and visibility of elements (`bdg dom layout`).
+ *
+ * One page-side pass per command measures every match: its box in page and
+ * viewport coordinates (iframe offsets included), what clips it, whether it
+ * is rendered, what covers its center and the styles that decide how it
+ * shows. The measurements are classified outside the page
+ * ({@link classifyViewportPosition}).
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { DomLayoutCommand } from '../../ipc/protocol/commands.js';
+import type { LayoutComputedStyle, LayoutResult, PageLayout } from '../../ipc/protocol/domTypes.js';
+import { type ElementGeometry } from './elementGeometry.js';
+/** Matches measured per command (the rest are counted as omitted) */
+export declare const LAYOUT_ELEMENT_LIMIT = 100;
+/**
+ * Page-side end of a visible span kept clear of an overlay scrollbar along
+ * an edge (16 CSS px wide): overlay scrollbars (macOS, mobile) show for about a
+ * second after a scroll and catch hit tests, which then return the scroller.
+ * The span ends before the strip when it reaches into it and also shows
+ * outside it; without overlay scrollbars along the edge it is unchanged.
+ * Arguments: span start and end, the edge, whether overlay scrollbars show there.
+ */
+export declare const CLEAR_OF_SCROLLBAR_JS = "(start, end, edge, overlay) =>\n  overlay && end > edge - 16 && edge - 16 > start ? edge - 16 : end";
+/** One element as {@link LAYOUT_JS} measures it. */
+export interface RawElementLayout {
+    index: number;
+    tag: string;
+    element: string;
+    text: string;
+    context: string;
+    geometry: ElementGeometry;
+    coveredBy: string | null;
+    computed: LayoutComputedStyle;
+}
+/** What {@link LAYOUT_JS} returns. */
+export interface RawLayout {
+    /** Elements the selector matched */
+    count: number;
+    /** Set when at least one element was measured */
+    page?: PageLayout;
+    elements: RawElementLayout[];
+    /** Measured inside a cross-origin iframe: `page` and the coordinates are that frame's */
+    crossOriginFrame?: boolean;
+}
+/**
+ * Measure the elements a selector (or cached index) refers to.
+ *
+ * @param cdp - CDP connection
+ * @param params - Selector (and index) or backend node id
+ * @returns Layout report
+ * @throws CommandError (83) no match, (81) index out of range or invalid
+ *   selector, (87) the cached element left the page
+ */
+export declare function inspectLayout(cdp: CDPConnection, params: DomLayoutCommand): Promise<LayoutResult>;
+/**
+ * Turn page-side measurements into the layout report: rounded page and
+ * viewport coordinates, viewport position and text preview per element.
+ *
+ * @param raw - Measurements with at least one element
+ * @param params - Request (selector and index)
+ * @returns Layout report
+ */
+export declare function buildLayoutResult(raw: RawLayout & {
+    page: PageLayout;
+}, params: Pick<DomLayoutCommand, 'selector' | 'index'>): LayoutResult;
+//# sourceMappingURL=layout.d.ts.map