@design-parity/diff 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @design-parity/diff
+
+The source-agnostic diff engine. Consume a `(DesignReference, CandidateRender)`
+pair — from any adapter plus the candidate renderer — and emit a deterministic
+[`Verdict`](../core/src/types.ts), a markdown summary, and a
+reference/candidate/diff triptych per image.
+
+Per [docs/PRINCIPLES.md](../../docs/PRINCIPLES.md): the engine runs **only
+committed, deterministic rules/config — no model calls at run time**, and the
+verdict **leads with a11y + i18n**, then token compliance, then the raw visual
+diff.
+
+## Use
+
+```ts
+import { diff } from "@design-parity/diff";
+
+const { verdict, summary, triptychs } = await diff(reference, candidate, {
+  repoRoot,          // image `uri`s resolve against this (default: cwd)
+  outDir: "out",     // optional: write triptych-<key>.png here
+  // config: { spacingTolerance: 0, pixelThreshold: 0.05, ... },
+  // checksConfig: { contrastLevel: "AAA" },  // a11y/i18n thresholds
+  // checks: myProvider,   // swap the default @design-parity/checks provider
+});
+```
+
+`verdict.status` is `pass | warn | fail` (any `error` finding ⇒ `fail`); findings
+are ordered a11y → token → semantic → visual; `verdict.visualScores` maps each
+`state/theme/size` key to its differing-pixel fraction.
+
+## Dimensions
+
+- **a11y + i18n** — delegated to [`@design-parity/checks`](../checks) (#10)
+  through a [`ChecksProvider`](./src/checks.ts) seam: WCAG contrast, touch
+  targets, semantic roles/labels, and i18n risks. `defaultChecks` wires the real
+  package; inject a custom provider (or `checksConfig`) to override.
+- **Token compliance** — flatten the candidate's tree tokens and compare against
+  the reference spec: numeric tokens honour a committed tolerance, colours and
+  typography must match exactly.
+- **Semantics** — theme-coverage and structural (role/label) deltas.
+- **Visual** — per-pixel diff via `pixelmatch`, plus the triptych.
+
+Everything is committed config (see [`config.ts`](./src/config.ts)); the same
+pair always yields the same verdict.
+
+## Develop
+
+```sh
+npm run build --workspace @design-parity/diff
+npm test --workspace @design-parity/diff
+```

package/dist/checks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Accessibility + i18n checks — the highest-value signal (Principle 2), so the
+ * verdict leads with them.
+ *
+ * These checks are owned by `@design-parity/checks` (issue #10), which has
+ * landed: the {@link defaultChecks} provider delegates straight to its
+ * `runChecks`. The {@link ChecksProvider} seam stays so a consumer can inject a
+ * stricter config or a future provider without the diff engine changing — but
+ * the default is the real package, not a stub.
+ */
+import { type ChecksConfig } from "@design-parity/checks";
+import type { CandidateRender, DesignReference, Finding } from "@design-parity/core";
+/** What an a11y/i18n check provider receives. Source-agnostic by construction. */
+export interface ChecksInput {
+    reference: DesignReference;
+    candidate: CandidateRender;
+    /** Committed thresholds/levels passed through to the provider. */
+    config: ChecksConfig;
+}
+/**
+ * The a11y + i18n seam. An implementation inspects the candidate (never a live
+ * model) and returns deterministic findings. Async is allowed so a heavier
+ * provider can read files, but it must not depend on network or a model at run
+ * time.
+ */
+export interface ChecksProvider {
+    run(input: ChecksInput): Finding[] | Promise<Finding[]>;
+}
+/**
+ * The default provider: `@design-parity/checks` (#10). Deterministic, offline,
+ * and committed — WCAG contrast, touch targets, semantic roles/labels, plus the
+ * i18n risks (text expansion, RTL, hardcoded strings).
+ */
+export declare const defaultChecks: ChecksProvider;
+export type { ChecksConfig };
+//# sourceMappingURL=checks.d.ts.map

package/dist/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../src/checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,OAAO,EACR,MAAM,qBAAqB,CAAC;AAE7B,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,CAAC;IAC3B,SAAS,EAAE,eAAe,CAAC;IAC3B,kEAAkE;IAClE,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACzD;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,cAI3B,CAAC;AAEF,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/checks.js

@@ -0,0 +1,22 @@
+/**
+ * Accessibility + i18n checks — the highest-value signal (Principle 2), so the
+ * verdict leads with them.
+ *
+ * These checks are owned by `@design-parity/checks` (issue #10), which has
+ * landed: the {@link defaultChecks} provider delegates straight to its
+ * `runChecks`. The {@link ChecksProvider} seam stays so a consumer can inject a
+ * stricter config or a future provider without the diff engine changing — but
+ * the default is the real package, not a stub.
+ */
+import { runChecks } from "@design-parity/checks";
+/**
+ * The default provider: `@design-parity/checks` (#10). Deterministic, offline,
+ * and committed — WCAG contrast, touch targets, semantic roles/labels, plus the
+ * i18n risks (text expansion, RTL, hardcoded strings).
+ */
+export const defaultChecks = {
+    run({ reference, candidate, config }) {
+        return runChecks(reference, candidate, config);
+    },
+};
+//# sourceMappingURL=checks.js.map

package/dist/checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.js","sourceRoot":"","sources":["../src/checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAqB,MAAM,uBAAuB,CAAC;AAyBrE;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,GAAG,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAe;QAC/C,OAAO,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;CACF,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Diff thresholds and rules.
+ *
+ * Per docs/PRINCIPLES.md (Principle 1) every threshold the engine uses is
+ * committed config, never inferred at run time. A consumer overrides any field;
+ * the rest fall back to {@link defaultDiffConfig}. The same config in → the same
+ * verdict out.
+ *
+ * a11y + i18n thresholds (contrast levels, touch-target sizes, expansion
+ * factors) are *not* here — they belong to `@design-parity/checks` and are
+ * configured through {@link DiffOptions.checksConfig}.
+ */
+export interface DiffConfig {
+    /** Max allowed absolute delta (dp/px) for a spacing token before it fails. */
+    spacingTolerance: number;
+    /** Max allowed absolute delta (dp/px) for a radius token before it fails. */
+    radiusTolerance: number;
+    /**
+     * pixelmatch per-pixel matching threshold (0 strict … 1 loose). Pixels whose
+     * colour distance exceeds this fraction are counted as differing. Tighter
+     * than pixelmatch's 0.1 default so a visible theme-colour drift registers.
+     */
+    pixelThreshold: number;
+    /**
+     * Fraction of differing pixels (0…1) above which an image pair raises a
+     * visual finding. Visual diff is the least-valuable signal (Principle 2), so
+     * it never escalates past `warn`.
+     */
+    visualWarnRatio: number;
+    /**
+     * Max per-axis dimension delta (px) between reference and candidate that is
+     * still diffed as an aligned overlap rather than scored a 100% mismatch. Two
+     * render tools rounding density differently (e.g. Robolectric 2.625 vs a
+     * `deviceScaleFactor=2` capture) can differ by a pixel or two without any real
+     * visual drift; tolerating that keeps the heatmap informative (#47). A delta
+     * beyond this on either axis is a genuine total mismatch.
+     */
+    visualDimTolerancePx: number;
+}
+/** The committed defaults: exact-match tokens, sensitive visual diff. */
+export declare const defaultDiffConfig: DiffConfig;
+/** Merge a partial override over the committed defaults. */
+export declare function resolveConfig(override?: Partial<DiffConfig>): DiffConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,EAAE,UAM/B,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAGxE"}

package/dist/config.js

@@ -0,0 +1,27 @@
+/**
+ * Diff thresholds and rules.
+ *
+ * Per docs/PRINCIPLES.md (Principle 1) every threshold the engine uses is
+ * committed config, never inferred at run time. A consumer overrides any field;
+ * the rest fall back to {@link defaultDiffConfig}. The same config in → the same
+ * verdict out.
+ *
+ * a11y + i18n thresholds (contrast levels, touch-target sizes, expansion
+ * factors) are *not* here — they belong to `@design-parity/checks` and are
+ * configured through {@link DiffOptions.checksConfig}.
+ */
+/** The committed defaults: exact-match tokens, sensitive visual diff. */
+export const defaultDiffConfig = {
+    spacingTolerance: 0,
+    radiusTolerance: 0,
+    pixelThreshold: 0.05,
+    visualWarnRatio: 0,
+    visualDimTolerancePx: 8,
+};
+/** Merge a partial override over the committed defaults. */
+export function resolveConfig(override) {
+    if (!override)
+        return defaultDiffConfig;
+    return { ...defaultDiffConfig, ...override };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA8BH,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAe;IAC3C,gBAAgB,EAAE,CAAC;IACnB,eAAe,EAAE,CAAC;IAClB,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,CAAC;IAClB,oBAAoB,EAAE,CAAC;CACxB,CAAC;AAEF,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,QAA8B;IAC1D,IAAI,CAAC,QAAQ;QAAE,OAAO,iBAAiB,CAAC;IACxC,OAAO,EAAE,GAAG,iBAAiB,EAAE,GAAG,QAAQ,EAAE,CAAC;AAC/C,CAAC"}

package/dist/diff.d.ts

@@ -0,0 +1,48 @@
+import type { CandidateRender, DesignReference, Verdict } from "@design-parity/core";
+import { type ChecksConfig, type ChecksProvider } from "./checks.js";
+import { type DiffConfig } from "./config.js";
+export interface DiffOptions {
+    /** Repo root the image `uri`s resolve against. Defaults to `process.cwd()`. */
+    repoRoot?: string;
+    /** Threshold/rule overrides; unset fields use the committed defaults. */
+    config?: Partial<DiffConfig>;
+    /**
+     * a11y + i18n provider. Defaults to {@link defaultChecks}, which delegates to
+     * `@design-parity/checks` (#10). Inject to swap in a custom provider.
+     */
+    checks?: ChecksProvider;
+    /** Committed a11y/i18n thresholds passed to the checks provider. */
+    checksConfig?: ChecksConfig;
+    /**
+     * If set, triptych PNGs are written here as `triptych-<key>.png` and their
+     * paths land in {@link DiffResult.triptychs}. Omit to skip disk writes; the
+     * buffers are still returned.
+     */
+    outDir?: string;
+}
+/** A rendered triptych for one image pair. */
+export interface Triptych {
+    /** `state/theme/size` key, shared with {@link Verdict.visualScores}. */
+    key: string;
+    png: Buffer;
+    /** Absolute path, present only when {@link DiffOptions.outDir} was set. */
+    path?: string;
+    /**
+     * The standalone diff heatmap PNG for this pair (the pixelmatch panel only),
+     * so a consumer laying out its own columns can inline it — e.g. the HTML
+     * report (#50). Absent when there was no aligned region to diff.
+     */
+    diff?: Buffer;
+}
+export interface DiffResult {
+    verdict: Verdict;
+    /** Markdown summary for the PR surface. */
+    summary: string;
+    triptychs: Triptych[];
+}
+/**
+ * Run the full parity diff. Resolves images, runs every dimension, orders the
+ * findings by value, and returns the verdict, its markdown, and the triptychs.
+ */
+export declare function diff(reference: DesignReference, candidate: CandidateRender, options?: DiffOptions): Promise<DiffResult>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAGf,OAAO,EAER,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAa7D,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,oEAAoE;IACpE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,EAAE,CAAC;CACvB;AAuDD;;;GAGG;AACH,wBAAsB,IAAI,CACxB,SAAS,EAAE,eAAe,EAC1B,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CA6ErB"}

package/dist/diff.js

@@ -0,0 +1,152 @@
+/**
+ * The diff engine entry point: consume a `(DesignReference, CandidateRender)`
+ * pair and emit a deterministic {@link Verdict} plus a human summary and the
+ * visual triptychs.
+ *
+ * Findings are assembled in value order (Principle 2): a11y + i18n (the checks
+ * provider) → token compliance → semantics → visual. No network, no model, no
+ * clock — the same pair always yields the same verdict (Principle 1).
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { defaultChecks, } from "./checks.js";
+import { resolveConfig } from "./config.js";
+import { diffSemantics } from "./semantic.js";
+import { renderSummary } from "./summary.js";
+import { collectTokens, diffTokens } from "./tokens.js";
+import { diffImagePair, imageKey, looseKey, pairKey, sizeCompatible, } from "./visual.js";
+/**
+ * Pair candidate images to reference images. Exact `state/theme/normalized-size`
+ * first (so `"Compact"`/`"600dp"`/`"compact"` line up); then a size-tolerant
+ * fallback by `state/theme` when one side omits/uses an unknown size. Two
+ * *different known* sizes never pair. Reference variants left over are reported
+ * rather than silently dropped.
+ */
+function pairImages(reference, candidate) {
+    const exact = new Map();
+    for (const i of candidate.images) {
+        if (!exact.has(pairKey(i)))
+            exact.set(pairKey(i), i);
+    }
+    const used = new Set();
+    const pairs = [];
+    const unmatched = [];
+    for (const ref of reference.referenceImages) {
+        let cand = exact.get(pairKey(ref));
+        if (cand && used.has(cand))
+            cand = undefined;
+        if (!cand) {
+            cand = candidate.images.find((c) => !used.has(c) &&
+                looseKey(c) === looseKey(ref) &&
+                sizeCompatible(ref, c));
+        }
+        if (cand) {
+            used.add(cand);
+            pairs.push({ reference: ref, candidate: cand });
+        }
+        else {
+            unmatched.push(ref);
+        }
+    }
+    return { pairs, unmatched };
+}
+function statusFor(findings) {
+    if (findings.some((f) => f.severity === "error"))
+        return "fail";
+    if (findings.some((f) => f.severity === "warn"))
+        return "warn";
+    return "pass";
+}
+/**
+ * Run the full parity diff. Resolves images, runs every dimension, orders the
+ * findings by value, and returns the verdict, its markdown, and the triptychs.
+ */
+export async function diff(reference, candidate, options = {}) {
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const config = resolveConfig(options.config);
+    const checks = options.checks ?? defaultChecks;
+    const candidateTokens = collectTokens(candidate.semantics.root);
+    // 1. a11y + i18n (highest value, leads the verdict).
+    const a11y = await checks.run({
+        reference,
+        candidate,
+        config: options.checksConfig ?? {},
+    });
+    // 2. token compliance.
+    const tokens = diffTokens(reference.tokens, candidateTokens, config);
+    // 3. semantics (+ reference variants with no candidate counterpart).
+    const semantic = diffSemantics(reference, candidate);
+    const { pairs, unmatched } = pairImages(reference, candidate);
+    const candidateThemes = new Set(candidate.images.map((i) => i.theme).filter(Boolean));
+    for (const ref of unmatched) {
+        // A wholly-missing theme is already reported by diffSemantics; only flag
+        // finer gaps (a missing size/state within a theme the candidate renders).
+        if (ref.theme && !candidateThemes.has(ref.theme))
+            continue;
+        semantic.push({
+            kind: "semantic",
+            severity: "warn",
+            message: `reference variant '${imageKey(ref)}' has no candidate render to compare`,
+            detail: { variant: imageKey(ref) },
+        });
+    }
+    // 4. visual diff (table stakes).
+    const visuals = [];
+    for (const pair of pairs) {
+        visuals.push(await diffImagePair(repoRoot, pair.reference, pair.candidate, config));
+    }
+    const visualScores = {};
+    const visualFindings = [];
+    for (const v of visuals) {
+        visualScores[v.key] = round(v.score);
+        if (v.dimensionMismatch) {
+            // The pair was diffed over its overlap after a sub-tolerance size delta;
+            // note it so the reviewer knows the score is an aligned comparison (#47).
+            visualFindings.push({
+                kind: "visual",
+                severity: "info",
+                message: `${v.key}: reference and candidate differ slightly in size; compared over their overlap`,
+                detail: { key: v.key },
+            });
+        }
+        if (v.score > config.visualWarnRatio) {
+            visualFindings.push({
+                kind: "visual",
+                severity: "warn",
+                message: `${v.key}: ${(v.score * 100).toFixed(1)}% of pixels differ from reference`,
+                detail: { key: v.key, score: round(v.score), diffPixels: v.diffPixels },
+            });
+        }
+    }
+    const findings = [...a11y, ...tokens, ...semantic, ...visualFindings];
+    const verdict = {
+        componentId: candidate.componentId,
+        status: statusFor(findings),
+        findings,
+        visualScores,
+    };
+    const triptychs = await emitTriptychs(visuals, options.outDir);
+    return { verdict, summary: renderSummary(verdict), triptychs };
+}
+async function emitTriptychs(visuals, outDir) {
+    if (outDir)
+        await mkdir(outDir, { recursive: true });
+    const out = [];
+    for (const v of visuals) {
+        const safeKey = v.key.replace(/[^a-z0-9]+/gi, "-");
+        const triptych = { key: v.key, png: v.triptych };
+        if (v.diffPng)
+            triptych.diff = v.diffPng;
+        if (outDir) {
+            const path = join(outDir, `triptych-${safeKey}.png`);
+            await writeFile(path, v.triptych);
+            triptych.path = path;
+        }
+        out.push(triptych);
+    }
+    return out;
+}
+function round(n) {
+    return Math.round(n * 1e6) / 1e6;
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@design-parity/diff` — the source-agnostic diff engine.
+ *
+ * Consume a `(DesignReference, CandidateRender)` pair (from any adapter +
+ * the candidate renderer) and emit a deterministic {@link Verdict}, a markdown
+ * summary, and reference/candidate/diff triptychs. a11y + i18n lead; tokens,
+ * semantics, and raw visual diff follow (docs/PRINCIPLES.md).
+ */
+export { diff } from "./diff.js";
+export type { DiffOptions, DiffResult, Triptych } from "./diff.js";
+export { defaultDiffConfig, resolveConfig } from "./config.js";
+export type { DiffConfig } from "./config.js";
+export { defaultChecks } from "./checks.js";
+export type { ChecksProvider, ChecksInput, ChecksConfig } from "./checks.js";
+export { collectTokens, diffTokens } from "./tokens.js";
+export { diffSemantics, referenceThemes, candidateThemes } from "./semantic.js";
+export { diffImagePair, imageKey } from "./visual.js";
+export type { VisualResult } from "./visual.js";
+export { renderSummary } from "./summary.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEnE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@design-parity/diff` — the source-agnostic diff engine.
+ *
+ * Consume a `(DesignReference, CandidateRender)` pair (from any adapter +
+ * the candidate renderer) and emit a deterministic {@link Verdict}, a markdown
+ * summary, and reference/candidate/diff triptychs. a11y + i18n lead; tokens,
+ * semantics, and raw visual diff follow (docs/PRINCIPLES.md).
+ */
+export { diff } from "./diff.js";
+export { defaultDiffConfig, resolveConfig } from "./config.js";
+export { defaultChecks } from "./checks.js";
+export { collectTokens, diffTokens } from "./tokens.js";
+export { diffSemantics, referenceThemes, candidateThemes } from "./semantic.js";
+export { diffImagePair, imageKey } from "./visual.js";
+export { renderSummary } from "./summary.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG/D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/semantic.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Semantic diff: structural / theme deltas between reference and candidate.
+ *
+ * A {@link DesignReference} carries images + tokens but no semantic tree, so the
+ * deltas we can assert deterministically are coverage-shaped: does the candidate
+ * render every theme the reference exposes, and is its root node a labelled,
+ * roled element (the minimum an a11y tree needs)? Deeper a11y lives in the
+ * checks provider (issue #10).
+ */
+import type { CandidateRender, DesignReference, Finding, Theme } from "@design-parity/core";
+/** Themes the reference exposes, in first-seen order. */
+export declare function referenceThemes(reference: DesignReference): Theme[];
+/** Themes the candidate renders, in first-seen order. */
+export declare function candidateThemes(candidate: CandidateRender): Theme[];
+export declare function diffSemantics(reference: DesignReference, candidate: CandidateRender): Finding[];
+//# sourceMappingURL=semantic.d.ts.map

package/dist/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../src/semantic.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,OAAO,EACP,KAAK,EACN,MAAM,qBAAqB,CAAC;AAE7B,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,SAAS,EAAE,eAAe,GAAG,KAAK,EAAE,CAEnE;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,SAAS,EAAE,eAAe,GAAG,KAAK,EAAE,CAEnE;AAUD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,eAAe,EAC1B,SAAS,EAAE,eAAe,GACzB,OAAO,EAAE,CAkCX"}

package/dist/semantic.js

@@ -0,0 +1,49 @@
+/** Themes the reference exposes, in first-seen order. */
+export function referenceThemes(reference) {
+    return uniqueThemes(reference.referenceImages.map((i) => i.theme));
+}
+/** Themes the candidate renders, in first-seen order. */
+export function candidateThemes(candidate) {
+    return uniqueThemes(candidate.images.map((i) => i.theme));
+}
+function uniqueThemes(themes) {
+    const out = [];
+    for (const t of themes) {
+        if (t && !out.includes(t))
+            out.push(t);
+    }
+    return out;
+}
+export function diffSemantics(reference, candidate) {
+    const findings = [];
+    const have = candidateThemes(candidate);
+    for (const theme of referenceThemes(reference)) {
+        if (!have.includes(theme)) {
+            findings.push({
+                kind: "semantic",
+                severity: "warn",
+                message: `reference exposes a ${theme} theme the candidate does not render`,
+                detail: { theme, missing: "candidate-image" },
+            });
+        }
+    }
+    const root = candidate.semantics.root;
+    if (!root.role) {
+        findings.push({
+            kind: "semantic",
+            severity: "warn",
+            message: "candidate root node has no accessibility role",
+            detail: { node: "root", field: "role" },
+        });
+    }
+    if (!root.label) {
+        findings.push({
+            kind: "semantic",
+            severity: "warn",
+            message: "candidate root node has no accessible label",
+            detail: { node: "root", field: "label" },
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=semantic.js.map

package/dist/semantic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../src/semantic.ts"],"names":[],"mappings":"AAgBA,yDAAyD;AACzD,MAAM,UAAU,eAAe,CAAC,SAA0B;IACxD,OAAO,YAAY,CAAC,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,eAAe,CAAC,SAA0B;IACxD,OAAO,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,YAAY,CAAC,MAAgC;IACpD,MAAM,GAAG,GAAY,EAAE,CAAC;IACxB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,SAA0B,EAC1B,SAA0B;IAE1B,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,MAAM,IAAI,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE,MAAM;gBAChB,OAAO,EAAE,uBAAuB,KAAK,sCAAsC;gBAC3E,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE;aAC9C,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC;IACtC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACf,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,+CAA+C;YACxD,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE;SACxC,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,6CAA6C;YACtD,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE;SACzC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/summary.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Human-readable markdown summary of a {@link Verdict}.
+ *
+ * The machine `Verdict` is for downstream consumers; this is what a reviewer
+ * reads in the PR comment. Sections are ordered by value (Principle 2):
+ * a11y + i18n first, then tokens, then semantics, then the visual diff.
+ */
+import type { Verdict } from "@design-parity/core";
+/** Render a verdict as a self-contained markdown block. */
+export declare function renderSummary(verdict: Verdict): string;
+//# sourceMappingURL=summary.d.ts.map

package/dist/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAsBzE,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CA8BtD"}

package/dist/summary.js

@@ -0,0 +1,38 @@
+const STATUS_ICON = { pass: "✅", warn: "⚠️", fail: "❌" };
+const SEVERITY_ICON = { info: "ℹ️", warn: "⚠️", error: "❌" };
+// a11y + i18n lead (Principle 2); contrast/a11y/i18n are the checks signals.
+const SECTIONS = [
+    { title: "Accessibility & i18n", kinds: ["contrast", "a11y", "i18n"] },
+    { title: "Token compliance", kinds: ["token"] },
+    { title: "Semantics", kinds: ["semantic"] },
+    { title: "Visual", kinds: ["visual"] },
+];
+function renderFinding(f) {
+    return `- ${SEVERITY_ICON[f.severity]} ${f.message}`;
+}
+/** Render a verdict as a self-contained markdown block. */
+export function renderSummary(verdict) {
+    const lines = [
+        `## Parity verdict: \`${verdict.componentId}\` — ${STATUS_ICON[verdict.status]} ${verdict.status}`,
+    ];
+    for (const section of SECTIONS) {
+        const matched = verdict.findings.filter((f) => section.kinds.includes(f.kind));
+        if (matched.length === 0)
+            continue;
+        lines.push("", `**${section.title}**`, ...matched.map(renderFinding));
+    }
+    const scores = verdict.visualScores;
+    if (scores && Object.keys(scores).length > 0) {
+        const detail = Object.entries(scores)
+            .map(([key, score]) => score === 0
+            ? `\`${key}\` match`
+            : `\`${key}\` ${(score * 100).toFixed(1)}% differ`)
+            .join(", ");
+        lines.push("", `_Visual diff: ${detail}._`);
+    }
+    if (verdict.findings.length === 0) {
+        lines.push("", "No parity findings — candidate matches the reference spec.");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=summary.js.map

package/dist/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAW,CAAC;AAClE,MAAM,aAAa,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAW,CAAC;AAOtE,6EAA6E;AAC7E,MAAM,QAAQ,GAAc;IAC1B,EAAE,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;IACtE,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE;IAC/C,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE;IAC3C,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,EAAE;CACvC,CAAC;AAEF,SAAS,aAAa,CAAC,CAAU;IAC/B,OAAO,KAAK,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;AACvD,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,KAAK,GAAa;QACtB,wBAAwB,OAAO,CAAC,WAAW,QAAQ,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE;KACnG,CAAC;IAEF,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC5C,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAC/B,CAAC;QACF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,OAAO,CAAC,KAAK,IAAI,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IACpC,IAAI,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;aAClC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CACpB,KAAK,KAAK,CAAC;YACT,CAAC,CAAC,KAAK,GAAG,UAAU;YACpB,CAAC,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CACrD;aACA,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,iBAAiB,MAAM,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,4DAA4D,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/tokens.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Token collection + token-compliance diff.
+ *
+ * A {@link DesignReference} carries one flat {@link DesignTokens} bag; a
+ * {@link CandidateRender} scatters tokens across its semantic tree. We flatten
+ * the candidate's tree into the same shape, then compare key-by-key against the
+ * reference spec. Numeric tokens honour a committed tolerance; colours and
+ * typography must match exactly.
+ */
+import type { DesignTokens, Finding, SemanticNode } from "@design-parity/core";
+import type { DiffConfig } from "./config.js";
+/** Deep-merge every node's tokens into one flat bag (children override parents). */
+export declare function collectTokens(root: SemanticNode): DesignTokens;
+/**
+ * Compare candidate tokens against the reference spec. Findings are emitted in
+ * a stable order — spacing, radius, colours, typography — so the verdict is
+ * reproducible. A reference token absent from the candidate is a `missing`
+ * finding; tokens the candidate adds beyond the spec are ignored.
+ */
+export declare function diffTokens(spec: DesignTokens | undefined, candidate: DesignTokens, config: DiffConfig): Finding[];
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EACV,YAAY,EACZ,OAAO,EACP,YAAY,EAEb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAQ9D;AAqBD;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,YAAY,GAAG,SAAS,EAC9B,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,UAAU,GACjB,OAAO,EAAE,CAuCX"}

package/dist/tokens.js

@@ -0,0 +1,102 @@
+/** Deep-merge every node's tokens into one flat bag (children override parents). */
+export function collectTokens(root) {
+    const out = {};
+    const visit = (node) => {
+        mergeInto(out, node.tokens);
+        for (const child of node.children ?? [])
+            visit(child);
+    };
+    visit(root);
+    return out;
+}
+function mergeInto(target, src) {
+    if (!src)
+        return;
+    if (src.spacing)
+        target.spacing = { ...target.spacing, ...src.spacing };
+    if (src.radius)
+        target.radius = { ...target.radius, ...src.radius };
+    if (src.colors)
+        target.colors = { ...target.colors, ...src.colors };
+    if (src.typography)
+        target.typography = { ...target.typography, ...src.typography };
+}
+function typographyEqual(a, b) {
+    return (a.fontFamily === b.fontFamily &&
+        a.fontSize === b.fontSize &&
+        a.fontWeight === b.fontWeight &&
+        a.lineHeight === b.lineHeight &&
+        a.letterSpacing === b.letterSpacing);
+}
+/**
+ * Compare candidate tokens against the reference spec. Findings are emitted in
+ * a stable order — spacing, radius, colours, typography — so the verdict is
+ * reproducible. A reference token absent from the candidate is a `missing`
+ * finding; tokens the candidate adds beyond the spec are ignored.
+ */
+export function diffTokens(spec, candidate, config) {
+    const findings = [];
+    if (!spec)
+        return findings;
+    for (const [name, want] of Object.entries(spec.spacing ?? {})) {
+        const got = candidate.spacing?.[name];
+        numericFinding("spacing", name, want, got, config.spacingTolerance, findings);
+    }
+    for (const [name, want] of Object.entries(spec.radius ?? {})) {
+        const got = candidate.radius?.[name];
+        numericFinding("radius", name, want, got, config.radiusTolerance, findings);
+    }
+    for (const [name, want] of Object.entries(spec.colors ?? {})) {
+        const got = candidate.colors?.[name];
+        if (got === undefined) {
+            findings.push(missing("colors", name, want));
+        }
+        else if (got.toLowerCase() !== want.toLowerCase()) {
+            findings.push({
+                kind: "token",
+                severity: "warn",
+                message: `colors.${name}: ${got} vs spec ${want}`,
+                detail: { token: `colors.${name}`, expected: want, actual: got },
+            });
+        }
+    }
+    for (const [name, want] of Object.entries(spec.typography ?? {})) {
+        const got = candidate.typography?.[name];
+        if (got === undefined) {
+            findings.push(missing("typography", name, JSON.stringify(want)));
+        }
+        else if (!typographyEqual(want, got)) {
+            findings.push({
+                kind: "token",
+                severity: "warn",
+                message: `typography.${name} differs from spec`,
+                detail: { token: `typography.${name}`, expected: want, actual: got },
+            });
+        }
+    }
+    return findings;
+}
+function numericFinding(group, name, want, got, tolerance, findings) {
+    if (got === undefined) {
+        findings.push(missing(group, name, String(want)));
+        return;
+    }
+    const delta = Math.abs(got - want);
+    if (delta > tolerance) {
+        findings.push({
+            kind: "token",
+            severity: "error",
+            message: `${group}.${name}: ${got} vs spec ${want} (Δ${delta})`,
+            detail: { token: `${group}.${name}`, expected: want, actual: got, delta },
+        });
+    }
+}
+function missing(group, name, want) {
+    return {
+        kind: "token",
+        severity: "error",
+        message: `${group}.${name} missing from candidate (spec ${want})`,
+        detail: { token: `${group}.${name}`, expected: want, actual: null },
+    };
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAkBA,oFAAoF;AACpF,MAAM,UAAU,aAAa,CAAC,IAAkB;IAC9C,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,CAAC,IAAkB,EAAQ,EAAE;QACzC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE;YAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACxD,CAAC,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,CAAC;IACZ,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,SAAS,CAAC,MAAoB,EAAE,GAAkB;IACzD,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,IAAI,GAAG,CAAC,OAAO;QAAE,MAAM,CAAC,OAAO,GAAG,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;IACxE,IAAI,GAAG,CAAC,MAAM;QAAE,MAAM,CAAC,MAAM,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;IACpE,IAAI,GAAG,CAAC,MAAM;QAAE,MAAM,CAAC,MAAM,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;IACpE,IAAI,GAAG,CAAC,UAAU;QAChB,MAAM,CAAC,UAAU,GAAG,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,GAAG,GAAG,CAAC,UAAU,EAAE,CAAC;AACpE,CAAC;AAED,SAAS,eAAe,CAAC,CAAkB,EAAE,CAAkB;IAC7D,OAAO,CACL,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;QAC7B,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;QACzB,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;QAC7B,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;QAC7B,CAAC,CAAC,aAAa,KAAK,CAAC,CAAC,aAAa,CACpC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,IAA8B,EAC9B,SAAuB,EACvB,MAAkB;IAElB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAE3B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;QACtC,cAAc,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;IAChF,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QAC7D,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACrC,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC9E,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QAC7D,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;aAAM,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACpD,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,MAAM;gBAChB,OAAO,EAAE,UAAU,IAAI,KAAK,GAAG,YAAY,IAAI,EAAE;gBACjD,MAAM,EAAE,EAAE,KAAK,EAAE,UAAU,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;aACjE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC;QACjE,MAAM,GAAG,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACnE,CAAC;aAAM,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YACvC,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,MAAM;gBAChB,OAAO,EAAE,cAAc,IAAI,oBAAoB;gBAC/C,MAAM,EAAE,EAAE,KAAK,EAAE,cAAc,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;aACrE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,cAAc,CACrB,KAA2B,EAC3B,IAAY,EACZ,IAAY,EACZ,GAAuB,EACvB,SAAiB,EACjB,QAAmB;IAEnB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClD,OAAO;IACT,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IACnC,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,OAAO;YACb,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,GAAG,KAAK,IAAI,IAAI,KAAK,GAAG,YAAY,IAAI,MAAM,KAAK,GAAG;YAC/D,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE;SAC1E,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,KAAa,EAAE,IAAY,EAAE,IAAY;IACxD,OAAO;QACL,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,GAAG,KAAK,IAAI,IAAI,iCAAiC,IAAI,GAAG;QACjE,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;KACpE,CAAC;AACJ,CAAC"}

package/dist/visual.d.ts

@@ -0,0 +1,44 @@
+import { type Image } from "@design-parity/core";
+import type { DiffConfig } from "./config.js";
+/** The result of comparing one reference image against its candidate twin. */
+export interface VisualResult {
+    /** `state/theme/size` key shared with {@link Verdict.visualScores}. */
+    key: string;
+    /** Fraction of differing pixels, 0 (identical) … 1. */
+    score: number;
+    diffPixels: number;
+    totalPixels: number;
+    /** Side-by-side reference | candidate | diff PNG. */
+    triptych: Buffer;
+    /**
+     * The standalone diff heatmap PNG (just the pixelmatch panel), for consumers
+     * that lay out their own reference/candidate columns — e.g. the HTML report
+     * (#50). Absent when there was no aligned region to diff (a beyond-tolerance
+     * dimension mismatch).
+     */
+    diffPng?: Buffer;
+    /**
+     * True when reference and candidate had different dimensions but within
+     * {@link DiffConfig.visualDimTolerancePx}, so they were diffed over their
+     * top-left overlap rather than scored a total mismatch (#47).
+     */
+    dimensionMismatch?: boolean;
+}
+/** Human-readable key (raw size) — also the {@link Verdict.visualScores} key. */
+export declare function imageKey(img: Image): string;
+/**
+ * Pairing key with the size normalized, so `"Compact"` / `"compact"` / `"600dp"`
+ * all match. Differs from {@link imageKey} (which keeps the raw label for humans).
+ */
+export declare function pairKey(img: Image): string;
+/** Looser key ignoring size — used to pair when a side omits/uses an unknown size. */
+export declare function looseKey(img: Image): string;
+/**
+ * Whether two images may pair despite different size labels: compatible when at
+ * least one side has no recognized size, or both canonicalize to the same one.
+ * Two *different* known sizes (compact vs expanded) are genuinely distinct.
+ */
+export declare function sizeCompatible(a: Image, b: Image): boolean;
+/** Compare one matched pair, returning its score and triptych. */
+export declare function diffImagePair(repoRoot: string, reference: Image, candidate: Image, config: DiffConfig): Promise<VisualResult>;
+//# sourceMappingURL=visual.d.ts.map

package/dist/visual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual.d.ts","sourceRoot":"","sources":["../src/visual.ts"],"names":[],"mappings":"AAWA,OAAO,EAAiB,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAIhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAW9C,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAE3C;AAOD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAE1C;AAED,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAI1D;AAsBD,kEAAkE;AAClE,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,KAAK,EAChB,SAAS,EAAE,KAAK,EAChB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,YAAY,CAAC,CAqDvB"}

package/dist/visual.js

@@ -0,0 +1,156 @@
+/**
+ * Visual diff: per-pixel comparison + the reference/candidate/diff triptych.
+ *
+ * pixelmatch gives a deterministic differing-pixel count (Principle 1); the
+ * triptych is a single PNG that stacks reference, candidate, and the pixelmatch
+ * heatmap side by side so a reviewer sees what moved. Visual diff is table
+ * stakes (Principle 2) — it informs, it never gates.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { normalizeSize } from "@design-parity/core";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+const GAP = 8;
+const GAP_RGBA = [0x1f, 0x1f, 0x24, 0xff];
+/** Human-readable key (raw size) — also the {@link Verdict.visualScores} key. */
+export function imageKey(img) {
+    return [img.state, img.theme, img.size].filter(Boolean).join("/");
+}
+/** The size token used for pairing: canonical when recognized, else the raw label. */
+function sizeToken(img) {
+    return normalizeSize(img.size) ?? img.size?.toLowerCase();
+}
+/**
+ * Pairing key with the size normalized, so `"Compact"` / `"compact"` / `"600dp"`
+ * all match. Differs from {@link imageKey} (which keeps the raw label for humans).
+ */
+export function pairKey(img) {
+    return [img.state, img.theme, sizeToken(img)].filter(Boolean).join("/");
+}
+/** Looser key ignoring size — used to pair when a side omits/uses an unknown size. */
+export function looseKey(img) {
+    return [img.state, img.theme].filter(Boolean).join("/");
+}
+/**
+ * Whether two images may pair despite different size labels: compatible when at
+ * least one side has no recognized size, or both canonicalize to the same one.
+ * Two *different* known sizes (compact vs expanded) are genuinely distinct.
+ */
+export function sizeCompatible(a, b) {
+    const ca = normalizeSize(a.size);
+    const cb = normalizeSize(b.size);
+    return ca === undefined || cb === undefined || ca === cb;
+}
+/** Decode a `data:<mediatype>;base64,<payload>` URI to its raw bytes. */
+function decodeDataUri(uri) {
+    const comma = uri.indexOf(",");
+    const meta = comma === -1 ? "" : uri.slice("data:".length, comma);
+    if (!/;base64$/i.test(meta)) {
+        throw new Error(`visual: unsupported data: URI (expected base64): ${meta}`);
+    }
+    return Buffer.from(uri.slice(comma + 1), "base64");
+}
+async function readRaster(repoRoot, uri) {
+    // A source may hand us the PNG inline as a `data:` URI (e.g. a `.zip` bundle,
+    // which has no standalone repo file); decode it rather than reading from disk.
+    const buf = uri.startsWith("data:")
+        ? decodeDataUri(uri)
+        : await readFile(resolve(repoRoot, uri));
+    const png = PNG.sync.read(buf);
+    return { width: png.width, height: png.height, data: png.data };
+}
+/** Compare one matched pair, returning its score and triptych. */
+export async function diffImagePair(repoRoot, reference, candidate, config) {
+    const ref = await readRaster(repoRoot, reference.uri);
+    const cand = await readRaster(repoRoot, candidate.uri);
+    const key = imageKey(reference);
+    const dw = Math.abs(ref.width - cand.width);
+    const dh = Math.abs(ref.height - cand.height);
+    const sameSize = dw === 0 && dh === 0;
+    // A sub-tolerance dimension delta (e.g. density rounding between two render
+    // tools) is diffed over the shared top-left overlap rather than written off as
+    // a total mismatch, so the real content drift isn't masked (#47).
+    const aligned = !sameSize &&
+        dw <= config.visualDimTolerancePx &&
+        dh <= config.visualDimTolerancePx;
+    // Score against the union box so the non-overlapping border (counted as
+    // differing below) can't push the ratio past 1; for equal sizes this is just
+    // the shared area.
+    const totalPixels = Math.max(ref.width, cand.width) * Math.max(ref.height, cand.height);
+    let diffPixels;
+    let diff = null;
+    let diffPng;
+    if (sameSize || aligned) {
+        const ow = Math.min(ref.width, cand.width);
+        const oh = Math.min(ref.height, cand.height);
+        const out = new PNG({ width: ow, height: oh });
+        const overlapDiff = pixelmatch(cropTopLeft(ref, ow, oh), cropTopLeft(cand, ow, oh), out.data, ow, oh, { threshold: config.pixelThreshold });
+        diff = { width: ow, height: oh, data: out.data };
+        diffPng = PNG.sync.write(out);
+        // Differing overlap pixels + the border only one image covers.
+        diffPixels = overlapDiff + (totalPixels - ow * oh);
+    }
+    else {
+        // Dimension drift beyond tolerance is a genuine total mismatch; there's no
+        // meaningful aligned region to render.
+        diffPixels = totalPixels;
+    }
+    const score = totalPixels === 0 ? 0 : diffPixels / totalPixels;
+    const triptych = composeTriptych([ref, cand, diff]);
+    const result = { key, score, diffPixels, totalPixels, triptych };
+    if (diffPng)
+        result.diffPng = diffPng;
+    if (aligned)
+        result.dimensionMismatch = true;
+    return result;
+}
+/**
+ * Copy the top-left `w×h` region of a raster into a fresh, tightly-packed RGBA
+ * buffer (pixelmatch needs both inputs at one common stride). A no-op when the
+ * region already spans the whole raster.
+ */
+function cropTopLeft(src, w, h) {
+    if (src.width === w && src.height === h)
+        return src.data;
+    const out = Buffer.alloc(w * h * 4);
+    const rowBytes = w * 4;
+    for (let y = 0; y < h; y++) {
+        const srcStart = y * src.width * 4;
+        src.data.copy(out, y * rowBytes, srcStart, srcStart + rowBytes);
+    }
+    return out;
+}
+/** Lay panels out left-to-right on a gap-coloured strip, top-aligned. */
+function composeTriptych(panels) {
+    const present = panels.map((p) => p ?? { width: 1, height: 1, data: Buffer.alloc(4) });
+    const height = Math.max(...present.map((p) => p.height));
+    const width = present.reduce((sum, p) => sum + p.width, 0) + GAP * (present.length - 1);
+    const out = new PNG({ width, height });
+    // Fill with the gap colour so seams and short panels read as deliberate.
+    for (let i = 0; i < out.data.length; i += 4) {
+        out.data[i] = GAP_RGBA[0];
+        out.data[i + 1] = GAP_RGBA[1];
+        out.data[i + 2] = GAP_RGBA[2];
+        out.data[i + 3] = GAP_RGBA[3];
+    }
+    let xOffset = 0;
+    for (const panel of present) {
+        blit(out, panel, xOffset);
+        xOffset += panel.width + GAP;
+    }
+    return PNG.sync.write(out);
+}
+function blit(dest, src, xOffset) {
+    for (let y = 0; y < src.height; y++) {
+        for (let x = 0; x < src.width; x++) {
+            const si = (y * src.width + x) * 4;
+            const di = (y * dest.width + (x + xOffset)) * 4;
+            dest.data[di] = src.data[si];
+            dest.data[di + 1] = src.data[si + 1];
+            dest.data[di + 2] = src.data[si + 2];
+            dest.data[di + 3] = src.data[si + 3];
+        }
+    }
+}
+//# sourceMappingURL=visual.js.map

package/dist/visual.js.map

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@design-parity/diff",
+  "version": "0.1.0",
+  "description": "Source-agnostic diff engine: consume a (DesignReference, CandidateRender) pair and emit a deterministic Verdict — a11y + i18n first, then token compliance, then visual diff.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@design-parity/checks": "^0.1.0",
+    "@design-parity/core": "^0.1.0",
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/pngjs": "^6.0.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yschimke/design-parity.git",
+    "directory": "packages/diff"
+  },
+  "homepage": "https://github.com/yschimke/design-parity/tree/main/packages/diff#readme",
+  "bugs": "https://github.com/yschimke/design-parity/issues"
+}