@michaelmagan/dnumb 0.1.0

package/dist/analysis/types.d.ts

@@ -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[];
+}

package/dist/analysis/types.js

@@ -0,0 +1,6 @@
+/**
+ * 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.
+ */
+export {};

package/dist/bundle.cjs

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BundleFormatError = void 0;
+exports.buildBundle = buildBundle;
+exports.parseBundle = parseBundle;
+exports.serializeBundle = serializeBundle;
+const index_js_1 = require("./spec/index.cjs");
+/**
+ * The four color-capture string fields and the two overlap-signal fields are
+ * required on `ElementRecord` (`snapshot/types.ts`) -- both real capture
+ * paths always set all six, the same as `rect` or `overflowX`. A bundle
+ * written before they existed simply has no key for them at all in its JSON,
+ * though, which is not the same violation as a caller hand-building a record
+ * and skipping one: this is a format-migration problem, not a construction
+ * error, so it gets a format-migration fix here rather than the clear thrown
+ * error `snapshot/color.ts#requireColorField` gives a hand-built record that
+ * is missing a required field. Reading `undefined.trim()` or
+ * `undefined.indexOf(...)` off an unmigrated old record would throw deep
+ * inside `snapshot/color.ts` regardless of which of the two situations
+ * produced it, which is exactly the failure this function exists to
+ * pre-empt for the bundle case specifically.
+ *
+ * `textShadow`/`textStrokeWidth`/`textStrokeColor` are backfilled with the
+ * same defaults a fresh capture with nothing to report would itself have
+ * written -- `'none'`/`'0px'`/opaque black -- because a missing value and a
+ * genuine "no such style" both render identically for these three (each is
+ * an optional counter-fact token, printed only when present; see
+ * `snapshot/color.ts#colorFactFor`'s tail tokens), so there is no
+ * fabrication risk in picking the harmless default.
+ *
+ * `backgroundImage` does NOT get that treatment (A3, fixed here): it feeds
+ * `resolveBackdrop`'s gradient/image detection directly, so defaulting a
+ * genuinely-uncaptured value to `'none'` used to manufacture the positive
+ * claim "this element has no background image" -- which then silently
+ * terminated the compositing walk and printed a specific, fabricated ratio.
+ * `null` here means exactly what it means on `hitStackIds`/`paintOrder`
+ * below: this specific capture never measured this field, and
+ * `snapshot/color.ts` refuses to guess past it (reports
+ * `unmeasured (not-captured ...)` instead) -- the same "backfill the honest
+ * unknown, not a false positive" discipline `NO_CAPTURE_NOT_MEASURED` below
+ * uses for shadow roots and iframes.
+ *
+ * Every record `parseBundle` returns satisfies the required contract by
+ * construction; `requireColorField` exists for the different case of a
+ * record that never went through this function at all.
+ */
+function normalizeElement(raw) {
+    const el = raw;
+    return {
+        ...el,
+        backgroundImage: el.backgroundImage ?? null,
+        textShadow: el.textShadow ?? 'none',
+        textStrokeWidth: el.textStrokeWidth ?? '0px',
+        textStrokeColor: el.textStrokeColor ?? 'rgb(0, 0, 0)',
+        hitStackIds: el.hitStackIds ?? null,
+        paintOrder: el.paintOrder ?? null,
+    };
+}
+/**
+ * Stand-in for `notMeasured` when a `CaptureResult` has none -- both real
+ * capture paths always set it, so this only fires for a hand-built result
+ * that skipped them entirely (a test fixture, typically). `closed: 'unknown'`
+ * because that is true regardless of how the result was built; the rest
+ * default to zero rather than to a matching 'unknown', which is a real
+ * "no measurement was taken" gap this constant papers over for a
+ * non-production caller, not a claim about the page.
+ */
+const NO_CAPTURE_NOT_MEASURED = {
+    shadowRoots: { open: 0, closed: 'unknown' },
+    iframes: { sameOrigin: 0, crossOrigin: 0, unknownOrigin: 0 },
+};
+function buildBundle(capture, options) {
+    return {
+        spec: index_js_1.SPEC_VERSION,
+        name: options.name,
+        url: options.url,
+        capturedAt: options.capturedAt,
+        viewport: options.viewportName
+            ? { name: options.viewportName, ...capture.viewport }
+            : capture.viewport,
+        strategy: capture.strategy,
+        truncated: capture.truncated,
+        ...(capture.cdpFellBack ? { cdpFellBack: true } : {}),
+        notMeasured: capture.notMeasured ?? NO_CAPTURE_NOT_MEASURED,
+        documentBackground: capture.documentBackground ?? null,
+        elements: capture.elements,
+        ...(options.labels ? { labels: options.labels } : {}),
+    };
+}
+class BundleFormatError extends Error {
+    name = 'BundleFormatError';
+}
+exports.BundleFormatError = BundleFormatError;
+/**
+ * Parse and validate. Structural, not schema-library: the check exists so a
+ * consumer gets "this is not a dnumb bundle" rather than `undefined is not an
+ * object` fourteen frames deep, and that does not need a dependency.
+ */
+function parseBundle(text, source = '<input>') {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new BundleFormatError(`${source} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof value !== 'object' || value === null) {
+        throw new BundleFormatError(`${source} is not a dnumb bundle (expected a JSON object)`);
+    }
+    const bundle = value;
+    if (typeof bundle.spec !== 'number') {
+        throw new BundleFormatError(`${source} is not a dnumb bundle (no "spec" field)`);
+    }
+    if (bundle.spec > index_js_1.SPEC_VERSION) {
+        throw new BundleFormatError(`${source} was written by a newer dnumb (spec ${bundle.spec}; this build reads ${index_js_1.SPEC_VERSION}). Upgrade dnumb.`);
+    }
+    if (!Array.isArray(bundle.elements)) {
+        throw new BundleFormatError(`${source} has no "elements" array`);
+    }
+    if (typeof bundle.viewport !== 'object' || bundle.viewport === null) {
+        throw new BundleFormatError(`${source} has no "viewport"`);
+    }
+    // `Bundle.strategy`'s own doc comment: "Recorded, never inferred" (B4).
+    // `bundle.strategy ?? 'walk'` used to assert a specific capture path a
+    // bundle never actually recorded -- a `cdp` bundle whose `"strategy"` key
+    // happened to be missing (an old writer, a hand-edited file) would parse
+    // back claiming to be `walk`, which is a different, real fact this bundle
+    // never measured. Neither value is an honest default for "don't know", so
+    // this refuses to parse rather than guess one -- the same register the
+    // `notMeasured` check just below uses for the identical shape of problem.
+    if (bundle.strategy !== 'cdp' && bundle.strategy !== 'walk') {
+        throw new BundleFormatError(`${source} has no valid "strategy" (must be "cdp" or "walk", got ` +
+            `${JSON.stringify(bundle.strategy)}): this build cannot honestly say which capture path ` +
+            'produced these records, and defaulting to "walk" would assert a specific path this ' +
+            'bundle never recorded. Re-capture the page with a current dnumb.');
+    }
+    // `NotMeasured`'s own doc comment: "every other field here is always a
+    // real, counted number." `NO_CAPTURE_NOT_MEASURED`'s zeroed shape is that
+    // promise's one sanctioned exception, and it is scoped narrowly -- "a
+    // hand-built [CaptureResult] that skipped them entirely (a test fixture,
+    // typically)", i.e. `buildBundle`'s in-memory case just above, where no
+    // capture happened at all and nothing claims otherwise. A bundle read back
+    // from disk is different: it is a *real* prior capture, and reusing that
+    // same all-zero shape for one that predates `notMeasured` used to print a
+    // specific, confident zero cross-origin-iframe count a page might not
+    // actually have (B4) -- exactly the "always a real, counted number"
+    // promise broken. There is no honest partial value this format can hand
+    // back for that case (unlike `strategy`, `NotMeasured`'s numeric fields
+    // have no `| undefined`/`'unknown'` escape hatch), so this refuses outright
+    // rather than fabricate one: re-capture with a current dnumb instead.
+    if (bundle.notMeasured === undefined) {
+        throw new BundleFormatError(`${source} predates capture accounting ("notMeasured") and cannot be read by this build: ` +
+            'it has no honest way to report shadow-DOM/iframe coverage for a bundle this old, and ' +
+            'silently reporting zero would claim a specific count this bundle never measured. ' +
+            're-capture the page with a current dnumb to get a bundle this build can read.');
+    }
+    return {
+        // The value this bundle actually claims, preserved -- never rewritten to
+        // this build's own `SPEC_VERSION` (B4). Already validated above: a
+        // number, and no greater than `SPEC_VERSION`.
+        spec: bundle.spec,
+        name: bundle.name ?? 'capture',
+        url: bundle.url ?? '',
+        capturedAt: bundle.capturedAt ?? '',
+        viewport: bundle.viewport,
+        // Already validated above: exactly `'cdp'` or `'walk'`, never inferred.
+        strategy: bundle.strategy,
+        truncated: bundle.truncated ?? false,
+        ...(bundle.cdpFellBack ? { cdpFellBack: true } : {}),
+        notMeasured: bundle.notMeasured,
+        // `null` on a bundle old enough to predate color capture entirely (before
+        // `documentBackground` existed) -- an honest "never measured", not a
+        // guessed canvas color. See `DocumentBackground`.
+        documentBackground: bundle.documentBackground ?? null,
+        elements: bundle.elements.map(normalizeElement),
+        ...(bundle.labels ? { labels: bundle.labels } : {}),
+    };
+}
+/** The bundle as it is written to disk. Stable key order, one trailing newline. */
+function serializeBundle(bundle) {
+    return `${JSON.stringify(bundle, null, 2)}\n`;
+}

package/dist/bundle.d.cts

@@ -0,0 +1,91 @@
+/**
+ * The capture bundle — the load-bearing object in this package.
+ *
+ * Not the browser session. A bundle is a self-describing file that answers
+ * `q describe e91` six months later, on a machine with no app and no browser.
+ * Percy and Chromatic artifacts are pixels for human eyes; an aria snapshot has
+ * no geometry; a Playwright trace is a replayable page rather than a set of
+ * measurements. This is measurements, and it travels.
+ *
+ * It is deliberately a plain JSON object with a version on it, because the
+ * thing most likely to read it is a program written after this one.
+ */
+import type { CaptureResult } from "./snapshot/capture.cjs";
+import type { DocumentBackground, ElementRecord, NotMeasured } from "./snapshot/types.cjs";
+export interface Bundle {
+    /**
+     * The capture format version this bundle actually claims to be.
+     *
+     * A fresh capture (`buildBundle`) always writes the running build's own
+     * `SPEC_VERSION`, because that is genuinely what it is. Reading a bundle
+     * back (`parseBundle`) is different: this is the value *parsed from the
+     * file*, preserved as-is, never silently rewritten to the current build's
+     * `SPEC_VERSION` (B4) -- doing that used to make a bundle from an older
+     * spec claim, falsely, to be current. It can therefore be lower than
+     * `SPEC_VERSION` (never higher: `parseBundle` already throws on that, see
+     * below) on a bundle this build can still read but did not itself write.
+     */
+    spec: number;
+    /** Caller-chosen name for this capture: `settings-desktop`, `menu-open`. */
+    name: string;
+    url: string;
+    /** ISO 8601. Set by the writer, not by the collector. */
+    capturedAt: string;
+    viewport: {
+        name?: string;
+        width: number;
+        height: number;
+    };
+    /**
+     * Which capture path produced these records. Recorded, never inferred
+     * (B4): a bundle whose `"strategy"` is missing or not one of these two
+     * literals is not a bundle `parseBundle` can honestly assign a strategy
+     * to -- it refuses to parse rather than default to `'walk'`, which used
+     * to assert a specific capture path a bundle never recorded and could
+     * just as well have been `'cdp'`. See `parseBundle`.
+     */
+    strategy: 'cdp' | 'walk';
+    /** True when the capture stopped at the element cap. */
+    truncated: boolean;
+    /**
+     * True only for a `strategy: 'walk'` bundle that got there by CDP failing
+     * on a Chromium page, not by running on a browser CDP never covers. See the
+     * doc comment on `CaptureResult.cdpFellBack`.
+     */
+    cdpFellBack?: boolean;
+    /** Shadow DOM and iframe content this capture walked past. See `NotMeasured`. */
+    notMeasured: NotMeasured;
+    /**
+     * `<html>`'s own background-color/color-scheme -- see `DocumentBackground`.
+     * `null` on a bundle old enough to predate color capture entirely: an
+     * honest "never measured", the same register `documentBackground: null`
+     * uses everywhere else in this file, never a guessed color. Optional only
+     * so a hand-built `Bundle` in a test need not name a value it has no
+     * opinion about, exactly like `Snapshot.documentBackground` -- `buildBundle`
+     * and `parseBundle` both always set it (to a real value or `null`, never
+     * leaving the key absent).
+     */
+    documentBackground?: DocumentBackground | null;
+    elements: ElementRecord[];
+    /** Free-form labels a caller attaches: theme, branch, test title. */
+    labels?: Record<string, string>;
+}
+export interface BuildBundleOptions {
+    name: string;
+    url: string;
+    capturedAt: string;
+    viewportName?: string;
+    labels?: Record<string, string>;
+}
+export declare function buildBundle(capture: CaptureResult, options: BuildBundleOptions): Bundle;
+export declare class BundleFormatError extends Error {
+    name: string;
+}
+/**
+ * Parse and validate. Structural, not schema-library: the check exists so a
+ * consumer gets "this is not a dnumb bundle" rather than `undefined is not an
+ * object` fourteen frames deep, and that does not need a dependency.
+ */
+export declare function parseBundle(text: string, source?: string): Bundle;
+/** The bundle as it is written to disk. Stable key order, one trailing newline. */
+export declare function serializeBundle(bundle: Bundle): string;

package/dist/bundle.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The capture bundle — the load-bearing object in this package.
+ *
+ * Not the browser session. A bundle is a self-describing file that answers
+ * `q describe e91` six months later, on a machine with no app and no browser.
+ * Percy and Chromatic artifacts are pixels for human eyes; an aria snapshot has
+ * no geometry; a Playwright trace is a replayable page rather than a set of
+ * measurements. This is measurements, and it travels.
+ *
+ * It is deliberately a plain JSON object with a version on it, because the
+ * thing most likely to read it is a program written after this one.
+ */
+import type { CaptureResult } from "./snapshot/capture.js";
+import type { DocumentBackground, ElementRecord, NotMeasured } from "./snapshot/types.js";
+export interface Bundle {
+    /**
+     * The capture format version this bundle actually claims to be.
+     *
+     * A fresh capture (`buildBundle`) always writes the running build's own
+     * `SPEC_VERSION`, because that is genuinely what it is. Reading a bundle
+     * back (`parseBundle`) is different: this is the value *parsed from the
+     * file*, preserved as-is, never silently rewritten to the current build's
+     * `SPEC_VERSION` (B4) -- doing that used to make a bundle from an older
+     * spec claim, falsely, to be current. It can therefore be lower than
+     * `SPEC_VERSION` (never higher: `parseBundle` already throws on that, see
+     * below) on a bundle this build can still read but did not itself write.
+     */
+    spec: number;
+    /** Caller-chosen name for this capture: `settings-desktop`, `menu-open`. */
+    name: string;
+    url: string;
+    /** ISO 8601. Set by the writer, not by the collector. */
+    capturedAt: string;
+    viewport: {
+        name?: string;
+        width: number;
+        height: number;
+    };
+    /**
+     * Which capture path produced these records. Recorded, never inferred
+     * (B4): a bundle whose `"strategy"` is missing or not one of these two
+     * literals is not a bundle `parseBundle` can honestly assign a strategy
+     * to -- it refuses to parse rather than default to `'walk'`, which used
+     * to assert a specific capture path a bundle never recorded and could
+     * just as well have been `'cdp'`. See `parseBundle`.
+     */
+    strategy: 'cdp' | 'walk';
+    /** True when the capture stopped at the element cap. */
+    truncated: boolean;
+    /**
+     * True only for a `strategy: 'walk'` bundle that got there by CDP failing
+     * on a Chromium page, not by running on a browser CDP never covers. See the
+     * doc comment on `CaptureResult.cdpFellBack`.
+     */
+    cdpFellBack?: boolean;
+    /** Shadow DOM and iframe content this capture walked past. See `NotMeasured`. */
+    notMeasured: NotMeasured;
+    /**
+     * `<html>`'s own background-color/color-scheme -- see `DocumentBackground`.
+     * `null` on a bundle old enough to predate color capture entirely: an
+     * honest "never measured", the same register `documentBackground: null`
+     * uses everywhere else in this file, never a guessed color. Optional only
+     * so a hand-built `Bundle` in a test need not name a value it has no
+     * opinion about, exactly like `Snapshot.documentBackground` -- `buildBundle`
+     * and `parseBundle` both always set it (to a real value or `null`, never
+     * leaving the key absent).
+     */
+    documentBackground?: DocumentBackground | null;
+    elements: ElementRecord[];
+    /** Free-form labels a caller attaches: theme, branch, test title. */
+    labels?: Record<string, string>;
+}
+export interface BuildBundleOptions {
+    name: string;
+    url: string;
+    capturedAt: string;
+    viewportName?: string;
+    labels?: Record<string, string>;
+}
+export declare function buildBundle(capture: CaptureResult, options: BuildBundleOptions): Bundle;
+export declare class BundleFormatError extends Error {
+    name: string;
+}
+/**
+ * Parse and validate. Structural, not schema-library: the check exists so a
+ * consumer gets "this is not a dnumb bundle" rather than `undefined is not an
+ * object` fourteen frames deep, and that does not need a dependency.
+ */
+export declare function parseBundle(text: string, source?: string): Bundle;
+/** The bundle as it is written to disk. Stable key order, one trailing newline. */
+export declare function serializeBundle(bundle: Bundle): string;