browser-debugger-cli 0.7.1 → 0.8.0

package/dist/telemetry/a11y.js

@@ -1,8 +1,14 @@
+import { CommandError } from '../errors/index.js';
+import { unknownQueryFieldError } from '../errors/messages.js';
 import { callCDP } from '../ipc/client.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
 /**
  * Builds accessibility tree from raw CDP nodes.
  *
  * Pure function that filters out ignored nodes and builds the tree structure.
+ * Children that are ignored are replaced by their own non-ignored children
+ * (as DevTools shows the tree), so every `childIds` entry is in `nodes`, and
+ * nodes are listed depth-first from the root (document order).
  * Separated from collectA11yTree for easier unit testing.
  *
  * @param rawNodes - Raw AXNode array from CDP
@@ -10,29 +16,55 @@ import { callCDP } from '../ipc/client.js';
  * @throws Error if no root node found
  */
 export function buildTreeFromRawNodes(rawNodes) {
+    const rawById = new Map(rawNodes.map((rawNode) => [rawNode.nodeId, rawNode]));
+    const rootRaw = rawNodes.find((rawNode) => !rawNode.ignored);
+    if (!rootRaw) {
+        throw new CommandError('No root node found in accessibility tree', { suggestion: 'The page may not be fully loaded. Wait and retry.' }, EXIT_CODES.SOFTWARE_ERROR);
+    }
     const nodes = new Map();
-    let root = null;
-    for (const rawNode of rawNodes) {
-        if (rawNode.ignored) {
-            continue;
-        }
+    const visit = (rawNode) => {
+        if (nodes.has(rawNode.nodeId))
+            return;
         const node = parseA11yNode(rawNode);
+        const childIds = visibleChildIds(rawNode, rawById);
+        if (childIds.length > 0)
+            node.childIds = childIds;
+        else
+            delete node.childIds;
         nodes.set(node.nodeId, node);
-        root ??= node;
-    }
-    if (!root) {
-        throw new Error('No root node found in accessibility tree');
-    }
-    return {
-        root,
-        nodes,
-        count: nodes.size,
+        for (const childId of childIds) {
+            const child = rawById.get(childId);
+            if (child)
+                visit(child);
+        }
     };
+    visit(rootRaw);
+    rawNodes.filter((rawNode) => !rawNode.ignored).forEach(visit);
+    const root = nodes.get(rootRaw.nodeId);
+    return { root, nodes, count: nodes.size };
+}
+/**
+ * Ids of a node's children as shown: ignored children are replaced by their
+ * own non-ignored descendants; ids missing from the tree are dropped.
+ *
+ * @param rawNode - Node whose children to list
+ * @param rawById - All raw nodes by id
+ * @param seen - Ids already listed (guards against cycles)
+ * @returns Child ids, all of non-ignored nodes in the tree
+ */
+function visibleChildIds(rawNode, rawById, seen = new Set()) {
+    return (rawNode.childIds ?? []).flatMap((childId) => {
+        const child = rawById.get(childId);
+        if (!child || seen.has(childId))
+            return [];
+        seen.add(childId);
+        return child.ignored ? visibleChildIds(child, rawById, seen) : [childId];
+    });
 }
 /**
  * Collects the full accessibility tree from the page via IPC.
  *
- * Uses the worker's persistent CDP connection through callCDP for consistency
+ * Uses the session's persistent CDP connection through callCDP for consistency
  * with other DOM commands and to avoid connection conflicts.
  *
  * @returns Parsed and filtered accessibility tree
@@ -44,14 +76,86 @@ export async function collectA11yTree() {
         const response = await callCDP('Accessibility.getFullAXTree', {});
         const result = response.data?.result;
         if (!result?.nodes) {
-            throw new Error('Failed to get accessibility tree');
+            throw new CommandError('Failed to get accessibility tree', { suggestion: 'CDP returned no nodes. The page may not be fully loaded.' }, EXIT_CODES.SOFTWARE_ERROR);
         }
-        return buildTreeFromRawNodes(result.nodes);
+        return buildTreeFromRawNodes([...result.nodes, ...(await collectFrameNodes(result.nodes))]);
     }
     finally {
         await callCDP('Accessibility.disable', {});
     }
 }
+/**
+ * Accessibility nodes of the page's iframes, attached under their `Iframe`
+ * node (the page's own tree stops there). Frames in another process
+ * (cross-origin) cannot be read this way and are skipped. Node ids are
+ * prefixed per frame, as each frame numbers its nodes on its own.
+ *
+ * @param pageNodes - The page's nodes (their iframe nodes get the frame root as
+ *   child; nested frames attach to their parent frame's nodes)
+ * @returns Nodes of all readable frames
+ */
+async function collectFrameNodes(pageNodes) {
+    const tree = (await callCDP('Page.getFrameTree', {})).data?.result;
+    const known = [...pageNodes];
+    const collected = [];
+    for (const [index, frameId] of childFrames(tree?.frameTree).entries()) {
+        const nodes = await frameNodes(frameId, `f${index}:`, known);
+        known.push(...nodes);
+        collected.push(...nodes);
+    }
+    return collected;
+}
+/**
+ * Ids of all frames below a frame tree's root.
+ *
+ * @param tree - Frame tree
+ * @returns Frame ids, depth-first
+ */
+function childFrames(tree) {
+    return (tree?.childFrames ?? []).flatMap((child) => [child.frame.id, ...childFrames(child)]);
+}
+/**
+ * One frame's nodes, with ids prefixed, its root attached to the node of its
+ * `<iframe>` element.
+ *
+ * @param frameId - Frame id
+ * @param prefix - Prefix for the frame's node ids
+ * @param ownerNodes - Nodes that may contain the frame's `<iframe>` node
+ * @returns The frame's nodes, or none when it cannot be read
+ */
+async function frameNodes(frameId, prefix, ownerNodes) {
+    const response = await callCDP('Accessibility.getFullAXTree', { frameId });
+    const nodes = response.data?.result
+        ?.nodes;
+    const owner = (await callCDP('DOM.getFrameOwner', { frameId })).data?.result;
+    if (!nodes?.length || !owner)
+        return [];
+    const prefixed = nodes.map((node) => ({
+        ...node,
+        nodeId: prefix + node.nodeId,
+        ...(node.parentId && { parentId: prefix + node.parentId }),
+        ...(node.childIds && { childIds: node.childIds.map((id) => prefix + id) }),
+    }));
+    const root = prefixed.find((node) => !node.parentId);
+    const iframeNode = ownerNodes.find((node) => node.backendDOMNodeId === owner.backendNodeId);
+    if (root && iframeNode)
+        iframeNode.childIds = [...(iframeNode.childIds ?? []), root.nodeId];
+    return prefixed;
+}
+/**
+ * Chrome reports some states (`checked`, `pressed`) as the strings "true" and
+ * "false" (they may also be "mixed"); make those booleans like the others.
+ *
+ * @param value - Property value
+ * @returns The value, with "true"/"false" as booleans
+ */
+function booleanIfFlag(value) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return value;
+}
 /**
  * Parses raw CDP AXNode into simplified A11yNode format.
  *
@@ -91,7 +195,7 @@ function parseA11yNode(rawNode) {
                 node.required = prop.value.value === true;
             }
             else {
-                props[prop.name] = prop.value.value;
+                props[prop.name] = booleanIfFlag(prop.value.value);
             }
         }
         if (Object.keys(props).length > 0) {
@@ -120,6 +224,12 @@ function extractRole(rawNode) {
     }
     return 'unknown';
 }
+/**
+ * Roles of text nodes: they repeat the name of the element they are in (a
+ * name search found every button three times) and are not elements that
+ * commands can act on. Left out unless the query asks for the role.
+ */
+const TEXT_ROLES = new Set(['statictext', 'inlinetextbox']);
 /**
  * Queries accessibility tree by pattern (role, name, description).
  *
@@ -143,7 +253,10 @@ function extractRole(rawNode) {
  */
 export function queryA11yTree(tree, pattern) {
     const matches = [];
+    const wantsText = pattern.role !== undefined && TEXT_ROLES.has(pattern.role.toLowerCase());
     for (const node of tree.nodes.values()) {
+        if (!wantsText && TEXT_ROLES.has(node.role.toLowerCase()))
+            continue;
         if (matchesPattern(node, pattern)) {
             matches.push(node);
         }
@@ -154,128 +267,112 @@ export function queryA11yTree(tree, pattern) {
         pattern,
     };
 }
+/**
+ * Match a value against a query term.
+ *
+ * Without `*` the term matches as a case-insensitive substring (or exactly,
+ * for `exact`); `*` matches any run of characters.
+ *
+ * @param value - Node value (role, name, description)
+ * @param term - Query term
+ * @param exact - Whole-value match instead of substring
+ * @returns True on match
+ */
+function matchesTerm(value, term, exact = false) {
+    if (value === undefined)
+        return false;
+    if (!term.includes('*')) {
+        const [v, t] = [value.toLowerCase(), term.toLowerCase()];
+        return exact ? v === t : v.includes(t);
+    }
+    const source = term
+        .split('*')
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+        .join('[\\s\\S]*');
+    return new RegExp(exact ? `^${source}$` : source, 'i').test(value);
+}
 /**
  * Checks if a node matches the query pattern.
  *
- * All specified fields must match (AND logic).
- * String matching is case-insensitive.
+ * All specified fields must match (AND logic), case-insensitively: role
+ * exactly, name and description as substrings; `*` is a wildcard.
  *
  * @param node - A11y node to test
  * @param pattern - Query pattern
  * @returns True if node matches all pattern criteria
  */
 function matchesPattern(node, pattern) {
-    if (pattern.role) {
-        if (node.role.toLowerCase() !== pattern.role.toLowerCase()) {
-            return false;
-        }
-    }
-    if (pattern.name) {
-        if (!node.name) {
-            return false;
-        }
-        if (!node.name.toLowerCase().includes(pattern.name.toLowerCase())) {
-            return false;
-        }
-    }
-    if (pattern.description) {
-        if (!node.description) {
-            return false;
-        }
-        if (!node.description.toLowerCase().includes(pattern.description.toLowerCase())) {
-            return false;
-        }
-    }
+    if (pattern.role && !matchesTerm(node.role, pattern.role, true))
+        return false;
+    if (pattern.name && !matchesTerm(node.name, pattern.name))
+        return false;
+    if (pattern.description && !matchesTerm(node.description, pattern.description))
+        return false;
     return true;
 }
+/** Query fields and their aliases. */
+const QUERY_FIELDS = {
+    role: 'role',
+    name: 'name',
+    description: 'description',
+    desc: 'description',
+};
+/**
+ * One `key:value` (or `key=value`) field: the value is quoted, or runs until
+ * the next `key:`/`key=` after a space or comma.
+ */
+const QUERY_FIELD = /([a-z]+)\s*[:=](?:\s*("[^"]*"|'[^']*')|((?:(?![\s,]+[a-z]+\s*[:=]).)*))/gis;
 /**
  * Parses query pattern string into A11yQueryPattern object.
  *
- * Supports format: "role:button name:Submit description:Main"
- * Also accepts = as separator: "role=button name=Submit"
- * Fields are separated by spaces, case-insensitive.
+ * Fields are `key:value` or `key=value`, separated by spaces or commas.
+ * Values may contain spaces (quote them if they contain `key:`-like text).
+ * Keys: role, name, description (desc). Case-insensitive.
  *
  * @param patternString - Query pattern string
  * @returns Parsed query pattern
+ * @throws CommandError (81) for unknown keys
  *
  * @example
  * ```typescript
- * parseQueryPattern('role:button name:Submit')
- * // => { role: 'button', name: 'Submit' }
- *
- * parseQueryPattern('role=heading')
- * // => { role: 'heading' }
- *
- * parseQueryPattern('name:Email')
- * // => { name: 'Email' }
+ * parseQueryPattern('role:button name:Submit')     // { role: 'button', name: 'Submit' }
+ * parseQueryPattern('role=link,name=Google Chrome') // { role: 'link', name: 'Google Chrome' }
+ * parseQueryPattern('name:"Sign in" role:button')  // { name: 'Sign in', role: 'button' }
  * ```
  */
 export function parseQueryPattern(patternString) {
     const pattern = {};
-    const parts = patternString.trim().split(/\s+/);
-    for (const part of parts) {
-        const separatorMatch = part.match(/[:=]/);
-        if (!separatorMatch) {
-            continue;
-        }
-        const separator = separatorMatch[0];
-        const [key, ...valueParts] = part.split(separator);
-        const value = valueParts.join(separator);
-        if (!value) {
-            continue;
-        }
-        if (!key) {
-            continue;
-        }
-        const normalizedKey = key.toLowerCase();
-        if (normalizedKey === 'role') {
-            pattern.role = value;
-        }
-        else if (normalizedKey === 'name') {
-            pattern.name = value;
-        }
-        else if (normalizedKey === 'description' || normalizedKey === 'desc') {
-            pattern.description = value;
+    for (const [, rawKey = '', quoted, plain = ''] of patternString.matchAll(QUERY_FIELD)) {
+        const rawValue = quoted ?? plain;
+        const field = QUERY_FIELDS[rawKey.toLowerCase()];
+        if (!field) {
+            const err = unknownQueryFieldError(rawKey);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
         }
+        const value = rawValue
+            .trim()
+            .replace(/,+$/, '')
+            .replace(/^(["'])(.*)\1$/s, '$2');
+        if (value)
+            pattern[field] = value;
     }
     return pattern;
 }
 /**
- * Resolve accessibility properties for a DOM node by CSS selector or nodeId via IPC.
+ * Resolve accessibility properties for a DOM node via IPC.
  *
- * Uses the worker's persistent CDP connection through callCDP for consistency.
- * Supports direct nodeId lookup (bypassing selector) for index-based access patterns.
+ * Uses the session's persistent CDP connection through callCDP for consistency.
+ * Selectors are resolved by the caller (see `resolveBackendNodeIds`), so they
+ * reach shadow roots and same-origin iframes like every other DOM command.
  *
- * @param selector - CSS selector (ignored if nodeId provided)
- * @param nodeId - Optional nodeId to use directly instead of querying by selector
+ * @param target - Node reference
  * @returns A11y node or null if not found
- * @throws Error if selector is invalid or element not found
  */
-export async function resolveA11yNode(selector, nodeId) {
+export async function resolveA11yNode(target) {
     await callCDP('Accessibility.enable', {});
     try {
-        let targetNodeId;
-        if (nodeId !== undefined) {
-            targetNodeId = nodeId;
-        }
-        else {
-            const docResponse = await callCDP('DOM.getDocument', {});
-            const doc = docResponse.data?.result;
-            if (!doc?.root?.nodeId) {
-                throw new Error('Failed to get document root');
-            }
-            const nodeResponse = await callCDP('DOM.querySelector', {
-                nodeId: doc.root.nodeId,
-                selector,
-            });
-            const nodeResult = nodeResponse.data?.result;
-            if (!nodeResult?.nodeId) {
-                return null;
-            }
-            targetNodeId = nodeResult.nodeId;
-        }
         const a11yResponse = await callCDP('Accessibility.getPartialAXTree', {
-            nodeId: targetNodeId,
+            ...target,
             fetchRelatives: false,
         });
         const a11yResult = a11yResponse.data?.result;
@@ -292,4 +389,40 @@ export async function resolveA11yNode(selector, nodeId) {
         await callCDP('Accessibility.disable', {});
     }
 }
+/**
+ * Why an element has no node in the accessibility tree (e.g. it is not
+ * rendered, aria-hidden, or a decorative image with `alt=""`).
+ *
+ * @param target - Node reference
+ * @returns Chrome's reasons in plain words (empty if unknown)
+ */
+export async function a11yIgnoredReasons(target) {
+    await callCDP('Accessibility.enable', {});
+    try {
+        const response = await callCDP('Accessibility.getPartialAXTree', {
+            ...target,
+            fetchRelatives: false,
+        });
+        const nodes = response.data?.result?.nodes;
+        return (nodes?.[0]?.ignoredReasons ?? []).map((reason) => IGNORED_REASONS[reason.name] ?? reason.name);
+    }
+    finally {
+        await callCDP('Accessibility.disable', {});
+    }
+}
+/** Chrome's ignored reasons in plain words */
+const IGNORED_REASONS = {
+    notRendered: 'not rendered (display: none or hidden)',
+    notVisible: 'not visible',
+    ariaHiddenElement: 'aria-hidden="true"',
+    ariaHiddenSubtree: 'inside an aria-hidden element',
+    presentationalRole: 'presentational (e.g. an image with alt="")',
+    emptyAlt: 'an image with alt=""',
+    inertElement: 'inert',
+    inertSubtree: 'inside an inert element',
+    activeModalDialog: 'outside the open modal dialog',
+    probablyPresentational: 'probably decorative',
+    uninteresting: 'has no role or name',
+    labelFor: 'a label (its text names another element)',
+};
 //# sourceMappingURL=a11y.js.map

package/dist/telemetry/attachedTargets.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Attach to the page's child targets: out-of-process (cross-origin) iframes
+ * and workers.
+ *
+ * Their console, log and network events do not reach the page's own session.
+ * With flattened auto-attach, each child gets a session on the same
+ * connection; its events arrive with that session id, and commands are sent
+ * to it by id. Children start paused, so every collector can enable its
+ * domains before the child loads anything; they are resumed afterwards.
+ */
+import type { CDPConnection } from '../connection/cdp.js';
+import type { CleanupFunction } from '../types.js';
+/** Enables what a collector needs on a child session (e.g. `Runtime.enable`) */
+type ChildSetup = (sessionId: string) => Promise<void>;
+/**
+ * Attach to child targets of the page and run `setup` on each one's session
+ * before it starts. Children that are already attached (e.g. when another
+ * collector registered first) get the setup right away.
+ *
+ * @param cdp - CDP connection to the page
+ * @param setup - Enables domains on a child session (e.g. `Runtime.enable`)
+ * @returns Cleanup function that stops running `setup` for new targets
+ */
+export declare function attachChildTargets(cdp: CDPConnection, setup: ChildSetup): Promise<CleanupFunction>;
+/**
+ * Session of an attached child target (e.g. an out-of-process iframe) on the
+ * connection. Its commands are answered even while the target's scripts keep
+ * it busy, unlike those of a session attached afterwards.
+ *
+ * @param cdp - CDP connection to the page
+ * @param targetId - Target id (an iframe target's id is its frame id)
+ * @returns The session, undefined when the target is not attached
+ */
+export declare function attachedSessionOf(cdp: CDPConnection, targetId: string): string | undefined;
+export {};
+//# sourceMappingURL=attachedTargets.d.ts.map

package/dist/telemetry/attachedTargets.js

@@ -0,0 +1,163 @@
+/**
+ * Attach to the page's child targets: out-of-process (cross-origin) iframes
+ * and workers.
+ *
+ * Their console, log and network events do not reach the page's own session.
+ * With flattened auto-attach, each child gets a session on the same
+ * connection; its events arrive with that session id, and commands are sent
+ * to it by id. Children start paused, so every collector can enable its
+ * domains before the child loads anything; they are resumed afterwards.
+ */
+import { CDPHandlerRegistry } from '../connection/handlers.js';
+import { TypedCDPConnection } from '../connection/typed-cdp.js';
+import { createLogger } from '../ui/logging/index.js';
+import { getErrorMessage } from '../utils/errors.js';
+const log = createLogger('targets');
+/** Auto-attach settings: children wait until set up; one connection for all sessions */
+const AUTO_ATTACH = { autoAttach: true, waitForDebuggerOnStart: true, flatten: true };
+/**
+ * How long a paused child waits for the collectors' setup before it is
+ * resumed anyway. A paused service worker answers no command until it runs,
+ * so waiting for its setup kept it (and the page's `register()`) paused
+ * forever; its pending commands complete once it runs.
+ */
+const SETUP_WAIT_MS = 1000;
+/** Turns auto-attach off again (children attached afterwards would stay paused) */
+const NO_AUTO_ATTACH = { autoAttach: false, waitForDebuggerOnStart: false };
+const managers = new WeakMap();
+/**
+ * Run setups on a child session, logging (not throwing) failures.
+ *
+ * @param sessionId - Session of the attached target
+ * @param url - Target URL (for logs)
+ * @param setups - Collector setups to run
+ */
+async function runSetups(sessionId, url, setups) {
+    const results = await Promise.allSettled([...setups].map((setup) => setup(sessionId)));
+    for (const result of results) {
+        if (result.status === 'rejected') {
+            log.debug(`Setup of attached target ${url} failed: ${getErrorMessage(result.reason)}`);
+        }
+    }
+}
+/**
+ * Prepare a newly attached child target: run every collector's setup on its
+ * session, auto-attach to its own children (iframes nested in iframes), and
+ * resume it (after at most {@link SETUP_WAIT_MS}).
+ *
+ * @param manager - Shared manager of the connection
+ * @param sessionId - Session of the attached target
+ * @param child - Target URL (for logs) and id
+ */
+async function prepareChild(manager, sessionId, child) {
+    const { url } = child;
+    manager.sessions.set(sessionId, child);
+    try {
+        let timer;
+        await Promise.race([
+            Promise.all([
+                runSetups(sessionId, url, manager.setups),
+                manager.typed.send('Target.setAutoAttach', AUTO_ATTACH, sessionId),
+            ]),
+            new Promise((resolve) => (timer = setTimeout(resolve, SETUP_WAIT_MS))),
+        ]).finally(() => clearTimeout(timer));
+        log.debug(`Attached to ${url || 'a new target'}`);
+    }
+    catch (error) {
+        log.debug(`Could not prepare attached target ${url}: ${getErrorMessage(error)}`);
+    }
+    finally {
+        await manager.typed
+            .send('Runtime.runIfWaitingForDebugger', {}, sessionId)
+            .catch((error) => log.debug(`Could not resume ${url}: ${getErrorMessage(error)}`));
+    }
+}
+/**
+ * Create the shared manager of a connection (auto-attach starts once the
+ * first setup is registered).
+ *
+ * @param cdp - CDP connection to the page
+ * @returns The manager
+ */
+function createManager(cdp) {
+    const typed = new TypedCDPConnection(cdp);
+    const manager = {
+        typed,
+        setups: new Set(),
+        sessions: new Map(),
+        registry: new CDPHandlerRegistry(),
+    };
+    manager.registry.registerTyped(typed, 'Target.attachedToTarget', (params) => {
+        const { url, targetId } = params.targetInfo;
+        void prepareChild(manager, params.sessionId, { url, targetId });
+    });
+    manager.registry.registerTyped(typed, 'Target.detachedFromTarget', (params) => {
+        manager.sessions.delete(params.sessionId);
+    });
+    managers.set(cdp, manager);
+    return manager;
+}
+/**
+ * Stop auto-attaching once no collector needs children any more.
+ *
+ * @param cdp - CDP connection to the page
+ * @param manager - The connection's manager
+ */
+function retireManager(cdp, manager) {
+    manager.registry.cleanup();
+    managers.delete(cdp);
+    void manager.typed
+        .send('Target.setAutoAttach', { ...NO_AUTO_ATTACH, flatten: true })
+        .catch((error) => log.debug(`Auto-attach not turned off: ${getErrorMessage(error)}`));
+}
+/**
+ * Attach to child targets of the page and run `setup` on each one's session
+ * before it starts. Children that are already attached (e.g. when another
+ * collector registered first) get the setup right away.
+ *
+ * @param cdp - CDP connection to the page
+ * @param setup - Enables domains on a child session (e.g. `Runtime.enable`)
+ * @returns Cleanup function that stops running `setup` for new targets
+ */
+export async function attachChildTargets(cdp, setup) {
+    const existing = managers.get(cdp);
+    const manager = existing ?? createManager(cdp);
+    manager.setups.add(setup);
+    const cleanup = () => {
+        manager.setups.delete(setup);
+        if (manager.setups.size === 0 && managers.get(cdp) === manager)
+            retireManager(cdp, manager);
+    };
+    if (existing) {
+        for (const [sessionId, { url }] of manager.sessions)
+            void runSetups(sessionId, url, [setup]);
+        return cleanup;
+    }
+    try {
+        await manager.typed.send('Target.setAutoAttach', AUTO_ATTACH);
+    }
+    catch (error) {
+        manager.setups.delete(setup);
+        manager.registry.cleanup();
+        managers.delete(cdp);
+        throw error;
+    }
+    return cleanup;
+}
+/**
+ * Session of an attached child target (e.g. an out-of-process iframe) on the
+ * connection. Its commands are answered even while the target's scripts keep
+ * it busy, unlike those of a session attached afterwards.
+ *
+ * @param cdp - CDP connection to the page
+ * @param targetId - Target id (an iframe target's id is its frame id)
+ * @returns The session, undefined when the target is not attached
+ */
+export function attachedSessionOf(cdp, targetId) {
+    for (const [sessionId, child] of managers.get(cdp)?.sessions ?? []) {
+        if (child.targetId === targetId)
+            return sessionId;
+    }
+    return undefined;
+}
+//# sourceMappingURL=attachedTargets.js.map

package/dist/telemetry/console.d.ts

@@ -1,13 +1,30 @@
 /**
- * Console message collection via CDP Runtime domain.
+ * Console message collection via CDP Runtime and Log domains.
  *
  * Captures console.log, console.error, etc. and JavaScript exceptions
- * with automatic nested object expansion.
+ * with automatic nested object expansion, browser messages (failed loads,
+ * CORS, security, deprecations), and the same from cross-origin iframes and
+ * workers.
  */
 import type { CDPConnection } from '../connection/cdp.js';
-import type { ConsoleMessage, CleanupFunction } from '../types';
+import type { Protocol } from '../connection/typed-cdp.js';
+import type { ConsoleMessage, CleanupFunction } from '../types.js';
 /**
- * Start collecting console messages and exceptions via CDP Runtime domain.
+ * Build the message text for an uncaught exception, as DevTools shows it.
+ *
+ * CDP's `text` is usually just "Uncaught" or "Uncaught (in promise)"; the
+ * actual error lives in `exception.description` (Errors) or `exception.value`
+ * (thrown primitives). The description's stack frames (`    at ...` lines)
+ * are dropped, since the stack is kept separately on the message; multi-line
+ * error messages are kept whole.
+ *
+ * @param details - CDP exception details
+ * @returns e.g. "Uncaught TypeError: x is not a function"
+ */
+export declare function formatExceptionText(details: Protocol.Runtime.ExceptionDetails): string;
+/**
+ * Start collecting console messages, exceptions and browser log entries from
+ * the page and its cross-origin iframes and workers.
  *
  * @param cdp - CDP connection instance
  * @param messages - Array to populate with console messages