browser-debugger-cli 0.7.2 → 0.9.0

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

package/dist/telemetry/console.js

@@ -1,17 +1,27 @@
 /**
- * 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 { CDPHandlerRegistry } from '../connection/handlers.js';
 import { TypedCDPConnection } from '../connection/typed-cdp.js';
 import { MAX_CONSOLE_MESSAGES } from '../constants.js';
+import { attachChildTargets } from './attachedTargets.js';
 import { createLogger } from '../ui/logging/index.js';
 import { shouldExcludeConsoleMessage } from './filters.js';
-import { expandConsoleArgs } from './objectExpander.js';
-import { formatConsoleArgs } from './remoteObject.js';
+import { expandConsoleArgs, senderFor } from './objectExpander.js';
+import { formatConsoleArgs, usesFormatSpecifiers } from './remoteObject.js';
 import { needsAsyncExpansion } from './remoteObjectUtils.js';
+/** Console message type of each browser log level */
+const LOG_LEVEL_TYPES = {
+    verbose: 'debug',
+    info: 'info',
+    warning: 'warning',
+    error: 'error',
+};
 const log = createLogger('console');
 /**
  * Convert a CDP call frame to a StackFrame.
@@ -60,6 +70,7 @@ function createMessage(type, text, timestamp, args, context) {
         ...(args && { args }),
         ...(context.navigationId !== undefined && { navigationId: context.navigationId }),
         ...(context.stackTrace && { stackTrace: context.stackTrace }),
+        ...(context.source && { source: context.source }),
     };
 }
 /**
@@ -101,7 +112,7 @@ function handleConsoleAPICall(cdp, messages, params, context, includeAll) {
     if (shouldExcludeConsoleMessage(basicText, params.type, includeAll)) {
         return;
     }
-    if (hasArgsNeedingExpansion(params.args)) {
+    if (hasArgsNeedingExpansion(params.args) && !usesFormatSpecifiers(params.args)) {
         handleExpandableMessage(cdp, messages, params, context, basicText);
     }
     else {
@@ -124,12 +135,46 @@ function handleExpandableMessage(cdp, messages, params, context, fallbackText) {
         insertMessageByTimestamp(messages, message);
     });
 }
+/**
+ * Remove V8 stack frame lines from an error description.
+ *
+ * @param description - Error description: message lines followed by stack frame lines
+ * @returns The message lines only
+ */
+function stripStackFrames(description) {
+    const lines = description.split('\n');
+    const firstFrame = lines.findIndex((line) => /^\s+at\s/.test(line));
+    return (firstFrame === -1 ? lines : lines.slice(0, firstFrame)).join('\n').trim();
+}
+/**
+ * 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 function formatExceptionText(details) {
+    const exception = details.exception;
+    const raw = exception?.description ?? (exception?.value !== undefined ? String(exception.value) : '');
+    const detail = stripStackFrames(raw);
+    const prefix = details.text;
+    if (!detail)
+        return prefix || 'Unknown error';
+    if (!prefix || detail.startsWith(prefix))
+        return detail;
+    return `${prefix} ${detail}`;
+}
 /**
  * Handle an exception thrown event.
  */
 function handleExceptionThrown(messages, params, context, includeAll) {
     const exception = params.exceptionDetails;
-    const text = exception.text ?? exception.exception?.description ?? 'Unknown error';
+    const text = formatExceptionText(exception);
     if (shouldExcludeConsoleMessage(text, 'error', includeAll)) {
         return;
     }
@@ -137,7 +182,62 @@ function handleExceptionThrown(messages, params, context, includeAll) {
     insertMessageByTimestamp(messages, message);
 }
 /**
- * Start collecting console messages and exceptions via CDP Runtime domain.
+ * Handle a browser log entry (failed resource loads, CORS, security,
+ * deprecations). Entries without a stack point at their resource URL.
+ *
+ * Worker entries are skipped: workers are attached directly, so their console
+ * calls already arrive (with arguments) from the worker's own session.
+ */
+function handleLogEntry(messages, entry, navigationId, includeAll) {
+    const type = LOG_LEVEL_TYPES[entry.level];
+    if (entry.source === 'worker' || shouldExcludeConsoleMessage(entry.text, type, includeAll)) {
+        return;
+    }
+    const location = entry.url
+        ? [
+            entry.lineNumber === undefined
+                ? { url: entry.url, lineNumber: -1, columnNumber: -1 }
+                : { url: entry.url, lineNumber: entry.lineNumber, columnNumber: 0 },
+        ]
+        : undefined;
+    const context = {
+        navigationId,
+        stackTrace: convertStackTrace(entry.stackTrace) ?? location,
+        source: entry.source,
+    };
+    insertMessageByTimestamp(messages, createMessage(type, entry.text, entry.timestamp, undefined, context));
+}
+/**
+ * Enable console and log events on an attached target's session.
+ *
+ * @param typed - Typed CDP connection
+ * @param sessionId - Session of the attached target
+ */
+async function enableConsoleEvents(typed, sessionId) {
+    await typed.send('Runtime.enable', {}, sessionId);
+    await typed.send('Log.enable', {}, sessionId);
+}
+/**
+ * Enable browser log entries and attach to iframes and workers. Both only add
+ * messages, so a failure is logged and the session keeps the page's console.
+ *
+ * @param cdp - CDP connection
+ * @param typed - Typed CDP connection
+ * @returns Cleanup that stops attaching to new targets
+ */
+async function startOptionalSources(cdp, typed) {
+    try {
+        await typed.send('Log.enable', {});
+        return await attachChildTargets(cdp, (sessionId) => enableConsoleEvents(typed, sessionId));
+    }
+    catch (error) {
+        log.debug(`Browser messages or iframe/worker consoles unavailable: ${String(error)}`);
+        return () => undefined;
+    }
+}
+/**
+ * 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
@@ -148,13 +248,12 @@ function handleExceptionThrown(messages, params, context, includeAll) {
 export async function startConsoleCollection(cdp, messages, includeAll = false, getCurrentNavigationId) {
     const registry = new CDPHandlerRegistry();
     const typed = new TypedCDPConnection(cdp);
-    await cdp.send('Runtime.enable');
-    registry.registerTyped(typed, 'Runtime.consoleAPICalled', (params) => {
+    registry.registerTyped(typed, 'Runtime.consoleAPICalled', (params, sessionId) => {
         const context = {
             navigationId: getCurrentNavigationId?.(),
             stackTrace: convertStackTrace(params.stackTrace),
         };
-        handleConsoleAPICall(cdp, messages, params, context, includeAll);
+        handleConsoleAPICall(senderFor(cdp, sessionId), messages, params, context, includeAll);
     });
     registry.registerTyped(typed, 'Runtime.exceptionThrown', (params) => {
         const context = {
@@ -163,8 +262,20 @@ export async function startConsoleCollection(cdp, messages, includeAll = false,
         };
         handleExceptionThrown(messages, params, context, includeAll);
     });
-    return () => {
+    registry.registerTyped(typed, 'Log.entryAdded', ({ entry }) => {
+        handleLogEntry(messages, entry, getCurrentNavigationId?.(), includeAll);
+    });
+    try {
+        await typed.send('Runtime.enable', {});
+    }
+    catch (error) {
+        registry.cleanup();
+        throw error;
+    }
+    const detachChildren = await startOptionalSources(cdp, typed);
+    return async () => {
         registry.cleanup();
+        await detachChildren();
     };
 }
 //# sourceMappingURL=console.js.map

package/dist/telemetry/dialogs.d.ts

@@ -1,5 +1,6 @@
 import type { CDPConnection } from '../connection/cdp.js';
-import type { CleanupFunction } from '../types';
+import type { DialogInfo } from '../ipc/protocol/domTypes.js';
+import type { CleanupFunction } from '../types.js';
 /**
  * Start auto-dismissing JavaScript dialogs to prevent collection blocking.
  *
@@ -8,6 +9,7 @@ import type { CleanupFunction } from '../types';
  * further telemetry collection.
  *
  * @param cdp - CDP connection instance
+ * @param onDialog - Called for each accepted dialog
  * @returns Cleanup function to remove event handlers
  *
  * @remarks
@@ -23,5 +25,5 @@ import type { CleanupFunction } from '../types';
  * cleanup(); // Stop handling dialogs
  * ```
  */
-export declare function startDialogHandling(cdp: CDPConnection): Promise<CleanupFunction>;
+export declare function startDialogHandling(cdp: CDPConnection, onDialog?: (dialog: DialogInfo) => void): Promise<CleanupFunction>;
 //# sourceMappingURL=dialogs.d.ts.map

package/dist/telemetry/dialogs.js

@@ -10,6 +10,7 @@ const log = createLogger('dialogs');
  * further telemetry collection.
  *
  * @param cdp - CDP connection instance
+ * @param onDialog - Called for each accepted dialog
  * @returns Cleanup function to remove event handlers
  *
  * @remarks
@@ -25,12 +26,13 @@ const log = createLogger('dialogs');
  * cleanup(); // Stop handling dialogs
  * ```
  */
-export async function startDialogHandling(cdp) {
+export async function startDialogHandling(cdp, onDialog) {
     const registry = new CDPHandlerRegistry();
     const typed = new TypedCDPConnection(cdp);
     await cdp.send('Page.enable');
     registry.registerTyped(typed, 'Page.javascriptDialogOpening', (params) => {
         log.debug(`Auto-dismissing ${params.type} dialog: "${params.message}" from ${params.url}`);
+        onDialog?.({ type: params.type, message: params.message });
         void cdp
             .send('Page.handleJavaScriptDialog', {
             accept: true,

package/dist/telemetry/dom.d.ts

@@ -1,5 +1,5 @@
 import type { CDPConnection } from '../connection/cdp.js';
-import type { DOMData, CleanupFunction } from '../types';
+import type { CleanupFunction } from '../types.js';
 /**
  * Prepare CDP domains for DOM collection.
  *
@@ -9,14 +9,4 @@ import type { DOMData, CleanupFunction } from '../types';
  * @returns Cleanup function that disables Runtime domain
  */
 export declare function prepareDOMCollection(cdp: CDPConnection): Promise<CleanupFunction>;
-/**
- * Capture a complete DOM snapshot of the current page.
- *
- * Called during session shutdown to get the final state of the page.
- * Parallelizes independent CDP calls for better performance.
- *
- * @param cdp - CDP connection instance
- * @returns DOM data including URL, title, full HTML, and A11y tree
- */
-export declare function collectDOM(cdp: CDPConnection): Promise<DOMData>;
 //# sourceMappingURL=dom.d.ts.map

package/dist/telemetry/dom.js

@@ -1,9 +1,6 @@
 import { createLogger } from '../ui/logging/index.js';
 import { getErrorMessage } from '../utils/errors.js';
-import { buildTreeFromRawNodes } from './a11y.js';
-import { withTimeout } from './utils.js';
 const log = createLogger('dom');
-const CDP_TIMEOUT = 5000;
 /**
  * Prepare CDP domains for DOM collection.
  *
@@ -27,103 +24,4 @@ export async function prepareDOMCollection(cdp) {
         }
     };
 }
-/**
- * Get the root node of the DOM tree.
- */
-async function getDocumentRoot(cdp) {
-    const response = await withTimeout(cdp.send('DOM.getDocument', { depth: -1 }), CDP_TIMEOUT, 'DOM.getDocument');
-    return response.root;
-}
-/**
- * Get the outer HTML of a node.
- */
-async function getOuterHTML(cdp, nodeId) {
-    const response = await withTimeout(cdp.send('DOM.getOuterHTML', { nodeId }), CDP_TIMEOUT, 'DOM.getOuterHTML');
-    return response.outerHTML;
-}
-/**
- * Get the main frame information.
- */
-async function getMainFrame(cdp) {
-    const response = await withTimeout(cdp.send('Page.getFrameTree'), CDP_TIMEOUT, 'Page.getFrameTree');
-    return response.frameTree.frame;
-}
-/**
- * Get the document title using Runtime.evaluate.
- */
-async function getDocumentTitle(cdp) {
-    try {
-        const result = await withTimeout(cdp.send('Runtime.evaluate', {
-            expression: 'document.title',
-            returnByValue: true,
-        }), CDP_TIMEOUT, 'Runtime.evaluate');
-        if (result.result.value !== undefined && typeof result.result.value === 'string') {
-            return result.result.value;
-        }
-    }
-    catch (error) {
-        log.debug(`Failed to get document title: ${getErrorMessage(error)}`);
-    }
-    return 'Untitled';
-}
-/**
- * Capture accessibility tree from the current page.
- *
- * @param cdp - CDP connection instance
- * @returns A11y tree with nodes serialized as plain object, or undefined on error
- */
-async function collectA11yTree(cdp) {
-    try {
-        await cdp.send('Accessibility.enable');
-        const response = (await withTimeout(cdp.send('Accessibility.getFullAXTree', {}), CDP_TIMEOUT, 'Accessibility.getFullAXTree'));
-        if (!response.nodes) {
-            return undefined;
-        }
-        const tree = buildTreeFromRawNodes(response.nodes);
-        await cdp.send('Accessibility.disable').catch(() => {
-            /* Ignore errors */
-        });
-        return {
-            root: tree.root,
-            nodes: Object.fromEntries(tree.nodes),
-            count: tree.count,
-        };
-    }
-    catch (error) {
-        log.debug(`A11y tree capture failed: ${getErrorMessage(error)}`);
-        return undefined;
-    }
-}
-/**
- * Capture a complete DOM snapshot of the current page.
- *
- * Called during session shutdown to get the final state of the page.
- * Parallelizes independent CDP calls for better performance.
- *
- * @param cdp - CDP connection instance
- * @returns DOM data including URL, title, full HTML, and A11y tree
- */
-export async function collectDOM(cdp) {
-    try {
-        // Run independent CDP calls in parallel for better performance
-        const [root, frame, title, a11yTree] = await Promise.all([
-            getDocumentRoot(cdp),
-            getMainFrame(cdp),
-            getDocumentTitle(cdp),
-            collectA11yTree(cdp),
-        ]);
-        // getOuterHTML depends on root.nodeId, so it must be sequential
-        const outerHTML = await getOuterHTML(cdp, root.nodeId);
-        return {
-            url: frame.url,
-            title,
-            outerHTML,
-            ...(a11yTree && { a11yTree }),
-        };
-    }
-    catch (error) {
-        log.info(`DOM capture failed: ${getErrorMessage(error)}`);
-        throw error;
-    }
-}
 //# sourceMappingURL=dom.js.map

package/dist/telemetry/filterDsl.d.ts

@@ -6,7 +6,7 @@
  * header inspection, and various state filters.
  */
 import type { NetworkRequest } from '../types.js';
-export type FilterType = 'domain' | 'status-code' | 'method' | 'mime-type' | 'resource-type' | 'larger-than' | 'has-response-header' | 'is' | 'scheme';
+export type FilterType = 'domain' | 'status-code' | 'method' | 'mime-type' | 'resource-type' | 'larger-than' | 'duration' | 'has-response-header' | 'is' | 'scheme';
 export type ComparisonOperator = '=' | '>=' | '<=' | '>' | '<';
 export interface ParsedFilter {
     type: FilterType;
@@ -22,6 +22,14 @@ export type FilterValidationResult = {
     error: string;
     suggestion?: string;
 };
+/**
+ * Parse a duration into milliseconds.
+ *
+ * @param value - e.g. "500", "500ms", "1.5s"
+ * @returns Milliseconds
+ * @throws Error for another format
+ */
+export declare function parseDuration(value: string): number;
 /**
  * Parse a size string with units into bytes.
  */