@mmerterden/dev-toolkit-mcp 2.24.1

package/tools/design-check/report.js

@@ -0,0 +1,590 @@
+/**
+ * design_report - render a design-audit report into a self-contained HTML file
+ * (base64-embedded images) and optionally a PDF (via Playwright if present).
+ *
+ * Presentation:
+ *   - Per screen: Figma (expected) on the left, Live (actual) on the right with
+ *     SVG arrow callouts pointing at each deviation and its "expected → actual".
+ *   - Findings grouped by category (Localization/Copy, Component, Padding,
+ *     Font Size, Font Color, Spacing, Size). Verified (on-spec) checks are listed
+ *     as passing so the report shows what was measured, not only what failed.
+ *   - Localization/copy deltas are compared against the design's source-of-truth
+ *     UX-writing, never against a stale frame render.
+ *   - A coverage gate: audited screens are weighed against the run's declared
+ *     target set, and every target that was neither audited nor skipped WITH A
+ *     REASON fails the gate. An audit that quietly visits a third of the screens
+ *     must not read as a clean report.
+ *
+ * Generic: the report object is platform/project-agnostic, and all human-facing
+ * wording comes from a label pack (English by default) so the engine carries no
+ * single natural language.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+
+const LABEL_PACKS = {
+  en: {
+    htmlLang: "en",
+    reportTitle: "Design Check Report",
+    moduleWord: "module",
+    thScreen: "Screen", thPerceptual: "Perceptual", thDeviations: "Deviations", thStatus: "Status",
+    statusCaptured: "CAPTURED", statusDeviation: "DEVIATION", statusPass: "PASS", statusReview: "REVIEW",
+    screensWord: "screens", deviationsWord: "deviations", advisoryWord: "ADVISORY (not counted)",
+    awaitingFigma: "captured · awaiting Figma mapping",
+    noAutoFindings: "visual comparison · no automatic element findings",
+    noDeviations: "No deviations.",
+    verifiedOnSpec: "VERIFIED · on-spec",
+    expectedWord: "expected", actualWord: "actual",
+    affectedComponents: "Affected components",
+    mainComponent: "Main component",
+    variantsWord: "variants",
+    toggleHint: "(show/hide · click → Figma)",
+    noPreview: "No preview captured.",
+    fixPromptTitle: "Developer prompt (paste into an agent)",
+    figmaCol: "FIGMA · expected", liveCol: "LIVE · actual",
+    coverageTitle: "Coverage",
+    coverageAudited: "audited", coverageTargets: "targets",
+    coverageSkipped: "Skipped with a reason", coverageUnaccounted: "Not audited, no reason given",
+    coverageGatePass: "COVERAGE GATE PASSED",
+    coverageGateFail: "COVERAGE GATE FAILED",
+    coverageGateHint: "every target must be audited or skipped with an explicit reason",
+    coverageNoReason: "no reason given",
+    coverageUndeclared: "target undeclared by the run",
+    coverageTruncated: "The scenario inventory hit its cap, so the target set is incomplete and this percentage is measured against a partial denominator.",
+    coverageBelowFloor: "below the required coverage floor",
+    footerNote: "dev-toolkit-mcp design-check · copy is compared against the design's source-of-truth UX writing, not a stale frame render; localization differences are not counted as defects.",
+  },
+  tr: {
+    htmlLang: "tr",
+    reportTitle: "Design Check Raporu",
+    moduleWord: "modül",
+    thScreen: "Ekran", thPerceptual: "Perceptual", thDeviations: "Sapma", thStatus: "Durum",
+    statusCaptured: "YAKALANDI", statusDeviation: "SAPMA", statusPass: "PASS", statusReview: "İNCELE",
+    screensWord: "ekran", deviationsWord: "sapma", advisoryWord: "BİLGİ AMAÇLI (sayılmıyor)",
+    awaitingFigma: "yakalandı · Figma eşlemesi bekliyor",
+    noAutoFindings: "görsel karşılaştırma · otomatik element bulgusu yok",
+    noDeviations: "Sapma yok.",
+    verifiedOnSpec: "DOĞRULANDI · on-spec",
+    expectedWord: "olması gereken", actualWord: "mevcut",
+    affectedComponents: "Etkilenen componentler",
+    mainComponent: "Main component",
+    variantsWord: "varyant",
+    toggleHint: "(göster/gizle · tıkla → Figma)",
+    noPreview: "Önizleme çekilmedi.",
+    fixPromptTitle: "Geliştirme promptu (ajana yapıştır)",
+    figmaCol: "FIGMA · olması gereken", liveCol: "CANLI · mevcut",
+    coverageTitle: "Kapsam",
+    coverageAudited: "denetlendi", coverageTargets: "hedef",
+    coverageSkipped: "Gerekçeli atlanan", coverageUnaccounted: "Denetlenmedi, gerekçe yok",
+    coverageGatePass: "KAPSAM GEÇİDİ GEÇTİ",
+    coverageGateFail: "KAPSAM GEÇİDİ BAŞARISIZ",
+    coverageGateHint: "her hedef ya denetlenmeli ya da açık gerekçeyle atlanmalı",
+    coverageNoReason: "gerekçe verilmedi",
+    coverageUndeclared: "hedef koşuda hiç bildirilmedi",
+    coverageTruncated: "Senaryo envanteri üst sınıra takıldı; hedef kümesi eksik ve bu yüzde kısmi bir payda üzerinden hesaplandı.",
+    coverageBelowFloor: "istenen kapsam tabanının altında",
+    footerNote: "dev-toolkit-mcp design-check · metin karşılaştırması tasarımın kaynak-doğru UX-writing'ine göre yapılır (bayat frame render'ına değil); localization farkları hata sayılmaz.",
+  },
+};
+
+function labels(report) {
+  const pack = LABEL_PACKS[report.lang] || LABEL_PACKS.en;
+  return { ...LABEL_PACKS.en, ...pack, ...(report.labels || {}) };
+}
+
+function dataUri(path) {
+  if (!path || !existsSync(path)) return "";
+  return `data:image/png;base64,${readFileSync(path).toString("base64")}`;
+}
+function esc(s) {
+  return String(s == null ? "" : s).replace(/[&<>"']/g, (c) => (
+    { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]
+  ));
+}
+function parseSize(s) { const m = /^(\d+)x(\d+)$/.exec(s || ""); return m ? { w: +m[1], h: +m[2] } : { w: 375, h: 812 }; }
+function figmaNodeUrl(fileKey, node) {
+  if (!fileKey || !node) return null;
+  return `https://www.figma.com/design/${fileKey}/?node-id=${String(node).replace(":", "-")}`;
+}
+
+/**
+ * The file a finding's component actually lives in.
+ *
+ * Components are NOT all in the audited screen's file. Observed on a real module:
+ *
+ *   CardsFlightCardsCheckinCheckinStart -> 9ipBvrtsq9HlQ175B9k0wx
+ *   CheckinBoardingPassLayout           -> ps4xrJzhn7WNbfkZs895Bi
+ *
+ * Every component link was built from the report-level `figmaFileKey`, so a
+ * component from a second library file got a URL into the wrong file. That link
+ * still opens - it just resolves to nothing - which is worse than no link,
+ * because the reader concludes the node was deleted. Prefer the per-finding key;
+ * fall back to the report-level one, which is correct for the same-file case.
+ */
+function componentFileKey(finding, reportFileKey) {
+  return (finding && finding.componentFileKey) || reportFileKey;
+}
+
+/**
+ * Normalize whatever the caller passed as `coverage` into a verdict.
+ *
+ * Accepted shapes:
+ *   - { targets: <n>|[ids], covered: <n>|[ids], skipped: [{id,group?,reason}], floor?: 0..1 }
+ *   - legacy: [ { group, items:[...] } ]  → every item counts as an unaccounted
+ *     target, because the legacy shape carries no per-item reason.
+ *
+ * Gate: nothing may vanish. Every target is audited, or skipped with a reason.
+ */
+const idOf = (x) => (typeof x === "string" ? x : (x && x.id ? String(x.id) : null));
+const tally = (list) => list.reduce((n, e) => n + (e.count || 1), 0);
+
+export function coverageVerdict(coverage, auditedCount) {
+  if (!coverage) return null;
+  const count = (x) => (Array.isArray(x) ? x.length : (Number.isFinite(x) ? x : 0));
+
+  if (Array.isArray(coverage)) {
+    const unaccounted = coverage.flatMap((g) => (g.items || []).map((it) => ({
+      id: String(it), group: g.group, reason: "",
+    })));
+    const target = auditedCount + unaccounted.length;
+    return {
+      target, audited: auditedCount, skipped: [], unaccounted,
+      unaccountedCount: unaccounted.length,
+      pct: target ? auditedCount / target : 1,
+      gate: unaccounted.length ? "fail" : "pass",
+      floor: null, belowFloor: false, legacyShape: true,
+    };
+  }
+
+  const target = count(coverage.targets) || (auditedCount + count(coverage.skipped));
+  // An explicitly empty `covered` means nothing was audited - honour it instead of
+  // falling back to the variant count, which would credit a run for screens it
+  // never claimed to have covered.
+  const audited = "covered" in coverage ? count(coverage.covered) : auditedCount;
+  const skippedRaw = coverage.skipped || [];
+  const skipped = [], unaccounted = [];
+  for (const s of skippedRaw) {
+    const entry = typeof s === "string" ? { id: s, reason: "" } : { id: s.id, group: s.group, reason: s.reason || "" };
+    (entry.reason ? skipped : unaccounted).push(entry);
+  }
+
+  // Targets that appear in neither list are the silent drops this gate exists for.
+  // When the caller passes id arrays they get named; with bare counts the best the
+  // report can say is how many went undeclared.
+  const accountedIds = new Set([
+    ...(Array.isArray(coverage.covered) ? coverage.covered.map(idOf) : []),
+    ...skipped.map((e) => e.id), ...unaccounted.map((e) => e.id),
+  ].filter(Boolean));
+  if (Array.isArray(coverage.targets)) {
+    for (const t of coverage.targets) {
+      const id = idOf(t);
+      if (id && !accountedIds.has(id)) {
+        unaccounted.push({ id, group: (t && t.screen) || (t && t.group) || null, reason: "" });
+        accountedIds.add(id);
+      }
+    }
+  } else {
+    const missing = Math.max(0, target - (audited + skipped.length + unaccounted.length));
+    if (missing) unaccounted.push({ id: null, group: null, reason: "", count: missing });
+  }
+
+  // Clamped: a caller that reports covered ids outside the target set must not
+  // render a >100% bar.
+  const pct = target ? Math.min(1, Math.max(0, audited / target)) : 1;
+  const floor = Number.isFinite(coverage.floor) ? coverage.floor : null;
+  const belowFloor = floor != null && pct < floor;
+  const unaccountedCount = tally(unaccounted);
+  // A truncated inventory means the denominator itself is incomplete, so no
+  // percentage over it can be trusted - that is a gate failure, not a footnote.
+  const truncatedInventory = !!coverage.truncatedInventory;
+  return {
+    target, audited, skipped, unaccounted, unaccountedCount, pct, floor, belowFloor,
+    truncatedInventory,
+    gate: unaccountedCount || belowFloor || truncatedInventory ? "fail" : "pass",
+    legacyShape: false,
+  };
+}
+
+const CAT_COLOR = {
+  "localization": "#E31837", "copy": "#E31837",
+  "component": "#B5179E", "icon": "#B5179E",
+  "padding": "#3A0CA3", "spacing": "#3A0CA3", "size": "#3A0CA3", "position": "#3A0CA3",
+  "font size": "#F77F00", "typography": "#F77F00",
+  "font color": "#0A7D33", "color": "#0A7D33",
+};
+const catColor = (c) => CAT_COLOR[(c || "").toLowerCase()] || "#555";
+
+// Polished annotation (Zeplin/Figma-inspect style): Figma + Live screenshots with
+// numbered pins, dashed leader lines, and dark callout cards stacked on the right
+// carrying the category chip, element, and expected → actual. Pure static SVG so it
+// renders identically in HTML, PDF, and Confluence.
+function twoUp(v, fileKey, L) {
+  const size = parseSize(v.compareSize);                  // figma/compare space (e.g. 375x812)
+  const lsz = parseSize(v.liveSize || v.compareSize);     // live NATIVE aspect (undistorted)
+  const LW = 250;
+  const LHf = Math.round(LW * size.h / size.w);           // figma column height
+  const LHl = Math.round(LW * lsz.h / lsz.w);             // live column height (own aspect)
+  const LH = Math.max(LHf, LHl);
+  const imgY = 22, gap = 34;
+  const hasFigma = !!(v.images && v.images.figma);
+  const liveX = hasFigma ? LW + gap : 0, liveRight = liveX + LW;
+  const cardX = liveRight + 78, CW = 440, CH = 120;
+  const devs = (v.findings || []).filter((f) => (f.status || "deviation") !== "verified" && !f.advisory && f.region);
+  const rowH = CH + 16, top = 24;
+  const svgH = Math.max(LH + imgY + 20, top + devs.length * rowH + 20);
+  const totalW = cardX + CW + 20;
+
+  let pins = "", leaders = "", cards = "";
+  devs.forEach((f, i) => {
+    const c = catColor(f.category || f.type);
+    const rx = (f.region.x + f.region.w / 2) / size.w * LW;
+    const ry = (f.region.y + f.region.h / 2) / size.h * LHl;   // pins on the live column (own height)
+    const pinX = liveX + rx, pinY = imgY + ry;
+    const cy = top + i * rowH + CH / 2;
+    const cardTop = cy - CH / 2;
+    const cat = (f.category || f.type || "").toUpperCase();
+    // dashed leader: pin -> elbow -> card left edge
+    const midX = (pinX + cardX) / 2;
+    leaders += `<path d="M ${pinX.toFixed(0)} ${pinY.toFixed(0)} L ${midX.toFixed(0)} ${pinY.toFixed(0)} L ${midX.toFixed(0)} ${cy.toFixed(0)} L ${cardX.toFixed(0)} ${cy.toFixed(0)}" fill="none" stroke="${c}" stroke-width="1" stroke-dasharray="4 3" opacity="0.75"/>`;
+    pins += `<circle cx="${pinX.toFixed(0)}" cy="${pinY.toFixed(0)}" r="8" fill="${c}" stroke="#fff" stroke-width="1.5"/><text x="${pinX.toFixed(0)}" y="${(pinY + 3.5).toFixed(0)}" text-anchor="middle" font-size="10" fill="#fff" font-weight="700">${i + 1}</text>`;
+    const u = f.component ? figmaNodeUrl(componentFileKey(f, fileKey), f.componentNode) : null;
+    const compHtml = f.component
+      ? `<div style="font-size:11px;color:#7A5AF8;font-weight:600;margin-bottom:3px">◈ ${u ? `<a href="${esc(u)}" target="_blank" style="color:#7A5AF8;text-decoration:none">${esc(f.component)} ↗</a>` : esc(f.component)}</div>`
+      : "";
+    // HTML card inside a foreignObject → text wraps naturally (no truncation)
+    cards += `<foreignObject x="${cardX}" y="${cardTop}" width="${CW}" height="${CH}">
+      <div xmlns="http://www.w3.org/1999/xhtml" style="box-sizing:border-box;width:100%;font-family:-apple-system,Segoe UI,Roboto,sans-serif;background:#fff;border:1.5px solid #1a1a1a;border-radius:12px;padding:9px 12px;overflow:hidden">
+        <div style="display:flex;align-items:center;gap:6px;flex-wrap:wrap;margin-bottom:5px">
+          <span style="background:${c};color:#fff;font-size:10px;font-weight:700;min-width:18px;height:18px;border-radius:9px;display:inline-flex;align-items:center;justify-content:center">${i + 1}</span>
+          <span style="background:${c};color:#fff;font-size:10px;font-weight:700;padding:2px 7px;border-radius:9px">${esc(cat)}</span>
+          <span style="font-size:12.5px;font-weight:600;color:#111">${esc(f.element || "")}</span>
+        </div>
+        ${compHtml}
+        <div style="font-size:12px;line-height:1.35"><span style="color:#8a8f98">${esc(L.expectedWord)} </span><span style="color:#0A7D33;font-weight:700">${esc(f.expected ?? "-")}</span></div>
+        <div style="font-size:12px;line-height:1.35"><span style="color:#8a8f98">${esc(L.actualWord)} </span><span style="color:#cf222e;font-weight:700">${esc(f.actual ?? "-")}</span></div>
+      </div>
+    </foreignObject>`;
+  });
+
+  return `<div class="twoup"><svg viewBox="0 0 ${totalW} ${svgH}" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system,Segoe UI,Roboto,sans-serif">
+    ${hasFigma ? `<text x="0" y="15" font-size="11" font-weight="700" fill="#666">${esc(L.figmaCol)}</text>
+    <image href="${dataUri(v.images.figma)}" x="0" y="${imgY}" width="${LW}" height="${LHf}" preserveAspectRatio="xMidYMin meet"/>
+    <rect x="0" y="${imgY}" width="${LW}" height="${LHf}" fill="none" stroke="#e5e5e5"/>` : ""}
+    <text x="${liveX}" y="15" font-size="11" font-weight="700" fill="#666">${esc(L.liveCol)}</text>
+    <image href="${dataUri(v.images?.live)}" x="${liveX}" y="${imgY}" width="${LW}" height="${LHl}" preserveAspectRatio="xMidYMin meet"/>
+    <rect x="${liveX}" y="${imgY}" width="${LW}" height="${LHl}" fill="none" stroke="#e5e5e5"/>
+    ${leaders}${pins}${cards}
+  </svg></div>`;
+}
+
+function groupFindings(findings) {
+  const groups = {};
+  for (const f of findings || []) {
+    const cat = (f.category || f.type || "other");
+    (groups[cat] = groups[cat] || []).push(f);
+  }
+  return groups;
+}
+
+function findingLine(f, i, L) {
+  const c = catColor(f.category || f.type);
+  const verified = (f.status === "verified");
+  return `<li class="finding ${verified ? "ok" : "bad"}">
+    <span class="mark" style="color:${verified ? "#0A7D33" : c}">${verified ? "✓" : (i != null ? i + 1 : "•")}</span>
+    <span class="fel">${esc(f.element || "")}</span>
+    ${!verified && (f.expected != null || f.actual != null)
+      ? `<span class="exp">${esc(L.expectedWord)} <code>${esc(f.expected)}</code> <b>→</b> ${esc(L.actualWord)} <code>${esc(f.actual)}</code></span>`
+      : ""}
+    ${/* the detail carries the measured delta and its unit - the actionable part,
+          so keep it even when expected → actual is shown */ ""}
+    ${f.detail ? `<span class="detail">${esc(f.detail)}</span>` : (!verified && f.expected == null ? `<span class="detail">on-spec</span>` : "")}
+  </li>`;
+}
+
+// Expandable "main component + all its variants" blocks (click to reveal).
+function componentsBlock(v, fileKey, L) {
+  const seen = new Map();
+  for (const f of v.findings || []) {
+    if (f.component && !seen.has(f.component)) seen.set(f.component, f);
+  }
+  if (!seen.size) return "";
+  const blocks = [...seen.values()].map((f) => {
+    const variants = f.componentVariants || [];
+    // A variant may name its own file too (a variant pulled from a different
+    // library than its parent set), so resolve per-variant and fall back to the
+    // component's file, then the report's.
+    const compKey = componentFileKey(f, fileKey);
+    const url = figmaNodeUrl(compKey, f.componentNode);
+    const thumbs = variants.length
+      ? `<div class="cvgrid">${variants.map((cv) => `<figure>${cv.node && url ? `<a href="${esc(figmaNodeUrl(cv.fileKey || compKey, cv.node))}" target="_blank">` : ""}<img src="${dataUri(cv.image)}" alt="">${cv.node && url ? "</a>" : ""}<figcaption>${esc(cv.name)}</figcaption></figure>`).join("")}</div>`
+      : `<p class="cvnote">${esc(L.noPreview)}</p>`;
+    const name = url ? `<a href="${esc(url)}" target="_blank">${esc(f.component)} ↗</a>` : `<b>${esc(f.component)}</b>`;
+    return `<details class="cvcomp"><summary>◈ ${esc(L.mainComponent)}: ${name}${variants.length ? ` · ${variants.length} ${esc(L.variantsWord)}` : ""} <span class="cvhint">${esc(L.toggleHint)}</span></summary>${thumbs}</details>`;
+  }).join("");
+  return `<div class="components"><h4>${esc(L.affectedComponents)}</h4>${blocks}</div>`;
+}
+
+/**
+ * A fix prompt an agent can act on without re-deriving anything.
+ *
+ * Prose loses the two things that make a deviation fixable: WHICH property moved
+ * and BY HOW MUCH. So emit a fixed-field table instead, keep it in English
+ * (it is a payload for a coding agent, next to code identifiers, not report
+ * copy), and state explicitly what must NOT be touched - advisories and
+ * fixture differences otherwise get "fixed" into new bugs.
+ */
+function buildFixPrompt(v) {
+  const all = v.findings || [];
+  const devs = all.filter((f) => !f.advisory && f.status !== "verified");
+  const advs = all.filter((f) => f.advisory);
+  if (!devs.length && !advs.length) return v.fixPrompt || "";
+
+  const rows = devs.map((f, i) => {
+    const prop = f.type === "inset" ? `${Object.keys(f.deltaPt || f.deltaPx || { edge: 1 })[0]} inset`
+      : f.type === "gap" ? "vertical gap"
+      : f.type === "spacing" ? "top offset"
+      : f.type === "height" ? "height"
+      : f.type === "font-size" ? "font size"
+      : f.type === "color" ? "colour"
+      : f.type;
+    const d = f.deltaPt || f.deltaPx || {};
+    const delta = Object.entries(d).map(([k, n]) => `${n >= 0 ? "+" : ""}${n}pt`).join(" ") || "-";
+    return `${i + 1}. ${f.element} | ${prop} | ${f.expected} -> ${f.actual} | ${delta}`;
+  });
+
+  // Deltas repeated verbatim across elements point at one shared container or
+  // token rather than N independent bugs - say so instead of making the agent
+  // spot it.
+  const byDelta = {};
+  for (const f of devs) {
+    const d = f.deltaPt || f.deltaPx || {};
+    for (const [k, n] of Object.entries(d)) {
+      const key = `${k}:${n}`;
+      (byDelta[key] = byDelta[key] || []).push(f.element);
+    }
+  }
+  const shared = Object.entries(byDelta)
+    .filter(([, els]) => new Set(els).size > 1)
+    .map(([key, els]) => {
+      const [k, n] = key.split(":");
+      return `  - ${k} off by ${n >= 0 ? "+" : ""}${n}pt on ${[...new Set(els)].join(", ")} -> likely ONE shared container padding / spacing token, not ${new Set(els).size} separate fixes`;
+    });
+
+  const out = [
+    `SCREEN: ${v.name}`,
+    `FIGMA NODE: ${v.figmaNodeId || "-"}   COMPARE FRAME: ${v.compareSize || "-"}`,
+    v.measurement ? `MEASUREMENT: ${v.measurement.mode} (tolerance ${v.measurement.tolerancePt}pt)` : "",
+  ];
+  // No deviations means nothing to fix - an empty "DEVIATIONS" heading would read
+  // as one, and on an advisory-only screen it is actively wrong.
+  if (rows.length) {
+    out.push("", "DEVIATIONS  (element | property | expected -> actual | delta)", ...rows);
+  } else {
+    out.push("", "NO GEOMETRY ISSUES - nothing to change on this screen.");
+  }
+  if (shared.length) out.push("", "SHARED ROOT CAUSE", ...shared);
+  if (advs.length) {
+    out.push("", "DO NOT CHANGE  (advisory / not a defect)");
+    for (const f of advs) out.push(`  - ${f.element}: ${f.detail}`);
+  }
+  out.push("", "RULES",
+    "  - Fix only the properties listed above.",
+    "  - Values are POINTS, already normalised for the device/design width difference.",
+    "  - Prefer changing a spacing/padding token over hardcoding a number.",
+    "  - Content/copy and row counts come from mock fixtures; do not 'fix' those.");
+  return out.filter((l) => l !== "").join("\n");
+}
+
+function variantSection(v, idx, fileKey, L) {
+  const findings = v.findings || [];
+  // An advisory (content-driven height, unmeasurable font family) is context, not
+  // a defect. Counting it as a deviation buries the real insets and gaps under
+  // noise, so it gets its own uncounted group.
+  const devs = findings.filter((f) => (f.status || "deviation") !== "verified" && !f.advisory);
+  const advisories = findings.filter((f) => f.advisory && f.status !== "verified");
+  const verified = findings.filter((f) => f.status === "verified");
+  const grouped = groupFindings(devs);
+  let devPin = 0;
+  const devGroups = Object.entries(grouped).map(([cat, list]) => `
+    <div class="grp"><h4 style="color:${catColor(cat)}">${esc(cat.toUpperCase())} <span>(${list.length})</span></h4>
+    <ul class="findings">${list.map((f) => findingLine(f, devPin++, L)).join("")}</ul></div>`).join("");
+  // An advisory exists to say "do not act on this". Printing each one as a full
+  // card beside the real findings doubles the page for the same elements and
+  // gives the reader nothing to do, so it collapses to one line they can open.
+  const advGroups = advisories.length ? `
+    <details class="grp adv"><summary style="color:#8a6d00;font-weight:700;font-size:12px;cursor:pointer">${esc(L.advisoryWord)} (${advisories.length})</summary>
+    <ul class="findings">${advisories.map((f) => findingLine(f, null, L)).join("")}</ul></details>` : "";
+  const okGroups = (verified.length ? `
+    <div class="grp verified"><h4 style="color:#0A7D33">${esc(L.verifiedOnSpec)} (${verified.length})</h4>
+    <ul class="findings">${verified.map((f) => findingLine(f, null, L)).join("")}</ul></div>` : "") + advGroups;
+
+  return `<section class="variant">
+    <h2>${idx + 1}. ${esc(v.name)} ${v.passed === null ? `<span class="cap">${esc(L.awaitingFigma)}</span>` : (devs.length > 0 ? `<span class="fail">${devs.length} ${esc(L.deviationsWord)}</span>` : `<span class="cap">${esc(L.noAutoFindings)}</span>`)}
+      <small>node ${esc(v.figmaNodeId || "-")}${v.perceptualPct === "-" ? "" : " · perceptual " + esc(v.perceptualPct) + "%"}</small></h2>
+    ${twoUp(v, fileKey, L)}
+    ${componentsBlock(v, fileKey, L)}
+    <div class="groups">${devGroups || `<p class="clean">${esc(L.noDeviations)}</p>`}${okGroups}</div>
+    ${(() => { const fp = buildFixPrompt(v) || v.fixPrompt; return fp ? `<details class="fix" open><summary>${esc(L.fixPromptTitle)}</summary><pre>${esc(fp)}</pre></details>` : ""; })()}
+  </section>`;
+}
+
+function coverageSection(cv, L) {
+  if (!cv) return "";
+  const pct = Math.round(cv.pct * 100);
+  const fail = cv.gate === "fail";
+  const byGroup = (list) => {
+    const m = new Map();
+    for (const e of list) {
+      const g = e.group || "-";
+      if (!m.has(g)) m.set(g, []);
+      m.get(g).push(e);
+    }
+    return [...m.entries()];
+  };
+  const line = (e, withReason) => {
+    if (!e.id && e.count) return `<li><span class="norsn">${e.count} × ${esc(L.coverageUndeclared)}</span></li>`;
+    return `<li>${esc(e.id || "-")}${withReason ? ` - <i>${esc(e.reason)}</i>` : ` - <span class="norsn">${esc(L.coverageNoReason)}</span>`}</li>`;
+  };
+  const block = (title, list, withReason) => list.length ? `<div class="covgrp"><h4>${esc(title)} <span>(${tally(list)})</span></h4>
+    ${byGroup(list).map(([g, items]) => `<div class="covsub"><b>${esc(g)}</b><ul>${items.map((e) => line(e, withReason)).join("")}</ul></div>`).join("")}</div>` : "";
+
+  return `<section class="coverage ${fail ? "covfail" : "covpass"}">
+  <h2>${esc(L.coverageTitle)}
+    <span class="covbadge ${fail ? "bad" : "good"}">${esc(fail ? L.coverageGateFail : L.coverageGatePass)}</span>
+    <small>${esc(L.coverageGateHint)}</small></h2>
+  <div class="covbar"><div class="covfill" style="width:${pct}%"></div></div>
+  <p class="covnum"><b>${cv.audited}</b> ${esc(L.coverageAudited)} / <b>${cv.target}</b> ${esc(L.coverageTargets)} · ${pct}%${cv.belowFloor ? ` · <span class="fail">${esc(L.coverageBelowFloor)} (${Math.round(cv.floor * 100)}%)</span>` : ""}</p>
+  ${cv.truncatedInventory ? `<p class="covnum"><span class="fail">${esc(L.coverageTruncated)}</span></p>` : ""}
+  ${block(L.coverageSkipped, cv.skipped, true)}
+  ${block(L.coverageUnaccounted, cv.unaccounted, false)}
+  </section>`;
+}
+
+export function renderHtml(report) {
+  const L = labels(report);
+  const variants = report.variants || [];
+  const fileKey = report.figmaFileKey || null;
+  const totalDev = variants.reduce((n, v) => n + (v.findings || []).filter((f) => f.status !== "verified" && !f.advisory).length, 0);
+  // Must exclude advisories on the same terms as totalDev and variantSection's
+  // devs: this drives the per-screen status label and the fail class, so counting
+  // them here made a screen whose only finding was advisory render as DEVIATION
+  // under a header that said 0 deviations.
+  const devCount = (v) => (v.findings || []).filter((f) => f.status !== "verified" && !f.advisory).length;
+  const statusLabel = (v) => v.passed === null ? L.statusCaptured : (devCount(v) > 0 ? L.statusDeviation : (v.perceptualPct === "-" ? L.statusPass : L.statusReview));
+  const statusCls = (v) => v.passed === null ? "" : (devCount(v) > 0 ? "fail" : "");
+  const rows = variants.map((v, i) => `<tr><td>${i + 1}. ${esc(v.name)}</td><td>${v.perceptualPct === "-" ? "-" : esc(v.perceptualPct) + "%"}</td>
+    <td>${devCount(v)}</td>
+    <td class="${statusCls(v)}">${esc(statusLabel(v))}</td></tr>`).join("");
+  const cv = coverageVerdict(report.coverage, variants.length);
+
+  return `<!doctype html><html lang="${esc(L.htmlLang)}"><head><meta charset="utf-8">
+<title>Design Check - ${esc(report.project)} / ${esc(report.module)}</title>
+<style>
+:root{--fg:#1a1a1a;--muted:#666;--line:#e5e5e5;--card:#fafafa}
+*{box-sizing:border-box}body{font:14px/1.5 -apple-system,Segoe UI,Roboto,sans-serif;color:var(--fg);margin:0;padding:32px;max-width:1180px;margin-inline:auto;background:#fff}
+h1{font-size:22px;margin:0 0 4px}.sub{color:var(--muted);margin:0 0 20px}
+table{border-collapse:collapse;width:100%;margin-bottom:28px}th,td{text-align:left;padding:8px 12px;border-bottom:1px solid var(--line)}
+th{font-size:12px;text-transform:uppercase;letter-spacing:.04em;color:var(--muted)}
+.pass{color:#0A7D33;font-weight:700}.fail{color:#cf222e;font-weight:700}.cap{color:#7A5AF8;font-weight:600;font-size:13px}
+.variant{border:1px solid var(--line);border-radius:12px;padding:20px;margin-bottom:28px;background:var(--card)}
+.variant h2{font-size:17px;margin:0 0 14px}.variant h2 small{display:block;font-weight:400;color:var(--muted);font-size:12px;margin-top:2px}
+.twoup{overflow-x:auto;background:#fff;border:1px solid var(--line);border-radius:8px;padding:12px;margin-bottom:16px}
+.groups{display:flex;flex-wrap:wrap;gap:20px}.grp{min-width:280px;flex:1}.grp.adv{min-width:100%;flex:0 0 100%;margin-top:6px}.grp.adv summary{outline:none}
+.grp h4{font-size:12px;letter-spacing:.04em;margin:0 0 6px}.grp h4 span{color:var(--muted);font-weight:400}
+ul.findings{margin:0;padding:0;list-style:none}
+.finding{display:flex;gap:8px;align-items:baseline;padding:5px 0;border-bottom:1px dashed var(--line)}
+.mark{font-weight:700;min-width:16px;text-align:center}
+.fel{font-weight:600}.exp{color:var(--fg)}.exp b{color:#cf222e}.detail{color:var(--muted)}
+code{background:#eee;padding:1px 5px;border-radius:4px;font-size:12px}
+.verified .fel{color:#0A7D33}
+.clean{color:#0A7D33}
+.fix{margin-top:14px}.fix summary{cursor:pointer;font-weight:600;font-size:13px}
+.fix pre{background:#0d1117;color:#e6edf3;padding:14px;border-radius:8px;overflow:auto;font-size:12px;white-space:pre-wrap}
+.components{margin:8px 0 16px}.components h4{font-size:12px;letter-spacing:.04em;color:var(--muted);margin:0 0 8px}
+.cvcomp{border:1px solid var(--line);border-radius:8px;padding:8px 12px;margin-bottom:8px;background:#fff}
+.cvcomp summary{cursor:pointer;font-size:13px}.cvcomp summary b{color:#7A5AF8}.cvhint{color:var(--muted);font-weight:400;font-size:11px}
+.cvgrid{display:flex;flex-wrap:wrap;gap:12px;margin-top:12px}
+.cvgrid figure{margin:0;text-align:center}.cvgrid img{height:150px;border:1px solid var(--line);border-radius:6px;display:block}
+.cvgrid figcaption{font-size:11px;color:var(--muted);margin-top:4px;max-width:160px}
+.cvnote{color:var(--muted);font-size:12px;margin:10px 0 2px}
+a{color:#0A66C2;text-decoration:none}a:hover{text-decoration:underline}
+.coverage{border-radius:12px;padding:20px;margin-bottom:28px}
+.covfail{border:2px solid #cf222e;background:#fff5f5}.covpass{border:1px solid #0A7D33;background:#f6fff8}
+.coverage h2{font-size:16px;margin:0 0 12px}.coverage h2 small{display:block;font-weight:400;color:var(--muted);font-size:12px;margin-top:3px}
+.covbadge{font-size:11px;font-weight:700;padding:3px 9px;border-radius:10px;margin-left:8px;vertical-align:middle}
+.covbadge.bad{background:#cf222e;color:#fff}.covbadge.good{background:#0A7D33;color:#fff}
+.covbar{height:8px;border-radius:4px;background:#e9e9e9;overflow:hidden;margin-bottom:8px}
+.covfill{height:100%;background:#0A7D33}.covfail .covfill{background:#cf222e}
+.covnum{margin:0 0 14px;font-size:13px;color:#333}
+.covgrp{margin-bottom:14px}.covgrp h4{margin:0 0 6px;font-size:13px}.covgrp h4 span{color:var(--muted);font-weight:400}
+.covsub{margin:0 0 8px}.covsub b{font-size:12px;color:#444}
+.covsub ul{margin:2px 0 0;padding-left:18px;font-size:12.5px;color:#444}
+.covsub i{color:var(--muted);font-style:normal}
+.norsn{color:#cf222e;font-weight:600}
+footer{color:var(--muted);font-size:12px;margin-top:24px}
+</style></head><body>
+<h1>${esc(L.reportTitle)}</h1>
+<p class="sub">${esc(report.project)} · ${esc(L.moduleWord)} <b>${esc(report.module)}</b> · ${esc(report.platform || "")} · ${esc(report.timestamp)}<br>
+${report.figmaUrl ? `Figma: <a href="${esc(report.figmaUrl)}">${esc(report.figmaUrl)}</a>` : ""}</p>
+${coverageSection(cv, L)}
+<table><thead><tr><th>${esc(L.thScreen)}</th><th>${esc(L.thPerceptual)}</th><th>${esc(L.thDeviations)}</th><th>${esc(L.thStatus)}</th></tr></thead><tbody>${rows}</tbody></table>
+<p class="sub">${variants.length} ${esc(L.screensWord)} · ${totalDev} ${esc(L.deviationsWord)}</p>
+${variants.map((v, i) => variantSection(v, i, fileKey, L)).join("")}
+<footer>${esc(L.footerNote)}</footer>
+</body></html>`;
+}
+
+export async function writeReport({ report, outDir, formats = ["html"] }) {
+  const html = renderHtml(report);
+  const out = {};
+  const cv = coverageVerdict(report.coverage, (report.variants || []).length);
+  if (cv) {
+    out.coverage = {
+      gate: cv.gate, audited: cv.audited, target: cv.target,
+      pct: Math.round(cv.pct * 1000) / 10,
+      skippedWithReason: cv.skipped.length,
+      unaccounted: cv.unaccountedCount,
+      unaccountedIds: cv.unaccounted.map((e) => e.id).filter(Boolean),
+    };
+    out.coverage.truncatedInventory = cv.truncatedInventory;
+    if (cv.gate === "fail") {
+      out.coverageError = cv.truncatedInventory
+        ? "Coverage gate FAILED: the scenario inventory was truncated, so the target set is incomplete and coverage cannot be verified."
+        : cv.belowFloor
+        ? `Coverage gate FAILED: ${cv.audited}/${cv.target} audited (${Math.round(cv.pct * 100)}%), below the ${Math.round(cv.floor * 100)}% floor.`
+        : `Coverage gate FAILED: ${cv.unaccountedCount} of ${cv.target} targets were neither audited nor skipped with a reason.`;
+    }
+  }
+  if (formats.includes("html") || formats.includes("confluence")) {
+    out.html = join(outDir, "report.html");
+    writeFileSync(out.html, html, "utf-8");
+  }
+  if (formats.includes("pdf")) {
+    const pdfPath = join(outDir, "report.pdf");
+    let ok = false, err = "";
+    try {
+      const { chromium } = await import("playwright");
+      const browser = await chromium.launch();
+      const page = await browser.newPage();
+      await page.setContent(html, { waitUntil: "networkidle" });
+      await page.pdf({ path: pdfPath, format: "A4", printBackground: true, margin: { top: "12mm", bottom: "12mm", left: "10mm", right: "10mm" } });
+      await browser.close(); ok = true;
+    } catch (e) {
+      err = e.message;
+      // Fallback: use the chrome-headless-shell binary directly (no `playwright` package).
+      try {
+        const { execSync } = await import("node:child_process");
+        const bin = execSync('ls -d "$HOME"/Library/Caches/ms-playwright/chromium_headless_shell-*/chrome-headless-shell-*/chrome-headless-shell 2>/dev/null | head -1', { encoding: "utf-8", shell: "/bin/bash" }).trim();
+        if (bin && existsSync(bin)) {
+          const htmlPath = join(outDir, ".report-print.html");
+          writeFileSync(htmlPath, html, "utf-8");
+          execSync(`"${bin}" --headless --disable-gpu --no-sandbox --no-pdf-header-footer --print-to-pdf="${pdfPath}" "file://${htmlPath}"`, { timeout: 90000 });
+          ok = existsSync(pdfPath);
+        }
+      } catch (e2) { err += " | headless-shell: " + e2.message; }
+    }
+    if (ok) out.pdf = pdfPath; else out.pdfError = `PDF skipped (${err}).`;
+  }
+  return out;
+}