browser-debugger-cli 0.9.0 → 0.11.0

package/dist/ui/formatters/keyAttributes.js

@@ -0,0 +1,84 @@
+/**
+ * Key attributes of an element (`KeyAttributes`) shortened for one line of
+ * human output: `dom query` shows them in the element's tag, `dom get` after
+ * its role. `--json` has the full values.
+ */
+import { cutMiddle, escapeControlChars, truncateUrl } from '../formatting.js';
+import { safeParseUrl } from '../../utils/url.js';
+/** Longest value shown (longer ones are cut in the middle) */
+const MAX_VALUE_LENGTH = 40;
+/**
+ * An image URL as its file name, after `…/` when it had a path or host
+ * before it (`…/sl-404.168b1cce.jpg`); data: URLs keep their start.
+ *
+ * @param src - `src` attribute
+ * @returns Short form
+ */
+function fileName(src) {
+    if (/^(data|blob):/i.test(src))
+        return src;
+    const path = src.split(/[?#]/)[0] ?? src;
+    const name = path.substring(path.lastIndexOf('/') + 1);
+    return name && name !== path ? `…/${name}` : src;
+}
+/**
+ * An iframe URL as its host, with `/…` when it has a path or query
+ * (`//pay.example/…`); others (about:blank, relative URLs) as given.
+ *
+ * @param src - `src` attribute
+ * @returns Short form
+ */
+function hostOf(src) {
+    const parsed = /^https?:/i.test(src) ? safeParseUrl(src) : null;
+    if (!parsed)
+        return src;
+    const more = parsed.pathname.length > 1 || parsed.search ? '/…' : '';
+    return `//${parsed.host}${more}`;
+}
+/**
+ * A link or form target: an absolute web URL as `//host/path`, cut in the
+ * middle of the path (`//` keeps it from reading as a relative path).
+ *
+ * @param url - `href` or `action` attribute
+ * @returns Short form
+ */
+function shortUrl(url) {
+    return /^https?:/i.test(url) ? `//${truncateUrl(url, MAX_VALUE_LENGTH - 2)}` : url;
+}
+/**
+ * One value shortened for display.
+ *
+ * @param tag - Element tag
+ * @param name - Attribute name
+ * @param value - Full value
+ * @returns Short value on one line
+ */
+function shortValue(tag, name, value) {
+    let short = value;
+    if (name === 'src')
+        short = tag === 'iframe' ? hostOf(value) : fileName(value);
+    else if (name === 'href' || name === 'action')
+        short = shortUrl(value);
+    return cutMiddle(escapeControlChars(short.replace(/\s+/g, ' ').trim()), MAX_VALUE_LENGTH);
+}
+/**
+ * Key attributes as `name="value"` items, values shortened: an image's
+ * file name, an iframe's host, links without their scheme, the rest cut in
+ * the middle at 40 characters. `checked` is shown as a bare word, and left
+ * out when false.
+ *
+ * @param tag - Element tag
+ * @param attributes - Key attributes
+ * @param leaveOut - Names not to show (already shown elsewhere)
+ * @returns Items in attribute order, e.g. `['src="…/logo.png"', 'alt="Logo"']`
+ */
+export function keyAttributeItems(tag, attributes, leaveOut = new Set()) {
+    return Object.entries(attributes ?? {}).flatMap(([name, value]) => {
+        if (leaveOut.has(name) || value === false)
+            return [];
+        if (value === true)
+            return [name];
+        return [`${name}="${shortValue(tag, name, value)}"`];
+    });
+}
+//# sourceMappingURL=keyAttributes.js.map

package/dist/ui/formatters/layout.js

@@ -3,7 +3,7 @@
  */
 import { indexSourceText } from '../../errors/messages.js';
 import { OutputFormatter } from '../formatting.js';
-import { indexLayoutHeadline, layoutHeadline, layoutPositionLabel, moreMatchesNote, pageLayoutLine, } from '../messages/commands.js';
+import { coverText, indexLayoutHeadline, layoutHeadline, layoutPositionLabel, moreMatchesNote, pageLayoutLine, } from '../messages/commands.js';
 /** Elements listed in human output (JSON has up to 100) */
 const LAYOUT_DISPLAY_LIMIT = 20;
 /**
@@ -23,7 +23,7 @@ export function layoutLine(element, viewport) {
         `[${element.index}] ${element.element}${element.text ? ` "${element.text}"` : ''}`,
         element.inViewport !== 'hidden' && `${bounds.x},${bounds.y} ${bounds.width}×${bounds.height}`,
         layoutPositionLabel(element, viewport),
-        element.coveredBy && `covered by ${element.coveredBy}`,
+        element.coveredBy && coverText(element.coveredBy, element.coverTransparent),
         element.inert && 'inert',
         element.invisible,
         element.context && element.context !== element.clippedBy && `in ${element.context}`,

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

@@ -11,4 +11,17 @@ import type { SessionNetworkHeadersData } from '../../ipc/protocol/commands.js';
  * @returns Formatted string for console output
  */
 export declare function formatNetworkHeaders(data: SessionNetworkHeadersData): string;
+/**
+ * The values of a header, one per line. A header sent several times reaches
+ * CDP as one value with the values joined by newlines (`Set-Cookie`, or a
+ * server repeating `Strict-Transport-Security`); a value sent more than once
+ * is listed once, saying how often it was sent. `Set-Cookie` lines are all
+ * kept: each one sets a cookie, and repeating one is not the same as sending
+ * it once.
+ *
+ * @param name - Header name
+ * @param value - Header value as CDP reports it
+ * @returns e.g. `['max-age=63072000 (sent 2 times)']`
+ */
+export declare function headerValueLines(name: string, value: string): string[];
 //# sourceMappingURL=networkHeaders.d.ts.map

package/dist/ui/formatters/networkHeaders.js

@@ -5,6 +5,7 @@
  */
 import { formatRequestStatus } from './requestStatus.js';
 import { OutputFormatter } from '../formatting.js';
+import { headerRepeatedNote } from '../messages/networkMessages.js';
 /**
  * Format network request headers for display.
  *
@@ -33,11 +34,30 @@ export function formatNetworkHeaders(data) {
     fmt.text(`Request ID: ${data.requestId}`);
     return fmt.build();
 }
+/**
+ * The values of a header, one per line. A header sent several times reaches
+ * CDP as one value with the values joined by newlines (`Set-Cookie`, or a
+ * server repeating `Strict-Transport-Security`); a value sent more than once
+ * is listed once, saying how often it was sent. `Set-Cookie` lines are all
+ * kept: each one sets a cookie, and repeating one is not the same as sending
+ * it once.
+ *
+ * @param name - Header name
+ * @param value - Header value as CDP reports it
+ * @returns e.g. `['max-age=63072000 (sent 2 times)']`
+ */
+export function headerValueLines(name, value) {
+    if (name.toLowerCase() === 'set-cookie')
+        return value.split('\n');
+    const counts = new Map();
+    for (const line of value.split('\n'))
+        counts.set(line, (counts.get(line) ?? 0) + 1);
+    return [...counts].map(([line, count]) => count > 1 ? `${line} ${headerRepeatedNote(count)}` : line);
+}
 /**
  * Format a section of headers with consistent formatting.
  *
- * Repeated headers (CDP joins e.g. multiple `Set-Cookie` values with newlines)
- * are printed one per line.
+ * Repeated headers are printed one value per line ({@link headerValueLines}).
  *
  * @param fmt - Output formatter instance
  * @param headers - Headers to format
@@ -46,7 +66,7 @@ function formatHeaderSection(fmt, headers) {
     const entries = Object.entries(headers).sort(([a], [b]) => a.localeCompare(b));
     const keyWidth = Math.max(...entries.map(([k]) => k.length)) + 4;
     entries.forEach(([key, value]) => {
-        value.split('\n').forEach((line) => fmt.keyValue(`  ${key}`, line, keyWidth));
+        headerValueLines(key, value).forEach((line) => fmt.keyValue(`  ${key}`, line, keyWidth));
     });
 }
 /**

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

@@ -7,22 +7,50 @@
 import type { NetworkRequest } from '../../types.js';
 export interface NetworkListOptions {
     verbose?: boolean;
+    /** Start of the current page, which the START column counts from ({@link pageStartOf}) */
+    pageStart?: PageStart;
     last?: number;
     totalCount?: number;
     /** Requests matching the filters, before --last (defaults to totalCount) */
     filteredCount?: number;
 }
+/**
+ * When the current page started loading: the request of its document, in
+ * Chrome's monotonic time (`sentTime`, seconds) and wall-clock time
+ * (`timestamp`, epoch ms).
+ */
+export type PageStart = Pick<NetworkRequest, 'sentTime' | 'timestamp'>;
+/**
+ * The start of the current page: the earliest document request of the
+ * latest navigation among the requests (its earliest request when its
+ * document was not captured).
+ *
+ * @param requests - All captured requests (before filters, so the document is among them)
+ * @returns Its times, or undefined when there are no requests
+ */
+export declare function pageStartOf(requests: NetworkRequest[]): PageStart | undefined;
+/**
+ * Format a request's start for the START column, relative to the current
+ * page's start: tenths of a second up to 100 s, then whole seconds, then
+ * minutes.
+ *
+ * @param request - Request
+ * @param pageStart - Start of the current page (none: `-`)
+ * @returns e.g. "+0.0s", "+1.2s", "+250s", "+17m", "-35.2s" (earlier page)
+ */
+export declare function formatStartOffset(request: NetworkRequest, pageStart: PageStart | undefined): string;
 /**
  * Rows of the network stream: requests that finished since the last poll,
  * with the column header the first time.
  *
  * @param requests - Newly finished requests
- * @param options - `header` the first time; `verbose` for full URLs
+ * @param options - `header` the first time; `verbose` for full URLs; the page start for START
  * @returns Text to print (empty when there is nothing new)
  */
 export declare function formatNetworkFollowRows(requests: NetworkRequest[], options?: {
     header?: boolean;
     verbose?: boolean;
+    pageStart?: PageStart;
 }): string;
 /**
  * Format network requests for display.

package/dist/ui/formatters/networkList.js

@@ -39,32 +39,99 @@ function formatDuration(ms) {
     return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
 }
 /**
- * Column header aligned to the widest request id in the list.
+ * The start of the current page: the earliest document request of the
+ * latest navigation among the requests (its earliest request when its
+ * document was not captured).
  *
- * @param idWidth - Width of the bracketed id column
+ * @param requests - All captured requests (before filters, so the document is among them)
+ * @returns Its times, or undefined when there are no requests
+ */
+export function pageStartOf(requests) {
+    const navigationIds = requests.flatMap((r) => r.navigationId === undefined ? [] : [r.navigationId]);
+    const current = navigationIds.length > 0 ? Math.max(...navigationIds) : undefined;
+    const page = requests.filter((r) => r.navigationId === current);
+    const documents = page.filter((r) => r.resourceType === 'Document');
+    const first = (documents.length > 0 ? documents : page).reduce((earliest, r) => (earliest === undefined || r.timestamp < earliest.timestamp ? r : earliest), undefined);
+    return (first && {
+        timestamp: first.timestamp,
+        ...(first.sentTime !== undefined && { sentTime: first.sentTime }),
+    });
+}
+/**
+ * Milliseconds from the page start to a request's start, in Chrome's time
+ * when both have it (precise), else in wall-clock time.
+ *
+ * @param request - Request
+ * @param pageStart - Start of the current page
+ * @returns Offset (negative for requests of earlier pages)
+ */
+function startOffsetMs(request, pageStart) {
+    if (request.sentTime !== undefined && pageStart.sentTime !== undefined) {
+        return (request.sentTime - pageStart.sentTime) * 1000;
+    }
+    return request.timestamp - pageStart.timestamp;
+}
+/**
+ * Format a request's start for the START column, relative to the current
+ * page's start: tenths of a second up to 100 s, then whole seconds, then
+ * minutes.
+ *
+ * @param request - Request
+ * @param pageStart - Start of the current page (none: `-`)
+ * @returns e.g. "+0.0s", "+1.2s", "+250s", "+17m", "-35.2s" (earlier page)
+ */
+export function formatStartOffset(request, pageStart) {
+    if (!pageStart)
+        return '-';
+    const ms = startOffsetMs(request, pageStart);
+    const seconds = Math.abs(ms) / 1000;
+    const sign = ms < -50 ? '-' : '+';
+    if (seconds < 99.95)
+        return `${sign}${seconds.toFixed(1)}s`;
+    if (seconds < 999.5)
+        return `${sign}${Math.round(seconds)}s`;
+    return `${sign}${Math.floor(seconds / 60)}m`;
+}
+/**
+ * Column header aligned to the widest request id and method in the list.
+ *
+ * @param widths - Column widths
  * @returns Header line
  */
-function formatColumnHeader(idWidth) {
-    return `${'[ID]'.padEnd(idWidth)} STS METH TYP ${'SIZE'.padStart(8)} ${'TIME'.padStart(6)}  URL`;
+function formatColumnHeader(widths) {
+    return `${'[ID]'.padEnd(widths.id)} ${'START'.padStart(6)} STS ${'METH'.padEnd(widths.method)} TYP ${'SIZE'.padStart(8)} ${'TIME'.padStart(6)}  URL`;
 }
 /**
  * Format one request as a table row.
  *
  * @param request - Network request
- * @param verbose - Show full URLs
- * @param idWidth - Width of the bracketed id column (ids vary in length)
+ * @param options - Show full URLs (`verbose`), the page start for START
+ * @param widths - Column widths (ids and methods vary in length)
  * @returns Row text
  */
-function formatRequestLine(request, verbose, idWidth) {
-    const id = `[${request.requestId}]`.padEnd(idWidth);
+function formatRequestLine(request, options, widths) {
+    const id = `[${request.requestId}]`.padEnd(widths.id);
+    const start = formatStartOffset(request, options.pageStart).padStart(6);
     const status = formatStatus(request).padEnd(3);
-    const method = request.method.padEnd(4);
+    const method = request.method.padEnd(widths.method);
     const type = getResourceTypeAbbr(request.resourceType, request.mimeType).padEnd(3);
     const size = formatSize(request.encodedDataLength).padStart(8);
     const time = formatDuration(request.duration).padStart(6);
-    const urlMaxLength = verbose ? 120 : 50;
-    const url = verbose ? request.url : truncateUrl(request.url, urlMaxLength);
-    return `${id} ${status} ${method} ${type} ${size} ${time}  ${url}`;
+    const url = options.verbose ? request.url : truncateUrl(request.url, 50);
+    return `${id} ${start} ${status} ${method} ${type} ${size} ${time}  ${url}`;
+}
+/**
+ * Column widths fitting the rows.
+ *
+ * @param requests - Rows
+ * @param minIdWidth - Narrowest id column
+ * @returns Widths
+ */
+function columnWidths(requests, minIdWidth) {
+    return {
+        id: Math.max(minIdWidth, ...requests.map((r) => r.requestId.length + 2)),
+        method: Math.max('METH'.length, ...requests.map((r) => r.method.length)),
+    };
 }
 /**
  * Header line with how many requests are shown.
@@ -91,12 +158,11 @@ function formatNetworkListHuman(requests, options) {
         fmt.text('No matching requests found.');
         return fmt.build();
     }
-    const idWidth = Math.max('[ID]'.length, ...requests.map((r) => r.requestId.length + 2));
-    fmt.text(formatColumnHeader(idWidth));
+    const widths = columnWidths(requests, '[ID]'.length);
+    fmt.text(formatColumnHeader(widths));
     fmt.separator('─', SEPARATOR_WIDTH);
-    const verbose = options.verbose ?? false;
     for (const request of requests) {
-        fmt.text(formatRequestLine(request, verbose, idWidth));
+        fmt.text(formatRequestLine(request, options, widths));
     }
     return fmt.build();
 }
@@ -107,19 +173,19 @@ const FOLLOW_ID_WIDTH = 14;
  * with the column header the first time.
  *
  * @param requests - Newly finished requests
- * @param options - `header` the first time; `verbose` for full URLs
+ * @param options - `header` the first time; `verbose` for full URLs; the page start for START
  * @returns Text to print (empty when there is nothing new)
  */
 export function formatNetworkFollowRows(requests, options = {}) {
     const fmt = new OutputFormatter();
-    const idWidth = Math.max(FOLLOW_ID_WIDTH, ...requests.map((r) => r.requestId.length + 2));
+    const widths = columnWidths(requests, FOLLOW_ID_WIDTH);
     if (options.header) {
         fmt.text('Streaming network requests... (Ctrl+C to stop)');
-        fmt.text(formatColumnHeader(idWidth));
+        fmt.text(formatColumnHeader(widths));
         fmt.separator('─', SEPARATOR_WIDTH);
     }
     for (const request of requests)
-        fmt.text(formatRequestLine(request, options.verbose ?? false, idWidth));
+        fmt.text(formatRequestLine(request, options, widths));
     return fmt.build();
 }
 /**

package/dist/ui/formatters/status.js

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

package/dist/ui/formatting.d.ts

@@ -72,6 +72,15 @@ export declare function truncateText(text: string, maxLines?: number): string;
  * @returns Shortened URL; non-web URLs (data:, blob:) cut at the end
  */
 export declare function truncateUrl(url: string, maxLength?: number): string;
+/**
+ * Cut text in the middle, marking the cut with "…" (text that fits is
+ * returned as is).
+ *
+ * @param text - Text
+ * @param maxLength - Maximum length
+ * @returns Text, or its start and end around "…"
+ */
+export declare function cutMiddle(text: string, maxLength: number): string;
 export declare function pluralize(count: number, singular: string, plural?: string): string;
 export declare function formatDuration(ms: number): string;
 //# sourceMappingURL=formatting.d.ts.map

package/dist/ui/formatting.js

@@ -167,13 +167,16 @@ export function truncateUrl(url, maxLength = 60) {
 /** Characters of path and query a shortened URL keeps at least besides its host */
 const MIN_URL_END_SHOWN = 12;
 /**
- * Cut text in the middle, marking the cut with "…".
+ * Cut text in the middle, marking the cut with "…" (text that fits is
+ * returned as is).
  *
  * @param text - Text
  * @param maxLength - Maximum length
- * @returns Start and end of the text around "…"
+ * @returns Text, or its start and end around "…"
  */
-function cutMiddle(text, maxLength) {
+export function cutMiddle(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
     const head = Math.ceil((maxLength - 1) / 2);
     return `${text.substring(0, head)}…${text.substring(text.length - (maxLength - 1 - head))}`;
 }

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

@@ -5,7 +5,8 @@
  * cleaning up stale files, and validating command arguments.
  */
 import type { DomFrame, PageLoadingState, PendingRequestInfo } from '../../ipc/protocol/commands.js';
-import type { ElementLayout, FillValueMismatch, LayoutSize, NewMessage, PageLayout, PageNavigation } from '../../ipc/protocol/domTypes.js';
+import type { ElementLayout, FillValueMismatch, LayoutSize, NewMessage, PageLayout, PageNavigation, PendingChanges, ShownElement } from '../../ipc/protocol/domTypes.js';
+import type { InspectVisibility } from '../../ipc/protocol/inspectTypes.js';
 import type { DelegationNote } from '../../runtime/dom/listenerSummary.js';
 import type { WaitCondition, WaitSnapshot } from '../../runtime/dom/waitCondition.js';
 import type { DocumentRequestState, ViewportPosition } from '../../types.js';
@@ -58,12 +59,33 @@ export declare const NO_VISIBLE_EFFECT = "no visible effect observed: no DOM cha
  * Status line of a DOM action: a check mark only for a clean success.
  *
  * @param done - What was done, e.g. "Element Clicked"
- * @param warned - Whether the action has warnings (shown right below)
- * @param noEffect - Whether the action had no visible effect
- * @returns e.g. "✓ Element Clicked", "⚠ Element Clicked (with warnings)" or
+ * @param state - Whether the action has warnings (shown right below), had no
+ *   visible effect, or returned while the page was still changing
+ * @returns e.g. "✓ Element Clicked", "⚠ Element Clicked (with warnings)",
+ *   "⚠ Element Clicked (page still changing)" or
  *   "⚠ Element Clicked (no visible effect observed: no DOM change, requests or navigation within 300 ms)"
  */
-export declare function actionStatusLine(done: string, warned: boolean, noEffect?: boolean): string;
+export declare function actionStatusLine(done: string, state: {
+    warned: boolean;
+    noEffect?: boolean;
+    stillChanging?: boolean;
+}): string;
+/**
+ * Note under the status line of an action that returned while the page was
+ * still changing.
+ *
+ * @param action - What returned, e.g. "click", "key press"
+ * @param pending - What the page was still working on
+ * @returns e.g. "The page was still changing when the click returned (2 requests pending); wait for the result with bdg dom wait <selector>"
+ */
+export declare function stillChangingNote(action: string, pending: PendingChanges): string;
+/**
+ * An element an action showed, for its `Shown:` rows.
+ *
+ * @param element - Shown element
+ * @returns e.g. `div.figcaption "name: user2 View profile"`
+ */
+export declare function shownElementText(element: ShownElement): string;
 /**
  * How an action changed the page's location, for its `Page:` row.
  *
@@ -191,7 +213,7 @@ export declare function layoutPositionLabel(element: LabelledLayout, viewport?:
  * comes from.
  *
  * @param scheme - Light or dark
- * @param emulated - Set with `--color-scheme` (otherwise the system setting)
+ * @param emulated - Set with `--color-scheme` or `page emulate` (otherwise the system setting)
  * @returns e.g. `prefers-color-scheme: dark (from the system setting)`
  */
 export declare function colorSchemeLabel(scheme: string, emulated: boolean): string;
@@ -229,6 +251,48 @@ export declare function layoutHeadline(count: number, listed: number, selector:
  * @returns e.g. `Element at index 0 of the last dom query "h3" (page x,y and size in CSS px):`
  */
 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.";
+/**
+ * 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.
+ *
+ * @param cover - Description of the covering element
+ * @param transparent - The cover paints nothing there
+ * @returns e.g. `covered by div#modal`, `under transparent ul.filters (clicks land on it)`
+ */
+export declare function coverText(cover: string, transparent: boolean | undefined): string;
+/**
+ * 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)
+ * @returns Note
+ */
+export declare function inspectCascadeNote(reason: 'timeout' | 'failed'): 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.
+ *
+ * @returns Badge
+ */
+export declare function inspectDarkThemeBadge(): string;
+/**
+ * Header badges of `bdg dom inspect` for what keeps an element from being seen.
+ *
+ * @param visibility - Not rendered, hidden, offscreen, covered
+ * @returns e.g. `[not rendered: display: none]`, `[offscreen: below]`, `[covered by div#modal]`
+ */
+export declare function inspectVisibilityBadges(visibility: InspectVisibility): string[];
+/**
+ * What `bdg dom inspect` did when several elements matched and no --index was given.
+ *
+ * @param picked - How the match was chosen
+ * @param index - Index of the inspected match
+ * @returns e.g. "inspected the first visible one ([2])"
+ */
+export declare function inspectedMatchAction(picked: 'first-visible' | 'first', index: number): string;
 /**
  * Warning when a selector matched several elements and no --index was given.
  *
@@ -327,6 +391,13 @@ export declare const POINTER_ACTION_DONE: {
     readonly right: "Right-clicked";
     readonly hover: "Hovered";
 };
+/** What each pointer action is called in notes ("when the click returned") */
+export declare const POINTER_ACTION_NOUN: {
+    readonly click: "click";
+    readonly double: "double-click";
+    readonly right: "right-click";
+    readonly hover: "hover";
+};
 /** Headline of each `bdg page` action */
 export declare const PAGE_ACTION_DONE: {
     readonly navigate: "Navigated";
@@ -334,9 +405,11 @@ export declare const PAGE_ACTION_DONE: {
     readonly back: "Went back";
     readonly forward: "Went forward";
 };
-/** Help text of the `bdg page` history commands */
 /** Description of `bdg page info` */
 export declare const PAGE_INFO_DESCRIPTION = "Show the URL and title of the session page";
+/** Description of `bdg page emulate` */
+export declare const PAGE_EMULATE_DESCRIPTION = "Change the viewport or color scheme mid-session (like --viewport and --color-scheme at start), or --reset both";
+/** Help text of the `bdg page` history commands */
 export declare const PAGE_ACTION_DESCRIPTIONS: {
     readonly reload: "Reload the page";
     readonly back: "Go back one page (like the browser button)";
@@ -562,5 +635,48 @@ export declare function sessionStillActiveSuggestion(session: string | null): st
  * @returns Multi-line help message with examples
  * */
 export declare function startCommandHelpMessage(): string;
+/**
+ * `bdg page emulate` without anything to change.
+ *
+ * @returns Message and suggestion
+ */
+export declare function pageEmulateNothingError(): {
+    message: string;
+    suggestion: string;
+};
+/**
+ * Lines of `bdg page emulate`: what is emulated and what the page now has.
+ *
+ * @param result - Emulation and page appearance
+ * @returns Label/value pairs
+ */
+export declare function pageEmulationLines(result: {
+    emulated: {
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        colorScheme?: string;
+    };
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    colorScheme?: string;
+}): Array<[string, string]>;
+/**
+ * Header badge of `bdg dom inspect` while CSS transitions or animations run
+ * on the element: the values read are mid-way.
+ *
+ * @param animating - Transitioned properties and animation names
+ * @returns e.g. `[animating: background-color; values are mid-way, inspect again]`
+ */
+export declare function inspectAnimatingBadge(animating: readonly string[]): string;
+/**
+ * `--why` note on a computed value read during its transition.
+ *
+ * @returns Note
+ */
+export declare function inspectMidTransitionNote(): string;
 export {};
 //# sourceMappingURL=commands.d.ts.map