browser-debugger-cli 0.10.0 → 0.12.0

package/dist/ui/formatters/inspect.js

@@ -16,7 +16,7 @@
  */
 import { containerKind } from '../../runtime/dom/inspectLayoutModel.js';
 import { joinLines } from '../formatting.js';
-import { inspectCascadeNote, inspectAnimatingBadge, inspectMidTransitionNote, inspectDarkThemeBadge, inspectedMatchAction, inspectVisibilityBadges, multipleMatchesWarning, } from '../messages/commands.js';
+import { inspectCascadeNote, inspectAnimatingBadge, inspectMidTransitionNote, inspectDarkThemeBadge, inspectPseudoOfNote, inspectedMatchAction, inspectVisibilityBadges, multipleMatchesWarning, } from '../messages/commands.js';
 import { shadowText, sidesShorthand } from '../../utils/cssValues.js';
 import { truncateByLength } from '../../utils/strings.js';
 /** Longest parent label on the parent line (CSS-module class names run long) */
@@ -50,11 +50,12 @@ export function inspectHeader(data) {
         data.element,
         data.content !== undefined && `"${data.content}"`,
         data.placeholder !== undefined && `placeholder "${data.placeholder}"`,
-        data.rect && `${data.rect.w}x${data.rect.h} @${data.rect.x},${data.rect.y}`,
+        data.rect &&
+            `${data.rect.w}x${data.rect.h}${data.rect.screen ? ` (${data.rect.screen.w}x${data.rect.screen.h} on screen)` : ''} @${data.rect.x},${data.rect.y}${data.rect.in ? ' (fixed: viewport position)' : ''}`,
         kind && `[${kind}]`,
         ...inspectVisibilityBadges(data.visibility),
         data.context && `in ${data.context}`,
-        data.theme === 'dark' && inspectDarkThemeBadge(),
+        data.theme === 'dark' && inspectDarkThemeBadge(data.themeFrom === 'emulation'),
         data.animating && inspectAnimatingBadge(data.animating),
     ]
         .filter(Boolean)
@@ -177,9 +178,9 @@ function parentLine(layout) {
     ]);
 }
 /**
- * Font, weight and size as one phrase, e.g. `Inter (webfont) 600 italic 16/24`
- * or `Inter (rendered "Helvetica") 400 14/normal` when the text was drawn in
- * another font (a fallback, or the face's own name); for a container only
+ * Font, weight and size as one phrase, e.g. `Inter (webfont) 600 italic 16/24`,
+ * `Inter (rendered "Helvetica") 400 14/normal` when the text was drawn in a
+ * fallback, or `sans-serif (resolves to "Helvetica")`; for a container only
  * the fields it has.
  *
  * @param text - Text group
@@ -188,6 +189,7 @@ function parentLine(layout) {
 function fontParts(text) {
     const loaded = [
         text.rendered && `rendered "${text.rendered}"`,
+        text.resolved && `resolves to "${text.resolved}"`,
         text.webfont && 'webfont loaded',
     ].filter(Boolean);
     const family = text.family && [text.family, loaded.length > 0 && `(${loaded.join(', ')})`];
@@ -218,10 +220,13 @@ function contrastText(contrast) {
     if (!contrast)
         return undefined;
     return [
-        `contrast ${contrast.ratio} ${contrast.level}`,
-        contrast.inherited && `on ${contrast.background}`,
+        contrast.approximate
+            ? `contrast ≈${contrast.ratio} ${contrast.level}`
+            : `contrast ${contrast.ratio} ${contrast.level}`,
+        `on ${contrast.background}`,
         contrast.overImage && '(over image)',
         contrast.opacity !== undefined && `(faded: opacity ${contrast.opacity})`,
+        contrast.approximate && `(approximate: ${contrast.approximate.join(', ')})`,
     ]
         .filter(Boolean)
         .join(' ');
@@ -234,6 +239,7 @@ function contrastText(contrast) {
  */
 function textLine(text) {
     return groupLine('text', [
+        text.holder && `in ${text.holder}`,
         ...fontParts(text),
         text.color && `color ${text.color}`,
         contrastText(text.contrast),
@@ -244,6 +250,8 @@ function textLine(text) {
         text.whiteSpace && `ws ${text.whiteSpace}`,
         text.overflow && `text-overflow ${text.overflow}`,
         text.clamp && `clamp ${text.clamp}`,
+        text.truncated && 'truncated',
+        text.gradientFill && 'filled by its background (background-clip: text; no contrast)',
         text.shadow && `shadow ${text.shadow}`,
         text.features && `features ${text.features}`,
     ]);
@@ -257,9 +265,13 @@ function textLine(text) {
 function fillText(fill) {
     if (fill.type === 'solid')
         return `bg ${fill.color}`;
-    if (fill.type === 'gradient')
-        return `bg-image ${fill.value}`;
-    return `bg-image ${fill.value}${fill.size ? ` size ${fill.size}` : ''}`;
+    return [
+        `bg-image ${fill.value}`,
+        fill.size && `size ${fill.size}`,
+        fill.position && `at ${fill.position}`,
+    ]
+        .filter(Boolean)
+        .join(' ');
 }
 /**
  * The fill line: backgrounds, opacity and blend mode.
@@ -268,7 +280,11 @@ function fillText(fill) {
  * @returns Line
  */
 function fillLine(data) {
+    const paint = data.paint;
     return groupLine('fill', [
+        paint && `fill ${paint.fill}`,
+        paint &&
+            `stroke ${paint.stroke}${paint.strokeWidth !== undefined ? ` ${paint.strokeWidth}` : ''}`,
         ...(data.fills ?? []).map(fillText),
         data.opacity !== undefined && `opacity ${data.opacity}`,
         data.blend && `blend ${data.blend}`,
@@ -337,6 +353,7 @@ function pseudoText(pseudo) {
         pseudo.content !== undefined && `content ${pseudo.content}`,
         pseudo.display,
         pseudo.position,
+        pseudo.inset && `inset ${pseudo.inset}`,
         pseudo.size && `${pseudo.size.w}x${pseudo.size.h}`,
         pseudo.color && `color ${pseudo.color}`,
         pseudo.fontStyle,
@@ -370,7 +387,9 @@ function treeRow(node) {
     return [
         node.element,
         node.count !== undefined && `×${node.count}`,
-        `${node.w}x${node.h}`,
+        node.contents ? '(contents)' : `${node.w}x${node.h}`,
+        node.shadow && '(shadow root)',
+        node.via && `via ${node.via}`,
         node.layout && `[${node.layout}]`,
         node.text && `"${node.text}"`,
         node.childCount !== undefined && `(${node.childCount})`,
@@ -422,7 +441,7 @@ function ruleScope(entry) {
  * @returns Lines
  */
 function cascadeBlock(data) {
-    const hints = (data.hints ?? []).map((hint) => `${hint.property}: ${hint.value} ${hint.kind === 'not-inherited' ? "is the browser's" : 'has no effect'}: ${hint.reason} → ${hint.fix} · in ${hint.source}`);
+    const hints = (data.hints ?? []).map((hint) => `${hint.property}: ${hint.value} ${hint.kind === 'not-inherited' ? "is the browser's" : hint.only ? `has no effect on ${hint.only.join(', ')}` : 'has no effect'}: ${hint.reason} → ${hint.fix} · in ${hint.source}`);
     return [
         ...labelledLines('hints', data.hints?.length === 0 ? ['none'] : hints),
         ...labelledLines('rules', (data.rules ?? []).map(ruleLine)),
@@ -472,14 +491,19 @@ function whyLines(why, data) {
             entry.important ? ' !important' : '',
             `  ${entry.source}${entry.specificity ? ` [${entry.specificity.join(',')}]` : ''}${ruleScope(entry)}`,
             entry.status === 'inherited' ? ' (inherited)' : '',
+            entry.note ? ` (${entry.note})` : '',
         ].join('');
     });
     const variables = (why.variables ?? []).map((variable) => `    ${variable.name}: ${truncateByLength(variable.value, CASCADE_VALUE_WIDTH)}  ${variable.source}${variable.inherited !== undefined ? ` (inherited from ${levelsUp(variable.inherited)})` : ''}`);
     return [
         `${why.property} = ${why.computed}${midTransition(why.property, data.animating) ? ` ${inspectMidTransitionNote()}` : ''}`,
         ...entries.slice(0, 1),
+        ...(why.chain[0]?.rule
+            ? [`    in ${truncateByLength(why.chain[0].rule, RULE_LINE_WIDTH)}`]
+            : []),
         ...variables,
         ...entries.slice(1),
+        ...(why.inactive ?? []).map((rule) => `  - ${truncateByLength(rule.value, CASCADE_VALUE_WIDTH)}  ${rule.selector} ${rule.condition} (does not apply now)`),
         ...(why.chain.length === 0 ? ['  no author declaration: the default or inherited value'] : []),
     ];
 }
@@ -505,6 +529,8 @@ function midTransition(property, animating) {
 function levelsUp(levels) {
     return levels === 1 ? 'the parent' : `${levels} levels up`;
 }
+/** Longest rule text shown under the winner in `--why` (JSON has up to 300 characters) */
+const RULE_LINE_WIDTH = 120;
 /** Longest declared value shown in `--rules` and `--why` lines (font stacks run long) */
 const CASCADE_VALUE_WIDTH = 60;
 /**
@@ -589,8 +615,9 @@ export function formatInspect(data) {
     const note = data.picked
         ? multipleMatchesWarning(data.count, inspectedMatchAction(data.picked, data.index))
         : undefined;
+    const pseudoNote = data.pseudoOf && inspectPseudoOfNote(data.pseudoOf);
     if (data.why)
-        return joinLines(inspectHeader(data), ...cascadeBlock(data), note);
-    return joinLines(inspectHeader(data), ...body, ...cascadeBlock(data), ...treeBlock(data), note);
+        return joinLines(inspectHeader(data), ...cascadeBlock(data), note, pseudoNote);
+    return joinLines(inspectHeader(data), ...body, ...cascadeBlock(data), ...treeBlock(data), note, pseudoNote);
 }
 //# sourceMappingURL=inspect.js.map

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

@@ -0,0 +1,11 @@
+import type { InstalledSkill } from '../../types.js';
+/**
+ * Format where the skill was installed, one line per agent.
+ *
+ * @param data - Install results
+ * @returns Human-readable summary
+ */
+export declare function formatInstalledSkills(data: {
+    skills: InstalledSkill[];
+}): string;
+//# sourceMappingURL=installSkill.d.ts.map

package/dist/ui/formatters/installSkill.js

@@ -0,0 +1,31 @@
+import { homedir } from 'os';
+import { OutputFormatter } from '../formatting.js';
+/**
+ * Shorten a path under the home directory to `~/...`.
+ *
+ * @param path - Absolute path
+ * @returns Path as the user would type it
+ */
+function tildePath(path) {
+    const home = homedir();
+    return path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+/**
+ * Format where the skill was installed, one line per agent.
+ *
+ * @param data - Install results
+ * @returns Human-readable summary
+ */
+export function formatInstalledSkills(data) {
+    const fmt = new OutputFormatter().text('bdg skill:');
+    for (const skill of data.skills) {
+        fmt.text(`  ${skill.target.padEnd(6)}  ${skill.status.padEnd(9)}  ${tildePath(skill.path)}`);
+    }
+    return fmt
+        .hints('Next:', [
+        'Start a new agent session to load it (running sessions keep the old list)',
+        'After upgrading bdg, run bdg install-skill again',
+    ])
+        .build();
+}
+//# sourceMappingURL=installSkill.js.map

package/dist/ui/formatters/status.js

@@ -98,7 +98,7 @@ export function appearanceLines(metadata, pageState) {
             ? [
                 [
                     'Viewport',
-                    `${viewport.width}×${viewport.height}${metadata.viewport ? ` (emulated ${metadata.viewport.width}x${metadata.viewport.height})` : ''}`,
+                    `${viewport.width}×${viewport.height}${metadata.viewport ? ` (emulated ${metadata.viewport.width}x${metadata.viewport.height}${metadata.viewport.mobile ? ', phone' : ''})` : ''}`,
                 ],
             ]
             : []),

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

@@ -94,6 +94,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.
  *
@@ -252,7 +263,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 +281,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.
  *
@@ -538,13 +559,24 @@ export declare function elementTextLine(text: string): string;
  * @returns e.g. `No text; holds 1 element: iframe (see its HTML with --raw)`
  */
 export declare function emptyElementLine(children: string[], count: number): 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 +584,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.
@@ -655,6 +687,7 @@ export declare function pageEmulationLines(result: {
         viewport?: {
             width: number;
             height: number;
+            mobile?: boolean;
         };
         colorScheme?: string;
     };
@@ -678,5 +711,9 @@ 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";
 export {};
 //# sourceMappingURL=commands.d.ts.map

package/dist/ui/messages/commands.js

@@ -136,6 +136,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.
  *
@@ -432,8 +445,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 +485,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.
@@ -887,16 +920,35 @@ export function emptyElementLine(children, count) {
     const more = count > children.length ? `, … ${count - children.length} more` : '';
     return `No text; holds ${pluralize(count, 'element')}: ${children.join(', ')}${more} (see its HTML with --raw)`;
 }
+/**
+ * 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
@@ -1010,7 +1062,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 +1074,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 +1107,21 @@ 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`;
 //# sourceMappingURL=commands.js.map

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

@@ -61,4 +61,10 @@ export declare function connectionLostRetryMessage(timestamp: string, retryLabel
  * @returns Message instructing the user how to stop follow mode
  */
 export declare function connectionLostStopHintMessage(): string;
+/**
+ * Notice that `bdg tail` is deprecated (it still runs).
+ *
+ * @returns Notice for stderr
+ */
+export declare function tailDeprecatedNotice(): string;
 //# sourceMappingURL=preview.d.ts.map

package/dist/ui/messages/preview.js

@@ -30,7 +30,7 @@ export function verboseCommandsMessage() {
     return [
         'Commands:',
         `  Full preview:    ${sessionCommand('bdg peek --last 50')}`,
-        `  Watch live:      ${sessionCommand('bdg tail')}`,
+        `  Watch live:      ${sessionCommand('bdg peek --follow')}`,
         `  End session:     ${sessionCommand('bdg stop')}`,
     ].join('\n');
 }
@@ -79,4 +79,12 @@ export function connectionLostRetryMessage(timestamp, retryLabel) {
 export function connectionLostStopHintMessage() {
     return 'Press Ctrl+C to stop';
 }
+/**
+ * Notice that `bdg tail` is deprecated (it still runs).
+ *
+ * @returns Notice for stderr
+ */
+export function tailDeprecatedNotice() {
+    return 'Note: "bdg tail" is deprecated and will be removed; use "bdg peek --follow" (same options: --last, --network, --console, --interval, --verbose)';
+}
 //# sourceMappingURL=preview.js.map

package/dist/utils/cssValues.js

@@ -44,11 +44,42 @@ export function cssLength(value) {
  * @returns Normalized value
  */
 export function normalizeCssValue(value) {
-    return hexColorsIn(value)
-        .replace(PX_IN_VALUE, (_match, number) => String(round1(Number(number))))
+    return mapOutsideFunctions(hexColorsIn(value), UNIT_KEEPING_FUNCTIONS, (part) => part.replace(PX_IN_VALUE, (_match, number) => String(round1(Number(number)))))
         .replace(/\s+/g, ' ')
         .trim();
 }
+/** Functions whose px stay written: math mixes units, URLs are names */
+const UNIT_KEEPING_FUNCTIONS = new Set(['calc', 'min', 'max', 'clamp', 'url']);
+/**
+ * Change the parts of a value that are not inside the given functions.
+ *
+ * @param value - CSS value
+ * @param functions - Function names whose arguments are kept as written
+ * @param change - Change for the other parts
+ * @returns Value
+ */
+function mapOutsideFunctions(value, functions, change) {
+    let result = '';
+    let start = 0;
+    let depth = 0;
+    for (let i = 0; i < value.length; i++) {
+        if (value[i] === '(') {
+            const name = /([\w-]+)$/.exec(value.slice(start, i))?.[1]?.toLowerCase() ?? '';
+            if (depth === 0 && functions.has(name)) {
+                result += change(value.slice(start, i));
+                start = i;
+                depth = 1;
+            }
+            else if (depth > 0)
+                depth++;
+        }
+        else if (value[i] === ')' && depth > 0 && --depth === 0) {
+            result += value.slice(start, i + 1);
+            start = i + 1;
+        }
+    }
+    return result + (depth > 0 ? value.slice(start) : change(value.slice(start)));
+}
 /**
  * 1-4 values the way CSS shorthands write them (top, right, bottom, left).
  *
@@ -190,9 +221,10 @@ function round3(value) {
 function decomposeMatrix([a = 1, b = 0, c = 0, d = 1, e = 0, f = 0]) {
     if (Math.abs(a * c + b * d) > 1e-6)
         return undefined;
-    const scaleX = Math.hypot(a, b);
+    const mirrored = a * d - b * c < 0 && a < 0;
+    const scaleX = mirrored ? -Math.hypot(a, b) : Math.hypot(a, b);
     const scaleY = scaleX === 0 ? 0 : (a * d - b * c) / scaleX;
-    const angle = round3((Math.atan2(b, a) * 180) / Math.PI);
+    const angle = round3((Math.atan2(mirrored ? -b : b, mirrored ? -a : a) * 180) / Math.PI);
     const parts = [];
     if (e !== 0 || f !== 0)
         parts.push(`translate(${round1(e)},${round1(f)})`);

package/dist/utils/decisionTrees.js

@@ -121,11 +121,6 @@ export const DECISION_TREES = {
                 yesCommand: 'peek --follow',
                 noAction: 'next',
             },
-            {
-                question: 'Need continuous monitoring (like tail -f)?',
-                yesCommand: 'tail',
-                noAction: 'next',
-            },
             {
                 question: 'Need quick preview of recent data?',
                 yesCommand: 'peek',

package/dist/utils/suggestions.d.ts

@@ -18,8 +18,10 @@ export declare function getSuggestion(input: string, candidates: readonly string
 /**
  * Names (ids or classes) similar to one that matched nothing, best first, at
  * most three: near-typos first (Levenshtein distance up to a fifth of the
- * length, at least 2), then names sharing a long end, then names sharing a
- * long start (at least a third of the name, at least 4 characters). The end
+ * length, at least 2), then names sharing a long end (at least a third of
+ * the name, at least 4 characters), then names sharing a long start (at
+ * least half: `--color-btn-inset-shadow` and `--color-bg-discussions-…` share
+ * only a namespace). The end
  * ranks before the start because ids tend to name an action before the item
  * (`add-to-cart-backpack` becomes `remove-backpack` once clicked).
  *

package/dist/utils/suggestions.js

@@ -65,8 +65,10 @@ function commonSuffixLength(a, b) {
 /**
  * Names (ids or classes) similar to one that matched nothing, best first, at
  * most three: near-typos first (Levenshtein distance up to a fifth of the
- * length, at least 2), then names sharing a long end, then names sharing a
- * long start (at least a third of the name, at least 4 characters). The end
+ * length, at least 2), then names sharing a long end (at least a third of
+ * the name, at least 4 characters), then names sharing a long start (at
+ * least half: `--color-btn-inset-shadow` and `--color-bg-discussions-…` share
+ * only a namespace). The end
  * ranks before the start because ids tend to name an action before the item
  * (`add-to-cart-backpack` becomes `remove-backpack` once clicked).
  *
@@ -79,15 +81,15 @@ export function findSimilarNames(name, candidates) {
     const maxDistance = Math.max(2, Math.floor(name.length / 5));
     const minAffix = Math.max(4, Math.ceil(name.length / 3));
     const typos = findMatches(name, others, maxDistance, false).map((match) => match.value);
-    const byAffix = (length) => others
+    const byAffix = (length, min = minAffix) => others
         .map((candidate) => ({ candidate, length: length(candidate) }))
-        .filter((entry) => entry.length >= minAffix)
+        .filter((entry) => entry.length >= min)
         .sort((a, b) => b.length - a.length)
         .map((entry) => entry.candidate);
     const ranked = [
         ...typos,
         ...byAffix((candidate) => commonSuffixLength(name, candidate)),
-        ...byAffix((candidate) => commonPrefixLength(name, candidate)),
+        ...byAffix((candidate) => commonPrefixLength(name, candidate), Math.max(minAffix, Math.ceil(name.length / 2))),
     ];
     return [...new Set(ranked)].slice(0, MAX_SIMILAR_NAMES);
 }