@michaelmagan/dnumb 0.1.0

package/dist/analysis/layout-tree.js

@@ -0,0 +1,242 @@
+/**
+ * `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';
+}
+export 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/region-query.cjs

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodesAtPoint = nodesAtPoint;
+exports.nodesInRegion = nodesInRegion;
+/**
+ * Point/region lookup over an already-built layout tree — the geometric
+ * half of `query`'s `at`/`within` verbs (Step 17). Pure, tree-shaped, no
+ * `ElementRecord`, same boundary rules as the rest of `src/analysis/`. This
+ * is the shared helper both verbs dispatch through in `query.ts`, so a point
+ * query and a region query use the exact same rect-arithmetic and traversal
+ * rather than two hand-rolled walks that could quietly diverge.
+ *
+ * Both functions identify nodes by rect, not by `selector` — the join key
+ * `digest/render.ts#findBySelector` is stuck with and the one Step 16 found
+ * is not globally unique on real pages (duplicate `nth-of-type` selectors
+ * under a repeated table structure). A point or region is geometry from the
+ * start, so there is no selector-collision risk here at all.
+ */
+const geometry_js_1 = require("./geometry.cjs");
+/** Flattens the tree into every node at every depth, root-first, parent
+ * before children — same shape `distances.ts#flattenWithLineage` builds,
+ * reimplemented here since this module only needs the flat node list, not
+ * lineage. */
+function flatten(tree) {
+    const out = [];
+    function visit(node) {
+        out.push(node);
+        for (const child of node.children)
+            visit(child);
+    }
+    for (const root of tree)
+        visit(root);
+    return out;
+}
+/** True if the point `(x, y)` falls within `rect`, edges inclusive (a point
+ * exactly on a border counts as contained — the same "touching counts"
+ * convention `geometry.ts#contains` uses for rect-in-rect). */
+function containsPoint(rect, x, y) {
+    return x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
+}
+/**
+ * Every `LayoutNode` (at any depth) whose rect contains the point `(x, y)`,
+ * sorted most-specific first (ascending area — the smallest containing rect,
+ * typically a leaf, comes before its containers, all the way out to a page
+ * root). Empty array if the point is outside every node, including the page
+ * roots. Callers wanting a shorter "leaf plus a bit of context" list should
+ * slice the result themselves — this returns every ancestor rank, uncapped.
+ */
+function nodesAtPoint(tree, x, y) {
+    return flatten(tree)
+        .filter((node) => containsPoint(node.rect, x, y))
+        .sort((a, b) => (0, geometry_js_1.area)(a.rect) - (0, geometry_js_1.area)(b.rect));
+}
+/**
+ * Every `LayoutNode` (at any depth) whose rect intersects `region` —
+ * partial overlap counts, not just full containment (a region query is
+ * meant to catch things partially inside it too; see
+ * `geometry.ts#intersect`, which is the same primitive `overlap`/`query
+ * overlap` already use). Sorted by intersection area descending
+ * (most-overlapping first). Empty array if nothing overlaps.
+ */
+function nodesInRegion(tree, region) {
+    const matches = [];
+    for (const node of flatten(tree)) {
+        const overlap = (0, geometry_js_1.intersect)(node.rect, region);
+        if (overlap)
+            matches.push({ node, intersectionArea: (0, geometry_js_1.area)(overlap) });
+    }
+    matches.sort((a, b) => b.intersectionArea - a.intersectionArea);
+    return matches;
+}

package/dist/analysis/region-query.d.cts

@@ -0,0 +1,25 @@
+import type { LayoutNode, Rect } from "./types.cjs";
+/**
+ * Every `LayoutNode` (at any depth) whose rect contains the point `(x, y)`,
+ * sorted most-specific first (ascending area — the smallest containing rect,
+ * typically a leaf, comes before its containers, all the way out to a page
+ * root). Empty array if the point is outside every node, including the page
+ * roots. Callers wanting a shorter "leaf plus a bit of context" list should
+ * slice the result themselves — this returns every ancestor rank, uncapped.
+ */
+export declare function nodesAtPoint(tree: LayoutNode[], x: number, y: number): LayoutNode[];
+export interface RegionMatch {
+    node: LayoutNode;
+    /** Area (px²) of the overlap between `node.rect` and the queried region —
+     * what the result is sorted by (descending, most-overlapping first). */
+    intersectionArea: number;
+}
+/**
+ * Every `LayoutNode` (at any depth) whose rect intersects `region` —
+ * partial overlap counts, not just full containment (a region query is
+ * meant to catch things partially inside it too; see
+ * `geometry.ts#intersect`, which is the same primitive `overlap`/`query
+ * overlap` already use). Sorted by intersection area descending
+ * (most-overlapping first). Empty array if nothing overlaps.
+ */
+export declare function nodesInRegion(tree: LayoutNode[], region: Rect): RegionMatch[];

package/dist/analysis/region-query.d.ts

@@ -0,0 +1,25 @@
+import type { LayoutNode, Rect } from "./types.js";
+/**
+ * Every `LayoutNode` (at any depth) whose rect contains the point `(x, y)`,
+ * sorted most-specific first (ascending area — the smallest containing rect,
+ * typically a leaf, comes before its containers, all the way out to a page
+ * root). Empty array if the point is outside every node, including the page
+ * roots. Callers wanting a shorter "leaf plus a bit of context" list should
+ * slice the result themselves — this returns every ancestor rank, uncapped.
+ */
+export declare function nodesAtPoint(tree: LayoutNode[], x: number, y: number): LayoutNode[];
+export interface RegionMatch {
+    node: LayoutNode;
+    /** Area (px²) of the overlap between `node.rect` and the queried region —
+     * what the result is sorted by (descending, most-overlapping first). */
+    intersectionArea: number;
+}
+/**
+ * Every `LayoutNode` (at any depth) whose rect intersects `region` —
+ * partial overlap counts, not just full containment (a region query is
+ * meant to catch things partially inside it too; see
+ * `geometry.ts#intersect`, which is the same primitive `overlap`/`query
+ * overlap` already use). Sorted by intersection area descending
+ * (most-overlapping first). Empty array if nothing overlaps.
+ */
+export declare function nodesInRegion(tree: LayoutNode[], region: Rect): RegionMatch[];

package/dist/analysis/region-query.js

@@ -0,0 +1,67 @@
+/**
+ * Point/region lookup over an already-built layout tree — the geometric
+ * half of `query`'s `at`/`within` verbs (Step 17). Pure, tree-shaped, no
+ * `ElementRecord`, same boundary rules as the rest of `src/analysis/`. This
+ * is the shared helper both verbs dispatch through in `query.ts`, so a point
+ * query and a region query use the exact same rect-arithmetic and traversal
+ * rather than two hand-rolled walks that could quietly diverge.
+ *
+ * Both functions identify nodes by rect, not by `selector` — the join key
+ * `digest/render.ts#findBySelector` is stuck with and the one Step 16 found
+ * is not globally unique on real pages (duplicate `nth-of-type` selectors
+ * under a repeated table structure). A point or region is geometry from the
+ * start, so there is no selector-collision risk here at all.
+ */
+import { area, intersect } from "./geometry.js";
+/** Flattens the tree into every node at every depth, root-first, parent
+ * before children — same shape `distances.ts#flattenWithLineage` builds,
+ * reimplemented here since this module only needs the flat node list, not
+ * lineage. */
+function flatten(tree) {
+    const out = [];
+    function visit(node) {
+        out.push(node);
+        for (const child of node.children)
+            visit(child);
+    }
+    for (const root of tree)
+        visit(root);
+    return out;
+}
+/** True if the point `(x, y)` falls within `rect`, edges inclusive (a point
+ * exactly on a border counts as contained — the same "touching counts"
+ * convention `geometry.ts#contains` uses for rect-in-rect). */
+function containsPoint(rect, x, y) {
+    return x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
+}
+/**
+ * Every `LayoutNode` (at any depth) whose rect contains the point `(x, y)`,
+ * sorted most-specific first (ascending area — the smallest containing rect,
+ * typically a leaf, comes before its containers, all the way out to a page
+ * root). Empty array if the point is outside every node, including the page
+ * roots. Callers wanting a shorter "leaf plus a bit of context" list should
+ * slice the result themselves — this returns every ancestor rank, uncapped.
+ */
+export function nodesAtPoint(tree, x, y) {
+    return flatten(tree)
+        .filter((node) => containsPoint(node.rect, x, y))
+        .sort((a, b) => area(a.rect) - area(b.rect));
+}
+/**
+ * Every `LayoutNode` (at any depth) whose rect intersects `region` —
+ * partial overlap counts, not just full containment (a region query is
+ * meant to catch things partially inside it too; see
+ * `geometry.ts#intersect`, which is the same primitive `overlap`/`query
+ * overlap` already use). Sorted by intersection area descending
+ * (most-overlapping first). Empty array if nothing overlaps.
+ */
+export function nodesInRegion(tree, region) {
+    const matches = [];
+    for (const node of flatten(tree)) {
+        const overlap = intersect(node.rect, region);
+        if (overlap)
+            matches.push({ node, intersectionArea: area(overlap) });
+    }
+    matches.sort((a, b) => b.intersectionArea - a.intersectionArea);
+    return matches;
+}

package/dist/analysis/types.cjs

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Geometry primitives. Deliberately structural and tree-unaware: every
+ * function in `geometry.ts` takes plain rects, so the collector, the digest,
+ * and the diff all share one arithmetic implementation rather than three.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/analysis/types.d.cts

@@ -0,0 +1,143 @@
+/**
+ * Geometry primitives. Deliberately structural and tree-unaware: every
+ * function in `geometry.ts` takes plain rects, so the collector, the digest,
+ * and the diff all share one arithmetic implementation rather than three.
+ */
+/** A CSS-pixel rectangle in viewport coordinates. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The four sides of a box property (`margin`, `padding`, `border`). */
+export interface BoxSides {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export type Flow = 'row' | 'column' | 'grid' | 'none';
+export type LayoutNodeKind = 'leaf' | 'container';
+/**
+ * One node in the layout tree `buildLayoutTree` produces. `elementId`/`tag`/`rect`
+ * identify the *representative* underlying element — for a
+ * folded wrapper chain (see `wrapped`) that's the innermost element, since
+ * it carries the meaningful content (text, replaced-element type, or a
+ * distinct border/background); the outer wrapper's box is what proved the
+ * fold was safe (its content box matched), but it has nothing worth
+ * reporting on its own once absorbed.
+ */
+export interface LayoutNode {
+    elementId: string;
+    tag: string;
+    kind: LayoutNodeKind;
+    flow: Flow;
+    /** Computed CSS `position` of the representative element (`static`,
+     * `relative`, `absolute`, `fixed`, `sticky`) — carried through from
+     * `ElementRecord.position` so `Analysis`-level geometry (`overlaps`,
+     * `proximities`) can exclude `fixed`/`sticky` chrome the same way
+     * `checks/overflow.ts#UNCONTAINED_POSITIONS` already does at the
+     * `ElementRecord` level. */
+    position: string;
+    /** Count of wrapper levels folded into this node (0 if none). */
+    wrapped: number;
+    rect: Rect;
+    children: LayoutNode[];
+}
+export interface LayoutTreeDropped {
+    svgInternal: number;
+    invisible: number;
+    wrappers: number;
+}
+export interface LayoutTreeResult {
+    tree: LayoutNode[];
+    dropped: LayoutTreeDropped;
+}
+export interface SiblingGapPair {
+    a: string;
+    b: string;
+    gap: number;
+}
+export interface SiblingGapGroup {
+    containerId: string;
+    axis: 'x' | 'y';
+    pairs: SiblingGapPair[];
+}
+/**
+ * `SiblingGapGroup` plus base-unit detection over the group's own gap
+ * values (`pairs[].gap`) — `null` unit means no candidate explained enough
+ * of the gaps (see `cluster.ts#detectBaseUnit`). This is what `Analysis.gaps`
+ * actually holds: extending `SiblingGapGroup` rather than a parallel array
+ * keyed by `containerId`, since every consumer that already has a gap group
+ * (the digest renderer, the future spacing check) needs the group's own
+ * spacing stats in the same place it reads `pairs`, and a parallel array
+ * would just be a second lookup by the same key for no benefit — see
+ * LOG.md step 9. `siblingGaps()` in `neighbors.ts` itself still returns the
+ * plain `SiblingGapGroup` (it has no candidates/tolerance to detect a base
+ * unit with); `analyze()` is what adds these fields on top.
+ */
+export interface SpacingGapGroup extends SiblingGapGroup {
+    baseUnit: number | null;
+    onGridShare: number;
+    offGrid: number[];
+    distinct: Record<string, number>;
+}
+export interface OverlapPair {
+    a: string;
+    b: string;
+    area: number;
+    rect: Rect;
+}
+export interface ProximityPair {
+    a: string;
+    b: string;
+    edge: number;
+    dx: number;
+    dy: number;
+}
+export interface EdgeClusterSet {
+    left: Array<{
+        value: number;
+        count: number;
+        members: number[];
+    }>;
+    right: Array<{
+        value: number;
+        count: number;
+        members: number[];
+    }>;
+    top: Array<{
+        value: number;
+        count: number;
+        members: number[];
+    }>;
+}
+export interface NearMiss {
+    id: string;
+    axis: 'left' | 'right' | 'top';
+    actual: number;
+    nearestClusterValue: number;
+    delta: number;
+    /** Count of `nearestClusterValue`'s members that are container-scoped to
+     * this node — nearest common ancestor no more than `index.ts`'s
+     * `MAX_ANCESTOR_DISTANCE` combined steps away — not the cluster's raw
+     * page-wide `count` in `Analysis.edges`. `checkAlignment`'s
+     * `minClusterSize` gate reads this field instead of looking up
+     * `Analysis.edges`, so an unrelated page-wide cluster (large `count`,
+     * but zero members actually related to this node) can't pass the gate
+     * on size alone. See LOG.md Step 11b. */
+    scopedMemberCount: number;
+}
+export interface UniformityDeviant {
+    id: string;
+    reason: string;
+}
+export interface SiblingUniformityGroup {
+    containerId: string;
+    children: number;
+    medianWidth: number;
+    medianHeight: number;
+    medianGap: number;
+    deviants: UniformityDeviant[];
+}