browser-debugger-cli 0.11.0 → 0.13.0

package/dist/telemetry/console.js

@@ -75,15 +75,23 @@ function createMessage(type, text, timestamp, args, context) {
     };
 }
 /**
- * Insert a message in timestamp order.
- * Messages are kept sorted by timestamp to handle async expansion delays.
+ * Insert a message in timestamp order (async expansion can deliver a message
+ * late). At {@link MAX_CONSOLE_MESSAGES} the oldest message is dropped to
+ * make room, so the newest are kept; a late message older than all kept ones
+ * is dropped itself.
  *
- * @returns False when the message limit is reached (the message is dropped)
+ * @param messages - Messages, oldest first (updated)
+ * @param message - Message to add
+ * @param onDropped - Called for each message dropped
+ * @returns False when the message itself was dropped
  */
-function insertMessageByTimestamp(messages, message) {
+function insertMessageByTimestamp(messages, message, onDropped) {
     if (messages.length >= MAX_CONSOLE_MESSAGES) {
-        log.debug(`Warning: Console message limit reached (${MAX_CONSOLE_MESSAGES})`);
-        return false;
+        const oldest = messages[0];
+        onDropped();
+        if (oldest && message.timestamp < oldest.timestamp)
+            return false;
+        messages.shift();
     }
     const insertIndex = findInsertIndex(messages, message.timestamp);
     messages.splice(insertIndex, 0, message);
@@ -111,32 +119,31 @@ function findInsertIndex(messages, timestamp) {
 /**
  * Handle a console API call event with object expansion.
  */
-function handleConsoleAPICall(cdp, messages, params, context, includeAll) {
+function handleConsoleAPICall(cdp, insert, params, context, includeAll) {
     const basicText = formatConsoleArgs(params.args);
     if (shouldExcludeConsoleMessage(basicText, params.type, includeAll)) {
         return;
     }
     if (hasArgsNeedingExpansion(params.args) && !usesFormatSpecifiers(params.args)) {
-        handleExpandableMessage(cdp, messages, params, context, basicText);
+        handleExpandableMessage(cdp, insert, params, context, basicText);
     }
     else {
-        const message = createMessage(params.type, basicText, params.timestamp, params.args, context);
-        insertMessageByTimestamp(messages, message);
+        insert(createMessage(params.type, basicText, params.timestamp, params.args, context));
     }
 }
 /**
  * Handle a message with expandable objects.
  */
-function handleExpandableMessage(cdp, messages, params, context, fallbackText) {
+function handleExpandableMessage(cdp, insert, params, context, fallbackText) {
     void expandConsoleArgs(cdp, params.args)
         .then((expandedText) => {
         const message = createMessage(params.type, expandedText, params.timestamp, params.args, context);
-        insertMessageByTimestamp(messages, message);
+        insert(message);
     })
         .catch((error) => {
         log.debug(`Object expansion failed, using basic text: ${String(error)}`);
         const message = createMessage(params.type, fallbackText, params.timestamp, params.args, context);
-        insertMessageByTimestamp(messages, message);
+        insert(message);
     });
 }
 /**
@@ -178,14 +185,14 @@ export function formatExceptionText(details) {
  *
  * @returns The message added, undefined when filtered out or over the limit
  */
-function handleExceptionThrown(messages, params, context, includeAll) {
+function handleExceptionThrown(insert, params, context, includeAll) {
     const exception = params.exceptionDetails;
     const text = formatExceptionText(exception);
     if (shouldExcludeConsoleMessage(text, 'error', includeAll)) {
         return undefined;
     }
     const message = createMessage('error', text, params.timestamp, undefined, context);
-    return insertMessageByTimestamp(messages, message) ? message : undefined;
+    return insert(message) ? message : undefined;
 }
 /** CDP's text of an unhandled promise rejection (the only kind Chrome revokes) */
 const UNHANDLED_REJECTION_TEXT = 'Uncaught (in promise)';
@@ -270,7 +277,7 @@ class RevocableRejections {
  * Worker entries are skipped: workers are attached directly, so their console
  * calls already arrive (with arguments) from the worker's own session.
  */
-function handleLogEntry(messages, entry, navigationId, includeAll) {
+function handleLogEntry(insert, entry, navigationId, includeAll) {
     const type = LOG_LEVEL_TYPES[entry.level];
     if (entry.source === 'worker' || shouldExcludeConsoleMessage(entry.text, type, includeAll)) {
         return;
@@ -287,7 +294,7 @@ function handleLogEntry(messages, entry, navigationId, includeAll) {
         stackTrace: convertStackTrace(entry.stackTrace) ?? location,
         source: entry.source,
     };
-    insertMessageByTimestamp(messages, createMessage(type, entry.text, entry.timestamp, undefined, context));
+    insert(createMessage(type, entry.text, entry.timestamp, undefined, context));
 }
 /**
  * Enable console and log events on an attached target's session.
@@ -325,17 +332,19 @@ async function startOptionalSources(cdp, typed) {
  * @param messages - Array to populate with console messages
  * @param includeAll - If true, disable default pattern filtering
  * @param getCurrentNavigationId - Function to get current navigation ID
+ * @param onDropped - Called for each message dropped at the limit (the oldest go first)
  * @returns Cleanup function to remove event handlers
  */
-export async function startConsoleCollection(cdp, messages, includeAll = false, getCurrentNavigationId) {
+export async function startConsoleCollection(cdp, messages, includeAll = false, getCurrentNavigationId, onDropped = () => undefined) {
     const registry = new CDPHandlerRegistry();
     const typed = new TypedCDPConnection(cdp);
+    const insert = (message) => insertMessageByTimestamp(messages, message, onDropped);
     registry.registerTyped(typed, 'Runtime.consoleAPICalled', (params, sessionId) => {
         const context = {
             navigationId: getCurrentNavigationId?.(),
             stackTrace: convertStackTrace(params.stackTrace),
         };
-        handleConsoleAPICall(senderFor(cdp, sessionId), messages, params, context, includeAll);
+        handleConsoleAPICall(senderFor(cdp, sessionId), insert, params, context, includeAll);
     });
     const rejections = new RevocableRejections();
     registry.registerTyped(typed, 'Runtime.exceptionThrown', (params, sessionId) => {
@@ -343,7 +352,7 @@ export async function startConsoleCollection(cdp, messages, includeAll = false,
             navigationId: getCurrentNavigationId?.(),
             stackTrace: convertStackTrace(params.exceptionDetails.stackTrace),
         };
-        const message = handleExceptionThrown(messages, params, context, includeAll);
+        const message = handleExceptionThrown(insert, params, context, includeAll);
         if (message)
             rejections.track(params.exceptionDetails, message, sessionId);
     });
@@ -357,7 +366,7 @@ export async function startConsoleCollection(cdp, messages, includeAll = false,
         rejections.forgetSession(sessionId);
     });
     registry.registerTyped(typed, 'Log.entryAdded', ({ entry }) => {
-        handleLogEntry(messages, entry, getCurrentNavigationId?.(), includeAll);
+        handleLogEntry(insert, entry, getCurrentNavigationId?.(), includeAll);
     });
     try {
         await typed.send('Runtime.enable', {});

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

@@ -226,10 +226,14 @@ 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;
     };
     error?: string;
     partial?: boolean;
@@ -327,6 +331,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 */
@@ -370,6 +376,8 @@ export type ColorScheme = 'light' | 'dark';
 export interface ViewportSize {
     width: number;
     height: number;
+    /** A phone: mobile viewport (meta viewport, overlay scrollbars), touch and a mobile user agent */
+    mobile?: true;
 }
 /**
  * The page (document) request an action sent, as far as it got: still
@@ -436,6 +444,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.
@@ -483,6 +499,8 @@ export interface ScreenshotResult {
          * descendants) made it larger than the border box
          */
         captured?: ElementBounds;
+        /** `--padding` given: CSS px of page added around the captured area */
+        padding?: number;
     };
     /** Capture mode used */
     captureMode?: 'full_page' | 'viewport';
@@ -675,5 +693,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/formatters/audit.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Human output of `bdg dom audit` and `bdg css search`.
+ */
+import type { AuditResult, CssSearchResult } from '../../ipc/protocol/auditTypes.js';
+/**
+ * Format `bdg dom audit`.
+ *
+ * @param data - Audit result
+ * @returns Output
+ */
+export declare function formatAudit(data: AuditResult): string;
+/**
+ * Format `bdg css search`.
+ *
+ * @param data - Search result
+ * @returns Output
+ */
+export declare function formatCssSearch(data: CssSearchResult): string;
+//# sourceMappingURL=audit.d.ts.map

package/dist/ui/formatters/audit.js

@@ -0,0 +1,115 @@
+/**
+ * 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;
+/**
+ * Format `bdg dom audit`.
+ *
+ * @param data - Audit result
+ * @returns Output
+ */
+export function formatAudit(data) {
+    const sections = [
+        data.contrast && contrastSection(data.contrast),
+        data.overflow && overflowSection(data.overflow),
+        data.layers && layersSection(data.layers),
+        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();
+}
+/**
+ * The contrast section.
+ *
+ * @param contrast - Contrast findings
+ * @returns Lines
+ */
+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.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)`] : []),
+        ...(contrast.uncertain ? [`  ${auditUncertainContrastNote(contrast.uncertain)}`] : []),
+    ];
+}
+/**
+ * The overflow section.
+ *
+ * @param overflow - Overflow findings
+ * @returns Lines
+ */
+function overflowSection(overflow) {
+    const head = overflow.scrollsSideways
+        ? `Overflow: the page is ${overflow.pageWidth} wide in a ${overflow.viewportWidth} viewport (it scrolls sideways)`
+        : `Overflow: nothing makes the page scroll sideways (${overflow.viewportWidth} wide)`;
+    return [
+        head,
+        ...overflow.wide.map((item) => `  past the right edge: ${item.element} (to ${item.right}, ${item.width} wide)`),
+        ...overflow.truncated.map((item) => `  cut off (${item.kind}): ${item.element}${times(item.count)} "${truncateByLength(item.text, TEXT_WIDTH)}"`),
+        ...overflow.scrollers.map((item) => `  scrolls sideways inside: ${item.element} (${item.scrollWidth} of content in ${item.width})`),
+        ...overflow.images.map((image) => `  image ${[image.upscaled && `upscaled ${image.scale}x${overflow.pixelRatio > 1 ? ` at pixel ratio ${overflow.pixelRatio}` : ''}`, image.distorted && 'distorted'].filter(Boolean).join(', ')}: ${image.element}${times(image.count)} ${image.natural.w}x${image.natural.h} pixels drawn at ${image.rendered.w}x${image.rendered.h} CSS px`),
+    ];
+}
+/**
+ * How many identical findings a row stands for.
+ *
+ * @param count - Count, when 2 or more
+ * @returns e.g. ` ×5`, or empty
+ */
+function times(count) {
+    return count ? ` ×${count}` : '';
+}
+/**
+ * The layers section.
+ *
+ * @param layers - Fixed and sticky elements
+ * @returns Lines
+ */
+function layersSection(layers) {
+    if (layers.length === 0)
+        return ['Layers: no fixed or sticky elements'];
+    return [
+        `Layers: ${layers.length} fixed or sticky`,
+        ...layers.map((layer) => `  ${layer.position} z ${layer.zIndex}  ${layer.element} ${layer.rect.w}x${layer.rect.h} at ${layer.rect.x},${layer.rect.y} of the viewport${layer.inView ? '' : ' (not in view now)'}`),
+    ];
+}
+/**
+ * The animations section.
+ *
+ * @param animations - Running animations
+ * @param canvases - Visible canvas elements
+ * @returns Lines
+ */
+function animationsSection(animations, canvases) {
+    const note = canvases ? [`  ${auditCanvasNote(canvases)}`] : [];
+    if (animations.length === 0)
+        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,
+    ];
+}
+/**
+ * Format `bdg css search`.
+ *
+ * @param data - Search result
+ * @returns Output
+ */
+export function formatCssSearch(data) {
+    if (data.total === 0)
+        return `"${data.query}" is not in the page's ${data.sheets} stylesheets`;
+    const more = data.total - data.matches.length;
+    return [
+        `"${data.query}": ${data.total} matches in ${data.sheets} stylesheets`,
+        ...data.matches.flatMap((match) => [`  ${match.source}`, `    ${match.text}`]),
+        ...(more > 0 ? [`  (+${more} more; --limit to list them)`] : []),
+    ].join('\n');
+}
+//# sourceMappingURL=audit.js.map

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

@@ -0,0 +1,138 @@
+/**
+ * Human-readable output of `bdg cdp`: search results, domain and method
+ * lists, method schemas and method results (`--json` prints the data as is).
+ */
+import type { ParameterSchema, ReturnSchema } from '../../cdp/schema.js';
+/** Protocol description and flags shared by domains and methods */
+interface ProtocolEntry {
+    description?: string | undefined;
+    experimental?: boolean | undefined;
+    deprecated?: boolean | undefined;
+}
+/** A method in `bdg cdp --search` results */
+interface CdpSearchMethod extends ProtocolEntry {
+    name: string;
+    domain: string;
+    method: string;
+    parameterCount: number;
+    example?: string | undefined;
+}
+/** `bdg cdp --search <query>` result */
+export interface CdpSearchData {
+    query: string;
+    count: number;
+    methods: CdpSearchMethod[];
+}
+/** A domain in `bdg cdp --list` */
+interface CdpDomainEntry extends ProtocolEntry {
+    name: string;
+    commands: number;
+    events: number;
+    dependencies?: string[] | undefined;
+}
+/** `bdg cdp --list` result */
+export interface CdpDomainListData {
+    count: number;
+    domains: CdpDomainEntry[];
+}
+/** A method in `bdg cdp <Domain> --list` */
+interface CdpDomainMethod extends ProtocolEntry {
+    name: string;
+    fullName: string;
+    parameterCount: number;
+    parameters: Pick<ParameterSchema, 'name' | 'type' | 'required'>[];
+    returns: Pick<ReturnSchema, 'name' | 'type'>[];
+    example?: string | undefined;
+}
+/** `bdg cdp <Domain> --list` result */
+export interface CdpDomainMethodsData {
+    domain: string;
+    description?: string | undefined;
+    count: number;
+    methods: CdpDomainMethod[];
+}
+/** `bdg cdp <Domain> --describe` result */
+export interface CdpDomainDescription extends ProtocolEntry {
+    type: 'domain';
+    domain: string;
+    commands: number;
+    events: number;
+    note?: string | undefined;
+    nextStep: string;
+}
+/** A parameter or return value in `bdg cdp <Domain.method> --describe` */
+interface CdpField {
+    name: string;
+    type: string;
+    description?: string | undefined;
+    items?: string | undefined;
+}
+/** `bdg cdp <Domain.method> --describe` result */
+export interface CdpMethodDescription extends ProtocolEntry {
+    type: 'method';
+    name: string;
+    domain: string;
+    method: string;
+    note?: string | undefined;
+    parameters: (CdpField & {
+        required: boolean;
+        enum?: string[] | undefined;
+        deprecated?: boolean | undefined;
+    })[];
+    returns: (CdpField & {
+        optional: boolean;
+    })[];
+    example?: {
+        command: string;
+        params?: Record<string, unknown> | undefined;
+    } | undefined;
+}
+/** `bdg cdp <Domain.method>` result */
+export interface CdpExecuteData {
+    method: string;
+    result: unknown;
+}
+/**
+ * Format `bdg cdp --search <query>`.
+ *
+ * @param data - Search result
+ * @returns Matching methods with their first description sentence
+ */
+export declare function formatCdpSearch(data: CdpSearchData): string;
+/**
+ * Format `bdg cdp --list`.
+ *
+ * @param data - All domains
+ * @returns One line per domain with its method and event counts
+ */
+export declare function formatCdpDomains(data: CdpDomainListData): string;
+/**
+ * Format `bdg cdp <Domain> --list`.
+ *
+ * @param data - The domain's methods
+ * @returns One line per method with the first sentence of its description
+ */
+export declare function formatCdpDomainMethods(data: CdpDomainMethodsData): string;
+/**
+ * Format `bdg cdp <Domain.method> --describe` or `bdg cdp <Domain> --describe`.
+ *
+ * @param data - Method or domain description
+ * @returns Description, parameters (`?` = optional), returns, note and example
+ */
+export declare function formatCdpDescription(data: CdpMethodDescription | CdpDomainDescription): string;
+/**
+ * Whether a CDP method returned nothing (null, undefined or an empty object).
+ *
+ * @param result - Method result
+ * @returns True for an empty result
+ */
+export declare function isEmptyCdpResult(result: unknown): boolean;
+/**
+ * Format a CDP method's result: the result object as indented JSON.
+ *
+ * @param data - Method and its result
+ * @returns The result, or a line saying the method returned nothing
+ */
+export declare function formatCdpResult(data: CdpExecuteData): string;
+export {};
+//# sourceMappingURL=cdp.d.ts.map