@usefragments/core 1.0.0

package/src/preview/comparison-references.test.ts

@@ -0,0 +1,430 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildFigmaDesignSource,
+  buildPreviewComparisonReport,
+  getPreviewDesignReference,
+  getPreviewComparisonContextSummary,
+  parseFigmaNodeUrl,
+  type PreviewComponentDefinition,
+} from "./index";
+
+describe("preview design references", () => {
+  it("parses Figma design and file URLs", () => {
+    expect(parseFigmaNodeUrl("https://www.figma.com/design/file123/System?node-id=1%3A2")).toEqual({
+      fileKey: "file123",
+      nodeId: "1:2",
+    });
+    expect(parseFigmaNodeUrl("https://figma.com/file/file456/System?node-id=3-4")).toEqual({
+      fileKey: "file456",
+      nodeId: "3:4",
+    });
+    expect(parseFigmaNodeUrl("www.figma.com/design/file789?node-id=5-6&t=abc123")).toEqual({
+      fileKey: "file789",
+      nodeId: "5:6",
+    });
+
+    expect(parseFigmaNodeUrl("https://example.com")).toBeNull();
+    expect(parseFigmaNodeUrl("https://evilfigma.com/design/file123/System?node-id=1-2")).toBeNull();
+    expect(parseFigmaNodeUrl("https://www.figma.com/design/file123/System")).toBeNull();
+  });
+
+  it("resolves variant design references before component defaults", () => {
+    const component: PreviewComponentDefinition = {
+      componentKey: "Button",
+      publicRef: "Button",
+      displayName: "Button",
+      exportName: "Button",
+      importPath: "@acme/ui",
+      tier: "primitive",
+      previewability: "ready",
+      definitionSource: "manual",
+      diagnostics: [],
+      props: {},
+      design: {
+        provider: "figma",
+        label: "Button",
+        nodeUrl: "https://www.figma.com/design/file123/System?node-id=1%3A2",
+      },
+      variants: [
+        {
+          id: "secondary",
+          name: "Secondary",
+          source: "manual",
+          props: {},
+          design: {
+            provider: "figma",
+            label: "Button / Secondary",
+            nodeUrl: "https://www.figma.com/design/file123/System?node-id=4%3A5",
+            imageUrl: "/figma/button-secondary.png",
+            size: { width: 120, height: 40 },
+            comparison: {
+              state: {
+                variantId: "secondary",
+                theme: "light",
+                viewport: { width: 120, height: 40 },
+              },
+              previewImageUrl: "/captures/button-secondary.png",
+              previewSize: { width: 120, height: 40 },
+              designStyles: {
+                backgroundColor: "#ffffff",
+                borderRadius: "8px",
+              },
+              previewStyles: {
+                backgroundColor: "rgb(255, 255, 255)",
+                borderRadius: "8px",
+              },
+              diffImageUrl: "/diffs/button-secondary.png",
+              diffPercentage: 0.25,
+              changedRegions: [{ x: 0, y: 0, width: 4, height: 4 }],
+              capturedAt: "2026-05-24T00:00:00.000Z",
+            },
+          },
+        },
+      ],
+    };
+
+    const reference = getPreviewDesignReference(component, "secondary");
+
+    expect(reference).toEqual({
+      provider: "figma",
+      label: "Button / Secondary",
+      nodeUrl: "https://www.figma.com/design/file123/System?node-id=4%3A5",
+      fileKey: "file123",
+      nodeId: "4:5",
+      imageUrl: "/figma/button-secondary.png",
+      size: { width: 120, height: 40 },
+      comparison: {
+        state: {
+          variantId: "secondary",
+          theme: "light",
+          viewport: { width: 120, height: 40 },
+        },
+        previewImageUrl: "/captures/button-secondary.png",
+        previewSize: { width: 120, height: 40 },
+        designStyles: {
+          backgroundColor: "#ffffff",
+          borderRadius: "8px",
+        },
+        previewStyles: {
+          backgroundColor: "rgb(255, 255, 255)",
+          borderRadius: "8px",
+        },
+        diffImageUrl: "/diffs/button-secondary.png",
+        diffPercentage: 0.25,
+        changedRegions: [{ x: 0, y: 0, width: 4, height: 4 }],
+        capturedAt: "2026-05-24T00:00:00.000Z",
+      },
+    });
+    expect(buildFigmaDesignSource(reference!, "Button")).toEqual({
+      kind: "figma",
+      label: "Button / Secondary",
+      fileKey: "file123",
+      nodeId: "4:5",
+      nodeUrl: "https://www.figma.com/design/file123/System?node-id=4%3A5",
+      imageUrl: "/figma/button-secondary.png",
+      size: { width: 120, height: 40 },
+    });
+
+    const report = buildPreviewComparisonReport({
+      component,
+      variantId: "secondary",
+      preview: {
+        variantId: "secondary",
+        theme: "light",
+        viewport: { width: 120, height: 40 },
+        size: { width: 120, height: 40 },
+      },
+    });
+
+    expect(report).toMatchObject({
+      status: "pass",
+      design: {
+        label: "Button / Secondary",
+        imageUrl: "/figma/button-secondary.png",
+      },
+      preview: {
+        label: "Button / Secondary",
+        componentKey: "Button",
+        variantId: "secondary",
+        imageUrl: "/captures/button-secondary.png",
+        size: { width: 120, height: 40 },
+        capturedAt: "2026-05-24T00:00:00.000Z",
+      },
+      image: {
+        diffPercentage: 0.25,
+        diffImageUrl: "/diffs/button-secondary.png",
+        changedRegions: [{ x: 0, y: 0, width: 4, height: 4 }],
+      },
+      styles: {
+        match: true,
+        properties: [
+          {
+            property: "backgroundColor",
+            design: "#ffffff",
+            preview: "rgb(255, 255, 255)",
+            match: true,
+          },
+          {
+            property: "borderRadius",
+            design: "8px",
+            preview: "8px",
+            match: true,
+          },
+        ],
+      },
+    });
+  });
+
+  it("does not score stored capture evidence when preview state changed", () => {
+    const component: PreviewComponentDefinition = {
+      componentKey: "Card",
+      publicRef: "Card",
+      displayName: "Card",
+      exportName: "Card",
+      importPath: "@acme/ui",
+      tier: "primitive",
+      previewability: "ready",
+      definitionSource: "manual",
+      diagnostics: [],
+      props: {},
+      design: {
+        provider: "figma",
+        label: "Card / Summary",
+        nodeUrl: "https://www.figma.com/design/file123/System?node-id=8%3A9",
+        imageUrl: "/figma/card-summary.png",
+        size: { width: 360, height: 220 },
+        comparison: {
+          state: {
+            variantId: "summary",
+            theme: "light",
+            viewport: { width: 360, height: 220 },
+          },
+          previewImageUrl: "/captures/card-summary.png",
+          previewSize: { width: 360, height: 220 },
+          designStyles: { backgroundColor: "#ffffff" },
+          previewStyles: { backgroundColor: "rgb(255, 255, 255)" },
+          diffImageUrl: "/diffs/card-summary.png",
+          diffPercentage: 0.2,
+          capturedAt: "2026-05-24T00:00:00.000Z",
+        },
+      },
+      variants: [{ id: "summary", name: "Summary", source: "manual", props: {} }],
+    };
+
+    const report = buildPreviewComparisonReport({
+      component,
+      variantId: "summary",
+      preview: {
+        variantId: "summary",
+        theme: "dark",
+        viewport: { width: 360, height: 220 },
+        size: { width: 360, height: 220 },
+      },
+    });
+
+    expect(report?.status).toBe("review");
+    expect(report?.image).toBeUndefined();
+    expect(report?.styles).toBeUndefined();
+    expect(report?.preview.imageUrl).toBeUndefined();
+    expect(report?.findings).toMatchObject([
+      {
+        code: "stale-comparison-signal",
+        severity: "warning",
+      },
+    ]);
+    expect(report?.findings[0]?.message).toContain("theme dark");
+    expect(report?.context).toMatchObject({
+      scope: "component",
+      stale: true,
+      staleReasons: ["theme"],
+      captured: {
+        variantId: "summary",
+        theme: "light",
+      },
+      active: {
+        variantId: "summary",
+        theme: "dark",
+      },
+    });
+    expect(getPreviewComparisonContextSummary(report!)).toEqual({
+      status: "stale",
+      label: "Capture context",
+      value: "Stale evidence",
+      detail: "Captured theme light, viewport 360 x 220; current theme dark, viewport 360 x 220.",
+    });
+  });
+
+  it("does not enforce component-level captured variant ids", () => {
+    const component: PreviewComponentDefinition = {
+      componentKey: "Card",
+      publicRef: "Card",
+      displayName: "Card",
+      exportName: "Card",
+      importPath: "@acme/ui",
+      tier: "primitive",
+      previewability: "ready",
+      definitionSource: "manual",
+      diagnostics: [],
+      props: {},
+      design: {
+        provider: "figma",
+        label: "Card / Summary",
+        size: { width: 360, height: 220 },
+        comparison: {
+          state: {
+            variantId: "default",
+            theme: "light",
+            viewport: { width: 360, height: 220 },
+          },
+          previewSize: { width: 360, height: 220 },
+          diffPercentage: 0.2,
+        },
+      },
+      variants: [
+        { id: "default", name: "Default", source: "manual", props: {} },
+        { id: "summary", name: "Summary", source: "manual", props: {} },
+      ],
+    };
+
+    const report = buildPreviewComparisonReport({
+      component,
+      variantId: "summary",
+      preview: {
+        variantId: "summary",
+        theme: "light",
+        viewport: { width: 360, height: 220 },
+        size: { width: 360, height: 220 },
+      },
+    });
+
+    expect(report?.status).toBe("pass");
+    expect(report?.findings).toEqual([]);
+    expect(report?.image?.diffPercentage).toBe(0.2);
+    expect(getPreviewComparisonContextSummary(report!)).toMatchObject({
+      status: "current",
+      value: "Current evidence",
+      detail: "Captured theme light, viewport 360 x 220.",
+    });
+  });
+
+  it("enforces explicit variant-scoped design references", () => {
+    const component: PreviewComponentDefinition = {
+      componentKey: "Button",
+      publicRef: "Button",
+      displayName: "Button",
+      exportName: "Button",
+      importPath: "@acme/ui",
+      tier: "primitive",
+      previewability: "ready",
+      definitionSource: "manual",
+      diagnostics: [],
+      props: {},
+      variants: [
+        { id: "primary", name: "Primary", source: "manual", props: {} },
+        { id: "secondary", name: "Secondary", source: "manual", props: {} },
+      ],
+    };
+    const designReference = {
+      provider: "figma" as const,
+      label: "Button / Primary",
+      size: { width: 120, height: 40 },
+      comparison: {
+        state: {
+          variantId: "primary",
+          theme: "light",
+          viewport: { width: 120, height: 40 },
+        },
+        previewSize: { width: 120, height: 40 },
+        diffPercentage: 0.2,
+      },
+    };
+
+    const report = buildPreviewComparisonReport({
+      component,
+      variantId: "secondary",
+      designReference,
+      designReferenceScope: "variant",
+      preview: {
+        variantId: "secondary",
+        theme: "light",
+        viewport: { width: 120, height: 40 },
+        size: { width: 120, height: 40 },
+      },
+    });
+
+    expect(report?.status).toBe("review");
+    expect(report?.image).toBeUndefined();
+    expect(report?.findings).toMatchObject([
+      {
+        code: "stale-comparison-signal",
+        severity: "warning",
+      },
+    ]);
+    expect(report?.findings[0]?.message).toContain("variant secondary");
+  });
+
+  it("scores artifact capture evidence before live iframe measurements", () => {
+    const component: PreviewComponentDefinition = {
+      componentKey: "Card",
+      publicRef: "Card",
+      displayName: "Card",
+      exportName: "Card",
+      importPath: "@acme/ui",
+      tier: "primitive",
+      previewability: "ready",
+      definitionSource: "manual",
+      diagnostics: [],
+      props: {},
+      design: {
+        provider: "figma",
+        label: "Card / Summary",
+        nodeUrl: "https://www.figma.com/design/file123/System?node-id=8%3A9",
+        imageUrl: "/figma/card-summary.png",
+        size: { width: 360, height: 220 },
+        comparison: {
+          state: {
+            variantId: "summary",
+            theme: "light",
+            viewport: { width: 360, height: 220 },
+          },
+          previewImageUrl: "/captures/card-summary.png",
+          previewSize: { width: 360, height: 220 },
+          diffImageUrl: "/diffs/card-summary.png",
+          diffPercentage: 0.2,
+          diffPixelCount: 158,
+          totalPixels: 79200,
+          capturedAt: "2026-05-24T00:00:00.000Z",
+        },
+      },
+      variants: [{ id: "summary", name: "Summary", source: "manual", props: {} }],
+    };
+
+    const report = buildPreviewComparisonReport({
+      component,
+      variantId: "summary",
+      preview: {
+        variantId: "summary",
+        theme: "light",
+        viewport: { width: 360, height: 220 },
+        // The current iframe may measure the scaled live box differently.
+        // Captured evidence should remain the scored comparison source.
+        size: { width: 324, height: 218 },
+      },
+    });
+
+    expect(report?.status).toBe("pass");
+    expect(report?.score).toBe(98);
+    expect(report?.dimensions).toMatchObject({
+      match: true,
+      preview: { width: 360, height: 220 },
+      delta: { width: 0, height: 0 },
+    });
+    expect(report?.image).toMatchObject({
+      match: true,
+      diffPercentage: 0.2,
+      diffPixelCount: 158,
+      totalPixels: 79200,
+      diffImageUrl: "/diffs/card-summary.png",
+    });
+  });
+});

package/src/preview/comparison-references.ts

@@ -0,0 +1,72 @@
+import type { PreviewComponentDefinition, PreviewDesignReference } from "./types";
+import type { FigmaDesignComparisonSource } from "./comparison";
+
+export function parseFigmaNodeUrl(url: string): { fileKey: string; nodeId: string } | null {
+  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, ":") };
+}
+
+export function getPreviewDesignReference(
+  component: PreviewComponentDefinition,
+  variantId?: string
+): PreviewDesignReference | undefined {
+  const variant = variantId
+    ? component.variants.find((candidate) => candidate.id === variantId)
+    : undefined;
+
+  return normalizePreviewDesignReference(variant?.design ?? component.design);
+}
+
+export function buildFigmaDesignSource(
+  reference: PreviewDesignReference,
+  fallbackLabel: string
+): FigmaDesignComparisonSource {
+  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,
+  };
+}
+
+export function normalizePreviewDesignReference(
+  reference: PreviewDesignReference | undefined
+): PreviewDesignReference | undefined {
+  if (!reference) return undefined;
+  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: string): boolean {
+  return hostname === "figma.com" || hostname.endsWith(".figma.com");
+}
+
+function parseUrl(url: string): URL | null {
+  try {
+    return new URL(url.includes("://") ? url : `https://${url}`);
+  } catch {
+    return null;
+  }
+}

package/src/preview/comparison-score.ts

@@ -0,0 +1,59 @@
+import type {
+  PreviewComparisonFinding,
+  PreviewComparisonReport,
+  PreviewComparisonStatus,
+} from "./comparison";
+
+export function scoreComparison(parts: {
+  image: PreviewComparisonReport["image"] | undefined;
+  dimensions: PreviewComparisonReport["dimensions"] | undefined;
+  styles: PreviewComparisonReport["styles"] | undefined;
+}): number | null {
+  const scores: Array<{ weight: number; score: number }> = [];
+
+  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);
+}
+
+export function resolveStatus(
+  score: number | null,
+  findings: PreviewComparisonFinding[]
+): PreviewComparisonStatus {
+  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";
+}
+
+export function summarizeStatus(
+  status: PreviewComparisonStatus,
+  score: number | null,
+  findings: PreviewComparisonFinding[]
+): string {
+  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}).`;
+}