@usefragments/core 1.0.0

package/src/types.ts

@@ -0,0 +1,1057 @@
+import type { ComponentType, ReactNode, JSX } from "react";
+import type { GovernanceConfig } from "./governance.js";
+import type { InspectConfig } from "./local-canonical.js";
+import type { Topology } from "./topology/resolve-area.js";
+
+/**
+ * A React component that can be used in a fragment definition.
+ * This type is intentionally broad to support various React component patterns
+ * including FC, forwardRef, memo, and class components across different React versions.
+ */
+
+export type FragmentComponent<TProps = any> =
+  | ComponentType<TProps>
+  | ((props: TProps) => ReactNode | JSX.Element | null);
+
+/**
+ * Framework-agnostic component reference.
+ * Used in contexts where React is not required (e.g., JSON component contracts).
+ * Accepts a string identifier, a generic function, or a record of metadata.
+ */
+export type ComponentRef = string | ((...args: unknown[]) => unknown) | Record<string, unknown>;
+
+/**
+ * Metadata about the component
+ */
+export interface FragmentMeta {
+  /** Component display name */
+  name: string;
+
+  /** Brief description of the component's purpose */
+  description: string;
+
+  /** Category for organizing components (e.g., "actions", "forms", "layout") */
+  category: string;
+
+  /** Optional tags for additional categorization */
+  tags?: string[];
+
+  /** Component status */
+  status?: "stable" | "beta" | "deprecated" | "experimental";
+
+  /** Version when component was introduced */
+  since?: string;
+
+  /** External npm packages required by this component (displayed in docs Setup section) */
+  dependencies?: Array<{
+    name: string;
+    version: string;
+    reason?: string;
+  }>;
+
+  /** Figma frame URL for design verification */
+  figma?: string;
+
+  /** Figma property mappings (how Figma props map to code props) */
+  figmaProps?: Record<string, FigmaPropMapping>;
+}
+
+/**
+ * Figma property mapping types - describes how a Figma property maps to code
+ */
+export type FigmaPropMapping =
+  | FigmaStringMapping
+  | FigmaBooleanMapping
+  | FigmaEnumMapping
+  | FigmaInstanceMapping
+  | FigmaChildrenMapping
+  | FigmaTextContentMapping;
+
+/** Maps a Figma text property to a string prop */
+export interface FigmaStringMapping {
+  __type: "figma-string";
+  figmaProperty: string;
+}
+
+/** Maps a Figma boolean property to a boolean prop (with optional value mapping) */
+export interface FigmaBooleanMapping {
+  __type: "figma-boolean";
+  figmaProperty: string;
+  valueMapping?: { true: unknown; false: unknown };
+}
+
+/** Maps a Figma variant property to an enum prop */
+export interface FigmaEnumMapping {
+  __type: "figma-enum";
+  figmaProperty: string;
+  valueMapping: Record<string, unknown>;
+}
+
+/** References a nested Figma component instance */
+export interface FigmaInstanceMapping {
+  __type: "figma-instance";
+  figmaProperty: string;
+}
+
+/** Renders children from Figma layer names */
+export interface FigmaChildrenMapping {
+  __type: "figma-children";
+  layers: string[];
+}
+
+/** Extracts text content from a Figma text layer */
+export interface FigmaTextContentMapping {
+  __type: "figma-text-content";
+  layer: string;
+}
+
+/**
+ * Usage guidelines for AI agents and developers
+ */
+export interface FragmentUsage {
+  /** When to use this component */
+  when: string[];
+
+  /** When NOT to use this component (with alternatives) */
+  whenNot: string[];
+
+  /** Additional usage guidelines and best practices */
+  guidelines?: string[];
+
+  /** Accessibility considerations */
+  accessibility?: string[];
+}
+
+/**
+ * Prop type definitions
+ */
+export type PropType =
+  | { type: "string"; pattern?: string }
+  | { type: "number"; min?: number; max?: number }
+  | { type: "boolean" }
+  | { type: "enum"; values: readonly string[] }
+  | { type: "function"; signature?: string }
+  | { type: "node" }
+  | { type: "element" }
+  | { type: "object"; shape?: Record<string, PropDefinition> }
+  | { type: "array"; items?: PropType }
+  | { type: "union"; types: PropType[] }
+  | { type: "custom"; typescript: string };
+
+/**
+ * Storybook control types for UI rendering
+ */
+export type ControlType =
+  | "text"
+  | "number"
+  | "range"
+  | "boolean"
+  | "select"
+  | "multi-select"
+  | "radio"
+  | "inline-radio"
+  | "check"
+  | "inline-check"
+  | "object"
+  | "file"
+  | "color"
+  | "date";
+
+/**
+ * Definition for a single prop
+ */
+export interface PropDefinition {
+  /** The prop type */
+  type: PropType["type"];
+
+  /** For enum types, the allowed values */
+  values?: readonly string[];
+
+  /** Default value if not provided */
+  default?: unknown;
+
+  /** Description of what this prop does */
+  description: string;
+
+  /** Whether this prop is required */
+  required?: boolean;
+
+  /** Usage constraints for AI agents */
+  constraints?: string[];
+
+  /** Additional type details for complex types */
+  typeDetails?: Omit<PropType, "type">;
+
+  /** Original Storybook control type for UI rendering (e.g., "color", "date", "range") */
+  controlType?: ControlType;
+
+  /** Control options (e.g., min/max for range, presetColors for color) */
+  controlOptions?: {
+    min?: number;
+    max?: number;
+    step?: number;
+    presetColors?: string[];
+  };
+}
+
+/**
+ * Relationship types between components
+ */
+export type RelationshipType =
+  | "alternative" // Use instead of this component in certain cases
+  | "sibling" // Related component at same level
+  | "parent" // This component should be wrapped by
+  | "child" // This component should contain
+  | "composition" // Used together as compound component
+  | "complementary" // Enhances or works alongside this component
+  | "used-by"; // This component is consumed by another
+
+/**
+ * Relationship to another component
+ */
+export interface ComponentRelation {
+  /** Name of the related component */
+  component: string;
+
+  /** Type of relationship */
+  relationship: RelationshipType;
+
+  /** Explanation of the relationship */
+  note: string;
+}
+
+/**
+ * Loader function type for async data loading before render
+ */
+export type VariantLoader = () => Promise<Record<string, unknown>>;
+
+/**
+ * Play function context passed during interaction testing
+ */
+export interface PlayFunctionContext {
+  /** The rendered canvas element containing the story */
+  canvasElement: HTMLElement;
+  /** Args passed to the story */
+  args: Record<string, unknown>;
+  /** Step function for organizing interactions */
+  step: (name: string, fn: () => Promise<void>) => Promise<void>;
+}
+
+/**
+ * Play function type for interaction testing
+ */
+export type PlayFunction = (context: PlayFunctionContext) => Promise<void>;
+
+/**
+ * Options passed to variant render function
+ */
+export interface VariantRenderOptions {
+  /** Props/args to override the variant defaults */
+  args?: Record<string, unknown>;
+  /** Data loaded from async loaders */
+  loadedData?: Record<string, unknown>;
+}
+
+/**
+ * A single variant/example of the component
+ */
+export interface FragmentVariant {
+  /** Variant name */
+  name: string;
+
+  /** Description of when to use this variant */
+  description: string;
+
+  /** Render function that returns the component example
+   * @param options - Optional args overrides and loaded data
+   */
+  render: (options?: VariantRenderOptions) => ReactNode;
+
+  /** Optional code string for display (auto-generated if not provided) */
+  code?: string;
+
+  /** Figma frame URL for this specific variant (overrides meta.figma) */
+  figma?: string;
+
+  /** Whether this variant has a Storybook play function (for display purposes) */
+  hasPlayFunction?: boolean;
+
+  /** The actual play function for interaction testing */
+  play?: PlayFunction;
+
+  /** Storybook story ID for this variant (generated by @storybook/csf toId) */
+  storyId?: string;
+
+  /** Optional tags for this variant (inherited from story tags) */
+  tags?: string[];
+
+  /** Async loaders to execute before rendering (from Storybook loaders) */
+  loaders?: VariantLoader[];
+
+  /** The args/props used to render this variant (for code generation) */
+  args?: Record<string, unknown>;
+}
+
+/**
+ * Agent-optimized contract metadata
+ * Provides compact, structured data for AI code generation
+ */
+export interface FragmentContract {
+  /** Short prop descriptions for agents (e.g., "variant: primary|secondary (required)") */
+  propsSummary?: string[];
+
+  /** Accessibility rule IDs for lookup in glossary (e.g., "A11Y_BTN_LABEL") */
+  a11yRules?: string[];
+
+  /** Banned patterns in codebase - triggers warnings during code review */
+  bans?: Array<{
+    /** Pattern to match (regex string or literal) */
+    pattern: string;
+    /** Message explaining why this pattern is banned and what to use instead */
+    message: string;
+  }>;
+
+  /** Scenario tags for use-case matching (e.g., "form.submit", "navigation.primary") */
+  scenarioTags?: string[];
+
+  /** Per-component performance budget override in bytes (gzipped). Overrides global budget. */
+  performanceBudget?: number;
+
+  /** Sub-component slot metadata for compound components (e.g., Card.Header, Dialog.Body) */
+  compoundChildren?: Record<
+    string,
+    {
+      required?: boolean;
+      accepts?: string[];
+      description?: string;
+    }
+  >;
+
+  /** Canonical JSX usage examples showing how to assemble the component */
+  canonicalUsage?: string[];
+}
+
+/**
+ * Provenance tracking for generated fragments
+ * Helps distinguish human-authored from machine-generated content
+ */
+export interface FragmentGenerated {
+  /** Source of this fragment definition */
+  source: "storybook" | "manual" | "ai" | "extracted" | "merged" | "migrated";
+
+  /** Original source file (e.g., "Button.stories.tsx") */
+  sourceFile?: string;
+
+  /** @deprecated Use provenance.verified instead — kept for backwards compatibility */
+  confidence?: number;
+
+  /** Whether the fragment has been verified against source */
+  verified?: boolean;
+
+  /** ISO timestamp when this was generated */
+  timestamp?: string;
+}
+
+/**
+ * AI-specific metadata for playground context generation
+ * Provides hints for AI code generation about component composition
+ */
+export interface AIMetadata {
+  /** How this component is composed with others */
+  compositionPattern?: "compound" | "simple" | "controlled" | "wrapper";
+
+  /** Sub-component names (without parent prefix, e.g., "Header" not "Card.Header") */
+  subComponents?: string[];
+
+  /** Sub-components that must be present for valid composition */
+  requiredChildren?: string[];
+
+  /** Common usage patterns as JSX strings for AI reference */
+  commonPatterns?: string[];
+}
+
+/**
+ * Complete fragment definition
+ */
+export interface FragmentDefinition<TProps = unknown> {
+  /** The component being documented */
+  component: FragmentComponent<TProps>;
+
+  /** Component metadata */
+  meta: FragmentMeta;
+
+  /** Usage guidelines */
+  usage: FragmentUsage;
+
+  /** Props documentation */
+  props: Record<string, PropDefinition>;
+
+  /** Relationships to other components */
+  relations?: ComponentRelation[];
+
+  /** Component variants/examples */
+  variants: FragmentVariant[];
+
+  /** Agent-optimized contract metadata */
+  contract?: FragmentContract;
+
+  /** AI-specific metadata for playground context generation */
+  ai?: AIMetadata;
+
+  /** Provenance tracking (for generated fragments) */
+  _generated?: FragmentGenerated;
+}
+
+// ---------------------------------------------------------------------------
+// v2 API — Clearer naming, alongside v1 (non-breaking)
+// ---------------------------------------------------------------------------
+
+/**
+ * Usage guidelines for AI agents and developers.
+ * v2 alias for FragmentUsage — clearer naming.
+ * @since 2.0
+ */
+export type FragmentGuidance = FragmentUsage;
+
+/**
+ * A single example of the component.
+ * v2 alias for FragmentVariant — research shows "examples" is clearer for AI consumption.
+ * @since 2.0
+ */
+export type FragmentExample = FragmentVariant;
+
+/**
+ * Composition metadata — promoted from ai.compositionPattern to first-class field.
+ * Uses shorter field names since the parent field is already `composition`.
+ * @since 2.0
+ */
+export interface CompositionMetadata {
+  /** How this component is composed with others */
+  pattern?: "compound" | "simple" | "controlled" | "wrapper";
+
+  /** Sub-component names (without parent prefix, e.g., "Header" not "Card.Header") */
+  subComponents?: string[];
+
+  /** Sub-components that must be present for valid composition */
+  requiredChildren?: string[];
+
+  /** Common usage patterns as JSX strings for AI reference */
+  commonPatterns?: string[];
+}
+
+/**
+ * Extended provenance tracking for generated fragments.
+ * Superset of FragmentGenerated with field-level attribution.
+ * @since 2.0
+ */
+export interface FragmentProvenance {
+  /** Source of this fragment definition */
+  source: "storybook" | "manual" | "ai" | "scan" | "extracted" | "merged" | "migrated";
+
+  /** Original source file (e.g., "Button.stories.tsx") */
+  sourceFile?: string;
+
+  /** @deprecated Use verified instead */
+  confidence?: number;
+
+  /** Whether the fragment has been verified against source */
+  verified: boolean;
+
+  /** Framework support level */
+  frameworkSupport?: "native" | "manual-only";
+
+  /** SHA hash of the source file at extraction time */
+  sourceHash?: string;
+
+  /** ISO timestamp when this was generated */
+  timestamp?: string;
+
+  /** Fields that were auto-extracted (e.g., ['props', 'composition']) */
+  autoFields?: string[];
+
+  /** Fields that were human-authored (e.g., ['guidance', 'examples']) */
+  humanFields?: string[];
+}
+
+/**
+ * v2 fragment definition with clearer field names.
+ *
+ * Changes from v1 FragmentDefinition:
+ * - `usage` → `guidance` (clearer intent)
+ * - `variants` → `examples` (research-backed: examples > parameter lists)
+ * - `ai` → `composition` (promoted to first-class, shorter field names)
+ * - `_generated` → `_provenance` (extended with autoFields/humanFields)
+ * - `contract` remains but is auto-compiled at build time
+ *
+ * @since 2.0
+ */
+export interface FragmentDefinitionV2<TProps = unknown> {
+  /** The component being documented */
+  component: FragmentComponent<TProps>;
+
+  /** Component metadata */
+  meta: FragmentMeta;
+
+  /** Usage guidelines (v2 name for 'usage') */
+  guidance: FragmentGuidance;
+
+  /** Props documentation */
+  props: Record<string, PropDefinition>;
+
+  /** Relationships to other components */
+  relations?: ComponentRelation[];
+
+  /** Component examples (v2 name for 'variants') */
+  examples: FragmentExample[];
+
+  /** Composition metadata (v2 name for 'ai', promoted to first-class) */
+  composition?: CompositionMetadata;
+
+  /** Agent-optimized contract — auto-compiled at build time */
+  contract?: FragmentContract;
+
+  /** Provenance tracking (v2 name for '_generated', extended) */
+  _provenance?: FragmentProvenance;
+}
+
+/**
+ * Registry generation options
+ */
+export interface RegistryOptions {
+  /** Only include components that have a corresponding .stories.tsx file */
+  requireStory?: boolean;
+
+  /** Only include components that are exported (public API) */
+  publicOnly?: boolean;
+
+  /** Maximum depth for category inference from directory structure (default: 1) */
+  categoryDepth?: number;
+
+  /** Include props in registry (default: false - AI can read TypeScript directly) */
+  includeProps?: boolean;
+
+  /** Include full fragment data in registry (default: false - reference fragmentPath instead) */
+  embedFragments?: boolean;
+}
+
+/**
+ * Design token configuration
+ */
+export type RepoRelativePath = string;
+
+export interface AppConfig {
+  /** Repo-root-relative app/source directory to scan. Defaults to ".". */
+  path?: RepoRelativePath;
+
+  /** Optional source globs relative to app.path. */
+  include?: string[];
+
+  /** Optional source exclusions relative to app.path. */
+  exclude?: string[];
+}
+
+export interface DesignSystemConfig {
+  /** Repo-root-relative directory that owns the canonical primitives. */
+  path?: RepoRelativePath;
+
+  /** Package name for primitive imports. Inferred from path/package.json when omitted. */
+  packageName?: string;
+
+  /** Component source globs relative to designSystem.path. */
+  components?: string[];
+}
+
+export type TokenSourceFormat = "auto" | "css" | "scss" | "dtcg" | "tailwind";
+
+export interface TokenSourceConfig {
+  /** Repo-root-relative token file or glob. */
+  path: RepoRelativePath;
+
+  /** Explicit token format, or "auto" to infer from extension/content. */
+  format?: TokenSourceFormat;
+}
+
+export interface TokenConfig {
+  /**
+   * Glob patterns for files to scan for tokens
+   * e.g., ["src/styles/theme.scss", "src/styles/variables.css"]
+   */
+  include?: string[];
+
+  /** Repo-root-relative token source files/globs for monorepos and Cloud setup. */
+  sources?: TokenSourceConfig[];
+
+  /**
+   * Glob patterns to exclude
+   * @example ["node_modules"]
+   */
+  exclude?: string[];
+
+  /**
+   * Map CSS selectors to theme names
+   * @example { ":root": "default", "[data-theme='dark']": "dark" }
+   */
+  themeSelectors?: Record<string, string>;
+
+  /** Enable token comparison in style diffs (default: true) */
+  enabled?: boolean;
+
+  /** Token source format detection ('auto' detects from file extension) */
+  format?: TokenSourceFormat;
+
+  /** Vendor namespace for Fragments extensions in DTCG files (default: 'com.usefragments') */
+  namespace?: string;
+}
+
+/**
+ * CI configuration for automated compliance checks
+ */
+export interface CIConfig {
+  /** Minimum compliance percentage to pass (default: 80) */
+  minCompliance?: number;
+
+  /** Whether to fail on any visual regression */
+  failOnDiff?: boolean;
+
+  /** Whether to output JSON format */
+  jsonOutput?: boolean;
+}
+
+/**
+ * Snippet policy configuration.
+ * Controls snippet/render quality enforcement in `fragments validate`.
+ */
+export interface SnippetPolicyConfig {
+  /** Validation mode: warn (non-blocking) or error (blocking). Default: warn */
+  mode?: "warn" | "error";
+
+  /** Validate snippet strings only, or snippet strings + render functions. Default: snippet+render */
+  scope?: "snippet" | "snippet+render";
+
+  /** Require authored snippets to be full, copy-pasteable examples with imports. Default: true */
+  requireFullSnippet?: boolean;
+
+  /** Allow these external modules for JSX components in snippets/renders. */
+  allowedExternalModules?: string[];
+}
+
+/**
+ * Storybook adapter filtering configuration.
+ * Controls which Storybook stories are included when generating fragments.
+ */
+export interface StorybookFilterConfig {
+  /** Glob-style patterns for component names to explicitly exclude */
+  exclude?: string[];
+  /** Glob-style patterns for component names to force-include (bypasses all heuristic filters) */
+  include?: string[];
+  /** Exclude stories with "Deprecated" in the title (default: true) */
+  excludeDeprecated?: boolean;
+  /** Exclude test stories (title ending /test(s) or *.test.stories.* files) (default: true) */
+  excludeTests?: boolean;
+  /** Exclude SVG icon components (names matching Svg[A-Z]*) (default: true) */
+  excludeSvgIcons?: boolean;
+  /** Exclude sub-components detected by directory structure (default: true) */
+  excludeSubComponents?: boolean;
+}
+
+/**
+ * Theme seed configuration.
+ * The 5 root values that derive 120+ CSS custom properties.
+ */
+export interface ThemeSeeds {
+  /** Primary brand color as hex (e.g., "#6366f1") */
+  brand?: string;
+
+  /** Neutral palette name */
+  neutral?: "stone" | "ice" | "earth" | "sand" | "fire" | "fragments";
+
+  /** Spacing density scale */
+  density?: "compact" | "default" | "relaxed";
+
+  /** Border radius style */
+  radiusStyle?: "sharp" | "subtle" | "default" | "rounded" | "pill";
+
+  /** Danger/error color as hex (e.g., "#ef4444") */
+  danger?: string;
+}
+
+/**
+ * Visual snapshot testing configuration.
+ */
+export interface SnapshotConfig {
+  /** Enable visual snapshot tests (default: false) */
+  enabled: boolean;
+
+  /** Output directory for snapshot baselines (relative to project root) */
+  outputDir?: string;
+
+  /** Viewport width for snapshots (default: 1440) */
+  viewportWidth?: number;
+
+  /** Viewport height for snapshots (default: 1100) */
+  viewportHeight?: number;
+
+  /** Diff threshold percentage before a snapshot fails (default: 0.1) */
+  threshold?: number;
+
+  /** Disable CSS animations during capture (default: true) */
+  disableAnimations?: boolean;
+}
+
+/**
+ * Config file structure
+ */
+export interface FragmentsConfig {
+  /** App/source scan scope. Paths are repo-root-relative. */
+  app?: AppConfig;
+
+  /** Canonical primitive component source. Paths are repo-root-relative. */
+  designSystem?: DesignSystemConfig;
+
+  /** Glob patterns for finding fragment/fragment files */
+  include?: string[];
+
+  /** Glob patterns to exclude */
+  exclude?: string[];
+
+  /** Glob patterns for finding component files (for coverage validation) */
+  components?: string[];
+
+  /** Output path for compiled output */
+  outFile?: string;
+
+  /** Framework adapter to use */
+  framework?: "react" | "vue" | "svelte";
+
+  /** Figma file URL for the design system (used by `fragments link`) */
+  figmaFile?: string;
+
+  /** Figma access token (alternative to FIGMA_ACCESS_TOKEN env var) */
+  figmaToken?: string;
+
+  /** Screenshot configuration */
+  screenshots?: ScreenshotConfig;
+
+  /** Service configuration */
+  service?: ServiceConfig;
+
+  /** Registry generation options */
+  registry?: RegistryOptions;
+
+  /** Design token discovery and mapping configuration */
+  tokens?: TokenConfig;
+
+  /** CI pipeline configuration */
+  ci?: CIConfig;
+
+  /** Snippet/render policy validation */
+  snippets?: SnippetPolicyConfig;
+
+  /** Performance budgets: preset name or custom config */
+  performance?: string | { preset?: string; budgets?: { bundleSize?: number } };
+
+  /** Storybook adapter filtering configuration */
+  storybook?: StorybookFilterConfig;
+
+  /** Theme seed values for the 5-seed theming system */
+  theme?: ThemeSeeds;
+
+  /**
+   * Product-area topology — maps file paths to areas (checkout, dashboard, …)
+   * for area-scoped governance. Resolved at scan time; areas are tagged onto
+   * findings and coverage. See `apps/cloud/docs/topology/`.
+   */
+  topology?: Topology;
+
+  /** Visual snapshot testing configuration */
+  snapshots?: SnapshotConfig;
+
+  /** Preview configuration for component rendering */
+  preview?: {
+    /** Module that runs before any render (global CSS, MSW, mocks) */
+    setupModule?: string;
+    /** Module path for the render wrapper component (ThemeProvider, etc.) */
+    wrapperModule?: string;
+    /** Named export from wrapperModule (e.g., 'ThemeProvider') */
+    wrapperExport?: string;
+    /** Additional CSS files to inject */
+    css?: string[];
+    /** Default theme for previews */
+    theme?: "light" | "dark";
+  };
+
+  /** Governance policy configuration (replaces standalone govern.config.ts) */
+  govern?: GovernanceConfig;
+
+  /** Local Inspect-only configuration. */
+  inspect?: InspectConfig;
+
+  /**
+   * Identifier names recognized as className-helper callees during Tailwind
+   * extraction (e.g. `clsx`, `cn`). Supplying this list **replaces** the
+   * default `['clsx', 'cn', 'classnames', 'twMerge', 'tw', 'cva']` — it does
+   * not merge.
+   */
+  recognizedClassHelpers?: string[];
+}
+
+/**
+ * Screenshot capture configuration
+ */
+export interface ScreenshotConfig {
+  /** Default viewport for captures */
+  viewport?: Viewport;
+
+  /** Diff threshold percentage (0-100) */
+  threshold?: number;
+
+  /** Additional delay after render before capture (ms) */
+  delay?: number;
+
+  /** Output directory for baselines (relative to project root) */
+  outputDir?: string;
+
+  /** Themes to capture */
+  themes?: Theme[];
+}
+
+/**
+ * Service configuration
+ */
+export interface ServiceConfig {
+  /** Browser pool size */
+  poolSize?: number;
+
+  /** Idle timeout before shutdown (ms) */
+  idleTimeout?: number;
+}
+
+/**
+ * Viewport dimensions
+ */
+export interface Viewport {
+  width: number;
+  height: number;
+  deviceScaleFactor?: number;
+}
+
+/**
+ * Theme identifier
+ */
+export type Theme = "light" | "dark";
+
+/**
+ * Screenshot metadata
+ */
+export interface Screenshot {
+  /** PNG image data */
+  data: Buffer;
+
+  /** SHA-256 hash of image data (for change detection) */
+  hash: string;
+
+  /** Viewport used for capture */
+  viewport: Viewport;
+
+  /** When this screenshot was taken */
+  capturedAt: Date;
+
+  /** Capture metadata */
+  metadata: ScreenshotMetadata;
+}
+
+/**
+ * Screenshot metadata
+ */
+export interface ScreenshotMetadata {
+  /** Component name */
+  component: string;
+
+  /** Variant name */
+  variant: string;
+
+  /** Theme used */
+  theme: Theme;
+
+  /** Time to render the component (ms) */
+  renderTimeMs: number;
+
+  /** Time to capture the screenshot (ms) */
+  captureTimeMs: number;
+}
+
+/**
+ * Result of comparing two screenshots
+ */
+export interface DiffResult {
+  /** Whether images are considered matching (below threshold) */
+  matches: boolean;
+
+  /** Percentage of pixels that differ (0-100) */
+  diffPercentage: number;
+
+  /** Number of differing pixels */
+  diffPixelCount: number;
+
+  /** Total pixels compared */
+  totalPixels: number;
+
+  /** PNG image highlighting differences */
+  diffImage?: Buffer;
+
+  /** Bounding boxes of changed regions */
+  changedRegions: BoundingBox[];
+
+  /** Time taken to compute diff (ms) */
+  diffTimeMs: number;
+}
+
+/**
+ * Bounding box for changed region
+ */
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Baseline information stored in manifest
+ */
+export interface BaselineInfo {
+  /** Component name */
+  component: string;
+
+  /** Variant name */
+  variant: string;
+
+  /** Theme */
+  theme: Theme;
+
+  /** Relative path to image file */
+  path: string;
+
+  /** SHA-256 hash */
+  hash: string;
+
+  /** Viewport used */
+  viewport: Viewport;
+
+  /** When captured */
+  capturedAt: string;
+
+  /** File size in bytes */
+  fileSize: number;
+}
+
+/**
+ * Manifest file structure
+ */
+export interface Manifest {
+  /** Schema version */
+  version: "1.0.0";
+
+  /** When manifest was generated */
+  generatedAt: string;
+
+  /** Configuration used for capture */
+  config: {
+    defaultViewport: Viewport;
+    defaultThreshold: number;
+    captureDelay: number;
+  };
+
+  /** All baselines indexed by component/variant */
+  baselines: Record<string, Record<string, BaselineInfo>>;
+}
+
+/**
+ * Verification request from AI agents
+ */
+export interface VerifyRequest {
+  /** Component name */
+  component: string;
+
+  /** Variant name */
+  variant: string;
+
+  /** Theme to verify against */
+  theme?: Theme;
+
+  /** Override diff threshold */
+  threshold?: number;
+}
+
+/**
+ * Verification result
+ */
+export interface VerifyResult {
+  /** Overall verdict */
+  verdict: "pass" | "fail" | "error";
+
+  /** Whether diff is below threshold */
+  matches: boolean;
+
+  /** Percentage of pixels that differ */
+  diffPercentage: number;
+
+  /** Current screenshot (base64 PNG) */
+  screenshot: string;
+
+  /** Baseline screenshot (base64 PNG) */
+  baseline: string;
+
+  /** Diff image if different (base64 PNG) */
+  diffImage?: string;
+
+  /** Human-readable notes */
+  notes: string[];
+
+  /** Error message if verdict is "error" */
+  error?: string;
+
+  /** Performance metrics */
+  timing: {
+    renderMs: number;
+    captureMs: number;
+    diffMs: number;
+    totalMs: number;
+  };
+}
+
+// Compiled types — re-exported from ./compiled-types.
+export type {
+  CompiledFragment,
+  CompiledBlock,
+  CompiledTokenEntry,
+  CompiledTokenData,
+  ObservedComponentUsage,
+  ObservedUsageProp,
+  CompiledFragmentsFile,
+} from "./compiled-types/index.js";
+
+import type { CompiledBlock as _CompiledBlock } from "./compiled-types/index.js";
+
+/**
+ * Block definition — a named composition pattern showing how
+ * design system components wire together for a common use case.
+ */
+export interface BlockDefinition {
+  name: string;
+  description: string;
+  category: string;
+  components: string[];
+  code: string;
+  tags?: string[];
+}
+
+/**
+ * @deprecated Use BlockDefinition instead
+ */
+export type RecipeDefinition = BlockDefinition;
+
+/**
+ * @deprecated Use CompiledBlock instead
+ */
+export type CompiledRecipe = _CompiledBlock;