browser-debugger-cli 0.7.2 → 0.9.0

package/dist/ui/formatters/details.d.ts

@@ -1,6 +1,9 @@
-import type { NetworkRequest, ConsoleMessage } from '../../types';
+import type { NetworkRequest, ConsoleMessage } from '../../types.js';
 /**
- * Format network request details for human-readable output
+ * Format network request details for human-readable output.
+ *
+ * @param request - Captured request
+ * @returns Formatted details
  */
 export declare function formatNetworkDetails(request: NetworkRequest): string;
 /**

package/dist/ui/formatters/details.js

@@ -1,42 +1,193 @@
-import { OutputFormatter } from '../../ui/formatting.js';
+import { skippedBodyReason } from '../../telemetry/network.js';
+import { formatFramePosition, formatTimestamp } from './console/shared.js';
+import { formatRequestStatus } from './requestStatus.js';
+import { OutputFormatter } from '../formatting.js';
+import { sessionCommand } from '../messages/sessionCommand.js';
+import { truncateByLength } from '../../utils/strings.js';
+/** Characters of each WebSocket message shown in human output (`--json` has all) */
+const MESSAGE_PREVIEW_LENGTH = 200;
+/** WebSocket opcode of binary messages */
+const BINARY_OPCODE = 2;
 /**
- * Format network request details for human-readable output
+ * Format one WebSocket message as a single line: direction, time, payload.
+ *
+ * @param frame - Captured frame
+ * @returns Line like `↑ 12:00:00.123  hello` (`[truncated]` when the capture was cut)
  */
-export function formatNetworkDetails(request) {
-    const fmt = new OutputFormatter();
-    fmt.text('Network Request Details').separator('━', 70);
-    fmt.keyValueList([
+function formatWebSocketMessage(frame) {
+    const arrow = frame.direction === 'sent' ? '↑' : '↓';
+    const time = formatTimestamp(frame.timestamp);
+    const truncated = frame.truncatedFrom === undefined ? '' : ' [truncated]';
+    const payload = frame.opcode === BINARY_OPCODE
+        ? binaryMessagePreview(frame.payloadData)
+        : textPreview(frame.payloadData);
+    return `  ${arrow} ${time}  ${payload}${truncated}`;
+}
+/**
+ * A message payload on one line, shortened to {@link MESSAGE_PREVIEW_LENGTH}.
+ *
+ * @param text - Payload text
+ * @returns Preview
+ */
+function textPreview(text) {
+    return truncateByLength(text.replace(/\s+/g, ' '), MESSAGE_PREVIEW_LENGTH);
+}
+/**
+ * Describe a binary message, with its text when it is valid UTF-8 without
+ * control characters (many protocols send JSON or text in binary frames).
+ *
+ * @param base64 - Payload as captured (base64)
+ * @returns e.g. `(binary, 42 bytes) {"op":"ping"}` or `(binary, 42 bytes captured)`
+ */
+function binaryMessagePreview(base64) {
+    const bytes = Buffer.from(base64, 'base64');
+    const text = readableText(bytes);
+    return text === undefined
+        ? `(binary, ${bytes.length} bytes captured)`
+        : `(binary, ${bytes.length} bytes) ${textPreview(text)}`;
+}
+/**
+ * The bytes as text, if they are valid UTF-8 and printable.
+ *
+ * @param bytes - Raw bytes
+ * @returns Text, or undefined for binary data
+ */
+function readableText(bytes) {
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+    const printable = (char) => {
+        const code = char.charCodeAt(0);
+        return (code >= 0x20 && code !== 0x7f) || char === '\t' || char === '\n' || char === '\r';
+    };
+    return text.length > 0 && Array.from(text).every(printable) ? text : undefined;
+}
+/**
+ * Add the messages of a WebSocket connection.
+ *
+ * @param fmt - Formatter to add to
+ * @param webSocket - Connection messages and lifecycle
+ */
+function addWebSocketMessages(fmt, webSocket) {
+    const state = webSocket.closedTime
+        ? `closed at ${new Date(webSocket.closedTime).toISOString()}`
+        : 'open';
+    fmt.blank();
+    fmt.text(`WebSocket Messages (${webSocket.frames.length}, ${state}):`).separator('━', 70);
+    webSocket.frames.forEach((frame) => fmt.text(formatWebSocketMessage(frame)));
+}
+/** Characters of a text body shown in human output (`--json` has all of it) */
+const BODY_PREVIEW_LENGTH = 20000;
+/**
+ * Format a byte count for humans.
+ *
+ * @param bytes - Byte count
+ * @returns e.g. "512 B", "12.3 KB"
+ */
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    return bytes < 1024 * 1024
+        ? `${(bytes / 1024).toFixed(1)} KB`
+        : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+/**
+ * Summary rows of a request: identity, outcome, timing and size.
+ *
+ * @param request - Captured request
+ * @returns Label/value rows
+ */
+function requestSummaryRows(request) {
+    const rows = [
         ['Request ID', request.requestId],
         ['URL', request.url],
         ['Method', request.method],
-        ['Status', request.status?.toString() ?? 'pending'],
+        ['Status', formatRequestStatus(request)],
         ['Resource Type', request.resourceType ?? 'N/A'],
         ['MIME Type', request.mimeType ?? 'N/A'],
-    ], 13);
+        ['Started', formatTimestamp(request.timestamp)],
+        ['Duration', request.duration === undefined ? 'pending' : `${Math.round(request.duration)} ms`],
+    ];
+    if (request.encodedDataLength !== undefined) {
+        const decoded = request.decodedBodyLength;
+        const sizes = [`${formatBytes(request.encodedDataLength)} transferred`];
+        if (decoded !== undefined)
+            sizes.push(`${formatBytes(decoded)} body`);
+        rows.push(['Size', sizes.join(', ')]);
+    }
+    if (request.fromCache)
+        rows.push(['From Cache', 'yes']);
+    if (request.serverIPAddress)
+        rows.push(['Remote Address', request.serverIPAddress]);
+    if (request.blockedReason)
+        rows.push(['Blocked', request.blockedReason]);
+    return rows;
+}
+/**
+ * Add a header block.
+ *
+ * @param fmt - Formatter
+ * @param title - Block title
+ * @param headers - Headers to list
+ */
+function addHeaders(fmt, title, headers) {
+    fmt.text(title).separator('━', 70);
+    Object.entries(headers).forEach(([key, value]) => fmt.text(`  ${key}: ${value}`));
     fmt.blank();
-    if (request.requestHeaders) {
-        fmt.text('Request Headers:').separator('━', 70);
-        Object.entries(request.requestHeaders).forEach(([key, value]) => {
-            fmt.text(`  ${key}: ${value}`);
-        });
-        fmt.blank();
+}
+/**
+ * Describe a response body for humans: binary and skipped bodies are
+ * summarized, long text is cut (the JSON output has everything).
+ *
+ * @param request - Captured request with a body
+ * @returns Body text
+ */
+function describeResponseBody(request) {
+    const skipped = skippedBodyReason(request.responseBody);
+    if (skipped !== undefined)
+        return `(not captured: ${skipped})`;
+    if (request.responseBodyBase64) {
+        return `(binary, ${request.decodedBodyLength ?? 0} bytes; base64 in --json and HAR export)`;
     }
+    const body = request.responseBody;
+    if (body.length <= BODY_PREVIEW_LENGTH)
+        return body;
+    return `${body.slice(0, BODY_PREVIEW_LENGTH)}\n… ${body.length - BODY_PREVIEW_LENGTH} more characters (full body: ${sessionCommand(`bdg details network ${request.requestId} --json`)})`;
+}
+/**
+ * Format network request details for human-readable output.
+ *
+ * @param request - Captured request
+ * @returns Formatted details
+ */
+export function formatNetworkDetails(request) {
+    const fmt = new OutputFormatter();
+    fmt.text('Network Request Details').separator('━', 70);
+    fmt.keyValueList(requestSummaryRows(request));
+    fmt.blank();
+    if (request.requestHeaders)
+        addHeaders(fmt, 'Request Headers:', request.requestHeaders);
     if (request.requestBody) {
         fmt.text('Request Body:').separator('━', 70);
         fmt.text(request.requestBody);
         fmt.blank();
     }
-    if (request.responseHeaders) {
-        fmt.text('Response Headers:').separator('━', 70);
-        Object.entries(request.responseHeaders).forEach(([key, value]) => {
-            fmt.text(`  ${key}: ${value}`);
-        });
-        fmt.blank();
+    if (request.responseHeaders)
+        addHeaders(fmt, 'Response Headers:', request.responseHeaders);
+    if (request.bodyNotCaptured) {
+        fmt.text('Response Body:').separator('━', 70);
+        fmt.text(`(not captured: ${request.bodyNotCaptured})`);
     }
-    if (request.responseBody) {
+    else if (request.responseBody) {
         fmt.text('Response Body:').separator('━', 70);
-        fmt.text(request.responseBody);
+        fmt.text(describeResponseBody({ ...request, responseBody: request.responseBody }));
     }
+    if (request.webSocket)
+        addWebSocketMessages(fmt, request.webSocket);
     return fmt.build();
 }
 /**
@@ -47,10 +198,19 @@ export function formatConsoleDetails(message) {
     fmt.text('Console Message Details').separator('━', 70);
     fmt.keyValueList([
         ['Type', message.type],
-        ['Timestamp', new Date(message.timestamp).toISOString()],
+        ['Time', formatTimestamp(message.timestamp)],
+        ...(message.source ? [['Source', message.source]] : []),
         ['Text', message.text],
-    ], 12);
+    ]);
     fmt.blank();
+    if (message.stackTrace && message.stackTrace.length > 0) {
+        fmt.text('Stack Trace:').separator('━', 70);
+        message.stackTrace.forEach((frame) => {
+            const name = frame.functionName?.length ? frame.functionName : '(anonymous)';
+            fmt.text(`  at ${name} (${formatFramePosition(frame)})`);
+        });
+        fmt.blank();
+    }
     if (message.args && message.args.length > 0) {
         fmt.text('Arguments:').separator('━', 70);
         message.args.forEach((arg, idx) => {

package/dist/ui/formatters/dom.d.ts

@@ -1,9 +1,13 @@
+import type { DomFrame } from '../../ipc/protocol/commands.js';
 import type { DomQueryResult, DomGetResult, ScreenshotResult } from '../../types.js';
 /**
  * Format DOM query results for human-readable output.
  *
- * Displays found nodes with their index, tag, classes, and preview text.
- * Shows helpful message when no nodes are found.
+ * Displays found nodes with their index, tag, classes, and preview text
+ * (plus where they are when outside the viewport or hidden, e.g.
+ * `(below fold)`), up to {@link QUERY_DISPLAY_LIMIT} of them (no match is an error, exit 83).
+ * One line of next commands follows; they take the match's index, so they
+ * work for matches in shadow roots and iframes too.
  *
  * @param data - DOM query result containing selector, count, and matching nodes
  * @returns Formatted output string
@@ -50,25 +54,31 @@ export declare function formatDomQuery(data: DomQueryResult): string;
  *   ]
  * });
  * // Output:
- * // [1] <div class="error">Error 1</div>
- * // [2] <span class="error">Error 2</span>
+ * // [0] <div class="error">Error 1</div>
+ * // [1] <span class="error">Error 2</span>
  * ```
  */
 export declare function formatDomGet(data: DomGetResult): string;
 /**
  * Format DOM eval results for human-readable output.
  *
- * Outputs the evaluated JavaScript result as formatted JSON.
+ * A string result is printed as is (not JSON-quoted), so text reads and
+ * pipes like `echo`, unless that would read as another value (empty,
+ * `undefined`, or valid JSON such as `42` or `[1,2]`): then it stays
+ * JSON-quoted. Other values are formatted JSON, and values Chrome only
+ * describes (functions, DOM nodes) their description. The iframe it ran in
+ * (`--frame`) is reported on stderr, so stdout stays the bare value. `--json`
+ * output is unchanged (the value in `data.result`).
  *
  * @param data - DOM eval result containing the evaluated value
- * @returns Formatted JSON string
+ * @returns The string, or formatted JSON
  *
  * @example
  * ```typescript
- * formatDomEval({ result: 'My Page Title' });
- * // Output: "My Page Title"
+ * formatDomEval({ result: 'My Page Title', type: 'string' });
+ * // Output: My Page Title
  *
- * formatDomEval({ result: { url: 'https://example.com', title: 'Example' } });
+ * formatDomEval({ result: { url: 'https://example.com', title: 'Example' }, type: 'object' });
  * // Output:
  * // {
  * //   "url": "https://example.com",
@@ -78,6 +88,26 @@ export declare function formatDomGet(data: DomGetResult): string;
  */
 export declare function formatDomEval(data: {
     result: unknown;
+    type?: string;
+}): string;
+/**
+ * Format the page's iframes, one per line, nested frames indented below
+ * their parent. While the page is still loading (`readyState` set), the list
+ * may be incomplete, and says so.
+ *
+ * @param data - Frames from `bdg dom frames`, with the readyState of a page still loading
+ * @returns Formatted list
+ *
+ * @example
+ * ```
+ * [0] http://localhost:3000/widget  name=widget  same-origin
+ * [1] https://pay.example/  #checkout  cross-origin, out-of-process
+ *   [2] about:blank  same-origin
+ * ```
+ */
+export declare function formatDomFrames(data: {
+    frames: DomFrame[];
+    readyState?: string;
 }): string;
 /**
  * Format screenshot capture result for human-readable display.
@@ -94,6 +124,9 @@ export declare function formatDomEval(data: {
  *
  * formatDomScreenshot({ path: './page.png', fullPageSkipped: { reason: 'page_too_tall', ... } });
  * // Output: Screenshot saved to ./page.png (viewport only - page too tall)
+ *
+ * // An element whose floated children overflow it
+ * // Output: Screenshot saved to ./el.png (grown from 940×37 to 940×285 to include content overflowing the element)
  * ```
  */
 export declare function formatDomScreenshot(data: ScreenshotResult): string;

package/dist/ui/formatters/dom.js

@@ -1,9 +1,15 @@
-import { OutputFormatter } from '../../ui/formatting.js';
+import { OutputFormatter } from '../formatting.js';
+import { frameLabel, moreMatchesNote, framesStillLoadingNote, noFramesMessage, queryNextSteps, screenshotGrownNote, viewportPositionHint, } from '../messages/commands.js';
+/** Matches listed in human output (JSON has all of them) */
+const QUERY_DISPLAY_LIMIT = 50;
 /**
  * Format DOM query results for human-readable output.
  *
- * Displays found nodes with their index, tag, classes, and preview text.
- * Shows helpful message when no nodes are found.
+ * Displays found nodes with their index, tag, classes, and preview text
+ * (plus where they are when outside the viewport or hidden, e.g.
+ * `(below fold)`), up to {@link QUERY_DISPLAY_LIMIT} of them (no match is an error, exit 83).
+ * One line of next commands follows; they take the match's index, so they
+ * work for matches in shadow roots and iframes too.
  *
  * @param data - DOM query result containing selector, count, and matching nodes
  * @returns Formatted output string
@@ -27,32 +33,28 @@ import { OutputFormatter } from '../../ui/formatting.js';
 export function formatDomQuery(data) {
     const { count, nodes, selector } = data;
     const fmt = new OutputFormatter();
-    if (count === 0) {
-        const safeSelector = selector.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
-        return fmt
-            .text(`No nodes found matching "${selector}"`)
-            .blank()
-            .section('Suggestions:', [
-            `Verify selector: bdg dom eval "document.querySelector('${safeSelector}')"`,
-            'List elements:   bdg dom query "*"',
-        ])
-            .build();
-    }
-    const nodeLines = nodes.map((node) => {
-        const classInfo = node.classes?.length ? ` class="${node.classes.join(' ')}"` : '';
-        return `[${node.index}] <${node.tag}${classInfo}> ${node.preview}`;
+    const nodeLines = nodes.slice(0, QUERY_DISPLAY_LIMIT).map((node) => {
+        const attributes = [
+            node.id && ` id="${node.id}"`,
+            node.name && ` name="${node.name}"`,
+            node.type && ` type="${node.type}"`,
+            node.value !== undefined && ` value="${node.value}"`,
+            node.classes?.length && ` class="${node.classes.join(' ')}"`,
+        ]
+            .filter(Boolean)
+            .join('');
+        const context = node.context ? ` (in ${node.context})` : '';
+        const preview = node.preview ? ` ${node.preview}` : '';
+        const position = node.inViewport && viewportPositionHint(node.inViewport, node.clippedBy);
+        const location = position ? ` (${position})` : '';
+        return `[${node.index}] <${node.tag}${attributes}>${context}${preview}${location}`;
     });
-    const hasMultipleResults = count > 1;
-    const exampleIndex = hasMultipleResults ? (nodes[0]?.index ?? 0) : 0;
+    const exampleIndex = nodes[0]?.index ?? 0;
     return fmt
         .text(`Found ${count} node${count === 1 ? '' : 's'} matching "${selector}":`)
         .list(nodeLines)
-        .blank()
-        .section('Next steps:', [
-        `Get HTML:        bdg dom get ${exampleIndex}`,
-        `Extract text:    bdg cdp Runtime.evaluate --params '{"expression": "document.querySelector('${selector.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}').textContent"}'`,
-        `Full details:    bdg details dom ${exampleIndex}`,
-    ])
+        .list(count > QUERY_DISPLAY_LIMIT ? [moreMatchesNote(count - QUERY_DISPLAY_LIMIT)] : [])
+        .tip(queryNextSteps(exampleIndex))
         .build();
 }
 /**
@@ -80,8 +82,8 @@ export function formatDomQuery(data) {
  *   ]
  * });
  * // Output:
- * // [1] <div class="error">Error 1</div>
- * // [2] <span class="error">Error 2</span>
+ * // [0] <div class="error">Error 1</div>
+ * // [1] <span class="error">Error 2</span>
  * ```
  */
 export function formatDomGet(data) {
@@ -92,24 +94,30 @@ export function formatDomGet(data) {
     }
     const fmt = new OutputFormatter();
     nodes.forEach((node, i) => {
-        fmt.text(`[${i + 1}] ${node.outerHTML}`);
+        fmt.text(`[${i}] ${node.outerHTML}`);
     });
     return fmt.build();
 }
 /**
  * Format DOM eval results for human-readable output.
  *
- * Outputs the evaluated JavaScript result as formatted JSON.
+ * A string result is printed as is (not JSON-quoted), so text reads and
+ * pipes like `echo`, unless that would read as another value (empty,
+ * `undefined`, or valid JSON such as `42` or `[1,2]`): then it stays
+ * JSON-quoted. Other values are formatted JSON, and values Chrome only
+ * describes (functions, DOM nodes) their description. The iframe it ran in
+ * (`--frame`) is reported on stderr, so stdout stays the bare value. `--json`
+ * output is unchanged (the value in `data.result`).
  *
  * @param data - DOM eval result containing the evaluated value
- * @returns Formatted JSON string
+ * @returns The string, or formatted JSON
  *
  * @example
  * ```typescript
- * formatDomEval({ result: 'My Page Title' });
- * // Output: "My Page Title"
+ * formatDomEval({ result: 'My Page Title', type: 'string' });
+ * // Output: My Page Title
  *
- * formatDomEval({ result: { url: 'https://example.com', title: 'Example' } });
+ * formatDomEval({ result: { url: 'https://example.com', title: 'Example' }, type: 'object' });
  * // Output:
  * // {
  * //   "url": "https://example.com",
@@ -118,7 +126,58 @@ export function formatDomGet(data) {
  * ```
  */
 export function formatDomEval(data) {
-    return JSON.stringify(data.result, null, 2);
+    if (data.type === 'undefined')
+        return 'undefined';
+    const { result } = data;
+    if (typeof result === 'string' && (data.type !== 'string' || !looksLikeOtherValue(result))) {
+        return result;
+    }
+    return JSON.stringify(result ?? null, null, 2);
+}
+/**
+ * Whether a string printed as is would read as another value: empty,
+ * `undefined`, or valid JSON (`42`, `true`, `null`, `[1,2]`, `{"a":1}`).
+ *
+ * @param text - String result
+ * @returns True when it must be JSON-quoted to read as a string
+ */
+function looksLikeOtherValue(text) {
+    if (text === '' || text === 'undefined')
+        return true;
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Format the page's iframes, one per line, nested frames indented below
+ * their parent. While the page is still loading (`readyState` set), the list
+ * may be incomplete, and says so.
+ *
+ * @param data - Frames from `bdg dom frames`, with the readyState of a page still loading
+ * @returns Formatted list
+ *
+ * @example
+ * ```
+ * [0] http://localhost:3000/widget  name=widget  same-origin
+ * [1] https://pay.example/  #checkout  cross-origin, out-of-process
+ *   [2] about:blank  same-origin
+ * ```
+ */
+export function formatDomFrames(data) {
+    const loading = data.readyState !== undefined && data.readyState !== 'complete';
+    if (data.frames.length === 0)
+        return loading ? framesStillLoadingNote(true) : noFramesMessage();
+    const depthOf = new Map();
+    const lines = data.frames.map((frame) => {
+        const depth = frame.parentIndex === undefined ? 0 : (depthOf.get(frame.parentIndex) ?? 0) + 1;
+        depthOf.set(frame.index, depth);
+        return '  '.repeat(depth) + frameLabel(frame);
+    });
+    return [...lines, ...(loading ? [framesStillLoadingNote(false)] : [])].join('\n');
 }
 /**
  * Format screenshot capture result for human-readable display.
@@ -135,6 +194,9 @@ export function formatDomEval(data) {
  *
  * formatDomScreenshot({ path: './page.png', fullPageSkipped: { reason: 'page_too_tall', ... } });
  * // Output: Screenshot saved to ./page.png (viewport only - page too tall)
+ *
+ * // An element whose floated children overflow it
+ * // Output: Screenshot saved to ./el.png (grown from 940×37 to 940×285 to include content overflowing the element)
  * ```
  */
 export function formatDomScreenshot(data) {
@@ -142,6 +204,9 @@ export function formatDomScreenshot(data) {
     if (data.fullPageSkipped && !data.scrolledTo) {
         output += ' (viewport only - page too tall)';
     }
+    if (data.element?.captured) {
+        output += ` (${screenshotGrownNote(data.element.bounds, data.element.captured)})`;
+    }
     return output;
 }
 //# sourceMappingURL=dom.js.map