@spectratools/graphic-designer-cli 0.3.2 → 0.6.0

package/dist/qa.d.ts

@@ -1,15 +1,24 @@
-import { R as RenderMetadata, D as DesignSpec } from './spec.schema-DhAI-tE8.js';
+import { R as RenderMetadata, D as DesignSpec } from './spec.schema-Dm_wOLTd.js';
 import 'zod';
 import '@napi-rs/canvas';
 
 type QaSeverity = 'error' | 'warning';
 type QaIssue = {
-    code: 'DIMENSIONS_MISMATCH' | 'ELEMENT_CLIPPED' | 'ELEMENT_OVERLAP' | 'LOW_CONTRAST' | 'FOOTER_SPACING' | 'TEXT_TRUNCATED' | 'MISSING_LAYOUT' | 'DRAW_OUT_OF_BOUNDS';
+    code: 'DIMENSIONS_MISMATCH' | 'ELEMENT_CLIPPED' | 'ELEMENT_OVERLAP' | 'LOW_CONTRAST' | 'FOOTER_SPACING' | 'TEXT_TRUNCATED' | 'MISSING_LAYOUT' | 'DRAW_OUT_OF_BOUNDS' | 'REFERENCE_MISMATCH';
     severity: QaSeverity;
     message: string;
     elementId?: string;
     details?: Record<string, number | string | boolean>;
 };
+type QaReferenceResult = {
+    similarity: number;
+    verdict: 'match' | 'close' | 'mismatch';
+    regions: Array<{
+        label: string;
+        similarity: number;
+        description?: string;
+    }>;
+};
 type QaReport = {
     pass: boolean;
     checkedAt: string;
@@ -27,6 +36,7 @@ type QaReport = {
         footerSpacingPx?: number;
     };
     issues: QaIssue[];
+    reference?: QaReferenceResult;
 };
 /**
  * Read and parse a sidecar `.meta.json` file produced by
@@ -57,6 +67,7 @@ declare function runQa(options: {
     imagePath: string;
     spec: DesignSpec;
     metadata?: RenderMetadata;
+    referencePath?: string;
 }): Promise<QaReport>;
 
-export { type QaIssue, type QaReport, type QaSeverity, readMetadata, runQa };
+export { type QaIssue, type QaReferenceResult, type QaReport, type QaSeverity, readMetadata, runQa };

package/dist/qa.js

@@ -1,7 +1,154 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/compare.ts
+var compare_exports = {};
+__export(compare_exports, {
+  compareImages: () => compareImages
+});
+import sharp from "sharp";
+function clampUnit(value) {
+  if (value < 0) {
+    return 0;
+  }
+  if (value > 1) {
+    return 1;
+  }
+  return value;
+}
+function toRegionLabel(row, column) {
+  const letter = String.fromCharCode(65 + row);
+  return `${letter}${column + 1}`;
+}
+function validateGrid(grid) {
+  if (!Number.isInteger(grid) || grid <= 0) {
+    throw new Error(`Invalid grid value "${grid}". Expected a positive integer.`);
+  }
+  if (grid > 26) {
+    throw new Error(`Invalid grid value "${grid}". Maximum supported grid is 26.`);
+  }
+  return grid;
+}
+function validateThreshold(threshold) {
+  if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+    throw new Error(`Invalid threshold value "${threshold}". Expected a number between 0 and 1.`);
+  }
+  return threshold;
+}
+async function readDimensions(path) {
+  const metadata = await sharp(path).metadata();
+  if (!metadata.width || !metadata.height) {
+    throw new Error(`Unable to read image dimensions for "${path}".`);
+  }
+  return {
+    width: metadata.width,
+    height: metadata.height
+  };
+}
+async function normalizeToRaw(path, width, height) {
+  const normalized = await sharp(path).rotate().resize(width, height, {
+    fit: "contain",
+    position: "centre",
+    background: { r: 0, g: 0, b: 0, alpha: 0 }
+  }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  return {
+    data: normalized.data,
+    width: normalized.info.width,
+    height: normalized.info.height
+  };
+}
+function scorePixelDifference(a, b, offset) {
+  const redDiff = Math.abs(a.data[offset] - b.data[offset]);
+  const greenDiff = Math.abs(a.data[offset + 1] - b.data[offset + 1]);
+  const blueDiff = Math.abs(a.data[offset + 2] - b.data[offset + 2]);
+  const alphaDiff = Math.abs(a.data[offset + 3] - b.data[offset + 3]);
+  const rgbDelta = (redDiff + greenDiff + blueDiff) / (3 * 255);
+  const alphaDelta = alphaDiff / 255;
+  return rgbDelta * 0.75 + alphaDelta * 0.25;
+}
+async function compareImages(target, rendered, options = {}) {
+  const grid = validateGrid(options.grid ?? DEFAULT_GRID);
+  const threshold = validateThreshold(options.threshold ?? DEFAULT_THRESHOLD);
+  const closeThreshold = clampUnit(threshold - (options.closeMargin ?? DEFAULT_CLOSE_MARGIN));
+  const targetDimensions = await readDimensions(target);
+  const renderedDimensions = await readDimensions(rendered);
+  const normalizedWidth = Math.max(targetDimensions.width, renderedDimensions.width);
+  const normalizedHeight = Math.max(targetDimensions.height, renderedDimensions.height);
+  const [targetImage, renderedImage] = await Promise.all([
+    normalizeToRaw(target, normalizedWidth, normalizedHeight),
+    normalizeToRaw(rendered, normalizedWidth, normalizedHeight)
+  ]);
+  const regionDiffSums = new Array(grid * grid).fill(0);
+  const regionCounts = new Array(grid * grid).fill(0);
+  let totalDiff = 0;
+  for (let y = 0; y < normalizedHeight; y += 1) {
+    const row = Math.min(Math.floor(y * grid / normalizedHeight), grid - 1);
+    for (let x = 0; x < normalizedWidth; x += 1) {
+      const column = Math.min(Math.floor(x * grid / normalizedWidth), grid - 1);
+      const regionIndex = row * grid + column;
+      const offset = (y * normalizedWidth + x) * 4;
+      const diff = scorePixelDifference(targetImage, renderedImage, offset);
+      totalDiff += diff;
+      regionDiffSums[regionIndex] += diff;
+      regionCounts[regionIndex] += 1;
+    }
+  }
+  const pixelCount = normalizedWidth * normalizedHeight;
+  const similarity = clampUnit(1 - totalDiff / pixelCount);
+  const regions = [];
+  for (let row = 0; row < grid; row += 1) {
+    for (let column = 0; column < grid; column += 1) {
+      const regionIndex = row * grid + column;
+      const regionCount = regionCounts[regionIndex];
+      const regionSimilarity = regionCount > 0 ? clampUnit(1 - regionDiffSums[regionIndex] / regionCount) : 1;
+      regions.push({
+        label: toRegionLabel(row, column),
+        row,
+        column,
+        similarity: regionSimilarity
+      });
+    }
+  }
+  const verdict = similarity >= threshold ? "match" : similarity >= closeThreshold ? "close" : "mismatch";
+  return {
+    targetPath: target,
+    renderedPath: rendered,
+    targetDimensions,
+    renderedDimensions,
+    normalizedDimensions: {
+      width: normalizedWidth,
+      height: normalizedHeight
+    },
+    dimensionMismatch: targetDimensions.width !== renderedDimensions.width || targetDimensions.height !== renderedDimensions.height,
+    grid,
+    threshold,
+    closeThreshold,
+    similarity,
+    verdict,
+    regions
+  };
+}
+var DEFAULT_GRID, DEFAULT_THRESHOLD, DEFAULT_CLOSE_MARGIN;
+var init_compare = __esm({
+  "src/compare.ts"() {
+    "use strict";
+    DEFAULT_GRID = 3;
+    DEFAULT_THRESHOLD = 0.8;
+    DEFAULT_CLOSE_MARGIN = 0.1;
+  }
+});
+
 // src/qa.ts
 import { readFile } from "fs/promises";
 import { resolve } from "path";
-import sharp from "sharp";
+import sharp2 from "sharp";
 
 // src/code-style.ts
 var CARBON_SURROUND_COLOR = "rgba(171, 184, 195, 1)";
@@ -62,7 +209,98 @@ import { z as z2 } from "zod";
 
 // src/themes/builtin.ts
 import { z } from "zod";
-var colorHexSchema = z.string().regex(/^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "Expected #RRGGBB or #RRGGBBAA color");
+
+// src/utils/color.ts
+function parseChannel(hex, offset) {
+  return Number.parseInt(hex.slice(offset, offset + 2), 16);
+}
+function parseHexColor(hexColor) {
+  const normalized = hexColor.startsWith("#") ? hexColor.slice(1) : hexColor;
+  if (normalized.length !== 6 && normalized.length !== 8) {
+    throw new Error(`Unsupported color format: ${hexColor}`);
+  }
+  return {
+    r: parseChannel(normalized, 0),
+    g: parseChannel(normalized, 2),
+    b: parseChannel(normalized, 4)
+  };
+}
+var rgbaRegex = /^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*([01](?:\.\d+)?|0?\.\d+)\s*)?\)$/;
+var hexColorRegex = /^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function toHex(n) {
+  return n.toString(16).padStart(2, "0");
+}
+function parseRgbaToHex(color) {
+  const match = rgbaRegex.exec(color);
+  if (!match) {
+    throw new Error(`Invalid rgb/rgba color: ${color}`);
+  }
+  const r = Number.parseInt(match[1], 10);
+  const g = Number.parseInt(match[2], 10);
+  const b = Number.parseInt(match[3], 10);
+  if (r > 255 || g > 255 || b > 255) {
+    throw new Error(`RGB channel values must be 0-255, got: ${color}`);
+  }
+  if (match[4] !== void 0) {
+    const a = Number.parseFloat(match[4]);
+    if (a < 0 || a > 1) {
+      throw new Error(`Alpha value must be 0-1, got: ${a}`);
+    }
+    const alphaByte = Math.round(a * 255);
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}${toHex(alphaByte)}`;
+  }
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+function isRgbaColor(color) {
+  return rgbaRegex.test(color);
+}
+function isHexColor(color) {
+  return hexColorRegex.test(color);
+}
+function normalizeColor(color) {
+  if (isHexColor(color)) {
+    return color;
+  }
+  if (isRgbaColor(color)) {
+    return parseRgbaToHex(color);
+  }
+  throw new Error(`Expected #RRGGBB, #RRGGBBAA, rgb(), or rgba() color, got: ${color}`);
+}
+function srgbToLinear(channel) {
+  const normalized = channel / 255;
+  if (normalized <= 0.03928) {
+    return normalized / 12.92;
+  }
+  return ((normalized + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance(hexColor) {
+  const normalized = isRgbaColor(hexColor) ? parseRgbaToHex(hexColor) : hexColor;
+  const rgb = parseHexColor(normalized);
+  const r = srgbToLinear(rgb.r);
+  const g = srgbToLinear(rgb.g);
+  const b = srgbToLinear(rgb.b);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function contrastRatio(foreground, background) {
+  const fg = relativeLuminance(foreground);
+  const bg = relativeLuminance(background);
+  const lighter = Math.max(fg, bg);
+  const darker = Math.min(fg, bg);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// src/themes/builtin.ts
+var colorHexSchema = z.string().refine(
+  (v) => {
+    try {
+      normalizeColor(v);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  { message: "Expected #RRGGBB, #RRGGBBAA, rgb(), or rgba() color" }
+).transform((v) => normalizeColor(v));
 var fontFamilySchema = z.string().min(1).max(120);
 var codeThemeSchema = z.object({
   background: colorHexSchema,
@@ -235,7 +473,17 @@ var builtInThemes = {
 var defaultTheme = builtInThemes.dark;
 
 // src/spec.schema.ts
-var colorHexSchema2 = z2.string().regex(/^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "Expected #RRGGBB or #RRGGBBAA color");
+var colorHexSchema2 = z2.string().refine(
+  (v) => {
+    try {
+      normalizeColor(v);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  { message: "Expected #RRGGBB, #RRGGBBAA, rgb(), or rgba() color" }
+).transform((v) => normalizeColor(v));
 var gradientStopSchema = z2.object({
   offset: z2.number().min(0).max(1),
   color: colorHexSchema2
@@ -419,13 +667,32 @@ var cardElementSchema = z2.object({
   tone: z2.enum(["neutral", "accent", "success", "warning", "error"]).default("neutral"),
   icon: z2.string().min(1).max(64).optional()
 }).strict();
+var flowNodeShadowSchema = z2.object({
+  color: colorHexSchema2.optional(),
+  blur: z2.number().min(0).max(64).default(8),
+  offsetX: z2.number().min(-32).max(32).default(0),
+  offsetY: z2.number().min(-32).max(32).default(0),
+  opacity: z2.number().min(0).max(1).default(0.3)
+}).strict();
 var flowNodeElementSchema = z2.object({
   type: z2.literal("flow-node"),
   id: z2.string().min(1).max(120),
-  shape: z2.enum(["box", "rounded-box", "diamond", "circle", "pill", "cylinder", "parallelogram"]),
+  shape: z2.enum([
+    "box",
+    "rounded-box",
+    "diamond",
+    "circle",
+    "pill",
+    "cylinder",
+    "parallelogram",
+    "hexagon"
+  ]).default("rounded-box"),
   label: z2.string().min(1).max(200),
   sublabel: z2.string().min(1).max(300).optional(),
   sublabelColor: colorHexSchema2.optional(),
+  sublabel2: z2.string().min(1).max(300).optional(),
+  sublabel2Color: colorHexSchema2.optional(),
+  sublabel2FontSize: z2.number().min(8).max(32).optional(),
   labelColor: colorHexSchema2.optional(),
   labelFontSize: z2.number().min(10).max(48).optional(),
   color: colorHexSchema2.optional(),
@@ -434,20 +701,30 @@ var flowNodeElementSchema = z2.object({
   cornerRadius: z2.number().min(0).max(64).optional(),
   width: z2.number().int().min(40).max(800).optional(),
   height: z2.number().int().min(30).max(600).optional(),
-  opacity: z2.number().min(0).max(1).default(1)
+  fillOpacity: z2.number().min(0).max(1).default(1),
+  opacity: z2.number().min(0).max(1).default(1),
+  badgeText: z2.string().min(1).max(32).optional(),
+  badgeColor: colorHexSchema2.optional(),
+  badgeBackground: colorHexSchema2.optional(),
+  badgePosition: z2.enum(["top", "inside-top"]).default("inside-top"),
+  shadow: flowNodeShadowSchema.optional()
 }).strict();
 var connectionElementSchema = z2.object({
   type: z2.literal("connection"),
   from: z2.string().min(1).max(120),
   to: z2.string().min(1).max(120),
   style: z2.enum(["solid", "dashed", "dotted"]).default("solid"),
+  strokeStyle: z2.enum(["solid", "dashed", "dotted"]).default("solid"),
   arrow: z2.enum(["end", "start", "both", "none"]).default("end"),
   label: z2.string().min(1).max(200).optional(),
   labelPosition: z2.enum(["start", "middle", "end"]).default("middle"),
   color: colorHexSchema2.optional(),
-  width: z2.number().min(0.5).max(8).optional(),
+  width: z2.number().min(0.5).max(10).optional(),
+  strokeWidth: z2.number().min(0.5).max(10).default(2),
   arrowSize: z2.number().min(4).max(32).optional(),
-  opacity: z2.number().min(0).max(1).default(1)
+  opacity: z2.number().min(0).max(1).default(1),
+  routing: z2.enum(["auto", "orthogonal", "curve", "arc"]).default("auto"),
+  tension: z2.number().min(0.1).max(0.8).default(0.35)
 }).strict();
 var codeBlockStyleSchema = z2.object({
   paddingVertical: z2.number().min(0).max(128).default(56),
@@ -516,6 +793,10 @@ var elementSchema = z2.discriminatedUnion("type", [
   shapeElementSchema,
   imageElementSchema
 ]);
+var diagramCenterSchema = z2.object({
+  x: z2.number(),
+  y: z2.number()
+}).strict();
 var autoLayoutConfigSchema = z2.object({
   mode: z2.literal("auto"),
   algorithm: z2.enum(["layered", "stress", "force", "radial", "box"]).default("layered"),
@@ -523,7 +804,17 @@ var autoLayoutConfigSchema = z2.object({
   nodeSpacing: z2.number().int().min(0).max(512).default(80),
   rankSpacing: z2.number().int().min(0).max(512).default(120),
   edgeRouting: z2.enum(["orthogonal", "polyline", "spline"]).default("polyline"),
-  aspectRatio: z2.number().min(0.5).max(3).optional()
+  aspectRatio: z2.number().min(0.5).max(3).optional(),
+  /** ID of the root node for radial layout. Only relevant when algorithm is 'radial'. */
+  radialRoot: z2.string().min(1).max(120).optional(),
+  /** Fixed radius in pixels for radial layout. Only relevant when algorithm is 'radial'. */
+  radialRadius: z2.number().positive().optional(),
+  /** Compaction strategy for radial layout. Only relevant when algorithm is 'radial'. */
+  radialCompaction: z2.enum(["none", "radial", "wedge"]).optional(),
+  /** Sort strategy for radial layout node ordering. Only relevant when algorithm is 'radial'. */
+  radialSortBy: z2.enum(["id", "connections"]).optional(),
+  /** Explicit center used by curve/arc connection routing. */
+  diagramCenter: diagramCenterSchema.optional()
 }).strict();
 var gridLayoutConfigSchema = z2.object({
   mode: z2.literal("grid"),
@@ -531,13 +822,17 @@ var gridLayoutConfigSchema = z2.object({
   gap: z2.number().int().min(0).max(256).default(24),
   cardMinHeight: z2.number().int().min(32).max(4096).optional(),
   cardMaxHeight: z2.number().int().min(32).max(4096).optional(),
-  equalHeight: z2.boolean().default(false)
+  equalHeight: z2.boolean().default(false),
+  /** Explicit center used by curve/arc connection routing. */
+  diagramCenter: diagramCenterSchema.optional()
 }).strict();
 var stackLayoutConfigSchema = z2.object({
   mode: z2.literal("stack"),
   direction: z2.enum(["vertical", "horizontal"]).default("vertical"),
   gap: z2.number().int().min(0).max(256).default(24),
-  alignment: z2.enum(["start", "center", "end", "stretch"]).default("stretch")
+  alignment: z2.enum(["start", "center", "end", "stretch"]).default("stretch"),
+  /** Explicit center used by curve/arc connection routing. */
+  diagramCenter: diagramCenterSchema.optional()
 }).strict();
 var manualPositionSchema = z2.object({
   x: z2.number().int(),
@@ -547,7 +842,9 @@ var manualPositionSchema = z2.object({
 }).strict();
 var manualLayoutConfigSchema = z2.object({
   mode: z2.literal("manual"),
-  positions: z2.record(z2.string().min(1), manualPositionSchema).default({})
+  positions: z2.record(z2.string().min(1), manualPositionSchema).default({}),
+  /** Explicit center used by curve/arc connection routing. */
+  diagramCenter: diagramCenterSchema.optional()
 }).strict();
 var layoutConfigSchema = z2.discriminatedUnion("mode", [
   autoLayoutConfigSchema,
@@ -599,6 +896,31 @@ var canvasSchema = z2.object({
   padding: z2.number().int().min(0).max(256).default(defaultCanvas.padding)
 }).strict();
 var themeInputSchema = z2.union([builtInThemeSchema, themeSchema]);
+var diagramPositionSchema = z2.object({
+  x: z2.number(),
+  y: z2.number(),
+  width: z2.number().positive(),
+  height: z2.number().positive()
+}).strict();
+var diagramElementSchema = z2.discriminatedUnion("type", [
+  flowNodeElementSchema,
+  connectionElementSchema
+]);
+var diagramLayoutSchema = z2.object({
+  mode: z2.enum(["manual", "auto"]).default("manual"),
+  positions: z2.record(z2.string(), diagramPositionSchema).optional(),
+  diagramCenter: diagramCenterSchema.optional()
+}).strict();
+var diagramSpecSchema = z2.object({
+  version: z2.literal(1),
+  canvas: z2.object({
+    width: z2.number().int().min(320).max(4096).default(1200),
+    height: z2.number().int().min(180).max(4096).default(675)
+  }).default({ width: 1200, height: 675 }),
+  theme: themeSchema.optional(),
+  elements: z2.array(diagramElementSchema).min(1),
+  layout: diagramLayoutSchema.default({ mode: "manual" })
+}).strict();
 var designSpecSchema = z2.object({
   version: z2.literal(2).default(2),
   canvas: canvasSchema.default(defaultCanvas),
@@ -627,43 +949,6 @@ function parseDesignSpec(input) {
   return designSpecSchema.parse(input);
 }
 
-// src/utils/color.ts
-function parseChannel(hex, offset) {
-  return Number.parseInt(hex.slice(offset, offset + 2), 16);
-}
-function parseHexColor(hexColor) {
-  const normalized = hexColor.startsWith("#") ? hexColor.slice(1) : hexColor;
-  if (normalized.length !== 6 && normalized.length !== 8) {
-    throw new Error(`Unsupported color format: ${hexColor}`);
-  }
-  return {
-    r: parseChannel(normalized, 0),
-    g: parseChannel(normalized, 2),
-    b: parseChannel(normalized, 4)
-  };
-}
-function srgbToLinear(channel) {
-  const normalized = channel / 255;
-  if (normalized <= 0.03928) {
-    return normalized / 12.92;
-  }
-  return ((normalized + 0.055) / 1.055) ** 2.4;
-}
-function relativeLuminance(hexColor) {
-  const rgb = parseHexColor(hexColor);
-  const r = srgbToLinear(rgb.r);
-  const g = srgbToLinear(rgb.g);
-  const b = srgbToLinear(rgb.b);
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-function contrastRatio(foreground, background) {
-  const fg = relativeLuminance(foreground);
-  const bg = relativeLuminance(background);
-  const lighter = Math.max(fg, bg);
-  const darker = Math.min(fg, bg);
-  return (lighter + 0.05) / (darker + 0.05);
-}
-
 // src/qa.ts
 function rectWithin(outer, inner) {
   return inner.x >= outer.x && inner.y >= outer.y && inner.x + inner.width <= outer.x + outer.width && inner.y + inner.height <= outer.y + outer.height;
@@ -709,7 +994,7 @@ async function runQa(options) {
   const imagePath = resolve(options.imagePath);
   const expectedSafeFrame = deriveSafeFrame(spec);
   const expectedCanvas = canvasRect(spec);
-  const imageMetadata = await sharp(imagePath).metadata();
+  const imageMetadata = await sharp2(imagePath).metadata();
   const issues = [];
   const expectedScale = options.metadata?.canvas.scale ?? resolveRenderScale(spec);
   const expectedWidth = spec.canvas.width * expectedScale;
@@ -860,6 +1145,31 @@ async function runQa(options) {
       });
     }
   }
+  let referenceResult;
+  if (options.referencePath) {
+    const { compareImages: compareImages2 } = await Promise.resolve().then(() => (init_compare(), compare_exports));
+    const comparison = await compareImages2(options.referencePath, imagePath);
+    referenceResult = {
+      similarity: comparison.similarity,
+      verdict: comparison.verdict,
+      regions: comparison.regions.map((region) => ({
+        label: region.label,
+        similarity: region.similarity
+      }))
+    };
+    if (comparison.verdict === "mismatch") {
+      const severity = comparison.similarity < 0.5 ? "error" : "warning";
+      issues.push({
+        code: "REFERENCE_MISMATCH",
+        severity,
+        message: `Reference image comparison ${severity === "error" ? "failed" : "warned"}: similarity ${comparison.similarity.toFixed(4)} with verdict "${comparison.verdict}".`,
+        details: {
+          similarity: comparison.similarity,
+          verdict: comparison.verdict
+        }
+      });
+    }
+  }
   const footerSpacingPx = options.metadata?.layout.elements ? (() => {
     const footer = options.metadata.layout.elements.find((element) => element.id === "footer");
     if (!footer) {
@@ -892,7 +1202,8 @@ async function runQa(options) {
       ...imageMetadata.height !== void 0 ? { height: imageMetadata.height } : {},
       ...footerSpacingPx !== void 0 ? { footerSpacingPx } : {}
     },
-    issues
+    issues,
+    ...referenceResult ? { reference: referenceResult } : {}
   };
 }
 export {

package/dist/renderer.d.ts

@@ -1,3 +1,3 @@
-export { h as DEFAULT_GENERATOR_VERSION, z as LayoutSnapshot, a as Rect, R as RenderMetadata, J as RenderResult, d as RenderedElement, W as WrittenArtifacts, X as computeSpecHash, a9 as inferSidecarPath, ab as renderDesign, ad as writeRenderArtifacts } from './spec.schema-DhAI-tE8.js';
+export { h as DEFAULT_GENERATOR_VERSION, N as LayoutSnapshot, a as Rect, R as RenderMetadata, Q as RenderResult, d as RenderedElement, Z as WrittenArtifacts, a0 as computeSpecHash, aj as inferSidecarPath, am as renderDesign, ao as writeRenderArtifacts } from './spec.schema-Dm_wOLTd.js';
 import 'zod';
 import '@napi-rs/canvas';