browser-debugger-cli 0.11.0 → 0.13.0

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()`.
  *
@@ -94,6 +101,17 @@ export declare function shownElementText(element: ShownElement): string;
  *   "URL changed to https://example.com/#/active (same document)"
  */
 export declare function pageNavigationText(navigation: PageNavigation): string;
+/**
+ * Last `New text:` row when an action made more messages appear than are listed.
+ *
+ * @param count - Messages not listed
+ * @returns e.g. `(+4 more)`
+ */
+export declare function moreMessagesText(count: number): string;
+/** Result line of `bdg dom hover --off` */
+export declare const HOVER_OFF_DONE = "\u2713 Mouse moved off the page (hover styles and menus that close on mouseleave are gone)";
+/** How `bdg dom hover` is called */
+export declare const HOVER_USAGE = "bdg dom hover <selector|index>, or bdg dom hover --off to move the mouse away";
 /**
  * A message an action made appear, for its `New text:` rows.
  *
@@ -124,6 +142,22 @@ export declare const CLICK_NOT_RECEIVED_WARNING = "The click may not have reache
  *   "... and 8980 more (--json lists the first 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;
 /**
  * Note under a list of a11y query matches cut by `--limit`.
  *
@@ -174,6 +208,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.
@@ -217,16 +276,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`.
  *
@@ -252,7 +348,7 @@ export declare function layoutHeadline(count: number, listed: number, selector:
  */
 export declare function indexLayoutHeadline(target: string): string;
 /** Help text explaining `bdg dom inspect`'s output notation */
-export declare const INSPECT_OUTPUT_LEGEND = "\nOutput notation:\n  WxH @x,y        rendered border box size and page position (CSS px, no unit)\n  m / p / b       margin / padding / border widths, 1-4 values in CSS order (top right bottom left)\n  in-parent       distances to the parent's content edges (l t r b); sib: gaps to the sibling on each side\n  scroll WxH      the content (pseudo-elements too) is larger than the box\n  16/24           font size / line height; 'webfont loaded' = drawn with a downloaded font;\n                  (rendered \"X\") = drawn with another font than declared (a fallback)\n  contrast 4.47   WCAG ratio, rounded down, against the background behind the text\n  (+N not rendered)  children with display: none (or not in the layout)\n  hints           declarations on this element that have no effect, why, the fix and where they are\n                  ('none': checked, nothing found)\n  \u2190 sel (file:N)  --rules: the declaration that sets the value (file:line, or file:line:column in\n                  minified files); 'over X': rules it beats; '= v': the value of a var() expression\n  \u2713 / \u2717           --why: the winning declaration / ones it beats, highest precedence first;\n                  [0,2,0]: selector specificity (ids, classes, types); indented --name lines: where\n                  the winner's custom properties are set\nSessions follow the system color scheme; start with --color-scheme light|dark to choose.";
+export declare const INSPECT_OUTPUT_LEGEND = "\nOutput notation:\n  WxH @x,y        rendered border box size and page position (CSS px, no unit)\n  m / p / b       margin / padding / border widths, 1-4 values in CSS order (top right bottom left)\n  in-parent       distances to the parent's content edges (l t r b); sib: gaps to the sibling on each side\n  scroll WxH      the content (pseudo-elements too) is larger than the box\n  16/24           font size / line height; 'webfont loaded' = drawn with a downloaded font;\n                  (rendered \"X\") = drawn with another font than declared (a fallback);\n                  (resolves to \"X\") = the font a generic family (sans-serif, system-ui) became\n  contrast 4.47   WCAG ratio, rounded down, against the background behind the text\n  text in X       the text is drawn by descendant X (the one with most of it): its font, color, contrast\n  truncated       the text is cut off (overflow clip, ellipsis or line clamp); a \"\u2026\" in the header is\n                  only bdg shortening the text\n  .a.b(+3)        the first two classes and how many more the element has\n  sizing content-box  padding and border add to the CSS size (shown only then; border-box is not)\n  (+N not rendered)  children with display: none (or not in the layout)\n  hints           declarations on this element that have no effect, why, the fix and where they are\n                  ('none': checked, nothing found)\n  \u2190 sel (file:N)  --rules: the declaration that sets the value (file:line, or file:line:column in\n                  minified files); 'over X': rules it beats; '= v': the value of a var() expression\n  \u2713 / \u2717           --why: the winning declaration / ones it beats, highest precedence first;\n                  [0,2,0]: selector specificity (ids, classes, types); indented --name lines: where\n                  the winner's custom properties are set\nSessions follow the system color scheme; start with --color-scheme light|dark to choose.";
 /**
  * What covers an element: a cover that paints nothing at that point (a
  * transparent box over it) does not hide it, but takes its clicks.
@@ -270,14 +366,24 @@ export declare function coverText(cover: string, transparent: boolean | undefine
  * @returns Note
  */
 export declare function inspectCascadeNote(reason: 'timeout' | 'failed'): 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.
+ *
+ * @param pseudo - `::before` or `::after`
+ * @returns Note
+ */
+export declare function inspectPseudoOfNote(pseudo: string): string;
 /**
  * Header badge of `bdg dom inspect` when the page is shown in its dark theme
- * because the session follows the system's dark preference: the colors are
- * the dark theme's, not what a light-mode visitor sees.
+ * because the session follows the system's dark preference, or because
+ * `page emulate` asked for dark: the colors are the dark theme's, not what a
+ * light-mode visitor sees.
  *
+ * @param emulated - The dark preference comes from `page emulate --color-scheme dark`
  * @returns Badge
  */
-export declare function inspectDarkThemeBadge(): string;
+export declare function inspectDarkThemeBadge(emulated?: boolean): string;
 /**
  * Header badges of `bdg dom inspect` for what keeps an element from being seen.
  *
@@ -384,6 +490,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";
@@ -535,16 +651,29 @@ 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.
+ *
+ * @param originalWidth - Captured width (CSS px)
+ * @param originalHeight - Captured height
+ * @param width - Image width
+ * @param height - Image height
+ * @returns e.g. `scaled from 1920×993 to 1568×811; --no-resize for full size`
+ */
+export declare function screenshotScaledNote(originalWidth: number, originalHeight: number, width: number, height: number): string;
 /**
  * Note on an element screenshot that captured more than the element's border
- * box, because content (floats, positioned children) overflows it.
+ * box, because content (floats, positioned children, text, shadows) overflows it.
  *
  * @param box - Border box
  * @param captured - Area captured
- * @returns e.g. `grown from 940×37 to 940×285 to include content overflowing the element`
+ * @param padding - `--padding` (px), which is not the element's own
+ * @returns e.g. `grown from 940×37 to 940×285 to include what it paints outside its box (…)`
  */
 export declare function screenshotGrownNote(box: {
     width: number;
@@ -552,7 +681,7 @@ export declare function screenshotGrownNote(box: {
 }, captured: {
     width: number;
     height: number;
-}): string;
+}, padding?: number): string;
 /**
  * Next commands after `bdg dom query`, by index so they reach matches in
  * shadow roots and iframes too.
@@ -568,6 +697,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.
  *
@@ -655,6 +801,7 @@ export declare function pageEmulationLines(result: {
         viewport?: {
             width: number;
             height: number;
+            mobile?: boolean;
         };
         colorScheme?: string;
     };
@@ -678,5 +825,15 @@ export declare function inspectAnimatingBadge(animating: readonly string[]): str
  * @returns Note
  */
 export declare function inspectMidTransitionNote(): string;
+/** Examples under `bdg dom audit --help` */
+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;
 export {};
 //# sourceMappingURL=commands.d.ts.map

package/dist/ui/messages/commands.js

@@ -26,6 +26,15 @@ export function chromeClosedMessage(pid) {
 export function orphanedDaemonsCleanedMessage(count) {
     return `Cleaned up ${count} orphaned daemon process${count === 1 ? '' : 'es'}`;
 }
+/**
+ * Where `bdg install-skill` kept the copy it replaced.
+ *
+ * @param path - Backup path, as the user would type it
+ * @returns One line
+ */
+export function skillBackupMessage(path) {
+    return `previous copy kept in ${path}`;
+}
 /**
  * Warning shown when a click falls back from mouse events to `el.click()`.
  *
@@ -136,6 +145,19 @@ export function pageNavigationText(navigation) {
     const status = navigation.status === undefined ? '' : ` (${navigation.status})`;
     return `navigated to ${navigation.url}${status}`;
 }
+/**
+ * Last `New text:` row when an action made more messages appear than are listed.
+ *
+ * @param count - Messages not listed
+ * @returns e.g. `(+4 more)`
+ */
+export function moreMessagesText(count) {
+    return `(+${count} more)`;
+}
+/** Result line of `bdg dom hover --off` */
+export const HOVER_OFF_DONE = '✓ Mouse moved off the page (hover styles and menus that close on mouseleave are gone)';
+/** How `bdg dom hover` is called */
+export const HOVER_USAGE = 'bdg dom hover <selector|index>, or bdg dom hover --off to move the mouse away';
 /**
  * A message an action made appear, for its `New text:` rows.
  *
@@ -182,6 +204,27 @@ export function moreMatchesNote(hidden, jsonLimit) {
     const where = jsonLimit === undefined ? 'use --json for all' : `--json lists the first ${jsonLimit}`;
     return `... and ${hidden} more (${where})`;
 }
+/**
+ * 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 function queryMoreMatchesNote(omitted, indexed) {
+    const indices = indexed === undefined ? '' : `; indices 0-${indexed - 1} work with other commands`;
+    return `... and ${omitted} more (--limit 0 lists all${indices})`;
+}
+/**
+ * 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 function queryViewportCheckedNote(checked) {
+    return `Visibility is checked for the first ${checked} matches only; ${sessionCommand('bdg dom layout <index>')} checks any of them`;
+}
 /**
  * Note under a list of a11y query matches cut by `--limit`.
  *
@@ -240,6 +283,37 @@ export const LAYOUT_REASONS = {
     /** Joins an invisible reason to the ancestor causing it */
     on: ' on ',
 };
+/** Why an out-of-view text's contrast in `dom audit` is approximate: none of its ancestors paints a background */
+export 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 function auditUncertainContrastNote(count) {
+    return `(+${count} more may be below it but cannot be measured: text over images or blended layers; check them with ${sessionCommand('bdg dom inspect <element>')})`;
+}
+/**
+ * `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 function auditCanvasNote(count) {
+    return `(+ ${count} canvas ${count === 1 ? 'element' : 'elements'}: animations drawn by scripts on ${count === 1 ? 'it are' : 'them are'} not listed)`;
+}
+/**
+ * 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 function maskedText(masked) {
+    return `masked by ${masked}`;
+}
 /** Start of the off-screen reason of an element a scroll-locked page hides ({@link scrollLockedReason}) */
 const SCROLL_LOCKED_PREFIX = 'page scrolling is locked';
 /**
@@ -378,16 +452,63 @@ export function colorSchemeLabel(scheme, emulated) {
     const source = emulated ? 'emulated' : 'from the system setting';
     return `prefers-color-scheme: ${scheme} (${source})`;
 }
+/**
+ * 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 function brokenByReplacedBuiltinsSuggestion(replaced) {
+    return `The page replaced built-ins bdg's action script uses (${replaced.join(', ')}), which may have broken it; if so, act on the element with ${sessionCommand("bdg dom eval '…'")} instead`;
+}
+/**
+ * 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 function replacedBuiltinsWarning(replaced) {
+    const shown = replaced.slice(0, 4).join(', ') +
+        (replaced.length > 4 ? `, +${replaced.length - 4} more (see --json)` : '');
+    return `the page replaced built-ins bdg's scripts use (${shown}); bdg found the element in its own world, but the action runs in the page's and may misbehave`;
+}
 /**
  * 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 function sessionActiveLine(page) {
     if (!page)
         return 'Session active';
-    return `Session active: ${page.url}${page.title ? ` — ${page.title}` : ''}`;
+    const line = `Session active: ${page.url}${page.title ? ` — ${page.title}` : ''}`;
+    return page.crashedAt === undefined ? line : `${line}\n${pageCrashedNote(page.crashedAt)}`;
+}
+/**
+ * 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 function pageCrashedNote(crashedAt) {
+    return `⚠ The page crashed at ${new Date(crashedAt).toLocaleTimeString()} (renderer gone); ${sessionCommand('bdg page reload')} brings it back`;
+}
+/**
+ * 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 function withPageCrashedNote(body, crashedAt) {
+    return crashedAt === undefined ? body : `${pageCrashedNote(crashedAt)}\n\n${body}`;
 }
 /**
  * Page dimensions line of `bdg dom layout`.
@@ -432,8 +553,14 @@ Output notation:
   in-parent       distances to the parent's content edges (l t r b); sib: gaps to the sibling on each side
   scroll WxH      the content (pseudo-elements too) is larger than the box
   16/24           font size / line height; 'webfont loaded' = drawn with a downloaded font;
-                  (rendered "X") = drawn with another font than declared (a fallback)
+                  (rendered "X") = drawn with another font than declared (a fallback);
+                  (resolves to "X") = the font a generic family (sans-serif, system-ui) became
   contrast 4.47   WCAG ratio, rounded down, against the background behind the text
+  text in X       the text is drawn by descendant X (the one with most of it): its font, color, contrast
+  truncated       the text is cut off (overflow clip, ellipsis or line clamp); a "…" in the header is
+                  only bdg shortening the text
+  .a.b(+3)        the first two classes and how many more the element has
+  sizing content-box  padding and border add to the CSS size (shown only then; border-box is not)
   (+N not rendered)  children with display: none (or not in the layout)
   hints           declarations on this element that have no effect, why, the fix and where they are
                   ('none': checked, nothing found)
@@ -466,15 +593,29 @@ export function inspectCascadeNote(reason) {
         ? "CSS rules not read: the page's stylesheets took too long (hints wait 1 s; --rules and --why 5 s)"
         : 'CSS rules not read: Chrome could not report the rules matching this element';
 }
+/**
+ * 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.
+ *
+ * @param pseudo - `::before` or `::after`
+ * @returns Note
+ */
+export function inspectPseudoOfNote(pseudo) {
+    return `Inspected the element of ${pseudo}: pseudo-elements cannot be selected; ${pseudo} is on the pseudo line (content, size, position, inset, colors)`;
+}
 /**
  * Header badge of `bdg dom inspect` when the page is shown in its dark theme
- * because the session follows the system's dark preference: the colors are
- * the dark theme's, not what a light-mode visitor sees.
+ * because the session follows the system's dark preference, or because
+ * `page emulate` asked for dark: the colors are the dark theme's, not what a
+ * light-mode visitor sees.
  *
+ * @param emulated - The dark preference comes from `page emulate --color-scheme dark`
  * @returns Badge
  */
-export function inspectDarkThemeBadge() {
-    return '[dark theme from system; --color-scheme light for light]';
+export function inspectDarkThemeBadge(emulated = false) {
+    return emulated
+        ? '[dark theme, emulated; bdg page emulate --color-scheme light for light]'
+        : '[dark theme from system; --color-scheme light for light]';
 }
 /**
  * Header badges of `bdg dom inspect` for what keeps an element from being seen.
@@ -491,6 +632,7 @@ export function inspectVisibilityBadges(visibility) {
         visibility.hidden && `[hidden: ${visibility.hidden}]`,
         visibility.offscreen && `[offscreen: ${visibility.offscreen}]`,
         visibility.coveredBy && `[${coverText(visibility.coveredBy, visibility.coverTransparent)}]`,
+        visibility.masked && `[${maskedText(visibility.masked)}]`,
     ].filter((badge) => Boolean(badge));
 }
 /**
@@ -641,6 +783,19 @@ export function dialogConsoleText(dialog) {
     const kind = dialog.type === 'beforeunload' ? 'beforeunload' : `${dialog.type}()`;
     return `${kind} dialog accepted${dialog.message ? `: "${dialog.message}"` : ''}`;
 }
+/**
+ * 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 function pointerScrollText(scrolledBy) {
+    const parts = [
+        scrolledBy.y !== 0 && `${scrolledBy.y > 0 ? 'down' : 'up'} ${Math.abs(scrolledBy.y)}px`,
+        scrolledBy.x !== 0 && `${scrolledBy.x > 0 ? 'right' : 'left'} ${Math.abs(scrolledBy.x)}px`,
+    ].filter(Boolean);
+    return `page ${parts.join(', ')} to reach it`;
+}
 /** Headline of each pointer action, e.g. "Element Double-clicked" */
 export const POINTER_ACTION_DONE = {
     click: 'Clicked',
@@ -879,24 +1034,47 @@ export function elementTextLine(text) {
  *
  * @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 function emptyElementLine(children, count) {
+export function emptyElementLine(children, count, inShadowRoot = false) {
+    const holder = inShadowRoot ? 'its shadow root holds' : 'holds';
     if (count === 0)
-        return 'No text and no child elements';
+        return `No text and no child elements${inShadowRoot ? ' in its shadow root' : ''}`;
     const more = count > children.length ? `, … ${count - children.length} more` : '';
-    return `No text; holds ${pluralize(count, 'element')}: ${children.join(', ')}${more} (see its HTML with --raw)`;
+    const hint = inShadowRoot ? 'see it with bdg dom inspect' : 'see its HTML with --raw';
+    return `No text; ${holder} ${pluralize(count, 'element')}: ${children.join(', ')}${more} (${hint})`;
+}
+/**
+ * Note on a screenshot scaled down to keep its image token cost bounded.
+ *
+ * @param originalWidth - Captured width (CSS px)
+ * @param originalHeight - Captured height
+ * @param width - Image width
+ * @param height - Image height
+ * @returns e.g. `scaled from 1920×993 to 1568×811; --no-resize for full size`
+ */
+export function screenshotScaledNote(originalWidth, originalHeight, width, height) {
+    return `scaled from ${originalWidth}×${originalHeight} to ${width}×${height}; --no-resize for full size`;
 }
 /**
  * Note on an element screenshot that captured more than the element's border
- * box, because content (floats, positioned children) overflows it.
+ * box, because content (floats, positioned children, text, shadows) overflows it.
  *
  * @param box - Border box
  * @param captured - Area captured
- * @returns e.g. `grown from 940×37 to 940×285 to include content overflowing the element`
+ * @param padding - `--padding` (px), which is not the element's own
+ * @returns e.g. `grown from 940×37 to 940×285 to include what it paints outside its box (…)`
  */
-export function screenshotGrownNote(box, captured) {
-    return `grown from ${box.width}×${box.height} to ${captured.width}×${captured.height} to include content overflowing the element`;
+export function screenshotGrownNote(box, captured, padding = 0) {
+    const painted = { width: captured.width - 2 * padding, height: captured.height - 2 * padding };
+    const grew = painted.width > box.width + 0.5 || painted.height > box.height + 0.5;
+    const ink = `grown from ${box.width}×${box.height} to ${painted.width}×${painted.height} to include what it paints outside its box (overflowing content, shadows, outline)`;
+    const pad = `${padding}px of page around it (--padding)`;
+    if (!padding)
+        return ink;
+    return grew ? `${ink}, plus ${pad}` : `with ${pad}: ${captured.width}×${captured.height}`;
 }
 /**
  * Next commands after `bdg dom query`, by index so they reach matches in
@@ -917,6 +1095,27 @@ export function queryNextSteps(index) {
 export function evalFrameLine(url) {
     return `Frame: ${frameUrlLabel(url)}`;
 }
+/**
+ * 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 function evalCopiedByBrowserWarning(replaced) {
+    return `the page replaced ${replaced.join(', ')}, so the browser copied the result: undefined, NaN, functions, DOM nodes, dates, maps and sets inside it show as null or {}`;
+}
+/**
+ * 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 function evalPreviewWarning(replaced) {
+    return `the page replaced ${replaced.join(', ')}, and the result could not be copied (it holds a cycle or a BigInt), so it is shown as a shortened preview string; return a JSON-safe value (e.g. pick the fields you need)`;
+}
 /**
  * Generate warning message.
  *
@@ -1010,7 +1209,7 @@ export function startCommandHelpMessage() {
 export function pageEmulateNothingError() {
     return {
         message: 'Nothing to emulate',
-        suggestion: 'Give --viewport <WxH>, --color-scheme light|dark, or --reset, e.g. bdg page emulate --viewport 900x700',
+        suggestion: 'Give --viewport <WxH>, --mobile, --color-scheme light|dark, or --reset, e.g. bdg page emulate --viewport 900x700',
     };
 }
 /**
@@ -1022,8 +1221,11 @@ export function pageEmulateNothingError() {
 export function pageEmulationLines(result) {
     const size = (v) => `${v.width}x${v.height}`;
     const { emulated } = result;
+    const phone = emulated.viewport?.mobile
+        ? ' (phone: mobile layout, touch, mobile user agent)'
+        : '';
     return [
-        ['Viewport', emulated.viewport ? size(emulated.viewport) : 'the browser window'],
+        ['Viewport', emulated.viewport ? `${size(emulated.viewport)}${phone}` : 'the browser window'],
         ...(result.viewport
             ? [['Layout', `${size(result.viewport)} (without scrollbars)`]]
             : []),
@@ -1052,4 +1254,29 @@ export function inspectAnimatingBadge(animating) {
 export function inspectMidTransitionNote() {
     return '(mid-transition: inspect again for the final value)';
 }
+/** Examples under `bdg dom audit --help` */
+export const AUDIT_HELP_EXAMPLES = `
+Examples:
+  bdg dom audit                       All checks
+  bdg dom audit contrast --level AAA  Text below WCAG AAA, weakest first
+  bdg dom audit overflow              What scrolls sideways, cut-off text, scaled images
+  bdg dom audit layers animations     Fixed/sticky elements and running animations
+
+Follow up on a finding with bdg dom inspect <element> (e.g. --why color).`;
+/** Examples under `bdg css search --help` */
+export const CSS_SEARCH_HELP_EXAMPLES = `
+Examples:
+  bdg css search -- --brand       Where a custom property is set and used (-- before a text
+                                  that starts with -; options go before it:
+                                  bdg css search --limit 50 -- --brand)
+  bdg css search "oklch("         Rules that use oklch colors
+  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 function helpJsonDetailsNote() {
+    return 'Option behaviors, defaults, choices and examples: bdg <command> --help --json (e.g. bdg dom query --help --json). Everything at once: bdg --help --json --full';
+}
 //# sourceMappingURL=commands.js.map