browser-debugger-cli 0.11.0 → 0.12.0

package/dist/runtime/dom/inspectPaintModel.js

@@ -8,7 +8,7 @@
  * canvas).
  */
 import { composite, contrastLevel, contrastRatio, hexColor, parseColor, toHex, } from '../../utils/color.js';
-import { cssLength, firstFontFamily, normalizeCssValue, parseShadows, pxNumber, readableTransform, shadowText, shortUrls, splitTopLevel, } from '../../utils/cssValues.js';
+import { cssLength, firstFontFamily, normalizeCssValue, parseShadows, pxNumber, readableTransform, shadowText, shortUrls, sidesShorthand, splitTopLevel, } from '../../utils/cssValues.js';
 /** Background images and gradients are shown at most this long */
 const IMAGE_TEXT_LENGTH = 140;
 /** Page canvas colors (light and dark color-scheme) */
@@ -16,62 +16,125 @@ const CANVAS = {
     light: { r: 1, g: 1, b: 1, a: 1 },
     dark: { r: 0x12 / 255, g: 0x12 / 255, b: 0x12 / 255, a: 1 },
 };
+/** CSS generic font families: the browser picks a font for them */
+const GENERIC_FAMILIES = new Set([
+    'serif',
+    'sans-serif',
+    'monospace',
+    'cursive',
+    'fantasy',
+    'system-ui',
+    'ui-serif',
+    'ui-sans-serif',
+    'ui-monospace',
+    'ui-rounded',
+    'math',
+    'emoji',
+    'fangsong',
+    '-apple-system',
+    'blinkmacsystemfont',
+]);
 /**
- * The font the text was rendered with, when it is not a face of the first
- * family (a fallback: `DM Sans 9pt` is a face of `DM Sans`, `Liberation Sans`
- * is not one of `Arial`), and whether it is a web font. Names
- * that are not readable (sites that scramble a web font's internal name)
- * are left out.
+ * The font the text was rendered with and whether it is a web font. For a
+ * generic first family, the font it resolved to (`resolved`). Otherwise
+ * `rendered` only when it is a fallback: not a face of the first family
+ * (`DM Sans 9pt` is a face of `DM Sans`, `Liberation Sans` is not one of
+ * `Arial`), and the first family is not a web font the page loaded (whose
+ * file may give any internal name: `Copyright Klim Type Foundry`, or the
+ * local font a `src: local()` points at). Names that are not readable
+ * (sites that scramble a web font's internal name) are left out.
  *
  * @param family - First family of `font-family`
  * @param fonts - Platform fonts of the text
- * @returns `rendered` and `webfont` fields
+ * @param familyLoaded - The first family is a loaded web font
+ * @returns `rendered`, `resolved` and `webfont` fields
  */
-export function renderedFont(family, fonts) {
+export function renderedFont(family, fonts, familyLoaded = false) {
     const primary = [...fonts].sort((a, b) => b.glyphCount - a.glyphCount)[0];
     if (!primary)
         return {};
+    const webfont = primary.isCustomFont ? { webfont: true } : {};
     const readable = /^[\p{L}\p{N}.][\p{L}\p{N} ._'-]+$/u.test(primary.familyName);
-    const differs = readable && !primary.familyName.toLowerCase().startsWith(family.toLowerCase());
+    if (!readable || familyLoaded)
+        return webfont;
+    if (GENERIC_FAMILIES.has(family.toLowerCase())) {
+        return { resolved: primary.familyName, ...webfont };
+    }
+    const differs = !primary.familyName.toLowerCase().startsWith(family.toLowerCase());
+    return { ...(differs && { rendered: primary.familyName }), ...webfont };
+}
+/** Fully transparent */
+const CLEAR = { r: 0, g: 0, b: 0, a: 0 };
+/**
+ * Paint the text color and the background behind it the way the browser
+ * composites them: from the element up to the root, each element's content
+ * over its own background, the result faded by its opacity (a translucent
+ * ancestor fades its background along with the text), then over the page
+ * canvas.
+ *
+ * @param text - Text color (undefined: the background alone)
+ * @param backgrounds - Backgrounds with their opacity, the element's own first
+ * @param canvasDark - The page canvas is dark
+ * @returns The text pixel, the background pixel and whether a background
+ *   image or gradient was in the way
+ */
+function paintOver(text, backgrounds, canvasDark) {
+    let withText = text ?? CLEAR;
+    let without = CLEAR;
+    let overImage = false;
+    for (const layer of backgrounds) {
+        if (layer.image && without.a < 0.999)
+            overImage = true;
+        const color = parseColor(layer.color);
+        if (color && color.a > 0) {
+            withText = composite(withText, color);
+            without = composite(without, color);
+        }
+        const opacity = layer.opacity ?? 1;
+        withText = { ...withText, a: withText.a * opacity };
+        without = { ...without, a: without.a * opacity };
+    }
+    const canvas = CANVAS[canvasDark ? 'dark' : 'light'];
     return {
-        ...(differs && { rendered: primary.familyName }),
-        ...(primary.isCustomFont && { webfont: true }),
+        text: composite(withText, canvas),
+        background: composite(without, canvas),
+        overImage,
     };
 }
+/**
+ * Whether the element's own background lets what is behind it through (the
+ * background behind its text comes from an ancestor or the canvas).
+ *
+ * @param backgrounds - Backgrounds, the element's own first
+ * @returns True when its own background is not opaque
+ */
+function ownBackgroundTranslucent(backgrounds) {
+    const own = parseColor(backgrounds[0]?.color ?? '');
+    return !own || own.a < 0.999;
+}
 /**
  * The background behind the element's text: its own and its ancestors'
- * backgrounds composited, from the nearest opaque one (or the page canvas).
+ * backgrounds composited with their opacity over the page canvas.
  *
  * @param backgrounds - Backgrounds, the element's own first
  * @param canvasDark - The page canvas is dark
  * @returns Opaque background, whether it came from an ancestor and whether an image was in the way
  */
 export function effectiveBackground(backgrounds, canvasDark) {
-    const layers = [];
-    let overImage = false;
-    for (const background of backgrounds) {
-        if (background.image)
-            overImage = true;
-        const color = parseColor(background.color);
-        if (!color || color.a === 0)
-            continue;
-        layers.push(color);
-        if (color.a >= 0.999)
-            break;
-    }
-    const base = layers[layers.length - 1];
-    let color = base && base.a >= 0.999 ? base : CANVAS[canvasDark ? 'dark' : 'light'];
-    const translucent = base && base.a >= 0.999 ? layers.slice(0, -1) : layers;
-    for (const layer of [...translucent].reverse())
-        color = composite(layer, color);
-    const own = parseColor(backgrounds[0]?.color ?? '');
-    return { color, inherited: !own || own.a < 0.999, overImage };
+    const painted = paintOver(undefined, backgrounds, canvasDark);
+    return {
+        color: painted.background,
+        inherited: ownBackgroundTranslucent(backgrounds),
+        overImage: painted.overImage,
+    };
 }
 /**
- * Contrast of the text color with the background behind it.
+ * Contrast of the text color with the background behind it, both painted
+ * as the browser composites them ({@link paintOver}), with what makes the
+ * number approximate (blend modes, filters, content behind or on top).
  *
  * @param style - Computed styles (color, font size and weight)
- * @param raw - Backgrounds and the page canvas
+ * @param raw - Backgrounds, the page canvas, opacity and paint risks
  * @returns Ratio (rounded down to 2 decimals), level and background
  */
 export function textContrast(style, raw) {
@@ -79,18 +142,19 @@ export function textContrast(style, raw) {
     if (!color)
         return undefined;
     const opacity = raw.opacity ?? 1;
-    const text = opacity < 1 ? { ...color, a: color.a * opacity } : color;
-    const background = effectiveBackground(raw.backgrounds, raw.canvasDark);
-    const ratio = Math.floor(contrastRatio(text, background.color) * 100) / 100;
+    const painted = paintOver(color, raw.backgrounds, raw.canvasDark);
+    const ratio = Math.floor(contrastRatio(painted.text, painted.background) * 100) / 100;
     const size = pxNumber(style['font-size']) ?? 16;
     const weight = Number(style['font-weight'] ?? 400);
+    const approximate = raw.paintRisks ?? [];
     return {
         ratio,
         level: contrastLevel(ratio, size, weight),
-        background: toHex(background.color),
-        ...(background.inherited && { inherited: true }),
-        ...(background.overImage && { overImage: true }),
+        background: toHex(painted.background),
+        ...(ownBackgroundTranslucent(raw.backgrounds) && { inherited: true }),
+        ...(painted.overImage && { overImage: true }),
         ...(opacity < 1 && { opacity: Math.round(opacity * 100) / 100 }),
+        ...(approximate.length > 0 && { approximate }),
     };
 }
 /**
@@ -188,40 +252,56 @@ function fontFields(style) {
     };
 }
 /**
- * The text group. Elements with text (or form controls) get the full group:
- * font with the rendered font, size, color, alignment, contrast (not for
- * text no one can see: `opacity: 0` on it or an ancestor,
- * `visibility: hidden`) and the non-default extras. Containers get only what differs from
- * their parent, with the font their text was rendered in when the family
- * differs.
+ * The text group. Elements with text (or text fields) get the full group,
+ * read from whatever draws the text (the element, or the descendant with
+ * most of it, named in `holder`): font with the rendered font, size, color,
+ * alignment, contrast (not for text no one can see: not rendered,
+ * `opacity: 0` on it or an ancestor, `visibility: hidden`) and the
+ * non-default extras. Containers get only what differs from their parent,
+ * with the font their text was rendered in when that text has the
+ * container's family. Nothing for an element without text (an icon button,
+ * a checkbox).
  *
- * @param style - Computed styles
- * @param parentStyle - Computed styles of the layout parent
+ * @param styles - Computed styles of the element, its parent and its text holder
  * @param raw - Page-side measurements
  * @param fonts - Platform fonts of the text
  * @returns Text group, or undefined when there is nothing to say
  */
-export function buildText(style, parentStyle, raw, fonts) {
-    const fields = fontFields(style);
+export function buildText(styles, raw, fonts) {
+    const { style, parentStyle, holderStyle } = styles;
     if (raw.textual) {
-        const seen = (raw.opacity ?? 1) > 0 && style['visibility'] !== 'hidden';
-        const contrast = seen ? textContrast(style, raw) : undefined;
+        const textStyle = raw.textHolder && holderStyle ? holderStyle : style;
+        const fields = fontFields(textStyle);
+        const gradientFill = (textStyle['background-clip'] ?? '').includes('text') &&
+            (parseColor(textStyle['-webkit-text-fill-color'] ?? '')?.a ?? 1) === 0;
+        const seen = raw.rendered !== false &&
+            (raw.opacity ?? 1) > 0 &&
+            textStyle['visibility'] !== 'hidden' &&
+            !gradientFill;
+        const contrast = seen ? textContrast(textStyle, raw) : undefined;
         return {
+            ...(textStyle !== style && raw.textHolder && { holder: raw.textHolder }),
             ...fields,
-            ...renderedFont(fields.family ?? '', fonts),
+            ...renderedFont(fields.family ?? '', fonts, raw.familyLoaded),
             ...(contrast && { contrast }),
-            ...textExtras(style),
-            align: alignOf(style),
+            ...textExtras(textStyle),
+            align: alignOf(textStyle),
+            ...(raw.truncated && { truncated: true }),
+            ...(gradientFill && { gradientFill: true }),
         };
     }
-    if (!parentStyle)
+    if (!parentStyle || raw.hasText === false)
         return undefined;
+    const fields = fontFields(style);
     const parentFields = { ...fontFields(parentStyle), ...textExtras(parentStyle) };
     const own = { ...fields, ...textExtras(style) };
     const differing = Object.fromEntries(Object.entries(own).filter(([key, value]) => parentFields[key] !== value));
     if (Object.keys(differing).length === 0)
         return undefined;
-    return differing.family ? { ...differing, ...renderedFont(differing.family, fonts) } : differing;
+    const sameFamily = !holderStyle || holderStyle['font-family'] === style['font-family'];
+    return differing.family && sameFamily
+        ? { ...differing, ...renderedFont(differing.family, fonts, raw.familyLoaded) }
+        : differing;
 }
 /**
  * Cut a long value.
@@ -233,7 +313,8 @@ function cut(text) {
     return text.length > IMAGE_TEXT_LENGTH ? `${text.slice(0, IMAGE_TEXT_LENGTH)}…` : text;
 }
 /**
- * Background layers: images and gradients (top first), then the color.
+ * Background layers: images and gradients (top first), each with its own
+ * size and position when they are not the defaults, then the color.
  *
  * @param style - Computed styles
  * @returns Fills
@@ -241,25 +322,46 @@ function cut(text) {
 export function buildFills(style) {
     const fills = [];
     const image = style['background-image'];
-    const size = style['background-size'];
     if (image && image !== 'none') {
-        for (const layer of splitTopLevel(image)) {
+        const sizes = splitTopLevel(style['background-size'] ?? 'auto');
+        const xs = splitTopLevel(style['background-position-x'] ?? '0%');
+        const ys = splitTopLevel(style['background-position-y'] ?? '0%');
+        const positions = xs.map((x, i) => `${x} ${ys[i % ys.length] ?? '0%'}`);
+        splitTopLevel(image).forEach((layer, i) => {
+            const size = sizes[i % sizes.length] ?? 'auto';
+            const position = positions[i % positions.length] ?? '0% 0%';
             const value = cut(normalizeCssValue(shortUrls(layer)));
-            if (layer.includes('gradient('))
-                fills.push({ type: 'gradient', value });
-            else
-                fills.push({
-                    type: 'image',
-                    value,
-                    ...(size && size !== 'auto' && { size: normalizeCssValue(size) }),
-                });
-        }
+            fills.push({
+                type: layer.includes('gradient(') ? 'gradient' : 'image',
+                value,
+                ...(size !== 'auto' && size !== 'auto auto' && { size: normalizeCssValue(size) }),
+                ...(position !== '0% 0%' && { position: normalizeCssValue(position) }),
+            });
+        });
     }
     const color = hexColor(style['background-color'] ?? 'transparent');
     if (color !== 'transparent')
         fills.push({ type: 'solid', color });
     return fills;
 }
+/**
+ * How an SVG element is painted: its `fill` and `stroke` (with the width).
+ *
+ * @param style - Computed styles
+ * @param raw - Whether it is an SVG element
+ * @returns Paint, or undefined for an HTML element
+ */
+export function buildSvgPaint(style, raw) {
+    if (!raw.svg)
+        return undefined;
+    const paint = (value) => normalizeCssValue(shortUrls(hexColor(value ?? 'none')));
+    const stroke = paint(style['stroke']);
+    return {
+        fill: paint(style['fill']),
+        stroke,
+        ...(stroke !== 'none' && { strokeWidth: cssLength(style['stroke-width'] ?? '1px') }),
+    };
+}
 /**
  * Border sides that show (a style other than none/hidden and a width): one
  * `all` stroke when the four are equal.
@@ -421,6 +523,7 @@ export function buildGeneratedPseudo(pseudo, hostColor) {
         content: shortUrls(content),
         ...(display && display !== 'inline' && { display }),
         ...(position && position !== 'static' && { position }),
+        ...(position && position !== 'static' && { inset: insetOf(style) }),
         ...(pseudo.size && { size: pseudo.size }),
         ...(style['color'] && style['color'] !== hostColor && { color: hexColor(style['color']) }),
         ...(fills.length > 0 && { fills }),
@@ -430,6 +533,15 @@ export function buildGeneratedPseudo(pseudo, hostColor) {
         ...(opacity !== 1 && { opacity }),
     };
 }
+/**
+ * Offsets of a positioned box, as one 1-4 value shorthand.
+ *
+ * @param style - Computed styles
+ * @returns e.g. `auto 50% -9 0`
+ */
+function insetOf(style) {
+    return sidesShorthand(['top', 'right', 'bottom', 'left'].map((side) => normalizeCssValue(style[side] ?? 'auto')));
+}
 /**
  * The pseudo group: generated `::before`/`::after` and the placeholder color.
  *

package/dist/runtime/dom/inspectRules.d.ts

@@ -14,6 +14,14 @@ import type { Declaration } from './inspectCascade.js';
  * @param cdp - CDP connection
  */
 export declare function trackStyleSheets(cdp: CDPConnection): void;
+/**
+ * The stylesheet headers seen on a connection (after {@link trackStyleSheets}
+ * and `CSS.enable`).
+ *
+ * @param cdp - CDP connection
+ * @returns Headers
+ */
+export declare function styleSheetHeaders(cdp: CDPConnection): Iterable<Protocol.CSS.CSSStyleSheetHeader>;
 /**
  * The rules that match an element, with its inline style and what its
  * ancestors pass down, or why they are missing.
@@ -34,4 +42,15 @@ export declare function matchedStyles(cdp: CDPConnection, nodeId: number, budget
  * @returns e.g. `.btn-primary (bootstrap.min.css:5:52628)`, `style attribute`, `browser default`
  */
 export declare function sourceLabel(declaration: Declaration, cdp: CDPConnection): string;
+/**
+ * A stylesheet position as `file:line[:column]`.
+ *
+ * @param header - Stylesheet header (unknown: just the line)
+ * @param line - 0-based line within the stylesheet
+ * @param column - 0-based column
+ * @returns e.g. `app.css:12`, `bootstrap.min.css:5:52628`, `<style> in index.html:40`,
+ *   `constructed stylesheet`, `<style> added by a script` (a sheet a script created and
+ *   filled with `insertRule`: its lines are not in any file)
+ */
+export declare function stylesheetPositionLabel(header: Protocol.CSS.CSSStyleSheetHeader | undefined, line: number | undefined, column: number | undefined): string;
 //# sourceMappingURL=inspectRules.d.ts.map

package/dist/runtime/dom/inspectRules.js

@@ -27,6 +27,16 @@ export function trackStyleSheets(cdp) {
         headers.delete(styleSheetId);
     });
 }
+/**
+ * The stylesheet headers seen on a connection (after {@link trackStyleSheets}
+ * and `CSS.enable`).
+ *
+ * @param cdp - CDP connection
+ * @returns Headers
+ */
+export function styleSheetHeaders(cdp) {
+    return headersByConnection.get(cdp)?.values() ?? [];
+}
 /**
  * The rules that match an element, with its inline style and what its
  * ancestors pass down, or why they are missing.
@@ -77,7 +87,7 @@ export function sourceLabel(declaration, cdp) {
     const header = source.styleSheetId
         ? headersByConnection.get(cdp)?.get(source.styleSheetId)
         : undefined;
-    return `${source.selector ?? ''} (${fileLabel(header, source.line, source.column)})`;
+    return `${source.selector ?? ''} (${stylesheetPositionLabel(header, source.line, source.column)})`;
 }
 /**
  * A stylesheet position as `file:line[:column]`.
@@ -85,17 +95,23 @@ export function sourceLabel(declaration, cdp) {
  * @param header - Stylesheet header (unknown: just the line)
  * @param line - 0-based line within the stylesheet
  * @param column - 0-based column
- * @returns e.g. `app.css:12`, `bootstrap.min.css:5:52628`, `<style> in index.html:40`, `constructed stylesheet`
+ * @returns e.g. `app.css:12`, `bootstrap.min.css:5:52628`, `<style> in index.html:40`,
+ *   `constructed stylesheet`, `<style> added by a script` (a sheet a script created and
+ *   filled with `insertRule`: its lines are not in any file)
  */
-function fileLabel(header, line, column) {
+export function stylesheetPositionLabel(header, line, column) {
     if (!header)
         return line === undefined ? 'stylesheet' : `stylesheet:${line + 1}`;
     if (header.isConstructed)
         return 'constructed stylesheet';
     const file = fileName(header.sourceURL) || 'page';
-    const absoluteLine = (line ?? 0) + (header.isInline ? header.startLine : 0) + 1;
     const where = header.isInline ? `<style> in ${file}` : file;
+    if (header.isMutable && !header.sourceURL)
+        return `<style> added by a script`;
+    const absoluteLine = (line ?? 0) + (header.isInline ? header.startLine : 0) + 1;
+    const firstLine = header.isInline && (line ?? 0) === 0;
+    const absoluteColumn = (column ?? 0) + (firstLine ? header.startColumn : 0) + 1;
     const minified = header.endLine - header.startLine < 10 && (column ?? 0) > 200;
-    return minified ? `${where}:${absoluteLine}:${(column ?? 0) + 1}` : `${where}:${absoluteLine}`;
+    return minified ? `${where}:${absoluteLine}:${absoluteColumn}` : `${where}:${absoluteLine}`;
 }
 //# sourceMappingURL=inspectRules.js.map