@usefragments/core 1.0.0

package/src/preview/validation.ts

@@ -0,0 +1,356 @@
+import type { PreviewArtifactManifest } from "./types";
+
+export interface PreviewArtifactValidationResult {
+  ok: boolean;
+  issues: string[];
+}
+
+export function definePreviewArtifactManifest(
+  manifest: PreviewArtifactManifest
+): PreviewArtifactManifest {
+  const validation = validatePreviewArtifactManifest(manifest);
+  if (!validation.ok) {
+    throw new Error(`Invalid preview artifact manifest:\n${validation.issues.join("\n")}`);
+  }
+  return manifest;
+}
+
+export function validatePreviewArtifactManifest(value: unknown): PreviewArtifactValidationResult {
+  const issues: string[] = [];
+  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 };
+}
+
+export function isPreviewArtifactManifest(value: unknown): value is PreviewArtifactManifest {
+  return validatePreviewArtifactManifest(value).ok;
+}
+
+function validateIdentity(value: unknown, issues: string[]) {
+  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: unknown, issues: string[]) {
+  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: unknown, issues: string[]) {
+  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: unknown, issues: string[]) {
+  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: unknown, issues: string[], path: string) {
+  if (value === undefined) 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] !== undefined && 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: unknown,
+  issues: string[],
+  path: string,
+  designSize: { width: number; height: number } | undefined
+) {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+
+  for (const key of ["previewImageUrl", "diffImageUrl", "capturedAt"]) {
+    if (value[key] !== undefined && 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 !== undefined) {
+    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: unknown, issues: string[], path: string) {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  if (value.variantId !== undefined && typeof value.variantId !== "string") {
+    issues.push(`${path}.variantId must be a string`);
+  }
+  if (value.theme !== undefined && typeof value.theme !== "string") {
+    issues.push(`${path}.theme must be a string`);
+  }
+  validateSize(value.viewport, issues, `${path}.viewport`);
+}
+
+function validatePixelCounts(value: Record<string, unknown>, issues: string[], path: string) {
+  if (value.diffPixelCount !== undefined) {
+    validateNonNegativeInteger(value.diffPixelCount, issues, `${path}.diffPixelCount`);
+  }
+  if (value.totalPixels !== undefined) {
+    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: unknown, issues: string[], path: string) {
+  if (value === undefined) 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: unknown, issues: string[], path: string) {
+  if (value === undefined) 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: unknown,
+  issues: string[],
+  path: string,
+  sourceSize?: { width: number; height: number }
+) {
+  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: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPreviewDefinitionSource(value: unknown): boolean {
+  return (
+    value === "typescript" || value === "fragment" || value === "manual" || value === "synthesized"
+  );
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function validatePositiveNumber(value: unknown, issues: string[], path: string) {
+  if (!isFiniteNumber(value) || value <= 0) {
+    issues.push(`${path} must be a positive number`);
+  }
+}
+
+function validateNonNegativeNumber(value: unknown, issues: string[], path: string) {
+  if (!isFiniteNumber(value) || value < 0) {
+    issues.push(`${path} must be a non-negative number`);
+  }
+}
+
+function validateFiniteNumber(value: unknown, issues: string[], path: string) {
+  if (value !== undefined && !isFiniteNumber(value)) {
+    issues.push(`${path} must be a finite number`);
+  }
+}
+
+function validatePositiveInteger(value: unknown, issues: string[], path: string) {
+  if (!Number.isInteger(value) || !isFiniteNumber(value) || value <= 0) {
+    issues.push(`${path} must be a positive integer`);
+  }
+}
+
+function validateNonNegativeInteger(value: unknown, issues: string[], path: string) {
+  if (!Number.isInteger(value) || !isFiniteNumber(value) || value < 0) {
+    issues.push(`${path} must be a non-negative integer`);
+  }
+}
+
+function readSize(value: unknown): { width: number; height: number } | undefined {
+  if (!isRecord(value)) return undefined;
+  if (!isFiniteNumber(value.width) || value.width <= 0) return undefined;
+  if (!isFiniteNumber(value.height) || value.height <= 0) return undefined;
+  return { width: value.width, height: value.height };
+}
+
+function requireString(object: Record<string, unknown>, key: string, issues: string[], path = "") {
+  if (typeof object[key] !== "string" || !object[key]) {
+    issues.push(`${path ? `${path}.` : ""}${key} must be a non-empty string`);
+  }
+}
+
+function requireLiteral(
+  object: Record<string, unknown>,
+  key: string,
+  expected: string,
+  issues: string[]
+) {
+  if (object[key] !== expected) {
+    issues.push(`${key} must be ${JSON.stringify(expected)}`);
+  }
+}

package/src/preview-runtime.tsx

@@ -0,0 +1,144 @@
+import { useEffect, useState, type ReactNode } from "react";
+import type { VariantLoader, VariantRenderOptions } from "./types.js";
+
+/**
+ * Minimal contract for rendering a preview variant.
+ * Compatible with fragment variants and Storybook-adapted variants.
+ */
+export interface PreviewVariantLike {
+  render: (options?: VariantRenderOptions) => ReactNode;
+  loaders?: VariantLoader[];
+}
+
+export interface PreviewRuntimeState {
+  content: ReactNode | null;
+  isLoading: boolean;
+  error: Error | null;
+  loadedData?: Record<string, unknown>;
+}
+
+export interface PreviewRuntimeOptions {
+  variant?: PreviewVariantLike | null;
+  loadedData?: Record<string, unknown>;
+}
+
+const EMPTY_STATE: PreviewRuntimeState = {
+  content: null,
+  isLoading: false,
+  error: null,
+  loadedData: undefined,
+};
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Execute all variant loaders and merge their payloads.
+ * `loadedData` is applied last so host-level overrides win.
+ */
+export async function executeVariantLoaders(
+  loaders: VariantLoader[] | undefined,
+  loadedData?: Record<string, unknown>,
+): Promise<Record<string, unknown> | undefined> {
+  const hasLoaders = !!loaders && loaders.length > 0;
+  if (!hasLoaders) {
+    return loadedData;
+  }
+
+  const results = await Promise.all(loaders.map((loader) => loader()));
+  const mergedFromLoaders = results.reduce<Record<string, unknown>>(
+    (acc, result) => ({ ...acc, ...result }),
+    {},
+  );
+
+  return loadedData ? { ...mergedFromLoaders, ...loadedData } : mergedFromLoaders;
+}
+
+/**
+ * Resolve a full runtime state (loader execution + render) in one async call.
+ * This is useful for testing and for hook/component orchestration.
+ */
+export async function resolvePreviewRuntimeState(
+  options: PreviewRuntimeOptions,
+): Promise<PreviewRuntimeState> {
+  const { variant, loadedData } = options;
+  if (!variant) {
+    return EMPTY_STATE;
+  }
+
+  try {
+    const mergedLoadedData = await executeVariantLoaders(variant.loaders, loadedData);
+    const content = variant.render({ loadedData: mergedLoadedData });
+    return {
+      content,
+      isLoading: false,
+      error: null,
+      loadedData: mergedLoadedData,
+    };
+  } catch (error) {
+    return {
+      content: null,
+      isLoading: false,
+      error: toError(error),
+      loadedData: undefined,
+    };
+  }
+}
+
+/**
+ * Hook for rendering a preview variant with loader support.
+ */
+export function usePreviewVariantRuntime(
+  options: PreviewRuntimeOptions,
+): PreviewRuntimeState {
+  const { variant, loadedData } = options;
+  const [state, setState] = useState<PreviewRuntimeState>(EMPTY_STATE);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    if (!variant) {
+      setState(EMPTY_STATE);
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    const hasLoaders = !!variant.loaders && variant.loaders.length > 0;
+    setState({
+      content: null,
+      isLoading: hasLoaders,
+      error: null,
+      loadedData: undefined,
+    });
+
+    resolvePreviewRuntimeState({ variant, loadedData }).then((nextState) => {
+      if (!cancelled) {
+        setState(nextState);
+      }
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [variant, loadedData]);
+
+  return state;
+}
+
+interface PreviewVariantRuntimeProps extends PreviewRuntimeOptions {
+  children: (state: PreviewRuntimeState) => ReactNode;
+}
+
+/**
+ * Render-prop component wrapper around `usePreviewVariantRuntime`.
+ */
+export function PreviewVariantRuntime({
+  variant,
+  loadedData,
+  children,
+}: PreviewVariantRuntimeProps) {
+  const state = usePreviewVariantRuntime({ variant, loadedData });
+  return <>{children(state)}</>;
+}

package/src/raw-html-canonical.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+
+import { isEnforceableHtmlEquivalent } from "./raw-html-canonical.js";
+
+describe("isEnforceableHtmlEquivalent — library-agnostic enforcement gate", () => {
+  it("always enforces low-frequency semantic tags for any canonical name", () => {
+    // Agnostic already: a custom-named component on a semantic tag.
+    expect(isEnforceableHtmlEquivalent({ tag: "textarea", canonical: "AcmeTextArea" })).toBe(true);
+    expect(isEnforceableHtmlEquivalent({ tag: "dialog", canonical: "Modal" })).toBe(true);
+  });
+
+  it("enforces an EXPLICITLY-declared button mapping against ANY component name (agnostic)", () => {
+    // The fix: @acme/ui's differently-named canonical button now fires on a raw
+    // <button>, not only the curated built-in "Button".
+    expect(
+      isEnforceableHtmlEquivalent({ tag: "button", canonical: "AcmeButton", explicit: true })
+    ).toBe(true);
+    expect(isEnforceableHtmlEquivalent({ tag: "a", canonical: "AcmeLink", explicit: true })).toBe(
+      true
+    );
+  });
+
+  it("keeps the built-in agreement check for INFERRED button mappings (flood guard)", () => {
+    // No `explicit` provenance → an inferred htmlEquivalent must still agree with
+    // the curated canonical. This is the <button> → Chip flood class (#229).
+    expect(isEnforceableHtmlEquivalent({ tag: "button", canonical: "Chip" })).toBe(false);
+    // Agreement (name === curated) still fires without an explicit flag.
+    expect(isEnforceableHtmlEquivalent({ tag: "button", canonical: "Button" })).toBe(true);
+  });
+
+  it("NEVER enforces generic containers, even when explicitly declared", () => {
+    // The load-bearing flood guard: an explicit div/span declaration must not
+    // turn every container into a bespoke re-implementation.
+    expect(isEnforceableHtmlEquivalent({ tag: "div", canonical: "MyCard", explicit: true })).toBe(
+      false
+    );
+    expect(isEnforceableHtmlEquivalent({ tag: "span", canonical: "MyBadge", explicit: true })).toBe(
+      false
+    );
+  });
+});