@usefragments/core 1.0.0

package/src/preview/types.ts

@@ -0,0 +1,309 @@
+export type JsonPrimitive = string | number | boolean | null;
+
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export type Previewability =
+  | "ready"
+  | "building"
+  | "needs-preview-provider"
+  | "missing-dependency"
+  | "missing-asset"
+  | "server-only"
+  | "unsupported-framework"
+  | "runtime-error"
+  | "build-error"
+  | "docs-only";
+
+export type PreviewDefinitionSource = "typescript" | "fragment" | "manual" | "synthesized";
+
+/**
+ * Seed provenance of a Specimen state (Slice 4). Distinct from
+ * `PreviewDefinitionSource` (how the variant def was authored): this records
+ * which evidence stream the state came from, in confidence order — a real
+ * Storybook story (`csf`), an observed call-site (`usage`), a fragment variant
+ * (`fragment`), or a synthesized enum-gap filler (`synthesized`).
+ */
+export type SpecimenStateSource = "csf" | "usage" | "fragment" | "synthesized";
+
+export type PreviewComponentTier = "primitive" | "provider-backed" | "app-context" | "server-bound";
+
+export interface PreviewArtifactIdentity {
+  artifactId: string;
+  artifactVersion: "preview-artifact/v1";
+  orgId: string;
+  projectId: string;
+  bindingId: string;
+  repoFullName: string;
+  commitSha: string;
+  sourceRef: string;
+  packageName?: string;
+  packagePath?: string;
+  lockfileHash?: string;
+  configHash?: string;
+  createdAt: string;
+}
+
+export interface PreviewArtifactBuilder {
+  name: string;
+  version: string;
+  configFile?: string;
+  typecheck: "typescript" | "none";
+  sources: PreviewDefinitionSource[];
+  adapters: string[];
+}
+
+export interface PreviewArtifactManifest {
+  artifactVersion: "preview-artifact/v1";
+  identity: PreviewArtifactIdentity;
+  builder: PreviewArtifactBuilder;
+  runtime: {
+    framework: "react";
+    reactVersion?: string;
+    moduleFormat: "esm";
+    entry: string;
+    css: string[];
+    assetsBaseUrl: string;
+  };
+  capabilities: PreviewArtifactCapabilities;
+  components: Record<string, PreviewComponentDefinition>;
+  diagnostics: PreviewDiagnostic[];
+  /**
+   * The component-contract FCID (`contractHash`) this specimen was derived
+   * against (Slice 4). Lets ingest pin each state row to its `contractVersions`
+   * row so a served state names the same contract identity CI enforces.
+   */
+  derivedFromContractHash?: string;
+}
+
+export interface PreviewArtifactCapabilities {
+  supportsThemes: boolean;
+  supportsViewports: boolean;
+  supportsActions: boolean;
+  supportsSlots: boolean;
+  supportsA11yScan: boolean;
+  supportsPlayFunctions: boolean;
+  supportsSceneNodes: boolean;
+}
+
+export interface PreviewDesignReference {
+  provider: "figma";
+  label?: string;
+  nodeUrl?: string;
+  fileKey?: string;
+  nodeId?: string;
+  imageUrl?: string;
+  size?: {
+    width: number;
+    height: number;
+  };
+  /**
+   * Optional comparison evidence produced by a preview capture pipeline.
+   *
+   * The preview package stores and scores this evidence, but does not own
+   * browser rendering, Figma API calls, or pixel-diff execution. Node
+   * consumers such as the CLI can populate these fields from Playwright,
+   * Figma, and pixelmatch; UI consumers can render the same report shape.
+   */
+  comparison?: PreviewDesignComparisonReference;
+}
+
+export interface PreviewDesignComparisonReference {
+  /**
+   * Preview state that produced this stored evidence. Consumers can still show
+   * the linked design for other states, but should only score stored image and
+   * style evidence when the active preview state matches this context.
+   */
+  state?: PreviewDesignComparisonState;
+  previewImageUrl?: string;
+  previewSize?: {
+    width: number;
+    height: number;
+  };
+  designStyles?: Record<string, string>;
+  previewStyles?: Record<string, string>;
+  diffImageUrl?: string;
+  diffPercentage?: number;
+  diffPixelCount?: number;
+  totalPixels?: number;
+  changedRegions?: Array<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }>;
+  capturedAt?: string;
+}
+
+export interface PreviewDesignComparisonState {
+  variantId?: string;
+  theme?: string;
+  viewport?: PreviewViewport;
+}
+
+export interface PreviewComponentDefinition {
+  componentKey: string;
+  publicRef: string;
+  displayName: string;
+  sourcePath?: string;
+  exportName: string;
+  importPath: string;
+  tier: PreviewComponentTier;
+  previewability: Previewability;
+  definitionSource: PreviewDefinitionSource;
+  diagnostics: PreviewDiagnostic[];
+  props: Record<string, PreviewPropDefinition>;
+  variants: PreviewVariantDefinition[];
+  defaultVariantId?: string;
+  requiredProviders?: PreviewProviderRequirement[];
+  canvas?: PreviewCanvasMetadata;
+  design?: PreviewDesignReference;
+}
+
+export interface PreviewProviderRequirement {
+  id: string;
+  label: string;
+  optional?: boolean;
+}
+
+export interface PreviewCanvasMetadata {
+  defaultWidth?: number;
+  defaultHeight?: number;
+  supportsChildren?: boolean;
+}
+
+export interface PreviewPropDefinition {
+  name: string;
+  type: string;
+  required: boolean;
+  defaultValue?: JsonValue;
+  source: PreviewDefinitionSource;
+  control:
+    | { type: "text" }
+    | { type: "number"; min?: number; max?: number; step?: number }
+    | { type: "boolean" }
+    | { type: "select"; options: Array<string | number | boolean> }
+    | { type: "color" }
+    | { type: "slot"; presets: PreviewSlotPreset[] }
+    | { type: "action" }
+    | { type: "unsupported"; reason: string };
+  description?: string;
+}
+
+export interface PreviewVariantDefinition {
+  id: string;
+  name: string;
+  description?: string;
+  source: PreviewDefinitionSource;
+  props: Record<string, JsonValue>;
+  slots?: Record<string, PreviewSlotValue>;
+  tags?: string[];
+  /** Seed provenance of this state (Slice 4); pinned alongside the FCID. */
+  stateSource?: SpecimenStateSource;
+  /** Confidence of the seed, 0..1 (csf high → synthesized low). */
+  confidence?: number;
+  design?: PreviewDesignReference;
+}
+
+export type PreviewSlotValue =
+  | { kind: "text"; value: string }
+  | { kind: "html"; value: string }
+  | { kind: "component"; node: ComponentInstanceNode };
+
+export interface PreviewSlotPreset {
+  id: string;
+  label: string;
+  value: PreviewSlotValue;
+}
+
+export type ComponentCanvasNode = ComponentInstanceNode | FrameNode | TextNode;
+
+export interface ComponentInstanceNode {
+  kind: "component-instance";
+  nodeId: string;
+  componentKey: string;
+  variantId?: string;
+  props: Record<string, JsonValue>;
+  slots: Record<string, ComponentCanvasNode[]>;
+  layout: LayoutConstraints;
+  styleOverrides?: ComponentStyleOverrides;
+}
+
+export interface FrameNode {
+  kind: "frame";
+  nodeId: string;
+  children: string[];
+  layout: LayoutConstraints;
+  style?: {
+    background?: string;
+    padding?: number | string;
+    gap?: number | string;
+  };
+}
+
+export interface TextNode {
+  kind: "text";
+  nodeId: string;
+  text: string;
+  layout: LayoutConstraints;
+}
+
+export interface LayoutConstraints {
+  position?: "auto" | "absolute";
+  width?: "hug" | "fill" | number;
+  height?: "hug" | "fill" | number;
+  minWidth?: number;
+  minHeight?: number;
+  x?: number;
+  y?: number;
+}
+
+export interface ComponentStyleOverrides {
+  className?: string;
+  style?: Record<string, JsonValue>;
+}
+
+export interface PreviewViewport {
+  width: number;
+  height: number;
+  background?: string;
+}
+
+export interface RenderPreviewArgs {
+  action: (name: string, payload?: JsonValue[]) => void;
+  component: PreviewComponentDefinition;
+  componentKey: string;
+  manifest: PreviewArtifactManifest;
+  props: Record<string, JsonValue>;
+  root: HTMLElement;
+  slots: Record<string, PreviewSlotValue>;
+  theme?: string;
+  variantId?: string;
+  viewport?: PreviewViewport;
+}
+
+export type PreviewCleanup = void | (() => void) | { cleanup: () => void };
+
+export type RenderPreview = (args: RenderPreviewArgs) => PreviewCleanup | Promise<PreviewCleanup>;
+
+export interface PreviewDiagnostic {
+  code:
+    | "missing-dependency"
+    | "missing-peer-dependency"
+    | "unresolved-import"
+    | "unsupported-server-component"
+    | "node-only-import"
+    | "missing-env"
+    | "missing-provider"
+    | "missing-asset"
+    | "css-build-failed"
+    | "runtime-error"
+    | "render-timeout"
+    | "unsupported-prop-control";
+  severity: "info" | "warning" | "error";
+  message: string;
+  componentKey?: string;
+  sourcePath?: string;
+  importPath?: string;
+  suggestedFix?: string;
+  docsHref?: string;
+}

package/src/preview/validation.test.ts

@@ -0,0 +1,290 @@
+import { describe, expect, it } from "vitest";
+import { definePreviewArtifactManifest, isPreviewArtifactManifest } from "./index";
+import type { PreviewArtifactManifest } from "./index";
+
+const manifest: PreviewArtifactManifest = {
+  artifactVersion: "preview-artifact/v1",
+  identity: {
+    artifactId: "example-preview-artifact-v1",
+    artifactVersion: "preview-artifact/v1",
+    orgId: "org",
+    projectId: "project",
+    bindingId: "binding",
+    repoFullName: "acme/ui",
+    commitSha: "abc123",
+    sourceRef: "main",
+    packageName: "@acme/ui",
+    createdAt: "2026-05-20T00:00:00.000Z",
+  },
+  builder: {
+    name: "@fragments-sdk/preview",
+    version: "0.1.0",
+    typecheck: "typescript",
+    sources: ["typescript", "manual"],
+    adapters: ["react"],
+  },
+  runtime: {
+    framework: "react",
+    reactVersion: "19.x",
+    moduleFormat: "esm",
+    entry: "index.js",
+    css: ["index.css"],
+    assetsBaseUrl: "/preview/",
+  },
+  capabilities: {
+    supportsThemes: true,
+    supportsViewports: true,
+    supportsActions: true,
+    supportsSlots: true,
+    supportsA11yScan: false,
+    supportsPlayFunctions: false,
+    supportsSceneNodes: false,
+  },
+  components: {
+    Button: {
+      componentKey: "Button",
+      publicRef: "Button",
+      displayName: "Button",
+      sourcePath: "src/button.tsx",
+      exportName: "Button",
+      importPath: "@acme/ui",
+      tier: "primitive",
+      previewability: "ready",
+      definitionSource: "typescript",
+      diagnostics: [],
+      props: {},
+      variants: [
+        {
+          id: "default",
+          name: "Default",
+          source: "manual",
+          props: {},
+          design: {
+            provider: "figma",
+            label: "Button / Default",
+            nodeUrl: "https://www.figma.com/design/file/System?node-id=1%3A2",
+            imageUrl: "/preview/button-default-figma.png",
+            size: { width: 120, height: 40 },
+            comparison: {
+              previewImageUrl: "/preview/button-default-capture.png",
+              previewSize: { width: 120, height: 40 },
+              designStyles: {
+                backgroundColor: "#ffffff",
+                borderRadius: "8px",
+              },
+              previewStyles: {
+                backgroundColor: "rgb(255, 255, 255)",
+                borderRadius: "8px",
+              },
+              diffImageUrl: "/preview/button-default-diff.png",
+              diffPercentage: 0.2,
+              diffPixelCount: 10,
+              totalPixels: 4800,
+              changedRegions: [{ x: 4, y: 4, width: 12, height: 8 }],
+              capturedAt: "2026-05-24T00:00:00.000Z",
+            },
+          },
+        },
+      ],
+      defaultVariantId: "default",
+    },
+  },
+  diagnostics: [],
+};
+
+describe("@usefragments/core/preview artifact validation", () => {
+  it("accepts a typed preview artifact manifest", () => {
+    expect(isPreviewArtifactManifest(manifest)).toBe(true);
+    expect(definePreviewArtifactManifest(manifest)).toBe(manifest);
+  });
+
+  it("rejects manifests without builder metadata", () => {
+    const invalid = { ...manifest, builder: undefined };
+
+    expect(isPreviewArtifactManifest(invalid)).toBe(false);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/builder must be an object/);
+  });
+
+  it("rejects Storybook as a Fragments-native source type", () => {
+    const invalid = {
+      ...manifest,
+      builder: {
+        ...manifest.builder,
+        sources: ["storybook"],
+      },
+      components: {
+        Button: {
+          ...manifest.components.Button,
+          definitionSource: "storybook",
+        },
+      },
+    };
+
+    expect(isPreviewArtifactManifest(invalid)).toBe(false);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/unsupported source "storybook"/);
+  });
+
+  it("rejects malformed design comparison evidence", () => {
+    const invalid = {
+      ...manifest,
+      components: {
+        Button: {
+          ...manifest.components.Button,
+          design: {
+            provider: "figma",
+            size: { width: 0, height: 40 },
+            comparison: {
+              state: {
+                variantId: 123,
+                theme: false,
+                viewport: { width: 120, height: 0 },
+              },
+              previewImageUrl: 123,
+              previewSize: { width: 120, height: -1 },
+              designStyles: { backgroundColor: 123 },
+              previewStyles: [],
+              diffPercentage: 120,
+              changedRegions: [{ x: -1, y: 0, width: 12, height: 8 }],
+            },
+          },
+        },
+      },
+    };
+
+    expect(isPreviewArtifactManifest(invalid)).toBe(false);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/components.Button.design.size.width must be a positive number/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/components.Button.design.comparison.previewImageUrl must be a string/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/components.Button.design.comparison.state.variantId must be a string/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/components.Button.design.comparison.state.theme must be a string/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(
+      /components.Button.design.comparison.state.viewport.height must be a positive number/
+    );
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/components.Button.design.comparison.designStyles.backgroundColor must be a string/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/components.Button.design.comparison.previewStyles must be an object/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/components.Button.design.comparison.diffPercentage must be between 0 and 100/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(
+      /components.Button.design.comparison.changedRegions.0.x must be a non-negative number/
+    );
+  });
+
+  it("rejects changed regions outside the comparison source size", () => {
+    const invalid = {
+      ...manifest,
+      components: {
+        Button: {
+          ...manifest.components.Button,
+          design: {
+            provider: "figma",
+            size: { width: 120, height: 40 },
+            comparison: {
+              previewSize: { width: 100, height: 32 },
+              diffPercentage: 0.2,
+              changedRegions: [{ x: 90, y: 24, width: 20, height: 12 }],
+            },
+          },
+        },
+      },
+    };
+
+    expect(isPreviewArtifactManifest(invalid)).toBe(false);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(
+      /components.Button.design.comparison.changedRegions.0 must fit within comparison source width 100/
+    );
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(
+      /components.Button.design.comparison.changedRegions.0 must fit within comparison source height 32/
+    );
+  });
+
+  it("rejects impossible comparison pixel counts", () => {
+    const invalid = {
+      ...manifest,
+      components: {
+        Button: {
+          ...manifest.components.Button,
+          design: {
+            provider: "figma",
+            size: { width: 120, height: 40 },
+            comparison: {
+              diffPercentage: 0.2,
+              diffPixelCount: 5000,
+              totalPixels: 4800,
+            },
+          },
+        },
+      },
+    };
+
+    const fractional = {
+      ...invalid,
+      components: {
+        Button: {
+          ...invalid.components.Button,
+          design: {
+            ...invalid.components.Button.design,
+            comparison: {
+              diffPercentage: 0.2,
+              diffPixelCount: 10.5,
+              totalPixels: 4800,
+            },
+          },
+        },
+      },
+    };
+
+    const emptyTotal = {
+      ...invalid,
+      components: {
+        Button: {
+          ...invalid.components.Button,
+          design: {
+            ...invalid.components.Button.design,
+            comparison: {
+              diffPercentage: 0.2,
+              diffPixelCount: 0,
+              totalPixels: 0,
+            },
+          },
+        },
+      },
+    };
+
+    expect(isPreviewArtifactManifest(invalid)).toBe(false);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(
+      /components.Button.design.comparison.diffPixelCount must be less than or equal to components.Button.design.comparison.totalPixels/
+    );
+    expect(() =>
+      definePreviewArtifactManifest(fractional as unknown as PreviewArtifactManifest)
+    ).toThrow(/components.Button.design.comparison.diffPixelCount must be a non-negative integer/);
+    expect(() =>
+      definePreviewArtifactManifest(emptyTotal as unknown as PreviewArtifactManifest)
+    ).toThrow(/components.Button.design.comparison.totalPixels must be a positive integer/);
+  });
+});