@michaelmagan/dnumb 0.1.0

package/dist/bundle.js

@@ -0,0 +1,175 @@
+import { SPEC_VERSION } from "./spec/index.js";
+/**
+ * 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 },
+};
+export function buildBundle(capture, options) {
+    return {
+        spec: 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 } : {}),
+    };
+}
+export class BundleFormatError extends Error {
+    name = '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.
+ */
+export 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 > SPEC_VERSION) {
+        throw new BundleFormatError(`${source} was written by a newer dnumb (spec ${bundle.spec}; this build reads ${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. */
+export function serializeBundle(bundle) {
+    return `${JSON.stringify(bundle, null, 2)}\n`;
+}