browser-debugger-cli 0.12.0 → 0.14.0

package/dist/ui/formatters/preview.js

@@ -1,10 +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 { 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.
  *
@@ -53,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)
@@ -69,8 +75,12 @@ export function buildPreviewJsonData(output, options) {
         target: output.target,
         ...(output.partial !== undefined && { partial: output.partial }),
         ...(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)),
+        }),
     };
 }
 /**
@@ -78,19 +88,40 @@ export function buildPreviewJsonData(output, options) {
  *
  * @param output - Preview output
  * @param options - Preview options
- * @returns Pretty-printed `{ version, success, data }` envelope
+ * @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) {
-    return JSON.stringify(buildSuccessResponse(buildPreviewJsonData(output, options)), null, 2);
+    const envelope = buildSuccessResponse(buildPreviewJsonData(output, options));
+    return options.follow ? JSON.stringify(envelope) : stringifyEnvelope(envelope);
 }
 /**
- * Format preview as human-readable output
+ * Format preview as human-readable output, after a warning when the page
+ * crashed (what is shown was collected before).
  */
 function formatPreviewHumanReadable(output, options) {
-    if (options.verbose) {
-        return formatPreviewVerbose(output, options);
-    }
-    return formatPreviewCompact(output, options);
+    const body = options.verbose
+        ? formatPreviewVerbose(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)
@@ -113,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 &&
@@ -145,14 +179,15 @@ function formatPreviewCompact(output, options) {
             const totalCount = output.totals?.console ?? output.data.console.length;
             const limitHint = formatLimitHint(showingCount, totalCount);
             fmt.text(`CONSOLE (${showingCount}/${totalCount})${limitHint}:`);
+            if (output.totals?.consoleDropped)
+                fmt.text(`  ${consoleDroppedNote(output.totals.consoleDropped)}`);
             if (messages.length === 0) {
                 fmt.text(`  ${PREVIEW_EMPTY_STATES.NO_DATA}`);
             }
             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);
             }
@@ -164,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
@@ -190,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 &&
@@ -232,13 +282,15 @@ function formatPreviewVerbose(output, options) {
                 ? `Console Messages (all ${messages.length})`
                 : `Console Messages (last ${messages.length} of ${output.totals?.console ?? output.data.console.length})`;
             fmt.text(title).separator('━', 50);
+            if (output.totals?.consoleDropped)
+                fmt.text(consoleDroppedNote(output.totals.consoleDropped));
             if (messages.length === 0) {
                 fmt.text(PREVIEW_EMPTY_STATES.NO_CONSOLE_MESSAGES);
             }
             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,7 @@
 import type { RunningSessionInfo } from '../../session/sessionList.js';
 /**
- * Format the sessions as a table, followed by the cleanup commands of
- * crashed and stale sessions.
+ * Format the sessions as a table, followed by why ended sessions ended and
+ * the cleanup commands of crashed and stale sessions.
  *
  * @param data - Sessions
  * @returns Human-readable list

package/dist/ui/formatters/sessions.js

@@ -1,9 +1,10 @@
 import { OutputFormatter } from '../formatting.js';
+import { endedSessionText } 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 the cleanup commands of
- * crashed and stale sessions.
+ * Format the sessions as a table, followed by why ended sessions ended and
+ * the cleanup commands of crashed and stale sessions.
  *
  * @param data - Sessions
  * @returns Human-readable list
@@ -31,6 +32,12 @@ export function formatSessionList(data) {
             .join('  ')
             .trimEnd());
     }
+    const ended = data.sessions.flatMap(({ name, endReason, endedAt }) => endReason && endedAt !== undefined
+        ? [endedSessionText(name ?? DEFAULT_SESSION_LABEL, { reason: endReason, endedAt })]
+        : []);
+    if (ended.length > 0) {
+        fmt.blank().section('Ended without bdg stop:', ended);
+    }
     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/logging/logger.d.ts

@@ -29,7 +29,7 @@ export type LogLevel = 'info' | 'debug';
  * Log contexts for different components.
  * Used to prefix log messages with component name.
  */
-export type LogContext = 'bdg' | 'launcher' | 'daemon' | 'client' | 'cleanup' | 'session' | 'chrome' | 'cdp' | 'ipc' | 'http' | 'dialogs' | 'navigation' | 'console' | 'dom' | 'network' | 'diagnostics' | 'readiness' | 'atomic-file' | 'object-expander' | 'fetcher' | 'targets';
+export type LogContext = 'bdg' | 'launcher' | 'daemon' | 'client' | 'cleanup' | 'session' | 'chrome' | 'cdp' | 'ipc' | 'http' | 'dialogs' | 'navigation' | 'page-crash' | 'console' | 'dom' | 'network' | 'diagnostics' | 'readiness' | 'atomic-file' | 'object-expander' | 'fetcher' | 'targets';
 /**
  * Logger instance with support for different log levels.
  */

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

@@ -158,9 +158,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

@@ -37,7 +37,7 @@ export function formatChromeIssue(issue) {
     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':
@@ -274,10 +274,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

@@ -24,6 +24,13 @@ export declare function chromeClosedMessage(pid?: number): string;
  * @returns Formatted success message
  */
 export declare function orphanedDaemonsCleanedMessage(count: number): string;
+/**
+ * Where `bdg install-skill` kept the copy it replaced.
+ *
+ * @param path - Backup path, as the user would type it
+ * @returns One line
+ */
+export declare function skillBackupMessage(path: string): string;
 /**
  * Warning shown when a click falls back from mouse events to `el.click()`.
  *
@@ -127,14 +134,43 @@ 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 - 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;
+/**
+ * Note under `dom query` matches cut by `--limit`.
+ *
+ * @param omitted - Matches not listed
+ * @param indexed - Matches usable by index, when not all of them
+ * @returns e.g. `... and 49953 more (--limit 0 lists all; indices 0-999 work with other commands)`
+ */
+export declare function queryMoreMatchesNote(omitted: number, indexed?: number): string;
+/**
+ * Note under `dom query` matches listed past those whose viewport position
+ * was checked.
+ *
+ * @param checked - First matches checked
+ * @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 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 listed - Nodes listed
+ * @returns e.g. "Showing the first 50 nodes (text boxes and repeated text left out)"
  */
-export declare function moreMatchesNote(hidden: number, jsonLimit?: number): string;
+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`.
  *
@@ -185,6 +221,31 @@ export declare const LAYOUT_REASONS: {
     /** Joins an invisible reason to the ancestor causing it */
     readonly on: " on ";
 };
+/** Why an out-of-view text's contrast in `dom audit` is approximate: none of its ancestors paints a background */
+export declare const AUDIT_OUT_OF_VIEW_RISK = "only its ancestors were checked";
+/**
+ * `dom audit contrast` note for text that looks below the level but cannot
+ * be measured exactly (over an image, blended, under or over another layer).
+ *
+ * @param count - How many such texts
+ * @returns e.g. `(+12 more may be below it but cannot be measured: text over images or blended layers; check them with bdg dom inspect)`
+ */
+export declare function auditUncertainContrastNote(count: number): string;
+/**
+ * `dom audit animations` note for canvas elements, whose script-drawn
+ * animations it cannot see.
+ *
+ * @param count - Visible canvas elements
+ * @returns e.g. `(+ 2 canvas elements: animations drawn by scripts on them are not listed)`
+ */
+export declare function auditCanvasNote(count: number): string;
+/**
+ * A mask over an element, for `dom layout` and `dom inspect`.
+ *
+ * @param masked - The mask, e.g. `mask-image on div.hero`
+ * @returns e.g. `masked by mask-image on div.hero`
+ */
+export declare function maskedText(masked: string): string;
 /**
  * Off-screen reason for an element out of view on a page whose scrolling is
  * locked, naming the visible dialog that likely locked it when there is one.
@@ -228,16 +289,53 @@ export declare function layoutPositionLabel(element: LabelledLayout, viewport?:
  * @returns e.g. `prefers-color-scheme: dark (from the system setting)`
  */
 export declare function colorSchemeLabel(scheme: string, emulated: boolean): string;
+/**
+ * Suggestion for an action that failed on a page that replaced built-ins
+ * bdg's page scripts use.
+ *
+ * @param replaced - Their dotted names (all are named)
+ * @returns Suggestion naming them and a way around
+ */
+export declare function brokenByReplacedBuiltinsSuggestion(replaced: readonly string[]): string;
+/**
+ * Warning on an action when the page replaced built-ins bdg's page scripts
+ * use (polyfills, old frameworks, anti-bot scripts). Names the first four;
+ * the action's `replacedBuiltins` (JSON) lists them all.
+ *
+ * @param replaced - Their dotted names
+ * @returns e.g. `the page replaced built-ins bdg's scripts use (Element.prototype.querySelectorAll); bdg found the element in its own world, but the action runs in the page's and may misbehave`
+ */
+export declare function replacedBuiltinsWarning(replaced: readonly string[]): string;
 /**
  * First line of `bdg status` for a running session.
  *
- * @param page - URL and title of the page, when the session reported them
- * @returns e.g. `Session active: https://example.com/ — Example Domain`
+ * @param page - URL and title of the page, when the session reported them,
+ *   and when it crashed
+ * @returns e.g. `Session active: https://example.com/ — Example Domain`, with
+ *   a crash warning on a second line
  */
 export declare function sessionActiveLine(page?: {
     url: string;
     title: string;
+    crashedAt?: number | undefined;
 }): string;
+/**
+ * Warning that the session's page crashed, for `bdg status`, `bdg peek`,
+ * `bdg console` and `bdg network list`.
+ *
+ * @param crashedAt - When it crashed (epoch ms)
+ * @returns e.g. `⚠ The page crashed at 18:42:10 (renderer gone); bdg page reload brings it back`
+ */
+export declare function pageCrashedNote(crashedAt: number): string;
+/**
+ * Put the page-crashed warning before a view of collected data, when the
+ * page crashed (what is shown was collected before).
+ *
+ * @param body - The view
+ * @param crashedAt - When the page crashed (epoch ms), if it did
+ * @returns The view, after the warning when the page crashed
+ */
+export declare function withPageCrashedNote(body: string, crashedAt: number | undefined): string;
 /**
  * Page dimensions line of `bdg dom layout`.
  *
@@ -277,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.
@@ -405,6 +504,16 @@ export declare function dialogConsoleText(dialog: {
     type: string;
     message: string;
 }): string;
+/**
+ * How far a pointer action scrolled the page to reach its element.
+ *
+ * @param scrolledBy - Page scroll (CSS px)
+ * @returns e.g. `page down 1240px to reach it`, `page right 300px, up 80px to reach it`
+ */
+export declare function pointerScrollText(scrolledBy: {
+    x: number;
+    y: number;
+}): string;
 /** Headline of each pointer action, e.g. "Element Double-clicked" */
 export declare const POINTER_ACTION_DONE: {
     readonly click: "Clicked";
@@ -556,9 +665,11 @@ export declare function elementTextLine(text: string): string;
  *
  * @param children - First child elements, e.g. `iframe#app`
  * @param count - Number of child elements
- * @returns e.g. `No text; holds 1 element: iframe (see its HTML with --raw)`
+ * @param inShadowRoot - The children are those of its shadow root (`--raw` does not show them)
+ * @returns e.g. `No text; holds 1 element: iframe (see its HTML with --raw)`,
+ *   `No text; its shadow root holds 1 element: button "Close" (see it with bdg dom inspect)`
  */
-export declare function emptyElementLine(children: string[], count: number): string;
+export declare function emptyElementLine(children: string[], count: number, inShadowRoot?: boolean): string;
 /**
  * Note on a screenshot scaled down to keep its image token cost bounded.
  *
@@ -600,6 +711,23 @@ export declare function queryNextSteps(index: number): string;
  * @returns e.g. `Frame: https://pay.example/`
  */
 export declare function evalFrameLine(url: string): string;
+/**
+ * Warning on a `dom eval` result the browser copied because the page
+ * replaced built-ins bdg's own copy uses.
+ *
+ * @param replaced - Their dotted names (all are named)
+ * @returns e.g. `the page replaced Object.keys, so the browser copied the result: undefined, NaN, functions, DOM nodes, dates, maps and sets inside it show as null or {}`
+ */
+export declare function evalCopiedByBrowserWarning(replaced: readonly string[]): string;
+/**
+ * Warning on a `dom eval` result shown as its preview: the page replaced
+ * built-ins bdg's copy uses and the browser could not copy it either (a
+ * cycle or a BigInt inside).
+ *
+ * @param replaced - Their dotted names (all are named)
+ * @returns Warning that the value is a shortened preview
+ */
+export declare function evalPreviewWarning(replaced: readonly string[]): string;
 /**
  * Generate warning message.
  *
@@ -715,5 +843,18 @@ export declare function inspectMidTransitionNote(): string;
 export declare const AUDIT_HELP_EXAMPLES = "\nExamples:\n  bdg dom audit                       All checks\n  bdg dom audit contrast --level AAA  Text below WCAG AAA, weakest first\n  bdg dom audit overflow              What scrolls sideways, cut-off text, scaled images\n  bdg dom audit layers animations     Fixed/sticky elements and running animations\n\nFollow up on a finding with bdg dom inspect <element> (e.g. --why color).";
 /** Examples under `bdg css search --help` */
 export declare const CSS_SEARCH_HELP_EXAMPLES = "\nExamples:\n  bdg css search -- --brand       Where a custom property is set and used (-- before a text\n                                  that starts with -; options go before it:\n                                  bdg css search --limit 50 -- --brand)\n  bdg css search \"oklch(\"         Rules that use oklch colors\n  bdg css search \".btn-primary\"   Rules of a class, in every stylesheet";
+/**
+ * `details` field of `bdg --help --json`: where the full help is.
+ *
+ * @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