@michaelmagan/dnumb 0.1.0

package/dist/analysis/geometry.d.cts

@@ -0,0 +1,34 @@
+/**
+ * Pure two-rect primitives — no tree awareness, no `ElementRecord`. Every
+ * function here takes plain `Rect`s so the collector, the digest, and the
+ * state diff can all share the exact same arithmetic.
+ *
+ * Ported unchanged from the prototype (`packages/layout-audit/src/analysis/
+ * geometry.ts`), where it was the best-tested pure module in the package.
+ */
+import type { Rect } from "./types.cjs";
+/**
+ * The overlapping rectangle between `a` and `b`, or `null` if they don't
+ * overlap on both axes. Touching edges count as no overlap — the intersection
+ * would have zero area, and a zero-area rect is not a thing anything on screen
+ * can be inside of.
+ */
+export declare function intersect(a: Rect, b: Rect): Rect | null;
+/** True if `inner` is fully within `outer`. Edges touching counts as contained. */
+export declare function contains(outer: Rect, inner: Rect): boolean;
+/**
+ * Signed edge-to-edge distance between `a` and `b` along one axis — positive is
+ * a real gap, negative is how far the two rects overlap along that axis.
+ *
+ * Unlike `intersect`, this is per-axis: two rects side by side in a row overlap
+ * on `y` and have a positive gap on `x`, which is exactly the question a gutter
+ * measurement asks.
+ */
+export declare function gapAlong(a: Rect, b: Rect, axis: 'x' | 'y'): number;
+/** Rect area in px². */
+export declare function area(r: Rect): number;
+/** Rect center point. */
+export declare function center(r: Rect): {
+    x: number;
+    y: number;
+};

package/dist/analysis/geometry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure two-rect primitives — no tree awareness, no `ElementRecord`. Every
+ * function here takes plain `Rect`s so the collector, the digest, and the
+ * state diff can all share the exact same arithmetic.
+ *
+ * Ported unchanged from the prototype (`packages/layout-audit/src/analysis/
+ * geometry.ts`), where it was the best-tested pure module in the package.
+ */
+import type { Rect } from "./types.js";
+/**
+ * The overlapping rectangle between `a` and `b`, or `null` if they don't
+ * overlap on both axes. Touching edges count as no overlap — the intersection
+ * would have zero area, and a zero-area rect is not a thing anything on screen
+ * can be inside of.
+ */
+export declare function intersect(a: Rect, b: Rect): Rect | null;
+/** True if `inner` is fully within `outer`. Edges touching counts as contained. */
+export declare function contains(outer: Rect, inner: Rect): boolean;
+/**
+ * Signed edge-to-edge distance between `a` and `b` along one axis — positive is
+ * a real gap, negative is how far the two rects overlap along that axis.
+ *
+ * Unlike `intersect`, this is per-axis: two rects side by side in a row overlap
+ * on `y` and have a positive gap on `x`, which is exactly the question a gutter
+ * measurement asks.
+ */
+export declare function gapAlong(a: Rect, b: Rect, axis: 'x' | 'y'): number;
+/** Rect area in px². */
+export declare function area(r: Rect): number;
+/** Rect center point. */
+export declare function center(r: Rect): {
+    x: number;
+    y: number;
+};

package/dist/analysis/geometry.js

@@ -0,0 +1,53 @@
+/**
+ * The overlapping rectangle between `a` and `b`, or `null` if they don't
+ * overlap on both axes. Touching edges count as no overlap — the intersection
+ * would have zero area, and a zero-area rect is not a thing anything on screen
+ * can be inside of.
+ */
+export function intersect(a, b) {
+    const x = Math.max(a.x, b.x);
+    const y = Math.max(a.y, b.y);
+    const right = Math.min(a.x + a.width, b.x + b.width);
+    const bottom = Math.min(a.y + a.height, b.y + b.height);
+    const width = right - x;
+    const height = bottom - y;
+    if (width <= 0 || height <= 0)
+        return null;
+    return { x, y, width, height };
+}
+/** True if `inner` is fully within `outer`. Edges touching counts as contained. */
+export function contains(outer, inner) {
+    return (inner.x >= outer.x &&
+        inner.y >= outer.y &&
+        inner.x + inner.width <= outer.x + outer.width &&
+        inner.y + inner.height <= outer.y + outer.height);
+}
+/**
+ * Signed edge-to-edge distance between `a` and `b` along one axis — positive is
+ * a real gap, negative is how far the two rects overlap along that axis.
+ *
+ * Unlike `intersect`, this is per-axis: two rects side by side in a row overlap
+ * on `y` and have a positive gap on `x`, which is exactly the question a gutter
+ * measurement asks.
+ */
+export function gapAlong(a, b, axis) {
+    const size = axis === 'x' ? 'width' : 'height';
+    const aStart = a[axis];
+    const aEnd = aStart + a[size];
+    const bStart = b[axis];
+    const bEnd = bStart + b[size];
+    if (bStart >= aEnd)
+        return bStart - aEnd;
+    if (aStart >= bEnd)
+        return aStart - bEnd;
+    // Overlapping along this axis: negative distance, magnitude of the overlap.
+    return Math.max(aStart, bStart) - Math.min(aEnd, bEnd);
+}
+/** Rect area in px². */
+export function area(r) {
+    return r.width * r.height;
+}
+/** Rect center point. */
+export function center(r) {
+    return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+}

package/dist/analysis/layout-tree.cjs

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLayoutTree = buildLayoutTree;
+/**
+ * `ElementRecord.tag` is always `el.tagName.toLowerCase()` (see
+ * `snapshot/collect.ts`) — HTML and SVG tags are stored in the same case,
+ * so there is no "starts lowercase" signal left in the data to check by the
+ * time it reaches this module (the step-6 fix already drops the `<svg>`
+ * subtree, root included, at collection time). This set is the practical
+ * replacement: a fixed list of SVG-only tag names, kept as a defensive net
+ * in case `collectSnapshot`'s `SKIPPED_TAGS` ever changes to stop dropping
+ * the `<svg>` root itself. `svg` is deliberately absent — the root svg
+ * element is a leaf "icon" box per the classification pass below, not
+ * dropped.
+ */
+const SVG_INTERNAL_TAGS = new Set([
+    'g',
+    'path',
+    'rect',
+    'circle',
+    'ellipse',
+    'line',
+    'polyline',
+    'polygon',
+    'defs',
+    'clippath',
+    'lineargradient',
+    'radialgradient',
+    'stop',
+    'use',
+    'symbol',
+    'mask',
+    'pattern',
+    'text',
+    'tspan',
+    'foreignobject',
+]);
+const REPLACED_TAGS = new Set(['img', 'input', 'textarea', 'select', 'button']);
+/** ~1px tolerance for the "rect equals parent's content box" collapse
+ * check — real layouts carry subpixel rounding. */
+const COLLAPSE_TOLERANCE = 1;
+function contentBox(el) {
+    return {
+        x: el.rect.x + el.padding.left + el.border.left,
+        y: el.rect.y + el.padding.top + el.border.top,
+        width: el.rect.width - el.padding.left - el.padding.right - el.border.left - el.border.right,
+        height: el.rect.height - el.padding.top - el.padding.bottom - el.border.top - el.border.bottom,
+    };
+}
+function rectsMatch(a, b, tolerance = COLLAPSE_TOLERANCE) {
+    return (Math.abs(a.x - b.x) <= tolerance &&
+        Math.abs(a.y - b.y) <= tolerance &&
+        Math.abs(a.width - b.width) <= tolerance &&
+        Math.abs(a.height - b.height) <= tolerance);
+}
+function hasVisibleBorder(el) {
+    return el.border.top > 0 || el.border.right > 0 || el.border.bottom > 0 || el.border.left > 0;
+}
+function sameBorder(a, b) {
+    return (a.border.top === b.border.top &&
+        a.border.right === b.border.right &&
+        a.border.bottom === b.border.bottom &&
+        a.border.left === b.border.left);
+}
+/** `rgba(r, g, b, 0)` / `transparent` are the only two forms
+ * `getComputedStyle` returns for "no background" — anything else paints
+ * something, even a translucent color. */
+function hasVisibleBackground(el) {
+    const bg = el.backgroundColor.trim();
+    if (bg === '' || bg === 'transparent')
+        return false;
+    const alphaMatch = /rgba?\([^)]*,\s*([\d.]+)\s*\)/.exec(bg);
+    if (alphaMatch?.[1] !== undefined && Number.parseFloat(alphaMatch[1]) === 0)
+        return false;
+    return true;
+}
+/**
+ * Leaf if: has non-empty own text, is a replaced element or an SVG root, or
+ * carries a visible border/background distinct from its parent's (a
+ * decorated box like a card or a chip is treated as one atomic layout unit
+ * — its internal structure isn't relevant to gap/overlap/uniformity
+ * analysis at the level above it). `parent` is `null` only at a document
+ * root, where "distinct from parent" degrades to "has one at all".
+ */
+function isLeaf(el, parent) {
+    if (el.text.trim().length > 0)
+        return true;
+    if (REPLACED_TAGS.has(el.tag))
+        return true;
+    if (el.tag === 'svg')
+        return true;
+    const ownBorder = hasVisibleBorder(el);
+    const ownBackground = hasVisibleBackground(el);
+    if (!parent)
+        return ownBorder || ownBackground;
+    if (ownBorder && !sameBorder(el, parent))
+        return true;
+    if (ownBackground && el.backgroundColor !== parent.backgroundColor)
+        return true;
+    return false;
+}
+/**
+ * Every flex container reported `row` until this took `flex-direction` into
+ * account, and `column` -- a value the grammar, the parser and the `Flow` type
+ * all carried -- was unreachable.
+ *
+ * It was not only a mislabelled token. The digest measures a child's gap along
+ * its parent's flow axis, so every `flex-direction: column` container had its
+ * children measured *horizontally*: a stack of full-width rows reported `→0`
+ * between each pair instead of the vertical gap that is actually there.
+ */
+function flowFromDisplay(display, flexDirection) {
+    if (display.includes('grid'))
+        return 'grid';
+    if (display.includes('flex')) {
+        return flexDirection.startsWith('column') ? 'column' : 'row';
+    }
+    return 'none';
+}
+function buildLayoutTree(elements, options = {}) {
+    const byId = new Map(elements.map((el) => [el.id, el]));
+    const keepIds = options.keepIds;
+    let svgInternal = 0;
+    let invisible = 0;
+    let wrappersFolded = 0;
+    function keep(el) {
+        // `keepIds` has to be the first check, not the second: an SVG `<path>`
+        // (or any other tag in `SVG_INTERNAL_TAGS`) that `factsFor` found
+        // something to say about -- most commonly `clipped`, on an icon
+        // partially hidden by an ancestor's `overflow` -- used to be dropped
+        // here before this function ever looked at `keepIds`, because the
+        // SVG-internal check ran first and returned unconditionally. Checking
+        // `keepIds` first makes the override total, the same way the doc
+        // comment on `BuildLayoutTreeOptions.keepIds` already promises ("the
+        // digest passes every element carrying a fact") rather than true only
+        // for the one reason (`!el.visible`) that happened to be checked after
+        // it.
+        if (keepIds?.has(el.id))
+            return true;
+        if (SVG_INTERNAL_TAGS.has(el.tag)) {
+            svgInternal++;
+            return false;
+        }
+        if (!el.visible) {
+            invisible++;
+            return false;
+        }
+        return true;
+    }
+    // Pass 1: filter + reparent. A dropped element's surviving children are
+    // spliced up to its nearest surviving ancestor's child list — dropping a
+    // node never deletes a subtree, only the one uninformative box.
+    function buildChildren(childIds) {
+        const result = [];
+        for (const id of childIds) {
+            const el = byId.get(id);
+            if (!el)
+                continue;
+            if (keep(el)) {
+                result.push({ el, children: buildChildren(el.childIds) });
+            }
+            else {
+                result.push(...buildChildren(el.childIds));
+            }
+        }
+        return result;
+    }
+    // Pass 2 (collapse) + pass 3 (classify), combined per node bottom-up: a
+    // node's children must already be finalized before we can test whether
+    // this node has exactly one surviving child whose rect matches this
+    // node's own content box.
+    function build(raw, parent) {
+        let children = raw.children.map((child) => build(child, raw.el));
+        let wrapped = 0;
+        // The representative element for identity/classification purposes —
+        // starts as this node's own element, and becomes the innermost folded
+        // child's element as wrapper levels collapse into it. The box test
+        // itself always uses `raw.el`'s own content box (fixed for this node
+        // regardless of how many levels have folded in) — that's the box every
+        // absorbed child proved it matched.
+        let inner = raw.el;
+        const box = contentBox(raw.el);
+        while (children.length === 1) {
+            // A wrapper that itself carries a fact (`keepIds` -- the same set pass
+            // 1's `keep()` checks above, threaded in from `renderDigest` as every
+            // id `factsFor` found something to say about) must not have its
+            // identity silently swapped out for its child's here. Before this
+            // check, `inner`'s reassignment below was unconditional: the wrapper's
+            // own id -- and with it, the only thing that could carry a fact
+            // computed for the wrapper itself, most commonly `<body>`'s own
+            // `overflow-y` when `<body>` has exactly one child filling it -- simply
+            // stopped being reachable from any `LayoutNode` in the tree, with no
+            // line anywhere disclosing that it happened. `keepIds` already exists
+            // for exactly this guarantee ("the digest passes every element
+            // carrying a fact") but was only ever consulted by pass 1's filter;
+            // this is the same guarantee at the one other point in the pipeline
+            // that can erase an element's identity. Stopping the fold at this
+            // level -- rather than hoisting the fact onto the surviving child, or
+            // collapsing anyway with a disclosure -- keeps the fix inside this
+            // module and inside `keepIds`'s existing contract: the wrapper gets its
+            // own line, exactly the "direct" route every other fact-bearing
+            // element already uses, so no new disclosure format is needed and no
+            // fact ever needs re-attributing to an id that didn't measure it.
+            if (keepIds?.has(inner.id))
+                break;
+            const only = children[0];
+            if (only && rectsMatch(only.rect, box)) {
+                const onlyEl = byId.get(only.elementId);
+                if (!onlyEl)
+                    break;
+                wrapped += 1 + only.wrapped;
+                wrappersFolded += 1;
+                inner = onlyEl;
+                children = only.children;
+            }
+            else {
+                break;
+            }
+        }
+        // `kind` is classification metadata only — it does not prune `children`.
+        // A card with a background distinct from its parent is a `leaf` in the
+        // sense that a digest/query consumer can treat it as one atomic visual
+        // unit, but `overlaps`/`siblingGaps`/`siblingUniformity` still need its
+        // real children (e.g. an absolutely-positioned badge nested inside a
+        // colored card) to be present in the tree to find them.
+        const leaf = isLeaf(inner, parent);
+        return {
+            elementId: inner.id,
+            tag: inner.tag,
+            kind: leaf ? 'leaf' : 'container',
+            flow: flowFromDisplay(inner.display, inner.flexDirection),
+            position: inner.position,
+            wrapped,
+            rect: inner.rect,
+            children,
+        };
+    }
+    const rootIds = elements.filter((el) => el.parentId === null).map((el) => el.id);
+    const rawRoots = buildChildren(rootIds);
+    const tree = rawRoots.map((raw) => build(raw, null));
+    return {
+        tree,
+        dropped: { svgInternal, invisible, wrappers: wrappersFolded },
+    };
+}

package/dist/analysis/layout-tree.d.cts

@@ -0,0 +1,45 @@
+/**
+ * Builds a `LayoutNode` tree from a flat `ElementRecord[]` snapshot — the
+ * keystone module of `src/analysis/`: `neighbors.ts` and `uniformity.ts`
+ * both walk the tree this produces, and the future digest renderer renders
+ * it directly. Get this right; everything else depends on it.
+ *
+ * Three passes, each pure and independently reasoned about:
+ *  1. Filter + reparent — drop elements that aren't layout-meaningful
+ *     (SVG-internals, invisible, zero-size), splicing any surviving
+ *     children up to the nearest surviving ancestor so a dropped node never
+ *     silently deletes a whole subtree.
+ *  2. Collapse — fold a lone wrapper child into its parent when the child's
+ *     rect matches the parent's content box, tracked as `wrapped`, unless the
+ *     wrapper itself is in `keepIds` (it carries a fact of its own), in which
+ *     case it keeps its own line instead of being folded away.
+ *  3. Classify — decide `leaf` vs `container` per surviving node.
+ */
+import type { ElementRecord } from "../snapshot/types.cjs";
+import type { LayoutTreeResult } from "./types.cjs";
+export interface BuildLayoutTreeOptions {
+    /**
+     * Elements that must survive whatever their geometry says -- checked at
+     * both points in this file that can otherwise erase an element's identity:
+     * pass 1's filter (`keep()`, below) and pass 2's wrapper collapse (the
+     * `while (children.length === 1)` loop in `build()`).
+     *
+     * Pass 1 drops anything with no visible box, which is right for the
+     * hundreds of zero-size nodes on a real page and catastrophically wrong for
+     * the one that matters: a column that collapsed to `0x1239` *around a page of
+     * content* has no visible box either. Dropping it deletes the element the
+     * whole finding is about, which is the prototype's failure mode wearing a
+     * different hat -- the measurement exists and the rendering throws it away.
+     *
+     * Pass 2's wrapper collapse can do the same thing a different way: it
+     * doesn't drop the wrapper's `ElementRecord`, but it does replace the
+     * wrapper's identity with its single child's in the rendered tree, and a
+     * fact keyed to the wrapper's own id (most commonly `<body>`'s own
+     * `overflow-y`) has nowhere left to attach once no `LayoutNode` carries
+     * that id anymore.
+     *
+     * The digest passes every element carrying a fact.
+     */
+    keepIds?: ReadonlySet<string>;
+}
+export declare function buildLayoutTree(elements: ElementRecord[], options?: BuildLayoutTreeOptions): LayoutTreeResult;

package/dist/analysis/layout-tree.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Builds a `LayoutNode` tree from a flat `ElementRecord[]` snapshot — the
+ * keystone module of `src/analysis/`: `neighbors.ts` and `uniformity.ts`
+ * both walk the tree this produces, and the future digest renderer renders
+ * it directly. Get this right; everything else depends on it.
+ *
+ * Three passes, each pure and independently reasoned about:
+ *  1. Filter + reparent — drop elements that aren't layout-meaningful
+ *     (SVG-internals, invisible, zero-size), splicing any surviving
+ *     children up to the nearest surviving ancestor so a dropped node never
+ *     silently deletes a whole subtree.
+ *  2. Collapse — fold a lone wrapper child into its parent when the child's
+ *     rect matches the parent's content box, tracked as `wrapped`, unless the
+ *     wrapper itself is in `keepIds` (it carries a fact of its own), in which
+ *     case it keeps its own line instead of being folded away.
+ *  3. Classify — decide `leaf` vs `container` per surviving node.
+ */
+import type { ElementRecord } from "../snapshot/types.js";
+import type { LayoutTreeResult } from "./types.js";
+export interface BuildLayoutTreeOptions {
+    /**
+     * Elements that must survive whatever their geometry says -- checked at
+     * both points in this file that can otherwise erase an element's identity:
+     * pass 1's filter (`keep()`, below) and pass 2's wrapper collapse (the
+     * `while (children.length === 1)` loop in `build()`).
+     *
+     * Pass 1 drops anything with no visible box, which is right for the
+     * hundreds of zero-size nodes on a real page and catastrophically wrong for
+     * the one that matters: a column that collapsed to `0x1239` *around a page of
+     * content* has no visible box either. Dropping it deletes the element the
+     * whole finding is about, which is the prototype's failure mode wearing a
+     * different hat -- the measurement exists and the rendering throws it away.
+     *
+     * Pass 2's wrapper collapse can do the same thing a different way: it
+     * doesn't drop the wrapper's `ElementRecord`, but it does replace the
+     * wrapper's identity with its single child's in the rendered tree, and a
+     * fact keyed to the wrapper's own id (most commonly `<body>`'s own
+     * `overflow-y`) has nowhere left to attach once no `LayoutNode` carries
+     * that id anymore.
+     *
+     * The digest passes every element carrying a fact.
+     */
+    keepIds?: ReadonlySet<string>;
+}
+export declare function buildLayoutTree(elements: ElementRecord[], options?: BuildLayoutTreeOptions): LayoutTreeResult;