browser-debugger-cli 0.8.0 → 0.10.0

package/dist/utils/cssValues.js

@@ -0,0 +1,236 @@
+/**
+ * Normalization of computed CSS values for `bdg dom inspect`: px as numbers
+ * rounded to one decimal (no unit), colors as hex, 1-4 value shorthands,
+ * shadow layers, grid tracks with `repeat()`, transforms decomposed from the
+ * matrices Chrome computes, and the first font family.
+ */
+import { hexColor, hexColorsIn } from './color.js';
+/** px lengths inside a value */
+const PX_IN_VALUE = /(-?\d*\.?\d+(?:e-?\d+)?)px\b/g;
+/**
+ * Round to one decimal (and drop `-0`).
+ *
+ * @param value - Number
+ * @returns e.g. 12.5, 0
+ */
+export function round1(value) {
+    const rounded = Math.round(value * 10) / 10;
+    return Object.is(rounded, -0) ? 0 : rounded;
+}
+/**
+ * A px value as a number.
+ *
+ * @param value - Computed value, e.g. `12.5px`
+ * @returns Rounded number, or undefined when the value is not a single px length
+ */
+export function pxNumber(value) {
+    const match = /^(-?\d*\.?\d+(?:e-?\d+)?)px$/.exec((value ?? '').trim());
+    return match ? round1(Number(match[1])) : undefined;
+}
+/**
+ * A length as {@link CssLength}.
+ *
+ * @param value - Computed value
+ * @returns Number for px, else the value as text
+ */
+export function cssLength(value) {
+    return pxNumber(value) ?? normalizeCssValue(value ?? '');
+}
+/**
+ * A computed value with px lengths as rounded unitless numbers and colors as
+ * hex, e.g. `rgba(0, 0, 0, 0.2) 0px 1.25px 2px` → `#00000033 0 1.3 2`.
+ *
+ * @param value - Computed value
+ * @returns Normalized value
+ */
+export function normalizeCssValue(value) {
+    return hexColorsIn(value)
+        .replace(PX_IN_VALUE, (_match, number) => String(round1(Number(number))))
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * 1-4 values the way CSS shorthands write them (top, right, bottom, left).
+ *
+ * @param sides - Top, right, bottom, left
+ * @returns e.g. `10`, `10 0`, `10 0 1`, `1 2 3 4`
+ */
+export function sidesShorthand(sides) {
+    const [top, right, bottom, left] = sides.map(String);
+    if (top === right && right === bottom && bottom === left)
+        return `${top}`;
+    if (top === bottom && right === left)
+        return `${top} ${right}`;
+    if (right === left)
+        return `${top} ${right} ${bottom}`;
+    return `${top} ${right} ${bottom} ${left}`;
+}
+/**
+ * Split a value at commas (or another separator) outside parentheses.
+ *
+ * @param value - e.g. `rgb(0, 0, 0) 0px 1px, rgb(1, 1, 1) 0px 2px`
+ * @param separator - Character to split at
+ * @returns Parts, trimmed
+ */
+export function splitTopLevel(value, separator = ',') {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const char of value) {
+        if (char === '(' || char === '[')
+            depth++;
+        if (char === ')' || char === ']')
+            depth--;
+        if (char === separator && depth === 0) {
+            parts.push(current.trim());
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    return parts;
+}
+/**
+ * The first family of a `font-family` list, without quotes.
+ *
+ * @param fontFamily - e.g. `"DM Sans", Arial, sans-serif`
+ * @returns e.g. `DM Sans`
+ */
+export function firstFontFamily(fontFamily) {
+    const first = splitTopLevel(fontFamily)[0] ?? '';
+    return first.replace(/^["']|["']$/g, '');
+}
+/**
+ * Parse one shadow layer as Chrome computes it (`<color> <x> <y> <blur> [<spread>] [inset]`).
+ *
+ * @param layer - e.g. `rgba(0, 0, 0, 0.2) 0px 1px 2px 0px`
+ * @returns The layer, or undefined when it does not parse
+ */
+function parseShadowLayer(layer) {
+    const color = /^((?:rgba?|lab|lch|oklab|oklch|color)\([^()]*\)|#[0-9a-f]{3,8}|[a-z]+)\s+/i.exec(layer);
+    const rest = (color ? layer.slice(color[0].length) : layer).split(/\s+/);
+    const lengths = rest.map(pxNumber).filter((n) => n !== undefined);
+    if (lengths.length < 2)
+        return undefined;
+    return {
+        x: lengths[0] ?? 0,
+        y: lengths[1] ?? 0,
+        blur: lengths[2] ?? 0,
+        spread: lengths[3] ?? 0,
+        color: hexColor(color?.[1] ?? 'currentcolor'),
+        inset: rest.includes('inset'),
+    };
+}
+/**
+ * The visible layers of a shadow: transparent layers and layers with no
+ * offset, blur or spread (Tailwind's ring placeholders) are left out.
+ *
+ * @param value - Computed `box-shadow` or `text-shadow`
+ * @returns Layers, outermost first
+ */
+export function parseShadows(value) {
+    if (!value || value === 'none')
+        return [];
+    return splitTopLevel(value)
+        .map(parseShadowLayer)
+        .filter((layer) => layer !== undefined)
+        .filter((layer) => layer.color !== 'transparent' &&
+        (layer.x !== 0 || layer.y !== 0 || layer.blur !== 0 || layer.spread !== 0));
+}
+/**
+ * A shadow layer as text, e.g. `#00000033 0 1 2 0`, `inset #000 0 0 0 1`.
+ *
+ * @param layer - Shadow layer
+ * @param withSpread - Include the spread (box shadows)
+ * @returns Text
+ */
+export function shadowText(layer, withSpread = true) {
+    const lengths = [layer.x, layer.y, layer.blur, ...(withSpread ? [layer.spread] : [])];
+    return `${layer.inset ? 'inset ' : ''}${layer.color} ${lengths.join(' ')}`;
+}
+/**
+ * Grid tracks with runs of equal sizes written as `repeat()`.
+ *
+ * @param value - Computed `grid-template-columns`/`rows`, e.g. `100px 100px 100px 50px`
+ * @returns e.g. `repeat(3,100) 50`; `none` stays `none`
+ */
+export function compressTracks(value) {
+    if (!value || value === 'none')
+        return value;
+    const tracks = splitTopLevel(value, ' ').map((token) => normalizeCssValue(token));
+    const parts = [];
+    for (let i = 0; i < tracks.length;) {
+        let run = 1;
+        while (tracks[i + run] === tracks[i])
+            run++;
+        parts.push(run > 1 ? `repeat(${run},${tracks[i]})` : `${tracks[i]}`);
+        i += run;
+    }
+    return parts.join(' ');
+}
+/**
+ * Round a number for a transform (3 decimals at most).
+ *
+ * @param value - Number
+ * @returns Rounded number
+ */
+function round3(value) {
+    const rounded = Math.round(value * 1000) / 1000;
+    return Object.is(rounded, -0) ? 0 : rounded;
+}
+/**
+ * A 2D matrix as translate/rotate/scale when it is one (no skew).
+ *
+ * @param m - a, b, c, d, e, f
+ * @returns e.g. `translate(10,20) rotate(45deg)`, or undefined for a skew
+ */
+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 scaleY = scaleX === 0 ? 0 : (a * d - b * c) / scaleX;
+    const angle = round3((Math.atan2(b, a) * 180) / Math.PI);
+    const parts = [];
+    if (e !== 0 || f !== 0)
+        parts.push(`translate(${round1(e)},${round1(f)})`);
+    if (angle !== 0)
+        parts.push(`rotate(${angle}deg)`);
+    const [sx, sy] = [round3(scaleX), round3(scaleY)];
+    if (sx !== 1 || sy !== 1)
+        parts.push(sx === sy ? `scale(${sx})` : `scale(${sx},${sy})`);
+    return parts.length > 0 ? parts.join(' ') : 'none';
+}
+/**
+ * A computed transform in readable form: a 2D matrix as
+ * translate/rotate/scale, other matrices with rounded numbers.
+ *
+ * @param value - Computed `transform`, e.g. `matrix(1, 0, 0, 1, 10, 20)`
+ * @returns e.g. `translate(10,20)`; `none` when it does nothing
+ */
+export function readableTransform(value) {
+    const match = /^(matrix|matrix3d)\((.*)\)$/.exec(value.trim());
+    if (!match)
+        return normalizeCssValue(value);
+    const numbers = (match[2] ?? '').split(',').map((n) => Number(n.trim()));
+    const decomposed = match[1] === 'matrix' ? decomposeMatrix(numbers) : undefined;
+    return decomposed ?? `${match[1]}(${numbers.map(round3).join(',')})`;
+}
+/**
+ * The file name of a URL in a CSS value: `url("https://x.com/a/b.png?v=1")` → `url(b.png)`;
+ * `data:` URLs become `url(data:…)`.
+ *
+ * @param value - Computed value with `url()`s
+ * @returns The value with short URLs
+ */
+export function shortUrls(value) {
+    return value.replace(/url\((["']?)(.*?)\1\)/g, (_match, _quote, url) => {
+        if (url.startsWith('data:'))
+            return 'url(data:…)';
+        const name = url.split(/[?#]/)[0]?.split('/').filter(Boolean).pop() ?? url;
+        return `url(${name})`;
+    });
+}
+//# sourceMappingURL=cssValues.js.map

package/dist/utils/http.d.ts

@@ -30,13 +30,34 @@ export interface FetchCDPTargetsOptions {
  * - Network errors are logged to help diagnose Chrome connectivity issues
  */
 export declare function fetchCDPTargets(port?: number, logger?: Logger, options?: FetchCDPTargetsOptions): Promise<CDPTarget[]>;
+/**
+ * What answers on a DevTools HTTP endpoint: a Chrome (with its browser-level
+ * WebSocket URL), an HTTP server that is not DevTools, or nothing.
+ */
+export type DevToolsProbe = {
+    kind: 'devtools';
+    wsUrl: string;
+} | {
+    kind: 'not-devtools';
+} | {
+    kind: 'unreachable';
+};
+/**
+ * Ask an endpoint for its DevTools version (`/json/version`).
+ *
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - Host and HTTPS
+ * @returns What answered
+ */
+export declare function probeDevToolsEndpoint(port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'host' | 'secure'>): Promise<DevToolsProbe>;
 /**
  * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
  * @param options - Host and HTTPS
- * @returns The URL, or null if Chrome could not be reached
+ * @returns The URL, or null if no Chrome answered
  */
 export declare function fetchBrowserWsUrl(port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'host' | 'secure'>): Promise<string | null>;
 /**

package/dist/utils/http.js

@@ -63,26 +63,45 @@ export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger, options)
     }
 }
 /**
- * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
+ * Ask an endpoint for its DevTools version (`/json/version`).
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
  * @param options - Host and HTTPS
- * @returns The URL, or null if Chrome could not be reached
+ * @returns What answered
  */
-export async function fetchBrowserWsUrl(port, logger, options) {
+export async function probeDevToolsEndpoint(port, logger, options) {
     const url = `${options?.secure ? 'https' : 'http'}://${options?.host ?? HTTP_LOCALHOST}:${port}/json/version`;
+    let response;
     try {
-        const response = await fetch(url, { signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS) });
-        if (!response.ok)
-            return null;
-        const data = (await response.json());
-        return typeof data.webSocketDebuggerUrl === 'string' ? data.webSocketDebuggerUrl : null;
+        response = await fetch(url, { signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS) });
     }
     catch (error) {
         logger?.debug(`Chrome version request failed: ${getErrorMessage(error)} (${url})`);
-        return null;
+        return { kind: 'unreachable' };
+    }
+    try {
+        const data = (await response.json());
+        const wsUrl = data?.webSocketDebuggerUrl;
+        if (response.ok && typeof wsUrl === 'string')
+            return { kind: 'devtools', wsUrl };
+    }
+    catch (error) {
+        logger?.debug(`Chrome version response is not JSON: ${getErrorMessage(error)} (${url})`);
     }
+    return { kind: 'not-devtools' };
+}
+/**
+ * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
+ *
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - Host and HTTPS
+ * @returns The URL, or null if no Chrome answered
+ */
+export async function fetchBrowserWsUrl(port, logger, options) {
+    const probe = await probeDevToolsEndpoint(port, logger, options);
+    return probe.kind === 'devtools' ? probe.wsUrl : null;
 }
 /**
  * Fetch specific CDP target by ID from Chrome's HTTP API.

package/dist/utils/selectorFilters.d.ts

@@ -3,12 +3,16 @@
  * `:visible`.
  *
  * They are not CSS, so the selector is split here (in Node) into the CSS the
- * browser runs and the filters the page applies to its matches. They are only
- * supported at the end of the last compound of each selector in a list
- * (`li.item:has-text("x"):visible`, `a:text-is("Home"), button:visible`):
- * there they narrow down the elements the CSS part matched. Anywhere else
- * (`div:has-text("x") > button`, `:not(:visible)`) they would have to be
- * evaluated inside the browser's selector matching, which bdg cannot do.
+ * browser runs and the filters the page applies to its matches. A filter
+ * applies to the compound it is written in (`li.item:has-text("x"):visible`,
+ * `a:visible.active`). On the last compound it narrows down the matches; on an
+ * earlier one it scopes the rest of the selector, which is then matched under
+ * each element passing the filter: `li:has-text("Buy milk") .toggle` is the
+ * `.toggle` inside the row that says "Buy milk". Only descendant and child
+ * combinators can follow a filtered compound. Inside `:has()` filters test
+ * what an element contains (`li:has(label:text-is("x"))`); inside other
+ * pseudo-classes (`:not(:visible)`) they would have to be evaluated by the
+ * browser's selector matching, which bdg cannot do.
  */
 /** Filter applied in the page to the elements the CSS part matched. */
 export type SelectorFilter = {
@@ -19,11 +23,27 @@ export type SelectorFilter = {
     text: string;
 } | {
     kind: 'visible';
+} | {
+    kind: 'has';
+    selectors: ScopedStep[][];
 };
-/** One selector of a selector list: the CSS to run and the filters for its matches. */
+/** Combinators a scoped step can follow: descendant (` `) and child (`>`). */
+export type ScopeCombinator = ' ' | '>';
+/** CSS matched under a scope element (`:scope <combinator> <css>`), then filtered. */
+export interface ScopedStep {
+    combinator: ScopeCombinator;
+    css: string;
+    filters: SelectorFilter[];
+}
+/**
+ * One selector of a selector list: the CSS to run and the filters for its
+ * matches; `steps` (when a filtered compound is not the last) are matched
+ * under each of them in turn, and the last step's matches are the result.
+ */
 export interface SelectorPart {
     css: string;
     filters: SelectorFilter[];
+    steps?: ScopedStep[];
 }
 /**
  * Split a selector into the CSS part and filters of each selector of its
@@ -31,9 +51,17 @@ export interface SelectorPart {
  *
  * @param selector - Selector as the user gave it
  * @returns The parts, or null for plain CSS (no filters anywhere), which runs unchanged
- * @throws CommandError (81) for a filter that is not at the end, or a malformed one
+ * @throws CommandError (81) for a misplaced or malformed filter
  */
 export declare function parseSelectorFilters(selector: string): SelectorPart[] | null;
+/**
+ * The parts with every `:visible` filter removed, to count what only
+ * visibility excluded.
+ *
+ * @param parts - Parsed selector parts
+ * @returns Parts without `:visible`, or null when they have none
+ */
+export declare function withoutVisibleFilters(parts: SelectorPart[]): SelectorPart[] | null;
 /**
  * Split a selector list at its top-level commas (not inside quotes,
  * attribute brackets or parentheses).
@@ -42,4 +70,16 @@ export declare function parseSelectorFilters(selector: string): SelectorPart[] |
  * @returns The selectors, untrimmed
  */
 export declare function splitSelectorList(selector: string): string[];
+/**
+ * The compounds of a complex selector before its last one, with the rest
+ * after each (`mdn-search-modal form` gives `mdn-search-modal` with `form`):
+ * the ancestors a selector would have to cross shadow roots through.
+ *
+ * @param selector - One selector (a list gives nothing)
+ * @returns Leading compounds and the selector after each
+ */
+export declare function leadingCompounds(selector: string): Array<{
+    compound: string;
+    rest: string;
+}>;
 //# sourceMappingURL=selectorFilters.d.ts.map