@usefragments/core 1.0.0

package/src/preview/comparison.ts

@@ -0,0 +1,488 @@
+import type {
+  PreviewComponentDefinition,
+  PreviewDesignComparisonReference,
+  PreviewDesignComparisonState,
+  PreviewDesignReference,
+  PreviewViewport,
+} from "./types";
+import { analyzeComparisonContext } from "./comparison-context";
+import { scoreComparison, resolveStatus, summarizeStatus } from "./comparison-score";
+import { compareStyles } from "./comparison-styles";
+import { formatDelta, formatPercent, round } from "./comparison-format";
+import { isPositiveComparisonSize, normalizeImageDiffEvidence } from "./comparison-evidence";
+import { buildFigmaDesignSource, normalizePreviewDesignReference } from "./comparison-references";
+
+export type PreviewComparisonSourceKind = "figma" | "preview";
+
+export type PreviewComparisonStatus = "pass" | "review" | "fail" | "incomplete";
+
+export type PreviewComparisonSeverity = "info" | "warning" | "error";
+
+export interface PreviewComparisonSize {
+  width: number;
+  height: number;
+}
+
+export interface PreviewComparisonBounds extends PreviewComparisonSize {
+  x: number;
+  y: number;
+}
+
+export type PreviewComparisonStyleMap = Record<string, string | undefined>;
+
+export interface PreviewComparisonSource {
+  kind: PreviewComparisonSourceKind;
+  label: string;
+  imageDataUrl?: string;
+  imageUrl?: string;
+  size?: PreviewComparisonSize;
+  styles?: PreviewComparisonStyleMap;
+  capturedAt?: string;
+}
+
+export interface FigmaDesignComparisonSource extends PreviewComparisonSource {
+  kind: "figma";
+  fileKey?: string;
+  nodeId?: string;
+  nodeUrl?: string;
+}
+
+export interface RenderedPreviewComparisonSource extends PreviewComparisonSource {
+  kind: "preview";
+  componentKey: string;
+  variantId?: string;
+  theme?: string;
+  viewport?: PreviewViewport;
+}
+
+export interface PreviewComparisonThresholds {
+  imageDiffPercentage: number;
+  dimensionPx: number;
+  numericPx: number;
+  colorChannel: number;
+  alpha: number;
+}
+
+export interface PreviewImageDiffInput {
+  diffPercentage: number;
+  changedRegions?: PreviewComparisonBounds[];
+  diffImageDataUrl?: string;
+  diffImageUrl?: string;
+  diffPixelCount?: number;
+  totalPixels?: number;
+}
+
+export interface PreviewComparisonInput {
+  design: FigmaDesignComparisonSource;
+  preview: RenderedPreviewComparisonSource;
+  imageDiff?: PreviewImageDiffInput;
+  thresholds?: Partial<PreviewComparisonThresholds>;
+  findings?: PreviewComparisonFinding[];
+  context?: PreviewComparisonContext;
+}
+
+export interface BuildPreviewComparisonReportInput {
+  component: PreviewComponentDefinition;
+  variantId?: string;
+  designReference?: PreviewDesignReference;
+  designReferenceScope?: "component" | "variant";
+  preview?: Partial<Omit<RenderedPreviewComparisonSource, "kind" | "componentKey">> & {
+    componentKey?: string;
+  };
+  imageDiff?: PreviewImageDiffInput;
+  thresholds?: Partial<PreviewComparisonThresholds>;
+}
+
+export interface PreviewStyleComparisonItem {
+  property: string;
+  design: string;
+  preview: string;
+  match: boolean;
+}
+
+export interface PreviewComparisonFinding {
+  code:
+    | "image-diff-threshold-exceeded"
+    | "dimension-mismatch"
+    | "style-mismatch"
+    | "missing-comparison-signal"
+    | "invalid-comparison-signal"
+    | "stale-comparison-signal";
+  severity: PreviewComparisonSeverity;
+  message: string;
+  bounds?: PreviewComparisonBounds;
+  property?: string;
+  designValue?: string;
+  previewValue?: string;
+}
+
+export type PreviewComparisonReferenceScope = "component" | "variant";
+
+export type PreviewComparisonContextMismatch = "variant" | "theme" | "viewport";
+
+export interface PreviewComparisonContext {
+  scope: PreviewComparisonReferenceScope;
+  captured?: PreviewDesignComparisonState;
+  active: PreviewDesignComparisonState;
+  stale: boolean;
+  staleReasons: PreviewComparisonContextMismatch[];
+}
+
+export interface PreviewComparisonReport {
+  status: PreviewComparisonStatus;
+  score: number | null;
+  summary: string;
+  design: FigmaDesignComparisonSource;
+  preview: RenderedPreviewComparisonSource;
+  thresholds: PreviewComparisonThresholds;
+  image?: {
+    match: boolean;
+    diffPercentage: number;
+    diffImageDataUrl?: string;
+    diffImageUrl?: string;
+    changedRegions: PreviewComparisonBounds[];
+    diffPixelCount?: number;
+    totalPixels?: number;
+  };
+  dimensions?: {
+    match: boolean;
+    design: PreviewComparisonSize;
+    preview: PreviewComparisonSize;
+    delta: PreviewComparisonSize;
+  };
+  styles?: {
+    match: boolean;
+    properties: PreviewStyleComparisonItem[];
+  };
+  findings: PreviewComparisonFinding[];
+  context?: PreviewComparisonContext;
+}
+
+export type PreviewComparisonSignalId = "image" | "dimensions" | "styles";
+
+export type PreviewComparisonSignalStatus = "pass" | "review" | "fail" | "missing";
+
+export interface PreviewComparisonSignal {
+  id: PreviewComparisonSignalId;
+  label: string;
+  status: PreviewComparisonSignalStatus;
+  value: string;
+  detail: string;
+}
+
+export interface PreviewComparisonContextSummary {
+  status: "current" | "stale";
+  label: string;
+  value: string;
+  detail: string;
+}
+
+export interface PreviewComparisonRegionOverlay extends PreviewComparisonBounds {
+  label: string;
+  leftPercent: number;
+  topPercent: number;
+  widthPercent: number;
+  heightPercent: number;
+}
+
+const DEFAULT_THRESHOLDS: PreviewComparisonThresholds = {
+  imageDiffPercentage: 1,
+  dimensionPx: 1,
+  numericPx: 1,
+  colorChannel: 5,
+  alpha: 0.05,
+};
+
+export function comparePreviewToDesign(input: PreviewComparisonInput): PreviewComparisonReport {
+  const thresholds = resolvePreviewComparisonThresholds(input.thresholds);
+  const findings: PreviewComparisonFinding[] = [...(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 }),
+  };
+}
+
+export function resolvePreviewComparisonThresholds(
+  thresholds?: Partial<PreviewComparisonThresholds> | null
+): PreviewComparisonThresholds {
+  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 }),
+  };
+}
+
+export function buildPreviewComparisonReport(
+  input: BuildPreviewComparisonReportInput
+): PreviewComparisonReport | null {
+  const variant = input.variantId
+    ? input.component.variants.find((candidate) => candidate.id === input.variantId)
+    : undefined;
+  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 : undefined;
+  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: BuildPreviewComparisonReportInput,
+  reference: PreviewDesignReference | undefined,
+  variant: PreviewComponentDefinition["variants"][number] | undefined
+): "component" | "variant" {
+  if (input.designReferenceScope) return input.designReferenceScope;
+  return reference === variant?.design ? "variant" : "component";
+}
+
+export function buildPreviewDesignComparisonEvidence(
+  report: PreviewComparisonReport
+): PreviewDesignComparisonReference | null {
+  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: PreviewDesignComparisonReference = {
+    ...(state && { state }),
+    ...(previewImageUrl && { previewImageUrl }),
+    ...(previewSize && { previewSize }),
+    ...(designStyles && { designStyles }),
+    ...(previewStyles && { previewStyles }),
+    ...(diffImageUrl && { diffImageUrl }),
+    ...(report.image && { diffPercentage: report.image.diffPercentage }),
+    ...(report.image?.diffPixelCount !== undefined && {
+      diffPixelCount: report.image.diffPixelCount,
+    }),
+    ...(report.image?.totalPixels !== undefined && {
+      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;
+}
+
+export function buildPreviewDesignReferenceFromReport(
+  report: PreviewComparisonReport
+): PreviewDesignReference {
+  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: RenderedPreviewComparisonSource
+): PreviewDesignComparisonState | undefined {
+  const state: PreviewDesignComparisonState = {
+    ...(preview.variantId && { variantId: preview.variantId }),
+    ...(preview.theme && { theme: preview.theme }),
+    ...(preview.viewport && { viewport: preview.viewport }),
+  };
+  return Object.keys(state).length > 0 ? state : undefined;
+}
+
+function cleanStyleMap(
+  styles: PreviewComparisonStyleMap | undefined
+): Record<string, string> | undefined {
+  if (!styles) return undefined;
+  const entries = Object.entries(styles).filter(
+    (entry): entry is [string, string] => typeof entry[1] === "string"
+  );
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+function imageDiffFromComparison(
+  comparison: PreviewDesignComparisonReference | undefined
+): PreviewImageDiffInput | undefined {
+  if (!comparison || comparison.diffPercentage === undefined) return undefined;
+
+  return {
+    diffPercentage: comparison.diffPercentage,
+    changedRegions: comparison.changedRegions,
+    diffImageUrl: comparison.diffImageUrl,
+    diffPixelCount: comparison.diffPixelCount,
+    totalPixels: comparison.totalPixels,
+  };
+}
+
+function compareImageDiff(
+  imageDiff: PreviewImageDiffInput | undefined,
+  thresholds: PreviewComparisonThresholds,
+  findings: PreviewComparisonFinding[]
+): PreviewComparisonReport["image"] | undefined {
+  if (!imageDiff) return undefined;
+  const normalized = normalizeImageDiffEvidence(imageDiff, findings);
+  if (!normalized) return undefined;
+
+  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: PreviewComparisonSize | undefined,
+  preview: PreviewComparisonSize | undefined,
+  thresholds: PreviewComparisonThresholds,
+  findings: PreviewComparisonFinding[]
+): PreviewComparisonReport["dimensions"] | undefined {
+  if (!design || !preview) return undefined;
+  if (!isPositiveComparisonSize(design) || !isPositiveComparisonSize(preview)) {
+    findings.push({
+      code: "invalid-comparison-signal",
+      severity: "warning",
+      message: "Design and preview sizes must be finite positive numbers.",
+    });
+    return undefined;
+  }
+
+  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: unknown,
+  fallback: number,
+  bounds: { min: number; max?: number }
+): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  if (value < bounds.min) return fallback;
+  if (bounds.max !== undefined && value > bounds.max) return fallback;
+  return value;
+}

package/src/preview/index.ts

@@ -0,0 +1,10 @@
+export * from "./comparison";
+export * from "./comparison-artifact";
+export * from "./comparison-presentation";
+export {
+  buildFigmaDesignSource,
+  getPreviewDesignReference,
+  parseFigmaNodeUrl,
+} from "./comparison-references";
+export * from "./types";
+export * from "./validation";