browser-debugger-cli 0.9.0 → 0.11.0

package/dist/runtime/dom/inspectCascade.js

@@ -0,0 +1,371 @@
+/**
+ * Which declaration sets a property of an element: the CSS cascade computed
+ * from `CSS.getMatchedStylesForNode` (Chrome reports the matching rules, not
+ * which declaration wins).
+ *
+ * The rules come in ascending precedence (user-agent first, then layered
+ * rules in layer order, then unlayered rules by specificity and source
+ * order), between the presentational attributes and the style attribute.
+ * The last normal declaration wins unless an `!important` one exists; among
+ * important ones the style attribute wins, then layered ones (earlier layers
+ * first), then unlayered ones. Shorthands are expanded into their longhands
+ * and logical properties mapped to physical ones (horizontal, left-to-right
+ * writing). With no declaration of its own, an inherited property comes from
+ * the nearest ancestor that declares it.
+ */
+/**
+ * The four side longhands of a pattern.
+ *
+ * @param pattern - e.g. `border-{side}-width`
+ * @returns Top, right, bottom, left
+ */
+function sideLonghands(pattern) {
+    return ['top', 'right', 'bottom', 'left'].map((side) => pattern.replace('{side}', side));
+}
+/** Longhands of common shorthands, for values with `var()` (CDP leaves those unexpanded) */
+const SHORTHANDS = {
+    margin: ['margin-top', 'margin-right', 'margin-bottom', 'margin-left'],
+    padding: ['padding-top', 'padding-right', 'padding-bottom', 'padding-left'],
+    inset: ['top', 'right', 'bottom', 'left'],
+    gap: ['row-gap', 'column-gap'],
+    overflow: ['overflow-x', 'overflow-y'],
+    'border-width': [
+        'border-top-width',
+        'border-right-width',
+        'border-bottom-width',
+        'border-left-width',
+    ],
+    'border-style': [
+        'border-top-style',
+        'border-right-style',
+        'border-bottom-style',
+        'border-left-style',
+    ],
+    'border-color': [
+        'border-top-color',
+        'border-right-color',
+        'border-bottom-color',
+        'border-left-color',
+    ],
+    'border-radius': [
+        'border-top-left-radius',
+        'border-top-right-radius',
+        'border-bottom-right-radius',
+        'border-bottom-left-radius',
+    ],
+    'margin-inline': ['margin-left', 'margin-right'],
+    'margin-block': ['margin-top', 'margin-bottom'],
+    'padding-inline': ['padding-left', 'padding-right'],
+    'padding-block': ['padding-top', 'padding-bottom'],
+    'inset-inline': ['left', 'right'],
+    'inset-block': ['top', 'bottom'],
+    border: ['width', 'style', 'color'].flatMap((part) => sideLonghands('border-{side}-' + part)),
+    ...Object.fromEntries(['top', 'right', 'bottom', 'left'].map((side) => [
+        `border-${side}`,
+        ['width', 'style', 'color'].map((part) => `border-${side}-${part}`),
+    ])),
+    background: ['background-color', 'background-image'],
+    font: ['font-style', 'font-weight', 'font-size', 'line-height', 'font-family'],
+    flex: ['flex-grow', 'flex-shrink', 'flex-basis'],
+    'place-items': ['align-items', 'justify-items'],
+    'place-content': ['align-content', 'justify-content'],
+    'place-self': ['align-self', 'justify-self'],
+};
+/** Physical longhand of a logical one (horizontal-tb, ltr) */
+const LOGICAL_TO_PHYSICAL = {
+    'inline-size': 'width',
+    'block-size': 'height',
+    'min-inline-size': 'min-width',
+    'min-block-size': 'min-height',
+    'max-inline-size': 'max-width',
+    'max-block-size': 'max-height',
+    'inset-block-start': 'top',
+    'inset-block-end': 'bottom',
+    'inset-inline-start': 'left',
+    'inset-inline-end': 'right',
+};
+/** Sides of the logical box properties (block-start → top, …) */
+const LOGICAL_SIDES = {
+    'block-start': 'top',
+    'block-end': 'bottom',
+    'inline-start': 'left',
+    'inline-end': 'right',
+};
+/** Properties that inherit (those `dom inspect` reports) */
+const INHERITED = new Set([
+    'color',
+    'font-family',
+    'font-size',
+    'font-style',
+    'font-weight',
+    'font-variant',
+    'font-feature-settings',
+    'font-variation-settings',
+    'line-height',
+    'letter-spacing',
+    'word-spacing',
+    'text-align',
+    'text-indent',
+    'text-transform',
+    'text-shadow',
+    'white-space-collapse',
+    'text-wrap-mode',
+    'visibility',
+    'cursor',
+    'direction',
+    'list-style-type',
+    'list-style-position',
+    'tab-size',
+    'pointer-events',
+    'user-select',
+    '-webkit-text-security',
+]);
+/**
+ * The longhands of a shorthand.
+ *
+ * @param name - Property name
+ * @returns Its longhands, or undefined when it is not a known shorthand
+ */
+export function shorthandLonghands(name) {
+    return Object.hasOwn(SHORTHANDS, name) ? SHORTHANDS[name] : undefined;
+}
+/**
+ * Whether a property inherits.
+ *
+ * @param property - Longhand
+ * @returns True for inherited properties (custom properties inherit)
+ */
+export function isInherited(property) {
+    return INHERITED.has(property) || property.startsWith('--');
+}
+/**
+ * The physical longhand a logical property sets.
+ *
+ * @param name - Property as written
+ * @returns Physical name, or the name itself
+ */
+export function physicalName(name) {
+    const direct = LOGICAL_TO_PHYSICAL[name];
+    if (direct)
+        return direct;
+    const match = /^(margin|padding|border|scroll-margin|scroll-padding)-(block-start|block-end|inline-start|inline-end)(-(width|style|color))?$/.exec(name);
+    if (!match)
+        return name;
+    const side = LOGICAL_SIDES[match[2] ?? ''] ?? '';
+    return `${match[1]}-${side}${match[3] ?? ''}`;
+}
+/**
+ * The longhands one written property sets, with the value each gets.
+ *
+ * @param property - CDP property (with `longhandProperties` when Chrome expanded it)
+ * @returns Longhand names and values
+ */
+function longhandsOf(property) {
+    if (property.longhandProperties && property.longhandProperties.length > 0) {
+        return property.longhandProperties.map((longhand) => ({
+            name: physicalName(longhand.name),
+            value: longhand.value,
+        }));
+    }
+    const expanded = SHORTHANDS[property.name];
+    if (expanded)
+        return expanded.map((name) => ({ name, value: property.value }));
+    return [{ name: physicalName(property.name), value: property.value }];
+}
+/**
+ * The declarations a CSS style block sets, longhand by longhand. Only
+ * declarations as written count (CDP adds unranged duplicates); disabled
+ * and invalid ones do not. A shorthand with `var()` gives each longhand the
+ * value as written: Chrome cannot expand it before substitution and reports
+ * the initial values (`currentcolor` for `border: 2px solid var(--c)`).
+ *
+ * @param style - CDP style
+ * @param source - Where the block comes from
+ * @returns Declarations
+ */
+function declarationsOf(style, source) {
+    if (!style)
+        return [];
+    return style.cssProperties
+        .filter((property) => property.range !== undefined ||
+        source.origin === 'user-agent' ||
+        source.kind === 'attribute')
+        .filter((property) => property.disabled !== true && property.parsedOk !== false)
+        .flatMap((property) => {
+        const written = property.value.replace(/\s*!important\s*$/, '');
+        return longhandsOf(property).map(({ name, value }) => ({
+            property: name,
+            value: property.longhandProperties && value !== '' && !written.includes('var(')
+                ? value
+                : written,
+            ...(name !== property.name && { via: property.name, written }),
+            important: property.important === true,
+            source: {
+                ...source,
+                ...(property.range && {
+                    line: property.range.startLine,
+                    column: property.range.startColumn,
+                }),
+            },
+        }));
+    });
+}
+/**
+ * Source of a matched rule: its matching selector, origin, stylesheet,
+ * layer (nested ones as `outer.inner`), the media or container condition
+ * it is under (`not all and (…)`, as Chrome writes `not (…)`, shortened) and
+ * the selector's specificity.
+ *
+ * @param match - CDP rule match
+ * @returns Declaration source
+ */
+function ruleSource(match) {
+    const { rule } = match;
+    const matching = rule.selectorList.selectors[match.matchingSelectors[0] ?? 0];
+    const selector = matching?.text ?? rule.selectorList.text;
+    const layer = rule.layers?.map((l) => l.text || '(anonymous)').join('.');
+    const condition = [...(rule.media ?? []), ...(rule.containerQueries ?? [])]
+        .map((c) => c.text.replace(/^not all and /, 'not '))
+        .join(' and ');
+    const specificity = matching?.specificity;
+    return {
+        kind: 'rule',
+        selector,
+        origin: rule.origin,
+        ...(specificity && { specificity: [specificity.a, specificity.b, specificity.c] }),
+        ...(rule.styleSheetId && { styleSheetId: rule.styleSheetId }),
+        ...(layer && { layer }),
+        ...(condition && { condition }),
+    };
+}
+/**
+ * The declarations of one element in ascending cascade order.
+ *
+ * @param entry - Inline style, presentational attributes and matched rules
+ * @returns Declarations, lowest precedence first
+ */
+function orderedDeclarations(entry) {
+    return [
+        ...declarationsOf(entry.attributesStyle, { kind: 'attribute' }),
+        ...(entry.matchedCSSRules ?? []).flatMap((match) => declarationsOf(match.rule.style, ruleSource(match))),
+        ...declarationsOf(entry.inlineStyle, { kind: 'inline' }),
+    ];
+}
+/**
+ * Whether a declaration comes from the page's authors (not the browser's
+ * own stylesheet or an extension's).
+ *
+ * @param declaration - Declaration
+ * @returns True for author declarations
+ */
+function isAuthor(declaration) {
+    const { origin } = declaration.source;
+    return origin === undefined || origin === 'regular' || origin === 'inspector';
+}
+/**
+ * Precedence of a declaration within one element's list. Normal: author over
+ * browser; then the style attribute; then by layer (presentational
+ * attributes below every layer, unlayered rules above); then by position.
+ * Important: browser over author; the style attribute; layers reversed
+ * (unlayered lowest); position.
+ *
+ * @param declaration - Declaration
+ * @param position - Its index in ascending order
+ * @param layers - Layer names in the order they first appear
+ * @returns Comparable tuple, higher wins
+ */
+function precedence(declaration, position, layers) {
+    const { layer, kind } = declaration.source;
+    const layerIndex = layer === undefined ? -1 : layers.indexOf(layer);
+    const author = isAuthor(declaration) ? 1 : 0;
+    const inline = kind === 'inline' ? 1 : 0;
+    if (!declaration.important) {
+        const layerRank = kind === 'attribute' ? -1 : layer === undefined ? layers.length : layerIndex;
+        return [0, author, inline, layerRank, position];
+    }
+    return [1, 1 - author, inline, layer === undefined ? -1 : layers.length - layerIndex, position];
+}
+/**
+ * Compare two precedence tuples.
+ *
+ * @param a - Tuple
+ * @param b - Tuple
+ * @returns Positive when a wins
+ */
+function compare(a, b) {
+    for (let i = 0; i < a.length; i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * Sort one element's declarations of a property, winner first.
+ *
+ * @param declarations - Declarations in ascending order
+ * @returns Highest precedence first
+ */
+function byPrecedence(declarations) {
+    const layers = [
+        ...new Set(declarations.flatMap((d) => (d.source.layer ? [d.source.layer] : []))),
+    ];
+    return declarations
+        .map((declaration, position) => ({
+        declaration,
+        key: precedence(declaration, position, layers),
+    }))
+        .sort((a, b) => compare(b.key, a.key))
+        .map((entry) => entry.declaration);
+}
+/**
+ * The longhands the element's own declarations set (what hints check).
+ *
+ * @param matched - `CSS.getMatchedStylesForNode` response
+ * @returns Longhands
+ */
+export function ownProperties(matched) {
+    return [...new Set(orderedDeclarations(matched).map((declaration) => declaration.property))];
+}
+/**
+ * Resolve the cascade of the given properties for an element.
+ *
+ * @param matched - `CSS.getMatchedStylesForNode` response
+ * @param properties - Longhands to resolve
+ * @returns Resolution per property
+ */
+export function resolveCascade(matched, properties) {
+    const own = orderedDeclarations(matched);
+    const ancestors = (matched.inherited ?? []).map(orderedDeclarations);
+    const resolved = new Map();
+    for (const property of properties) {
+        const ranked = byPrecedence(own.filter((d) => d.property === property));
+        const [winner, ...overridden] = ranked;
+        if (winner) {
+            resolved.set(property, { winner, overridden });
+            continue;
+        }
+        resolved.set(property, inheritedWinner(property, ancestors));
+    }
+    return resolved;
+}
+/**
+ * The nearest ancestor's winning declaration of an inherited property.
+ *
+ * @param property - Longhand
+ * @param ancestors - Declarations of each ancestor, nearest first
+ * @returns The winner and the declarations it beat on that ancestor (none for
+ *   non-inherited properties or when no ancestor sets it)
+ */
+function inheritedWinner(property, ancestors) {
+    if (!isInherited(property))
+        return { overridden: [] };
+    for (const [depth, declarations] of ancestors.entries()) {
+        const ranked = byPrecedence(declarations.filter((d) => d.property === property)).map((declaration) => ({ ...declaration, ancestor: depth + 1 }));
+        const [winner, ...overridden] = ranked;
+        if (winner)
+            return { winner, overridden };
+    }
+    return { overridden: [] };
+}
+//# sourceMappingURL=inspectCascade.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * `dom inspect`'s cascade fields from the matched rules: hints (declarations
+ * that have no effect), `--rules` (which declaration sets each shown
+ * property, sides set by one declaration merged into the shorthand) and
+ * `--why` (every declaration of one property).
+ */
+import type { Protocol } from '../../connection/typed-cdp.js';
+import type { InspectResult } from '../../ipc/protocol/inspectTypes.js';
+import { type Declaration } from './inspectCascade.js';
+import type { StyleMap } from './inspectLayoutModel.js';
+/** Longhands reported together, so a shorthand can stand for its sides */
+export interface PropertyGroup {
+    shorthand?: string;
+    longhands: string[];
+}
+/** What the cascade fields are built from */
+export interface CascadeInput {
+    matched: Protocol.CSS.GetMatchedStylesForNodeResponse;
+    style: StyleMap;
+    parentStyle: StyleMap | undefined;
+    replaced: boolean;
+    /** Where a declaration comes from, for people */
+    label: (declaration: Declaration) => string;
+    rules?: boolean;
+    why?: string;
+    /** `--props` names: `--rules` then covers only these */
+    props?: string[];
+    /** Check for declarations that have no effect (default true) */
+    hints?: boolean;
+    formControl?: boolean;
+}
+/**
+ * The cascade fields of the result.
+ *
+ * @param input - Matched rules, computed styles, options
+ * @returns `hints` (empty when checked and nothing found), `rules` and `why`
+ */
+export declare function buildCascadeFields(input: CascadeInput): Partial<InspectResult>;
+//# sourceMappingURL=inspectCascadeModel.d.ts.map

package/dist/runtime/dom/inspectCascadeModel.js

@@ -0,0 +1,232 @@
+/**
+ * `dom inspect`'s cascade fields from the matched rules: hints (declarations
+ * that have no effect), `--rules` (which declaration sets each shown
+ * property, sides set by one declaration merged into the shorthand) and
+ * `--why` (every declaration of one property).
+ */
+import { normalizeProperty } from './inspectAllStyles.js';
+import { physicalName, ownProperties, resolveCascade, shorthandLonghands, } from './inspectCascade.js';
+import { formControlFontHints, inactiveHints, undefinedVariableHints, } from './inspectHints.js';
+import { buildWhy } from './inspectWhyModel.js';
+const SIDES = ['top', 'right', 'bottom', 'left'];
+const sides = (pattern) => SIDES.map((side) => pattern.replace('{side}', side));
+/** Properties `--rules` reports */
+const RULE_GROUPS = [
+    { longhands: ['display'] },
+    { longhands: ['position'] },
+    { shorthand: 'inset', longhands: sides('{side}') },
+    { longhands: ['z-index'] },
+    { longhands: ['width'] },
+    { longhands: ['height'] },
+    { longhands: ['min-width'] },
+    { longhands: ['max-width'] },
+    { longhands: ['min-height'] },
+    { longhands: ['max-height'] },
+    { shorthand: 'margin', longhands: sides('margin-{side}') },
+    { shorthand: 'padding', longhands: sides('padding-{side}') },
+    { shorthand: 'border-width', longhands: sides('border-{side}-width') },
+    { shorthand: 'border-style', longhands: sides('border-{side}-style') },
+    { shorthand: 'border-color', longhands: sides('border-{side}-color') },
+    {
+        shorthand: 'border-radius',
+        longhands: ['top-left', 'top-right', 'bottom-right', 'bottom-left'].map((c) => `border-${c}-radius`),
+    },
+    { longhands: ['background-color'] },
+    { longhands: ['background-image'] },
+    { longhands: ['color'] },
+    { longhands: ['font-family'] },
+    { longhands: ['font-size'] },
+    { longhands: ['font-weight'] },
+    { longhands: ['line-height'] },
+    { longhands: ['letter-spacing'] },
+    { longhands: ['text-align'] },
+    { longhands: ['text-transform'] },
+    { longhands: ['opacity'] },
+    { longhands: ['box-shadow'] },
+    { longhands: ['transform'] },
+    { longhands: ['flex-direction'] },
+    { longhands: ['flex-wrap'] },
+    { longhands: ['justify-content'] },
+    { longhands: ['align-items'] },
+    { shorthand: 'gap', longhands: ['row-gap', 'column-gap'] },
+    { longhands: ['grid-template-columns'] },
+    { longhands: ['grid-template-rows'] },
+    { shorthand: 'flex', longhands: ['flex-grow', 'flex-shrink', 'flex-basis'] },
+    { longhands: ['align-self'] },
+    { shorthand: 'overflow', longhands: ['overflow-x', 'overflow-y'] },
+    { longhands: ['cursor'] },
+];
+/**
+ * The cascade fields of the result.
+ *
+ * @param input - Matched rules, computed styles, options
+ * @returns `hints` (empty when checked and nothing found), `rules` and `why`
+ */
+export function buildCascadeFields(input) {
+    const ruleGroups = input.rules ? (input.props?.map(propertyGroup) ?? RULE_GROUPS) : [];
+    const whyGroup = input.why ? propertyGroup(input.why) : undefined;
+    const wanted = [
+        ...new Set([
+            ...ownProperties(input.matched),
+            ...ruleGroups.flatMap((group) => group.longhands),
+            ...(whyGroup?.longhands ?? []),
+        ]),
+    ];
+    const cascade = resolveCascade(input.matched, wanted);
+    const hints = input.hints === false ? undefined : buildHints(cascade, input);
+    const rules = buildRules(ruleGroups, cascade, input);
+    return {
+        ...(hints && { hints }),
+        ...(rules.length > 0 && { rules }),
+        ...(whyGroup && { why: buildWhy(whyGroup, cascade, input) }),
+    };
+}
+/**
+ * The longhands a property name stands for.
+ *
+ * @param name - Shorthand, longhand, logical or custom property
+ * @returns Group (a shorthand with its longhands, or one physical longhand)
+ */
+function propertyGroup(name) {
+    const longhands = shorthandLonghands(name);
+    return longhands
+        ? { shorthand: name, longhands: [...longhands] }
+        : { longhands: [physicalName(name)] };
+}
+/**
+ * Hints: declarations with no effect, and var() of unset custom properties;
+ * none without the computed style to check them against.
+ *
+ * @param cascade - Resolved properties
+ * @param input - Styles and the label function
+ * @returns Hints
+ */
+function buildHints(cascade, input) {
+    if (input.style['display'] === undefined)
+        return [];
+    const ctx = {
+        style: input.style,
+        parentStyle: input.parentStyle,
+        replaced: input.replaced,
+        formControl: input.formControl === true,
+    };
+    return [
+        ...inactiveHints(cascade, ctx),
+        ...undefinedVariableHints(cascade, input.style),
+        ...formControlFontHints(cascade, ctx),
+    ].map((hint) => ({
+        kind: hint.kind,
+        property: hint.property,
+        value: hint.value,
+        reason: hint.reason,
+        fix: hint.fix,
+        source: input.label(hint.declaration),
+    }));
+}
+/**
+ * `--rules`: one row per property set by an author declaration; one row for
+ * a group (`padding`, `border-width`) when a single declaration sets all of
+ * it, and one for a shorthand Chrome could not expand (`var()`, such as
+ * `border: 2px solid var(--c)` or `background: var(--bg)`) however many
+ * properties it sets.
+ *
+ * @param groups - Properties to report
+ * @param cascade - Resolved properties
+ * @param input - Computed style and the label function
+ * @returns Rules
+ */
+function buildRules(groups, cascade, input) {
+    const rows = groups.flatMap((group) => {
+        const resolutions = group.longhands.map((longhand) => cascade.get(longhand));
+        const winners = resolutions.map((resolution) => resolution?.winner);
+        const grouped = group.shorthand !== undefined ? groupedRow(group.shorthand, winners) : undefined;
+        if (grouped)
+            return [toRule(grouped.property, grouped, resolutions[0], input)];
+        return group.longhands.flatMap((longhand, i) => {
+            const winner = winners[i];
+            if (!winner || winner.source.origin === 'user-agent')
+                return [];
+            const unexpanded = winner.via !== undefined && winner.value === winner.written;
+            return unexpanded && winner.via
+                ? [toRule(winner.via, winner, resolutions[i], input)]
+                : [toRule(longhand, winner, resolutions[i], input)];
+        });
+    });
+    const seen = new Set();
+    return rows.filter((row) => {
+        const key = `${row.property}|${row.value}|${row.source}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * One row for a group of longhands that a single author declaration sets:
+ * the shorthand as written, or (set by a wider shorthand, like `border`
+ * for `border-width`) the values it gives the sides; a wider shorthand
+ * Chrome could not expand (`var()`) as written.
+ *
+ * @param shorthand - The group's shorthand
+ * @param winners - Winning declaration of each longhand
+ * @returns The row's declaration, or undefined when the sides differ in source
+ */
+function groupedRow(shorthand, winners) {
+    const [first] = winners;
+    if (!first?.via || first.source.origin === 'user-agent')
+        return undefined;
+    const same = winners.every((w) => w && w.via === first.via && sameSource(w, first));
+    if (!same)
+        return undefined;
+    const written = first.written ?? first.value;
+    if (first.via === shorthand || first.value === written) {
+        return { ...first, property: first.via, value: written };
+    }
+    const values = winners.map((w) => w?.value ?? '');
+    const value = values.every((v) => v === first.value) ? first.value : values.join(' ');
+    return { ...first, property: shorthand, value };
+}
+/**
+ * Whether two declarations come from the same place.
+ *
+ * @param a - Declaration
+ * @param b - Declaration
+ * @returns True for the same declaration (same rule and position)
+ */
+function sameSource(a, b) {
+    return (a.source.kind === b.source.kind &&
+        a.source.selector === b.source.selector &&
+        a.source.styleSheetId === b.source.styleSheetId &&
+        a.source.line === b.source.line &&
+        a.source.column === b.source.column);
+}
+/**
+ * A `--rules` row.
+ *
+ * @param property - Property shown
+ * @param winner - Winning declaration
+ * @param resolution - Its resolution (for what it overrides)
+ * @param input - Computed style and the label function
+ * @returns Rule
+ */
+function toRule(property, winner, resolution, input) {
+    const computed = input.style[property];
+    const overrides = [
+        ...new Set((resolution?.overridden ?? [])
+            .filter((d) => d.source.origin !== 'user-agent')
+            .map((d) => d.source.selector ?? d.source.kind)),
+    ];
+    return {
+        property,
+        value: winner.value,
+        ...(winner.value.includes('var(') &&
+            computed !== undefined && { computed: normalizeProperty(property, computed) }),
+        source: input.label(winner),
+        ...(overrides.length > 0 && { overrides }),
+        ...(winner.ancestor !== undefined && { inherited: winner.ancestor }),
+        ...(winner.important && { important: true }),
+        ...(winner.source.layer && { layer: winner.source.layer }),
+        ...(winner.source.condition && { condition: winner.source.condition }),
+    };
+}
+//# sourceMappingURL=inspectCascadeModel.js.map