@usefragments/core 1.0.0

package/src/package-identity.ts

@@ -0,0 +1,157 @@
+import {
+  OWNED_PACKAGE_AUTHORING_EPOCH,
+  OWNED_PACKAGE_EXPLICIT_POLICIES,
+  OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
+  OWNED_PACKAGE_ROOT_POLICIES,
+} from "./package-identity.generated.js";
+
+export type OwnedPackageStatus = "retained" | "moved" | "retired";
+
+export interface OwnedPackageIdentityResolution {
+  readonly input: string;
+  readonly owned: boolean;
+  readonly identityId?: string;
+  readonly status?: OwnedPackageStatus;
+  /** Supported public read target. Absent for retired identities. */
+  readonly canonicalSpecifier?: string;
+  /** What first-party generators write in the active authoring epoch. */
+  readonly authoringSpecifier?: string;
+  /** Permanent legacy spelling used only inside the fcid-preimage:v1 domain. */
+  readonly v1Specifier: string;
+  /** Supported public spellings for this exact logical read identity. */
+  readonly readEquivalents?: readonly string[];
+}
+
+type ExplicitPolicy = (typeof OWNED_PACKAGE_EXPLICIT_POLICIES)[number];
+type RootPolicy = (typeof OWNED_PACKAGE_ROOT_POLICIES)[number];
+
+function appendSubpath(root: string | null, suffix: string): string | undefined {
+  if (!root) return undefined;
+  return suffix ? `${root}/${suffix}` : root;
+}
+
+function rootSuffix(specifier: string, root: string): string | null {
+  if (specifier === root) return "";
+  const prefix = `${root}/`;
+  return specifier.startsWith(prefix) ? specifier.slice(prefix.length) : null;
+}
+
+function authoringValue(policy: {
+  readonly authoring: { readonly legacy: string; readonly current: string | null };
+}): string | undefined {
+  return policy.authoring[OWNED_PACKAGE_AUTHORING_EPOCH] ?? undefined;
+}
+
+function resolveExplicit(specifier: string): OwnedPackageIdentityResolution | undefined {
+  for (const policy of OWNED_PACKAGE_EXPLICIT_POLICIES) {
+    if (specifier !== policy.legacySpecifier && specifier !== policy.currentSpecifier) continue;
+
+    // A target can also be the canonical identity of another package. The
+    // historical spelling is always unambiguous. Current targets participate
+    // here only when the policy explicitly owns the v1 projection (Preview ->
+    // Core/preview); CLI/core deliberately stays distinct from Core root.
+    if (specifier === policy.currentSpecifier && !policy.matchCurrentForV1) continue;
+
+    return {
+      input: specifier,
+      owned: true,
+      identityId: policy.id,
+      status: policy.status,
+      canonicalSpecifier: policy.currentSpecifier ?? undefined,
+      authoringSpecifier: authoringValue(policy),
+      v1Specifier: policy.v1Projection,
+      readEquivalents: policy.readEquivalents,
+    };
+  }
+  return undefined;
+}
+
+function resolveRoot(specifier: string): OwnedPackageIdentityResolution | undefined {
+  for (const policy of OWNED_PACKAGE_ROOT_POLICIES) {
+    const legacySuffix = rootSuffix(specifier, policy.legacyRoot);
+    const currentSuffix = policy.currentRoot ? rootSuffix(specifier, policy.currentRoot) : null;
+    const suffix = legacySuffix ?? currentSuffix;
+    if (suffix === null) continue;
+
+    const canonicalSpecifier =
+      policy.status === "retained"
+        ? appendSubpath(policy.currentRoot, suffix)
+        : suffix === ""
+          ? (policy.targetSpecifier ?? undefined)
+          : undefined;
+    const authoredRoot = authoringValue(policy);
+
+    return {
+      input: specifier,
+      owned: true,
+      identityId: policy.id,
+      status: policy.status,
+      canonicalSpecifier,
+      authoringSpecifier: appendSubpath(authoredRoot ?? null, suffix),
+      v1Specifier: appendSubpath(policy.v1Projection, suffix) ?? specifier,
+      readEquivalents: policy.readEquivalents.map((root) => appendSubpath(root, suffix) ?? root),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * Resolve only exact Fragments-owned npm roots/subpaths. Unknown packages and
+ * arbitrary strings are intentionally opaque; this is not a substring rewrite.
+ */
+export function resolveOwnedPackageImport(specifier: string): OwnedPackageIdentityResolution {
+  return (
+    resolveExplicit(specifier) ??
+    resolveRoot(specifier) ?? {
+      input: specifier,
+      owned: false,
+      v1Specifier: specifier,
+    }
+  );
+}
+
+/**
+ * Canonical current-read spelling. Retired/unknown identities are returned
+ * unchanged so a caller cannot accidentally expose a private @repo/* target.
+ */
+export function canonicalizeOwnedImport(specifier: string): string {
+  return resolveOwnedPackageImport(specifier).canonicalSpecifier ?? specifier;
+}
+
+/** Active-epoch spelling for generators; retired/unknown inputs stay unchanged. */
+export function authorOwnedImport(specifier: string): string {
+  return resolveOwnedPackageImport(specifier).authoringSpecifier ?? specifier;
+}
+
+/**
+ * Permanent compatibility encoder for fcid-preimage:v1 only. Never use this
+ * result for source edits, suggestions, provenance, or generated guidance.
+ */
+export function projectV1OwnedImportIdentity(specifier: string): string {
+  return resolveOwnedPackageImport(specifier).v1Specifier;
+}
+
+export function ownedImportEquivalents(specifier: string): readonly string[] {
+  return resolveOwnedPackageImport(specifier).readEquivalents ?? [specifier];
+}
+
+function mapComponentId(value: string, mapPackage: (packageName: string) => string): string {
+  const separator = value.lastIndexOf("#");
+  if (separator <= 0 || separator === value.length - 1) return value;
+  const packageName = value.slice(0, separator);
+  const componentName = value.slice(separator + 1);
+  return `${mapPackage(packageName)}#${componentName}`;
+}
+
+export function canonicalizeOwnedComponentId(value: string): string {
+  return mapComponentId(value, canonicalizeOwnedImport);
+}
+
+/** fcid-preimage:v1 component-id compatibility; subject to the same restriction. */
+export function projectV1OwnedComponentId(value: string): string {
+  return mapComponentId(value, projectV1OwnedImportIdentity);
+}
+
+/** Exposed for diagnostics and generator tests, not as a second policy owner. */
+export const OWNED_PACKAGE_IDENTITY_EPOCH = OWNED_PACKAGE_AUTHORING_EPOCH;
+export { OWNED_PACKAGE_IDENTITY_SOURCE_SHA256 };

package/src/performance-presets.ts

@@ -0,0 +1,142 @@
+/**
+ * Performance budget presets and classification utilities.
+ *
+ * ESLint model: global defaults, zero-config, auto-measurement.
+ * Users configure 0-3 numbers. Per-component overrides are the `eslint-disable` equivalent.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PerformanceBudgets {
+  /** Maximum gzipped bundle size in bytes */
+  bundleSize: number;
+}
+
+export interface PerformanceConfig {
+  preset: string;
+  budgets: PerformanceBudgets;
+}
+
+export type ComplexityTier = 'lightweight' | 'moderate' | 'heavy';
+
+export interface PerformanceData {
+  /** Gzipped bundle size in bytes */
+  bundleSize: number;
+  /** Raw (minified, not gzipped) bundle size in bytes */
+  rawSize: number;
+  /** Complexity classification */
+  complexity: ComplexityTier;
+  /** Percentage of budget used (0-100+) */
+  budgetPercent: number;
+  /** Whether the component exceeds its budget */
+  overBudget: boolean;
+  /** ISO timestamp when measured */
+  measuredAt: string;
+}
+
+export interface PerformanceSummary {
+  /** Preset name used */
+  preset: string;
+  /** Budget applied in bytes */
+  budget: number;
+  /** Total components measured */
+  total: number;
+  /** Number of components over budget */
+  overBudget: number;
+  /** Distribution by tier */
+  tiers: Record<ComplexityTier, number>;
+}
+
+// ---------------------------------------------------------------------------
+// Presets
+// ---------------------------------------------------------------------------
+
+const PRESETS: Record<string, PerformanceBudgets> = {
+  strict: { bundleSize: 8 * 1024 },     // 8KB gzipped
+  standard: { bundleSize: 15 * 1024 },   // 15KB gzipped
+  relaxed: { bundleSize: 30 * 1024 },    // 30KB gzipped
+};
+
+export const PRESET_NAMES = Object.keys(PRESETS) as readonly string[];
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a performance config from user input.
+ * Accepts a preset name string or a custom config object.
+ */
+export function resolvePerformanceConfig(
+  input: string | { preset?: string; budgets?: Partial<PerformanceBudgets> } | undefined
+): PerformanceConfig {
+  if (!input) {
+    return { preset: 'standard', budgets: PRESETS.standard };
+  }
+
+  if (typeof input === 'string') {
+    const budgets = PRESETS[input];
+    if (!budgets) {
+      throw new Error(
+        `Unknown performance preset "${input}". Available: ${PRESET_NAMES.join(', ')}`
+      );
+    }
+    return { preset: input, budgets };
+  }
+
+  const presetName = input.preset ?? 'standard';
+  const baseBudgets = PRESETS[presetName];
+  if (!baseBudgets) {
+    throw new Error(
+      `Unknown performance preset "${presetName}". Available: ${PRESET_NAMES.join(', ')}`
+    );
+  }
+
+  return {
+    preset: presetName,
+    budgets: {
+      bundleSize: input.budgets?.bundleSize ?? baseBudgets.bundleSize,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a component's complexity based on gzipped bundle size.
+ *
+ * - lightweight: < 5KB — simple, leaf components
+ * - moderate: < 15KB — typical composed components
+ * - heavy: >= 15KB — complex widgets with dependencies
+ */
+export function classifyComplexity(gzipBytes: number): ComplexityTier {
+  if (gzipBytes < 5 * 1024) return 'lightweight';
+  if (gzipBytes < 15 * 1024) return 'moderate';
+  return 'heavy';
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Format bytes to a human-readable string (e.g. "2.1KB", "15.3KB").
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  const kb = bytes / 1024;
+  return kb < 10 ? `${kb.toFixed(1)}KB` : `${Math.round(kb)}KB`;
+}
+
+/**
+ * Create a visual budget bar for terminal output.
+ */
+export function budgetBar(percent: number, width = 20): string {
+  const filled = Math.min(Math.round((percent / 100) * width), width);
+  const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
+  return percent > 100 ? `\x1b[31m${bar}\x1b[0m` : `\x1b[32m${bar}\x1b[0m`;
+}

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

@@ -0,0 +1,228 @@
+import { describe, expect, it } from "vitest";
+import {
+  applyPreviewComparisonArtifactPayload,
+  buildPreviewComparisonArtifactPayload,
+  comparePreviewToDesign,
+  type PreviewArtifactManifest,
+} from "./index";
+
+describe("preview comparison artifact payloads", () => {
+  it("applies reusable evidence to a variant design reference", () => {
+    const manifest = buildManifest();
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Button / Primary",
+        imageDataUrl: "data:image/png;base64,figma",
+        size: { width: 120, height: 40 },
+      },
+      preview: {
+        kind: "preview",
+        label: "Button / Primary",
+        componentKey: "Button",
+        variantId: "primary",
+        theme: "light",
+        viewport: { width: 120, height: 40 },
+        imageDataUrl: "data:image/png;base64,preview",
+        size: { width: 120, height: 40 },
+      },
+      imageDiff: {
+        diffPercentage: 0.2,
+        diffImageDataUrl: "data:image/png;base64,diff",
+      },
+    });
+    const payload = buildPreviewComparisonArtifactPayload({ report });
+
+    const result = applyPreviewComparisonArtifactPayload(manifest, payload!);
+
+    expect(result.status).toBe("applied");
+    expect(result.applied).toBe(true);
+    expect(result.manifest).not.toBe(manifest);
+    expect(manifest.components.Button.variants[0]?.design).toBeUndefined();
+    expect(result.manifest.components.Button.design).toBeUndefined();
+    expect(result.manifest.components.Button.variants[0]?.design).toMatchObject({
+      label: "Button / Primary",
+      comparison: {
+        previewImageUrl: "data:image/png;base64,preview",
+        diffImageUrl: "data:image/png;base64,diff",
+        diffPercentage: 0.2,
+      },
+    });
+  });
+
+  it("applies component-scoped evidence to the component design reference", () => {
+    const manifest = buildManifest();
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Button / Default",
+        imageDataUrl: "data:image/png;base64,figma",
+        size: { width: 120, height: 40 },
+      },
+      preview: {
+        kind: "preview",
+        label: "Button / Default",
+        componentKey: "Button",
+        variantId: "primary",
+        theme: "light",
+        viewport: { width: 120, height: 40 },
+        imageDataUrl: "data:image/png;base64,preview",
+        size: { width: 120, height: 40 },
+      },
+      imageDiff: {
+        diffPercentage: 0.2,
+      },
+      context: {
+        scope: "component",
+        active: {
+          variantId: "primary",
+          theme: "light",
+          viewport: { width: 120, height: 40 },
+        },
+        stale: false,
+        staleReasons: [],
+      },
+    });
+    const payload = buildPreviewComparisonArtifactPayload({ report });
+
+    const result = applyPreviewComparisonArtifactPayload(manifest, payload!);
+
+    expect(result.status).toBe("applied");
+    expect(result.manifest.components.Button.design).toMatchObject({
+      label: "Button / Default",
+      comparison: {
+        diffPercentage: 0.2,
+      },
+    });
+    expect(result.manifest.components.Button.variants[0]?.design).toBeUndefined();
+  });
+
+  it("refuses to apply stale reports with no reusable evidence", () => {
+    const manifest = buildManifest();
+    const report = comparePreviewToDesign({
+      design: {
+        kind: "figma",
+        label: "Button",
+        size: { width: 120, height: 40 },
+      },
+      preview: {
+        kind: "preview",
+        label: "Button",
+        componentKey: "Button",
+        size: { width: 120, height: 40 },
+      },
+      context: {
+        scope: "component",
+        captured: { theme: "light" },
+        active: { theme: "dark" },
+        stale: true,
+        staleReasons: ["theme"],
+      },
+    });
+    const payload = buildPreviewComparisonArtifactPayload({ report });
+
+    const result = applyPreviewComparisonArtifactPayload(manifest, payload!);
+
+    expect(result).toMatchObject({
+      status: "missing-comparison-evidence",
+      applied: false,
+      manifest,
+    });
+  });
+
+  it("reports missing target components and variants without mutating the manifest", () => {
+    const manifest = buildManifest();
+    const report = comparePreviewToDesign({
+      design: { kind: "figma", label: "Missing", size: { width: 120, height: 40 } },
+      preview: {
+        kind: "preview",
+        label: "Missing",
+        componentKey: "Missing",
+        variantId: "primary",
+        size: { width: 120, height: 40 },
+      },
+      imageDiff: { diffPercentage: 0.2 },
+    });
+    const payload = buildPreviewComparisonArtifactPayload({ report });
+
+    expect(applyPreviewComparisonArtifactPayload(manifest, payload!)).toMatchObject({
+      status: "component-not-found",
+      applied: false,
+      manifest,
+    });
+
+    expect(
+      applyPreviewComparisonArtifactPayload(manifest, {
+        ...payload!,
+        target: { ...payload!.target, componentKey: "Button", variantId: "missing" },
+      })
+    ).toMatchObject({
+      status: "variant-not-found",
+      applied: false,
+      manifest,
+    });
+  });
+});
+
+function buildManifest(): PreviewArtifactManifest {
+  return {
+    artifactVersion: "preview-artifact/v1",
+    identity: {
+      artifactId: "artifact",
+      artifactVersion: "preview-artifact/v1",
+      orgId: "org",
+      projectId: "project",
+      bindingId: "binding",
+      repoFullName: "acme/ui",
+      commitSha: "abc123",
+      sourceRef: "main",
+      createdAt: "2026-05-24T00:00:00.000Z",
+    },
+    builder: {
+      name: "test",
+      version: "1.0.0",
+      typecheck: "none",
+      sources: ["manual"],
+      adapters: [],
+    },
+    runtime: {
+      framework: "react",
+      moduleFormat: "esm",
+      entry: "index.js",
+      css: [],
+      assetsBaseUrl: "/preview/",
+    },
+    capabilities: {
+      supportsThemes: true,
+      supportsViewports: true,
+      supportsActions: false,
+      supportsSlots: false,
+      supportsA11yScan: false,
+      supportsPlayFunctions: false,
+      supportsSceneNodes: false,
+    },
+    components: {
+      Button: {
+        componentKey: "Button",
+        publicRef: "Button",
+        displayName: "Button",
+        exportName: "Button",
+        importPath: "./button",
+        tier: "primitive",
+        previewability: "ready",
+        definitionSource: "manual",
+        diagnostics: [],
+        props: {},
+        variants: [
+          {
+            id: "primary",
+            name: "Primary",
+            source: "manual",
+            props: {},
+          },
+        ],
+      },
+    },
+    diagnostics: [],
+  };
+}

package/src/preview/comparison-artifact.ts

@@ -0,0 +1,181 @@
+import type {
+  PreviewArtifactManifest,
+  PreviewDesignComparisonReference,
+  PreviewDesignReference,
+} from "./types";
+import {
+  buildPreviewDesignComparisonEvidence,
+  buildPreviewDesignReferenceFromReport,
+  type PreviewComparisonReferenceScope,
+  type PreviewComparisonReport,
+} from "./comparison";
+
+export interface PreviewComparisonArtifactAssetPaths {
+  rendered?: string;
+  figma?: string;
+  diff?: string;
+}
+
+export interface PreviewComparisonArtifactTarget {
+  componentKey: string;
+  variantId?: string;
+  designReferenceScope: PreviewComparisonReferenceScope;
+}
+
+export interface BuildPreviewComparisonArtifactPayloadInput {
+  report?: PreviewComparisonReport;
+  designReference?: PreviewDesignReference;
+  comparisonEvidence?: PreviewDesignComparisonReference;
+  assets?: PreviewComparisonArtifactAssetPaths;
+}
+
+export interface PreviewComparisonArtifactPayload {
+  target: PreviewComparisonArtifactTarget;
+  report: PreviewComparisonReport;
+  designReference: PreviewDesignReference;
+  comparisonEvidence?: PreviewDesignComparisonReference;
+}
+
+export type ApplyPreviewComparisonArtifactStatus =
+  | "applied"
+  | "component-not-found"
+  | "variant-not-found"
+  | "missing-comparison-evidence";
+
+export interface ApplyPreviewComparisonArtifactPayloadResult {
+  status: ApplyPreviewComparisonArtifactStatus;
+  applied: boolean;
+  manifest: PreviewArtifactManifest;
+  message: string;
+}
+
+export function buildPreviewComparisonArtifactPayload(
+  input: BuildPreviewComparisonArtifactPayloadInput
+): PreviewComparisonArtifactPayload | null {
+  if (!input.report) return null;
+
+  const report = input.report;
+  const designReference: PreviewDesignReference = {
+    ...(input.designReference ?? buildPreviewDesignReferenceFromReport(report)),
+  };
+  const reportEvidence = buildPreviewDesignComparisonEvidence(report);
+  const comparisonEvidence: PreviewDesignComparisonReference | undefined = report.context?.stale
+    ? undefined
+    : input.comparisonEvidence
+      ? { ...input.comparisonEvidence }
+      : designReference.comparison
+        ? { ...designReference.comparison }
+        : reportEvidence
+          ? { ...reportEvidence }
+          : undefined;
+
+  if (report.context?.stale) {
+    delete designReference.comparison;
+  }
+  if (input.assets?.figma) {
+    designReference.imageUrl = input.assets.figma;
+  }
+  if (comparisonEvidence && input.assets?.rendered) {
+    comparisonEvidence.previewImageUrl = input.assets.rendered;
+  }
+  if (comparisonEvidence && input.assets?.diff) {
+    comparisonEvidence.diffImageUrl = input.assets.diff;
+  }
+  if (comparisonEvidence) {
+    designReference.comparison = comparisonEvidence;
+  }
+
+  return {
+    target: buildComparisonArtifactTarget(report),
+    report,
+    designReference,
+    ...(comparisonEvidence && { comparisonEvidence }),
+  };
+}
+
+export function applyPreviewComparisonArtifactPayload(
+  manifest: PreviewArtifactManifest,
+  payload: PreviewComparisonArtifactPayload
+): ApplyPreviewComparisonArtifactPayloadResult {
+  if (!payload.comparisonEvidence) {
+    return {
+      status: "missing-comparison-evidence",
+      applied: false,
+      manifest,
+      message: "Comparison payload has no reusable evidence to apply.",
+    };
+  }
+
+  const component = manifest.components[payload.target.componentKey];
+  if (!component) {
+    return {
+      status: "component-not-found",
+      applied: false,
+      manifest,
+      message: `Component ${payload.target.componentKey} was not found in the manifest.`,
+    };
+  }
+
+  if (payload.target.designReferenceScope === "variant") {
+    const variantIndex = component.variants.findIndex(
+      (variant) => variant.id === payload.target.variantId
+    );
+    if (variantIndex < 0) {
+      return {
+        status: "variant-not-found",
+        applied: false,
+        manifest,
+        message: `Variant ${payload.target.variantId ?? "(missing)"} was not found on component ${
+          payload.target.componentKey
+        }.`,
+      };
+    }
+
+    const variants = component.variants.map((variant, index) =>
+      index === variantIndex ? { ...variant, design: payload.designReference } : variant
+    );
+
+    return {
+      status: "applied",
+      applied: true,
+      manifest: {
+        ...manifest,
+        components: {
+          ...manifest.components,
+          [payload.target.componentKey]: {
+            ...component,
+            variants,
+          },
+        },
+      },
+      message: `Applied comparison evidence to ${payload.target.componentKey} variant ${payload.target.variantId}.`,
+    };
+  }
+
+  return {
+    status: "applied",
+    applied: true,
+    manifest: {
+      ...manifest,
+      components: {
+        ...manifest.components,
+        [payload.target.componentKey]: {
+          ...component,
+          design: payload.designReference,
+        },
+      },
+    },
+    message: `Applied comparison evidence to ${payload.target.componentKey}.`,
+  };
+}
+
+function buildComparisonArtifactTarget(
+  report: PreviewComparisonReport
+): PreviewComparisonArtifactTarget {
+  return {
+    componentKey: report.preview.componentKey,
+    ...(report.preview.variantId && { variantId: report.preview.variantId }),
+    designReferenceScope:
+      report.context?.scope ?? (report.preview.variantId ? "variant" : "component"),
+  };
+}