browser-debugger-cli 0.11.0 → 0.12.0

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

@@ -6,6 +6,8 @@
  */
 import type { Declaration, Resolution } from './inspectCascade.js';
 import type { StyleMap } from './inspectLayoutModel.js';
+import type { InspectHint } from '../../ipc/protocol/inspectTypes.js';
+import type { VariableSetter } from './inspectScripts.js';
 /** A declaration that has no effect */
 export interface CssHint {
     kind: 'inactive' | 'unset-variable' | 'not-inherited';
@@ -17,6 +19,10 @@ export interface CssHint {
     reason: string;
     /** What would make it work */
     fix: string;
+    /** The longhands of a shorthand that have no effect, when the others do (`margin-top`, `margin-bottom`) */
+    only?: string[];
+    /** The custom properties that are not set (`unset-variable`) */
+    variables?: string[];
     /** The declaration */
     declaration: Declaration;
 }
@@ -24,15 +30,19 @@ export interface CssHint {
 interface HintContext {
     style: StyleMap;
     parentStyle: StyleMap | undefined;
+    /** `display` as the winning declaration wrote it, when it differs from the computed one (blockified) */
+    declaredDisplay?: string | undefined;
     /** The element is replaced (img, input, video…) */
     replaced: boolean;
     /** The element is a form control (input, textarea, select, button) */
     formControl?: boolean;
 }
 /**
- * Declarations of the element that have no effect: every longhand a
- * declaration wins is inactive (`margin: 0 4px` on an inline element still
- * moves it sideways, `gap` on a multi-column block still spaces the columns).
+ * Declarations of the element that have no effect: the longhands a
+ * declaration wins that are inactive, unless they only restate a default.
+ * When only some of a `margin` shorthand's longhands are inactive
+ * (`margin: 8px 12px` on an inline element: the sides still move it), the
+ * hint names those; other partly inactive shorthands are not hinted.
  *
  * @param cascade - Resolved properties (winning declarations are checked)
  * @param ctx - Computed styles of the element and its parent
@@ -49,6 +59,19 @@ export declare function inactiveHints(cascade: Map<string, Resolution>, ctx: Hin
  * @returns Hints
  */
 export declare function undefinedVariableHints(cascade: Map<string, Resolution>, style: StyleMap): CssHint[];
+/**
+ * Unset-variable hints told where the page does set the variable, when it
+ * does: only in a rule that does not match now (`.btn:hover`: expected in
+ * the other state), only in `@keyframes` (while the animation runs), or to
+ * `inherit`/`initial`/an empty value in a rule that matches (nothing above
+ * gives it a value). A set variable is not a typo, so the "did you mean"
+ * suggestion goes.
+ *
+ * @param hints - Hints of the result
+ * @param setters - Where each variable is set, by name ({@link VARIABLE_SETTERS_JS})
+ * @returns Hints
+ */
+export declare function explainUnsetVariables(hints: readonly InspectHint[], setters: Readonly<Record<string, VariableSetter>>): InspectHint[];
 /**
  * A form control drawn in the browser's font while its parent uses another:
  * controls do not inherit the font unless told to (a common oversight).

package/dist/runtime/dom/inspectHints.js

@@ -4,12 +4,14 @@
  * checked against authored declarations only (never the browser's own
  * styles), and `var()` references to custom properties that are not set.
  */
+import { isDefaultValue } from './inspectAllStyles.js';
 import { unsetVariables } from './inspectVariables.js';
 import { findSimilarNames } from '../../utils/suggestions.js';
 const display = (style) => style?.['display'] ?? 'inline';
 const isFlex = (value) => /(^|-)flex$/.test(value);
 const isGrid = (value) => /(^|-)grid$/.test(value);
 const isFlexOrGrid = (value) => isFlex(value) || isGrid(value);
+const horizontal = (style) => (style['writing-mode'] ?? 'horizontal-tb') === 'horizontal-tb';
 const isMulticol = (style) => (style['column-count'] ?? 'auto') !== 'auto' || (style['column-width'] ?? 'auto') !== 'auto';
 /** The checks, in DevTools' wording */
 const RULES = [
@@ -120,7 +122,7 @@ const RULES = [
     },
     {
         properties: ['margin-top', 'margin-bottom'],
-        inactive: ({ style, replaced }) => display(style) === 'inline' && !replaced
+        inactive: ({ style, replaced }) => display(style) === 'inline' && !replaced && horizontal(style)
             ? {
                 reason: 'display is inline (vertical margins do not move it)',
                 fix: 'use display: inline-block or block',
@@ -129,10 +131,10 @@ const RULES = [
     },
     {
         properties: ['vertical-align'],
-        inactive: ({ style }) => /^(inline|inline-block|inline-flex|inline-grid|table-cell)$/.test(display(style))
+        inactive: ({ style, parentStyle, declaredDisplay }) => /^(inline|table-cell|ruby)/.test(display(style))
             ? undefined
             : {
-                reason: `display is ${display(style)}`,
+                reason: `display is ${display(style)}${blockified(declaredDisplay, style, parentStyle)}`,
                 fix: 'vertical-align works on inline and table-cell boxes; use flex alignment instead',
             },
     },
@@ -165,9 +167,58 @@ const RULES = [
     },
 ];
 /**
- * Declarations of the element that have no effect: every longhand a
- * declaration wins is inactive (`margin: 0 4px` on an inline element still
- * moves it sideways, `gap` on a multi-column block still spaces the columns).
+ * Why a declared inline-level display computes to a block-level one: the
+ * element is a flex or grid item, floated or positioned (CSS blockification).
+ *
+ * @param declared - `display` as written, when it differs from the computed one
+ * @param style - Computed styles
+ * @param parentStyle - Computed styles of the layout parent
+ * @returns ` (inline-flex blockified: a flex item)`, or empty
+ */
+function blockified(declared, style, parentStyle) {
+    if (!declared || declared === display(style) || !/^(inline|table-|ruby)/.test(declared))
+        return '';
+    const parent = display(parentStyle);
+    const cause = isFlex(parent)
+        ? 'a flex item'
+        : isGrid(parent)
+            ? 'a grid item'
+            : (style['float'] ?? 'none') !== 'none'
+                ? 'floated'
+                : /^(absolute|fixed)$/.test(style['position'] ?? '')
+                    ? 'positioned'
+                    : 'by its context';
+    return ` (${declared} blockified: ${cause})`;
+}
+/**
+ * Shorthands whose inactive longhands are worth a hint while the others
+ * work: vertical margins of an inline element are a common mistake, while
+ * `gap` in a multi-column block or `grid-template-areas: none` are not
+ */
+const PARTIAL_SHORTHANDS = new Set(['margin', 'margin-block']);
+/** Values that change nothing wherever they are written */
+const NO_OP_KEYWORDS = new Set(['initial', 'unset', 'revert', 'revert-layer']);
+/**
+ * Whether a declared longhand value is its default, so writing it has no
+ * effect in any case (`vertical-align: baseline`, `margin-top: 0` from a
+ * reset): such declarations are not worth a hint.
+ *
+ * @param declaration - Declaration of a longhand
+ * @returns True for a default value
+ */
+function isNoOp(declaration) {
+    const value = declaration.value.trim().toLowerCase();
+    if (NO_OP_KEYWORDS.has(value))
+        return true;
+    const zero = /^[+-]?0*\.?0+([a-z]+|%)?$/.test(value) ? '0px' : value;
+    return isDefaultValue(declaration.property, value) || isDefaultValue(declaration.property, zero);
+}
+/**
+ * Declarations of the element that have no effect: the longhands a
+ * declaration wins that are inactive, unless they only restate a default.
+ * When only some of a `margin` shorthand's longhands are inactive
+ * (`margin: 8px 12px` on an inline element: the sides still move it), the
+ * hint names those; other partly inactive shorthands are not hinted.
  *
  * @param cascade - Resolved properties (winning declarations are checked)
  * @param ctx - Computed styles of the element and its parent
@@ -176,16 +227,21 @@ const RULES = [
 export function inactiveHints(cascade, ctx) {
     return [...ownWinnersByDeclaration(cascade).values()].flatMap((winners) => {
         const checks = winners.map((declaration) => RULES.find((rule) => rule.properties.includes(declaration.property))?.inactive(ctx));
+        const inactive = winners.filter((declaration, i) => checks[i] && !isNoOp(declaration));
         const [first] = winners;
-        const [inactive] = checks;
-        if (!first || !inactive || checks.some((check) => !check))
+        const reason = checks.find(Boolean);
+        const partial = checks.some((check) => !check);
+        if (!first || !reason || inactive.length === 0)
+            return [];
+        if (partial && !PARTIAL_SHORTHANDS.has(first.via ?? ''))
             return [];
         return [
             {
                 kind: 'inactive',
                 property: first.via ?? first.property,
                 value: first.written ?? first.value,
-                ...inactive,
+                ...reason,
+                ...(partial && { only: inactive.map((declaration) => declaration.property) }),
                 declaration: first,
             },
         ];
@@ -243,11 +299,71 @@ export function undefinedVariableHints(cascade, style) {
             value,
             reason: `${missing.join(', ')} is not set`,
             fix: variableFix(missing[0] ?? '', style),
+            variables: missing,
             declaration,
         });
     }
     return hints;
 }
+/**
+ * Unset-variable hints told where the page does set the variable, when it
+ * does: only in a rule that does not match now (`.btn:hover`: expected in
+ * the other state), only in `@keyframes` (while the animation runs), or to
+ * `inherit`/`initial`/an empty value in a rule that matches (nothing above
+ * gives it a value). A set variable is not a typo, so the "did you mean"
+ * suggestion goes.
+ *
+ * @param hints - Hints of the result
+ * @param setters - Where each variable is set, by name ({@link VARIABLE_SETTERS_JS})
+ * @returns Hints
+ */
+export function explainUnsetVariables(hints, setters) {
+    return hints.map((hint) => {
+        const variables = hint.variables ?? [];
+        const name = variables.find((variable) => setters[variable]);
+        const setter = name ? setters[name] : undefined;
+        if (!name || !setter)
+            return hint;
+        const explained = setterExplanation(name, setter);
+        if (variables.every((variable) => setters[variable]))
+            return { ...hint, ...explained };
+        return { ...hint, reason: `${hint.reason}; ${explained.reason}` };
+    });
+}
+/**
+ * Why a variable that the page sets is unset here, and the fix.
+ *
+ * @param name - Variable
+ * @param setter - Where it is set
+ * @returns Reason and fix
+ */
+function setterExplanation(name, setter) {
+    const fallback = 'give var() a fallback';
+    if (setter.keyframes) {
+        return {
+            reason: `${name} is set only in @keyframes ${setter.keyframes} (while it runs)`,
+            fix: `${fallback} for when the animation is not running`,
+        };
+    }
+    if (setter.condition) {
+        return {
+            reason: `${name} is set only by ${setter.selector} under ${setter.condition}, which does not apply now`,
+            fix: `expected under other conditions; otherwise ${fallback}`,
+        };
+    }
+    if (setter.matches) {
+        return {
+            reason: `${name} is set to ${setter.value === '' ? 'an empty value' : setter.value} by ${setter.selector}, and nothing above gives it a value`,
+            fix: `set ${name} on an ancestor, or ${fallback}`,
+        };
+    }
+    return {
+        reason: setter.matches === null
+            ? `${name} is set only by ${setter.selector} (whether it applies here is not known)`
+            : `${name} is set only by ${setter.selector}, which does not match now`,
+        fix: `expected in that state; otherwise ${fallback}`,
+    };
+}
 /**
  * How to fix a `var()` of an unset custom property, naming a similar one
  * that is set (a typo or a renamed token).

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

@@ -16,7 +16,10 @@ export interface InspectSources {
     raw: RawInspect;
     style: StyleMap;
     parentStyle?: StyleMap;
+    /** Computed styles of the descendant that draws the text, when it is not the element */
+    holderStyle?: StyleMap;
     pseudo: PseudoSource[];
+    /** Platform fonts of the text (of the descendant that draws it, when there is one) */
     fonts: PlatformFont[];
     /** Border box size from `DOM.getBoxModel`; absent when the element has no box */
     size?: {

package/dist/runtime/dom/inspectModel.js

@@ -7,7 +7,7 @@
  */
 import { allStyles } from './inspectAllStyles.js';
 import { buildBox, buildLayout } from './inspectLayoutModel.js';
-import { buildEffects, buildFills, buildFx, buildOutline, buildPseudo, buildRadius, buildState, buildStrokes, buildText, effectiveBackground, } from './inspectPaintModel.js';
+import { buildEffects, buildFills, buildSvgPaint, buildFx, buildOutline, buildPseudo, buildRadius, buildState, buildStrokes, buildText, effectiveBackground, } from './inspectPaintModel.js';
 import { buildTree, rowText } from './inspectTree.js';
 import { hexColor, relativeLuminance } from '../../utils/color.js';
 import { normalizeCssValue, round1 } from '../../utils/cssValues.js';
@@ -50,6 +50,30 @@ export function visibilityOf(layout, rendered) {
         ...(layout.coverTransparent && { coverTransparent: true }),
     };
 }
+/**
+ * The header rectangle: border box size (and the box it covers on screen
+ * when a transform turns it), and the page position, or the
+ * viewport position of an element fixed to the viewport (it or a container
+ * is `position: fixed`: its page position changes with the scroll).
+ *
+ * @param layout - Layout measurements
+ * @param size - Border box size
+ * @param style - Computed styles (transforms)
+ * @returns Rectangle
+ */
+function headerRect(layout, size, style) {
+    const { width, height } = layout.bounds;
+    const transformed = ['transform', 'rotate', 'scale'].some((name) => (style[name] ?? 'none') !== 'none');
+    const turned = transformed && (Math.abs(width - size.w) > 1 || Math.abs(height - size.h) > 1);
+    const box = {
+        w: round1(size.w),
+        h: round1(size.h),
+        ...(turned && { screen: { w: width, h: height } }),
+    };
+    return layout.fixed
+        ? { x: layout.viewport.x, y: layout.viewport.y, ...box, in: 'viewport' }
+        : { x: layout.bounds.x, y: layout.bounds.y, ...box };
+}
 /** Below this relative luminance a page background counts as dark */
 const DARK_LUMINANCE = 0.18;
 /**
@@ -72,10 +96,7 @@ function header(sources, request) {
         ...(content && { content }),
         ...(raw.placeholder && { placeholder: rowText(raw.placeholder) }),
         ...(raw.context && { context: raw.context }),
-        ...(size &&
-            layout && {
-            rect: { x: layout.bounds.x, y: layout.bounds.y, w: round1(size.w), h: round1(size.h) },
-        }),
+        ...(size && layout && { rect: headerRect(layout, size, sources.style) }),
         visibility: visibilityOf(layout, size !== undefined),
         ...(sources.colorScheme && { colorScheme: sources.colorScheme }),
         ...(sources.colorScheme === 'dark' && pageLooksDark(raw) && { theme: 'dark' }),
@@ -104,8 +125,9 @@ function pageLooksDark(raw) {
  */
 function groups(sources) {
     const { style, parentStyle, raw } = sources;
-    const text = buildText(style, parentStyle, raw, sources.fonts);
+    const text = buildText({ style, parentStyle, holderStyle: sources.holderStyle }, raw, sources.fonts);
     const fills = buildFills(style);
+    const paint = buildSvgPaint(style, raw);
     const strokes = buildStrokes(style);
     const radius = buildRadius(style);
     const outline = buildOutline(style);
@@ -120,6 +142,7 @@ function groups(sources) {
         layout: buildLayout(style, parentStyle, raw),
         ...(text && { text }),
         ...(fills.length > 0 && { fills }),
+        ...(paint && { paint }),
         ...(opacity !== 1 && { opacity }),
         ...(blend && blend !== 'normal' && { blend }),
         ...(strokes.length > 0 && { strokes }),
@@ -156,7 +179,7 @@ function treeFields(raw, limit) {
  * @returns Properties and values
  */
 function allFields(sources) {
-    const all = allStyles(sources.style, sources.raw.svg === true);
+    const all = allStyles(sources.style, sources.raw.svg === true, sources.raw.formControl);
     for (const pseudo of sources.pseudo) {
         const content = pseudo.style['content'];
         if (content && content !== 'none' && content !== 'normal') {

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

@@ -7,7 +7,7 @@
  * backgrounds of the element and its ancestors composited over the page
  * canvas).
  */
-import type { InspectContrast, InspectEffect, InspectFill, InspectFx, InspectPseudo, InspectState, InspectStroke, InspectText, Sides } from '../../ipc/protocol/inspectTypes.js';
+import type { InspectContrast, InspectEffect, InspectFill, InspectFx, InspectPseudo, InspectState, InspectStroke, InspectSvgPaint, InspectText, Sides } from '../../ipc/protocol/inspectTypes.js';
 import type { StyleMap } from './inspectLayoutModel.js';
 import type { RawBackground, RawInspect } from './inspectScripts.js';
 import { type Rgba } from '../../utils/color.js';
@@ -18,20 +18,24 @@ export interface PlatformFont {
     glyphCount: number;
 }
 /**
- * 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 declare function renderedFont(family: string, fonts: readonly PlatformFont[]): Pick<InspectText, 'rendered' | 'webfont'>;
+export declare function renderedFont(family: string, fonts: readonly PlatformFont[], familyLoaded?: boolean): Pick<InspectText, 'rendered' | 'resolved' | 'webfont'>;
 /**
  * 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
@@ -43,35 +47,57 @@ export declare function effectiveBackground(backgrounds: readonly RawBackground[
     overImage: boolean;
 };
 /**
- * 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 declare function textContrast(style: StyleMap, raw: Pick<RawInspect, 'backgrounds' | 'canvasDark' | 'opacity'>): InspectContrast | undefined;
+export declare function textContrast(style: StyleMap, raw: Pick<RawInspect, 'backgrounds' | 'canvasDark' | 'opacity' | 'paintRisks'>): InspectContrast | undefined;
+/** Computed styles the text group reads */
+export interface TextStyles {
+    /** The element's */
+    style: StyleMap;
+    /** Its layout parent's */
+    parentStyle?: StyleMap | undefined;
+    /** The descendant's that draws most of its text, when it is not the element */
+    holderStyle?: StyleMap | undefined;
+}
 /**
- * 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 declare function buildText(style: StyleMap, parentStyle: StyleMap | undefined, raw: Pick<RawInspect, 'textual' | 'backgrounds' | 'canvasDark' | 'opacity'>, fonts: readonly PlatformFont[]): InspectText | undefined;
+export declare function buildText(styles: TextStyles, raw: Pick<RawInspect, 'textual' | 'textHolder' | 'rendered' | 'hasText' | 'familyLoaded' | 'truncated' | 'backgrounds' | 'canvasDark' | 'opacity' | 'paintRisks'>, fonts: readonly PlatformFont[]): InspectText | undefined;
 /**
- * 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
  */
 export declare function buildFills(style: StyleMap): InspectFill[];
+/**
+ * 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 declare function buildSvgPaint(style: StyleMap, raw: Pick<RawInspect, 'svg'>): InspectSvgPaint | undefined;
 /**
  * Border sides that show (a style other than none/hidden and a width): one
  * `all` stroke when the four are equal.