browser-debugger-cli 0.7.2 → 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

@@ -41,35 +41,6 @@ export interface BdgResponse<T = unknown> {
     /** Actionable suggestion for error recovery */
     suggestion?: string;
 }
-/**
- * Type guard to validate BdgResponse structure.
- *
- * Use this to verify responses from commands or IPC.
- *
- * @param value - Unknown value to check
- * @returns True if value is a valid BdgResponse
- */
-export declare function isBdgResponse(value: unknown): value is BdgResponse;
-/**
- * Type guard for successful BdgResponse.
- *
- * @param value - Unknown value to check
- * @returns True if value is a successful BdgResponse with data
- */
-export declare function isSuccessResponse<T>(value: unknown): value is BdgResponse<T> & {
-    success: true;
-    data: T;
-};
-/**
- * Type guard for error BdgResponse.
- *
- * @param value - Unknown value to check
- * @returns True if value is an error BdgResponse
- */
-export declare function isErrorResponse(value: unknown): value is BdgResponse & {
-    success: false;
-    error: string;
-};
 /**
  * Re-export connection types for backward compatibility.
  *
@@ -77,16 +48,6 @@ export declare function isErrorResponse(value: unknown): value is BdgResponse &
  * This re-export maintains backward compatibility with existing code.
  */
 export type { CDPMessage, CDPTarget, ConnectionOptions, LaunchedChrome, Logger, CleanupFunction, } from './connection/types.js';
-export interface DOMData {
-    url: string;
-    title: string;
-    outerHTML: string;
-    a11yTree?: {
-        root: A11yNode;
-        nodes: Record<string, A11yNode>;
-        count: number;
-    };
-}
 /**
  * WebSocket frame data captured during connection.
  */
@@ -97,8 +58,10 @@ export interface WebSocketFrame {
     direction: 'sent' | 'received';
     /** WebSocket opcode (1 = text, 2 = binary) */
     opcode: number;
-    /** Frame payload data */
+    /** Frame payload data (base64 for binary frames) */
     payloadData: string;
+    /** Original payload length in characters, when `payloadData` was truncated */
+    truncatedFrom?: number;
 }
 /**
  * WebSocket connection with lifecycle and frame data.
@@ -112,8 +75,12 @@ export interface WebSocketConnection {
     timestamp: number;
     /** Initiator URL (page that opened the WebSocket) */
     initiatorUrl?: string;
+    /** Request headers of the handshake */
+    requestHeaders?: Record<string, string>;
     /** Response status from handshake */
     status?: number;
+    /** Response status text from handshake */
+    statusText?: string;
     /** Response headers from handshake */
     responseHeaders?: Record<string, string>;
     /** Captured frames (sent and received) */
@@ -162,10 +129,29 @@ export interface NetworkRequest {
         receiveHeadersEnd?: number;
     };
     loadingFinishedTime?: number;
+    /** Chrome's monotonic time (seconds) when the request was sent; durations are measured from it */
+    sentTime?: number;
+    /** Milliseconds from the request start to its last byte or failure (a redirect hop: to the redirect) */
+    duration?: number;
+    /** For a redirect hop: the URL it redirected to */
+    redirectURL?: string;
     encodedDataLength?: number;
     decodedBodyLength?: number;
     serverIPAddress?: string;
     connection?: string;
+    /** Status text sent by the server (empty for HTTP/2) */
+    statusText?: string;
+    /** `responseBody` is base64 (binary content) */
+    responseBodyBase64?: boolean;
+    /** Served from the browser's memory, disk or prefetch cache */
+    fromCache?: boolean;
+    /** Why the response body was not captured (`details`; `responseBody` is then absent) */
+    bodyNotCaptured?: string;
+    /** Messages and lifecycle of a WebSocket connection (`resourceType` is `WebSocket`) */
+    webSocket?: {
+        frames: WebSocketFrame[];
+        closedTime?: number;
+    };
     /**
      * Network error text from loadingFailed events.
      * Contains specific error codes like net::ERR_CERT_DATE_INVALID, net::ERR_CONNECTION_REFUSED.
@@ -201,6 +187,8 @@ export interface StackFrame {
     scriptId?: string;
 }
 export interface ConsoleMessage {
+    /** Position in the session's message list (set in previews; `details console <n>` takes it) */
+    index?: number;
     type: Protocol.Runtime.ConsoleAPICalledEvent['type'];
     text: string;
     timestamp: number;
@@ -211,6 +199,8 @@ export interface ConsoleMessage {
      * First frame indicates the source location of the console call.
      */
     stackTrace?: StackFrame[];
+    /** Browser subsystem of a browser message (`network`, `security`, ...); absent for page console calls */
+    source?: Protocol.Log.LogEntry['source'];
 }
 /**
  * Console message level categories for user-facing filtering.
@@ -227,11 +217,17 @@ export interface BdgOutput {
         title: string;
     };
     data: {
-        dom?: DOMData;
         network?: NetworkRequest[];
         console?: ConsoleMessage[];
         websockets?: WebSocketConnection[];
     };
+    /** Navigation id of the page currently loaded (live previews) */
+    currentNavigationId?: number;
+    /** Counts of all captured items matching the request (e.g. `peek --type`), when `data` holds only the most recent ones */
+    totals?: {
+        network: number;
+        console: number;
+    };
     error?: string;
     partial?: boolean;
 }
@@ -243,6 +239,8 @@ export type TelemetryType = 'dom' | 'network' | 'console';
  * optimized for agent consumption and semantic queries.
  */
 export interface A11yNode {
+    /** Position in the last `a11y query` result (usable as a DOM index, e.g. `bdg dom click 0`) */
+    index?: number;
     /** Unique node identifier from CDP */
     nodeId: string;
     /** ARIA role (button, textbox, heading, etc.) */
@@ -303,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;
 }
@@ -318,7 +318,63 @@ 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
+ * within one command) or a `backendNodeId` (valid while the node exists).
+ */
+export type NodeRef = {
+    nodeId: number;
+} | {
+    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.
  */
@@ -327,13 +383,27 @@ export interface DomQueryResult {
     count: number;
     nodes: Array<{
         index: number;
+        /** Backend node id (stable while the element exists; 0 if unknown) */
         nodeId: number;
         tag?: string;
+        /** `id`, `name` and `type` attributes, when present */
+        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;
     }>;
-    /** Navigation ID when query was performed (for staleness detection). */
-    navigationId?: number;
 }
 /**
  * Result of a DOM get operation.
@@ -374,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';
@@ -458,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;
@@ -470,7 +548,6 @@ export interface FormField {
     options?: FieldOption[] | undefined;
     command: string;
     selectorCommand: string;
-    alternativeCommand?: string | undefined;
 }
 /**
  * Form button discovered on the page.
@@ -495,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;
@@ -506,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[];
 }
@@ -526,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;
@@ -537,6 +626,14 @@ export interface FormDiscoveryResult {
     formCount: number;
     selectedForm: number;
     forms: DiscoveredForm[];
+    /** 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;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,34 +1,2 @@
-/**
- * Type guard to validate BdgResponse structure.
- *
- * Use this to verify responses from commands or IPC.
- *
- * @param value - Unknown value to check
- * @returns True if value is a valid BdgResponse
- */
-export function isBdgResponse(value) {
-    if (typeof value !== 'object' || value === null) {
-        return false;
-    }
-    const obj = value;
-    return typeof obj['version'] === 'string' && typeof obj['success'] === 'boolean';
-}
-/**
- * Type guard for successful BdgResponse.
- *
- * @param value - Unknown value to check
- * @returns True if value is a successful BdgResponse with data
- */
-export function isSuccessResponse(value) {
-    return isBdgResponse(value) && value.success === true && value.data !== undefined;
-}
-/**
- * Type guard for error BdgResponse.
- *
- * @param value - Unknown value to check
- * @returns True if value is an error BdgResponse
- */
-export function isErrorResponse(value) {
-    return isBdgResponse(value) && value.success === false && typeof value.error === 'string';
-}
+export {};
 //# sourceMappingURL=types.js.map

package/dist/ui/OutputBuilder.d.ts

@@ -1,26 +1,29 @@
 /**
  * Structured output building for CLI commands.
  */
-import type { BdgOutput, BdgResponse, CDPTarget, NetworkRequest, ConsoleMessage, DOMData, TelemetryType } from '../types';
-export type OutputMode = 'preview' | 'full' | 'final';
-export interface OutputBuilderOptions {
-    mode: OutputMode;
-    target: CDPTarget;
-    startTime: number;
-    networkRequests: NetworkRequest[];
-    consoleLogs: ConsoleMessage[];
-    domData?: DOMData;
-    activeTelemetry: TelemetryType[];
-}
+import type { BdgResponse } from '../types.js';
+/**
+ * Build a success response envelope.
+ *
+ * @param data - Response payload
+ * @returns `{ version, success: true, data }`
+ */
 export declare function buildSuccessResponse<T>(data: T): BdgResponse<T>;
+/** Builders for JSON error envelopes. */
 export declare class OutputBuilder {
-    static build(options: OutputBuilderOptions): BdgOutput;
-    static buildError(error: unknown, startTime: number, target?: CDPTarget): BdgOutput;
+    /**
+     * Build an error response envelope.
+     *
+     * Envelope fields in `options` cannot override `version`, `success` or `error`.
+     *
+     * @param error - Error or message
+     * @param options - Exit code, suggestion and extra context fields
+     * @returns `{ version, success: false, error, ...options }`
+     */
     static buildJsonError(error: string | Error, options?: {
         exitCode?: number;
         suggestion?: string;
         context?: Record<string, string>;
     }): Record<string, unknown>;
-    static buildJsonSuccess(data: Record<string, unknown>): Record<string, unknown>;
 }
 //# sourceMappingURL=OutputBuilder.d.ts.map

package/dist/ui/OutputBuilder.js

@@ -1,104 +1,35 @@
 /**
  * Structured output building for CLI commands.
  */
-import { getErrorMessage } from '../utils/errors.js';
 import { VERSION } from '../utils/version.js';
+/**
+ * Build a success response envelope.
+ *
+ * @param data - Response payload
+ * @returns `{ version, success: true, data }`
+ */
 export function buildSuccessResponse(data) {
     return { version: VERSION, success: true, data };
 }
-function buildBaseOutput(target, startTime, partial) {
-    return {
-        version: VERSION,
-        success: true,
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - startTime,
-        target: { url: target.url, title: target.title },
-        partial,
-    };
-}
-function buildPreviewData(networkRequests, consoleLogs, activeTelemetry) {
-    const data = {};
-    if (activeTelemetry.includes('network')) {
-        data['network'] = networkRequests.slice(-1000).map((req) => ({
-            requestId: req.requestId,
-            url: req.url,
-            method: req.method,
-            timestamp: req.timestamp,
-            status: req.status,
-            mimeType: req.mimeType,
-        }));
-    }
-    if (activeTelemetry.includes('console')) {
-        data['console'] = consoleLogs.slice(-1000).map((msg) => ({
-            type: msg.type,
-            text: msg.text,
-            timestamp: msg.timestamp,
-        }));
-    }
-    return data;
-}
-function buildFullData(networkRequests, consoleLogs, activeTelemetry) {
-    const data = {};
-    if (activeTelemetry.includes('network'))
-        data['network'] = networkRequests;
-    if (activeTelemetry.includes('console'))
-        data['console'] = consoleLogs;
-    return data;
-}
-function buildFinalData(networkRequests, consoleLogs, domData, activeTelemetry) {
-    const data = {};
-    if (activeTelemetry.includes('network'))
-        data['network'] = networkRequests;
-    if (activeTelemetry.includes('console'))
-        data['console'] = consoleLogs;
-    if (activeTelemetry.includes('dom') && domData)
-        data['dom'] = domData;
-    return data;
-}
+/** Builders for JSON error envelopes. */
 export class OutputBuilder {
-    static build(options) {
-        const { mode, target, startTime, networkRequests, consoleLogs, domData, activeTelemetry } = options;
-        const baseOutput = buildBaseOutput(target, startTime, mode !== 'final');
-        switch (mode) {
-            case 'preview':
-                return {
-                    ...baseOutput,
-                    data: buildPreviewData(networkRequests, consoleLogs, activeTelemetry),
-                };
-            case 'full':
-                return {
-                    ...baseOutput,
-                    data: buildFullData(networkRequests, consoleLogs, activeTelemetry),
-                };
-            case 'final':
-                return {
-                    ...baseOutput,
-                    partial: false,
-                    data: buildFinalData(networkRequests, consoleLogs, domData, activeTelemetry),
-                };
-        }
-    }
-    static buildError(error, startTime, target) {
-        return {
-            version: VERSION,
-            success: false,
-            timestamp: new Date().toISOString(),
-            duration: Date.now() - startTime,
-            target: target ? { url: target.url, title: target.title } : { url: '', title: '' },
-            data: {},
-            error: getErrorMessage(error),
-        };
-    }
+    /**
+     * Build an error response envelope.
+     *
+     * Envelope fields in `options` cannot override `version`, `success` or `error`.
+     *
+     * @param error - Error or message
+     * @param options - Exit code, suggestion and extra context fields
+     * @returns `{ version, success: false, error, ...options }`
+     */
     static buildJsonError(error, options) {
+        const { version: _version, success: _success, error: _error, ...rest } = (options ?? {});
         return {
             version: VERSION,
             success: false,
             error: error instanceof Error ? error.message : error,
-            ...options,
+            ...rest,
         };
     }
-    static buildJsonSuccess(data) {
-        return { version: VERSION, success: true, ...data };
-    }
 }
 //# sourceMappingURL=OutputBuilder.js.map