browser-debugger-cli 0.9.0 → 0.10.0

package/dist/ui/messages/commands.js

@@ -82,15 +82,46 @@ export const NO_VISIBLE_EFFECT = 'no visible effect observed: no DOM change, req
  * 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 function actionStatusLine(done, warned, noEffect = false) {
-    if (noEffect)
+export function actionStatusLine(done, state) {
+    if (state.noEffect)
         return `⚠ ${done} (${NO_VISIBLE_EFFECT})`;
-    return warned ? `⚠ ${done} (with warnings)` : `✓ ${done}`;
+    const notes = [state.warned && 'with warnings', state.stillChanging && 'page still changing'];
+    const shown = notes.filter((note) => typeof note === 'string');
+    return shown.length > 0 ? `⚠ ${done} (${shown.join('; ')})` : `✓ ${done}`;
+}
+/**
+ * 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 function stillChangingNote(action, pending) {
+    const parts = [
+        pending.requests !== undefined && `${pluralize(pending.requests, 'request')} pending`,
+        pending.navigation && 'a new page still loading',
+        pending.loading !== undefined && `loading indicator ${pending.loading} shown`,
+        pending.domChanging && 'DOM still changing',
+        pending.busy && 'page busy running a script',
+    ].filter((part) => typeof part === 'string');
+    const wait = sessionCommand('bdg dom wait <selector>');
+    return `The page was still changing when the ${action} returned (${parts.join(', ')}); wait for the result with ${wait}`;
+}
+/**
+ * An element an action showed, for its `Shown:` rows.
+ *
+ * @param element - Shown element
+ * @returns e.g. `div.figcaption "name: user2 View profile"`
+ */
+export function shownElementText(element) {
+    return `${element.element} "${element.text}"`;
 }
 /**
  * How an action changed the page's location, for its `Page:` row.
@@ -340,11 +371,11 @@ export function layoutPositionLabel(element, 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 function colorSchemeLabel(scheme, emulated) {
-    const source = emulated ? 'emulated with --color-scheme' : 'from the system setting';
+    const source = emulated ? 'emulated' : 'from the system setting';
     return `prefers-color-scheme: ${scheme} (${source})`;
 }
 /**
@@ -393,6 +424,87 @@ export function layoutHeadline(count, listed, selector) {
 export function indexLayoutHeadline(target) {
     return `Element at ${target} (page x,y and size in CSS px):`;
 }
+/** Help text explaining `bdg dom inspect`'s output notation */
+export const INSPECT_OUTPUT_LEGEND = `
+Output notation:
+  WxH @x,y        rendered border box size and page position (CSS px, no unit)
+  m / p / b       margin / padding / border widths, 1-4 values in CSS order (top right bottom left)
+  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)
+  contrast 4.47   WCAG ratio, rounded down, against the background behind the text
+  (+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)
+  ← sel (file:N)  --rules: the declaration that sets the value (file:line, or file:line:column in
+                  minified files); 'over X': rules it beats; '= v': the value of a var() expression
+  ✓ / ✗           --why: the winning declaration / ones it beats, highest precedence first;
+                  [0,2,0]: selector specificity (ids, classes, types); indented --name lines: where
+                  the winner's custom properties are set
+Sessions 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 function coverText(cover, transparent) {
+    return transparent ? `under transparent ${cover} (clicks land on it)` : `covered by ${cover}`;
+}
+/**
+ * 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 function inspectCascadeNote(reason) {
+    return reason === 'timeout'
+        ? "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';
+}
+/**
+ * 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 function inspectDarkThemeBadge() {
+    return '[dark theme from system; --color-scheme light for light]';
+}
+/**
+ * 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 function inspectVisibilityBadges(visibility) {
+    const reason = (text) => (text ? `: ${text}` : '');
+    if (visibility.notRendered) {
+        return [`[not rendered${reason(visibility.hidden?.replace(/^not rendered \((.*)\)$/, '$1'))}]`];
+    }
+    return [
+        visibility.hidden && `[hidden: ${visibility.hidden}]`,
+        visibility.offscreen && `[offscreen: ${visibility.offscreen}]`,
+        visibility.coveredBy && `[${coverText(visibility.coveredBy, visibility.coverTransparent)}]`,
+    ].filter((badge) => Boolean(badge));
+}
+/**
+ * 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 function inspectedMatchAction(picked, index) {
+    return picked === 'first-visible'
+        ? `inspected the first visible one ([${index}])`
+        : 'inspected the first';
+}
 /**
  * Warning when a selector matched several elements and no --index was given.
  *
@@ -536,6 +648,13 @@ export const POINTER_ACTION_DONE = {
     right: 'Right-clicked',
     hover: 'Hovered',
 };
+/** What each pointer action is called in notes ("when the click returned") */
+export const POINTER_ACTION_NOUN = {
+    click: 'click',
+    double: 'double-click',
+    right: 'right-click',
+    hover: 'hover',
+};
 /** Headline of each `bdg page` action */
 export const PAGE_ACTION_DONE = {
     navigate: 'Navigated',
@@ -543,9 +662,11 @@ export const PAGE_ACTION_DONE = {
     back: 'Went back',
     forward: 'Went forward',
 };
-/** Help text of the `bdg page` history commands */
 /** Description of `bdg page info` */
 export const PAGE_INFO_DESCRIPTION = 'Show the URL and title of the session page';
+/** Description of `bdg page emulate` */
+export 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 const PAGE_ACTION_DESCRIPTIONS = {
     reload: 'Reload the page',
     back: 'Go back one page (like the browser button)',
@@ -638,7 +759,7 @@ export function pageLoadingWarning(state) {
  * Help of `dom click`/`submit`: they wait for the network only, so results a
  * page shows later (timers, spinners, animations) are waited for with `dom wait`.
  */
-export const CLICK_RESULT_WAIT_HELP = joinLines('', 'Waits only for the requests the action starts (150 ms idle, up to 2 s), not for', 'results the page shows later (timers, spinners, animations). Wait for those with:', "  bdg dom wait '#result' --visible          # or --text 'Saved', or '.spinner' --gone");
+export const CLICK_RESULT_WAIT_HELP = joinLines('', 'Waits only for the requests the action starts (150 ms idle, up to 2 s), not for', 'results the page shows later (timers, spinners, animations); the result says', '"page still changing" when it saw such work pending. Wait for those with:', "  bdg dom wait '#result' --visible          # or --text 'Saved', or '.spinner' --gone");
 /** Examples in the help of `bdg dom wait` */
 export const WAIT_HELP_EXAMPLES = joinLines('', 'Examples:', "  bdg dom wait '#finish' --visible          # timer-based loading (a spinner, then the result)", "  bdg dom wait '.toast' --text 'Saved'      # a match containing the text", "  bdg dom wait '#loading' --gone            # the spinner went away", '  bdg dom wait --load                       # the page finished loading');
 /**
@@ -881,4 +1002,54 @@ export function sessionStillActiveSuggestion(session) {
 export function startCommandHelpMessage() {
     return joinLines('', buildAgentDiscoveryHelp(), '', buildCommonTaskExamples(), '', buildUrlExamples(), '', buildSessionManagementReminder(), '', 'Not sure which command? Start a session to see all available commands:', '  bdg <url>', '');
 }
+/**
+ * `bdg page emulate` without anything to change.
+ *
+ * @returns Message and suggestion
+ */
+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',
+    };
+}
+/**
+ * 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 function pageEmulationLines(result) {
+    const size = (v) => `${v.width}x${v.height}`;
+    const { emulated } = result;
+    return [
+        ['Viewport', emulated.viewport ? size(emulated.viewport) : 'the browser window'],
+        ...(result.viewport
+            ? [['Layout', `${size(result.viewport)} (without scrollbars)`]]
+            : []),
+        [
+            'Scheme',
+            emulated.colorScheme ??
+                `system setting${result.colorScheme ? ` (${result.colorScheme})` : ''}`,
+        ],
+    ];
+}
+/**
+ * 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 function inspectAnimatingBadge(animating) {
+    return `[animating: ${animating.join(', ')}; values are mid-way, inspect again]`;
+}
+/**
+ * `--why` note on a computed value read during its transition.
+ *
+ * @returns Note
+ */
+export function inspectMidTransitionNote() {
+    return '(mid-transition: inspect again for the final value)';
+}
 //# sourceMappingURL=commands.js.map

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

@@ -15,4 +15,18 @@ export declare function followingNetworkMessage(): string;
  * @returns Status message for stderr
  */
 export declare function stoppedFollowingNetworkMessage(): string;
+/**
+ * Note after a header value the server sent more than once.
+ *
+ * @param count - Times it was sent
+ * @returns e.g. `(sent 2 times)`
+ */
+export declare function headerRepeatedNote(count: number): string;
+/**
+ * Note after a loopback remote address of a request to another host and
+ * port: Chrome probably connected to a proxy on this machine, not the server.
+ *
+ * @returns Note text
+ */
+export declare function localProxyNote(): string;
 //# sourceMappingURL=networkMessages.d.ts.map

package/dist/ui/messages/networkMessages.js

@@ -19,4 +19,22 @@ export function followingNetworkMessage() {
 export function stoppedFollowingNetworkMessage() {
     return '\nStopped following network requests.';
 }
+/**
+ * Note after a header value the server sent more than once.
+ *
+ * @param count - Times it was sent
+ * @returns e.g. `(sent 2 times)`
+ */
+export function headerRepeatedNote(count) {
+    return `(sent ${count} times)`;
+}
+/**
+ * Note after a loopback remote address of a request to another host and
+ * port: Chrome probably connected to a proxy on this machine, not the server.
+ *
+ * @returns Note text
+ */
+export function localProxyNote() {
+    return '(loopback; likely a local proxy)';
+}
 //# sourceMappingURL=networkMessages.js.map

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

@@ -77,4 +77,18 @@ export declare function lastSessionEndText(end: {
     reason: string;
     endedAt: number;
 }): string;
+/**
+ * Note after a failed start whose daemon had not exited when bdg stopped waiting.
+ *
+ * @param pid - Daemon PID, when known
+ * @param waitedMs - How long bdg waited
+ * @returns Note
+ */
+export declare function daemonStillExitingHint(pid: number | undefined, waitedMs: number): string;
+/**
+ * What to do about a daemon still shutting down after a failed start.
+ *
+ * @returns Suggestion
+ */
+export declare function daemonStillExitingSuggestion(): string;
 //# sourceMappingURL=session.d.ts.map

package/dist/ui/messages/session.js

@@ -6,6 +6,7 @@
  */
 import { joinLines } from '../formatting.js';
 import { pageLoadingWarning } from './commands.js';
+import { sessionCommand } from './sessionCommand.js';
 /**
  * Lines shown under the target in both the full and the quiet start output:
  * the session name, an HTTP error of the page, a page still loading, and
@@ -96,4 +97,23 @@ export function lastSessionEndText(end) {
     const at = new Date(end.endedAt).toLocaleTimeString();
     return `The last session ended at ${at}: ${why[end.reason] ?? end.reason}`;
 }
+/**
+ * Note after a failed start whose daemon had not exited when bdg stopped waiting.
+ *
+ * @param pid - Daemon PID, when known
+ * @param waitedMs - How long bdg waited
+ * @returns Note
+ */
+export function daemonStillExitingHint(pid, waitedMs) {
+    const daemon = pid === undefined ? 'The daemon' : `The daemon (PID ${pid})`;
+    return `${daemon} was still shutting down after ${waitedMs / 1000}s`;
+}
+/**
+ * What to do about a daemon still shutting down after a failed start.
+ *
+ * @returns Suggestion
+ */
+export function daemonStillExitingSuggestion() {
+    return `check with bdg sessions, or end it with ${sessionCommand('bdg cleanup --force')}`;
+}
 //# sourceMappingURL=session.js.map

package/dist/utils/async.d.ts

@@ -15,4 +15,13 @@ export declare function delay(ms: number): Promise<void>;
  * @returns The promise's result, or undefined when the time ran out first
  */
 export declare function raceTimeout<T>(promise: Promise<T>, ms: number): Promise<T | undefined>;
+/**
+ * Poll a condition until it holds or a time runs out.
+ *
+ * @param condition - Checked first right away, then every `pollMs`
+ * @param timeoutMs - Milliseconds to wait at most
+ * @param pollMs - Milliseconds between checks
+ * @returns True when the condition held, false when the time ran out
+ */
+export declare function waitUntil(condition: () => boolean, timeoutMs: number, pollMs?: number): Promise<boolean>;
 //# sourceMappingURL=async.d.ts.map

package/dist/utils/async.js

@@ -28,4 +28,21 @@ export async function raceTimeout(promise, ms) {
         clearTimeout(timer);
     }
 }
+/**
+ * Poll a condition until it holds or a time runs out.
+ *
+ * @param condition - Checked first right away, then every `pollMs`
+ * @param timeoutMs - Milliseconds to wait at most
+ * @param pollMs - Milliseconds between checks
+ * @returns True when the condition held, false when the time ran out
+ */
+export async function waitUntil(condition, timeoutMs, pollMs = 25) {
+    const deadline = Date.now() + timeoutMs;
+    while (!condition()) {
+        if (Date.now() >= deadline)
+            return false;
+        await delay(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+    }
+    return true;
+}
 //# sourceMappingURL=async.js.map

package/dist/utils/color.d.ts

@@ -0,0 +1,84 @@
+/**
+ * CSS colors as `bdg dom inspect` reports them: parsed from the computed
+ * values Chrome returns (`rgb()`/`rgba()`, and `lab()`, `lch()`, `oklab()`,
+ * `oklch()` and `color()` as Tailwind v4 and other modern CSS leave them),
+ * converted to sRGB the way Chrome paints them on an sRGB screen (channels
+ * outside the gamut are clipped), and printed as short hex. Also the WCAG
+ * contrast math over alpha-composited backgrounds.
+ *
+ * Conversions follow the CSS Color 4 sample code (Bradford D50 → D65, the
+ * OKLab matrices of Björn Ottosson).
+ */
+/** A color in sRGB: channels 0-1 (unclipped until printed), alpha 0-1 */
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * Parse a CSS color as Chrome computes it.
+ *
+ * @param value - e.g. `rgba(0, 0, 0, 0.2)`, `oklch(0.373 0.034 259.733)`, `#fff`, `transparent`
+ * @returns The color in sRGB, or null for anything else (`currentcolor`, keywords, gradients)
+ */
+export declare function parseColor(value: string): Rgba | null;
+/**
+ * A color as short hex: `#rgb` when every channel's digits repeat, else
+ * `#rrggbb`; `#rrggbbaa` when translucent; `transparent` at alpha 0.
+ *
+ * @param color - Color in sRGB
+ * @returns e.g. `#fff`, `#364153`, `#00000033`
+ */
+export declare function toHex(color: Rgba): string;
+/**
+ * A computed color as short hex ({@link toHex}).
+ *
+ * @param value - Computed color
+ * @returns Hex, or the value unchanged when it is not a color
+ */
+export declare function hexColor(value: string): string;
+/**
+ * Replace every color inside a value with its hex ({@link toHex}).
+ *
+ * @param value - e.g. `rgba(0, 0, 0, 0.2) 0px 1px 2px 0px`
+ * @returns e.g. `#00000033 0px 1px 2px 0px`
+ */
+export declare function hexColorsIn(value: string): string;
+/**
+ * Paint a color over another (source-over alpha compositing).
+ *
+ * @param top - Color on top
+ * @param bottom - Color below
+ * @returns The color a user sees
+ */
+export declare function composite(top: Rgba, bottom: Rgba): Rgba;
+/**
+ * WCAG relative luminance of an opaque color (clipped to sRGB).
+ *
+ * @param color - Color
+ * @returns Luminance 0-1
+ */
+export declare function relativeLuminance(color: Rgba): number;
+/**
+ * WCAG contrast ratio of text over an opaque background; translucent text
+ * is composited over the background first.
+ *
+ * @param text - Text color
+ * @param background - Opaque background color
+ * @returns Ratio 1-21
+ */
+export declare function contrastRatio(text: Rgba, background: Rgba): number;
+/** WCAG 2 conformance of a contrast ratio */
+export type ContrastLevel = 'AAA' | 'AA' | 'AA large' | 'fail';
+/**
+ * WCAG 2 level a contrast ratio reaches. Large text (24px, or 18.66px bold)
+ * needs 4.5 for AAA and 3 for AA; other text 7 and 4.5.
+ *
+ * @param ratio - Contrast ratio
+ * @param fontSize - Font size in px
+ * @param fontWeight - Font weight
+ * @returns Level reached
+ */
+export declare function contrastLevel(ratio: number, fontSize: number, fontWeight: number): ContrastLevel;
+//# sourceMappingURL=color.d.ts.map