@design-parity/report-html 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @design-parity/report-html
+
+The per-run **self-contained HTML comparison page**: the rich artifact a
+reviewer opens from a PR to actually *review* a mismatch.
+
+Given the same `(DesignReference, CandidateRender, Verdict)` the markdown
+summary uses — plus optional diff panels — `renderHtmlReport` emits **one
+offline `.html` string**:
+
+- **reference | candidate | diff** side by side per variant (paired by
+  `state/theme/size`, tolerant when a side omits or relabels the size), with a
+  vanilla opacity/overlay slider to wipe between reference and candidate.
+- the verdict findings in **value order** (a11y + i18n → token → semantic →
+  visual), each with its severity, and the token expected-vs-actual shown
+  inline from `finding.detail`.
+- everything inlined: CSS in a `<style>`, the slider JS in a `<script>`, and
+  every image as a `data:image/png;base64,…` URI. **No external requests** — it
+  opens from a file, as a CI artifact, or on GitHub Pages.
+
+It is a **leaf consumer**: it depends only on `@design-parity/core`. The diff
+panels arrive as a generic `DiffImage { key; png }`, so it never depends on
+`@design-parity/diff`.
+
+Output is **deterministic** — same input, byte-identical HTML. No timestamps,
+random ids, or `Date.now()` (docs/PRINCIPLES.md, Principle 1).
+
+## Usage
+
+```ts
+import { renderHtmlReport } from "@design-parity/report-html";
+
+const html = renderHtmlReport({
+  reference, // DesignReference
+  candidate, // CandidateRender
+  verdict, // Verdict
+  diffImages: triptychs.map((t) => ({ key: t.key, png: t.png })), // optional
+  repoRoot, // resolves reference/candidate Image.uri (defaults to cwd)
+});
+// write `html` to one .html file
+```
+
+Reference and candidate PNGs are read from disk via `repoRoot + Image.uri`
+(the same resolution the diff engine uses) and inlined. A side with no images
+(a semantic/token-only verdict) degrades cleanly — the findings still render.
+
+## CLI
+
+A small demo CLI ships as `design-parity-report`:
+
+```sh
+design-parity-report \
+  --reference fixtures/figma/button-primary.reference.json \
+  --candidate fixtures/candidate/button-primary.candidate.json \
+  --verdict   out/verdict.json \
+  --diff default/dark/compact=out/diff-dark.png \
+  --repo . \
+  --out report.html
+```

package/dist/cli/report.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=report.d.ts.map

package/dist/cli/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/cli/report.ts"],"names":[],"mappings":""}

package/dist/cli/report.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * `design-parity-report` — write a self-contained HTML comparison page.
+ *
+ *   design-parity-report \
+ *     --reference figma/button.reference.json \
+ *     --candidate candidate/button.candidate.json \
+ *     --verdict   out/verdict.json \
+ *     --diff default/dark/compact=out/diff-dark.png \
+ *     --repo . \
+ *     --out report.html
+ *
+ * Reads a `DesignReference`, a `CandidateRender`, and a `Verdict` (the diff
+ * engine's JSON), optionally one or more `key=path.png` diff panels, and writes
+ * the rendered HTML to `--out` (or stdout). Handy for demos; the Action wires
+ * the same `renderHtmlReport` call in steady state.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { argv, cwd, exit, stderr, stdout } from "node:process";
+import { renderHtmlReport } from "../render.js";
+function parseArgs(args) {
+    const out = { repoRoot: cwd(), diffs: [] };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const next = () => {
+            const v = args[(i += 1)];
+            if (v === undefined)
+                throw new Error(`missing value for ${a}`);
+            return v;
+        };
+        switch (a) {
+            case "--reference":
+                out.reference = next();
+                break;
+            case "--candidate":
+                out.candidate = next();
+                break;
+            case "--verdict":
+                out.verdict = next();
+                break;
+            case "--repo":
+                out.repoRoot = resolve(next());
+                break;
+            case "--out":
+                out.out = next();
+                break;
+            case "--diff": {
+                const spec = next();
+                const eq = spec.indexOf("=");
+                if (eq === -1)
+                    throw new Error(`--diff expects key=path, got ${spec}`);
+                out.diffs.push({ key: spec.slice(0, eq), path: spec.slice(eq + 1) });
+                break;
+            }
+            default:
+                throw new Error(`unknown argument: ${a}`);
+        }
+    }
+    return out;
+}
+function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function main() {
+    const args = parseArgs(argv.slice(2));
+    if (!args.reference || !args.candidate || !args.verdict) {
+        stderr.write("usage: design-parity-report --reference <json> --candidate <json> --verdict <json> [--diff key=png]... [--repo dir] [--out file]\n");
+        exit(2);
+    }
+    const diffImages = args.diffs.map((d) => ({
+        key: d.key,
+        png: readFileSync(d.path),
+    }));
+    const html = renderHtmlReport({
+        reference: readJson(args.reference),
+        candidate: readJson(args.candidate),
+        verdict: readJson(args.verdict),
+        diffImages,
+        repoRoot: args.repoRoot,
+    });
+    if (args.out) {
+        writeFileSync(args.out, html);
+        stderr.write(`wrote ${args.out}\n`);
+    }
+    else {
+        stdout.write(html);
+    }
+}
+main();
+//# sourceMappingURL=report.js.map

package/dist/cli/report.js.map

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

package/dist/findings.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Group verdict findings into value-ordered sections (docs/PRINCIPLES.md,
+ * Principle 2): accessibility + i18n first, then token compliance, then
+ * semantics, then the raw visual diff. Mirrors the markdown summary so the two
+ * surfaces agree.
+ */
+import type { Finding, FindingKind } from "@design-parity/core";
+export interface FindingSection {
+    title: string;
+    kinds: FindingKind[];
+}
+export declare const SECTIONS: FindingSection[];
+export interface GroupedSection {
+    title: string;
+    findings: Finding[];
+}
+/** Findings bucketed by section, in value order; empty sections dropped. */
+export declare function groupFindings(findings: readonly Finding[]): GroupedSection[];
+/**
+ * Pull an expected/actual token delta out of a finding's `detail` when present
+ * (the diff engine stamps `{ token, expected, actual, delta }`).
+ */
+export interface TokenDelta {
+    token?: string;
+    expected?: string;
+    actual?: string;
+}
+export declare function tokenDelta(finding: Finding): TokenDelta | undefined;
+//# sourceMappingURL=findings.d.ts.map

package/dist/findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.d.ts","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,eAAO,MAAM,QAAQ,EAAE,cAAc,EAKpC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,cAAc,EAAE,CAO5E;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAanE"}

package/dist/findings.js

@@ -0,0 +1,31 @@
+export const SECTIONS = [
+    { title: "Accessibility & i18n", kinds: ["contrast", "a11y", "i18n"] },
+    { title: "Token compliance", kinds: ["token"] },
+    { title: "Semantics", kinds: ["semantic"] },
+    { title: "Visual", kinds: ["visual"] },
+];
+/** Findings bucketed by section, in value order; empty sections dropped. */
+export function groupFindings(findings) {
+    const grouped = [];
+    for (const section of SECTIONS) {
+        const matched = findings.filter((f) => section.kinds.includes(f.kind));
+        if (matched.length > 0)
+            grouped.push({ title: section.title, findings: matched });
+    }
+    return grouped;
+}
+export function tokenDelta(finding) {
+    const d = finding.detail;
+    if (!d)
+        return undefined;
+    const has = "token" in d || "expected" in d || "actual" in d;
+    if (!has)
+        return undefined;
+    const fmt = (v) => v === undefined || v === null ? undefined : String(v);
+    return {
+        token: fmt(d["token"]),
+        expected: fmt(d["expected"]),
+        actual: fmt(d["actual"]),
+    };
+}
+//# sourceMappingURL=findings.js.map

package/dist/findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,QAAQ,GAAqB;IACxC,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;AAOF,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAAC,QAA4B;IACxD,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACvE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAYD,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IACzB,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,MAAM,GAAG,GACP,OAAO,IAAI,CAAC,IAAI,UAAU,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,CAAC;IACnD,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,GAAG,GAAG,CAAC,CAAU,EAAsB,EAAE,CAC7C,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACtB,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAC5B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;KACzB,CAAC;AACJ,CAAC"}

package/dist/html.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tiny HTML helpers. No template engine — everything is inlined by hand so the
+ * output is deterministic and the page is fully self-contained (no escaping
+ * surprises, no external dependency).
+ */
+/** Escape text for use in element content / double-quoted attributes. */
+export declare function escapeHtml(value: string): string;
+/** Wrap raw PNG bytes in a `data:` URI suitable for an `<img src>`. */
+export declare function pngDataUri(png: Uint8Array): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAGlD"}

package/dist/html.js

@@ -0,0 +1,20 @@
+/**
+ * Tiny HTML helpers. No template engine — everything is inlined by hand so the
+ * output is deterministic and the page is fully self-contained (no escaping
+ * surprises, no external dependency).
+ */
+/** Escape text for use in element content / double-quoted attributes. */
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+/** Wrap raw PNG bytes in a `data:` URI suitable for an `<img src>`. */
+export function pngDataUri(png) {
+    // Buffer.from(Uint8Array) shares no quirks here; base64 is deterministic.
+    return `data:image/png;base64,${Buffer.from(png).toString("base64")}`;
+}
+//# sourceMappingURL=html.js.map

package/dist/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK;SACT,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,UAAU,CAAC,GAAe;IACxC,0EAA0E;IAC1E,OAAO,yBAAyB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;AACxE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@design-parity/report-html` — the per-run, self-contained HTML comparison
+ * page.
+ *
+ * Consume the same `(DesignReference, CandidateRender, Verdict)` the markdown
+ * summary uses, plus optional diff panels, and emit ONE offline `.html` string:
+ * reference | candidate | diff side by side per variant, the verdict findings
+ * in value order, every image inlined as a `data:` URI. Deterministic, no
+ * external assets. A leaf consumer — depends only on `@design-parity/core`.
+ */
+export { renderHtmlReport } from "./render.js";
+export type { DiffImage, ReportInput } from "./types.js";
+export { pairVariants } from "./variants.js";
+export type { Variant } from "./variants.js";
+export { groupFindings, tokenDelta, SECTIONS } from "./findings.js";
+export type { FindingSection, GroupedSection, TokenDelta } from "./findings.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;;;;;;;;;GASG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@design-parity/report-html` — the per-run, self-contained HTML comparison
+ * page.
+ *
+ * Consume the same `(DesignReference, CandidateRender, Verdict)` the markdown
+ * summary uses, plus optional diff panels, and emit ONE offline `.html` string:
+ * reference | candidate | diff side by side per variant, the verdict findings
+ * in value order, every image inlined as a `data:` URI. Deterministic, no
+ * external assets. A leaf consumer — depends only on `@design-parity/core`.
+ */
+export { renderHtmlReport } from "./render.js";
+export { pairVariants } from "./variants.js";
+export { groupFindings, tokenDelta, SECTIONS } from "./findings.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;;;;;;;;;GASG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,8 @@
+import type { ReportInput } from "./types.js";
+/**
+ * Render a parity run as one self-contained HTML document string.
+ *
+ * @see ReportInput
+ */
+export declare function renderHtmlReport(input: ReportInput): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,YAAY,CAAC;AA2MzD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAmD3D"}

package/dist/render.js

@@ -0,0 +1,241 @@
+/**
+ * `renderHtmlReport` — turn a parity run into one self-contained HTML page.
+ *
+ * The page inlines everything: CSS in a `<style>`, a small vanilla `<script>`
+ * for the overlay/opacity slider and theme/size switches, and every image as a
+ * `data:image/png;base64,…` URI. No external requests — it opens offline, from
+ * a file, as a CI artifact, or on GitHub Pages.
+ *
+ * Output is deterministic: same input → byte-identical string. No timestamps,
+ * no random ids, no `Date.now()`.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { cwd } from "node:process";
+import { groupFindings, tokenDelta } from "./findings.js";
+import { escapeHtml, pngDataUri } from "./html.js";
+import { pairVariants } from "./variants.js";
+const STATUS_LABEL = {
+    pass: "Pass",
+    warn: "Warn",
+    fail: "Fail",
+};
+const SEVERITY_LABEL = {
+    info: "info",
+    warn: "warn",
+    error: "error",
+};
+/** Inline an image from disk as a data URI, or `undefined` if absent/unreadable. */
+function inlineFromDisk(root, img) {
+    if (!img)
+        return undefined;
+    // A source may already hand us a `data:` URI; pass it through untouched.
+    if (img.uri.startsWith("data:"))
+        return img.uri;
+    const bytes = readFileSync(resolve(root, img.uri));
+    return pngDataUri(bytes);
+}
+function panelMarkup(panel, role) {
+    const inner = panel.src
+        ? `<img class="panel-img" data-role="${role}" src="${panel.src}" alt="${escapeHtml(panel.label)}" />`
+        : `<div class="panel-empty">no image</div>`;
+    return `<figure class="panel" data-role="${role}">
+            <figcaption>${escapeHtml(panel.label)}</figcaption>
+            <div class="panel-body">${inner}</div>
+          </figure>`;
+}
+function variantMarkup(variant, index, refSrc, candSrc, diffSrc) {
+    const meta = [variant.state, variant.theme, variant.size]
+        .filter(Boolean)
+        .map((v) => `<span class="chip">${escapeHtml(String(v))}</span>`)
+        .join(" ");
+    const ref = { label: "Reference", src: refSrc };
+    const cand = { label: "Candidate", src: candSrc };
+    const diff = { label: "Diff", src: diffSrc };
+    // The overlay stacks reference under candidate; the slider sets candidate
+    // opacity so you can wipe between them. Only meaningful when both exist.
+    const overlay = refSrc && candSrc
+        ? `<div class="overlay">
+           <div class="overlay-stack">
+             <img class="overlay-ref" src="${refSrc}" alt="reference" />
+             <img class="overlay-cand" src="${candSrc}" alt="candidate" data-overlay="${index}" />
+           </div>
+           <label class="overlay-control">
+             <span>reference</span>
+             <input type="range" min="0" max="100" value="100" data-slider="${index}" />
+             <span>candidate</span>
+           </label>
+         </div>`
+        : "";
+    return `<section class="variant" data-variant="${escapeHtml(variant.key)}">
+            <header class="variant-head">
+              <h3>${escapeHtml(variant.key)}</h3>
+              <div class="variant-meta">${meta}</div>
+            </header>
+            <div class="triptych">
+              ${panelMarkup(ref, "reference")}
+              ${panelMarkup(cand, "candidate")}
+              ${panelMarkup(diff, "diff")}
+            </div>
+            ${overlay}
+          </section>`;
+}
+function findingsMarkup(verdict) {
+    const sections = groupFindings(verdict.findings);
+    if (sections.length === 0) {
+        return `<p class="no-findings">No parity findings — candidate matches the reference spec.</p>`;
+    }
+    return sections
+        .map((section) => {
+        const items = section.findings
+            .map((f) => {
+            const delta = tokenDelta(f);
+            const deltaMarkup = delta && (delta.expected !== undefined || delta.actual !== undefined)
+                ? `<div class="delta">
+                   ${delta.token ? `<code>${escapeHtml(delta.token)}</code>` : ""}
+                   <span class="expected">expected ${escapeHtml(delta.expected ?? "—")}</span>
+                   <span class="actual">actual ${escapeHtml(delta.actual ?? "—")}</span>
+                 </div>`
+                : "";
+            return `<li class="finding sev-${f.severity}">
+                    <span class="sev-tag">${SEVERITY_LABEL[f.severity]}</span>
+                    <div class="finding-body">
+                      <span class="finding-msg">${escapeHtml(f.message)}</span>
+                      ${deltaMarkup}
+                    </div>
+                  </li>`;
+        })
+            .join("\n");
+        return `<div class="finding-section">
+                <h3>${escapeHtml(section.title)}</h3>
+                <ul class="finding-list">${items}</ul>
+              </div>`;
+    })
+        .join("\n");
+}
+function scoresMarkup(verdict) {
+    const scores = verdict.visualScores;
+    if (!scores || Object.keys(scores).length === 0)
+        return "";
+    const rows = Object.entries(scores)
+        .map(([key, score]) => `<li><code>${escapeHtml(key)}</code> ${score === 0
+        ? "<span class=\"match\">match</span>"
+        : `<span class="differ">${(score * 100).toFixed(1)}% differ</span>`}</li>`)
+        .join("\n");
+    return `<div class="finding-section">
+            <h3>Visual scores</h3>
+            <ul class="score-list">${rows}</ul>
+          </div>`;
+}
+const STYLE = `:root{color-scheme:light dark}
+*{box-sizing:border-box}
+body{margin:0;font:14px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;background:#0f0f14;color:#e7e7ef}
+a{color:inherit}
+header.page{padding:24px 28px;border-bottom:1px solid #26262f}
+header.page h1{margin:0 0 6px;font-size:18px}
+.subtitle{color:#9a9ab0;font-size:13px}
+.status{display:inline-block;margin-left:10px;padding:2px 10px;border-radius:999px;font-weight:600;font-size:12px;vertical-align:middle}
+.status-pass{background:#16351f;color:#7ee29a}
+.status-warn{background:#3a3115;color:#e8c66b}
+.status-fail{background:#3a1820;color:#f08a9c}
+main{padding:20px 28px;display:grid;gap:24px;max-width:1200px}
+.variant{border:1px solid #26262f;border-radius:10px;padding:16px;background:#15151c}
+.variant-head{display:flex;align-items:baseline;gap:12px;flex-wrap:wrap;margin-bottom:12px}
+.variant-head h3{margin:0;font-size:14px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+.chip{display:inline-block;padding:1px 8px;border-radius:6px;background:#222230;color:#b8b8cc;font-size:11px;margin-left:4px}
+.triptych{display:grid;grid-template-columns:repeat(3,1fr);gap:12px}
+.panel{margin:0;border:1px solid #26262f;border-radius:8px;overflow:hidden;background:#0c0c11}
+.panel figcaption{padding:6px 10px;font-size:11px;letter-spacing:.04em;text-transform:uppercase;color:#9a9ab0;border-bottom:1px solid #26262f}
+.panel-body{display:flex;align-items:center;justify-content:center;min-height:64px;padding:10px}
+.panel-img{max-width:100%;height:auto;image-rendering:pixelated}
+.panel-empty{color:#666;font-size:12px;padding:20px}
+.overlay{margin-top:14px}
+.overlay-stack{position:relative;display:inline-block;border:1px solid #26262f;border-radius:8px;overflow:hidden;background:#0c0c11}
+.overlay-stack img{display:block;max-width:100%}
+.overlay-cand{position:absolute;inset:0;width:100%;height:100%}
+.overlay-control{display:flex;align-items:center;gap:10px;margin-top:8px;font-size:12px;color:#9a9ab0}
+.overlay-control input{flex:1;max-width:280px}
+.findings{border:1px solid #26262f;border-radius:10px;padding:16px;background:#15151c}
+.finding-section+.finding-section{margin-top:16px}
+.finding-section h3{margin:0 0 8px;font-size:13px;color:#c9c9dd}
+.finding-list,.score-list{list-style:none;margin:0;padding:0;display:grid;gap:6px}
+.finding{display:flex;gap:10px;align-items:flex-start;padding:8px 10px;border-radius:8px;background:#0f0f15;border:1px solid #222230}
+.sev-tag{flex:none;font-size:10px;text-transform:uppercase;letter-spacing:.05em;padding:2px 7px;border-radius:999px;font-weight:700}
+.sev-info .sev-tag{background:#16283a;color:#7db4e8}
+.sev-warn .sev-tag{background:#3a3115;color:#e8c66b}
+.sev-error .sev-tag{background:#3a1820;color:#f08a9c}
+.finding-body{display:flex;flex-direction:column;gap:4px}
+.delta{display:flex;gap:8px;flex-wrap:wrap;font-size:12px;color:#9a9ab0}
+.delta code{background:#222230;padding:1px 6px;border-radius:5px}
+.delta .expected{color:#7ee29a}
+.delta .actual{color:#f08a9c}
+.score-list code{background:#222230;padding:1px 6px;border-radius:5px}
+.match{color:#7ee29a}
+.differ{color:#e8c66b}
+.no-findings{color:#7ee29a;margin:0}
+@media (max-width:760px){.triptych{grid-template-columns:1fr}}`;
+const SCRIPT = `(function(){
+  var sliders=document.querySelectorAll('input[data-slider]');
+  for(var i=0;i<sliders.length;i++){
+    (function(slider){
+      var id=slider.getAttribute('data-slider');
+      var cand=document.querySelector('img[data-overlay="'+id+'"]');
+      function apply(){ if(cand){ cand.style.opacity=(slider.value/100).toString(); } }
+      slider.addEventListener('input',apply);
+      apply();
+    })(sliders[i]);
+  }
+})();`;
+/**
+ * Render a parity run as one self-contained HTML document string.
+ *
+ * @see ReportInput
+ */
+export function renderHtmlReport(input) {
+    const { reference, candidate, verdict } = input;
+    const root = input.repoRoot ?? cwd();
+    const diffByKey = new Map();
+    for (const d of input.diffImages ?? [])
+        diffByKey.set(d.key, d);
+    const variants = pairVariants(reference.referenceImages, candidate.images);
+    const variantsHtml = variants
+        .map((variant, index) => {
+        const refSrc = inlineFromDisk(root, variant.reference);
+        const candSrc = inlineFromDisk(root, variant.candidate);
+        const diff = diffByKey.get(variant.key);
+        const diffSrc = diff ? pngDataUri(diff.png) : undefined;
+        return variantMarkup(variant, index, refSrc, candSrc, diffSrc);
+    })
+        .join("\n");
+    const hasVariants = variants.length > 0;
+    const variantsSection = hasVariants
+        ? variantsHtml
+        : `<section class="variant"><p class="panel-empty">No images for this verdict — findings only.</p></section>`;
+    const status = verdict.status;
+    const title = `Parity report: ${escapeHtml(verdict.componentId)}`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${title}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header class="page">
+  <h1>${escapeHtml(verdict.componentId)}<span class="status status-${status}">${STATUS_LABEL[status]}</span></h1>
+  <div class="subtitle">${escapeHtml(reference.source)} reference vs candidate render</div>
+</header>
+<main>
+${variantsSection}
+<section class="findings">
+${findingsMarkup(verdict)}
+${scoresMarkup(verdict)}
+</section>
+</main>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Local contracts for the HTML report.
+ *
+ * This package is a leaf consumer: it depends only on `@design-parity/core`.
+ * It deliberately does *not* import `@design-parity/diff` — instead the
+ * triptych/diff panels arrive as a generic {@link DiffImage}, so the diff
+ * engine (or any producer) can hand us heatmaps without this package taking a
+ * dependency on it.
+ */
+import type { CandidateRender, DesignReference, Verdict } from "@design-parity/core";
+/**
+ * A diff panel to inline, keyed by the same `state/theme/size` key the diff
+ * engine uses for its triptychs/visual scores. `png` is the raw PNG bytes.
+ */
+export interface DiffImage {
+    key: string;
+    png: Uint8Array;
+}
+/** Everything {@link renderHtmlReport} needs to emit one offline page. */
+export interface ReportInput {
+    reference: DesignReference;
+    candidate: CandidateRender;
+    verdict: Verdict;
+    /** Per-variant diff panels (e.g. the pixelmatch heatmaps). Optional. */
+    diffImages?: DiffImage[];
+    /**
+     * Root the reference/candidate `Image.uri`s resolve against (mirrors the
+     * diff engine). Defaults to `process.cwd()`.
+     */
+    repoRoot?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,OAAO,EACR,MAAM,qBAAqB,CAAC;AAE7B;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,UAAU,CAAC;CACjB;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,CAAC;IAC3B,SAAS,EAAE,eAAe,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/variants.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pair reference and candidate images into per-variant rows, tolerant of a side
+ * that omits or labels `size` differently (same rule the diff engine uses:
+ * canonicalize via `normalizeSize`, and let an unknown/missing size pair with
+ * anything).
+ */
+import { type Image } from "@design-parity/core";
+/** One reference | candidate | diff row. Any side may be missing. */
+export interface Variant {
+    /** `state/theme/size` key (raw size), stable for the DOM + diff lookup. */
+    key: string;
+    state: string;
+    theme?: string;
+    size?: string;
+    reference?: Image;
+    candidate?: Image;
+}
+/**
+ * Pair references with candidates. Output order is stable: references in their
+ * declared order first (each with its best candidate match), then any
+ * candidate-only variants in their declared order.
+ */
+export declare function pairVariants(references: readonly Image[], candidates: readonly Image[]): Variant[];
+//# sourceMappingURL=variants.d.ts.map

package/dist/variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.d.ts","sourceRoot":"","sources":["../src/variants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAiB,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEhE,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,SAAS,CAAC,EAAE,KAAK,CAAC;CACnB;AA4BD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,KAAK,EAAE,EAC5B,UAAU,EAAE,SAAS,KAAK,EAAE,GAC3B,OAAO,EAAE,CA2CX"}

package/dist/variants.js

@@ -0,0 +1,71 @@
+/**
+ * Pair reference and candidate images into per-variant rows, tolerant of a side
+ * that omits or labels `size` differently (same rule the diff engine uses:
+ * canonicalize via `normalizeSize`, and let an unknown/missing size pair with
+ * anything).
+ */
+import { normalizeSize } from "@design-parity/core";
+/** Human/diff key — raw size, matches `@design-parity/diff`'s `imageKey`. */
+function imageKey(img) {
+    return [img.state, img.theme, img.size].filter(Boolean).join("/");
+}
+/** Canonical size token for pairing (falls back to the lowercased label). */
+function sizeToken(img) {
+    return normalizeSize(img.size) ?? img.size?.toLowerCase();
+}
+/** Pairing key with the size normalized. */
+function pairKey(img) {
+    return [img.state, img.theme, sizeToken(img)].filter(Boolean).join("/");
+}
+/** Looser key ignoring size — used when a side omits/uses an unknown size. */
+function looseKey(img) {
+    return [img.state, img.theme].filter(Boolean).join("/");
+}
+function sizeCompatible(a, b) {
+    const ca = normalizeSize(a.size);
+    const cb = normalizeSize(b.size);
+    return ca === undefined || cb === undefined || ca === cb;
+}
+/**
+ * Pair references with candidates. Output order is stable: references in their
+ * declared order first (each with its best candidate match), then any
+ * candidate-only variants in their declared order.
+ */
+export function pairVariants(references, candidates) {
+    const used = new Set();
+    const findCandidate = (ref) => {
+        // Prefer an exact normalized-key match, then a size-tolerant loose match.
+        const exact = candidates.findIndex((c, i) => !used.has(i) && pairKey(c) === pairKey(ref));
+        if (exact !== -1)
+            return exact;
+        return candidates.findIndex((c, i) => !used.has(i) && looseKey(c) === looseKey(ref) && sizeCompatible(c, ref));
+    };
+    const variants = [];
+    for (const ref of references) {
+        const ci = findCandidate(ref);
+        const candidate = ci === -1 ? undefined : candidates[ci];
+        if (ci !== -1)
+            used.add(ci);
+        variants.push({
+            key: imageKey(ref),
+            state: ref.state,
+            theme: ref.theme,
+            size: ref.size,
+            reference: ref,
+            candidate,
+        });
+    }
+    candidates.forEach((c, i) => {
+        if (used.has(i))
+            return;
+        variants.push({
+            key: imageKey(c),
+            state: c.state,
+            theme: c.theme,
+            size: c.size,
+            candidate: c,
+        });
+    });
+    return variants;
+}
+//# sourceMappingURL=variants.js.map

package/dist/variants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.js","sourceRoot":"","sources":["../src/variants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAc,MAAM,qBAAqB,CAAC;AAahE,6EAA6E;AAC7E,SAAS,QAAQ,CAAC,GAAU;IAC1B,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpE,CAAC;AAED,6EAA6E;AAC7E,SAAS,SAAS,CAAC,GAAU;IAC3B,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC;AAC5D,CAAC;AAED,4CAA4C;AAC5C,SAAS,OAAO,CAAC,GAAU;IACzB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1E,CAAC;AAED,8EAA8E;AAC9E,SAAS,QAAQ,CAAC,GAAU;IAC1B,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,cAAc,CAAC,CAAQ,EAAE,CAAQ;IACxC,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,UAA4B,EAC5B,UAA4B;IAE5B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,MAAM,aAAa,GAAG,CAAC,GAAU,EAAU,EAAE;QAC3C,0EAA0E;QAC1E,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,CAChC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CACtD,CAAC;QACF,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC/B,OAAO,UAAU,CAAC,SAAS,CACzB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,GAAG,CAAC,IAAI,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,CAC1E,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,SAAS,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACzD,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC;YACZ,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC;YAClB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,SAAS,EAAE,GAAG;YACd,SAAS;SACV,CAAC,CAAC;IACL,CAAC;IAED,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC1B,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO;QACxB,QAAQ,CAAC,IAAI,CAAC;YACZ,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;YAChB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,SAAS,EAAE,CAAC;SACb,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@design-parity/report-html",
+  "version": "0.1.0",
+  "description": "Self-contained HTML comparison page per parity run: reference | candidate | diff side by side with the verdict findings, inlined to one offline .html file (data-URI PNGs + inline CSS/JS, no external assets).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "design-parity-report": "./dist/cli/report.js"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@design-parity/core": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yschimke/design-parity.git",
+    "directory": "packages/report-html"
+  },
+  "homepage": "https://github.com/yschimke/design-parity/tree/main/packages/report-html#readme",
+  "bugs": "https://github.com/yschimke/design-parity/issues"
+}