browser-debugger-cli 0.7.2 → 0.9.0

package/dist/telemetry/har/builder.js

@@ -1,6 +1,14 @@
 /**
  * HAR (HTTP Archive) builder for transforming network telemetry to HAR 1.2 format.
  */
+import { createRequire } from 'node:module';
+import { skippedBodyReason } from '../network.js';
+/**
+ * Loads Node builtins on first use: importing `node:http` in an ES module
+ * reads all its exports, which loads undici and zlib (about 8 ms of every CLI
+ * start), though only `network har` needs the status texts.
+ */
+const requireBuiltin = createRequire(import.meta.url);
 const UNKNOWN_TIMING = -1;
 const DEFAULT_HTTP_VERSION = 'HTTP/1.1';
 /**
@@ -25,7 +33,7 @@ const DEFAULT_HTTP_VERSION = 'HTTP/1.1';
  * ```
  */
 export function buildHAR(requests, metadata) {
-    const entries = requests.map((req) => buildEntry(req));
+    const entries = [...requests].sort((a, b) => a.timestamp - b.timestamp).map(buildEntry);
     const log = {
         version: '1.2',
         creator: {
@@ -68,8 +76,25 @@ function buildEntry(req) {
     if (req.resourceType) {
         entry._resourceType = req.resourceType;
     }
+    if (req.webSocket) {
+        entry._webSocketMessages = req.webSocket.frames.map(buildWebSocketMessage);
+    }
     return entry;
 }
+/**
+ * Build a HAR WebSocket message from a captured frame.
+ *
+ * @param frame - Captured WebSocket frame
+ * @returns HAR WebSocket message
+ */
+function buildWebSocketMessage(frame) {
+    return {
+        type: frame.direction === 'sent' ? 'send' : 'receive',
+        time: frame.timestamp / 1000,
+        opcode: frame.opcode,
+        data: frame.payloadData,
+    };
+}
 /**
  * Build HAR request object.
  *
@@ -82,7 +107,7 @@ function buildRequest(req) {
         method: req.method,
         url: req.url,
         httpVersion: DEFAULT_HTTP_VERSION,
-        cookies: extractCookies(req.requestHeaders),
+        cookies: extractRequestCookies(req.requestHeaders),
         headers: convertHeaders(req.requestHeaders),
         queryString: extractQueryParams(url),
         headersSize: estimateRequestHeadersSize(req.method, req.url, req.requestHeaders),
@@ -101,76 +126,59 @@ function buildRequest(req) {
  * @returns HAR response object
  */
 function buildResponse(req) {
-    const bodySize = req.encodedDataLength ?? (req.responseBody ? Buffer.byteLength(req.responseBody, 'utf-8') : 0);
+    const bodySize = req.encodedDataLength ?? req.decodedBodyLength ?? 0;
     return {
         status: req.status ?? 0,
-        statusText: getStatusText(req.status),
+        statusText: req.statusText ?? getStatusText(req.status),
+        ...(req.status === 0 && req.errorText && { _error: req.errorText }),
         httpVersion: DEFAULT_HTTP_VERSION,
-        cookies: extractCookies(req.responseHeaders),
+        cookies: extractResponseCookies(req.responseHeaders),
         headers: convertHeaders(req.responseHeaders),
         content: buildContent(req),
-        redirectURL: extractRedirectURL(req.responseHeaders),
+        redirectURL: extractRedirectURL(req),
         headersSize: estimateResponseHeadersSize(req.status, req.responseHeaders),
         bodySize,
     };
 }
 /**
- * Build content object for response body.
+ * Build the HAR content object for a response.
  *
- * @param req - Network request data
- * @returns HAR content object
+ * A body that bdg chose not to fetch is exported without `text` and with the
+ * reason as `comment`, instead of the placeholder pretending to be the body.
  *
- * @remarks
- * Uses decodedBodyLength if available, otherwise calculates from responseBody.
- * The size field represents the uncompressed/decoded content size.
+ * @param req - Network request
+ * @returns HAR content
  */
 function buildContent(req) {
-    const { text, encoding } = encodeBody(req.responseBody, req.mimeType);
-    const size = req.decodedBodyLength ?? (req.responseBody ? Buffer.byteLength(req.responseBody, 'utf-8') : 0);
-    const content = {
-        size,
-        mimeType: req.mimeType ?? 'application/octet-stream',
-    };
-    if (text !== undefined) {
-        content.text = text;
-    }
-    if (encoding !== undefined) {
-        content.encoding = encoding;
-    }
-    return content;
-}
-/**
- * Encode response body with appropriate encoding.
- *
- * Auto-detects binary content and applies base64 encoding.
- *
- * @param body - Response body string
- * @param mimeType - Response MIME type
- * @returns Encoded text and encoding type
- */
-function encodeBody(body, mimeType) {
-    if (!body) {
-        return {};
-    }
-    if (isBinaryMimeType(mimeType)) {
+    const mimeType = req.mimeType ?? 'application/octet-stream';
+    const skipped = skippedBodyReason(req.responseBody);
+    if (skipped !== undefined) {
         return {
-            text: Buffer.from(body).toString('base64'),
-            encoding: 'base64',
+            size: req.decodedBodyLength ?? contentLength(req) ?? req.encodedDataLength ?? 0,
+            mimeType,
+            comment: `Body not captured: ${skipped}`,
         };
     }
-    return { text: body };
+    const size = req.decodedBodyLength ?? (req.responseBody ? Buffer.byteLength(req.responseBody, 'utf-8') : 0);
+    const text = typeof req.responseBody === 'string' ? req.responseBody : undefined;
+    const encoding = req.responseBodyBase64 ? 'base64' : undefined;
+    return {
+        size,
+        mimeType,
+        ...(text !== undefined && { text }),
+        ...(encoding !== undefined && { encoding }),
+    };
 }
 /**
- * Check if MIME type represents binary content.
+ * Body size announced by the server (`encodedDataLength` also counts headers).
  *
- * @param mimeType - MIME type to check
- * @returns True if binary content
+ * @param req - Network request
+ * @returns Content-Length in bytes, if given
  */
-function isBinaryMimeType(mimeType) {
-    if (!mimeType)
-        return false;
-    const binaryTypes = ['image/', 'video/', 'audio/', 'application/pdf', 'application/zip'];
-    return binaryTypes.some((type) => mimeType.startsWith(type));
+function contentLength(req) {
+    const value = getHeader(req.responseHeaders, 'content-length');
+    const bytes = value === undefined ? NaN : Number(value);
+    return Number.isInteger(bytes) && bytes >= 0 ? bytes : undefined;
 }
 /**
  * Build POST data object if request has body.
@@ -181,95 +189,62 @@ function isBinaryMimeType(mimeType) {
 function buildPostData(req) {
     if (!req.requestBody)
         return undefined;
-    const contentType = req.requestHeaders?.['content-type'] ?? 'text/plain';
+    const contentType = getHeader(req.requestHeaders, 'content-type') ?? 'text/plain';
     return {
         mimeType: contentType,
-        params: [],
         text: req.requestBody,
     };
 }
 /**
- * Build timing object from NetworkRequest timing data.
+ * Duration between two CDP timing offsets (ms), or -1 if either is unknown.
  *
- * @param req - Network request data
- * @returns HAR timings object
+ * @param start - Start offset (-1 when not applicable)
+ * @param end - End offset (-1 when not applicable)
+ * @returns Duration in ms, or -1
+ */
+function span(start, end) {
+    if (start === undefined || end === undefined || start < 0 || end < 0 || end < start) {
+        return UNKNOWN_TIMING;
+    }
+    return end - start;
+}
+/**
+ * Build HAR timings from CDP resource timing.
  *
- * @remarks
- * Uses real timing data from CDP Network.responseReceived event.
- * Falls back to -1 (unknown) for missing timing fields (HAR spec compliant).
- *
- * HAR timing breakdown:
- * - blocked: Time waiting for network slot (DNS queue time)
- * - dns: DNS resolution time
- * - connect: TCP connection time
- * - ssl: SSL/TLS handshake time (if HTTPS)
- * - send: Time sending HTTP request
- * - wait: Time waiting for server response (TTFB)
- * - receive: Time receiving response data
+ * HAR 1.2: blocked/dns/connect/ssl may be -1 (not applicable); send, wait
+ * and receive are required to be non-negative. A response served from the
+ * browser cache carries the timing of the request that originally fetched
+ * it, so only its measured duration is used.
+ *
+ * @param req - Network request
+ * @returns HAR timings
  */
 function buildTimings(req) {
-    if (!req.timing) {
+    const t = req.timing;
+    if (!t || req.fromCache) {
         return {
             blocked: UNKNOWN_TIMING,
             dns: UNKNOWN_TIMING,
             connect: UNKNOWN_TIMING,
-            send: UNKNOWN_TIMING,
-            wait: UNKNOWN_TIMING,
-            receive: UNKNOWN_TIMING,
+            send: 0,
+            wait: 0,
+            receive: req.fromCache ? (req.duration ?? 0) : 0,
             ssl: UNKNOWN_TIMING,
         };
     }
-    const t = req.timing;
-    const blocked = t.dnsStart !== undefined && t.dnsStart >= 0 ? t.dnsStart : UNKNOWN_TIMING;
-    const dns = t.dnsStart !== undefined &&
-        t.dnsEnd !== undefined &&
-        t.dnsStart >= 0 &&
-        t.dnsEnd >= 0 &&
-        t.dnsEnd > t.dnsStart
-        ? t.dnsEnd - t.dnsStart
-        : UNKNOWN_TIMING;
-    const connect = t.connectStart !== undefined &&
-        t.connectEnd !== undefined &&
-        t.connectStart >= 0 &&
-        t.connectEnd >= 0 &&
-        t.connectEnd > t.connectStart
-        ? t.connectEnd - t.connectStart
-        : UNKNOWN_TIMING;
-    const ssl = t.sslStart !== undefined &&
-        t.sslEnd !== undefined &&
-        t.sslStart >= 0 &&
-        t.sslEnd >= 0 &&
-        t.sslEnd > t.sslStart
-        ? t.sslEnd - t.sslStart
-        : UNKNOWN_TIMING;
-    const send = t.sendStart !== undefined &&
-        t.sendEnd !== undefined &&
-        t.sendStart >= 0 &&
-        t.sendEnd >= 0 &&
-        t.sendEnd > t.sendStart
-        ? t.sendEnd - t.sendStart
-        : UNKNOWN_TIMING;
-    const wait = t.sendEnd !== undefined &&
-        t.receiveHeadersEnd !== undefined &&
-        t.sendEnd >= 0 &&
-        t.receiveHeadersEnd >= 0 &&
-        t.receiveHeadersEnd > t.sendEnd
-        ? t.receiveHeadersEnd - t.sendEnd
-        : UNKNOWN_TIMING;
     const receive = req.loadingFinishedTime !== undefined &&
         t.requestTime !== undefined &&
-        t.receiveHeadersEnd !== undefined &&
-        t.receiveHeadersEnd >= 0
+        t.receiveHeadersEnd !== undefined
         ? (req.loadingFinishedTime - t.requestTime) * 1000 - t.receiveHeadersEnd
-        : UNKNOWN_TIMING;
+        : 0;
     return {
-        blocked,
-        dns,
-        connect,
-        send,
-        wait,
-        receive,
-        ssl,
+        blocked: t.dnsStart !== undefined && t.dnsStart >= 0 ? t.dnsStart : UNKNOWN_TIMING,
+        dns: span(t.dnsStart, t.dnsEnd),
+        connect: span(t.connectStart, t.connectEnd),
+        ssl: span(t.sslStart, t.sslEnd),
+        send: Math.max(0, span(t.sendStart, t.sendEnd)),
+        wait: Math.max(0, span(t.sendEnd, t.receiveHeadersEnd)),
+        receive: Math.max(0, receive),
     };
 }
 /**
@@ -312,36 +287,106 @@ function convertHeaders(headers) {
     }));
 }
 /**
- * Extract cookies from headers.
+ * Look up a header value case-insensitively.
  *
- * @param headers - Headers object
- * @returns Array of HAR cookie objects
+ * CDP keeps the original header casing for HTTP/1.1 (`Content-Type`,
+ * `Set-Cookie`) and lowercases it for HTTP/2.
+ *
+ * @param headers - Header map
+ * @param name - Header name (any case)
+ * @returns Header value, if present
  */
-function extractCookies(headers) {
+function getHeader(headers, name) {
     if (!headers)
+        return undefined;
+    const lower = name.toLowerCase();
+    const key = Object.keys(headers).find((k) => k.toLowerCase() === lower);
+    return key === undefined ? undefined : headers[key];
+}
+/**
+ * Extract request cookies from the `Cookie` header.
+ *
+ * @param headers - Request headers
+ * @returns HAR cookies
+ */
+function extractRequestCookies(headers) {
+    const header = getHeader(headers, 'cookie');
+    if (!header)
         return [];
-    const cookieHeader = headers['cookie'] ?? headers['set-cookie'];
-    if (!cookieHeader)
+    return header
+        .split(';')
+        .map((pair) => parseNameValue(pair))
+        .filter((cookie) => cookie !== null);
+}
+/**
+ * Extract response cookies from `Set-Cookie` headers.
+ *
+ * CDP joins multiple `Set-Cookie` headers with newlines; each line is one
+ * cookie whose first `name=value` pair is the cookie and the rest are
+ * attributes (Path, Domain, Expires, HttpOnly, Secure).
+ *
+ * @param headers - Response headers
+ * @returns HAR cookies
+ */
+function extractResponseCookies(headers) {
+    const header = getHeader(headers, 'set-cookie');
+    if (!header)
         return [];
-    return parseCookies(cookieHeader);
+    return header
+        .split('\n')
+        .map(parseSetCookie)
+        .filter((cookie) => cookie !== null);
 }
 /**
- * Parse cookie header string into HAR cookie objects.
+ * Parse a `name=value` pair.
  *
- * @param cookieHeader - Cookie header string
- * @returns Array of HAR cookie objects
+ * @param pair - Raw pair
+ * @returns Cookie, or null if there is no name
  */
-function parseCookies(cookieHeader) {
-    const cookies = [];
-    const cookiePairs = cookieHeader.split(';').map((c) => c.trim());
-    for (const pair of cookiePairs) {
-        const [name, ...valueParts] = pair.split('=');
-        const value = valueParts.join('=');
-        if (name && value) {
-            cookies.push({ name: name.trim(), value: value.trim() });
+function parseNameValue(pair) {
+    const eq = pair.indexOf('=');
+    const name = (eq === -1 ? pair : pair.slice(0, eq)).trim();
+    if (!name)
+        return null;
+    return { name, value: eq === -1 ? '' : pair.slice(eq + 1).trim() };
+}
+/**
+ * Parse one `Set-Cookie` header line.
+ *
+ * @param line - Header line
+ * @returns Cookie with attributes, or null if malformed
+ */
+function parseSetCookie(line) {
+    const [first = '', ...attributes] = line.split(';');
+    const cookie = parseNameValue(first);
+    if (!cookie)
+        return null;
+    for (const attribute of attributes) {
+        const { name, value } = parseNameValue(attribute) ?? { name: '', value: '' };
+        switch (name.toLowerCase()) {
+            case 'path':
+                cookie.path = value;
+                break;
+            case 'domain':
+                cookie.domain = value;
+                break;
+            case 'expires': {
+                const date = new Date(value);
+                if (!Number.isNaN(date.getTime()))
+                    cookie.expires = date.toISOString();
+                break;
+            }
+            case 'httponly':
+                cookie.httpOnly = true;
+                break;
+            case 'secure':
+                cookie.secure = true;
+                break;
+            default:
+                break;
         }
     }
-    return cookies;
+    return cookie;
 }
 /**
  * Extract query parameters from URL.
@@ -357,13 +402,13 @@ function extractQueryParams(url) {
     return params;
 }
 /**
- * Extract redirect URL from Location header.
+ * Determine the redirect target of a response.
  *
- * @param headers - Response headers
- * @returns Redirect URL or empty string
+ * @param req - Network request
+ * @returns Redirect URL, or '' when the response is not a redirect
  */
-function extractRedirectURL(headers) {
-    return headers?.['location'] ?? '';
+function extractRedirectURL(req) {
+    return req.redirectURL ?? getHeader(req.responseHeaders, 'location') ?? '';
 }
 /**
  * Estimate request headers size in bytes including HTTP request line.
@@ -419,22 +464,7 @@ function estimateResponseHeadersSize(status, headers) {
  */
 function getStatusText(status) {
     if (!status)
-        return 'Unknown';
-    const statusTexts = {
-        200: 'OK',
-        201: 'Created',
-        204: 'No Content',
-        301: 'Moved Permanently',
-        302: 'Found',
-        304: 'Not Modified',
-        400: 'Bad Request',
-        401: 'Unauthorized',
-        403: 'Forbidden',
-        404: 'Not Found',
-        500: 'Internal Server Error',
-        502: 'Bad Gateway',
-        503: 'Service Unavailable',
-    };
-    return statusTexts[status] ?? 'Unknown';
+        return '';
+    return requireBuiltin('node:http').STATUS_CODES[status] ?? '';
 }
 //# sourceMappingURL=builder.js.map

package/dist/telemetry/har/types.d.ts

@@ -100,6 +100,21 @@ export interface Entry {
     comment?: string;
     /** CDP resource type (custom field per HAR spec) */
     _resourceType?: string;
+    /** Messages of a WebSocket connection (Chrome DevTools convention) */
+    _webSocketMessages?: WebSocketMessage[];
+}
+/**
+ * A WebSocket message (Chrome DevTools HAR convention).
+ */
+export interface WebSocketMessage {
+    /** Whether the page sent or received the message */
+    type: 'send' | 'receive';
+    /** Time the message was sent or received (seconds since the epoch) */
+    time: number;
+    /** WebSocket opcode (1 = text, 2 = binary) */
+    opcode: number;
+    /** Message payload (base64 for binary messages) */
+    data: string;
 }
 /**
  * Request object containing detailed info about the request.
@@ -148,6 +163,8 @@ export interface Response {
     headersSize: number;
     /** Size of the received response body in bytes (-1 if not available) */
     bodySize: number;
+    /** Network error for requests that got no response (Chrome DevTools convention) */
+    _error?: string;
     /** Comment (optional) */
     comment?: string;
 }
@@ -200,10 +217,10 @@ export interface QueryParam {
 export interface PostData {
     /** MIME type of posted data */
     mimeType: string;
-    /** List of posted parameters (parsed from request body) */
-    params: PostParam[];
-    /** Plain text posted data */
-    text: string;
+    /** List of posted parameters (mutually exclusive with `text` per HAR 1.2) */
+    params?: PostParam[];
+    /** Plain text posted data (mutually exclusive with `params` per HAR 1.2) */
+    text?: string;
     /** Comment (optional) */
     comment?: string;
 }

package/dist/telemetry/navigation.d.ts

@@ -1,5 +1,5 @@
 import type { CDPConnection } from '../connection/cdp.js';
-import type { CleanupFunction } from '../types';
+import type { CleanupFunction } from '../types.js';
 /**
  * Navigation event information.
  */
@@ -11,39 +11,23 @@ export interface NavigationEvent {
     /** Navigation counter (increments with each main frame navigation) */
     navigationId: number;
 }
+/**
+ * Navigation counters exposed by the tracker.
+ */
+export interface NavigationTracker {
+    cleanup: CleanupFunction;
+    /** Increments on each main-frame navigation; groups console/network data per page. */
+    getCurrentNavigationId: () => number;
+}
 /**
  * Start tracking page navigation events.
  *
- * Monitors main frame navigations (page loads, URL changes) and maintains
- * a navigation counter that increments with each navigation. This counter
- * can be used to detect stale references (e.g., network request indices
- * from a previous page load).
+ * `navigationId` counts main-frame navigations only, so all console messages
+ * and requests of one page load share an id.
  *
  * @param cdp - CDP connection instance
  * @param navigations - Array to populate with navigation events
- * @returns Object with cleanup function and getCurrentNavigationId getter
- *
- * @remarks
- * - Only tracks main frame navigations (ignores iframe navigations)
- * - Navigation ID starts at 0 and increments with each navigation
- * - Initial page load counts as navigation 0
- *
- * @example
- * ```typescript
- * const navs: NavigationEvent[] = [];
- * const { cleanup, getCurrentNavigationId } = await startNavigationTracking(cdp, navs);
- *
- * // Later, validate if a reference is stale:
- * const currentNavId = getCurrentNavigationId();
- * if (referenceNavId !== currentNavId) {
- *   throw new Error('Stale reference - page has navigated');
- * }
- *
- * cleanup();
- * ```
+ * @returns Cleanup function and counter getters
  */
-export declare function startNavigationTracking(cdp: CDPConnection, navigations: NavigationEvent[]): Promise<{
-    cleanup: CleanupFunction;
-    getCurrentNavigationId: () => number;
-}>;
+export declare function startNavigationTracking(cdp: CDPConnection, navigations: NavigationEvent[]): Promise<NavigationTracker>;
 //# sourceMappingURL=navigation.d.ts.map

package/dist/telemetry/navigation.js

@@ -5,63 +5,29 @@ const log = createLogger('navigation');
 /**
  * Start tracking page navigation events.
  *
- * Monitors main frame navigations (page loads, URL changes) and maintains
- * a navigation counter that increments with each navigation. This counter
- * can be used to detect stale references (e.g., network request indices
- * from a previous page load).
+ * `navigationId` counts main-frame navigations only, so all console messages
+ * and requests of one page load share an id.
  *
  * @param cdp - CDP connection instance
  * @param navigations - Array to populate with navigation events
- * @returns Object with cleanup function and getCurrentNavigationId getter
- *
- * @remarks
- * - Only tracks main frame navigations (ignores iframe navigations)
- * - Navigation ID starts at 0 and increments with each navigation
- * - Initial page load counts as navigation 0
- *
- * @example
- * ```typescript
- * const navs: NavigationEvent[] = [];
- * const { cleanup, getCurrentNavigationId } = await startNavigationTracking(cdp, navs);
- *
- * // Later, validate if a reference is stale:
- * const currentNavId = getCurrentNavigationId();
- * if (referenceNavId !== currentNavId) {
- *   throw new Error('Stale reference - page has navigated');
- * }
- *
- * cleanup();
- * ```
+ * @returns Cleanup function and counter getters
  */
 export async function startNavigationTracking(cdp, navigations) {
     const registry = new CDPHandlerRegistry();
     const typed = new TypedCDPConnection(cdp);
     let navigationCounter = 0;
     await cdp.send('Page.enable');
-    const initialNavigation = {
-        url: '',
-        timestamp: Date.now(),
-        navigationId: navigationCounter,
-    };
-    navigations.push(initialNavigation);
+    navigations.push({ url: '', timestamp: Date.now(), navigationId: navigationCounter });
     registry.registerTyped(typed, 'Page.frameNavigated', (params) => {
-        if (params.frame.parentId === undefined) {
-            navigationCounter++;
-            const navigation = {
-                url: params.frame.url,
-                timestamp: Date.now(),
-                navigationId: navigationCounter,
-            };
-            navigations.push(navigation);
-            log.debug(`Main frame navigation detected [${navigationCounter}]: ${params.frame.url}`);
-        }
-    });
-    // Track DOM.documentUpdated for SPA re-renders and document replacements
-    // This fires when the document is completely replaced (React root re-renders, etc.)
-    await cdp.send('DOM.enable');
-    registry.registerTyped(typed, 'DOM.documentUpdated', () => {
+        if (params.frame.parentId !== undefined)
+            return;
         navigationCounter++;
-        log.debug(`DOM document updated [${navigationCounter}]`);
+        navigations.push({
+            url: params.frame.url,
+            timestamp: Date.now(),
+            navigationId: navigationCounter,
+        });
+        log.debug(`Main frame navigation detected [${navigationCounter}]: ${params.frame.url}`);
     });
     return {
         cleanup: () => {