browser-debugger-cli 0.13.0 → 0.15.0

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

@@ -0,0 +1,14 @@
+/**
+ * Long values in human output: cut, with a pointer naming `--full`.
+ */
+/**
+ * A value for human output: its first `maxLength` characters followed by
+ * how many more there are, or all of it with `--full`.
+ *
+ * @param text - Value
+ * @param maxLength - Characters printed
+ * @param full - `--full`: print it whole
+ * @returns Text to print
+ */
+export declare function capForDisplay(text: string, maxLength: number, full?: boolean): string;
+//# sourceMappingURL=longValues.d.ts.map

package/dist/ui/formatters/longValues.js

@@ -0,0 +1,23 @@
+/**
+ * Long values in human output: cut, with a pointer naming `--full`.
+ */
+import { moreCharsNote } from '../messages/commands.js';
+import { capLength } from '../../utils/strings.js';
+/**
+ * A value for human output: its first `maxLength` characters followed by
+ * how many more there are, or all of it with `--full`.
+ *
+ * @param text - Value
+ * @param maxLength - Characters printed
+ * @param full - `--full`: print it whole
+ * @returns Text to print
+ */
+export function capForDisplay(text, maxLength, full) {
+    if (full)
+        return text;
+    const capped = capLength(text, maxLength);
+    return capped.truncatedFrom === undefined
+        ? text
+        : `${capped.text}${moreCharsNote(capped.truncatedFrom - capped.text.length)}`;
+}
+//# sourceMappingURL=longValues.js.map

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

@@ -5,6 +5,7 @@
  * with support for filtering results display.
  */
 import type { NetworkRequest } from '../../types.js';
+import { type NetworkEvictionCounts } from '../messages/networkMessages.js';
 export interface NetworkListOptions {
     verbose?: boolean;
     /** Start of the current page, which the START column counts from ({@link pageStartOf}) */
@@ -13,6 +14,8 @@ export interface NetworkListOptions {
     totalCount?: number;
     /** Requests matching the filters, before --last (defaults to totalCount) */
     filteredCount?: number;
+    /** Requests dropped and bodies evicted at the session's capture limits */
+    evictions?: NetworkEvictionCounts;
 }
 /**
  * When the current page started loading: the request of its document, in
@@ -41,16 +44,19 @@ export declare function pageStartOf(requests: NetworkRequest[]): PageStart | und
 export declare function formatStartOffset(request: NetworkRequest, pageStart: PageStart | undefined): string;
 /**
  * Rows of the network stream: requests that finished since the last poll,
- * with the column header the first time (the stream banner is on stderr).
+ * with the column header the first time (the stream banner is on stderr),
+ * after the dropped/evicted note when the counts changed.
  *
  * @param requests - Newly finished requests
- * @param options - `header` the first time; `verbose` for full URLs; the page start for START
+ * @param options - `header` the first time; `verbose` for full URLs; the page start for
+ *   START; `evictions` only when the session's counts changed since the last poll
  * @returns Text to print (empty when there is nothing new)
  */
 export declare function formatNetworkFollowRows(requests: NetworkRequest[], options?: {
     header?: boolean;
     verbose?: boolean;
     pageStart?: PageStart;
+    evictions?: NetworkEvictionCounts;
 }): string;
 /**
  * Format network requests for display.

package/dist/ui/formatters/networkList.js

@@ -7,6 +7,7 @@
 import { getResourceTypeAbbr } from './preview.js';
 import { getRequestState } from './requestStatus.js';
 import { OutputFormatter, truncateUrl } from '../formatting.js';
+import { networkEvictedNote } from '../messages/networkMessages.js';
 const SIZE_UNITS = ['B', 'KB', 'MB', 'GB'];
 const SEPARATOR_WIDTH = 80;
 function formatSize(bytes) {
@@ -154,6 +155,9 @@ function formatNetworkListHuman(requests, options) {
     const header = buildHeader(requests.length, options.filteredCount ?? totalCount, totalCount);
     fmt.text(header);
     fmt.separator('─', SEPARATOR_WIDTH);
+    const evictedNote = options.evictions && networkEvictedNote(options.evictions);
+    if (evictedNote)
+        fmt.text(evictedNote);
     if (requests.length === 0) {
         fmt.text('No matching requests found.');
         return fmt.build();
@@ -170,15 +174,20 @@ function formatNetworkListHuman(requests, options) {
 const FOLLOW_ID_WIDTH = 14;
 /**
  * Rows of the network stream: requests that finished since the last poll,
- * with the column header the first time (the stream banner is on stderr).
+ * with the column header the first time (the stream banner is on stderr),
+ * after the dropped/evicted note when the counts changed.
  *
  * @param requests - Newly finished requests
- * @param options - `header` the first time; `verbose` for full URLs; the page start for START
+ * @param options - `header` the first time; `verbose` for full URLs; the page start for
+ *   START; `evictions` only when the session's counts changed since the last poll
  * @returns Text to print (empty when there is nothing new)
  */
 export function formatNetworkFollowRows(requests, options = {}) {
     const fmt = new OutputFormatter();
     const widths = columnWidths(requests, FOLLOW_ID_WIDTH);
+    const evictedNote = options.evictions && networkEvictedNote(options.evictions);
+    if (evictedNote)
+        fmt.text(evictedNote);
     if (options.header) {
         fmt.text(formatColumnHeader(widths));
         fmt.separator('─', SEPARATOR_WIDTH);

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

@@ -39,6 +39,8 @@ export interface PreviewOptions {
     filteredTypes?: string[] | undefined;
     /** Total network requests before filtering (for showing feedback when no matches). */
     unfilteredNetworkCount?: number | undefined;
+    /** Console message texts whole instead of cut (`--full`). */
+    full?: boolean | undefined;
 }
 /**
  * Format preview output (peek command)
@@ -59,7 +61,8 @@ export interface PreviewJsonData {
     console?: BdgOutput['data']['console'];
 }
 /**
- * Build the JSON payload for a preview, honoring the section and `--last` filters.
+ * Build the JSON payload for a preview, honoring the section and `--last`
+ * filters; console texts are cut with `truncatedFrom` unless `--full`.
  *
  * @param output - Preview output from the daemon
  * @param options - Preview options (section filters, last N)

package/dist/ui/formatters/preview.js

@@ -1,12 +1,15 @@
-import { RESOURCE_TYPE_ABBREVIATIONS, MIME_TYPE_RULES } from '../../constants.js';
-import { buildSuccessResponse } from '../OutputBuilder.js';
-import { formatTimestamp } from './console/shared.js';
+import { MAX_CONSOLE_TEXT_LENGTH, MIME_TYPE_RULES, RESOURCE_TYPE_ABBREVIATIONS, } from '../../constants.js';
+import { buildSuccessResponse, stringifyEnvelope } from '../OutputBuilder.js';
+import { capMessageText, formatTimestamp } from './console/shared.js';
+import { capForDisplay } from './longValues.js';
 import { failureReason, formatRequestStatus, getRequestState, } from './requestStatus.js';
 import { OutputFormatter, truncateUrl, truncateText } from '../formatting.js';
-import { withPageCrashedNote } from '../messages/commands.js';
-import { PREVIEW_EMPTY_STATES, PREVIEW_HEADERS, compactTipsMessage, verboseCommandsMessage, } from '../messages/preview.js';
+import { moreCharsNote, withPageCrashedNote } from '../messages/commands.js';
 import { consoleDroppedNote } from '../messages/consoleMessages.js';
+import { networkEvictedNote } from '../messages/networkMessages.js';
+import { PREVIEW_EMPTY_STATES, PREVIEW_HEADERS, compactTipsMessage, verboseCommandsMessage, } from '../messages/preview.js';
 import { sessionCommand } from '../messages/sessionCommand.js';
+import { capLength } from '../../utils/strings.js';
 /**
  * Infer resource type from MIME type when CDP doesn't provide it.
  *
@@ -55,7 +58,8 @@ export function formatPreview(output, options) {
     return formatPreviewHumanReadable(output, options);
 }
 /**
- * Build the JSON payload for a preview, honoring the section and `--last` filters.
+ * Build the JSON payload for a preview, honoring the section and `--last`
+ * filters; console texts are cut with `truncatedFrom` unless `--full`.
  *
  * @param output - Preview output from the daemon
  * @param options - Preview options (section filters, last N)
@@ -73,7 +77,10 @@ export function buildPreviewJsonData(output, options) {
         ...(output.totals && { totals: output.totals }),
         ...(output.pageCrashedAt !== undefined && { pageCrashedAt: output.pageCrashedAt }),
         ...(pick('network') && output.data.network && { network: last(output.data.network) }),
-        ...(pick('console') && output.data.console && { console: last(output.data.console) }),
+        ...(pick('console') &&
+            output.data.console && {
+            console: last(output.data.console)?.map((message) => capMessageText(message, options.full)),
+        }),
     };
 }
 /**
@@ -81,12 +88,12 @@ export function buildPreviewJsonData(output, options) {
  *
  * @param output - Preview output
  * @param options - Preview options
- * @returns `{ version, success, data }` envelope, pretty-printed, or on one
- *   line in follow mode (one object per line, NDJSON)
+ * @returns `{ version, success, data }` envelope, indented on a terminal, and
+ *   always on one line in follow mode (one object per line, NDJSON)
  */
 function formatPreviewAsJson(output, options) {
     const envelope = buildSuccessResponse(buildPreviewJsonData(output, options));
-    return options.follow ? JSON.stringify(envelope) : JSON.stringify(envelope, null, 2);
+    return options.follow ? JSON.stringify(envelope) : stringifyEnvelope(envelope);
 }
 /**
  * Format preview as human-readable output, after a warning when the page
@@ -98,6 +105,24 @@ function formatPreviewHumanReadable(output, options) {
         : formatPreviewCompact(output, options);
     return withPageCrashedNote(body, output.pageCrashedAt);
 }
+/**
+ * A console message text in the compact preview: cut like `console --list`
+ * cuts it and to its first two lines, or whole with `--full`. The pointer
+ * naming `--full` comes after the line cut, so it is always shown.
+ *
+ * @param text - Message text
+ * @param full - `--full`
+ * @returns Text to print
+ */
+function compactConsoleText(text, full) {
+    if (full)
+        return text;
+    const capped = capLength(text, MAX_CONSOLE_TEXT_LENGTH);
+    const shown = truncateText(capped.text, 2);
+    return capped.truncatedFrom === undefined
+        ? shown
+        : `${shown}${moreCharsNote(capped.truncatedFrom - capped.text.length)}`;
+}
 /**
  * Format preview in compact format (default)
  * Token-efficient output optimized for AI agents
@@ -119,6 +144,9 @@ function formatPreviewCompact(output, options) {
             const totalCount = output.totals?.network ?? output.data.network.length;
             const limitHint = formatLimitHint(showingCount, totalCount);
             fmt.text(`NETWORK (${showingCount}/${totalCount})${limitHint}:`);
+            const evictedNote = previewEvictedNote(output);
+            if (evictedNote)
+                fmt.text(`  ${evictedNote}`);
             if (requests.length === 0) {
                 if (options.filteredTypes &&
                     options.filteredTypes.length > 0 &&
@@ -159,8 +187,7 @@ function formatPreviewCompact(output, options) {
             else {
                 const consoleLines = messages.map((msg) => {
                     const prefix = msg.type.toUpperCase().padEnd(5);
-                    const text = truncateText(msg.text, 2);
-                    return `${prefix} ${text}`;
+                    return `${prefix} ${compactConsoleText(msg.text, options.full)}`;
                 });
                 fmt.list(consoleLines, 2);
             }
@@ -172,6 +199,18 @@ function formatPreviewCompact(output, options) {
     }
     return fmt.build();
 }
+/**
+ * Note that the session dropped requests or evicted bodies at its capture limits.
+ *
+ * @param output - Preview output with its totals
+ * @returns Note text, or undefined when nothing was let go
+ */
+function previewEvictedNote(output) {
+    return networkEvictedNote({
+        requestsDropped: output.totals?.networkDropped ?? 0,
+        bodiesEvicted: output.totals?.networkBodiesEvicted ?? 0,
+    });
+}
 /**
  * Format preview in verbose format (opt-in with --verbose)
  * Original human-friendly output with Unicode formatting
@@ -198,6 +237,9 @@ function formatPreviewVerbose(output, options) {
                 ? `Network Requests (all ${requests.length})`
                 : `Network Requests (last ${requests.length} of ${output.totals?.network ?? output.data.network.length})`;
             fmt.text(title).separator('━', 50);
+            const evictedNote = previewEvictedNote(output);
+            if (evictedNote)
+                fmt.text(evictedNote);
             if (requests.length === 0) {
                 if (options.filteredTypes &&
                     options.filteredTypes.length > 0 &&
@@ -248,7 +290,7 @@ function formatPreviewVerbose(output, options) {
             else {
                 messages.forEach((msg) => {
                     const icon = msg.type === 'error' ? 'ERR' : msg.type === 'warning' ? 'WARN' : 'INFO';
-                    fmt.text(`${icon} [${msg.type}] ${msg.text}`);
+                    fmt.text(`${icon} [${msg.type}] ${capForDisplay(msg.text, MAX_CONSOLE_TEXT_LENGTH, options.full)}`);
                 });
             }
             fmt.blank();

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

@@ -1,7 +1,8 @@
 import type { RunningSessionInfo } from '../../session/sessionList.js';
 /**
- * Format the sessions as a table, followed by why ended sessions ended and
- * the cleanup commands of crashed and stale sessions.
+ * Format the sessions as a table, followed by why ended sessions ended, why
+ * untrusted sessions' directories are not safe to use, and the cleanup
+ * commands of crashed and stale sessions.
  *
  * @param data - Sessions
  * @returns Human-readable list

package/dist/ui/formatters/sessions.js

@@ -1,10 +1,11 @@
 import { OutputFormatter } from '../formatting.js';
-import { endedSessionText } from '../messages/session.js';
+import { endedSessionText, untrustedSessionText } from '../messages/session.js';
 /** Label of the default session in the list */
 const DEFAULT_SESSION_LABEL = '(default)';
 /**
- * Format the sessions as a table, followed by why ended sessions ended and
- * the cleanup commands of crashed and stale sessions.
+ * Format the sessions as a table, followed by why ended sessions ended, why
+ * untrusted sessions' directories are not safe to use, and the cleanup
+ * commands of crashed and stale sessions.
  *
  * @param data - Sessions
  * @returns Human-readable list
@@ -38,6 +39,12 @@ export function formatSessionList(data) {
     if (ended.length > 0) {
         fmt.blank().section('Ended without bdg stop:', ended);
     }
+    const untrusted = data.sessions.flatMap(({ name, untrusted: why }) => why ? [untrustedSessionText(name ?? DEFAULT_SESSION_LABEL, why)] : []);
+    if (untrusted.length > 0) {
+        fmt
+            .blank()
+            .section('Directory not safe to use (not asked; bdg status --session <name> says how to fix it):', untrusted);
+    }
     const cleanups = data.sessions.flatMap((session) => (session.cleanup ? [session.cleanup] : []));
     if (cleanups.length > 0) {
         fmt.hints('Crashed or stale sessions; clean up with:', cleanups);

package/dist/ui/formatters/status.js

@@ -2,6 +2,7 @@ import { describeRunningChrome } from '../../session/chrome.js';
 import { calculateDuration, formatTimeAgo } from '../../session/statusData.js';
 import { OutputFormatter } from '../formatting.js';
 import { colorSchemeLabel, sessionActiveLine } from '../messages/commands.js';
+import { networkEvictedNote } from '../messages/networkMessages.js';
 import { lastSessionEndText } from '../messages/session.js';
 import { noActiveSessionMessage, sessionCommand } from '../messages/sessionCommand.js';
 import { isProcessAlive } from '../../utils/process.js';
@@ -51,6 +52,12 @@ export function formatSessionStatus(metadata, pid, activity, pageState, verbose
         if (activity.lastNetworkRequestAt) {
             fmt.keyValue('  Last Request', formatTimeAgo(activity.lastNetworkRequestAt), 18);
         }
+        const evictedNote = networkEvictedNote({
+            requestsDropped: activity.networkRequestsDropped ?? 0,
+            bodiesEvicted: activity.networkBodiesEvicted ?? 0,
+        });
+        if (evictedNote)
+            fmt.text(`  ${evictedNote}`);
         fmt.keyValue('Console Messages', `${activity.consoleMessagesCaptured} captured`, 18);
         if (activity.lastConsoleMessageAt) {
             fmt.keyValue('  Last Message', formatTimeAgo(activity.lastConsoleMessageAt), 18);

package/dist/ui/formatters/triggeredRequests.js

@@ -1,6 +1,7 @@
 /**
  * Human output of the network requests a DOM action triggered.
  */
+import { MAX_TRIGGERED_REQUESTS } from '../../constants.js';
 import { assetTypeNames, isNotableRequest } from '../../telemetry/requestKinds.js';
 import { formatRequestStatus } from './requestStatus.js';
 import { formatDuration, truncateUrl } from '../formatting.js';
@@ -57,7 +58,7 @@ export function formatTriggeredRequestLines(requests, omitted = 0) {
     const lines = notable.slice(0, MAX_TRIGGERED_REQUESTS_SHOWN).map(formatTriggeredRequest);
     const hidden = notable.length - lines.length + omitted;
     if (hidden > 0)
-        lines.push(omitted > 0 ? moreRequestsNote(hidden) : moreMatchesNote(hidden));
+        lines.push(omitted > 0 ? moreRequestsNote(hidden) : moreMatchesNote(hidden, MAX_TRIGGERED_REQUESTS));
     if (assets.length > 0)
         lines.push(assetRequestsNote(assets.length, assetTypeNames(assets)));
     return lines;

package/dist/ui/messages/chrome.d.ts

@@ -20,8 +20,12 @@ export declare function formatChromeNotice(notice: NoticeDetails<ChromeNoticeCod
  * Called at the UI boundary when a ChromeLaunchError with `issue` details
  * reaches a CLI or daemon log sink. Core modules produce the IssueDetails;
  * this function is the only place wording is assembled.
+ *
+ * @param issue - Structured issue
+ * @param diagnostics - Source of Chrome installation diagnostics (tests stub it)
+ * @returns User-facing message
  */
-export declare function formatChromeIssue(issue: IssueDetails): string;
+export declare function formatChromeIssue(issue: IssueDetails, diagnostics?: () => ChromeDiagnostics): string;
 /**
  * Chrome exited before its debugging port opened.
  *
@@ -33,15 +37,19 @@ export declare function formatChromeIssue(issue: IssueDetails): string;
  */
 export declare function chromeExitedDuringStartupError(exitCode: number | null, output: string[], userDataDir: string, profileInUse: boolean): string;
 /**
- * Retrieve Chrome diagnostics and format for error messages.
- *
- * @returns Array of formatted diagnostic strings
+ * Options of {@link formatDiagnosticsForError}.
  */
-export declare function getFormattedDiagnostics(): string[];
+export interface DiagnosticsFormatOptions {
+    /** OS the CHROME_PATH example is for (default: this one) */
+    platform?: NodeJS.Platform;
+    /** Suggest CHROME_PATH when no Chrome is found (off when CHROME_PATH is the problem) */
+    suggestChromePath?: boolean;
+}
 /**
  * Format Chrome diagnostics for error reporting when Chrome launch fails.
  *
  * @param diagnostics - Chrome diagnostics information
+ * @param options - Platform of the example and whether to suggest CHROME_PATH
  * @returns Formatted error message lines with troubleshooting steps
  *
  * @example
@@ -51,7 +59,7 @@ export declare function getFormattedDiagnostics(): string[];
  * console.error(errorLines.join('\n'));
  * ```
  */
-export declare function formatDiagnosticsForError(diagnostics: ChromeDiagnostics): string[];
+export declare function formatDiagnosticsForError(diagnostics: ChromeDiagnostics, { platform, suggestChromePath }?: DiagnosticsFormatOptions): string[];
 /**
  * Generate invalid port error message.
  *
@@ -158,9 +166,28 @@ export declare function chromeBinaryOverrideIsDirectory(path: string, source: st
  * Generate error when CDP port is already in use.
  *
  * @param port - Port number that is in use
+ * @param reason - What was found on the port, when known
  * @returns Multi-line formatted error message with troubleshooting steps
  */
-export declare function portInUseError(port: number): string;
+export declare function portInUseError(port: number, reason?: string): string;
+/**
+ * Why a launched Chrome is not the one answering on 127.0.0.1:<port>.
+ *
+ * @param answeredBy - What answers there: a different browser, another
+ *   process, or nothing (the address is held but does not answer)
+ * @param chromeHost - Address the launched Chrome listens on
+ * @returns Reason for the PORT_IN_USE issue
+ */
+export declare function portTakenByReason(answeredBy: 'browser' | 'process' | 'nothing', chromeHost: string): string;
+/**
+ * Why a launch failed when Chrome announced its port but did not answer on
+ * it in time (a slow start, not a port conflict).
+ *
+ * @param port - Port Chrome announced
+ * @param waitedMs - How long bdg waited
+ * @returns Reason for the CHROME_LAUNCH_FAILED issue
+ */
+export declare function chromeNotAnsweringReason(port: number, waitedMs: number): string;
 /**
  * Warning when bdg's Chrome preferences (password manager and leak check
  * off, etc.) could not be written into the profile.

package/dist/ui/messages/chrome.js

@@ -32,12 +32,16 @@ export function formatChromeNotice(notice) {
  * Called at the UI boundary when a ChromeLaunchError with `issue` details
  * reaches a CLI or daemon log sink. Core modules produce the IssueDetails;
  * this function is the only place wording is assembled.
+ *
+ * @param issue - Structured issue
+ * @param diagnostics - Source of Chrome installation diagnostics (tests stub it)
+ * @returns User-facing message
  */
-export function formatChromeIssue(issue) {
+export function formatChromeIssue(issue, diagnostics = getChromeDiagnostics) {
     const ctx = issue.context ?? {};
     switch (issue.code) {
         case 'PORT_IN_USE':
-            return portInUseError(ctx['port']);
+            return portInUseError(ctx['port'], ctx['reason']);
         case 'INVALID_PORT':
             return invalidPortError(ctx['port']);
         case 'USER_DATA_DIR_CREATE_FAILED':
@@ -52,16 +56,18 @@ export function formatChromeIssue(issue) {
                 : reason
                     ? chromeLaunchFailedError(reason)
                     : `Chrome failed to launch`;
-            const diagnostics = getFormattedDiagnostics();
-            return joinLines(header, '', 'Possible causes:', `  - Port ${port} conflict (check: lsof -ti:${port})`, `  - Chrome binary not found`, `  - Insufficient permissions`, `  - Chrome crashed on startup`, '', ...diagnostics, '', 'Try:', `  - ${sessionCommand('bdg cleanup')}`, `  - See what uses the port: lsof -i :${port}`, `  - Use different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - In a container where Chrome's sandbox fails: BDG_NO_SANDBOX=1 ${sessionCommand('bdg <url>')}`);
+            const found = diagnostics();
+            const diagnosticLines = formatDiagnosticsForError(found);
+            if (noChromeFound(found))
+                return joinLines(header, '', ...diagnosticLines);
+            return joinLines(header, '', 'Possible causes:', `  - Port ${port} conflict (check: lsof -ti:${port})`, `  - Chrome binary not found`, `  - Insufficient permissions`, `  - Chrome crashed on startup`, '', ...diagnosticLines, '', 'Try:', `  - ${sessionCommand('bdg cleanup')}`, `  - See what uses the port: lsof -i :${port}`, `  - Use different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - In a container where Chrome's sandbox fails: BDG_NO_SANDBOX=1 ${sessionCommand('bdg <url>')}`);
         }
         case 'CHROME_EXITED_DURING_STARTUP':
             return chromeExitedDuringStartupError(ctx['exitCode'], ctx['output'] ?? [], ctx['userDataDir'], ctx['profileInUse'] === true);
         case 'NO_PAGE_TARGET_FOUND':
             return noPageTargetFoundError(ctx['port'], ctx['availableTargets']);
         case 'CHROME_BINARY_NOT_FOUND': {
-            const diagnostics = getFormattedDiagnostics();
-            return joinLines(chromeBinaryOverrideNotFound(ctx['chromePath'], ctx['source']), '', ...diagnostics);
+            return joinLines(chromeBinaryOverrideNotFound(ctx['chromePath'], ctx['source']), '', ...formatDiagnosticsForError(diagnostics(), { suggestChromePath: false }));
         }
         case 'CHROME_BINARY_IS_DIRECTORY':
             return chromeBinaryOverrideIsDirectory(ctx['chromePath'], ctx['source']);
@@ -96,17 +102,49 @@ export function chromeExitedDuringStartupError(exitCode, output, userDataDir, pr
     return joinLines(`Chrome exited during startup (exit code ${exitCode ?? 'none'})`, ...(output.length > 0 ? ['Chrome said:', ...output.map((line) => `  ${line}`)] : []), 'Check --chrome-flags and BDG_CHROME_FLAGS (an unknown flag or value can stop Chrome)');
 }
 /**
- * Retrieve Chrome diagnostics and format for error messages.
+ * Whether no Chrome was found at all: no installation and no default binary
+ * (chrome-launcher's default honors a valid CHROME_PATH).
+ *
+ * @param diagnostics - Chrome diagnostics
+ * @returns True when there is nothing to launch
+ */
+function noChromeFound(diagnostics) {
+    return diagnostics.installationCount === 0 && !diagnostics.defaultPath;
+}
+/**
+ * A Chromium-based browser binary that chrome-launcher does not find on its
+ * own, as an example value for CHROME_PATH.
+ *
+ * @param platform - OS the path is for
+ * @returns Microsoft Edge's binary on macOS or Linux; none on other systems
+ */
+function exampleChromePath(platform) {
+    if (platform === 'darwin')
+        return '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge';
+    if (platform === 'linux')
+        return '/usr/bin/microsoft-edge';
+    return undefined;
+}
+/**
+ * How to point bdg at another Chromium-based browser through CHROME_PATH.
  *
- * @returns Array of formatted diagnostic strings
+ * @param platform - OS the example is for
+ * @returns Message lines, with an example command where one is known
  */
-export function getFormattedDiagnostics() {
-    return formatDiagnosticsForError(getChromeDiagnostics());
+function chromePathSuggestion(platform) {
+    const example = exampleChromePath(platform);
+    if (!example)
+        return ['Set CHROME_PATH to a Chromium-based browser (Edge, Brave, Chromium)\n'];
+    return [
+        'Set CHROME_PATH to a Chromium-based browser (Edge, Brave, Chromium), e.g.:',
+        `   CHROME_PATH="${example}" ${sessionCommand('bdg <url>')}\n`,
+    ];
 }
 /**
  * Format Chrome diagnostics for error reporting when Chrome launch fails.
  *
  * @param diagnostics - Chrome diagnostics information
+ * @param options - Platform of the example and whether to suggest CHROME_PATH
  * @returns Formatted error message lines with troubleshooting steps
  *
  * @example
@@ -116,11 +154,13 @@ export function getFormattedDiagnostics() {
  * console.error(errorLines.join('\n'));
  * ```
  */
-export function formatDiagnosticsForError(diagnostics) {
+export function formatDiagnosticsForError(diagnostics, { platform = process.platform, suggestChromePath = true } = {}) {
     const lines = [];
-    if (diagnostics.installationCount === 0) {
+    if (noChromeFound(diagnostics)) {
         lines.push('Error: No Chrome installations detected\n');
-        lines.push('Install Chrome from:');
+        if (suggestChromePath)
+            lines.push(...chromePathSuggestion(platform));
+        lines.push(suggestChromePath ? 'Or install Chrome from:' : 'Install Chrome from:');
         lines.push('   https://www.google.com/chrome/\n');
     }
     else {
@@ -274,10 +314,36 @@ export function chromeBinaryOverrideIsDirectory(path, source) {
  * Generate error when CDP port is already in use.
  *
  * @param port - Port number that is in use
+ * @param reason - What was found on the port, when known
  * @returns Multi-line formatted error message with troubleshooting steps
  */
-export function portInUseError(port) {
-    return joinLines(`Port ${port} is already in use.\n`, 'Another program (or a Chrome left from a previous session) is listening on it.\n', 'Try:', `  - Use a different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - If a bdg session holds it: find it with bdg sessions, then end that one: bdg stop --session <name> (bdg cleanup --force --session <name> if it is stuck)`, `  - See what uses the port: lsof -i :${port}`);
+export function portInUseError(port, reason) {
+    return joinLines(reason ? `Port ${port} is already in use: ${reason}.\n` : `Port ${port} is already in use.\n`, 'Another program (or a Chrome left from a previous session) is listening on it.\n', 'Try:', `  - Use a different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - If a bdg session holds it: find it with bdg sessions, then end that one: bdg stop --session <name> (bdg cleanup --force --session <name> if it is stuck)`, `  - See what uses the port: lsof -i :${port}`);
+}
+/**
+ * Why a launched Chrome is not the one answering on 127.0.0.1:<port>.
+ *
+ * @param answeredBy - What answers there: a different browser, another
+ *   process, or nothing (the address is held but does not answer)
+ * @param chromeHost - Address the launched Chrome listens on
+ * @returns Reason for the PORT_IN_USE issue
+ */
+export function portTakenByReason(answeredBy, chromeHost) {
+    if (answeredBy === 'nothing')
+        return `something holds 127.0.0.1 (Chrome fell back to ${chromeHost})`;
+    const other = answeredBy === 'browser' ? 'another browser' : 'another process';
+    return `${other} answers on 127.0.0.1 (Chrome listens on ${chromeHost})`;
+}
+/**
+ * Why a launch failed when Chrome announced its port but did not answer on
+ * it in time (a slow start, not a port conflict).
+ *
+ * @param port - Port Chrome announced
+ * @param waitedMs - How long bdg waited
+ * @returns Reason for the CHROME_LAUNCH_FAILED issue
+ */
+export function chromeNotAnsweringReason(port, waitedMs) {
+    return `Chrome announced port ${port} but did not answer on 127.0.0.1 within ${(waitedMs / 1000).toFixed(1)}s (slow start)`;
 }
 /**
  * Warning when bdg's Chrome preferences (password manager and leak check

package/dist/ui/messages/commands.d.ts

@@ -134,14 +134,13 @@ export declare function valueMismatchWarning(mismatch: FillValueMismatch): strin
  */
 export declare const CLICK_NOT_RECEIVED_WARNING = "The click may not have reached the element: the page saw no mouse press (the browser may be showing a dialog or bubble that captures input)";
 /**
- * Note under a shortened list of matches.
+ * Note under a shortened human list whose JSON output lists more, up to a cap.
  *
- * @param hidden - Matches not listed
- * @param jsonLimit - How many JSON output lists, when it leaves some out too
- * @returns e.g. "... and 1174 more (use --json for all)",
- *   "... and 8980 more (--json lists the first 100)"
+ * @param hidden - Items not listed
+ * @param jsonLimit - Most items the JSON output lists
+ * @returns e.g. "... and 8980 more (--json lists up to 100)"
  */
-export declare function moreMatchesNote(hidden: number, jsonLimit?: number): string;
+export declare function moreMatchesNote(hidden: number, jsonLimit: number): string;
 /**
  * Note under `dom query` matches cut by `--limit`.
  *
@@ -158,6 +157,20 @@ export declare function queryMoreMatchesNote(omitted: number, indexed?: number):
  * @returns e.g. `Visibility is checked for the first 100 matches only; bdg dom layout <index> checks any of them`
  */
 export declare function queryViewportCheckedNote(checked: number): string;
+/**
+ * First line under an accessibility tree cut by `--limit` or `--depth`.
+ *
+ * @param listed - Nodes listed
+ * @returns e.g. "Showing the first 50 nodes (text boxes and repeated text left out)"
+ */
+export declare function a11yTreeShownNote(listed: number): string;
+/**
+ * How to see the rest of an accessibility tree cut by `--limit` or `--depth`.
+ *
+ * @param omitted - Nodes left out
+ * @returns e.g. "51391 more: --limit 0 lists all, --depth <n> limits the levels, or search with bdg dom a11y query \"role:<role>\""
+ */
+export declare function a11yTreeMoreNote(omitted: number): string;
 /**
  * Note under a list of a11y query matches cut by `--limit`.
  *
@@ -362,10 +375,11 @@ export declare function coverText(cover: string, transparent: boolean | undefine
  * Note when `bdg dom inspect` could not read the element's matched rules, so
  * no hints, rules or why were computed.
  *
- * @param reason - `timeout` (very large stylesheets) or `failed` (Chrome reported an error)
+ * @param reason - `timeout` (very large stylesheets), `failed` (Chrome reported
+ *   an error) or `skipped` (hints not read: an earlier read on this page timed out)
  * @returns Note
  */
-export declare function inspectCascadeNote(reason: 'timeout' | 'failed'): string;
+export declare function inspectCascadeNote(reason: 'timeout' | 'failed' | 'skipped'): string;
 /**
  * Note of `bdg dom inspect` when the selector named a pseudo-element: its
  * element is inspected and the pseudo-element is on the `pseudo` line.
@@ -835,5 +849,12 @@ export declare const CSS_SEARCH_HELP_EXAMPLES = "\nExamples:\n  bdg css search -
  * @returns Note
  */
 export declare function helpJsonDetailsNote(): string;
+/**
+ * Pointer after a value cut for human output.
+ *
+ * @param count - Characters left out
+ * @returns e.g. `… 299800 more chars (use --full)`
+ */
+export declare function moreCharsNote(count: number): string;
 export {};
 //# sourceMappingURL=commands.d.ts.map