browser-debugger-cli 0.8.0 → 0.9.0

package/dist/telemetry/requestState.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lifecycle state of captured network requests.
+ *
+ * A request is pending until it completes or fails. Status 0 means it failed
+ * without any response (DNS, refused, aborted, blocked); a request that got a
+ * response keeps its HTTP status even if loading failed afterwards.
+ */
+import type { NetworkRequest } from '../types.js';
+/** Lifecycle state of a captured request. */
+export type RequestState = 'pending' | 'failed' | 'complete';
+/**
+ * Classify a request.
+ *
+ * @param request - Captured request
+ * @returns Its lifecycle state
+ */
+export declare function getRequestState(request: Pick<NetworkRequest, 'status'>): RequestState;
+/**
+ * Why a request failed, leaving out Chrome stopping an unneeded body after a
+ * complete response (204/304 report `net::ERR_ABORTED` that way).
+ *
+ * @param request - Captured request
+ * @returns Reason, or undefined when there is none worth showing
+ */
+export declare function failureReason(request: Pick<NetworkRequest, 'status' | 'errorText'>): string | undefined;
+/**
+ * Error Chrome reports when it stops reading a response body nobody needs
+ * (the response itself arrived; not a failure of the request).
+ */
+export declare const BODY_ABORTED = "net::ERR_ABORTED";
+//# sourceMappingURL=requestState.d.ts.map

package/dist/telemetry/requestState.js

@@ -0,0 +1,38 @@
+/**
+ * Lifecycle state of captured network requests.
+ *
+ * A request is pending until it completes or fails. Status 0 means it failed
+ * without any response (DNS, refused, aborted, blocked); a request that got a
+ * response keeps its HTTP status even if loading failed afterwards.
+ */
+/**
+ * Classify a request.
+ *
+ * @param request - Captured request
+ * @returns Its lifecycle state
+ */
+export function getRequestState(request) {
+    if (request.status === undefined)
+        return 'pending';
+    return request.status === 0 ? 'failed' : 'complete';
+}
+/**
+ * Why a request failed, leaving out Chrome stopping an unneeded body after a
+ * complete response (204/304 report `net::ERR_ABORTED` that way).
+ *
+ * @param request - Captured request
+ * @returns Reason, or undefined when there is none worth showing
+ */
+export function failureReason(request) {
+    if (!request.errorText)
+        return undefined;
+    return getRequestState(request) === 'complete' && request.errorText === BODY_ABORTED
+        ? undefined
+        : request.errorText;
+}
+/**
+ * Error Chrome reports when it stops reading a response body nobody needs
+ * (the response itself arrived; not a failure of the request).
+ */
+export const BODY_ABORTED = 'net::ERR_ABORTED';
+//# sourceMappingURL=requestState.js.map

package/dist/types.d.ts

@@ -301,10 +301,12 @@ export interface A11yQueryPattern {
  * Result from A11y query operation.
  */
 export interface A11yQueryResult {
-    /** Matching nodes */
+    /** Matching nodes (the first `--limit` of them) */
     nodes: A11yNode[];
     /** Total matches found */
     count: number;
+    /** Matches not listed because of `--limit` (their indices still work) */
+    omitted?: number;
     /** Query pattern used */
     pattern: A11yQueryPattern;
 }
@@ -316,6 +318,12 @@ export interface DomContext {
     tag: string;
     classes?: string[];
     preview?: string;
+    /** Up to 500 characters of text, when it is longer than the preview */
+    text?: string;
+    /** First child elements (`tag#id.class`), for an element without text */
+    children?: string[];
+    /** Number of child elements, for an element without text */
+    childCount?: number;
 }
 /**
  * Reference to a DOM node for CDP calls: a per-connection `nodeId` (valid only
@@ -326,6 +334,47 @@ export type NodeRef = {
 } | {
     backendNodeId: number;
 };
+/** `prefers-color-scheme` value a session emulates (`--color-scheme`) */
+export type ColorScheme = 'light' | 'dark';
+/** Viewport size in CSS px (`--viewport`) */
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+/**
+ * The page (document) request an action sent, as far as it got: still
+ * pending, answered with a status, or failed.
+ */
+export interface DocumentRequestState {
+    method: string;
+    url: string;
+    /** How long it has been running (pending requests) */
+    pendingMs?: number;
+    /** HTTP status of the response, once answered */
+    status?: number;
+    statusText?: string;
+    /** Network error, when it failed */
+    errorText?: string;
+}
+/**
+ * The list a numeric index refers to: the results of the last
+ * `bdg dom query`, `bdg dom form` or `bdg dom a11y query` (one cache holds
+ * the last of them).
+ */
+export interface IndexSource {
+    /** The index the user gave (0-based) */
+    index: number;
+    /** Command whose results are cached */
+    command: 'dom query' | 'dom form' | 'dom a11y query';
+    /** The query's selector or a11y pattern (not for `dom form`) */
+    query?: string;
+}
+/**
+ * Where an element is relative to the top-level viewport: fully `visible`,
+ * `partly` visible, outside it in one direction, or `hidden` (not rendered,
+ * `visibility: hidden`, zero size, inert, or clipped away).
+ */
+export type ViewportPosition = 'visible' | 'partly' | 'above' | 'below' | 'left' | 'right' | 'hidden';
 /**
  * Result of a DOM query operation.
  */
@@ -341,11 +390,17 @@ export interface DomQueryResult {
         id?: string;
         name?: string;
         type?: string;
+        /** `value` attribute of an `<option>` */
+        value?: string;
         classes?: string[];
         /** Text content preview (display only, never used for targeting) */
         preview?: string;
         /** Enclosing iframe(s) and shadow root, e.g. "iframe#pay > shadow root of <x-card>" */
         context?: string;
+        /** Where the element is relative to the viewport when queried (first 100 matches) */
+        inViewport?: ViewportPosition;
+        /** Ancestor or iframe cutting it off, e.g. a scrolled list */
+        clippedBy?: string;
         /** Unique selector for this node (set by form discovery) */
         selector?: string;
     }>;
@@ -389,7 +444,13 @@ export interface ScreenshotResult {
     element?: {
         selector?: string;
         index?: number;
+        /** Border box of the element (page coordinates for element captures) */
         bounds: ElementBounds;
+        /**
+         * Area captured, when content overflowing the element (floats, positioned
+         * descendants) made it larger than the border box
+         */
+        captured?: ElementBounds;
     };
     /** Capture mode used */
     captureMode?: 'full_page' | 'viewport';
@@ -473,6 +534,8 @@ export interface FormField {
     name: string | null;
     placeholder?: string | undefined;
     required: boolean;
+    /** Name of the radio/checkbox group the field belongs to (counted once in the summary) */
+    groupLabel?: string | undefined;
     disabled: boolean;
     readOnly: boolean;
     hidden: boolean;
@@ -509,7 +572,9 @@ export interface FormBlocker {
     command: string;
 }
 /**
- * Summary statistics for a form.
+ * Summary statistics for a form. Counts cover the visible, editable fields;
+ * a radio or checkbox group (same name) counts once, filled when any of its
+ * options is checked.
  */
 export interface FormSummary {
     totalFields: number;
@@ -520,6 +585,12 @@ export interface FormSummary {
     requiredTotal: number;
     requiredFilled: number;
     requiredRemaining: number;
+    /** Labels of the fields (choice groups once) left empty, required or not */
+    emptyFieldLabels: string[];
+    /**
+     * Every required field is filled, nothing is invalid, the submit button is
+     * enabled, and at least one field is filled (or the form has none)
+     */
     readyToSubmit: boolean;
     blockers: FormBlocker[];
 }
@@ -540,6 +611,10 @@ export interface DiscoveredForm {
     method: string;
     step?: FormStep | undefined;
     relevanceScore: number;
+    /** Not visible (not rendered, visibility-hidden, or all its fields are) */
+    hidden: boolean;
+    /** Shown inside an open dialog: listed first, like visible forms before hidden ones */
+    inDialog: boolean;
     fields: FormField[];
     buttons: FormButton[];
     summary: FormSummary;
@@ -551,11 +626,13 @@ export interface FormDiscoveryResult {
     formCount: number;
     selectedForm: number;
     forms: DiscoveredForm[];
-    /** The forms not shown (without `--all`): name and number of visible fields */
+    /** The forms not shown (without `--all`): name and number of visible fields (all fields of a hidden form) */
     otherForms?: Array<{
         index: number;
         name: string | null;
         fieldCount: number;
+        hidden: boolean;
+        inDialog: boolean;
     }>;
     brief?: boolean | undefined;
 }

package/dist/ui/formatters/a11y.js

@@ -1,4 +1,5 @@
 import { OutputFormatter, areHintsHidden } from '../formatting.js';
+import { a11yMoreMatchesNote } from '../messages/commands.js';
 /**
  * Maximum number of nodes to display in tree output before truncating.
  * Prevents overwhelming terminal output for large accessibility trees.
@@ -111,6 +112,8 @@ export function formatA11yQueryResult(result) {
         const index = node.index !== undefined ? `[${node.index}] ` : '';
         fmt.text(index + formatA11yNodeOneLine(node)).blank();
     }
+    if (result.omitted)
+        fmt.text(a11yMoreMatchesNote(result.omitted)).blank();
     const first = result.nodes[0];
     if (first?.index !== undefined && !areHintsHidden()) {
         const fillable = FILLABLE_ROLES.has(first.role.toLowerCase());

package/dist/ui/formatters/console/chronological.d.ts

@@ -11,4 +11,12 @@ import { type ConsoleFormatOptions } from './shared.js';
  * navigation markers when page reloads are detected.
  */
 export declare function formatConsoleChronological(messages: ConsoleMessage[], options: ConsoleFormatOptions): string;
+/**
+ * The messages `--last` selects: the last N (all for 0 or none).
+ *
+ * @param messages - Messages after the page and level filters
+ * @param last - `--last` value
+ * @returns The messages to list
+ */
+export declare function lastMessages(messages: ConsoleMessage[], last: number | undefined): ConsoleMessage[];
 //# sourceMappingURL=chronological.d.ts.map

package/dist/ui/formatters/console/chronological.js

@@ -3,6 +3,7 @@
  * level prefixes, and navigation reload markers.
  */
 import { OutputFormatter } from '../../formatting.js';
+import { consoleIndexGapNote } from '../../messages/consoleMessages.js';
 import { truncateByLength } from '../../../utils/strings.js';
 import { formatSourceLocation, formatTimestamp } from './shared.js';
 const MAX_LIST_TEXT_LENGTH = 200;
@@ -14,10 +15,7 @@ const MAX_LIST_TEXT_LENGTH = 200;
  */
 export function formatConsoleChronological(messages, options) {
     const fmt = new OutputFormatter();
-    let displayMessages = messages;
-    if (options.last && options.last > 0) {
-        displayMessages = messages.slice(-options.last);
-    }
+    const displayMessages = lastMessages(messages, options.last);
     const headerSuffix = options.history ? ' (all navigations)' : '';
     const header = displayMessages.length === messages.length
         ? `Console Messages (${messages.length} total)${headerSuffix}`
@@ -53,6 +51,21 @@ export function formatConsoleChronological(messages, options) {
             fmt.text(`${sourceIndent}→ ${source}`);
         }
     }
+    const { skipped } = options;
+    if (skipped && skipped.otherPages + skipped.otherLevels > 0) {
+        fmt.blank();
+        fmt.text(consoleIndexGapNote(skipped));
+    }
     return fmt.build();
 }
+/**
+ * The messages `--last` selects: the last N (all for 0 or none).
+ *
+ * @param messages - Messages after the page and level filters
+ * @param last - `--last` value
+ * @returns The messages to list
+ */
+export function lastMessages(messages, last) {
+    return last && last > 0 ? messages.slice(-last) : messages;
+}
 //# sourceMappingURL=chronological.js.map

package/dist/ui/formatters/console/json.js

@@ -3,6 +3,7 @@
  * deduplicated errors/warnings; full message list is included only when
  * --list is set.
  */
+import { lastMessages } from './chronological.js';
 import { analyzeMessages, } from './shared.js';
 function toJsonError(dedup, includeStackTrace) {
     const source = dedup.message.stackTrace?.[0];
@@ -37,10 +38,8 @@ export function buildConsoleJsonOutput(messages, options) {
         errors: grouped.errors.map((d) => toJsonError(d, true)),
         warnings: grouped.warnings.map((d) => toJsonError(d, false)),
     };
-    if (options.list) {
-        const displayMessages = options.last && options.last > 0 ? messages.slice(-options.last) : messages;
-        output.messages = displayMessages;
-    }
+    if (options.list)
+        output.messages = lastMessages(messages, options.last);
     return output;
 }
 /**

package/dist/ui/formatters/console/shared.d.ts

@@ -55,6 +55,18 @@ export interface ConsoleFormatOptions {
     history?: boolean | undefined;
     /** Filter by level (error, warning, info, debug) */
     level?: ConsoleLevel | undefined;
+    /** Messages between the first and last listed index that the filters left out */
+    skipped?: ConsoleSkipped | undefined;
+}
+/**
+ * Messages the page and level filters left out between the first and last
+ * listed index (session indices then skip numbers).
+ */
+export interface ConsoleSkipped {
+    /** Logged by another page load (`--history` lists them) */
+    otherPages: number;
+    /** Of another level (`--level`) */
+    otherLevels: number;
 }
 /**
  * JSON error/warning entry structure.

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

@@ -7,9 +7,9 @@
  */
 import type { ConsoleMessage } from '../../types.js';
 import { type ConsoleFormatOptions } from './console/shared.js';
-export type { ConsoleFormatOptions, ConsoleJsonOutput, ConsoleLevel, ConsoleSummary, DeduplicatedMessage, } from './console/shared.js';
+export type { ConsoleFormatOptions, ConsoleJsonOutput, ConsoleLevel, ConsoleSkipped, ConsoleSummary, DeduplicatedMessage, } from './console/shared.js';
 export { LEVEL_MAP } from './console/shared.js';
-export { formatConsoleChronological } from './console/chronological.js';
+export { formatConsoleChronological, lastMessages } from './console/chronological.js';
 export { formatConsoleFollowLines } from './console/follow.js';
 export { buildConsoleJsonOutput, formatConsoleJson } from './console/json.js';
 export { formatConsoleSummary } from './console/summarize.js';

package/dist/ui/formatters/console.js

@@ -9,7 +9,7 @@ import { formatConsoleChronological } from './console/chronological.js';
 import { formatConsoleJson } from './console/json.js';
 import { formatConsoleSummary } from './console/summarize.js';
 export { LEVEL_MAP } from './console/shared.js';
-export { formatConsoleChronological } from './console/chronological.js';
+export { formatConsoleChronological, lastMessages } from './console/chronological.js';
 export { formatConsoleFollowLines } from './console/follow.js';
 export { buildConsoleJsonOutput, formatConsoleJson } from './console/json.js';
 export { formatConsoleSummary } from './console/summarize.js';

package/dist/ui/formatters/details.js

@@ -2,6 +2,7 @@ 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;
@@ -155,7 +156,7 @@ function describeResponseBody(request) {
     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: bdg details network ${request.requestId} --json)`;
+    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.

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

@@ -3,10 +3,11 @@ import type { DomQueryResult, DomGetResult, ScreenshotResult } from '../../types
 /**
  * Format DOM query results for human-readable output.
  *
- * Displays found nodes with their index, tag, classes, and preview text,
- * up to {@link QUERY_DISPLAY_LIMIT} of them (no match is an error, exit 83).
- * The text extraction hint is left out for selectors with text or visibility
- * filters, which `document.querySelectorAll` does not understand.
+ * 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
@@ -61,18 +62,23 @@ export declare function formatDomGet(data: DomGetResult): string;
 /**
  * Format DOM eval results for human-readable output.
  *
- * Outputs the evaluated JavaScript result as formatted JSON, preceded by a
- * `Frame: <url>` line when it ran in an iframe (`--frame`).
+ * 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 (and its frame)
- * @returns Formatted JSON string
+ * @param data - DOM eval result containing the evaluated value
+ * @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",
@@ -83,22 +89,25 @@ export declare function formatDomGet(data: DomGetResult): string;
 export declare function formatDomEval(data: {
     result: unknown;
     type?: string;
-    frame?: string;
 }): string;
 /**
- * Format the page's iframes, one per line.
+ * 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`
+ * @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.
@@ -115,6 +124,9 @@ export declare function formatDomFrames(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;