browser-debugger-cli 0.8.0 → 0.10.0

package/dist/runtime/dom/inspectTree.js

@@ -0,0 +1,134 @@
+/**
+ * The child tree of `bdg dom inspect`: the page-side walk's children
+ * ({@link RawTreeNode}) with sizes rounded, consecutive identical siblings
+ * (same label, size and layout) grouped into one row with a count
+ * (`li.card ×33 266x107`), and cut to a number of rows in document order.
+ */
+import { containerKind } from './inspectLayoutModel.js';
+/** Default depth of the tree */
+export const DEFAULT_TREE_DEPTH = 2;
+/** Default number of rows */
+export const DEFAULT_TREE_LIMIT = 20;
+/** Characters of text kept per row */
+const ROW_TEXT_LENGTH = 30;
+/**
+ * Cut a row's text on a whole character.
+ *
+ * @param text - Text
+ * @returns At most {@link ROW_TEXT_LENGTH} characters, with `…` when cut
+ */
+export function rowText(text) {
+    const characters = Array.from(text);
+    return characters.length > ROW_TEXT_LENGTH
+        ? `${characters.slice(0, ROW_TEXT_LENGTH).join('').trimEnd()}…`
+        : text;
+}
+/**
+ * One child as a tree row (its children converted too).
+ *
+ * @param raw - Child from the page-side walk
+ * @returns Tree row
+ */
+function toNode(raw) {
+    const layout = containerKind(raw.display);
+    const children = raw.children ? groupSiblings(raw.children.map(toNode)) : undefined;
+    return {
+        element: raw.label,
+        x: Math.round(raw.x * 10) / 10,
+        y: Math.round(raw.y * 10) / 10,
+        w: Math.round(raw.w),
+        h: Math.round(raw.h),
+        ...(layout && { layout }),
+        ...(raw.text && { text: rowText(raw.text) }),
+        ...(children && children.length > 0 && { children }),
+        ...(raw.childCount && { childCount: raw.childCount }),
+        ...(raw.hidden && { hiddenChildren: raw.hidden }),
+    };
+}
+/**
+ * Whether two siblings look the same in the tree.
+ *
+ * @param a - Row
+ * @param b - Row
+ * @returns True for the same label, size and layout
+ */
+function identical(a, b) {
+    return a.element === b.element && a.w === b.w && a.h === b.h && a.layout === b.layout;
+}
+/**
+ * Group runs of identical siblings into one row with a count. A group keeps
+ * its text only when every member has the same, and lists no children.
+ *
+ * @param nodes - Sibling rows
+ * @returns Rows with runs grouped
+ */
+export function groupSiblings(nodes) {
+    const grouped = [];
+    for (let i = 0; i < nodes.length;) {
+        const first = nodes[i];
+        let run = 1;
+        while (i + run < nodes.length && identical(first, nodes[i + run]))
+            run++;
+        if (run === 1) {
+            grouped.push(first);
+        }
+        else {
+            const members = nodes.slice(i, i + run);
+            const sameText = members.every((member) => member.text === first.text);
+            const { children: _children, childCount: _count, hiddenChildren: _hidden, text, ...row } = first;
+            grouped.push({ ...row, ...(sameText && text && { text }), count: run });
+        }
+        i += run;
+    }
+    return grouped;
+}
+/**
+ * Rows a node takes in the tree (itself and its listed descendants).
+ *
+ * @param node - Row
+ * @returns Row count
+ */
+function rowCount(node) {
+    return 1 + (node.children ?? []).reduce((sum, child) => sum + rowCount(child), 0);
+}
+/**
+ * Keep the first rows in document order.
+ *
+ * @param nodes - Rows
+ * @param budget - Rows still allowed (decremented)
+ * @returns Kept rows and the number left out
+ */
+function prune(nodes, budget) {
+    const kept = [];
+    let dropped = 0;
+    for (const node of nodes) {
+        if (budget.left <= 0) {
+            dropped += rowCount(node);
+            continue;
+        }
+        budget.left--;
+        if (!node.children) {
+            kept.push(node);
+            continue;
+        }
+        const sub = prune(node.children, budget);
+        dropped += sub.dropped;
+        const { children: _children, ...row } = node;
+        kept.push(sub.kept.length > 0 ? { ...row, children: sub.kept } : row);
+    }
+    return { kept, dropped };
+}
+/**
+ * The child tree from the page-side walk: grouped, then cut to `limit` rows.
+ *
+ * @param raw - Children from the walk
+ * @param limit - Rows shown at most
+ * @param skipped - Children the walk did not reach (counted as left out)
+ * @returns Rows and the number of rows left out
+ */
+export function buildTree(raw, limit, skipped = 0) {
+    const rows = groupSiblings(raw.map(toNode));
+    const { kept, dropped } = prune(rows, { left: limit });
+    return { children: kept, moreRows: dropped + skipped };
+}
+//# sourceMappingURL=inspectTree.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * `var()` in declared values: which custom properties a value uses, which of
+ * them are not set, and the value with them substituted. A fallback counts
+ * only when its custom property is not set.
+ */
+import type { StyleMap } from './inspectLayoutModel.js';
+/**
+ * The custom properties a value uses that are not set and have no fallback:
+ * the fallback of an unset one is used instead (and checked in turn).
+ *
+ * @param value - Value as written
+ * @param style - Computed styles (custom properties included)
+ * @returns Names of the unset custom properties
+ */
+export declare function unsetVariables(value: string, style: StyleMap): string[];
+/**
+ * The custom properties a value takes its value from (fallbacks only when
+ * used).
+ *
+ * @param value - Value as written
+ * @param style - Computed styles
+ * @returns Names
+ */
+export declare function usedVariables(value: string, style: StyleMap): string[];
+/**
+ * A value with its custom properties substituted.
+ *
+ * @param value - Value as written
+ * @param style - Computed styles
+ * @returns Substituted value (unset ones without fallback left as written)
+ */
+export declare function substituteVariables(value: string, style: StyleMap): string;
+//# sourceMappingURL=inspectVariables.d.ts.map

package/dist/runtime/dom/inspectVariables.js

@@ -0,0 +1,94 @@
+/**
+ * `var()` in declared values: which custom properties a value uses, which of
+ * them are not set, and the value with them substituted. A fallback counts
+ * only when its custom property is not set.
+ */
+/**
+ * The top-level `var()` calls of a value.
+ *
+ * @param value - Value as written
+ * @returns Calls in order (nested ones are inside a fallback)
+ */
+function varCalls(value) {
+    const calls = [];
+    for (let start = value.indexOf('var('); start !== -1; start = value.indexOf('var(', start + 1)) {
+        const end = closingParen(value, start + 3);
+        const [name = '', ...fallback] = value.slice(start + 4, end).split(',');
+        calls.push({
+            start,
+            end,
+            name: name.trim(),
+            ...(fallback.length > 0 && { fallback: fallback.join(',').trim() }),
+        });
+        start = end;
+    }
+    return calls;
+}
+/**
+ * Index of the parenthesis that closes the one at `open`.
+ *
+ * @param text - Text
+ * @param open - Index of `(`
+ * @returns Index of the matching `)` (the end of the text when unbalanced)
+ */
+function closingParen(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+        if (text[i] === '(')
+            depth++;
+        if (text[i] === ')' && --depth === 0)
+            return i;
+    }
+    return text.length;
+}
+/**
+ * The custom properties a value uses that are not set and have no fallback:
+ * the fallback of an unset one is used instead (and checked in turn).
+ *
+ * @param value - Value as written
+ * @param style - Computed styles (custom properties included)
+ * @returns Names of the unset custom properties
+ */
+export function unsetVariables(value, style) {
+    return varCalls(value).flatMap((call) => {
+        if (style[call.name] !== undefined)
+            return [];
+        return call.fallback !== undefined ? unsetVariables(call.fallback, style) : [call.name];
+    });
+}
+/**
+ * The custom properties a value takes its value from (fallbacks only when
+ * used).
+ *
+ * @param value - Value as written
+ * @param style - Computed styles
+ * @returns Names
+ */
+export function usedVariables(value, style) {
+    return varCalls(value).flatMap((call) => style[call.name] !== undefined || call.fallback === undefined
+        ? [call.name]
+        : usedVariables(call.fallback, style));
+}
+/**
+ * A value with its custom properties substituted.
+ *
+ * @param value - Value as written
+ * @param style - Computed styles
+ * @returns Substituted value (unset ones without fallback left as written)
+ */
+export function substituteVariables(value, style) {
+    let result = '';
+    let last = 0;
+    for (const call of varCalls(value)) {
+        const set = style[call.name];
+        const replacement = set !== undefined
+            ? set.trim()
+            : call.fallback !== undefined
+                ? substituteVariables(call.fallback, style)
+                : value.slice(call.start, call.end + 1);
+        result += value.slice(last, call.start) + replacement;
+        last = call.end + 1;
+    }
+    return result + value.slice(last);
+}
+//# sourceMappingURL=inspectVariables.js.map

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

@@ -0,0 +1,20 @@
+/**
+ * `dom inspect --why <property>`: every declaration of a property on the
+ * element, the winner first, with `var()` values substituted and where the
+ * winner's custom properties are set. A shorthand gives one answer when one
+ * declaration sets all its longhands (listing every declaration it beats on
+ * any of them), else one per longhand.
+ */
+import type { InspectWhy } from '../../ipc/protocol/inspectTypes.js';
+import { type Resolution } from './inspectCascade.js';
+import type { CascadeInput, PropertyGroup } from './inspectCascadeModel.js';
+/**
+ * `--why` for a property.
+ *
+ * @param group - The property and its longhands
+ * @param cascade - Resolved properties
+ * @param input - Matched rules, computed style and the label function
+ * @returns One entry, or one per longhand when they differ
+ */
+export declare function buildWhy(group: PropertyGroup, cascade: Map<string, Resolution>, input: CascadeInput): InspectWhy[];
+//# sourceMappingURL=inspectWhyModel.d.ts.map

package/dist/runtime/dom/inspectWhyModel.js

@@ -0,0 +1,134 @@
+/**
+ * `dom inspect --why <property>`: every declaration of a property on the
+ * element, the winner first, with `var()` values substituted and where the
+ * winner's custom properties are set. A shorthand gives one answer when one
+ * declaration sets all its longhands (listing every declaration it beats on
+ * any of them), else one per longhand.
+ */
+import { normalizeProperty } from './inspectAllStyles.js';
+import { resolveCascade } from './inspectCascade.js';
+import { substituteVariables, unsetVariables, usedVariables, } from './inspectVariables.js';
+/**
+ * `--why` for a property.
+ *
+ * @param group - The property and its longhands
+ * @param cascade - Resolved properties
+ * @param input - Matched rules, computed style and the label function
+ * @returns One entry, or one per longhand when they differ
+ */
+export function buildWhy(group, cascade, input) {
+    const whys = group.longhands.map((longhand) => whyOf(longhand, cascade.get(longhand), input));
+    const [first] = whys;
+    if (!first || group.shorthand === undefined)
+        return whys;
+    const winner = JSON.stringify(first.chain[0]);
+    if (!whys.every((why) => JSON.stringify(why.chain[0]) === winner))
+        return whys;
+    const values = whys.map((why) => why.computed);
+    const computed = values.every((value) => value === first.computed)
+        ? first.computed
+        : values.join(' ');
+    const beaten = whys.flatMap((why) => why.chain.slice(1));
+    const overridden = [...new Map(beaten.map((entry) => [JSON.stringify(entry), entry])).values()];
+    const chain = [...first.chain.slice(0, 1), ...overridden];
+    return [{ ...first, property: group.shorthand, computed, chain }];
+}
+/**
+ * `--why` for one longhand.
+ *
+ * @param property - Longhand
+ * @param resolution - Its resolution
+ * @param input - Matched rules, computed style and the label function
+ * @returns Why
+ */
+function whyOf(property, resolution, input) {
+    const winner = resolution?.winner;
+    const chain = [
+        ...(winner
+            ? [whyEntry(winner, winner.ancestor !== undefined ? 'inherited' : 'applied', input)]
+            : []),
+        ...(resolution?.overridden ?? []).map((d) => whyEntry(d, 'overridden', input)),
+    ];
+    const variables = winner ? variableSources(winner, input) : [];
+    return {
+        property,
+        computed: normalizeProperty(property, input.style[property] ?? ''),
+        chain,
+        ...(variables.length > 0 && { variables }),
+    };
+}
+/**
+ * One declaration in a `--why` chain: a shorthand's as written, `var()`
+ * substituted (or the custom properties that are not set), with the
+ * selector's specificity.
+ *
+ * @param declaration - Declaration
+ * @param status - Applied, overridden or inherited
+ * @param input - Computed style and the label function
+ * @returns Entry
+ */
+function whyEntry(declaration, status, input) {
+    const value = declaration.via ? (declaration.written ?? declaration.value) : declaration.value;
+    const unset = value.includes('var(') ? unsetVariables(value, input.style) : [];
+    const resolved = value.includes('var(') ? resolvedValue(declaration, value, input) : value;
+    const { specificity, layer, condition } = declaration.source;
+    return {
+        value,
+        ...(declaration.via && { via: declaration.via }),
+        ...(unset.length > 0 ? { unset } : resolved !== value && { resolved }),
+        source: input.label(declaration),
+        ...(specificity && { specificity }),
+        status,
+        ...(declaration.important && { important: true }),
+        ...(layer && { layer }),
+        ...(condition && { condition }),
+    };
+}
+/** How many levels of custom properties set from others are followed */
+const MAX_VARIABLE_DEPTH = 5;
+/**
+ * Where the custom properties the winning value uses are set, and those
+ * their values use in turn (`--bs-btn-border-width: var(--bs-border-width)`).
+ *
+ * @param winner - Winning declaration
+ * @param input - Matched rules, computed style and the label function
+ * @returns The variables with a declaration (on the element or an ancestor)
+ */
+function variableSources(winner, input) {
+    const found = [];
+    let names = usedVariables(winner.written ?? winner.value, input.style);
+    for (let depth = 0; names.length > 0 && depth < MAX_VARIABLE_DEPTH; depth++) {
+        const cascade = resolveCascade(input.matched, names);
+        const next = names.flatMap((name) => {
+            const declaration = cascade.get(name)?.winner;
+            if (!declaration || found.some((variable) => variable.name === name))
+                return [];
+            found.push({
+                name,
+                value: declaration.value,
+                source: input.label(declaration),
+                ...(declaration.ancestor !== undefined && { inherited: declaration.ancestor }),
+            });
+            return usedVariables(declaration.value, input.style);
+        });
+        names = [...new Set(next)];
+    }
+    return found;
+}
+/**
+ * A `var()` value substituted; a color longhand's in hex (Tailwind's
+ * `lab()` and `oklch()` tokens are unreadable).
+ *
+ * @param declaration - Declaration
+ * @param value - Its value as shown
+ * @param input - Computed style
+ * @returns Substituted value
+ */
+function resolvedValue(declaration, value, input) {
+    const substituted = substituteVariables(value, input.style);
+    const isColor = declaration.via === undefined && declaration.property.endsWith('color');
+    return isColor && !substituted.includes('var(')
+        ? normalizeProperty(declaration.property, substituted)
+        : substituted;
+}
+//# sourceMappingURL=inspectWhyModel.js.map

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

@@ -0,0 +1,71 @@
+/**
+ * Positions, sizes and visibility of elements (`bdg dom layout`).
+ *
+ * One page-side pass per command measures every match: its box in page and
+ * viewport coordinates (iframe offsets included), what clips it, whether it
+ * is rendered, what covers its center and the styles that decide how it
+ * shows. The measurements are classified outside the page
+ * ({@link classifyViewportPosition}).
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { DomLayoutCommand } from '../../ipc/protocol/commands.js';
+import type { LayoutComputedStyle, LayoutResult, PageLayout } from '../../ipc/protocol/domTypes.js';
+import { type ElementGeometry } from './elementGeometry.js';
+/** Matches measured per command (the rest are counted as omitted) */
+export declare const LAYOUT_ELEMENT_LIMIT = 100;
+/**
+ * Page-side end of a visible span kept clear of an overlay scrollbar along
+ * an edge (16 CSS px wide): overlay scrollbars (macOS, mobile) show for about a
+ * second after a scroll and catch hit tests, which then return the scroller.
+ * The span ends before the strip when it reaches into it and also shows
+ * outside it; without overlay scrollbars along the edge it is unchanged.
+ * Arguments: span start and end, the edge, whether overlay scrollbars show there.
+ */
+export declare const CLEAR_OF_SCROLLBAR_JS = "(start, end, edge, overlay) =>\n  overlay && end > edge - 16 && edge - 16 > start ? edge - 16 : end";
+/** One element as {@link LAYOUT_JS} measures it. */
+export interface RawElementLayout {
+    index: number;
+    tag: string;
+    element: string;
+    text: string;
+    context: string;
+    geometry: ElementGeometry;
+    /** The element on top at its visible center, and whether it paints nothing there */
+    cover: {
+        element: string;
+        transparent: boolean;
+    } | null;
+    computed: LayoutComputedStyle;
+}
+/** What {@link LAYOUT_JS} returns. */
+export interface RawLayout {
+    /** Elements the selector matched */
+    count: number;
+    /** Set when at least one element was measured */
+    page?: PageLayout;
+    elements: RawElementLayout[];
+    /** Measured inside a cross-origin iframe: `page` and the coordinates are that frame's */
+    crossOriginFrame?: boolean;
+}
+/**
+ * Measure the elements a selector (or cached index) refers to.
+ *
+ * @param cdp - CDP connection
+ * @param params - Selector (and index) or backend node id
+ * @returns Layout report
+ * @throws CommandError (83) no match, (81) index out of range or invalid
+ *   selector, (87) the cached element left the page
+ */
+export declare function inspectLayout(cdp: CDPConnection, params: DomLayoutCommand): Promise<LayoutResult>;
+/**
+ * Turn page-side measurements into the layout report: rounded page and
+ * viewport coordinates, viewport position and text preview per element.
+ *
+ * @param raw - Measurements with at least one element
+ * @param params - Request (selector and index)
+ * @returns Layout report
+ */
+export declare function buildLayoutResult(raw: RawLayout & {
+    page: PageLayout;
+}, params: Pick<DomLayoutCommand, 'selector' | 'index'>): LayoutResult;
+//# sourceMappingURL=layout.d.ts.map