@usefragments/core 1.0.0

package/dist/preview/index.js

@@ -0,0 +1,1129 @@
+// src/preview/comparison-context.ts
+function analyzeComparisonContext(comparison, preview, variantId, component, scope) {
+  const expected = comparison?.state;
+  if (!expected) return { findings: [] };
+  const actual = {
+    variantId: preview?.variantId ?? variantId,
+    theme: preview?.theme,
+    viewport: preview?.viewport
+  };
+  const staleReasons = [];
+  const mismatchLabels = [];
+  const expectedVariantStillExists = !expected.variantId || component.variants.some((variant) => variant.id === expected.variantId);
+  if (scope === "variant" && expected.variantId && expectedVariantStillExists && actual.variantId && expected.variantId !== actual.variantId) {
+    staleReasons.push("variant");
+    mismatchLabels.push(`variant ${actual.variantId}`);
+  }
+  if (expected.theme && actual.theme && expected.theme !== actual.theme) {
+    staleReasons.push("theme");
+    mismatchLabels.push(`theme ${actual.theme}`);
+  }
+  if (expected.viewport && actual.viewport && !sameViewport(expected.viewport, actual.viewport)) {
+    staleReasons.push("viewport");
+    mismatchLabels.push(`viewport ${formatViewport(actual.viewport)}`);
+  }
+  const context = {
+    scope,
+    captured: expected,
+    active: actual,
+    stale: staleReasons.length > 0,
+    staleReasons
+  };
+  if (staleReasons.length === 0) return { context, findings: [] };
+  return {
+    context,
+    findings: [
+      {
+        code: "stale-comparison-signal",
+        severity: "warning",
+        message: `Stored comparison evidence was captured for ${formatComparisonState(
+          expected
+        )}; current preview uses ${mismatchLabels.join(", ")}.`
+      }
+    ]
+  };
+}
+function sameViewport(a, b) {
+  return a.width === b.width && a.height === b.height && a.background === b.background;
+}
+function formatComparisonState(state) {
+  return [
+    state.variantId ? `variant ${state.variantId}` : void 0,
+    state.theme ? `theme ${state.theme}` : void 0,
+    state.viewport ? `viewport ${formatViewport(state.viewport)}` : void 0
+  ].filter(Boolean).join(", ");
+}
+function formatViewport(viewport) {
+  return `${viewport.width}x${viewport.height}`;
+}
+
+// src/preview/comparison-score.ts
+function scoreComparison(parts) {
+  const scores = [];
+  if (parts.image) {
+    scores.push({
+      weight: 0.5,
+      score: Math.max(0, 100 - parts.image.diffPercentage * 10)
+    });
+  }
+  if (parts.dimensions) {
+    const delta = Math.abs(parts.dimensions.delta.width) + Math.abs(parts.dimensions.delta.height);
+    scores.push({ weight: 0.15, score: Math.max(0, 100 - delta * 2) });
+  }
+  if (parts.styles) {
+    const matches = parts.styles.properties.filter((property) => property.match).length;
+    scores.push({ weight: 0.35, score: matches / parts.styles.properties.length * 100 });
+  }
+  if (scores.length === 0) return null;
+  const totalWeight = scores.reduce((sum, item) => sum + item.weight, 0);
+  const weighted = scores.reduce((sum, item) => sum + item.score * item.weight, 0);
+  return Math.round(weighted / totalWeight);
+}
+function resolveStatus(score, findings) {
+  if (score === null) return "incomplete";
+  if (findings.some((finding) => finding.severity === "error")) return "fail";
+  if (findings.some((finding) => finding.severity === "warning")) return "review";
+  if (score >= 90) return "pass";
+  if (score >= 65) return "review";
+  return "fail";
+}
+function summarizeStatus(status, score, findings) {
+  if (score === null) return "Comparison needs at least one captured signal.";
+  if (status === "pass") return `Preview matches the Figma reference (${score}/100).`;
+  const issueCount = findings.length === 1 ? "1 issue" : `${findings.length} issues`;
+  return `Preview needs ${status === "fail" ? "changes" : "review"} (${score}/100, ${issueCount}).`;
+}
+
+// src/preview/comparison-styles.ts
+var COLOR_PROPERTIES = /* @__PURE__ */ new Set([
+  "background",
+  "backgroundColor",
+  "borderColor",
+  "color",
+  "fill",
+  "stroke"
+]);
+var NUMERIC_PROPERTIES = /* @__PURE__ */ new Set([
+  "borderRadius",
+  "borderWidth",
+  "fontSize",
+  "gap",
+  "height",
+  "letterSpacing",
+  "lineHeight",
+  "margin",
+  "opacity",
+  "padding",
+  "width"
+]);
+function compareStyles(design, preview, thresholds, findings) {
+  if (!design || !preview) return void 0;
+  const properties = [];
+  for (const [property, designValue] of Object.entries(design)) {
+    if (designValue === void 0 || designValue === "") continue;
+    const previewValue = preview[property] ?? "(not set)";
+    const match = compareStyleValue(property, designValue, previewValue, thresholds);
+    properties.push({ property, design: designValue, preview: previewValue, match });
+    if (!match) {
+      findings.push({
+        code: "style-mismatch",
+        severity: "warning",
+        message: `${property} differs between Figma and the preview.`,
+        property,
+        designValue,
+        previewValue
+      });
+    }
+  }
+  if (properties.length === 0) return void 0;
+  return {
+    match: properties.every((property) => property.match),
+    properties
+  };
+}
+function compareStyleValue(property, designValue, previewValue, thresholds) {
+  const design = normalizeStyleValue(designValue);
+  const preview = normalizeStyleValue(previewValue);
+  if (design === preview) return true;
+  if (COLOR_PROPERTIES.has(property)) {
+    return compareColors(design, preview, thresholds);
+  }
+  if (NUMERIC_PROPERTIES.has(property)) {
+    return compareNumericValues(design, preview, thresholds.numericPx);
+  }
+  return false;
+}
+function normalizeStyleValue(value) {
+  return value.trim().replace(/\s+/g, " ").replace(/^none$/, "");
+}
+function compareNumericValues(valueA, valueB, tolerance) {
+  const numberA = Number.parseFloat(valueA);
+  const numberB = Number.parseFloat(valueB);
+  if (Number.isNaN(numberA) || Number.isNaN(numberB)) return valueA === valueB;
+  return Math.abs(numberA - numberB) <= tolerance;
+}
+function compareColors(valueA, valueB, thresholds) {
+  const colorA = parseColor(valueA);
+  const colorB = parseColor(valueB);
+  if (!colorA || !colorB) return valueA === valueB;
+  return Math.abs(colorA.r - colorB.r) <= thresholds.colorChannel && Math.abs(colorA.g - colorB.g) <= thresholds.colorChannel && Math.abs(colorA.b - colorB.b) <= thresholds.colorChannel && Math.abs(colorA.a - colorB.a) <= thresholds.alpha;
+}
+function parseColor(value) {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "transparent") return { r: 0, g: 0, b: 0, a: 0 };
+  const hex = normalized.match(/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/);
+  if (hex) return parseHexColor(hex[1]);
+  const rgb = normalized.match(/^rgba?\(([^)]+)\)$/);
+  if (rgb) return parseRgbColor(rgb[1]);
+  return null;
+}
+function parseHexColor(raw) {
+  const expanded = raw.length === 3 || raw.length === 4 ? raw.split("").map((part) => part + part).join("") : raw;
+  return {
+    r: Number.parseInt(expanded.slice(0, 2), 16),
+    g: Number.parseInt(expanded.slice(2, 4), 16),
+    b: Number.parseInt(expanded.slice(4, 6), 16),
+    a: expanded.length === 8 ? Number.parseInt(expanded.slice(6, 8), 16) / 255 : 1
+  };
+}
+function parseRgbColor(value) {
+  const channels = splitRgbChannels(value);
+  if (channels.length < 3 || channels.length > 4) return null;
+  const [rawR, rawG, rawB, rawA] = channels;
+  const r = parseRgbChannel(rawR);
+  const g = parseRgbChannel(rawG);
+  const b = parseRgbChannel(rawB);
+  const a = rawA === void 0 ? 1 : parseAlphaChannel(rawA);
+  if (r === null || g === null || b === null || a === null) return null;
+  return { r, g, b, a };
+}
+function splitRgbChannels(value) {
+  if (value.includes(",")) {
+    return value.split(",").map((part) => part.trim());
+  }
+  const parts = value.replace(/\s*\/\s*/g, " / ").split(/\s+/).filter(Boolean);
+  const slashIndex = parts.indexOf("/");
+  if (slashIndex === -1) return parts;
+  return [...parts.slice(0, slashIndex), parts[slashIndex + 1]].filter(
+    (part) => part !== void 0
+  );
+}
+function parseRgbChannel(value) {
+  if (value.endsWith("%")) {
+    const percentage = Number.parseFloat(value);
+    return Number.isFinite(percentage) ? percentage / 100 * 255 : null;
+  }
+  const channel = Number.parseFloat(value);
+  return Number.isFinite(channel) ? channel : null;
+}
+function parseAlphaChannel(value) {
+  if (value.endsWith("%")) {
+    const percentage = Number.parseFloat(value);
+    return Number.isFinite(percentage) ? percentage / 100 : null;
+  }
+  const alpha = Number.parseFloat(value);
+  return Number.isFinite(alpha) ? alpha : null;
+}
+
+// src/preview/comparison-format.ts
+function formatPercent(value) {
+  return `${round(value)}%`;
+}
+function formatDelta(value) {
+  return value > 0 ? `+${round(value)}` : `${round(value)}`;
+}
+function formatSize(size) {
+  return `${round(size.width)} x ${round(size.height)}`;
+}
+function formatInteger(value) {
+  return Math.round(value).toLocaleString("en-US");
+}
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+
+// src/preview/comparison-evidence.ts
+function normalizeImageDiffEvidence(imageDiff, findings) {
+  if (!isValidPercentage(imageDiff.diffPercentage)) {
+    findings.push({
+      code: "invalid-comparison-signal",
+      severity: "warning",
+      message: "Image diff percentage must be a finite number between 0 and 100."
+    });
+    return void 0;
+  }
+  return {
+    diffPercentage: imageDiff.diffPercentage,
+    changedRegions: normalizeChangedRegions(imageDiff.changedRegions, findings),
+    ...imageDiff.diffImageDataUrl && { diffImageDataUrl: imageDiff.diffImageDataUrl },
+    ...imageDiff.diffImageUrl && { diffImageUrl: imageDiff.diffImageUrl },
+    ...normalizePixelCounts(imageDiff, findings)
+  };
+}
+function isPositiveComparisonSize(value) {
+  return Number.isFinite(value.width) && Number.isFinite(value.height) && value.width > 0 && value.height > 0;
+}
+function normalizeChangedRegions(regions, findings) {
+  if (!regions) return [];
+  const validRegions = [];
+  for (const region of regions) {
+    if (isValidBounds(region)) {
+      validRegions.push(region);
+      continue;
+    }
+    findings.push({
+      code: "invalid-comparison-signal",
+      severity: "warning",
+      message: "Changed regions must use finite non-negative coordinates and positive sizes."
+    });
+  }
+  return validRegions;
+}
+function normalizePixelCounts(imageDiff, findings) {
+  const { diffPixelCount, totalPixels } = imageDiff;
+  if (diffPixelCount === void 0 && totalPixels === void 0) return {};
+  if (!Number.isInteger(diffPixelCount) || !Number.isInteger(totalPixels) || diffPixelCount === void 0 || totalPixels === void 0 || diffPixelCount < 0 || totalPixels <= 0 || diffPixelCount > totalPixels) {
+    findings.push({
+      code: "invalid-comparison-signal",
+      severity: "warning",
+      message: "Image diff pixel counts must be whole numbers with changed pixels less than or equal to total pixels."
+    });
+    return {};
+  }
+  return { diffPixelCount, totalPixels };
+}
+function isValidPercentage(value) {
+  return Number.isFinite(value) && value >= 0 && value <= 100;
+}
+function isValidBounds(value) {
+  return Number.isFinite(value.x) && Number.isFinite(value.y) && Number.isFinite(value.width) && Number.isFinite(value.height) && value.x >= 0 && value.y >= 0 && value.width > 0 && value.height > 0;
+}
+
+// src/preview/comparison-references.ts
+function parseFigmaNodeUrl(url) {
+  const parsed = parseUrl(url);
+  if (!parsed || !isFigmaHostname(parsed.hostname)) return null;
+  const [, surface, fileKey] = parsed.pathname.split("/");
+  if (surface !== "file" && surface !== "design" || !fileKey) return null;
+  const nodeId = parsed.searchParams.get("node-id");
+  if (!nodeId) return null;
+  return { fileKey, nodeId: nodeId.replace(/-/g, ":") };
+}
+function getPreviewDesignReference(component, variantId) {
+  const variant = variantId ? component.variants.find((candidate) => candidate.id === variantId) : void 0;
+  return normalizePreviewDesignReference(variant?.design ?? component.design);
+}
+function buildFigmaDesignSource(reference, fallbackLabel) {
+  const normalized = normalizePreviewDesignReference(reference);
+  return {
+    kind: "figma",
+    label: normalized?.label ?? fallbackLabel,
+    fileKey: normalized?.fileKey,
+    nodeId: normalized?.nodeId,
+    nodeUrl: normalized?.nodeUrl,
+    imageUrl: normalized?.imageUrl,
+    size: normalized?.size
+  };
+}
+function normalizePreviewDesignReference(reference) {
+  if (!reference) return void 0;
+  if (reference.fileKey && reference.nodeId) return reference;
+  if (!reference.nodeUrl) return reference;
+  const parsed = parseFigmaNodeUrl(reference.nodeUrl);
+  if (!parsed) return reference;
+  return {
+    ...reference,
+    fileKey: reference.fileKey ?? parsed.fileKey,
+    nodeId: reference.nodeId ?? parsed.nodeId
+  };
+}
+function isFigmaHostname(hostname) {
+  return hostname === "figma.com" || hostname.endsWith(".figma.com");
+}
+function parseUrl(url) {
+  try {
+    return new URL(url.includes("://") ? url : `https://${url}`);
+  } catch {
+    return null;
+  }
+}
+
+// src/preview/comparison.ts
+var DEFAULT_THRESHOLDS = {
+  imageDiffPercentage: 1,
+  dimensionPx: 1,
+  numericPx: 1,
+  colorChannel: 5,
+  alpha: 0.05
+};
+function comparePreviewToDesign(input) {
+  const thresholds = resolvePreviewComparisonThresholds(input.thresholds);
+  const findings = [...input.findings ?? []];
+  const image = compareImageDiff(input.imageDiff, thresholds, findings);
+  const dimensions = compareDimensions(input.design.size, input.preview.size, thresholds, findings);
+  const styles = compareStyles(input.design.styles, input.preview.styles, thresholds, findings);
+  const score = scoreComparison({ image, dimensions, styles });
+  if (score === null) {
+    findings.push({
+      code: "missing-comparison-signal",
+      severity: "warning",
+      message: "No image, dimension, or style comparison data was provided."
+    });
+  }
+  const status = resolveStatus(score, findings);
+  return {
+    status,
+    score,
+    summary: summarizeStatus(status, score, findings),
+    design: input.design,
+    preview: input.preview,
+    thresholds,
+    ...image && { image },
+    ...dimensions && { dimensions },
+    ...styles && { styles },
+    findings,
+    ...input.context && { context: input.context }
+  };
+}
+function resolvePreviewComparisonThresholds(thresholds) {
+  return {
+    imageDiffPercentage: readThreshold(
+      thresholds?.imageDiffPercentage,
+      DEFAULT_THRESHOLDS.imageDiffPercentage,
+      { min: 0, max: 100 }
+    ),
+    dimensionPx: readThreshold(thresholds?.dimensionPx, DEFAULT_THRESHOLDS.dimensionPx, {
+      min: 0
+    }),
+    numericPx: readThreshold(thresholds?.numericPx, DEFAULT_THRESHOLDS.numericPx, { min: 0 }),
+    colorChannel: readThreshold(thresholds?.colorChannel, DEFAULT_THRESHOLDS.colorChannel, {
+      min: 0,
+      max: 255
+    }),
+    alpha: readThreshold(thresholds?.alpha, DEFAULT_THRESHOLDS.alpha, { min: 0, max: 1 })
+  };
+}
+function buildPreviewComparisonReport(input) {
+  const variant = input.variantId ? input.component.variants.find((candidate) => candidate.id === input.variantId) : void 0;
+  const rawReference = input.designReference ?? variant?.design ?? input.component.design;
+  const reference = normalizePreviewDesignReference(rawReference);
+  if (!reference) return null;
+  const fallbackLabel = `${input.component.displayName}${variant ? ` / ${variant.name}` : ""}`;
+  const comparison = reference.comparison;
+  const comparisonContext = analyzeComparisonContext(
+    comparison,
+    input.preview,
+    input.variantId,
+    input.component,
+    resolveDesignReferenceScope(input, rawReference, variant)
+  );
+  const scoredComparison = comparisonContext.findings.length === 0 ? comparison : void 0;
+  const imageDiff = input.imageDiff ?? imageDiffFromComparison(scoredComparison);
+  const previewSize = scoredComparison?.previewSize ?? input.preview?.size;
+  return comparePreviewToDesign({
+    design: {
+      ...buildFigmaDesignSource(reference, fallbackLabel),
+      ...scoredComparison?.designStyles && { styles: scoredComparison.designStyles }
+    },
+    preview: {
+      kind: "preview",
+      label: input.preview?.label ?? fallbackLabel,
+      componentKey: input.preview?.componentKey ?? input.component.componentKey,
+      ...(input.preview?.variantId ?? input.variantId) && {
+        variantId: input.preview?.variantId ?? input.variantId
+      },
+      ...input.preview?.theme && { theme: input.preview.theme },
+      ...input.preview?.viewport && { viewport: input.preview.viewport },
+      ...previewSize && { size: previewSize },
+      ...(input.preview?.styles ?? scoredComparison?.previewStyles) && {
+        styles: input.preview?.styles ?? scoredComparison?.previewStyles
+      },
+      ...input.preview?.imageDataUrl && { imageDataUrl: input.preview.imageDataUrl },
+      ...(input.preview?.imageUrl ?? scoredComparison?.previewImageUrl) && {
+        imageUrl: input.preview?.imageUrl ?? scoredComparison?.previewImageUrl
+      },
+      ...(input.preview?.capturedAt ?? scoredComparison?.capturedAt) && {
+        capturedAt: input.preview?.capturedAt ?? scoredComparison?.capturedAt
+      }
+    },
+    ...imageDiff && { imageDiff },
+    ...input.thresholds && { thresholds: input.thresholds },
+    ...comparisonContext.findings.length > 0 && { findings: comparisonContext.findings },
+    ...comparisonContext.context && { context: comparisonContext.context }
+  });
+}
+function resolveDesignReferenceScope(input, reference, variant) {
+  if (input.designReferenceScope) return input.designReferenceScope;
+  return reference === variant?.design ? "variant" : "component";
+}
+function buildPreviewDesignComparisonEvidence(report) {
+  if (report.context?.stale) return null;
+  const state = buildStoredComparisonState(report.preview);
+  const previewImageUrl = report.preview.imageUrl ?? report.preview.imageDataUrl;
+  const diffImageUrl = report.image?.diffImageUrl ?? report.image?.diffImageDataUrl;
+  const designStyles = cleanStyleMap(report.design.styles);
+  const previewStyles = cleanStyleMap(report.preview.styles);
+  const previewSize = report.preview.size && isPositiveComparisonSize(report.preview.size) ? report.preview.size : report.dimensions?.preview;
+  const evidence = {
+    ...state && { state },
+    ...previewImageUrl && { previewImageUrl },
+    ...previewSize && { previewSize },
+    ...designStyles && { designStyles },
+    ...previewStyles && { previewStyles },
+    ...diffImageUrl && { diffImageUrl },
+    ...report.image && { diffPercentage: report.image.diffPercentage },
+    ...report.image?.diffPixelCount !== void 0 && {
+      diffPixelCount: report.image.diffPixelCount
+    },
+    ...report.image?.totalPixels !== void 0 && {
+      totalPixels: report.image.totalPixels
+    },
+    ...report.image?.changedRegions.length && {
+      changedRegions: report.image.changedRegions
+    },
+    ...report.preview.capturedAt && { capturedAt: report.preview.capturedAt }
+  };
+  return Object.keys(evidence).length > 0 ? evidence : null;
+}
+function buildPreviewDesignReferenceFromReport(report) {
+  const comparison = buildPreviewDesignComparisonEvidence(report);
+  const imageUrl = report.design.imageUrl ?? report.design.imageDataUrl;
+  return {
+    provider: "figma",
+    label: report.design.label,
+    ...report.design.nodeUrl && { nodeUrl: report.design.nodeUrl },
+    ...report.design.fileKey && { fileKey: report.design.fileKey },
+    ...report.design.nodeId && { nodeId: report.design.nodeId },
+    ...imageUrl && { imageUrl },
+    ...report.design.size && isPositiveComparisonSize(report.design.size) && {
+      size: report.design.size
+    },
+    ...comparison && { comparison }
+  };
+}
+function buildStoredComparisonState(preview) {
+  const state = {
+    ...preview.variantId && { variantId: preview.variantId },
+    ...preview.theme && { theme: preview.theme },
+    ...preview.viewport && { viewport: preview.viewport }
+  };
+  return Object.keys(state).length > 0 ? state : void 0;
+}
+function cleanStyleMap(styles) {
+  if (!styles) return void 0;
+  const entries = Object.entries(styles).filter(
+    (entry) => typeof entry[1] === "string"
+  );
+  return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+function imageDiffFromComparison(comparison) {
+  if (!comparison || comparison.diffPercentage === void 0) return void 0;
+  return {
+    diffPercentage: comparison.diffPercentage,
+    changedRegions: comparison.changedRegions,
+    diffImageUrl: comparison.diffImageUrl,
+    diffPixelCount: comparison.diffPixelCount,
+    totalPixels: comparison.totalPixels
+  };
+}
+function compareImageDiff(imageDiff, thresholds, findings) {
+  if (!imageDiff) return void 0;
+  const normalized = normalizeImageDiffEvidence(imageDiff, findings);
+  if (!normalized) return void 0;
+  const match = normalized.diffPercentage <= thresholds.imageDiffPercentage;
+  if (!match) {
+    findings.push({
+      code: "image-diff-threshold-exceeded",
+      severity: "error",
+      message: `Image diff ${formatPercent(normalized.diffPercentage)} exceeds ${formatPercent(
+        thresholds.imageDiffPercentage
+      )}.`,
+      bounds: normalized.changedRegions[0]
+    });
+  }
+  return {
+    match,
+    diffPercentage: round(normalized.diffPercentage),
+    diffImageDataUrl: normalized.diffImageDataUrl,
+    diffImageUrl: normalized.diffImageUrl,
+    changedRegions: normalized.changedRegions,
+    diffPixelCount: normalized.diffPixelCount,
+    totalPixels: normalized.totalPixels
+  };
+}
+function compareDimensions(design, preview, thresholds, findings) {
+  if (!design || !preview) return void 0;
+  if (!isPositiveComparisonSize(design) || !isPositiveComparisonSize(preview)) {
+    findings.push({
+      code: "invalid-comparison-signal",
+      severity: "warning",
+      message: "Design and preview sizes must be finite positive numbers."
+    });
+    return void 0;
+  }
+  const delta = {
+    width: round(preview.width - design.width),
+    height: round(preview.height - design.height)
+  };
+  const match = Math.abs(delta.width) <= thresholds.dimensionPx && Math.abs(delta.height) <= thresholds.dimensionPx;
+  if (!match) {
+    findings.push({
+      code: "dimension-mismatch",
+      severity: "warning",
+      message: `Preview is ${formatDelta(delta.width)}px wide and ${formatDelta(
+        delta.height
+      )}px tall compared with the Figma frame.`
+    });
+  }
+  return { match, design, preview, delta };
+}
+function readThreshold(value, fallback, bounds) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  if (value < bounds.min) return fallback;
+  if (bounds.max !== void 0 && value > bounds.max) return fallback;
+  return value;
+}
+
+// src/preview/comparison-artifact.ts
+function buildPreviewComparisonArtifactPayload(input) {
+  if (!input.report) return null;
+  const report = input.report;
+  const designReference = {
+    ...input.designReference ?? buildPreviewDesignReferenceFromReport(report)
+  };
+  const reportEvidence = buildPreviewDesignComparisonEvidence(report);
+  const comparisonEvidence = report.context?.stale ? void 0 : input.comparisonEvidence ? { ...input.comparisonEvidence } : designReference.comparison ? { ...designReference.comparison } : reportEvidence ? { ...reportEvidence } : void 0;
+  if (report.context?.stale) {
+    delete designReference.comparison;
+  }
+  if (input.assets?.figma) {
+    designReference.imageUrl = input.assets.figma;
+  }
+  if (comparisonEvidence && input.assets?.rendered) {
+    comparisonEvidence.previewImageUrl = input.assets.rendered;
+  }
+  if (comparisonEvidence && input.assets?.diff) {
+    comparisonEvidence.diffImageUrl = input.assets.diff;
+  }
+  if (comparisonEvidence) {
+    designReference.comparison = comparisonEvidence;
+  }
+  return {
+    target: buildComparisonArtifactTarget(report),
+    report,
+    designReference,
+    ...comparisonEvidence && { comparisonEvidence }
+  };
+}
+function applyPreviewComparisonArtifactPayload(manifest, payload) {
+  if (!payload.comparisonEvidence) {
+    return {
+      status: "missing-comparison-evidence",
+      applied: false,
+      manifest,
+      message: "Comparison payload has no reusable evidence to apply."
+    };
+  }
+  const component = manifest.components[payload.target.componentKey];
+  if (!component) {
+    return {
+      status: "component-not-found",
+      applied: false,
+      manifest,
+      message: `Component ${payload.target.componentKey} was not found in the manifest.`
+    };
+  }
+  if (payload.target.designReferenceScope === "variant") {
+    const variantIndex = component.variants.findIndex(
+      (variant) => variant.id === payload.target.variantId
+    );
+    if (variantIndex < 0) {
+      return {
+        status: "variant-not-found",
+        applied: false,
+        manifest,
+        message: `Variant ${payload.target.variantId ?? "(missing)"} was not found on component ${payload.target.componentKey}.`
+      };
+    }
+    const variants = component.variants.map(
+      (variant, index) => index === variantIndex ? { ...variant, design: payload.designReference } : variant
+    );
+    return {
+      status: "applied",
+      applied: true,
+      manifest: {
+        ...manifest,
+        components: {
+          ...manifest.components,
+          [payload.target.componentKey]: {
+            ...component,
+            variants
+          }
+        }
+      },
+      message: `Applied comparison evidence to ${payload.target.componentKey} variant ${payload.target.variantId}.`
+    };
+  }
+  return {
+    status: "applied",
+    applied: true,
+    manifest: {
+      ...manifest,
+      components: {
+        ...manifest.components,
+        [payload.target.componentKey]: {
+          ...component,
+          design: payload.designReference
+        }
+      }
+    },
+    message: `Applied comparison evidence to ${payload.target.componentKey}.`
+  };
+}
+function buildComparisonArtifactTarget(report) {
+  return {
+    componentKey: report.preview.componentKey,
+    ...report.preview.variantId && { variantId: report.preview.variantId },
+    designReferenceScope: report.context?.scope ?? (report.preview.variantId ? "variant" : "component")
+  };
+}
+
+// src/preview/comparison-presentation.ts
+function getPreviewComparisonSignals(report) {
+  return [buildImageSignal(report), buildDimensionSignal(report), buildStyleSignal(report)];
+}
+function getPreviewComparisonRegionOverlays(report) {
+  const sourceSize = report.dimensions?.preview ?? report.preview.size ?? report.design.size;
+  if (!sourceSize || sourceSize.width <= 0 || sourceSize.height <= 0) return [];
+  return (report.image?.changedRegions ?? []).flatMap((region) => {
+    const clipped = clipRegionToSize(region, sourceSize);
+    if (!clipped) return [];
+    return {
+      ...region,
+      label: formatChangedRegionLabel(region),
+      leftPercent: round(clipped.x / sourceSize.width * 100),
+      topPercent: round(clipped.y / sourceSize.height * 100),
+      widthPercent: round(clipped.width / sourceSize.width * 100),
+      heightPercent: round(clipped.height / sourceSize.height * 100)
+    };
+  });
+}
+function getPreviewComparisonContextSummary(report) {
+  if (!report.context) return null;
+  const captured = report.context.captured ? formatComparisonState2(report.context.captured, {
+    includeVariant: report.context.scope === "variant"
+  }) : "unknown capture state";
+  const active = formatComparisonState2(report.context.active, {
+    includeVariant: report.context.scope === "variant"
+  });
+  if (report.context.stale) {
+    return {
+      status: "stale",
+      label: "Capture context",
+      value: "Stale evidence",
+      detail: `Captured ${captured}; current ${active}.`
+    };
+  }
+  return {
+    status: "current",
+    label: "Capture context",
+    value: "Current evidence",
+    detail: `Captured ${captured}.`
+  };
+}
+function formatPreviewComparisonFinding(finding) {
+  const prefix = finding.severity.toUpperCase();
+  const subject = finding.property ? `${finding.property}: ` : "";
+  return `${prefix}: ${subject}${finding.message}`;
+}
+function formatComparisonState2(state, options) {
+  const parts = [
+    options.includeVariant && state.variantId ? `variant ${state.variantId}` : void 0,
+    state.theme ? `theme ${state.theme}` : void 0,
+    state.viewport ? `viewport ${formatSize(state.viewport)}` : void 0
+  ].filter((part) => Boolean(part));
+  return parts.length > 0 ? parts.join(", ") : "unspecified preview state";
+}
+function buildImageSignal(report) {
+  if (!report.image) {
+    return {
+      id: "image",
+      label: "Image diff",
+      status: "missing",
+      value: "No capture",
+      detail: "Capture a Figma image and preview screenshot to compare pixels."
+    };
+  }
+  const changedPixels = report.image.diffPixelCount !== void 0 && report.image.totalPixels !== void 0 ? `${formatInteger(report.image.diffPixelCount)} of ${formatInteger(
+    report.image.totalPixels
+  )} pixels changed` : `${report.image.changedRegions.length} changed ${report.image.changedRegions.length === 1 ? "region" : "regions"}`;
+  return {
+    id: "image",
+    label: "Image diff",
+    status: report.image.match ? "pass" : "fail",
+    value: `${formatPercent(report.image.diffPercentage)} changed`,
+    detail: `${changedPixels}; threshold ${formatPercent(report.thresholds.imageDiffPercentage)}.`
+  };
+}
+function buildDimensionSignal(report) {
+  if (!report.dimensions) {
+    return {
+      id: "dimensions",
+      label: "Size",
+      status: "missing",
+      value: "No size",
+      detail: "Provide both Figma frame size and captured preview size."
+    };
+  }
+  return {
+    id: "dimensions",
+    label: "Size",
+    status: report.dimensions.match ? "pass" : "review",
+    value: `${formatDelta(report.dimensions.delta.width)} x ${formatDelta(
+      report.dimensions.delta.height
+    )} px`,
+    detail: `${formatSize(report.dimensions.design)} design, ${formatSize(
+      report.dimensions.preview
+    )} preview; tolerance +/-${report.thresholds.dimensionPx}px.`
+  };
+}
+function buildStyleSignal(report) {
+  if (!report.styles) {
+    return {
+      id: "styles",
+      label: "Styles",
+      status: "missing",
+      value: "No styles",
+      detail: "Provide computed Figma and preview styles to compare tokens and CSS."
+    };
+  }
+  const matchCount = report.styles.properties.filter((property) => property.match).length;
+  const firstMismatch = report.styles.properties.find((property) => !property.match);
+  return {
+    id: "styles",
+    label: "Styles",
+    status: report.styles.match ? "pass" : "review",
+    value: `${matchCount}/${report.styles.properties.length} matched`,
+    detail: firstMismatch ? `${firstMismatch.property}: ${firstMismatch.design} in Figma, ${firstMismatch.preview} in preview.` : "All checked computed styles are within tolerance."
+  };
+}
+function formatChangedRegionLabel(region) {
+  return `Changed region x ${region.x} y ${region.y} width ${region.width} height ${region.height}`;
+}
+function clipRegionToSize(region, size) {
+  const x = Math.max(0, region.x);
+  const y = Math.max(0, region.y);
+  const right = Math.min(size.width, region.x + region.width);
+  const bottom = Math.min(size.height, region.y + region.height);
+  if (right <= x || bottom <= y) return null;
+  return {
+    x,
+    y,
+    width: right - x,
+    height: bottom - y
+  };
+}
+
+// src/preview/validation.ts
+function definePreviewArtifactManifest(manifest) {
+  const validation = validatePreviewArtifactManifest(manifest);
+  if (!validation.ok) {
+    throw new Error(`Invalid preview artifact manifest:
+${validation.issues.join("\n")}`);
+  }
+  return manifest;
+}
+function validatePreviewArtifactManifest(value) {
+  const issues = [];
+  if (!isRecord(value)) {
+    return { ok: false, issues: ["manifest must be an object"] };
+  }
+  requireLiteral(value, "artifactVersion", "preview-artifact/v1", issues);
+  validateIdentity(value.identity, issues);
+  validateBuilder(value.builder, issues);
+  validateRuntime(value.runtime, issues);
+  validateComponents(value.components, issues);
+  if (!Array.isArray(value.diagnostics)) {
+    issues.push("diagnostics must be an array");
+  }
+  return { ok: issues.length === 0, issues };
+}
+function isPreviewArtifactManifest(value) {
+  return validatePreviewArtifactManifest(value).ok;
+}
+function validateIdentity(value, issues) {
+  if (!isRecord(value)) {
+    issues.push("identity must be an object");
+    return;
+  }
+  requireLiteral(value, "artifactVersion", "preview-artifact/v1", issues);
+  for (const key of [
+    "artifactId",
+    "orgId",
+    "projectId",
+    "bindingId",
+    "repoFullName",
+    "commitSha",
+    "sourceRef",
+    "createdAt"
+  ]) {
+    requireString(value, key, issues);
+  }
+}
+function validateBuilder(value, issues) {
+  if (!isRecord(value)) {
+    issues.push("builder must be an object");
+    return;
+  }
+  requireString(value, "name", issues);
+  requireString(value, "version", issues);
+  if (value.typecheck !== "typescript" && value.typecheck !== "none") {
+    issues.push('builder.typecheck must be "typescript" or "none"');
+  }
+  if (!Array.isArray(value.sources)) {
+    issues.push("builder.sources must be an array");
+  } else {
+    for (const source of value.sources) {
+      if (!isPreviewDefinitionSource(source)) {
+        issues.push(`builder.sources contains unsupported source ${JSON.stringify(source)}`);
+      }
+    }
+  }
+  if (!Array.isArray(value.adapters)) {
+    issues.push("builder.adapters must be an array");
+  }
+}
+function validateRuntime(value, issues) {
+  if (!isRecord(value)) {
+    issues.push("runtime must be an object");
+    return;
+  }
+  requireLiteral(value, "framework", "react", issues);
+  requireLiteral(value, "moduleFormat", "esm", issues);
+  requireString(value, "entry", issues);
+  requireString(value, "assetsBaseUrl", issues);
+  if (!Array.isArray(value.css)) issues.push("runtime.css must be an array");
+}
+function validateComponents(value, issues) {
+  if (!isRecord(value)) {
+    issues.push("components must be an object");
+    return;
+  }
+  for (const [key, component] of Object.entries(value)) {
+    if (!isRecord(component)) {
+      issues.push(`components.${key} must be an object`);
+      continue;
+    }
+    requireString(component, "componentKey", issues, `components.${key}`);
+    requireString(component, "publicRef", issues, `components.${key}`);
+    requireString(component, "displayName", issues, `components.${key}`);
+    requireString(component, "exportName", issues, `components.${key}`);
+    requireString(component, "importPath", issues, `components.${key}`);
+    requireString(component, "definitionSource", issues, `components.${key}`);
+    if (!isPreviewDefinitionSource(component.definitionSource)) {
+      issues.push(
+        `components.${key}.definitionSource must be one of typescript, fragment, manual, synthesized`
+      );
+    }
+    if (!isRecord(component.props)) {
+      issues.push(`components.${key}.props must be an object`);
+    }
+    if (!Array.isArray(component.variants)) {
+      issues.push(`components.${key}.variants must be an array`);
+    } else {
+      component.variants.forEach((variant, index) => {
+        if (!isRecord(variant)) {
+          issues.push(`components.${key}.variants.${index} must be an object`);
+          return;
+        }
+        validateDesignReference(
+          variant.design,
+          issues,
+          `components.${key}.variants.${index}.design`
+        );
+      });
+    }
+    validateDesignReference(component.design, issues, `components.${key}.design`);
+  }
+}
+function validateDesignReference(value, issues, path) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  if (value.provider !== "figma") {
+    issues.push(`${path}.provider must be "figma"`);
+  }
+  for (const key of ["label", "nodeUrl", "fileKey", "nodeId", "imageUrl"]) {
+    if (value[key] !== void 0 && typeof value[key] !== "string") {
+      issues.push(`${path}.${key} must be a string`);
+    }
+  }
+  validateSize(value.size, issues, `${path}.size`);
+  validateComparisonEvidence(value.comparison, issues, `${path}.comparison`, readSize(value.size));
+}
+function validateComparisonEvidence(value, issues, path, designSize) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  for (const key of ["previewImageUrl", "diffImageUrl", "capturedAt"]) {
+    if (value[key] !== void 0 && typeof value[key] !== "string") {
+      issues.push(`${path}.${key} must be a string`);
+    }
+  }
+  validateSize(value.previewSize, issues, `${path}.previewSize`);
+  validateComparisonState(value.state, issues, `${path}.state`);
+  const comparisonSize = readSize(value.previewSize) ?? designSize;
+  validateStyleMap(value.designStyles, issues, `${path}.designStyles`);
+  validateStyleMap(value.previewStyles, issues, `${path}.previewStyles`);
+  validateFiniteNumber(value.diffPercentage, issues, `${path}.diffPercentage`);
+  validatePixelCounts(value, issues, path);
+  if (typeof value.diffPercentage === "number" && (value.diffPercentage < 0 || value.diffPercentage > 100)) {
+    issues.push(`${path}.diffPercentage must be between 0 and 100`);
+  }
+  if (value.changedRegions !== void 0) {
+    if (!Array.isArray(value.changedRegions)) {
+      issues.push(`${path}.changedRegions must be an array`);
+    } else {
+      value.changedRegions.forEach(
+        (region, index) => validateBounds(region, issues, `${path}.changedRegions.${index}`, comparisonSize)
+      );
+    }
+  }
+}
+function validateComparisonState(value, issues, path) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  if (value.variantId !== void 0 && typeof value.variantId !== "string") {
+    issues.push(`${path}.variantId must be a string`);
+  }
+  if (value.theme !== void 0 && typeof value.theme !== "string") {
+    issues.push(`${path}.theme must be a string`);
+  }
+  validateSize(value.viewport, issues, `${path}.viewport`);
+}
+function validatePixelCounts(value, issues, path) {
+  if (value.diffPixelCount !== void 0) {
+    validateNonNegativeInteger(value.diffPixelCount, issues, `${path}.diffPixelCount`);
+  }
+  if (value.totalPixels !== void 0) {
+    validatePositiveInteger(value.totalPixels, issues, `${path}.totalPixels`);
+  }
+  if (isFiniteNumber(value.diffPixelCount) && isFiniteNumber(value.totalPixels) && value.diffPixelCount > value.totalPixels) {
+    issues.push(`${path}.diffPixelCount must be less than or equal to ${path}.totalPixels`);
+  }
+}
+function validateSize(value, issues, path) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validatePositiveNumber(value.width, issues, `${path}.width`);
+  validatePositiveNumber(value.height, issues, `${path}.height`);
+}
+function validateStyleMap(value, issues, path) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  for (const [key, styleValue] of Object.entries(value)) {
+    if (typeof styleValue !== "string") {
+      issues.push(`${path}.${key} must be a string`);
+    }
+  }
+}
+function validateBounds(value, issues, path, sourceSize) {
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateNonNegativeNumber(value.x, issues, `${path}.x`);
+  validateNonNegativeNumber(value.y, issues, `${path}.y`);
+  validatePositiveNumber(value.width, issues, `${path}.width`);
+  validatePositiveNumber(value.height, issues, `${path}.height`);
+  if (!sourceSize) return;
+  if (isFiniteNumber(value.x) && isFiniteNumber(value.width) && value.x >= 0 && value.width > 0 && value.x + value.width > sourceSize.width) {
+    issues.push(`${path} must fit within comparison source width ${sourceSize.width}`);
+  }
+  if (isFiniteNumber(value.y) && isFiniteNumber(value.height) && value.y >= 0 && value.height > 0 && value.y + value.height > sourceSize.height) {
+    issues.push(`${path} must fit within comparison source height ${sourceSize.height}`);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPreviewDefinitionSource(value) {
+  return value === "typescript" || value === "fragment" || value === "manual" || value === "synthesized";
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function validatePositiveNumber(value, issues, path) {
+  if (!isFiniteNumber(value) || value <= 0) {
+    issues.push(`${path} must be a positive number`);
+  }
+}
+function validateNonNegativeNumber(value, issues, path) {
+  if (!isFiniteNumber(value) || value < 0) {
+    issues.push(`${path} must be a non-negative number`);
+  }
+}
+function validateFiniteNumber(value, issues, path) {
+  if (value !== void 0 && !isFiniteNumber(value)) {
+    issues.push(`${path} must be a finite number`);
+  }
+}
+function validatePositiveInteger(value, issues, path) {
+  if (!Number.isInteger(value) || !isFiniteNumber(value) || value <= 0) {
+    issues.push(`${path} must be a positive integer`);
+  }
+}
+function validateNonNegativeInteger(value, issues, path) {
+  if (!Number.isInteger(value) || !isFiniteNumber(value) || value < 0) {
+    issues.push(`${path} must be a non-negative integer`);
+  }
+}
+function readSize(value) {
+  if (!isRecord(value)) return void 0;
+  if (!isFiniteNumber(value.width) || value.width <= 0) return void 0;
+  if (!isFiniteNumber(value.height) || value.height <= 0) return void 0;
+  return { width: value.width, height: value.height };
+}
+function requireString(object, key, issues, path = "") {
+  if (typeof object[key] !== "string" || !object[key]) {
+    issues.push(`${path ? `${path}.` : ""}${key} must be a non-empty string`);
+  }
+}
+function requireLiteral(object, key, expected, issues) {
+  if (object[key] !== expected) {
+    issues.push(`${key} must be ${JSON.stringify(expected)}`);
+  }
+}
+export {
+  applyPreviewComparisonArtifactPayload,
+  buildFigmaDesignSource,
+  buildPreviewComparisonArtifactPayload,
+  buildPreviewComparisonReport,
+  buildPreviewDesignComparisonEvidence,
+  buildPreviewDesignReferenceFromReport,
+  comparePreviewToDesign,
+  definePreviewArtifactManifest,
+  formatPreviewComparisonFinding,
+  getPreviewComparisonContextSummary,
+  getPreviewComparisonRegionOverlays,
+  getPreviewComparisonSignals,
+  getPreviewDesignReference,
+  isPreviewArtifactManifest,
+  parseFigmaNodeUrl,
+  resolvePreviewComparisonThresholds,
+  validatePreviewArtifactManifest
+};
+//# sourceMappingURL=index.js.map