browser-debugger-cli 0.12.0 → 0.14.0

package/dist/telemetry/networkRetention.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What the network collector keeps of a long session: the newest finished
+ * requests up to a cap, and the newest response bodies up to a total size.
+ */
+import type { NetworkRequest } from '../types.js';
+/** Counts of what the session let go at its limits */
+export interface NetworkEvictions {
+    /** Finished requests dropped at the request cap, oldest first */
+    requestsDropped: number;
+    /** Response bodies replaced by a placeholder at the total body budget, oldest first */
+    bodiesEvicted: number;
+}
+/** Limits of {@link RequestRetention} */
+export interface RetentionLimits {
+    /** Finished requests kept at most */
+    maxRequests: number;
+    /** Total size of the stored response bodies (bytes) */
+    maxTotalBodyBytes: number;
+}
+/**
+ * Keeps finished requests, oldest first, dropping the oldest past the cap
+ * (requests in flight are never in the list, so never dropped), and tracks
+ * the size of their stored bodies, replacing the oldest bodies past the
+ * budget with a placeholder that says why.
+ *
+ * Stored bodies are kept in a Map, which iterates in insertion order: its
+ * first entry is the oldest body, and a dropped request's body is removed in
+ * O(1). Dropping from the front of the list is `Array.shift`, which V8 does
+ * without copying for arrays of this size.
+ */
+export declare class RequestRetention {
+    private readonly requests;
+    private readonly limits;
+    private readonly evictions;
+    private readonly bodySizes;
+    private storedBodyBytes;
+    /**
+     * @param requests - Finished requests, oldest first (updated in place)
+     * @param limits - Request cap and body budget
+     * @param evictions - Counters updated on each drop and eviction
+     */
+    constructor(requests: NetworkRequest[], limits: RetentionLimits, evictions: NetworkEvictions);
+    /**
+     * Add a finished request, dropping the oldest one past the cap.
+     *
+     * @param request - Finished request
+     * @returns The dropped request, if one was
+     */
+    add(request: NetworkRequest): NetworkRequest | undefined;
+    /**
+     * Store a fetched response body on a kept request, then evict the oldest
+     * bodies until the total fits the budget (a body larger than the whole
+     * budget is evicted itself). Storing a body again replaces the earlier one.
+     *
+     * @param request - Request the body belongs to
+     * @param body - Body as Chrome returned it
+     * @param base64Encoded - Whether `body` is base64
+     */
+    storeBody(request: NetworkRequest, body: string, base64Encoded: boolean): void;
+    /** Evict the oldest stored bodies while their total is over the budget. */
+    private enforceBodyBudget;
+    /**
+     * Stop counting a request's stored body.
+     *
+     * @param request - Request whose body is let go
+     */
+    private forgetBody;
+}
+/**
+ * Placeholder stored instead of a response body that was not fetched.
+ *
+ * @param reason - Why the body was skipped
+ * @returns Placeholder text shown by `bdg details`
+ */
+export declare function skippedBodyPlaceholder(reason: string): string;
+/**
+ * Extract the reason from a skipped-body placeholder.
+ *
+ * @param body - Stored response body
+ * @returns Reason if `body` is a placeholder, otherwise undefined
+ */
+export declare function skippedBodyReason(body: string | undefined): string | undefined;
+//# sourceMappingURL=networkRetention.d.ts.map

package/dist/telemetry/networkRetention.js

@@ -0,0 +1,117 @@
+/**
+ * What the network collector keeps of a long session: the newest finished
+ * requests up to a cap, and the newest response bodies up to a total size.
+ */
+import { bodyEvictedReason } from '../ui/messages/networkMessages.js';
+/**
+ * Keeps finished requests, oldest first, dropping the oldest past the cap
+ * (requests in flight are never in the list, so never dropped), and tracks
+ * the size of their stored bodies, replacing the oldest bodies past the
+ * budget with a placeholder that says why.
+ *
+ * Stored bodies are kept in a Map, which iterates in insertion order: its
+ * first entry is the oldest body, and a dropped request's body is removed in
+ * O(1). Dropping from the front of the list is `Array.shift`, which V8 does
+ * without copying for arrays of this size.
+ */
+export class RequestRetention {
+    requests;
+    limits;
+    evictions;
+    bodySizes = new Map();
+    storedBodyBytes = 0;
+    /**
+     * @param requests - Finished requests, oldest first (updated in place)
+     * @param limits - Request cap and body budget
+     * @param evictions - Counters updated on each drop and eviction
+     */
+    constructor(requests, limits, evictions) {
+        this.requests = requests;
+        this.limits = limits;
+        this.evictions = evictions;
+    }
+    /**
+     * Add a finished request, dropping the oldest one past the cap.
+     *
+     * @param request - Finished request
+     * @returns The dropped request, if one was
+     */
+    add(request) {
+        this.requests.push(request);
+        if (this.requests.length <= this.limits.maxRequests)
+            return undefined;
+        const dropped = this.requests.shift();
+        if (!dropped)
+            return undefined;
+        this.evictions.requestsDropped++;
+        this.forgetBody(dropped);
+        return dropped;
+    }
+    /**
+     * Store a fetched response body on a kept request, then evict the oldest
+     * bodies until the total fits the budget (a body larger than the whole
+     * budget is evicted itself). Storing a body again replaces the earlier one.
+     *
+     * @param request - Request the body belongs to
+     * @param body - Body as Chrome returned it
+     * @param base64Encoded - Whether `body` is base64
+     */
+    storeBody(request, body, base64Encoded) {
+        this.forgetBody(request);
+        request.responseBody = body;
+        if (base64Encoded)
+            request.responseBodyBase64 = true;
+        if (body) {
+            request.decodedBodyLength = Buffer.byteLength(body, base64Encoded ? 'base64' : 'utf-8');
+        }
+        const size = Buffer.byteLength(body);
+        this.bodySizes.set(request, size);
+        this.storedBodyBytes += size;
+        this.enforceBodyBudget();
+    }
+    /** Evict the oldest stored bodies while their total is over the budget. */
+    enforceBodyBudget() {
+        while (this.storedBodyBytes > this.limits.maxTotalBodyBytes) {
+            const oldest = this.bodySizes.keys().next();
+            if (oldest.done)
+                return;
+            const request = oldest.value;
+            this.forgetBody(request);
+            request.responseBody = skippedBodyPlaceholder(bodyEvictedReason(this.limits.maxTotalBodyBytes));
+            delete request.responseBodyBase64;
+            this.evictions.bodiesEvicted++;
+        }
+    }
+    /**
+     * Stop counting a request's stored body.
+     *
+     * @param request - Request whose body is let go
+     */
+    forgetBody(request) {
+        const size = this.bodySizes.get(request);
+        if (size === undefined)
+            return;
+        this.bodySizes.delete(request);
+        this.storedBodyBytes -= size;
+    }
+}
+const SKIPPED_BODY_PATTERN = /^\[SKIPPED: (.*)\]$/s;
+/**
+ * Placeholder stored instead of a response body that was not fetched.
+ *
+ * @param reason - Why the body was skipped
+ * @returns Placeholder text shown by `bdg details`
+ */
+export function skippedBodyPlaceholder(reason) {
+    return `[SKIPPED: ${reason}]`;
+}
+/**
+ * Extract the reason from a skipped-body placeholder.
+ *
+ * @param body - Stored response body
+ * @returns Reason if `body` is a placeholder, otherwise undefined
+ */
+export function skippedBodyReason(body) {
+    return body === undefined ? undefined : SKIPPED_BODY_PATTERN.exec(body)?.[1];
+}
+//# sourceMappingURL=networkRetention.js.map

package/dist/telemetry/pageCrash.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Renderer crash tracking: Chrome reports a crashed page with
+ * `Inspector.targetCrashed` and keeps the connection open, so without this a
+ * session looks active while every page command waits for a timeout. A
+ * reload (or any main-frame navigation) brings the page back.
+ */
+import type { CDPConnection } from '../connection/cdp.js';
+import { CommandError } from '../errors/index.js';
+import type { CleanupFunction } from '../types.js';
+/**
+ * Start tracking renderer crashes of the page.
+ *
+ * @param cdp - CDP connection to the page
+ * @param onChange - Called with the crash time when the page crashes, and
+ *   with undefined when it is loaded again
+ * @returns Cleanup that stops tracking
+ */
+export declare function startCrashTracking(cdp: CDPConnection, onChange: (crashedAt: number | undefined) => void): Promise<CleanupFunction>;
+/**
+ * Error for a page command after the page's renderer crashed (exit 107).
+ *
+ * @param crashedAt - When it crashed (epoch ms)
+ * @returns Error with the way back
+ */
+export declare function pageCrashedCommandError(crashedAt: number): CommandError;
+//# sourceMappingURL=pageCrash.d.ts.map

package/dist/telemetry/pageCrash.js

@@ -0,0 +1,53 @@
+/**
+ * Renderer crash tracking: Chrome reports a crashed page with
+ * `Inspector.targetCrashed` and keeps the connection open, so without this a
+ * session looks active while every page command waits for a timeout. A
+ * reload (or any main-frame navigation) brings the page back.
+ */
+import { CDPHandlerRegistry } from '../connection/handlers.js';
+import { TypedCDPConnection } from '../connection/typed-cdp.js';
+import { CommandError } from '../errors/index.js';
+import { pageCrashedError } from '../errors/messages.js';
+import { createLogger } from '../ui/logging/index.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+const log = createLogger('page-crash');
+/**
+ * Start tracking renderer crashes of the page.
+ *
+ * @param cdp - CDP connection to the page
+ * @param onChange - Called with the crash time when the page crashes, and
+ *   with undefined when it is loaded again
+ * @returns Cleanup that stops tracking
+ */
+export async function startCrashTracking(cdp, onChange) {
+    const registry = new CDPHandlerRegistry();
+    const typed = new TypedCDPConnection(cdp);
+    registry.registerTyped(typed, 'Inspector.targetCrashed', () => {
+        log.info('The page crashed (renderer gone)');
+        onChange(Date.now());
+    });
+    registry.registerTyped(typed, 'Inspector.targetReloadedAfterCrash', () => onChange(undefined));
+    registry.registerTyped(typed, 'Page.frameNavigated', ({ frame }) => {
+        if (frame.parentId === undefined)
+            onChange(undefined);
+    });
+    try {
+        await cdp.send('Inspector.enable');
+    }
+    catch (error) {
+        log.debug(`Crash reports unavailable: ${getErrorMessage(error)}`);
+    }
+    return () => registry.cleanup();
+}
+/**
+ * Error for a page command after the page's renderer crashed (exit 107).
+ *
+ * @param crashedAt - When it crashed (epoch ms)
+ * @returns Error with the way back
+ */
+export function pageCrashedCommandError(crashedAt) {
+    const err = pageCrashedError(crashedAt);
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.PAGE_CRASHED);
+}
+//# sourceMappingURL=pageCrash.js.map

package/dist/types.d.ts

@@ -204,6 +204,8 @@ export interface ConsoleMessage {
     stackTrace?: StackFrame[];
     /** Browser subsystem of a browser message (`network`, `security`, ...); absent for page console calls */
     source?: Protocol.Log.LogEntry['source'];
+    /** Original length of `text` when JSON output cut it (`--full` keeps it whole) */
+    truncatedFrom?: number;
 }
 /**
  * Console message level categories for user-facing filtering.
@@ -226,10 +228,18 @@ export interface BdgOutput {
     };
     /** Navigation id of the page currently loaded (live previews) */
     currentNavigationId?: number;
+    /** When the page's renderer crashed (epoch ms), while it is not loaded again */
+    pageCrashedAt?: 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;
+        /** Console messages dropped at the limit, oldest first (indices start after them) */
+        consoleDropped?: number;
+        /** Finished network requests dropped at the request cap, oldest first */
+        networkDropped?: number;
+        /** Response bodies evicted at the total body budget, oldest first */
+        networkBodiesEvicted?: number;
     };
     error?: string;
     partial?: boolean;
@@ -282,6 +292,24 @@ export interface A11yTree {
     /** Total node count */
     count: number;
 }
+/** An accessibility node as `dom a11y tree` lists it */
+export type ListedA11yNode = Omit<A11yNode, 'childIds'> & {
+    /** Indentation level (0 = root; left-out wrappers add none) */
+    depth: number;
+};
+/**
+ * The part of an accessibility tree `dom a11y tree` lists (`--limit`, `--depth`).
+ */
+export interface ListedA11yTree {
+    /** Listed nodes, depth-first from the root */
+    nodes: ListedA11yNode[];
+    /** Nodes in the whole tree (listed + omitted + skipped) */
+    count: number;
+    /** Nodes left out by `--limit` or `--depth` */
+    omitted?: number;
+    /** Nodes never listed: text boxes, blank or repeated text, nameless layout wrappers */
+    skipped?: number;
+}
 /**
  * Query pattern for searching accessibility tree.
  *
@@ -327,6 +355,8 @@ export interface DomContext {
     children?: string[];
     /** Number of child elements, for an element without text */
     childCount?: number;
+    /** The children listed are those of its shadow root (a web component) */
+    shadowChildren?: boolean;
     /** Attributes that identify it by its type (see {@link KeyAttributes}) */
     attributes?: KeyAttributes;
     /** A field holding a secret (password, card, one-time code): its value is shown masked */
@@ -438,6 +468,14 @@ export interface DomQueryResult {
         /** Unique selector for this node (set by form discovery) */
         selector?: string;
     }>;
+    /** Matches not listed (`--limit`); `count` is all of them */
+    omitted?: number;
+    /** Matches usable by index (described and cached), when fewer than `count` */
+    indexed?: number;
+    /** First matches whose viewport position was checked (`inViewport`), when more are listed */
+    viewportChecked?: number;
+    /** Identity of the page document the matches belong to (cached results only) */
+    document?: string;
 }
 /**
  * Result of a DOM get operation.
@@ -449,6 +487,8 @@ export interface DomGetResult {
         attributes?: Record<string, unknown>;
         classes?: string[];
         outerHTML?: string;
+        /** Original length of `outerHTML` when JSON output cut it (`--full` keeps it whole) */
+        truncatedFrom?: number;
     }>;
 }
 /**
@@ -679,5 +719,7 @@ export interface InstalledSkill {
     target: SkillTarget;
     path: string;
     status: 'installed' | 'updated' | 'unchanged';
+    /** Where the replaced copy was kept (`updated` only) */
+    backup?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/ui/OutputBuilder.d.ts

@@ -9,6 +9,16 @@ import type { BdgResponse } from '../types.js';
  * @returns `{ version, success: true, data }`
  */
 export declare function buildSuccessResponse<T>(data: T): BdgResponse<T>;
+/**
+ * Serialize a `--json` response envelope for stdout.
+ *
+ * Indented by two spaces when stdout is a terminal, so a person can read it;
+ * on one line otherwise, since agents and pipes only pay for the whitespace.
+ *
+ * @param envelope - Response envelope (or other `--json` payload)
+ * @returns JSON text
+ */
+export declare function stringifyEnvelope(envelope: unknown): string;
 /** Builders for JSON error envelopes. */
 export declare class OutputBuilder {
     /**

package/dist/ui/OutputBuilder.js

@@ -11,6 +11,18 @@ import { VERSION } from '../utils/version.js';
 export function buildSuccessResponse(data) {
     return { version: VERSION, success: true, data };
 }
+/**
+ * Serialize a `--json` response envelope for stdout.
+ *
+ * Indented by two spaces when stdout is a terminal, so a person can read it;
+ * on one line otherwise, since agents and pipes only pay for the whitespace.
+ *
+ * @param envelope - Response envelope (or other `--json` payload)
+ * @returns JSON text
+ */
+export function stringifyEnvelope(envelope) {
+    return process.stdout.isTTY ? JSON.stringify(envelope, null, 2) : JSON.stringify(envelope);
+}
 /** Builders for JSON error envelopes. */
 export class OutputBuilder {
     /**

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

@@ -1,5 +1,5 @@
 import type { DomContext } from '../../types.js';
-import type { A11yTree, A11yQueryResult, A11yNode } from '../../types.js';
+import type { A11yQueryResult, A11yNode, ListedA11yTree } from '../../types.js';
 /**
  * Data structure for a11y node with DOM context.
  */
@@ -8,15 +8,13 @@ interface A11yNodeWithContext {
     domContext: DomContext | null;
 }
 /**
- * Format accessibility tree for human-readable output.
+ * Format the listed part of an accessibility tree for human-readable output:
+ * one indented line per node, and when nodes were cut, how to see more.
  *
- * Displays the tree structure with role, name, and key properties.
- * Shows up to 50 nodes by default for manageable output.
- *
- * @param tree - Accessibility tree data
+ * @param tree - Listed accessibility tree
  * @returns Formatted output string
  */
-export declare function formatA11yTree(tree: A11yTree): string;
+export declare function formatA11yTree(tree: ListedA11yTree): string;
 /**
  * Format query result for human-readable output.
  *

package/dist/ui/formatters/a11y.js

@@ -1,79 +1,25 @@
 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.
- */
-const MAX_TREE_NODES_DISPLAY = 50;
+import { a11yMoreMatchesNote, a11yTreeMoreNote, a11yTreeShownNote, } from '../messages/commands.js';
 /**
  * Separator width for section dividers in formatted output.
  */
 const SEPARATOR_WIDTH = 50;
 /**
- * Format accessibility tree for human-readable output.
- *
- * Displays the tree structure with role, name, and key properties.
- * Shows up to 50 nodes by default for manageable output.
+ * Format the listed part of an accessibility tree for human-readable output:
+ * one indented line per node, and when nodes were cut, how to see more.
  *
- * @param tree - Accessibility tree data
+ * @param tree - Listed accessibility tree
  * @returns Formatted output string
  */
 export function formatA11yTree(tree) {
     const fmt = new OutputFormatter();
     fmt.text(`Accessibility Tree (${tree.count} nodes)`).separator('─', SEPARATOR_WIDTH).blank();
-    const { lines, truncated } = treeLines(tree);
-    lines.forEach((line) => fmt.text(line));
-    if (truncated) {
-        fmt
-            .blank()
-            .text(`Showing the first ${MAX_TREE_NODES_DISPLAY} nodes (text boxes and repeated text left out)`)
-            .text('Use --json flag for complete output, or bdg dom a11y query "role:<role>" to search');
+    tree.nodes.forEach((node) => fmt.text('  '.repeat(node.depth) + formatA11yNodeOneLine(node)));
+    if (tree.omitted) {
+        fmt.blank().text(a11yTreeShownNote(tree.nodes.length)).text(a11yTreeMoreNote(tree.omitted));
     }
     return fmt.build();
 }
-/** Roles that only lay out their children and say nothing themselves */
-const LAYOUT_ROLES = new Set([
-    'generic',
-    'none',
-    'presentation',
-    'LayoutTable',
-    'LayoutTableRow',
-    'LayoutTableCell',
-]);
-/**
- * The tree as indented lines, depth-first from the root. Text boxes, blank
- * text, text that repeats its parent's name, and nameless layout wrappers are left out
- * (their children move up a level), so the budget goes to meaningful nodes.
- *
- * @param tree - Accessibility tree
- * @returns Up to {@link MAX_TREE_NODES_DISPLAY} lines, and whether nodes were left
- */
-function treeLines(tree) {
-    const lines = [];
-    const visited = new Set();
-    let truncated = false;
-    const visit = (node, depth, parentName) => {
-        if (visited.has(node.nodeId))
-            return;
-        visited.add(node.nodeId);
-        if (lines.length >= MAX_TREE_NODES_DISPLAY) {
-            truncated = true;
-            return;
-        }
-        const skip = node.role === 'InlineTextBox' ||
-            (node.role === 'StaticText' && (node.name === parentName || !node.name?.trim())) ||
-            (LAYOUT_ROLES.has(node.role) && !node.name);
-        if (!skip)
-            lines.push('  '.repeat(depth) + formatA11yNodeOneLine(node));
-        for (const childId of node.childIds ?? []) {
-            const child = tree.nodes.get(childId);
-            if (child)
-                visit(child, skip ? depth : depth + 1, node.name ?? parentName);
-        }
-    };
-    visit(tree.root, 0, undefined);
-    return { lines, truncated };
-}
 /** Roles whose elements take a value (the next step is fill, not click) */
 const FILLABLE_ROLES = new Set([
     'textbox',

package/dist/ui/formatters/audit.js

@@ -1,6 +1,7 @@
 /**
  * Human output of `bdg dom audit` and `bdg css search`.
  */
+import { auditCanvasNote, auditUncertainContrastNote } from '../messages/commands.js';
 import { truncateByLength } from '../../utils/strings.js';
 /** Width of the text quoted in a finding */
 const TEXT_WIDTH = 50;
@@ -15,7 +16,7 @@ export function formatAudit(data) {
         data.contrast && contrastSection(data.contrast),
         data.overflow && overflowSection(data.overflow),
         data.layers && layersSection(data.layers),
-        data.animations && animationsSection(data.animations),
+        data.animations && animationsSection(data.animations, data.canvases),
     ].filter((section) => section !== undefined);
     const capped = data.capped ? [`(stopped after ${data.walked} elements; the page has more)`] : [];
     return [...sections.flatMap((lines) => [...lines, '']), ...capped].join('\n').trimEnd();
@@ -28,9 +29,14 @@ export function formatAudit(data) {
  */
 function contrastSection(contrast) {
     const head = `Contrast (${contrast.level}): ${contrast.failing} of ${contrast.checked} text elements below`;
-    const rows = contrast.items.map((item) => `  ${item.ratio.toFixed(2).padStart(5)}  ${item.color} on ${item.background}  ${item.element} "${truncateByLength(item.text, TEXT_WIDTH)}" ${item.size}px${item.weight >= 700 ? ' bold' : ''}${item.inView ? '' : ' (out of view)'}${item.approximate ? ` (approximate: ${item.approximate.join(', ')})` : ''}`);
+    const rows = contrast.items.map((item) => `  ${item.ratio.toFixed(2).padStart(5)}  ${item.color} on ${item.background}  ${item.element} "${truncateByLength(item.text, TEXT_WIDTH)}" ${item.size}px${item.weight >= 700 ? ' bold' : ''}${item.opacity !== undefined ? ` (faded: opacity ${item.opacity})` : ''}${item.inView ? '' : ' (out of view)'}`);
     const more = contrast.failing - contrast.items.length;
-    return [head, ...rows, ...(more > 0 ? [`  (+${more} more; --limit to list them)`] : [])];
+    return [
+        head,
+        ...rows,
+        ...(more > 0 ? [`  (+${more} more; --limit to list them)`] : []),
+        ...(contrast.uncertain ? [`  ${auditUncertainContrastNote(contrast.uncertain)}`] : []),
+    ];
 }
 /**
  * The overflow section.
@@ -77,14 +83,17 @@ function layersSection(layers) {
  * The animations section.
  *
  * @param animations - Running animations
+ * @param canvases - Visible canvas elements
  * @returns Lines
  */
-function animationsSection(animations) {
+function animationsSection(animations, canvases) {
+    const note = canvases ? [`  ${auditCanvasNote(canvases)}`] : [];
     if (animations.length === 0)
-        return ['Animations: none running'];
+        return ['Animations: none running', ...note];
     return [
         `Animations: ${animations.length} running`,
         ...animations.map((animation) => `  ${animation.name} on ${animation.element}${times(animation.count)} (${animation.type}, ${typeof animation.duration === 'number' ? `${animation.duration}ms` : animation.duration}, ${animation.iterations === 'infinite' ? 'infinite' : `${animation.iterations}x`}${animation.scrollDriven ? ', scroll-driven' : ''})`),
+        ...note,
     ];
 }
 /**