@michaelmagan/dnumb 0.1.0

package/dist/analysis/cluster.d.cts

@@ -0,0 +1,68 @@
+/**
+ * 1-D numeric clustering and spacing-grid detection — pure arithmetic over
+ * plain `number[]`, no `LayoutNode`/`ElementRecord` knowledge at all (the
+ * caller decides whether the numbers are x-coordinates, gaps, or anything
+ * else). Same boundary rules as the rest of `src/analysis/`: no imports
+ * beyond `../snapshot/types.js` and sibling `analysis/` modules — this file
+ * needs neither, so it has no imports.
+ */
+export interface EdgeCluster {
+    /** Representative value for the cluster: the mean of its members: cheap,
+     * stable under this module's adjacent-gap grouping (a cluster's members
+     * are already known to be within `tolerance` px of their neighbors, so
+     * the mean can never land more than `tolerance` px from any one member),
+     * and doesn't require picking a media convention for even-sized groups. */
+    value: number;
+    count: number;
+    /** Original indices into the input `values` array that belong to this
+     * cluster, in the order they were grouped (ascending by value, not
+     * necessarily the input order). */
+    members: number[];
+}
+/**
+ * Groups `values` into 1-D clusters using adjacent-gap chaining: sort
+ * ascending, then start a new cluster whenever the gap between two
+ * consecutive sorted values exceeds `tolerance`. This is deliberately
+ * "adjacent" rather than "each within `tolerance` of the cluster's running
+ * mean" — a run of values 2px apart (0, 2, 4, 6, 8) chains into one cluster
+ * under either rule, but the two rules diverge once a cluster's span grows
+ * past `tolerance`; adjacent-gap chaining is the simpler rule to reason
+ * about and to test, and matches "group any within tolerance px of each
+ * other" read as a chain of pairwise closeness rather than a fixed-radius
+ * ball around one center.
+ */
+export declare function clusterEdges(values: number[], tolerance?: number): Array<{
+    value: number;
+    count: number;
+    members: number[];
+}>;
+export interface BaseUnitResult {
+    unit: number | null;
+    onGridShare: number;
+    offGrid: number[];
+}
+/**
+ * Picks the candidate spacing unit (default `[4, 8]`) that best explains
+ * `gaps`: for each candidate, the fraction of non-zero gaps within 1px of a
+ * multiple of that unit. Zero-valued gaps are excluded from both the sample
+ * count and the coverage fraction — a touching pair (gap 0) is trivially "on
+ * every grid" and would inflate the score without saying anything about the
+ * page's actual spacing rhythm.
+ *
+ * Requires at least `MIN_GAP_SAMPLES` non-zero gaps and at least
+ * `MIN_ON_GRID_SHARE` coverage from the best candidate; otherwise returns
+ * `{unit: null, onGridShare: 0, offGrid: gaps}` (the *original*, unfiltered
+ * `gaps` — a caller with too little data to trust gets everything back as
+ * "off-grid" rather than a partially-filtered list) instead of a
+ * low-confidence guess. Ties are broken toward the smaller candidate — the
+ * candidates are tried in the order given and a later candidate only wins by
+ * strictly exceeding the current best share.
+ */
+export declare function detectBaseUnit(gaps: number[], candidates?: number[]): BaseUnitResult;
+export interface SpacingStats {
+    distinct: Record<string, number>;
+}
+/** Histogram of `gaps`, each value rounded to the nearest px before being
+ * used as the key — the digest and the (future) spacing check use this to
+ * summarize "column gaps: 24×4" rather than listing every raw float. */
+export declare function spacingStats(gaps: number[]): SpacingStats;

package/dist/analysis/cluster.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 1-D numeric clustering and spacing-grid detection — pure arithmetic over
+ * plain `number[]`, no `LayoutNode`/`ElementRecord` knowledge at all (the
+ * caller decides whether the numbers are x-coordinates, gaps, or anything
+ * else). Same boundary rules as the rest of `src/analysis/`: no imports
+ * beyond `../snapshot/types.js` and sibling `analysis/` modules — this file
+ * needs neither, so it has no imports.
+ */
+export interface EdgeCluster {
+    /** Representative value for the cluster: the mean of its members: cheap,
+     * stable under this module's adjacent-gap grouping (a cluster's members
+     * are already known to be within `tolerance` px of their neighbors, so
+     * the mean can never land more than `tolerance` px from any one member),
+     * and doesn't require picking a media convention for even-sized groups. */
+    value: number;
+    count: number;
+    /** Original indices into the input `values` array that belong to this
+     * cluster, in the order they were grouped (ascending by value, not
+     * necessarily the input order). */
+    members: number[];
+}
+/**
+ * Groups `values` into 1-D clusters using adjacent-gap chaining: sort
+ * ascending, then start a new cluster whenever the gap between two
+ * consecutive sorted values exceeds `tolerance`. This is deliberately
+ * "adjacent" rather than "each within `tolerance` of the cluster's running
+ * mean" — a run of values 2px apart (0, 2, 4, 6, 8) chains into one cluster
+ * under either rule, but the two rules diverge once a cluster's span grows
+ * past `tolerance`; adjacent-gap chaining is the simpler rule to reason
+ * about and to test, and matches "group any within tolerance px of each
+ * other" read as a chain of pairwise closeness rather than a fixed-radius
+ * ball around one center.
+ */
+export declare function clusterEdges(values: number[], tolerance?: number): Array<{
+    value: number;
+    count: number;
+    members: number[];
+}>;
+export interface BaseUnitResult {
+    unit: number | null;
+    onGridShare: number;
+    offGrid: number[];
+}
+/**
+ * Picks the candidate spacing unit (default `[4, 8]`) that best explains
+ * `gaps`: for each candidate, the fraction of non-zero gaps within 1px of a
+ * multiple of that unit. Zero-valued gaps are excluded from both the sample
+ * count and the coverage fraction — a touching pair (gap 0) is trivially "on
+ * every grid" and would inflate the score without saying anything about the
+ * page's actual spacing rhythm.
+ *
+ * Requires at least `MIN_GAP_SAMPLES` non-zero gaps and at least
+ * `MIN_ON_GRID_SHARE` coverage from the best candidate; otherwise returns
+ * `{unit: null, onGridShare: 0, offGrid: gaps}` (the *original*, unfiltered
+ * `gaps` — a caller with too little data to trust gets everything back as
+ * "off-grid" rather than a partially-filtered list) instead of a
+ * low-confidence guess. Ties are broken toward the smaller candidate — the
+ * candidates are tried in the order given and a later candidate only wins by
+ * strictly exceeding the current best share.
+ */
+export declare function detectBaseUnit(gaps: number[], candidates?: number[]): BaseUnitResult;
+export interface SpacingStats {
+    distinct: Record<string, number>;
+}
+/** Histogram of `gaps`, each value rounded to the nearest px before being
+ * used as the key — the digest and the (future) spacing check use this to
+ * summarize "column gaps: 24×4" rather than listing every raw float. */
+export declare function spacingStats(gaps: number[]): SpacingStats;

package/dist/analysis/cluster.js

@@ -0,0 +1,109 @@
+/**
+ * 1-D numeric clustering and spacing-grid detection — pure arithmetic over
+ * plain `number[]`, no `LayoutNode`/`ElementRecord` knowledge at all (the
+ * caller decides whether the numbers are x-coordinates, gaps, or anything
+ * else). Same boundary rules as the rest of `src/analysis/`: no imports
+ * beyond `../snapshot/types.js` and sibling `analysis/` modules — this file
+ * needs neither, so it has no imports.
+ */
+/**
+ * Groups `values` into 1-D clusters using adjacent-gap chaining: sort
+ * ascending, then start a new cluster whenever the gap between two
+ * consecutive sorted values exceeds `tolerance`. This is deliberately
+ * "adjacent" rather than "each within `tolerance` of the cluster's running
+ * mean" — a run of values 2px apart (0, 2, 4, 6, 8) chains into one cluster
+ * under either rule, but the two rules diverge once a cluster's span grows
+ * past `tolerance`; adjacent-gap chaining is the simpler rule to reason
+ * about and to test, and matches "group any within tolerance px of each
+ * other" read as a chain of pairwise closeness rather than a fixed-radius
+ * ball around one center.
+ */
+export function clusterEdges(values, tolerance = 2) {
+    if (values.length === 0)
+        return [];
+    const sorted = values.map((value, index) => ({ value, index })).sort((a, b) => a.value - b.value);
+    const clusters = [];
+    let current = [];
+    function flush() {
+        if (current.length === 0)
+            return;
+        const sum = current.reduce((total, entry) => total + entry.value, 0);
+        clusters.push({
+            value: sum / current.length,
+            count: current.length,
+            members: current.map((entry) => entry.index),
+        });
+        current = [];
+    }
+    for (const entry of sorted) {
+        const prev = current.at(-1);
+        if (prev !== undefined && entry.value - prev.value > tolerance)
+            flush();
+        current.push(entry);
+    }
+    flush();
+    return clusters;
+}
+const MIN_GAP_SAMPLES = 5;
+const MIN_ON_GRID_SHARE = 0.5;
+const GRID_TOLERANCE = 1;
+/**
+ * Picks the candidate spacing unit (default `[4, 8]`) that best explains
+ * `gaps`: for each candidate, the fraction of non-zero gaps within 1px of a
+ * multiple of that unit. Zero-valued gaps are excluded from both the sample
+ * count and the coverage fraction — a touching pair (gap 0) is trivially "on
+ * every grid" and would inflate the score without saying anything about the
+ * page's actual spacing rhythm.
+ *
+ * Requires at least `MIN_GAP_SAMPLES` non-zero gaps and at least
+ * `MIN_ON_GRID_SHARE` coverage from the best candidate; otherwise returns
+ * `{unit: null, onGridShare: 0, offGrid: gaps}` (the *original*, unfiltered
+ * `gaps` — a caller with too little data to trust gets everything back as
+ * "off-grid" rather than a partially-filtered list) instead of a
+ * low-confidence guess. Ties are broken toward the smaller candidate — the
+ * candidates are tried in the order given and a later candidate only wins by
+ * strictly exceeding the current best share.
+ */
+export function detectBaseUnit(gaps, candidates = [4, 8]) {
+    const nonZero = gaps.filter((gap) => gap !== 0);
+    if (nonZero.length < MIN_GAP_SAMPLES) {
+        return { unit: null, onGridShare: 0, offGrid: gaps };
+    }
+    let bestUnit = null;
+    let bestShare = 0;
+    let bestOffGrid = gaps;
+    for (const unit of candidates) {
+        if (unit <= 0)
+            continue;
+        const offGrid = [];
+        let onGrid = 0;
+        for (const gap of nonZero) {
+            const nearestMultiple = Math.round(gap / unit) * unit;
+            if (Math.abs(gap - nearestMultiple) <= GRID_TOLERANCE)
+                onGrid++;
+            else
+                offGrid.push(gap);
+        }
+        const share = onGrid / nonZero.length;
+        if (share > bestShare) {
+            bestShare = share;
+            bestUnit = unit;
+            bestOffGrid = offGrid;
+        }
+    }
+    if (bestUnit === null || bestShare < MIN_ON_GRID_SHARE) {
+        return { unit: null, onGridShare: 0, offGrid: gaps };
+    }
+    return { unit: bestUnit, onGridShare: bestShare, offGrid: bestOffGrid };
+}
+/** Histogram of `gaps`, each value rounded to the nearest px before being
+ * used as the key — the digest and the (future) spacing check use this to
+ * summarize "column gaps: 24×4" rather than listing every raw float. */
+export function spacingStats(gaps) {
+    const distinct = {};
+    for (const gap of gaps) {
+        const key = String(Math.round(gap));
+        distinct[key] = (distinct[key] ?? 0) + 1;
+    }
+    return { distinct };
+}

package/dist/analysis/distances.cjs

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.distance = distance;
+exports.nearest = nearest;
+exports.proximities = proximities;
+/**
+ * Geometric distance queries over a `LayoutNode[]` tree — the piece that
+ * lets an agent go from a digest's element ids to on-demand geometric
+ * answers (`query`'s `distance`/`nearest` verbs) instead of re-deriving
+ * arithmetic by hand from raw rects. Pure, tree-shaped, no `ElementRecord` —
+ * same boundary rules as the rest of `src/analysis/`.
+ */
+const geometry_js_1 = require("./geometry.cjs");
+/** Distance between two rects along every axis a query needs: signed
+ * per-axis gaps, the Euclidean closest-edge gap, and center-to-center. */
+function distance(a, b) {
+    const dx = (0, geometry_js_1.gapAlong)(a, b, 'x');
+    const dy = (0, geometry_js_1.gapAlong)(a, b, 'y');
+    const edge = Math.sqrt(Math.max(dx, 0) ** 2 + Math.max(dy, 0) ** 2);
+    const ca = (0, geometry_js_1.center)(a);
+    const cb = (0, geometry_js_1.center)(b);
+    const centerDistance = Math.sqrt((ca.x - cb.x) ** 2 + (ca.y - cb.y) ** 2);
+    return { dx, dy, edge, center: centerDistance };
+}
+/** Flattens the tree once, tracking each node's immediate parent id (for
+ * sibling exclusion in `proximities`) and full ancestor-id set (for
+ * ancestor/descendant exclusion in both `nearest` and `proximities`) — the
+ * same lineage-tracking shape `neighbors.ts#overlaps` uses internally,
+ * reimplemented here rather than imported since `neighbors.ts` doesn't
+ * export it and this module also needs `parentId`, which that shape
+ * doesn't carry. */
+function flattenWithLineage(tree) {
+    const entries = [];
+    function visit(node, parentId, ancestorIds) {
+        entries.push({ node, parentId, ancestorIds });
+        const withSelf = new Set(ancestorIds);
+        withSelf.add(node.elementId);
+        for (const child of node.children)
+            visit(child, node.elementId, withSelf);
+    }
+    for (const root of tree)
+        visit(root, null, new Set());
+    return entries;
+}
+function isAncestorPair(a, b) {
+    return a.ancestorIds.has(b.node.elementId) || b.ancestorIds.has(a.node.elementId);
+}
+function idCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** `fixed`/`sticky` elements are deliberately layered over other content
+ * (persistent chrome like Charming's floating feedback launcher) — mirrors
+ * `checks/overflow.ts#UNCONTAINED_POSITIONS` and
+ * `neighbors.ts#UNCONTAINED_POSITIONS`. A `fixed` element reads as "near"
+ * whatever page content sits under it at the moment of capture, which is an
+ * artifact of scroll position, not a real proximity relationship between
+ * two page elements — the same reasoning that excludes it from `overlaps`
+ * applies here. */
+const UNCONTAINED_POSITIONS = new Set(['fixed', 'sticky']);
+const DEFAULT_K = 4;
+/** The `k` layout nodes nearest `id` by edge distance (ascending, ties
+ * broken by id for determinism), excluding `id` itself and — by default —
+ * its ancestors and descendants. Returns `[]` if `id` isn't found. */
+function nearest(tree, id, k = DEFAULT_K, opts = {}) {
+    const excludeAncestors = opts.excludeAncestors ?? true;
+    const entries = flattenWithLineage(tree);
+    const target = entries.find((e) => e.node.elementId === id);
+    if (!target)
+        return [];
+    const results = [];
+    for (const entry of entries) {
+        if (entry.node.elementId === id)
+            continue;
+        if (excludeAncestors && isAncestorPair(target, entry))
+            continue;
+        const d = distance(target.node.rect, entry.node.rect);
+        results.push({ id: entry.node.elementId, edge: d.edge, dx: d.dx, dy: d.dy });
+    }
+    results.sort((x, y) => x.edge - y.edge || idCompare(x.id, y.id));
+    return results.slice(0, k);
+}
+const DEFAULT_MAX_EDGE = 4;
+/**
+ * Every pair of nodes that are NOT ancestor/descendant of each other AND
+ * NOT direct siblings (siblings are already covered by
+ * `neighbors.ts#siblingGaps` — this is specifically the cross-container
+ * near-touch case, e.g. a badge sitting on the wrong card) AND NOT
+ * `fixed`/`sticky` (see `UNCONTAINED_POSITIONS`) whose edge distance is at
+ * or below `opts.maxEdge` (default 4px).
+ *
+ * Implementation note: this is a straightforward O(n²) pass over the
+ * flattened node list, not the sort-by-x sweep the plan calls "ideal" —
+ * post-collapse layout trees are expected to be dozens to low hundreds of
+ * nodes (confirmed: the real owner-profile golden collapses 54 raw
+ * elements to 47 layout nodes), not thousands, so the quadratic pass is
+ * fast enough in practice and simpler to get right within this step's
+ * budget. Revisit with a sweep if a future corpus produces trees large
+ * enough for this to matter.
+ */
+function proximities(tree, opts = {}) {
+    const maxEdge = opts.maxEdge ?? DEFAULT_MAX_EDGE;
+    const entries = flattenWithLineage(tree);
+    const found = [];
+    for (let i = 0; i < entries.length; i++) {
+        for (let j = i + 1; j < entries.length; j++) {
+            const a = entries[i];
+            const b = entries[j];
+            if (!a || !b)
+                continue;
+            if (isAncestorPair(a, b))
+                continue;
+            if (a.parentId !== null && a.parentId === b.parentId)
+                continue; // direct siblings
+            if (UNCONTAINED_POSITIONS.has(a.node.position) || UNCONTAINED_POSITIONS.has(b.node.position))
+                continue;
+            const d = distance(a.node.rect, b.node.rect);
+            if (d.edge <= maxEdge) {
+                found.push({ a: a.node.elementId, b: b.node.elementId, edge: d.edge, dx: d.dx, dy: d.dy });
+            }
+        }
+    }
+    found.sort((x, y) => x.edge - y.edge || idCompare(x.a, y.a) || idCompare(x.b, y.b));
+    return found;
+}

package/dist/analysis/distances.d.cts

@@ -0,0 +1,58 @@
+import type { LayoutNode, ProximityPair, Rect } from "./types.cjs";
+export interface DistanceResult {
+    /** Signed x-axis edge gap (`geometry.ts#gapAlong`) — negative means the
+     * two rects overlap on the x axis. */
+    dx: number;
+    /** Signed y-axis edge gap — negative means overlap on the y axis. */
+    dy: number;
+    /** Euclidean gap between the closest edges, 0 when touching or
+     * overlapping on either axis (`dx`/`dy` are clamped to 0 before the
+     * Euclidean combination, so a real overlap never reads as a negative
+     * "closer than touching" edge distance). */
+    edge: number;
+    /** Straight center-to-center Euclidean distance — always positive,
+     * meaningful even when the two rects overlap (unlike `edge`). */
+    center: number;
+}
+/** Distance between two rects along every axis a query needs: signed
+ * per-axis gaps, the Euclidean closest-edge gap, and center-to-center. */
+export declare function distance(a: Rect, b: Rect): DistanceResult;
+export interface NearestOptions {
+    /** A child is always at distance 0 from its parent and is never useful
+     * information — excludes both ancestors AND descendants of the target
+     * node when true (the default). */
+    excludeAncestors?: boolean;
+}
+export interface NearestResult {
+    id: string;
+    edge: number;
+    dx: number;
+    dy: number;
+}
+/** The `k` layout nodes nearest `id` by edge distance (ascending, ties
+ * broken by id for determinism), excluding `id` itself and — by default —
+ * its ancestors and descendants. Returns `[]` if `id` isn't found. */
+export declare function nearest(tree: LayoutNode[], id: string, k?: number, opts?: NearestOptions): NearestResult[];
+export interface ProximitiesOptions {
+    /** Only pairs at or below this edge distance (px) are returned. Default
+     * 4 — genuinely close but not necessarily touching. */
+    maxEdge?: number;
+}
+/**
+ * Every pair of nodes that are NOT ancestor/descendant of each other AND
+ * NOT direct siblings (siblings are already covered by
+ * `neighbors.ts#siblingGaps` — this is specifically the cross-container
+ * near-touch case, e.g. a badge sitting on the wrong card) AND NOT
+ * `fixed`/`sticky` (see `UNCONTAINED_POSITIONS`) whose edge distance is at
+ * or below `opts.maxEdge` (default 4px).
+ *
+ * Implementation note: this is a straightforward O(n²) pass over the
+ * flattened node list, not the sort-by-x sweep the plan calls "ideal" —
+ * post-collapse layout trees are expected to be dozens to low hundreds of
+ * nodes (confirmed: the real owner-profile golden collapses 54 raw
+ * elements to 47 layout nodes), not thousands, so the quadratic pass is
+ * fast enough in practice and simpler to get right within this step's
+ * budget. Revisit with a sweep if a future corpus produces trees large
+ * enough for this to matter.
+ */
+export declare function proximities(tree: LayoutNode[], opts?: ProximitiesOptions): ProximityPair[];

package/dist/analysis/distances.d.ts

@@ -0,0 +1,58 @@
+import type { LayoutNode, ProximityPair, Rect } from "./types.js";
+export interface DistanceResult {
+    /** Signed x-axis edge gap (`geometry.ts#gapAlong`) — negative means the
+     * two rects overlap on the x axis. */
+    dx: number;
+    /** Signed y-axis edge gap — negative means overlap on the y axis. */
+    dy: number;
+    /** Euclidean gap between the closest edges, 0 when touching or
+     * overlapping on either axis (`dx`/`dy` are clamped to 0 before the
+     * Euclidean combination, so a real overlap never reads as a negative
+     * "closer than touching" edge distance). */
+    edge: number;
+    /** Straight center-to-center Euclidean distance — always positive,
+     * meaningful even when the two rects overlap (unlike `edge`). */
+    center: number;
+}
+/** Distance between two rects along every axis a query needs: signed
+ * per-axis gaps, the Euclidean closest-edge gap, and center-to-center. */
+export declare function distance(a: Rect, b: Rect): DistanceResult;
+export interface NearestOptions {
+    /** A child is always at distance 0 from its parent and is never useful
+     * information — excludes both ancestors AND descendants of the target
+     * node when true (the default). */
+    excludeAncestors?: boolean;
+}
+export interface NearestResult {
+    id: string;
+    edge: number;
+    dx: number;
+    dy: number;
+}
+/** The `k` layout nodes nearest `id` by edge distance (ascending, ties
+ * broken by id for determinism), excluding `id` itself and — by default —
+ * its ancestors and descendants. Returns `[]` if `id` isn't found. */
+export declare function nearest(tree: LayoutNode[], id: string, k?: number, opts?: NearestOptions): NearestResult[];
+export interface ProximitiesOptions {
+    /** Only pairs at or below this edge distance (px) are returned. Default
+     * 4 — genuinely close but not necessarily touching. */
+    maxEdge?: number;
+}
+/**
+ * Every pair of nodes that are NOT ancestor/descendant of each other AND
+ * NOT direct siblings (siblings are already covered by
+ * `neighbors.ts#siblingGaps` — this is specifically the cross-container
+ * near-touch case, e.g. a badge sitting on the wrong card) AND NOT
+ * `fixed`/`sticky` (see `UNCONTAINED_POSITIONS`) whose edge distance is at
+ * or below `opts.maxEdge` (default 4px).
+ *
+ * Implementation note: this is a straightforward O(n²) pass over the
+ * flattened node list, not the sort-by-x sweep the plan calls "ideal" —
+ * post-collapse layout trees are expected to be dozens to low hundreds of
+ * nodes (confirmed: the real owner-profile golden collapses 54 raw
+ * elements to 47 layout nodes), not thousands, so the quadratic pass is
+ * fast enough in practice and simpler to get right within this step's
+ * budget. Revisit with a sweep if a future corpus produces trees large
+ * enough for this to matter.
+ */
+export declare function proximities(tree: LayoutNode[], opts?: ProximitiesOptions): ProximityPair[];

package/dist/analysis/distances.js

@@ -0,0 +1,119 @@
+/**
+ * Geometric distance queries over a `LayoutNode[]` tree — the piece that
+ * lets an agent go from a digest's element ids to on-demand geometric
+ * answers (`query`'s `distance`/`nearest` verbs) instead of re-deriving
+ * arithmetic by hand from raw rects. Pure, tree-shaped, no `ElementRecord` —
+ * same boundary rules as the rest of `src/analysis/`.
+ */
+import { center, gapAlong } from "./geometry.js";
+/** Distance between two rects along every axis a query needs: signed
+ * per-axis gaps, the Euclidean closest-edge gap, and center-to-center. */
+export function distance(a, b) {
+    const dx = gapAlong(a, b, 'x');
+    const dy = gapAlong(a, b, 'y');
+    const edge = Math.sqrt(Math.max(dx, 0) ** 2 + Math.max(dy, 0) ** 2);
+    const ca = center(a);
+    const cb = center(b);
+    const centerDistance = Math.sqrt((ca.x - cb.x) ** 2 + (ca.y - cb.y) ** 2);
+    return { dx, dy, edge, center: centerDistance };
+}
+/** Flattens the tree once, tracking each node's immediate parent id (for
+ * sibling exclusion in `proximities`) and full ancestor-id set (for
+ * ancestor/descendant exclusion in both `nearest` and `proximities`) — the
+ * same lineage-tracking shape `neighbors.ts#overlaps` uses internally,
+ * reimplemented here rather than imported since `neighbors.ts` doesn't
+ * export it and this module also needs `parentId`, which that shape
+ * doesn't carry. */
+function flattenWithLineage(tree) {
+    const entries = [];
+    function visit(node, parentId, ancestorIds) {
+        entries.push({ node, parentId, ancestorIds });
+        const withSelf = new Set(ancestorIds);
+        withSelf.add(node.elementId);
+        for (const child of node.children)
+            visit(child, node.elementId, withSelf);
+    }
+    for (const root of tree)
+        visit(root, null, new Set());
+    return entries;
+}
+function isAncestorPair(a, b) {
+    return a.ancestorIds.has(b.node.elementId) || b.ancestorIds.has(a.node.elementId);
+}
+function idCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** `fixed`/`sticky` elements are deliberately layered over other content
+ * (persistent chrome like Charming's floating feedback launcher) — mirrors
+ * `checks/overflow.ts#UNCONTAINED_POSITIONS` and
+ * `neighbors.ts#UNCONTAINED_POSITIONS`. A `fixed` element reads as "near"
+ * whatever page content sits under it at the moment of capture, which is an
+ * artifact of scroll position, not a real proximity relationship between
+ * two page elements — the same reasoning that excludes it from `overlaps`
+ * applies here. */
+const UNCONTAINED_POSITIONS = new Set(['fixed', 'sticky']);
+const DEFAULT_K = 4;
+/** The `k` layout nodes nearest `id` by edge distance (ascending, ties
+ * broken by id for determinism), excluding `id` itself and — by default —
+ * its ancestors and descendants. Returns `[]` if `id` isn't found. */
+export function nearest(tree, id, k = DEFAULT_K, opts = {}) {
+    const excludeAncestors = opts.excludeAncestors ?? true;
+    const entries = flattenWithLineage(tree);
+    const target = entries.find((e) => e.node.elementId === id);
+    if (!target)
+        return [];
+    const results = [];
+    for (const entry of entries) {
+        if (entry.node.elementId === id)
+            continue;
+        if (excludeAncestors && isAncestorPair(target, entry))
+            continue;
+        const d = distance(target.node.rect, entry.node.rect);
+        results.push({ id: entry.node.elementId, edge: d.edge, dx: d.dx, dy: d.dy });
+    }
+    results.sort((x, y) => x.edge - y.edge || idCompare(x.id, y.id));
+    return results.slice(0, k);
+}
+const DEFAULT_MAX_EDGE = 4;
+/**
+ * Every pair of nodes that are NOT ancestor/descendant of each other AND
+ * NOT direct siblings (siblings are already covered by
+ * `neighbors.ts#siblingGaps` — this is specifically the cross-container
+ * near-touch case, e.g. a badge sitting on the wrong card) AND NOT
+ * `fixed`/`sticky` (see `UNCONTAINED_POSITIONS`) whose edge distance is at
+ * or below `opts.maxEdge` (default 4px).
+ *
+ * Implementation note: this is a straightforward O(n²) pass over the
+ * flattened node list, not the sort-by-x sweep the plan calls "ideal" —
+ * post-collapse layout trees are expected to be dozens to low hundreds of
+ * nodes (confirmed: the real owner-profile golden collapses 54 raw
+ * elements to 47 layout nodes), not thousands, so the quadratic pass is
+ * fast enough in practice and simpler to get right within this step's
+ * budget. Revisit with a sweep if a future corpus produces trees large
+ * enough for this to matter.
+ */
+export function proximities(tree, opts = {}) {
+    const maxEdge = opts.maxEdge ?? DEFAULT_MAX_EDGE;
+    const entries = flattenWithLineage(tree);
+    const found = [];
+    for (let i = 0; i < entries.length; i++) {
+        for (let j = i + 1; j < entries.length; j++) {
+            const a = entries[i];
+            const b = entries[j];
+            if (!a || !b)
+                continue;
+            if (isAncestorPair(a, b))
+                continue;
+            if (a.parentId !== null && a.parentId === b.parentId)
+                continue; // direct siblings
+            if (UNCONTAINED_POSITIONS.has(a.node.position) || UNCONTAINED_POSITIONS.has(b.node.position))
+                continue;
+            const d = distance(a.node.rect, b.node.rect);
+            if (d.edge <= maxEdge) {
+                found.push({ a: a.node.elementId, b: b.node.elementId, edge: d.edge, dx: d.dx, dy: d.dy });
+            }
+        }
+    }
+    found.sort((x, y) => x.edge - y.edge || idCompare(x.a, y.a) || idCompare(x.b, y.b));
+    return found;
+}

package/dist/analysis/geometry.cjs

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.intersect = intersect;
+exports.contains = contains;
+exports.gapAlong = gapAlong;
+exports.area = area;
+exports.center = center;
+/**
+ * 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.
+ */
+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. */
+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.
+ */
+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². */
+function area(r) {
+    return r.width * r.height;
+}
+/** Rect center point. */
+function center(r) {
+    return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+}