@juxtapose/core 0.2.0 → 0.5.0

package/dist/capture/snap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snap.js","sourceRoot":"","sources":["../../src/capture/snap.ts"],"names":[],"mappings":"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"}

package/dist/capture/structure.d.ts

@@ -0,0 +1,77 @@
+import type { Page } from '../browser/page.js';
+import type { StructureSnapshot, Viewport } from '../types.js';
+/** Styles recorded per element. `display`/`visibility` are deliberately absent:
+ *  display:none elements have no layout entry at all, and visibility is read
+ *  only to filter (see `visibilityIdx` in normalizeStructure). */
+export declare const STRUCTURE_PROPS: readonly string[];
+/** Inherited properties are stored only where they differ from the parent. */
+export declare const INHERITED_PROPS: ReadonlySet<string>;
+/** Computed-style initial values for non-inherited properties. A value equal
+ *  to its initial value is not stored. Border colors are special-cased: they
+ *  default to currentColor, so they are stored only when that side's width is
+ *  non-zero. */
+export declare const INITIAL_VALUES: Readonly<Record<string, string>>;
+export declare const MASK_ATTR = "data-jux-masked";
+export declare const MAX_ELEMENTS = 5000;
+/** The subset of a CDP DOMSnapshot.captureSnapshot response we read. */
+export interface CdpSnapshot {
+    documents: Array<{
+        contentHeight?: number;
+        nodes: {
+            parentIndex: number[];
+            nodeType: number[];
+            nodeName: number[];
+            nodeValue: number[];
+            attributes: number[][];
+            /** Rare-string data: parallel arrays of node index → string index.
+             *  Verified on Chromium 151: pseudo-elements appear as element nodes
+             *  named `::before`/`::after` with pseudoType set; an <input>'s typed
+             *  value is in inputValue, not in an attribute. */
+            pseudoType?: {
+                index: number[];
+                value: number[];
+            };
+            inputValue?: {
+                index: number[];
+                value: number[];
+            };
+        };
+        layout: {
+            nodeIndex: number[];
+            styles: number[][];
+            bounds: number[][];
+            paintOrders?: number[];
+        };
+    }>;
+    strings: string[];
+}
+export declare const round: (n: number) => number;
+/**
+ * Turn a raw CDP snapshot into a StructureSnapshot.
+ *
+ * Only the top document is read: iframe content is a separate document and is
+ * represented by the <iframe> element's own rect. Open shadow content is part
+ * of the host document's node list and is included.
+ */
+export declare function normalizeStructure(raw: CdpSnapshot, viewport: Viewport): StructureSnapshot;
+/** The full value of `prop` for element `index`, reconstructing what the
+ *  compact storage omitted. */
+export declare function effectiveStyle(s: StructureSnapshot, index: number, prop: string): string;
+export declare function encodeStructure(s: StructureSnapshot): Buffer;
+export declare function decodeStructure(b: Buffer): StructureSnapshot;
+/**
+ * Snapshot the page's structure. Never throws: a missing structure costs the
+ * agent some explanation, a thrown error would cost the story its capture.
+ *
+ * Mask selectors are resolved with the same CSS-over-open-shadow-roots query
+ * the screenshot masks with; Playwright-only syntax is rejected in
+ * captureStory before anything runs. Matches get MASK_ATTR so the normalizer
+ * collapses their subtree. A plain document.querySelectorAll would miss
+ * matches inside shadow roots and leak masked content into the sidecar.
+ *
+ * Fail closed: if marking fails, or any match lost its mark by the time the
+ * snapshot returns (the page mutated in between), return undefined. Setting an
+ * attribute does not affect paint unless a stylesheet targets it, which
+ * nothing ships with.
+ */
+export declare function captureStructure(page: Page, viewport: Viewport, mask: readonly string[]): Promise<StructureSnapshot | undefined>;

package/dist/capture/structure.js

@@ -0,0 +1,498 @@
+// Structure snapshot: the visible DOM and its computed styles, captured in the
+// same frame as the screenshot.
+//
+// Why: pixels say WHERE something changed; this says WHAT — which element,
+// which property, old → new — so an agent can decide without reading an image
+// (spec: docs/specs/2026-10-12-sp0-structural-diff-agent-surface-design.md).
+// It explains a failure; it never decides one. The pixel hash still does.
+//
+// Everything here is a pure function of the CDP response so it can be tested
+// against real Chromium output committed as a fixture.
+import { createHash } from 'node:crypto';
+import { gunzipSync, gzipSync } from 'node:zlib';
+import { queryAllExpression } from '../browser/selectors.js';
+/** Styles recorded per element. `display`/`visibility` are deliberately absent:
+ *  display:none elements have no layout entry at all, and visibility is read
+ *  only to filter (see `visibilityIdx` in normalizeStructure). */
+export const STRUCTURE_PROPS = [
+    'color',
+    'background-color',
+    'background-image',
+    'font-family',
+    'font-size',
+    'font-weight',
+    'font-style',
+    'line-height',
+    'letter-spacing',
+    'text-align',
+    'text-decoration-line',
+    'text-transform',
+    'padding-top',
+    'padding-right',
+    'padding-bottom',
+    'padding-left',
+    'margin-top',
+    'margin-right',
+    'margin-bottom',
+    'margin-left',
+    'border-top-width',
+    'border-right-width',
+    'border-bottom-width',
+    'border-left-width',
+    'border-top-color',
+    'border-right-color',
+    'border-bottom-color',
+    'border-left-color',
+    'border-top-left-radius',
+    'border-top-right-radius',
+    'border-bottom-right-radius',
+    'border-bottom-left-radius',
+    'opacity',
+    'transform',
+    'box-shadow',
+    'gap',
+    'z-index',
+    // SVG paint is computed style, not an attribute: without these an icon
+    // recolour is unexplained pixels.
+    'fill',
+    'stroke',
+    'stroke-width',
+    // A pseudo-element's visible text lives here, not in a text node: without it
+    // a CSS icon swap (`content: "★"` → `"☆"`) is unexplained pixels.
+    'content',
+];
+/** Inherited properties are stored only where they differ from the parent. */
+export const INHERITED_PROPS = new Set([
+    'color',
+    'font-family',
+    'font-size',
+    'font-weight',
+    'font-style',
+    'line-height',
+    'letter-spacing',
+    'text-align',
+    'text-transform',
+    'fill',
+    'stroke',
+    'stroke-width',
+]);
+/** Computed-style initial values for non-inherited properties. A value equal
+ *  to its initial value is not stored. Border colors are special-cased: they
+ *  default to currentColor, so they are stored only when that side's width is
+ *  non-zero. */
+export const INITIAL_VALUES = {
+    'background-color': 'rgba(0, 0, 0, 0)',
+    'background-image': 'none',
+    'text-decoration-line': 'none',
+    'padding-top': '0px',
+    'padding-right': '0px',
+    'padding-bottom': '0px',
+    'padding-left': '0px',
+    'margin-top': '0px',
+    'margin-right': '0px',
+    'margin-bottom': '0px',
+    'margin-left': '0px',
+    'border-top-width': '0px',
+    'border-right-width': '0px',
+    'border-bottom-width': '0px',
+    'border-left-width': '0px',
+    'border-top-left-radius': '0px',
+    'border-top-right-radius': '0px',
+    'border-bottom-right-radius': '0px',
+    'border-bottom-left-radius': '0px',
+    opacity: '1',
+    transform: 'none',
+    'box-shadow': 'none',
+    gap: 'normal',
+    'z-index': 'auto',
+    content: 'normal',
+};
+/** Root defaults for inherited props when no kept ancestor exists. */
+const ROOT_INHERITED = {
+    color: 'rgb(0, 0, 0)',
+    'font-style': 'normal',
+    'font-weight': '400',
+    'letter-spacing': 'normal',
+    'text-align': 'start',
+    'text-transform': 'none',
+    // SVG paint defaults (CSS initial values, as Chromium computes them)
+    fill: 'rgb(0, 0, 0)',
+    stroke: 'none',
+    'stroke-width': '1px',
+};
+export const MASK_ATTR = 'data-jux-masked';
+export const MAX_ELEMENTS = 5000;
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const IMPLICIT_ROLES = {
+    button: 'button',
+    h1: 'heading',
+    h2: 'heading',
+    h3: 'heading',
+    h4: 'heading',
+    h5: 'heading',
+    h6: 'heading',
+    img: 'img',
+    select: 'combobox',
+    textarea: 'textbox',
+    nav: 'navigation',
+    main: 'main',
+    header: 'banner',
+    footer: 'contentinfo',
+    ul: 'list',
+    ol: 'list',
+    li: 'listitem',
+    table: 'table',
+    dialog: 'dialog',
+    iframe: 'document',
+};
+export const round = (n) => Math.round(n * 100) / 100;
+/**
+ * Turn a raw CDP snapshot into a StructureSnapshot.
+ *
+ * Only the top document is read: iframe content is a separate document and is
+ * represented by the <iframe> element's own rect. Open shadow content is part
+ * of the host document's node list and is included.
+ */
+export function normalizeStructure(raw, viewport) {
+    const doc = raw.documents[0];
+    const str = (i) => i === undefined || i < 0 ? undefined : raw.strings[i];
+    const { nodes, layout } = doc;
+    const styleIdx = STRUCTURE_PROPS.map((_, i) => i);
+    // `visibility` is requested after STRUCTURE_PROPS and used only to filter.
+    const visibilityIdx = STRUCTURE_PROPS.length;
+    // node index -> layout row. A node can have several rows (a pseudo-element
+    // gets one for its box and one per text fragment); the FIRST is the box.
+    const layoutOf = new Map();
+    layout.nodeIndex.forEach((n, row) => {
+        if (!layoutOf.has(n))
+            layoutOf.set(n, row);
+    });
+    const contentIdx = STRUCTURE_PROPS.indexOf('content');
+    const rare = (r) => {
+        const m = new Map();
+        r?.index.forEach((n, k) => m.set(n, str(r.value[k]) ?? ''));
+        return m;
+    };
+    const inputValue = rare(nodes.inputValue);
+    // children lists and own text, in document order
+    const children = new Map();
+    const ownText = new Map();
+    for (let i = 0; i < nodes.nodeType.length; i++) {
+        const p = nodes.parentIndex[i];
+        if (p < 0)
+            continue;
+        if (nodes.nodeType[i] === TEXT_NODE) {
+            const t = str(nodes.nodeValue[i]) ?? '';
+            ownText.set(p, (ownText.get(p) ?? '') + t);
+        }
+        else if (nodes.nodeType[i] === ELEMENT_NODE) {
+            const list = children.get(p) ?? [];
+            list.push(i);
+            children.set(p, list);
+        }
+    }
+    const attrs = (i) => {
+        const out = {};
+        const a = nodes.attributes[i] ?? [];
+        for (let k = 0; k + 1 < a.length; k += 2)
+            out[str(a[k])] = str(a[k + 1]) ?? '';
+        return out;
+    };
+    const elements = [];
+    let total = 0;
+    // effective inherited values per kept element, for compact storage
+    const effective = [];
+    const visit = (i, parentPath, keptParent) => {
+        const tag = (str(nodes.nodeName[i]) ?? '').toLowerCase();
+        if (tag === 'head' || tag === 'script' || tag === 'style')
+            return;
+        const a = attrs(i);
+        const siblings = children.get(nodes.parentIndex[i]) ?? [];
+        const sameTag = siblings.filter((s) => (str(nodes.nodeName[s]) ?? '').toLowerCase() === tag);
+        const step = a.id !== undefined
+            ? `${tag}#${a.id}`
+            : a['data-testid'] !== undefined
+                ? `${tag}[data-testid="${a['data-testid']}"]`
+                : `${tag}:nth-of-type(${sameTag.indexOf(i) + 1})`;
+        const path = parentPath ? `${parentPath}>${step}` : step;
+        const row = layoutOf.get(i);
+        // Mask first, before any check that can descend: a visibility:hidden mask
+        // target with a visibility:visible child used to take the hidden branch
+        // below and record the child's text, while the screenshot mask covered it.
+        if (a[MASK_ATTR] !== undefined) {
+            if (row === undefined)
+                return; // no box: nothing to stand in for
+            total++;
+            if (elements.length < MAX_ELEMENTS) {
+                const [x, y, w, h] = layout.bounds[row];
+                elements.push({
+                    path,
+                    parent: keptParent,
+                    tag: 'masked',
+                    rect: { x: round(x), y: round(y), w: round(w), h: round(h) },
+                    paintOrder: layout.paintOrders?.[row] ?? 0,
+                    styles: {},
+                });
+                effective.push(keptParent === null ? { ...ROOT_INHERITED } : effective[keptParent]);
+            }
+            return; // never descend into a masked subtree
+        }
+        if (row === undefined)
+            return; // display:none (or no box): drop the subtree
+        const values = layout.styles[row].map((s) => urlsToFileNames(str(s) ?? ''));
+        if (values[visibilityIdx] === 'hidden' || values[visibilityIdx] === 'collapse') {
+            // hidden boxes can still contain visible descendants (visibility: visible)
+            for (const c of children.get(i) ?? [])
+                visit(c, path, keptParent);
+            return;
+        }
+        const [x, y, w, h] = layout.bounds[row];
+        const rect = { x: round(x), y: round(y), w: round(w), h: round(h) };
+        const offscreen = rect.x + rect.w <= 0 ||
+            rect.y + rect.h <= 0 ||
+            rect.x >= viewport.width ||
+            rect.y >= viewport.height;
+        const empty = rect.w <= 0 || rect.h <= 0;
+        const keep = !offscreen && !empty && tag !== 'html' && tag !== 'body';
+        let me = keptParent;
+        if (keep) {
+            total++;
+            if (elements.length < MAX_ELEMENTS) {
+                const inherited = keptParent === null ? ROOT_INHERITED : effective[keptParent];
+                const styles = {};
+                const eff = { ...inherited };
+                for (const k of styleIdx) {
+                    const prop = STRUCTURE_PROPS[k];
+                    const v = values[k];
+                    if (INHERITED_PROPS.has(prop)) {
+                        eff[prop] = v;
+                        if (inherited[prop] !== v)
+                            styles[prop] = v;
+                    }
+                    else if (prop.startsWith('border-') && prop.endsWith('-color')) {
+                        const side = prop.split('-')[1];
+                        const width = values[STRUCTURE_PROPS.indexOf(`border-${side}-width`)];
+                        if (width !== '0px')
+                            styles[prop] = v;
+                    }
+                    else if (INITIAL_VALUES[prop] !== v) {
+                        styles[prop] = v;
+                    }
+                }
+                // `content` is meaningful only on a pseudo-element, where it IS the
+                // text; on a normal element it is always `normal`, so drop it there.
+                const isPseudo = tag.startsWith('::');
+                if (!isPseudo)
+                    delete styles.content;
+                const pseudoText = isPseudo ? parseContent(values[contentIdx]) : '';
+                // Sidecars are committed to git: never record a secret field's value.
+                const secret = tag === 'input' && isSecretInput(a);
+                const typed = secret ? undefined : inputValue.get(i);
+                const text = collapse(pseudoText || typed || ownText.get(i) || '');
+                const role = a.role ?? implicitRole(tag, a);
+                const name = (a['aria-label'] ?? a.alt ?? a.title ?? text) || undefined;
+                const el = {
+                    path,
+                    parent: keptParent,
+                    tag,
+                    rect,
+                    paintOrder: layout.paintOrders?.[row] ?? 0,
+                    styles,
+                };
+                if (a.id !== undefined)
+                    el.id = a.id;
+                if (a['data-testid'] !== undefined)
+                    el.testId = a['data-testid'];
+                const classes = (a.class ?? '').split(/\s+/).filter(Boolean);
+                if (classes.length)
+                    el.classes = classes;
+                if (role)
+                    el.role = role;
+                if (name)
+                    el.name = name.slice(0, 80);
+                if (text)
+                    el.text = text.slice(0, 200);
+                if (a.src !== undefined)
+                    el.src = fileName(a.src);
+                elements.push(el);
+                effective.push(eff);
+                me = elements.length - 1;
+            }
+        }
+        for (const c of children.get(i) ?? [])
+            visit(c, path, me);
+    };
+    // node 0 is #document; start from its element children (<html>)
+    for (const c of children.get(0) ?? [])
+        visit(c, '', null);
+    const snapshot = {
+        schema: 'juxtapose.structure/v1',
+        viewport,
+        structureHash: hashElements(elements),
+        contentHeight: round(doc.contentHeight ?? viewport.height),
+        elements,
+    };
+    if (total > elements.length)
+        snapshot.truncated = { kept: elements.length, total };
+    return snapshot;
+}
+/** Autofill tokens that name a secret: a typed OTP, password or card number
+ *  in a `type=text` field is as sensitive as one in `type=password`. */
+const SECRET_AUTOCOMPLETE = new Set([
+    'one-time-code',
+    'current-password',
+    'new-password',
+]);
+function isSecretInput(a) {
+    if (['password', 'hidden'].includes((a.type ?? '').toLowerCase()))
+        return true;
+    return (a.autocomplete ?? '')
+        .toLowerCase()
+        .split(/\s+/)
+        .some((t) => SECRET_AUTOCOMPLETE.has(t) || t.startsWith('cc-'));
+}
+function implicitRole(tag, a) {
+    if (tag === 'a')
+        return a.href !== undefined ? 'link' : undefined;
+    if (tag === 'input') {
+        const t = (a.type ?? 'text').toLowerCase();
+        return t === 'checkbox' || t === 'radio'
+            ? t
+            : t === 'button' || t === 'submit'
+                ? 'button'
+                : 'textbox';
+    }
+    return IMPLICIT_ROLES[tag];
+}
+/** The filename of a URL: no origin, path, query or hash. The origin changes
+ *  every run (`jux run` serves on port 0) and between machines, so recording
+ *  it would make the same page hash differently each time. */
+function fileName(u) {
+    // A data: URI's "filename" is a slice of its payload: opaque, and as long as
+    // the payload happens to be between slashes.
+    if (/^data:/i.test(u.trim()))
+        return 'data:';
+    return u.split(/[?#]/)[0].split('/').pop() ?? '';
+}
+/** Computed values serialize url() tokens absolute: probe2 recorded
+ *  `url("http://127.0.0.1:41001/bg.png")` vs `...:41002/bg.png` for one page
+ *  on two ports, and two different structureHashes. Keep only the filename. */
+function urlsToFileNames(v) {
+    if (!v.includes('url('))
+        return v;
+    return v.replace(/url\((?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|([^)]*))\)/g, (_m, dq, sq, bare) => `url(${JSON.stringify(fileName((dq ?? sq ?? bare ?? '').trim()))})`);
+}
+const collapse = (s) => s.replace(/\s+/g, ' ').trim();
+/** Computed `content` is a CSS string like `"★"` (quoted), `none`, `normal`,
+ *  or something like `counter(x)`. Return the visible literal text when there
+ *  is one; otherwise the raw value, so a change is still detected. */
+function parseContent(v) {
+    if (!v || v === 'none' || v === 'normal')
+        return '';
+    const m = /^"(.*)"$/.exec(v);
+    return m ? m[1] : v;
+}
+/** The full value of `prop` for element `index`, reconstructing what the
+ *  compact storage omitted. */
+export function effectiveStyle(s, index, prop) {
+    const el = s.elements[index];
+    if (el.styles[prop] !== undefined)
+        return el.styles[prop];
+    if (INHERITED_PROPS.has(prop)) {
+        return el.parent === null
+            ? (ROOT_INHERITED[prop] ?? '')
+            : effectiveStyle(s, el.parent, prop);
+    }
+    if (prop.startsWith('border-') && prop.endsWith('-color')) {
+        return effectiveStyle(s, index, 'color'); // currentColor
+    }
+    return INITIAL_VALUES[prop] ?? '';
+}
+/** Canonical JSON: object keys sorted at every level, so hashing is stable. */
+function canonical(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonical).join(',')}]`;
+    if (v && typeof v === 'object') {
+        const o = v;
+        return `{${Object.keys(o)
+            .sort()
+            .filter((k) => o[k] !== undefined)
+            .map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(v);
+}
+function hashElements(elements) {
+    return createHash('sha256').update(canonical(elements)).digest('hex');
+}
+export function encodeStructure(s) {
+    return gzipSync(Buffer.from(JSON.stringify(s)));
+}
+export function decodeStructure(b) {
+    return JSON.parse(gunzipSync(b).toString('utf8'));
+}
+/**
+ * Snapshot the page's structure. Never throws: a missing structure costs the
+ * agent some explanation, a thrown error would cost the story its capture.
+ *
+ * Mask selectors are resolved with the same CSS-over-open-shadow-roots query
+ * the screenshot masks with; Playwright-only syntax is rejected in
+ * captureStory before anything runs. Matches get MASK_ATTR so the normalizer
+ * collapses their subtree. A plain document.querySelectorAll would miss
+ * matches inside shadow roots and leak masked content into the sidecar.
+ *
+ * Fail closed: if marking fails, or any match lost its mark by the time the
+ * snapshot returns (the page mutated in between), return undefined. Setting an
+ * attribute does not affect paint unless a stylesheet targets it, which
+ * nothing ships with.
+ */
+export async function captureStructure(page, viewport, mask) {
+    const mark = (sel) => page.evaluate(queryAllExpression(sel, "for (const el of els) el.setAttribute(a0, '1'); return els.length;", MASK_ATTR));
+    const verify = (sel) => page.evaluate(queryAllExpression(sel, 'return { total: els.length, marked: els.filter((e) => e.hasAttribute(a0)).length };', MASK_ATTR));
+    const unmark = () => page
+        .evaluate(queryAllExpression(`[${MASK_ATTR}]`, 'for (const el of els) el.removeAttribute(a0);', MASK_ATTR))
+        .catch(() => { });
+    // How many elements each selector marked. Verification re-resolves the
+    // selector, so an element that lost both its mark and its match would drop
+    // out of the re-resolved list and `every` would pass on the survivors
+    // (probe c: SECRET-C recorded). Comparing counts closes that.
+    const markedCounts = [];
+    try {
+        for (const sel of mask) {
+            const n = await mark(sel);
+            markedCounts.push(typeof n === 'number' ? n : 0);
+        }
+    }
+    catch {
+        if (mask.length)
+            await unmark();
+        return undefined;
+    }
+    try {
+        const raw = (await page.send('DOMSnapshot.captureSnapshot', {
+            computedStyles: [...STRUCTURE_PROPS, 'visibility'],
+            includeDOMRects: true,
+            includePaintOrder: true,
+        }));
+        for (const [k, sel] of mask.entries()) {
+            const v = (await verify(sel));
+            // Every current match still marked, and none of the marked ones gone.
+            const intact = typeof v === 'object' &&
+                v !== null &&
+                v.marked === v.total &&
+                v.marked >= markedCounts[k];
+            if (!intact)
+                return undefined;
+        }
+        return normalizeStructure(raw, viewport);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (mask.length)
+            await unmark();
+    }
+}
+//# sourceMappingURL=structure.js.map

package/dist/capture/structure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.js","sourceRoot":"","sources":["../../src/capture/structure.ts"],"names":[],"mappings":"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"}

package/dist/diff/compare.d.ts

@@ -0,0 +1,19 @@
+import type { ChangedRegion, StructureSnapshot, StructuralVerdict } from '../types.js';
+import { type DiffOutput } from './diff.js';
+export interface SnapSide {
+    image: Buffer;
+    structure?: StructureSnapshot;
+}
+export interface SnapComparison {
+    pixels: DiffOutput;
+    verdict: StructuralVerdict;
+    /** Every region no delta explains, in diff order, not the budget-fitted
+     *  prefix on the verdict. `--crops` orders and labels from this. */
+    unexplainedRegions: ChangedRegion[];
+    /** The changed elements' boxes, in delta order: `--crops` falls back to
+     *  these when the pixel diff marked nothing. */
+    elementRegions: ChangedRegion[];
+}
+export declare function compareSnaps(a: SnapSide, b: SnapSide, escalate: {
+    command: string;
+}): Promise<SnapComparison>;

package/dist/diff/compare.js

@@ -0,0 +1,19 @@
+// Two snaps on disk → pixels + verdict. The public seam for `jux diff`: it
+// keeps diffImages and the structural internals unexported while giving the
+// CLI the one call it needs. No browser is involved anywhere below this line.
+import { diffImages } from './diff.js';
+import { structuralDiffWithCoverage } from './structural.js';
+export async function compareSnaps(a, b, escalate) {
+    const pixels = await diffImages(a.image, b.image);
+    const { verdict, unexplainedRegions, elementRegions } = structuralDiffWithCoverage({
+        baseline: a.structure,
+        current: b.structure,
+        // Byte equality, not mismatchPixels === 0: a sub-threshold colour change
+        // has no mismatching pixels but is still a different image.
+        imagesIdentical: a.image.equals(b.image),
+        pixels,
+        escalate,
+    });
+    return { pixels, verdict, unexplainedRegions, elementRegions };
+}
+//# sourceMappingURL=compare.js.map

package/dist/diff/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../src/diff/compare.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,4EAA4E;AAC5E,8EAA8E;AAG9E,OAAO,EAAE,UAAU,EAAmB,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAkB7D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,CAAW,EACX,CAAW,EACX,QAA6B;IAE7B,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,GAAG,0BAA0B,CAAC;QACjF,QAAQ,EAAE,CAAC,CAAC,SAAS;QACrB,OAAO,EAAE,CAAC,CAAC,SAAS;QACpB,yEAAyE;QACzE,4DAA4D;QAC5D,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;QACxC,MAAM;QACN,QAAQ;KACT,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,CAAC;AACjE,CAAC"}