browser-debugger-cli 0.11.0 → 0.13.0

package/dist/ui/formatters/cdp.js

@@ -0,0 +1,131 @@
+/**
+ * Human-readable output of `bdg cdp`: search results, domain and method
+ * lists, method schemas and method results (`--json` prints the data as is).
+ */
+import { joinLines, pluralize } from '../formatting.js';
+/**
+ * First sentence (or line) of a protocol description.
+ *
+ * @param description - Description, possibly multi-line
+ * @returns Its first sentence, or an empty string
+ */
+function firstSentence(description) {
+    const [line = ''] = (description ?? '').split('\n');
+    const end = line.indexOf('. ');
+    return end === -1 ? line : line.slice(0, end + 1);
+}
+/**
+ * `(experimental, deprecated)` tags, or nothing.
+ *
+ * @param flags - Protocol flags
+ * @returns Tag text with a leading space, or an empty string
+ */
+function tags(flags) {
+    const names = [flags.experimental && 'experimental', flags.deprecated && 'deprecated'].filter(Boolean);
+    return names.length > 0 ? ` (${names.join(', ')})` : '';
+}
+/**
+ * Rows of a name column padded to one width, then the rest.
+ *
+ * @param rows - Name and text of each row
+ * @returns Indented lines
+ */
+function columns(rows) {
+    const width = Math.max(0, ...rows.map(([name]) => name.length));
+    return rows.map(([name, text]) => `  ${name.padEnd(width)}  ${text.trim()}`.trimEnd());
+}
+/**
+ * A type as written in the schema, e.g. "array<Cookie>".
+ *
+ * @param field - Parameter or return value
+ * @returns Type text
+ */
+function typeText(field) {
+    return field.items ? `${field.type}<${field.items}>` : field.type;
+}
+/**
+ * Format `bdg cdp --search <query>`.
+ *
+ * @param data - Search result
+ * @returns Matching methods with their first description sentence
+ */
+export function formatCdpSearch(data) {
+    if (data.count === 0) {
+        return joinLines(`No CDP method matches "${data.query}"`, 'List the domains: bdg cdp --list');
+    }
+    return joinLines(`${pluralize(data.count, 'method')} ${data.count === 1 ? 'matches' : 'match'} "${data.query}":`, ...columns(data.methods.map((m) => [m.name, `${firstSentence(m.description)}${tags(m)}`])), 'Parameters and an example: bdg cdp <Domain.method> --describe');
+}
+/**
+ * Format `bdg cdp --list`.
+ *
+ * @param data - All domains
+ * @returns One line per domain with its method and event counts
+ */
+export function formatCdpDomains(data) {
+    return joinLines(`${pluralize(data.count, 'CDP domain')}:`, ...columns(data.domains.map((d) => [
+        d.name,
+        `${pluralize(d.commands, 'method')}, ${pluralize(d.events, 'event')}${tags(d)}`,
+    ])), 'Methods of a domain: bdg cdp <Domain> --list');
+}
+/**
+ * Format `bdg cdp <Domain> --list`.
+ *
+ * @param data - The domain's methods
+ * @returns One line per method with the first sentence of its description
+ */
+export function formatCdpDomainMethods(data) {
+    return joinLines(`${data.domain}: ${pluralize(data.count, 'method')}`, firstSentence(data.description) || undefined, ...columns(data.methods.map((m) => [m.name, `${firstSentence(m.description)}${tags(m)}`])), `Parameters and an example: bdg cdp ${data.domain}.<method> --describe`);
+}
+/**
+ * Lines of a parameter or return value list.
+ *
+ * @param title - Section title
+ * @param fields - Parameters or return values
+ * @returns Title and one line per field, or nothing for an empty list
+ */
+function fieldSection(title, fields) {
+    if (fields.length === 0)
+        return [];
+    return [
+        `${title}:`,
+        ...columns(fields.map((f) => [
+            `${f.name}${f.optional ? '?' : ''}: ${typeText(f)}`,
+            (f.description ?? '').replace(/\s*\n\s*/g, ' '),
+        ])),
+    ];
+}
+/**
+ * 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 function formatCdpDescription(data) {
+    if (data.type === 'domain') {
+        return joinLines(`${data.domain}: ${pluralize(data.commands, 'method')}, ${pluralize(data.events, 'event')}${tags(data)}`, data.description, data.note, data.nextStep);
+    }
+    return joinLines(`${data.name}${tags(data)}`, data.description, ...fieldSection('Parameters', data.parameters.map((p) => ({ ...p, optional: !p.required }))), ...fieldSection('Returns', data.returns), data.note && `Note: ${data.note}`, data.example && `Example: ${data.example.command}`);
+}
+/**
+ * Whether a CDP method returned nothing (null, undefined or an empty object).
+ *
+ * @param result - Method result
+ * @returns True for an empty result
+ */
+export function isEmptyCdpResult(result) {
+    return (result === null ||
+        result === undefined ||
+        (typeof result === 'object' && Object.keys(result).length === 0));
+}
+/**
+ * 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 function formatCdpResult(data) {
+    return isEmptyCdpResult(data.result)
+        ? `${data.method}: done (no result data)`
+        : JSON.stringify(data.result, null, 2);
+}
+//# sourceMappingURL=cdp.js.map

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

@@ -3,7 +3,7 @@
  * level prefixes, and navigation reload markers.
  */
 import { OutputFormatter } from '../../formatting.js';
-import { consoleIndexGapNote } from '../../messages/consoleMessages.js';
+import { consoleDroppedNote, consoleIndexGapNote } from '../../messages/consoleMessages.js';
 import { truncateByLength } from '../../../utils/strings.js';
 import { formatSourceLocation, formatTimestamp } from './shared.js';
 const MAX_LIST_TEXT_LENGTH = 200;
@@ -22,6 +22,8 @@ export function formatConsoleChronological(messages, options) {
         : `Console Messages (last ${displayMessages.length} of ${messages.length})${headerSuffix}`;
     fmt.text(header);
     fmt.separator('━', 50);
+    if (options.dropped)
+        fmt.text(consoleDroppedNote(options.dropped));
     if (displayMessages.length === 0) {
         fmt.text('No console messages');
         return fmt.build();

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

@@ -5,7 +5,8 @@
 import type { ConsoleMessage } from '../../../types.js';
 /**
  * Lines of the console stream: the new messages since the last poll, with
- * the stream header the first time and a separator after a navigation.
+ * a rule the first time (the stream banner is on stderr) and a separator
+ * after a navigation.
  *
  * @param messages - New messages
  * @param options - `header` the first time; `navigationId` when the page changed

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

@@ -6,7 +6,8 @@ import { OutputFormatter } from '../../formatting.js';
 import { formatSourceLocation, formatTimestamp } from './shared.js';
 /**
  * Lines of the console stream: the new messages since the last poll, with
- * the stream header the first time and a separator after a navigation.
+ * a rule the first time (the stream banner is on stderr) and a separator
+ * after a navigation.
  *
  * @param messages - New messages
  * @param options - `header` the first time; `navigationId` when the page changed
@@ -15,7 +16,6 @@ import { formatSourceLocation, formatTimestamp } from './shared.js';
 export function formatConsoleFollowLines(messages, options = {}) {
     const fmt = new OutputFormatter();
     if (options.header) {
-        fmt.text('Streaming console... (Ctrl+C to stop)');
         fmt.separator('━', 40);
         if (messages.length === 0)
             fmt.text('Waiting for messages...');

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

@@ -6,8 +6,8 @@
 import type { ConsoleMessage } from '../../../types.js';
 import { type ConsoleFormatOptions, type ConsoleJsonOutput } from './shared.js';
 /**
- * Build the rich JSON output shape (summary + deduped errors/warnings, plus
- * the full message list when --list is requested).
+ * Build the rich JSON output shape (summary + the newest deduped
+ * errors/warnings, plus the message list when --list is requested).
  *
  * Returns a plain object so callers (e.g. runCommand's JSON envelope) can
  * embed it without re-parsing a stringified payload.

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

@@ -4,7 +4,7 @@
  * --list is set.
  */
 import { lastMessages } from './chronological.js';
-import { analyzeMessages, } from './shared.js';
+import { analyzeMessages, newestGroups, } from './shared.js';
 function toJsonError(dedup, includeStackTrace) {
     const source = dedup.message.stackTrace?.[0];
     return {
@@ -25,18 +25,24 @@ function toJsonError(dedup, includeStackTrace) {
     };
 }
 /**
- * Build the rich JSON output shape (summary + deduped errors/warnings, plus
- * the full message list when --list is requested).
+ * Build the rich JSON output shape (summary + the newest deduped
+ * errors/warnings, plus the message list when --list is requested).
  *
  * Returns a plain object so callers (e.g. runCommand's JSON envelope) can
  * embed it without re-parsing a stringified payload.
  */
 export function buildConsoleJsonOutput(messages, options) {
     const { grouped, summary } = analyzeMessages(messages);
+    const errors = newestGroups(grouped.errors, options.groupLimit);
+    const warnings = newestGroups(grouped.warnings, options.groupLimit);
     const output = {
         summary,
-        errors: grouped.errors.map((d) => toJsonError(d, true)),
-        warnings: grouped.warnings.map((d) => toJsonError(d, false)),
+        errors: errors.shown.map((d) => toJsonError(d, true)),
+        warnings: warnings.shown.map((d) => toJsonError(d, false)),
+        ...(errors.more > 0 && { moreErrors: errors.more }),
+        ...(warnings.more > 0 && { moreWarnings: warnings.more }),
+        ...(options.dropped && { dropped: options.dropped }),
+        ...(options.pageCrashedAt !== undefined && { pageCrashedAt: options.pageCrashedAt }),
     };
     if (options.list)
         output.messages = lastMessages(messages, options.last);

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

@@ -57,7 +57,27 @@ export interface ConsoleFormatOptions {
     level?: ConsoleLevel | undefined;
     /** Messages between the first and last listed index that the filters left out */
     skipped?: ConsoleSkipped | undefined;
+    /** Distinct errors and warnings listed, the newest (0 = all; default {@link DEFAULT_GROUP_LIMIT}) */
+    groupLimit?: number | undefined;
+    /** Oldest messages the session dropped at its limit */
+    dropped?: number | undefined;
+    /** When the page crashed (epoch ms), while it is not loaded again */
+    pageCrashedAt?: number | undefined;
 }
+/** Distinct errors and warnings the summary lists without `--last` */
+export declare const DEFAULT_GROUP_LIMIT = 50;
+/**
+ * The newest distinct messages of a level, and how many earlier ones are not
+ * listed.
+ *
+ * @param groups - Distinct messages, in order of first appearance
+ * @param limit - How many to keep (0 = all; undefined: {@link DEFAULT_GROUP_LIMIT})
+ * @returns Groups to list and the count left out
+ */
+export declare function newestGroups(groups: DeduplicatedMessage[], limit: number | undefined): {
+    shown: DeduplicatedMessage[];
+    more: number;
+};
 /**
  * Messages the page and level filters left out between the first and last
  * listed index (session indices then skip numbers).
@@ -90,8 +110,18 @@ export interface JsonErrorEntry {
  */
 export interface ConsoleJsonOutput {
     summary: ConsoleSummary;
+    /** The newest distinct errors (see `moreErrors`) */
     errors: JsonErrorEntry[];
+    /** The newest distinct warnings (see `moreWarnings`) */
     warnings: Omit<JsonErrorEntry, 'stackTrace'>[];
+    /** Earlier distinct errors not in `errors` (`--last 0` lists all) */
+    moreErrors?: number;
+    /** Earlier distinct warnings not in `warnings` */
+    moreWarnings?: number;
+    /** Oldest messages the session dropped at its limit (10000 are kept) */
+    dropped?: number;
+    /** When the page crashed (epoch ms), while it is not loaded again */
+    pageCrashedAt?: number;
     messages?: ConsoleMessage[];
 }
 /**

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

@@ -1,6 +1,22 @@
 /**
  * Shared types, constants, and helpers used by every console formatter.
  */
+/** Distinct errors and warnings the summary lists without `--last` */
+export const DEFAULT_GROUP_LIMIT = 50;
+/**
+ * The newest distinct messages of a level, and how many earlier ones are not
+ * listed.
+ *
+ * @param groups - Distinct messages, in order of first appearance
+ * @param limit - How many to keep (0 = all; undefined: {@link DEFAULT_GROUP_LIMIT})
+ * @returns Groups to list and the count left out
+ */
+export function newestGroups(groups, limit) {
+    const keep = limit ?? DEFAULT_GROUP_LIMIT;
+    if (keep === 0 || groups.length <= keep)
+        return { shown: groups, more: 0 };
+    return { shown: groups.slice(-keep), more: groups.length - keep };
+}
 /**
  * Mapping from console message types to level categories.
  * Exported for use by console command filtering.

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

@@ -3,8 +3,15 @@
  * and shows info/debug/other as count-only footer entries.
  */
 import type { ConsoleMessage } from '../../../types.js';
+import { type ConsoleFormatOptions } from './shared.js';
 /**
- * Format console output as smart summary (default mode).
+ * Format console output as smart summary (default mode): the newest distinct
+ * errors and warnings, counts of the rest, and a note when the session
+ * dropped its oldest messages.
+ *
+ * @param messages - Messages to summarise
+ * @param options - Distinct messages listed and messages dropped
+ * @returns Summary
  */
-export declare function formatConsoleSummary(messages: ConsoleMessage[]): string;
+export declare function formatConsoleSummary(messages: ConsoleMessage[], options?: Pick<ConsoleFormatOptions, 'groupLimit' | 'dropped'>): string;
 //# sourceMappingURL=summarize.d.ts.map

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

@@ -3,13 +3,25 @@
  * and shows info/debug/other as count-only footer entries.
  */
 import { OutputFormatter, pluralize } from '../../formatting.js';
-import { analyzeMessages, formatCountPrefix, formatSectionHeader, formatSourceLocation, } from './shared.js';
-function renderErrorSection(fmt, errors, total) {
+import { consoleDroppedNote, consoleMoreGroupsNote } from '../../messages/consoleMessages.js';
+import { analyzeMessages, formatCountPrefix, formatSectionHeader, formatSourceLocation, newestGroups, } from './shared.js';
+/**
+ * The errors: the newest distinct ones, with a note for the earlier ones.
+ *
+ * @param fmt - Output
+ * @param errors - Distinct errors in order of first appearance
+ * @param total - Errors logged
+ * @param limit - Distinct errors listed (0 = all)
+ */
+function renderErrorSection(fmt, errors, total, limit) {
     if (errors.length === 0)
         return;
+    const { shown, more } = newestGroups(errors, limit);
     fmt.text(formatSectionHeader('Errors', errors.length, total));
     fmt.separator('─', 30);
-    for (const { message, count } of errors) {
+    if (more > 0)
+        fmt.text(consoleMoreGroupsNote(more, 'error')).blank();
+    for (const { message, count } of shown) {
         fmt.text(`${formatCountPrefix(count)}${message.text}`);
         const source = formatSourceLocation(message.stackTrace);
         if (source) {
@@ -18,12 +30,23 @@ function renderErrorSection(fmt, errors, total) {
         fmt.blank();
     }
 }
-function renderWarningSection(fmt, warnings, total) {
+/**
+ * The warnings: the newest distinct ones, with a note for the earlier ones.
+ *
+ * @param fmt - Output
+ * @param warnings - Distinct warnings in order of first appearance
+ * @param total - Warnings logged
+ * @param limit - Distinct warnings listed (0 = all)
+ */
+function renderWarningSection(fmt, warnings, total, limit) {
     if (warnings.length === 0)
         return;
+    const { shown, more } = newestGroups(warnings, limit);
     fmt.text(formatSectionHeader('Warnings', warnings.length, total));
     fmt.separator('─', 30);
-    for (const { message, count } of warnings) {
+    if (more > 0)
+        fmt.text(consoleMoreGroupsNote(more, 'warning'));
+    for (const { message, count } of shown) {
         fmt.text(`• ${formatCountPrefix(count)}${message.text}`);
         const source = formatSourceLocation(message.stackTrace);
         if (source)
@@ -43,16 +66,24 @@ function renderOtherSummary(fmt, summary) {
     }
 }
 /**
- * Format console output as smart summary (default mode).
+ * Format console output as smart summary (default mode): the newest distinct
+ * errors and warnings, counts of the rest, and a note when the session
+ * dropped its oldest messages.
+ *
+ * @param messages - Messages to summarise
+ * @param options - Distinct messages listed and messages dropped
+ * @returns Summary
  */
-export function formatConsoleSummary(messages) {
+export function formatConsoleSummary(messages, options = {}) {
     const fmt = new OutputFormatter();
     const { grouped, summary } = analyzeMessages(messages);
     fmt.text('Console Summary');
     fmt.separator('━', 60);
+    if (options.dropped)
+        fmt.text(consoleDroppedNote(options.dropped));
     fmt.blank();
-    renderErrorSection(fmt, grouped.errors, summary.errors.total);
-    renderWarningSection(fmt, grouped.warnings, summary.warnings.total);
+    renderErrorSection(fmt, grouped.errors, summary.errors.total, options.groupLimit);
+    renderWarningSection(fmt, grouped.warnings, summary.warnings.total, options.groupLimit);
     if (grouped.errors.length === 0 && grouped.warnings.length === 0) {
         fmt.text('No errors or warnings found');
         fmt.blank();

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

@@ -16,7 +16,8 @@ export { formatConsoleSummary } from './console/summarize.js';
 /**
  * Format console output based on options. Routes to the per-mode formatter:
  * a `--level` filter lists the matching messages (the summary only shows
- * errors and warnings, so it would hide e.g. `--level info`).
+ * errors and warnings, so it would hide e.g. `--level info`). The text
+ * starts with a warning when the page crashed.
  */
 export declare function formatConsole(messages: ConsoleMessage[], options: ConsoleFormatOptions): string;
 //# sourceMappingURL=console.d.ts.map

package/dist/ui/formatters/console.js

@@ -5,6 +5,7 @@
  * the `formatConsole` dispatcher. The per-mode implementations live in
  * `./console/`.
  */
+import { withPageCrashedNote } from '../messages/commands.js';
 import { formatConsoleChronological } from './console/chronological.js';
 import { formatConsoleJson } from './console/json.js';
 import { formatConsoleSummary } from './console/summarize.js';
@@ -16,15 +17,16 @@ export { formatConsoleSummary } from './console/summarize.js';
 /**
  * Format console output based on options. Routes to the per-mode formatter:
  * a `--level` filter lists the matching messages (the summary only shows
- * errors and warnings, so it would hide e.g. `--level info`).
+ * errors and warnings, so it would hide e.g. `--level info`). The text
+ * starts with a warning when the page crashed.
  */
 export function formatConsole(messages, options) {
     if (options.json) {
         return formatConsoleJson(messages, options);
     }
-    if (options.list || options.level) {
-        return formatConsoleChronological(messages, options);
-    }
-    return formatConsoleSummary(messages);
+    const body = options.list || options.level
+        ? formatConsoleChronological(messages, options)
+        : formatConsoleSummary(messages, options);
+    return withPageCrashedNote(body, options.pageCrashedAt);
 }
 //# sourceMappingURL=console.js.map

package/dist/ui/formatters/details.js

@@ -184,13 +184,15 @@ function requestSummaryRows(request) {
 }
 /**
  * Add a header block, a header sent several times one value per line
- * ({@link headerValueLines}).
+ * ({@link headerValueLines}); nothing when there are no headers.
  *
  * @param fmt - Formatter
  * @param title - Block title
  * @param headers - Headers to list
  */
 function addHeaders(fmt, title, headers) {
+    if (Object.keys(headers).length === 0)
+        return;
     fmt.text(title).separator('━', 70);
     Object.entries(headers).forEach(([key, value]) => headerValueLines(key, value).forEach((line) => fmt.text(`  ${key}: ${line}`)));
     fmt.blank();

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

@@ -6,7 +6,7 @@ import type { DomQueryResult, DomGetResult, ScreenshotResult } from '../../types
  * Displays found nodes with their index, tag, identifying attributes
  * ({@link queryTagAttributes}), 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).
+ * `(below fold)`), as many as `--limit` listed, with a note for the rest (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.
  *
@@ -127,7 +127,7 @@ export declare function formatDomFrames(data: {
  * // 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)
+ * // Output: Screenshot saved to ./el.png (grown from 940×37 to 940×285 to include what it paints outside its box (…))
  * ```
  */
 export declare function formatDomScreenshot(data: ScreenshotResult): string;

package/dist/ui/formatters/dom.js

@@ -1,15 +1,13 @@
 import { keyAttributeItems } from './keyAttributes.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;
+import { frameLabel, framesStillLoadingNote, noFramesMessage, queryMoreMatchesNote, queryViewportCheckedNote, queryNextSteps, screenshotGrownNote, screenshotScaledNote, viewportPositionHint, } from '../messages/commands.js';
 /**
  * Format DOM query results for human-readable output.
  *
  * Displays found nodes with their index, tag, identifying attributes
  * ({@link queryTagAttributes}), 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).
+ * `(below fold)`), as many as `--limit` listed, with a note for the rest (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.
  *
@@ -35,7 +33,7 @@ const QUERY_DISPLAY_LIMIT = 50;
 export function formatDomQuery(data) {
     const { count, nodes, selector } = data;
     const fmt = new OutputFormatter();
-    const nodeLines = nodes.slice(0, QUERY_DISPLAY_LIMIT).map((node) => {
+    const nodeLines = nodes.map((node) => {
         const attributes = queryTagAttributes(node)
             .map((item) => ` ${item}`)
             .join('');
@@ -49,7 +47,8 @@ export function formatDomQuery(data) {
     return fmt
         .text(`Found ${count} node${count === 1 ? '' : 's'} matching "${selector}":`)
         .list(nodeLines)
-        .list(count > QUERY_DISPLAY_LIMIT ? [moreMatchesNote(count - QUERY_DISPLAY_LIMIT)] : [])
+        .list(data.omitted ? [queryMoreMatchesNote(data.omitted, data.indexed)] : [])
+        .list(data.viewportChecked ? [queryViewportCheckedNote(data.viewportChecked)] : [])
         .tip(queryNextSteps(exampleIndex))
         .build();
 }
@@ -212,7 +211,7 @@ export function formatDomFrames(data) {
  * // 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)
+ * // Output: Screenshot saved to ./el.png (grown from 940×37 to 940×285 to include what it paints outside its box (…))
  * ```
  */
 export function formatDomScreenshot(data) {
@@ -221,7 +220,10 @@ export function formatDomScreenshot(data) {
         output += ' (viewport only - page too tall)';
     }
     if (data.element?.captured) {
-        output += ` (${screenshotGrownNote(data.element.bounds, data.element.captured)})`;
+        output += ` (${screenshotGrownNote(data.element.bounds, data.element.captured, data.element.padding)})`;
+    }
+    if (data.resized && data.originalWidth !== undefined && data.originalHeight !== undefined) {
+        output += ` (${screenshotScaledNote(data.originalWidth, data.originalHeight, data.width, data.height)})`;
     }
     return output;
 }

package/dist/ui/formatters/helpFormatters.js

@@ -17,7 +17,7 @@ import { section } from '../formatting.js';
 export function buildAgentDiscoveryHelp() {
     const counts = getProtocolCounts();
     return section('For AI Agents:', [
-        'bdg --help --json          Machine-readable command schema',
+        'bdg --help --json          Commands, flags, exit codes (bdg <cmd> --help --json: details)',
         `bdg cdp --list             List all ${counts.domains} CDP domains`,
         `bdg cdp --search <term>    Search ${counts.methods} CDP methods`,
     ]);