browser-debugger-cli 0.9.0 → 0.11.0

package/dist/runtime/dom/inspectLayoutModel.js

@@ -0,0 +1,346 @@
+/**
+ * Box and layout groups of `bdg dom inspect`, from computed styles.
+ *
+ * Core facts are always there (display, padding/margin/border as computed,
+ * even when they equal the UA default); the rest only when it applies
+ * (container fields for flex and grid containers, item fields in a flex or
+ * grid parent) and is not a no-op default. Sizing is named like Figma's
+ * auto layout: hug (sized by the content), fill (stretched by the parent)
+ * or fixed, from the computed (not resolved) width and height.
+ */
+import { compressTracks, cssLength, round1 } from '../../utils/cssValues.js';
+const SIDES = ['top', 'right', 'bottom', 'left'];
+/**
+ * The four sides of a box property.
+ *
+ * @param style - Computed styles
+ * @param name - e.g. `padding-{side}`, `border-{side}-width`
+ * @returns Top, right, bottom, left
+ */
+export function sides(style, name) {
+    return SIDES.map((side) => cssLength(style[name.replace('{side}', side)]));
+}
+/**
+ * Whether a computed value is a no-op for a size limit.
+ *
+ * @param value - Computed min/max width or height
+ * @returns True for `auto`, `none` and 0
+ */
+function noLimit(value) {
+    return value === undefined || value === 'auto' || value === 'none' || value === '0px';
+}
+/**
+ * Min or max sizes that constrain the box.
+ *
+ * @param style - Computed styles
+ * @param kind - `min` or `max`
+ * @returns Width and height limits, or undefined when there are none
+ */
+function sizeLimits(style, kind) {
+    const w = style[`${kind}-width`];
+    const h = style[`${kind}-height`];
+    const limits = {
+        ...(!noLimit(w) && { w: cssLength(w) }),
+        ...(!noLimit(h) && { h: cssLength(h) }),
+    };
+    return Object.keys(limits).length > 0 ? limits : undefined;
+}
+/**
+ * The box group: padding, margin, border widths, box-sizing, size limits,
+ * overflow and the content size when it overflows.
+ *
+ * @param style - Computed styles
+ * @param raw - Page-side measurements
+ * @returns Box group
+ */
+export function buildBox(style, raw) {
+    const overflowX = style['overflow-x'] ?? 'visible';
+    const overflowY = style['overflow-y'] ?? 'visible';
+    const overflow = overflowX === 'visible' && overflowY === 'visible'
+        ? undefined
+        : overflowX === overflowY
+            ? overflowX
+            : `${overflowX} ${overflowY}`;
+    const min = sizeLimits(style, 'min');
+    const max = sizeLimits(style, 'max');
+    return {
+        padding: sides(style, 'padding-{side}'),
+        margin: sides(style, 'margin-{side}'),
+        border: sides(style, 'border-{side}-width'),
+        sizing: style['box-sizing'] ?? 'content-box',
+        ...(min && { min }),
+        ...(max && { max }),
+        ...(overflow && { overflow }),
+        ...(raw.scroll && { scroll: { w: raw.scroll.w, h: raw.scroll.h } }),
+    };
+}
+/**
+ * Row and column gap, when there is one.
+ *
+ * @param style - Computed styles
+ * @returns One length when both are equal, else row and column
+ */
+function gapOf(style) {
+    const toLength = (value) => value === undefined || value === 'normal' ? 0 : cssLength(value);
+    const row = toLength(style['row-gap']);
+    const column = toLength(style['column-gap']);
+    if (row === 0 && column === 0)
+        return undefined;
+    return row === column ? row : [row, column];
+}
+/**
+ * Whether a display value makes a flex or grid container.
+ *
+ * @param display - Computed display
+ * @returns `flex`, `grid` or undefined
+ */
+export function containerKind(display) {
+    if (display === undefined)
+        return undefined;
+    if (/(^|-)flex$/.test(display) || display === '-webkit-box')
+        return 'flex';
+    return /(^|-)grid$/.test(display) ? 'grid' : undefined;
+}
+/**
+ * Flex or grid container fields that are not no-op defaults (the flex
+ * direction is always there).
+ *
+ * @param style - Computed styles
+ * @returns Container fields, empty for other displays
+ */
+export function buildContainer(style) {
+    const kind = containerKind(style['display']);
+    if (!kind)
+        return {};
+    const justify = style['justify-content'];
+    const align = style['align-items'];
+    const wrap = style['flex-wrap'];
+    const gap = gapOf(style);
+    const columns = style['grid-template-columns'] ?? 'none';
+    const rows = style['grid-template-rows'] ?? 'none';
+    return {
+        ...(kind === 'flex' && { direction: style['flex-direction'] ?? 'row' }),
+        ...(kind === 'flex' && wrap && wrap !== 'nowrap' && { wrap }),
+        ...(kind === 'grid' && columns !== 'none' && { columns: compressTracks(columns) }),
+        ...(kind === 'grid' && rows !== 'none' && { rows: compressTracks(rows) }),
+        ...(justify && !['normal', 'flex-start', 'start'].includes(justify) && { justify }),
+        ...(align && !['normal', 'stretch'].includes(align) && { align }),
+        ...(gap !== undefined && { gap }),
+    };
+}
+/**
+ * Position fields: position unless static, inset unless all `auto` (or all
+ * 0/auto for relative), z-index unless `auto`.
+ *
+ * @param style - Computed styles
+ * @returns Position fields
+ */
+function positionFields(style) {
+    const position = style['position'] ?? 'static';
+    if (position === 'static')
+        return {};
+    const inset = sides(style, '{side}');
+    const allAuto = inset.every((value) => value === 'auto');
+    const noOffset = inset.every((value) => value === 'auto' || value === 0);
+    const z = style['z-index'];
+    return {
+        position,
+        ...(!allAuto && !(position === 'relative' && noOffset) && { inset }),
+        ...(z && z !== 'auto' && { z: /^-?\d+$/.test(z) ? Number(z) : z }),
+    };
+}
+/**
+ * Fields of an element laid out by a flex or grid parent: flex
+ * grow/shrink/basis (unless `0 1 auto`), self alignment, order and grid area.
+ *
+ * @param style - Computed styles
+ * @param parentDisplay - Display of the layout parent
+ * @returns Item fields, empty in other parents
+ */
+function itemFields(style, parentDisplay) {
+    const parentKind = containerKind(parentDisplay);
+    if (!parentKind)
+        return {};
+    const flex = `${style['flex-grow'] ?? 0} ${style['flex-shrink'] ?? 1} ${cssLength(style['flex-basis'] ?? 'auto')}`;
+    const self = style['align-self'];
+    const justifySelf = style['justify-self'];
+    const order = Number(style['order'] ?? 0);
+    const placement = ['grid-row-start', 'grid-column-start', 'grid-row-end', 'grid-column-end'].map((name) => style[name] ?? 'auto');
+    const selfAlign = [self, parentKind === 'grid' ? justifySelf : undefined]
+        .filter((value) => value && value !== 'auto')
+        .join(' ');
+    return {
+        ...(parentKind === 'flex' && flex !== '0 1 auto' && { flex }),
+        ...(selfAlign && { self: selfAlign }),
+        ...(order !== 0 && { order }),
+        ...(parentKind === 'grid' &&
+            placement.some((value) => value !== 'auto') && { area: placement.join(' / ') }),
+    };
+}
+/**
+ * The parent line: its description, display, container fields and its
+ * text alignment (when not the start).
+ *
+ * @param parentStyle - Computed styles of the layout parent
+ * @param element - Its short description
+ * @returns Parent fields
+ */
+function buildParent(parentStyle, element) {
+    const textAlign = parentStyle['text-align'];
+    return {
+        element,
+        display: parentStyle['display'] ?? 'block',
+        ...buildContainer(parentStyle),
+        ...(textAlign && !['start', 'left', '-webkit-auto'].includes(textAlign) && { textAlign }),
+    };
+}
+/**
+ * Whether an item stretches along the cross axis of its flex or grid parent.
+ *
+ * @param self - The item's `align-self`/`justify-self`
+ * @param items - The parent's `align-items`/`justify-items`
+ * @returns True for `stretch` and `normal` (stretch for non-replaced items)
+ */
+function stretches(self, items) {
+    const effective = self === 'auto' ? (items ?? 'normal') : self;
+    return effective === 'normal' || effective === 'stretch';
+}
+/**
+ * How the element is sized along an axis inside a flex parent.
+ *
+ * @param input - Sizing inputs
+ * @param automatic - The size is `auto` (or content-based)
+ * @returns Sizing mode
+ */
+function flexItemSizing(input, automatic) {
+    const mainAxis = (input.parentDirection ?? 'row').startsWith('row') ? 'w' : 'h';
+    if (input.axis === mainAxis) {
+        if (input.flexGrow > 0)
+            return 'fill';
+        if (!['auto', 'content'].includes(input.flexBasis))
+            return 'fixed';
+        return automatic ? 'hug' : 'fixed';
+    }
+    if (automatic && input.size === 'auto' && stretches(input.alignSelf, input.parentAlignItems)) {
+        return 'fill';
+    }
+    return automatic ? 'hug' : input.size === '100%' ? 'fill' : 'fixed';
+}
+/**
+ * Sizing of a replaced element with an automatic size: its intrinsic size
+ * (hug), unless it grows along a flex main axis or is stretched explicitly
+ * (`normal` alignment does not stretch replaced elements).
+ *
+ * @param input - Computed size, display and the parent's layout
+ * @returns Sizing mode
+ */
+function replacedSizing(input) {
+    const kind = containerKind(input.parentDisplay);
+    const mainAxis = (input.parentDirection ?? 'row').startsWith('row') ? 'w' : 'h';
+    if (kind === 'flex' && input.axis === mainAxis && input.flexGrow > 0)
+        return 'fill';
+    const self = input.axis === 'w' && kind === 'grid' ? input.justifySelf : input.alignSelf;
+    return kind && self === 'stretch' ? 'fill' : 'hug';
+}
+/**
+ * How the element is sized along an axis: `fill` when its parent stretches
+ * it (a flex item that grows, a stretched cross axis or grid cell, a block's
+ * width in normal flow, 100%), `hug` when its content sizes it (`auto` and
+ * the content keywords elsewhere), `fixed` for a length.
+ *
+ * @param input - Computed size, display and the parent's layout
+ * @returns Sizing mode
+ */
+export function deriveSizing(input) {
+    const automatic = /^(auto|fit-content|max-content|min-content)$/.test(input.size) || input.size === '';
+    if (input.display === 'inline')
+        return 'hug';
+    if (input.replaced && automatic)
+        return replacedSizing(input);
+    if (input.position === 'absolute' || input.position === 'fixed')
+        return automatic ? 'hug' : 'fixed';
+    const parentKind = containerKind(input.parentDisplay);
+    if (parentKind === 'flex')
+        return flexItemSizing(input, automatic);
+    if (parentKind === 'grid' && input.size === 'auto') {
+        const fills = input.axis === 'w'
+            ? stretches(input.justifySelf, input.parentJustifyItems)
+            : stretches(input.alignSelf, input.parentAlignItems);
+        return fills ? 'fill' : 'hug';
+    }
+    if (input.size === '100%')
+        return 'fill';
+    if (!automatic)
+        return 'fixed';
+    const blockLevel = !/^inline|^table$/.test(input.display) && input.float === 'none';
+    return input.axis === 'w' && input.size === 'auto' && blockLevel ? 'fill' : 'hug';
+}
+/**
+ * Sizing along both axes.
+ *
+ * @param style - Computed styles
+ * @param parentStyle - Computed styles of the layout parent
+ * @param raw - Computed (not resolved) width and height, and whether the element is replaced
+ * @returns Width and height sizing
+ */
+function sizingOf(style, parentStyle, raw) {
+    const typed = raw.typed;
+    const base = {
+        ...(raw.replaced && { replaced: true }),
+        display: style['display'] ?? 'inline',
+        position: style['position'] ?? 'static',
+        float: style['float'] ?? 'none',
+        flexGrow: Number(style['flex-grow'] ?? 0),
+        flexBasis: style['flex-basis'] ?? 'auto',
+        alignSelf: style['align-self'] ?? 'auto',
+        justifySelf: style['justify-self'] ?? 'auto',
+        ...(parentStyle && {
+            parentDisplay: parentStyle['display'] ?? 'block',
+            parentDirection: parentStyle['flex-direction'] ?? 'row',
+            parentAlignItems: parentStyle['align-items'] ?? 'normal',
+            parentJustifyItems: parentStyle['justify-items'] ?? 'normal',
+        }),
+    };
+    return {
+        w: deriveSizing({ ...base, size: typed.width, axis: 'w' }),
+        h: deriveSizing({ ...base, size: typed.height, axis: 'h' }),
+    };
+}
+/**
+ * Round each value of a record of distances.
+ *
+ * @param distances - Distances in CSS px
+ * @returns Rounded distances
+ */
+function rounded(distances) {
+    return Object.fromEntries(Object.entries(distances).map(([key, value]) => [key, round1(value)]));
+}
+/**
+ * The layout group: display, position, container and item fields, valign
+ * for inline displays, float, sizing, and the parent with the element's
+ * place in it (offsets from its content edges, gaps to the siblings).
+ *
+ * @param style - Computed styles
+ * @param parentStyle - Computed styles of the layout parent (none for the root)
+ * @param raw - Page-side measurements
+ * @returns Layout group
+ */
+export function buildLayout(style, parentStyle, raw) {
+    const display = style['display'] ?? 'inline';
+    const valign = style['vertical-align'];
+    const float = style['float'];
+    const siblings = raw.siblings && Object.keys(raw.siblings).length > 0 ? raw.siblings : undefined;
+    return {
+        display,
+        ...positionFields(style),
+        ...buildContainer(style),
+        ...itemFields(style, parentStyle?.['display']),
+        ...(/^inline|table-cell/.test(display) && valign && valign !== 'baseline' && { valign }),
+        ...(float && float !== 'none' && { float }),
+        ...(display !== 'none' && { sizing: sizingOf(style, parentStyle, raw) }),
+        ...(parentStyle && raw.parent && { parent: buildParent(parentStyle, raw.parent) }),
+        ...(raw.inParent && { inParent: rounded(raw.inParent) }),
+        ...(siblings && { siblings: rounded(siblings) }),
+    };
+}
+//# sourceMappingURL=inspectLayoutModel.js.map

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

@@ -0,0 +1,74 @@
+/**
+ * Assemble the `bdg dom inspect` result from what CDP and the page-side walk
+ * read: the header (label, text, rect, what keeps it from being seen), then
+ * the groups (or, with `--all`/`--props`, the property lists) and the child
+ * tree. Pure: every input is plain data, so the rules are tested without a
+ * browser.
+ */
+import type { Protocol } from '../../connection/typed-cdp.js';
+import type { ElementLayout } from '../../ipc/protocol/domTypes.js';
+import type { InspectResult, InspectVisibility } from '../../ipc/protocol/inspectTypes.js';
+import { type StyleMap } from './inspectLayoutModel.js';
+import { type PlatformFont, type PseudoSource } from './inspectPaintModel.js';
+import type { RawInspect } from './inspectScripts.js';
+/** What one inspect read */
+export interface InspectSources {
+    raw: RawInspect;
+    style: StyleMap;
+    parentStyle?: StyleMap;
+    pseudo: PseudoSource[];
+    fonts: PlatformFont[];
+    /** Border box size from `DOM.getBoxModel`; absent when the element has no box */
+    size?: {
+        w: number;
+        h: number;
+    };
+    /** The element as `dom layout` measures it */
+    layout?: ElementLayout;
+    colorScheme?: 'light' | 'dark';
+    /** Matched rules for the cascade fields; `timeout` or `failed` when they were not read */
+    matched?: Protocol.CSS.GetMatchedStylesForNodeResponse | 'timeout' | 'failed';
+    /** `--rules` was asked for */
+    rules?: boolean;
+    /** `--why` property */
+    why?: string;
+    /** `--props` names, custom property patterns expanded (`--rules` covers only these) */
+    props?: string[];
+    /** `--no-hints` */
+    hints?: false;
+}
+/** What the command asked for */
+export interface InspectRequest {
+    selector: string;
+    index: number;
+    count: number;
+    /** Tree rows shown at most */
+    treeLimit: number;
+    all?: boolean;
+    /** `--props` values (from `selectedProps`) */
+    propValues?: InspectResult['props'];
+}
+/**
+ * The element's label: tag, id and the first classes, with a count of the rest.
+ *
+ * @param raw - Tag, id and classes
+ * @returns e.g. `a.z-1.max-sm:hidden(+11)`, `input#user-name`
+ */
+export declare function elementLabel(raw: Pick<RawInspect, 'tag' | 'id' | 'classes'>): string;
+/**
+ * Why the element cannot be seen, from `dom layout`'s measurements.
+ *
+ * @param layout - Layout measurements
+ * @param rendered - The element has a box
+ * @returns Visibility fields
+ */
+export declare function visibilityOf(layout: ElementLayout | undefined, rendered: boolean): InspectVisibility;
+/**
+ * The `bdg dom inspect` result.
+ *
+ * @param sources - What CDP and the page-side walk read
+ * @param request - Selector, index, match count and options
+ * @returns Inspect result
+ */
+export declare function buildInspectResult(sources: InspectSources, request: InspectRequest): InspectResult;
+//# sourceMappingURL=inspectModel.d.ts.map

package/dist/runtime/dom/inspectModel.js

@@ -0,0 +1,184 @@
+/**
+ * Assemble the `bdg dom inspect` result from what CDP and the page-side walk
+ * read: the header (label, text, rect, what keeps it from being seen), then
+ * the groups (or, with `--all`/`--props`, the property lists) and the child
+ * tree. Pure: every input is plain data, so the rules are tested without a
+ * browser.
+ */
+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 { buildTree, rowText } from './inspectTree.js';
+import { hexColor, relativeLuminance } from '../../utils/color.js';
+import { normalizeCssValue, round1 } from '../../utils/cssValues.js';
+/** Classes shown in the label (the rest are counted) */
+const LABEL_CLASSES = 2;
+/**
+ * The element's label: tag, id and the first classes, with a count of the rest.
+ *
+ * @param raw - Tag, id and classes
+ * @returns e.g. `a.z-1.max-sm:hidden(+11)`, `input#user-name`
+ */
+export function elementLabel(raw) {
+    const shown = raw.classes
+        .slice(0, LABEL_CLASSES)
+        .map((name) => `.${name}`)
+        .join('');
+    const more = raw.classes.length - LABEL_CLASSES;
+    return `${raw.tag}${raw.id ? `#${raw.id}` : ''}${shown}${more > 0 ? `(+${more})` : ''}`;
+}
+/**
+ * Why the element cannot be seen, from `dom layout`'s measurements.
+ *
+ * @param layout - Layout measurements
+ * @param rendered - The element has a box
+ * @returns Visibility fields
+ */
+export function visibilityOf(layout, rendered) {
+    if (!rendered)
+        return { notRendered: true, ...(layout?.hiddenReason && { hidden: layout.hiddenReason }) };
+    if (!layout)
+        return {};
+    const hidden = layout.inViewport === 'hidden' ? layout.hiddenReason : layout.invisible;
+    const offscreen = ['above', 'below', 'left', 'right'].includes(layout.inViewport)
+        ? layout.inViewport
+        : undefined;
+    return {
+        ...(hidden && { hidden }),
+        ...(offscreen && { offscreen }),
+        ...(layout.coveredBy && { coveredBy: layout.coveredBy }),
+        ...(layout.coverTransparent && { coverTransparent: true }),
+    };
+}
+/** Below this relative luminance a page background counts as dark */
+const DARK_LUMINANCE = 0.18;
+/**
+ * Header fields: label, text, placeholder, context, rect, visibility and
+ * the color scheme.
+ *
+ * @param sources - What was read
+ * @param request - Selector, index and match count
+ * @returns Header part of the result
+ */
+function header(sources, request) {
+    const { raw, size, layout } = sources;
+    const content = raw.textual && raw.content ? rowText(raw.content) : undefined;
+    return {
+        success: true,
+        selector: request.selector,
+        count: request.count,
+        index: request.index,
+        element: elementLabel(raw),
+        ...(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) },
+        }),
+        visibility: visibilityOf(layout, size !== undefined),
+        ...(sources.colorScheme && { colorScheme: sources.colorScheme }),
+        ...(sources.colorScheme === 'dark' && pageLooksDark(raw) && { theme: 'dark' }),
+        ...(raw.animating.length > 0 && { animating: raw.animating }),
+    };
+}
+/**
+ * Whether the page renders dark: a dark canvas (its color-scheme), or a dark
+ * background on the page's root (the backgrounds of body and html).
+ *
+ * @param raw - Backgrounds from the element up to the root, and the canvas
+ * @returns True for a dark page
+ */
+function pageLooksDark(raw) {
+    if (raw.canvasDark)
+        return true;
+    const root = effectiveBackground(raw.backgrounds.slice(-2), false).color;
+    return relativeLuminance(root) < DARK_LUMINANCE;
+}
+/**
+ * The style groups: box, layout, text, fills, strokes, radius, outline,
+ * effects, fx, state and pseudo-elements.
+ *
+ * @param sources - What was read
+ * @returns Group fields
+ */
+function groups(sources) {
+    const { style, parentStyle, raw } = sources;
+    const text = buildText(style, parentStyle, raw, sources.fonts);
+    const fills = buildFills(style);
+    const strokes = buildStrokes(style);
+    const radius = buildRadius(style);
+    const outline = buildOutline(style);
+    const effects = buildEffects(style);
+    const fx = buildFx(style);
+    const state = buildState(style, raw);
+    const pseudo = buildPseudo(sources.pseudo, style, raw);
+    const opacity = Number(style['opacity'] ?? 1);
+    const blend = style['mix-blend-mode'];
+    return {
+        box: buildBox(style, raw),
+        layout: buildLayout(style, parentStyle, raw),
+        ...(text && { text }),
+        ...(fills.length > 0 && { fills }),
+        ...(opacity !== 1 && { opacity }),
+        ...(blend && blend !== 'normal' && { blend }),
+        ...(strokes.length > 0 && { strokes }),
+        ...(radius && { radius }),
+        ...(outline && { outline }),
+        ...(effects.length > 0 && { effects }),
+        ...(fx && { fx }),
+        ...(state && { state }),
+        ...(pseudo && { pseudo }),
+    };
+}
+/**
+ * The child tree fields.
+ *
+ * @param raw - Page-side walk
+ * @param limit - Rows shown at most
+ * @returns Children, hidden count and rows left out
+ */
+function treeFields(raw, limit) {
+    if (!raw.tree)
+        return {};
+    const { children, moreRows } = buildTree(raw.tree, limit, raw.treeSkipped);
+    return {
+        ...(children.length > 0 && { children }),
+        ...(raw.hiddenChildren > 0 && { hiddenChildren: raw.hiddenChildren }),
+        ...(moreRows > 0 && { moreRows }),
+    };
+}
+/**
+ * The `--all` list: the element's own non-default longhands, plus its
+ * generated pseudo-elements' content and the placeholder color.
+ *
+ * @param sources - What was read
+ * @returns Properties and values
+ */
+function allFields(sources) {
+    const all = allStyles(sources.style, sources.raw.svg === true);
+    for (const pseudo of sources.pseudo) {
+        const content = pseudo.style['content'];
+        if (content && content !== 'none' && content !== 'normal') {
+            all[`${pseudo.type}`] = normalizeCssValue(content);
+        }
+    }
+    if (sources.raw.placeholderColor)
+        all['::placeholder'] = `color ${hexColor(sources.raw.placeholderColor)}`;
+    return all;
+}
+/**
+ * The `bdg dom inspect` result.
+ *
+ * @param sources - What CDP and the page-side walk read
+ * @param request - Selector, index, match count and options
+ * @returns Inspect result
+ */
+export function buildInspectResult(sources, request) {
+    const result = header(sources, request);
+    if (request.propValues)
+        return { ...result, props: request.propValues };
+    const body = request.all ? { all: allFields(sources) } : groups(sources);
+    return { ...result, ...body, ...treeFields(sources.raw, request.treeLimit) };
+}
+//# sourceMappingURL=inspectModel.js.map