@usefragments/core 1.0.0

package/src/preview/comparison-context.ts

@@ -0,0 +1,93 @@
+import type {
+  PreviewComponentDefinition,
+  PreviewDesignComparisonReference,
+  PreviewViewport,
+} from "./types";
+import type {
+  BuildPreviewComparisonReportInput,
+  PreviewComparisonContext,
+  PreviewComparisonContextMismatch,
+  PreviewComparisonFinding,
+  PreviewComparisonReferenceScope,
+} from "./comparison";
+
+export function analyzeComparisonContext(
+  comparison: PreviewDesignComparisonReference | undefined,
+  preview: BuildPreviewComparisonReportInput["preview"] | undefined,
+  variantId: string | undefined,
+  component: PreviewComponentDefinition,
+  scope: PreviewComparisonReferenceScope
+): { context?: PreviewComparisonContext; findings: PreviewComparisonFinding[] } {
+  const expected = comparison?.state;
+  if (!expected) return { findings: [] };
+  const actual = {
+    variantId: preview?.variantId ?? variantId,
+    theme: preview?.theme,
+    viewport: preview?.viewport,
+  };
+
+  const staleReasons: PreviewComparisonContextMismatch[] = [];
+  const mismatchLabels: string[] = [];
+
+  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: PreviewViewport, b: PreviewViewport): boolean {
+  return a.width === b.width && a.height === b.height && a.background === b.background;
+}
+
+function formatComparisonState(state: NonNullable<PreviewDesignComparisonReference["state"]>) {
+  return [
+    state.variantId ? `variant ${state.variantId}` : undefined,
+    state.theme ? `theme ${state.theme}` : undefined,
+    state.viewport ? `viewport ${formatViewport(state.viewport)}` : undefined,
+  ]
+    .filter(Boolean)
+    .join(", ");
+}
+
+function formatViewport(viewport: PreviewViewport): string {
+  return `${viewport.width}x${viewport.height}`;
+}

package/src/preview/comparison-evidence.ts

@@ -0,0 +1,112 @@
+import type {
+  PreviewComparisonBounds,
+  PreviewComparisonFinding,
+  PreviewComparisonSize,
+  PreviewImageDiffInput,
+} from "./comparison";
+
+export interface NormalizedImageDiffEvidence {
+  diffPercentage: number;
+  changedRegions: PreviewComparisonBounds[];
+  diffImageDataUrl?: string;
+  diffImageUrl?: string;
+  diffPixelCount?: number;
+  totalPixels?: number;
+}
+
+export function normalizeImageDiffEvidence(
+  imageDiff: PreviewImageDiffInput,
+  findings: PreviewComparisonFinding[]
+): NormalizedImageDiffEvidence | undefined {
+  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 undefined;
+  }
+
+  return {
+    diffPercentage: imageDiff.diffPercentage,
+    changedRegions: normalizeChangedRegions(imageDiff.changedRegions, findings),
+    ...(imageDiff.diffImageDataUrl && { diffImageDataUrl: imageDiff.diffImageDataUrl }),
+    ...(imageDiff.diffImageUrl && { diffImageUrl: imageDiff.diffImageUrl }),
+    ...normalizePixelCounts(imageDiff, findings),
+  };
+}
+
+export function isPositiveComparisonSize(value: PreviewComparisonSize): boolean {
+  return (
+    Number.isFinite(value.width) &&
+    Number.isFinite(value.height) &&
+    value.width > 0 &&
+    value.height > 0
+  );
+}
+
+function normalizeChangedRegions(
+  regions: PreviewComparisonBounds[] | undefined,
+  findings: PreviewComparisonFinding[]
+): PreviewComparisonBounds[] {
+  if (!regions) return [];
+
+  const validRegions: PreviewComparisonBounds[] = [];
+  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: PreviewImageDiffInput,
+  findings: PreviewComparisonFinding[]
+): Pick<NormalizedImageDiffEvidence, "diffPixelCount" | "totalPixels"> {
+  const { diffPixelCount, totalPixels } = imageDiff;
+  if (diffPixelCount === undefined && totalPixels === undefined) return {};
+
+  if (
+    !Number.isInteger(diffPixelCount) ||
+    !Number.isInteger(totalPixels) ||
+    diffPixelCount === undefined ||
+    totalPixels === undefined ||
+    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: number): boolean {
+  return Number.isFinite(value) && value >= 0 && value <= 100;
+}
+
+function isValidBounds(value: PreviewComparisonBounds): boolean {
+  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
+  );
+}

package/src/preview/comparison-format.ts

@@ -0,0 +1,21 @@
+import type { PreviewComparisonSize } from "./comparison";
+
+export function formatPercent(value: number): string {
+  return `${round(value)}%`;
+}
+
+export function formatDelta(value: number): string {
+  return value > 0 ? `+${round(value)}` : `${round(value)}`;
+}
+
+export function formatSize(size: PreviewComparisonSize): string {
+  return `${round(size.width)} x ${round(size.height)}`;
+}
+
+export function formatInteger(value: number): string {
+  return Math.round(value).toLocaleString("en-US");
+}
+
+export function round(value: number): number {
+  return Math.round(value * 100) / 100;
+}

package/src/preview/comparison-presentation.ts

@@ -0,0 +1,187 @@
+import type {
+  PreviewComparisonBounds,
+  PreviewComparisonFinding,
+  PreviewComparisonContextSummary,
+  PreviewComparisonRegionOverlay,
+  PreviewComparisonReport,
+  PreviewComparisonSignal,
+  PreviewComparisonSize,
+} from "./comparison";
+import type { PreviewDesignComparisonState } from "./types";
+import { formatDelta, formatInteger, formatPercent, formatSize, round } from "./comparison-format";
+
+export function getPreviewComparisonSignals(
+  report: PreviewComparisonReport
+): PreviewComparisonSignal[] {
+  return [buildImageSignal(report), buildDimensionSignal(report), buildStyleSignal(report)];
+}
+
+export function getPreviewComparisonRegionOverlays(
+  report: PreviewComparisonReport
+): PreviewComparisonRegionOverlay[] {
+  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),
+    };
+  });
+}
+
+export function getPreviewComparisonContextSummary(
+  report: PreviewComparisonReport
+): PreviewComparisonContextSummary | null {
+  if (!report.context) return null;
+
+  const captured = report.context.captured
+    ? formatComparisonState(report.context.captured, {
+        includeVariant: report.context.scope === "variant",
+      })
+    : "unknown capture state";
+  const active = formatComparisonState(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}.`,
+  };
+}
+
+export function formatPreviewComparisonFinding(finding: PreviewComparisonFinding): string {
+  const prefix = finding.severity.toUpperCase();
+  const subject = finding.property ? `${finding.property}: ` : "";
+  return `${prefix}: ${subject}${finding.message}`;
+}
+
+function formatComparisonState(
+  state: PreviewDesignComparisonState,
+  options: { includeVariant: boolean }
+): string {
+  const parts = [
+    options.includeVariant && state.variantId ? `variant ${state.variantId}` : undefined,
+    state.theme ? `theme ${state.theme}` : undefined,
+    state.viewport ? `viewport ${formatSize(state.viewport)}` : undefined,
+  ].filter((part): part is string => Boolean(part));
+
+  return parts.length > 0 ? parts.join(", ") : "unspecified preview state";
+}
+
+function buildImageSignal(report: PreviewComparisonReport): PreviewComparisonSignal {
+  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 !== undefined && report.image.totalPixels !== undefined
+      ? `${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: PreviewComparisonReport): PreviewComparisonSignal {
+  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: PreviewComparisonReport): PreviewComparisonSignal {
+  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: PreviewComparisonBounds): string {
+  return `Changed region x ${region.x} y ${region.y} width ${region.width} height ${region.height}`;
+}
+
+function clipRegionToSize(
+  region: PreviewComparisonBounds,
+  size: PreviewComparisonSize
+): PreviewComparisonBounds | null {
+  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,
+  };
+}