@fragments-sdk/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2873 @@
+import { ComponentType, ReactNode, JSX } from 'react';
+import { CompiledBlock, CompiledFragment } from '@fragments-sdk/context/types';
+export { CompiledBlock, CompiledFragment, CompiledFragmentsFile, CompiledTokenData, CompiledTokenEntry } from '@fragments-sdk/context/types';
+import { z } from 'zod';
+export { ContextOptions, ContextResult, generateContext } from '@fragments-sdk/context/generate';
+import { ComponentGraph } from '@fragments-sdk/context/graph';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { toId as toId$1, storyNameFromExport as storyNameFromExport$1, isExportStory as isExportStory$1 } from '@storybook/csf';
+
+/**
+ * Brand constants for easy rebranding if domain availability requires it.
+ * All naming throughout the codebase should reference these constants.
+ */
+declare const BRAND: {
+    /** Display name (e.g., "Fragments") */
+    readonly name: "Fragments";
+    /** Lowercase name for file paths and CLI (e.g., "fragments") */
+    readonly nameLower: "fragments";
+    /** File extension for fragment definition files (e.g., ".fragment.tsx") */
+    readonly fileExtension: ".fragment.tsx";
+    /** Legacy file extension for segments (still supported for migration) */
+    readonly legacyFileExtension: ".segment.tsx";
+    /** JSON file extension for compiled output */
+    readonly jsonExtension: ".fragment.json";
+    /** Default output file name (e.g., "fragments.json") */
+    readonly outFile: "fragments.json";
+    /** Config file name (e.g., "fragments.config.ts") */
+    readonly configFile: "fragments.config.ts";
+    /** Legacy config file name (still supported for migration) */
+    readonly legacyConfigFile: "segments.config.ts";
+    /** CLI command name (e.g., "fragments") */
+    readonly cliCommand: "fragments";
+    /** Package scope (e.g., "@fragments") */
+    readonly packageScope: "@fragments";
+    /** Directory for storing fragments, registry, and cache */
+    readonly dataDir: ".fragments";
+    /** Components subdirectory within .fragments/ */
+    readonly componentsDir: "components";
+    /** Registry file name */
+    readonly registryFile: "registry.json";
+    /** Context file name (AI-ready markdown) */
+    readonly contextFile: "context.md";
+    /** Screenshots subdirectory */
+    readonly screenshotsDir: "screenshots";
+    /** Cache subdirectory (gitignored) */
+    readonly cacheDir: "cache";
+    /** Diff output subdirectory (gitignored) */
+    readonly diffDir: "diff";
+    /** Manifest filename */
+    readonly manifestFile: "manifest.json";
+    /** Prefix for localStorage keys (e.g., "fragments-") */
+    readonly storagePrefix: "fragments-";
+    /** Static viewer HTML file name */
+    readonly viewerHtmlFile: "fragments-viewer.html";
+    /** MCP tool name prefix (e.g., "fragments_") */
+    readonly mcpToolPrefix: "fragments_";
+    /** File extension for block definition files */
+    readonly blockFileExtension: ".block.ts";
+    /** @deprecated Use blockFileExtension instead */
+    readonly recipeFileExtension: ".recipe.ts";
+    /** Vite plugin namespace */
+    readonly vitePluginNamespace: "fragments-core-shim";
+};
+type Brand = typeof BRAND;
+/**
+ * Default configuration values for the service.
+ * These can be overridden in fragments.config.ts
+ */
+declare const DEFAULTS: {
+    /** Default viewport dimensions */
+    readonly viewport: {
+        readonly width: 1280;
+        readonly height: 800;
+    };
+    /** Default diff threshold (percentage) */
+    readonly diffThreshold: 5;
+    /** Browser pool size */
+    readonly poolSize: 3;
+    /** Idle timeout before browser shutdown (ms) - 5 minutes */
+    readonly idleTimeoutMs: number;
+    /** Delay after render before capture (ms) */
+    readonly captureDelayMs: 100;
+    /** Font loading timeout (ms) */
+    readonly fontTimeoutMs: 3000;
+    /** Default theme */
+    readonly theme: "light";
+    /** Dev server port */
+    readonly port: 6006;
+};
+type Defaults = typeof DEFAULTS;
+
+/**
+ * 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.
+ */
+type FragmentComponent<TProps = any> = ComponentType<TProps> | ((props: TProps) => ReactNode | JSX.Element | null);
+/**
+ * Metadata about the component
+ */
+interface FragmentMeta$1 {
+    /** 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
+ */
+type FigmaPropMapping = FigmaStringMapping | FigmaBooleanMapping | FigmaEnumMapping | FigmaInstanceMapping | FigmaChildrenMapping | FigmaTextContentMapping;
+/** Maps a Figma text property to a string prop */
+interface FigmaStringMapping {
+    __type: 'figma-string';
+    figmaProperty: string;
+}
+/** Maps a Figma boolean property to a boolean prop (with optional value mapping) */
+interface FigmaBooleanMapping {
+    __type: 'figma-boolean';
+    figmaProperty: string;
+    valueMapping?: {
+        true: unknown;
+        false: unknown;
+    };
+}
+/** Maps a Figma variant property to an enum prop */
+interface FigmaEnumMapping {
+    __type: 'figma-enum';
+    figmaProperty: string;
+    valueMapping: Record<string, unknown>;
+}
+/** References a nested Figma component instance */
+interface FigmaInstanceMapping {
+    __type: 'figma-instance';
+    figmaProperty: string;
+}
+/** Renders children from Figma layer names */
+interface FigmaChildrenMapping {
+    __type: 'figma-children';
+    layers: string[];
+}
+/** Extracts text content from a Figma text layer */
+interface FigmaTextContentMapping {
+    __type: 'figma-text-content';
+    layer: string;
+}
+/**
+ * Usage guidelines for AI agents and developers
+ */
+interface FragmentUsage$1 {
+    /** 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
+ */
+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
+ */
+type ControlType = "text" | "number" | "range" | "boolean" | "select" | "multi-select" | "radio" | "inline-radio" | "check" | "inline-check" | "object" | "file" | "color" | "date";
+/**
+ * Definition for a single prop
+ */
+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
+ */
+type RelationshipType = "alternative" | "sibling" | "parent" | "child" | "composition" | "complementary" | "used-by";
+/**
+ * Relationship to another component
+ */
+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
+ */
+type VariantLoader = () => Promise<Record<string, unknown>>;
+/**
+ * Play function context passed during interaction testing
+ */
+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
+ */
+type PlayFunction = (context: PlayFunctionContext) => Promise<void>;
+/**
+ * Options passed to variant render function
+ */
+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
+ */
+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
+ */
+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;
+}
+/**
+ * Provenance tracking for generated fragments
+ * Helps distinguish human-authored from machine-generated content
+ */
+interface FragmentGenerated {
+    /** Source of this fragment definition */
+    source: "storybook" | "manual" | "ai";
+    /** Original source file (e.g., "Button.stories.tsx") */
+    sourceFile?: string;
+    /** Confidence score from 0-1 (how reliable the extraction was) */
+    confidence?: number;
+    /** ISO timestamp when this was generated */
+    timestamp?: string;
+}
+/**
+ * AI-specific metadata for playground context generation
+ * Provides hints for AI code generation about component composition
+ */
+interface AIMetadata {
+    /** How this component is composed with others */
+    compositionPattern?: "compound" | "simple" | "controlled";
+    /** 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
+ */
+interface FragmentDefinition<TProps = unknown> {
+    /** The component being documented */
+    component: FragmentComponent<TProps>;
+    /** Component metadata */
+    meta: FragmentMeta$1;
+    /** Usage guidelines */
+    usage: FragmentUsage$1;
+    /** 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;
+}
+/**
+ * Registry generation options
+ */
+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
+ */
+interface TokenConfig {
+    /**
+     * Glob patterns for files to scan for tokens
+     * e.g., ["src/styles/theme.scss", "src/styles/variables.css"]
+     */
+    include: string[];
+    /**
+     * 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;
+}
+/**
+ * CI configuration for automated compliance checks
+ */
+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`.
+ */
+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.
+ */
+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;
+}
+/**
+ * Config file structure
+ */
+interface FragmentsConfig {
+    /** 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;
+}
+/**
+ * Screenshot capture configuration
+ */
+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
+ */
+interface ServiceConfig {
+    /** Browser pool size */
+    poolSize?: number;
+    /** Idle timeout before shutdown (ms) */
+    idleTimeout?: number;
+}
+/**
+ * Viewport dimensions
+ */
+interface Viewport {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+}
+/**
+ * Theme identifier
+ */
+type Theme = "light" | "dark";
+/**
+ * Screenshot metadata
+ */
+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
+ */
+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
+ */
+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
+ */
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Baseline information stored in manifest
+ */
+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
+ */
+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
+ */
+interface VerifyRequest {
+    /** Component name */
+    component: string;
+    /** Variant name */
+    variant: string;
+    /** Theme to verify against */
+    theme?: Theme;
+    /** Override diff threshold */
+    threshold?: number;
+}
+/**
+ * Verification result
+ */
+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;
+    };
+}
+
+/**
+ * Block definition — a named composition pattern showing how
+ * design system components wire together for a common use case.
+ */
+interface BlockDefinition {
+    name: string;
+    description: string;
+    category: string;
+    components: string[];
+    code: string;
+    tags?: string[];
+}
+/**
+ * @deprecated Use BlockDefinition instead
+ */
+type RecipeDefinition = BlockDefinition;
+/**
+ * @deprecated Use CompiledBlock instead
+ */
+type CompiledRecipe = CompiledBlock;
+
+/**
+ * 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.
+ */
+interface PerformanceBudgets {
+    /** Maximum gzipped bundle size in bytes */
+    bundleSize: number;
+}
+interface PerformanceConfig {
+    preset: string;
+    budgets: PerformanceBudgets;
+}
+type ComplexityTier = 'lightweight' | 'moderate' | 'heavy';
+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;
+}
+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>;
+}
+declare const PRESET_NAMES: readonly string[];
+/**
+ * Resolve a performance config from user input.
+ * Accepts a preset name string or a custom config object.
+ */
+declare function resolvePerformanceConfig(input: string | {
+    preset?: string;
+    budgets?: Partial<PerformanceBudgets>;
+} | undefined): PerformanceConfig;
+/**
+ * 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
+ */
+declare function classifyComplexity(gzipBytes: number): ComplexityTier;
+/**
+ * Format bytes to a human-readable string (e.g. "2.1KB", "15.3KB").
+ */
+declare function formatBytes(bytes: number): string;
+/**
+ * Create a visual budget bar for terminal output.
+ */
+declare function budgetBar(percent: number, width?: number): string;
+
+/**
+ * Design Token Types for Fragments
+ *
+ * These types define the structure for CSS custom property (CSS variable) discovery,
+ * parsing, and reverse lookup capabilities. The token system enables:
+ *
+ * 1. Automatic discovery of design tokens from CSS/SCSS files
+ * 2. Reverse lookup: given a computed value, find which token(s) produce it
+ * 3. Detection of hardcoded values vs token usage
+ * 4. AI-friendly fix suggestions
+ */
+/**
+ * Token categories for grouping and filtering
+ */
+type TokenCategory = "color" | "spacing" | "typography" | "radius" | "shadow" | "sizing" | "border" | "animation" | "z-index" | "other";
+/**
+ * A single design token (CSS custom property)
+ */
+interface DesignToken {
+    /** Token name with leading dashes (e.g., "--color-primary") */
+    name: string;
+    /** Raw value as written in CSS (e.g., "var(--color-cobalt-50)") */
+    rawValue: string;
+    /** Fully resolved value (e.g., "#0051c2") */
+    resolvedValue: string;
+    /** Inferred category based on naming convention */
+    category: TokenCategory;
+    /**
+     * Token level in the design system hierarchy:
+     * - 1 = Base/primitive tokens (raw values like colors, sizes)
+     * - 2 = Semantic tokens (references to base tokens with meaning)
+     * - 3 = Component tokens (component-specific tokens)
+     */
+    level: 1 | 2 | 3;
+    /**
+     * Reference chain showing how the value was resolved
+     * e.g., ["--color-primary", "--color-cobalt-50"] means
+     * --color-primary references --color-cobalt-50
+     */
+    referenceChain: string[];
+    /** Source file where this token was defined */
+    sourceFile: string;
+    /** Line number in source file */
+    lineNumber?: number;
+    /** Theme this token belongs to (e.g., "default", "dark", "light") */
+    theme: string;
+    /** CSS selector where this token is defined (e.g., ":root", "[data-theme='dark']") */
+    selector: string;
+    /** Optional description from comments */
+    description?: string;
+}
+/**
+ * Token registry for fast lookups
+ */
+interface TokenRegistry {
+    /** Lookup by token name (e.g., "--color-primary") */
+    byName: Map<string, DesignToken>;
+    /**
+     * REVERSE lookup: resolved value -> token names
+     * Key is normalized value (e.g., "#0051c2" lowercase)
+     * Value is array of token names that resolve to this value
+     */
+    byValue: Map<string, string[]>;
+    /** Tokens grouped by theme */
+    byTheme: Map<string, DesignToken[]>;
+    /** Tokens grouped by category */
+    byCategory: Map<TokenCategory, DesignToken[]>;
+    /** Registry metadata */
+    meta: TokenRegistryMeta;
+}
+/**
+ * Token registry metadata
+ */
+interface TokenRegistryMeta {
+    /** When tokens were discovered */
+    discoveredAt: Date;
+    /** Source files that were parsed */
+    sourceFiles: string[];
+    /** Total number of tokens discovered */
+    totalTokens: number;
+    /** Time taken to parse (ms) */
+    parseTimeMs: number;
+    /** Number of circular references detected */
+    circularRefs: number;
+    /** Number of unresolved references */
+    unresolvedRefs: number;
+}
+/**
+ * Enhanced style diff item with token information
+ */
+interface EnhancedStyleDiffItem {
+    /** CSS property name (e.g., "backgroundColor") */
+    property: string;
+    /** Value from Figma design */
+    figma: string;
+    /** Value from rendered component */
+    rendered: string;
+    /** Whether values match (within tolerance) */
+    match: boolean;
+    /** Token name if Figma value matches a known token */
+    figmaToken?: string;
+    /** Token name if rendered value uses a token */
+    renderedToken?: string;
+    /**
+     * True if rendered value doesn't use a token but should
+     * (i.e., Figma uses a token but code uses hardcoded value)
+     */
+    isHardcoded: boolean;
+    /** Suggested fix if hardcoded */
+    suggestedFix?: TokenFix;
+}
+/**
+ * Token-based fix suggestion
+ */
+interface TokenFix {
+    /** Token name to use (e.g., "--color-primary") */
+    tokenName: string;
+    /** Token's resolved value */
+    tokenValue: string;
+    /** Code snippet to fix the issue */
+    codeFix: string;
+    /** Confidence score 0-1 */
+    confidence: number;
+    /** Human-readable explanation */
+    reason: string;
+}
+/**
+ * Result of parsing a CSS/SCSS file for tokens
+ */
+interface TokenParseResult {
+    /** Tokens discovered in the file */
+    tokens: DesignToken[];
+    /** Errors encountered during parsing */
+    errors: TokenParseError[];
+    /** Warnings (non-fatal issues) */
+    warnings: string[];
+    /** Parse time in ms */
+    parseTimeMs: number;
+}
+/**
+ * Error during token parsing
+ */
+interface TokenParseError {
+    /** Error message */
+    message: string;
+    /** File where error occurred */
+    file: string;
+    /** Line number if known */
+    line?: number;
+    /** The problematic content if available */
+    content?: string;
+}
+/**
+ * Request to match a value to tokens
+ */
+interface TokenMatchRequest {
+    /** The value to find tokens for (e.g., "#0051c2") */
+    value: string;
+    /** Property type hint for better matching (e.g., "color") */
+    propertyType?: "color" | "spacing" | "typography" | "other";
+    /** Specific theme to search in */
+    theme?: string;
+}
+/**
+ * Result of token matching
+ */
+interface TokenMatchResult {
+    /** Exact matches (same resolved value) */
+    exactMatches: DesignToken[];
+    /** Close matches (similar value, useful for colors) */
+    closeMatches: Array<{
+        token: DesignToken;
+        /** How close the match is (0-1, 1 = exact) */
+        similarity: number;
+    }>;
+    /** Whether any match was found */
+    found: boolean;
+}
+/**
+ * Summary of token usage in a component
+ */
+interface TokenUsageSummary {
+    /** Total CSS properties checked */
+    totalProperties: number;
+    /** Properties using design tokens */
+    usingTokens: number;
+    /** Properties with hardcoded values */
+    hardcoded: number;
+    /** Properties matching but not using tokens explicitly */
+    implicitMatches: number;
+    /** Compliance percentage (usingTokens / totalProperties * 100) */
+    compliancePercent: number;
+    /** List of hardcoded properties with fix suggestions */
+    hardcodedProperties: EnhancedStyleDiffItem[];
+}
+
+declare const figmaPropMappingSchema: z.ZodDiscriminatedUnion<"__type", [z.ZodObject<{
+    __type: z.ZodLiteral<"figma-string">;
+    figmaProperty: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    __type: "figma-string";
+    figmaProperty: string;
+}, {
+    __type: "figma-string";
+    figmaProperty: string;
+}>, z.ZodObject<{
+    __type: z.ZodLiteral<"figma-boolean">;
+    figmaProperty: z.ZodString;
+    valueMapping: z.ZodOptional<z.ZodObject<{
+        true: z.ZodUnknown;
+        false: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        true?: unknown;
+        false?: unknown;
+    }, {
+        true?: unknown;
+        false?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    __type: "figma-boolean";
+    figmaProperty: string;
+    valueMapping?: {
+        true?: unknown;
+        false?: unknown;
+    } | undefined;
+}, {
+    __type: "figma-boolean";
+    figmaProperty: string;
+    valueMapping?: {
+        true?: unknown;
+        false?: unknown;
+    } | undefined;
+}>, z.ZodObject<{
+    __type: z.ZodLiteral<"figma-enum">;
+    figmaProperty: z.ZodString;
+    valueMapping: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    __type: "figma-enum";
+    figmaProperty: string;
+    valueMapping: Record<string, unknown>;
+}, {
+    __type: "figma-enum";
+    figmaProperty: string;
+    valueMapping: Record<string, unknown>;
+}>, z.ZodObject<{
+    __type: z.ZodLiteral<"figma-instance">;
+    figmaProperty: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    __type: "figma-instance";
+    figmaProperty: string;
+}, {
+    __type: "figma-instance";
+    figmaProperty: string;
+}>, z.ZodObject<{
+    __type: z.ZodLiteral<"figma-children">;
+    layers: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    __type: "figma-children";
+    layers: string[];
+}, {
+    __type: "figma-children";
+    layers: string[];
+}>, z.ZodObject<{
+    __type: z.ZodLiteral<"figma-text-content">;
+    layer: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    __type: "figma-text-content";
+    layer: string;
+}, {
+    __type: "figma-text-content";
+    layer: string;
+}>]>;
+declare const fragmentMetaSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    status: z.ZodOptional<z.ZodEnum<["stable", "beta", "deprecated", "experimental"]>>;
+    since: z.ZodOptional<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        version: string;
+        reason?: string | undefined;
+    }, {
+        name: string;
+        version: string;
+        reason?: string | undefined;
+    }>, "many">>;
+    figma: z.ZodOptional<z.ZodString>;
+    figmaProps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<"__type", [z.ZodObject<{
+        __type: z.ZodLiteral<"figma-string">;
+        figmaProperty: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        __type: "figma-string";
+        figmaProperty: string;
+    }, {
+        __type: "figma-string";
+        figmaProperty: string;
+    }>, z.ZodObject<{
+        __type: z.ZodLiteral<"figma-boolean">;
+        figmaProperty: z.ZodString;
+        valueMapping: z.ZodOptional<z.ZodObject<{
+            true: z.ZodUnknown;
+            false: z.ZodUnknown;
+        }, "strip", z.ZodTypeAny, {
+            true?: unknown;
+            false?: unknown;
+        }, {
+            true?: unknown;
+            false?: unknown;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        __type: "figma-boolean";
+        figmaProperty: string;
+        valueMapping?: {
+            true?: unknown;
+            false?: unknown;
+        } | undefined;
+    }, {
+        __type: "figma-boolean";
+        figmaProperty: string;
+        valueMapping?: {
+            true?: unknown;
+            false?: unknown;
+        } | undefined;
+    }>, z.ZodObject<{
+        __type: z.ZodLiteral<"figma-enum">;
+        figmaProperty: z.ZodString;
+        valueMapping: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        __type: "figma-enum";
+        figmaProperty: string;
+        valueMapping: Record<string, unknown>;
+    }, {
+        __type: "figma-enum";
+        figmaProperty: string;
+        valueMapping: Record<string, unknown>;
+    }>, z.ZodObject<{
+        __type: z.ZodLiteral<"figma-instance">;
+        figmaProperty: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        __type: "figma-instance";
+        figmaProperty: string;
+    }, {
+        __type: "figma-instance";
+        figmaProperty: string;
+    }>, z.ZodObject<{
+        __type: z.ZodLiteral<"figma-children">;
+        layers: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        __type: "figma-children";
+        layers: string[];
+    }, {
+        __type: "figma-children";
+        layers: string[];
+    }>, z.ZodObject<{
+        __type: z.ZodLiteral<"figma-text-content">;
+        layer: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        __type: "figma-text-content";
+        layer: string;
+    }, {
+        __type: "figma-text-content";
+        layer: string;
+    }>]>>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    category: string;
+    status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+    tags?: string[] | undefined;
+    since?: string | undefined;
+    dependencies?: {
+        name: string;
+        version: string;
+        reason?: string | undefined;
+    }[] | undefined;
+    figma?: string | undefined;
+    figmaProps?: Record<string, {
+        __type: "figma-string";
+        figmaProperty: string;
+    } | {
+        __type: "figma-boolean";
+        figmaProperty: string;
+        valueMapping?: {
+            true?: unknown;
+            false?: unknown;
+        } | undefined;
+    } | {
+        __type: "figma-enum";
+        figmaProperty: string;
+        valueMapping: Record<string, unknown>;
+    } | {
+        __type: "figma-instance";
+        figmaProperty: string;
+    } | {
+        __type: "figma-children";
+        layers: string[];
+    } | {
+        __type: "figma-text-content";
+        layer: string;
+    }> | undefined;
+}, {
+    name: string;
+    description: string;
+    category: string;
+    status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+    tags?: string[] | undefined;
+    since?: string | undefined;
+    dependencies?: {
+        name: string;
+        version: string;
+        reason?: string | undefined;
+    }[] | undefined;
+    figma?: string | undefined;
+    figmaProps?: Record<string, {
+        __type: "figma-string";
+        figmaProperty: string;
+    } | {
+        __type: "figma-boolean";
+        figmaProperty: string;
+        valueMapping?: {
+            true?: unknown;
+            false?: unknown;
+        } | undefined;
+    } | {
+        __type: "figma-enum";
+        figmaProperty: string;
+        valueMapping: Record<string, unknown>;
+    } | {
+        __type: "figma-instance";
+        figmaProperty: string;
+    } | {
+        __type: "figma-children";
+        layers: string[];
+    } | {
+        __type: "figma-text-content";
+        layer: string;
+    }> | undefined;
+}>;
+declare const fragmentUsageSchema: z.ZodObject<{
+    when: z.ZodArray<z.ZodString, "many">;
+    whenNot: z.ZodArray<z.ZodString, "many">;
+    guidelines: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    accessibility: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    when: string[];
+    whenNot: string[];
+    guidelines?: string[] | undefined;
+    accessibility?: string[] | undefined;
+}, {
+    when: string[];
+    whenNot: string[];
+    guidelines?: string[] | undefined;
+    accessibility?: string[] | undefined;
+}>;
+declare const propDefinitionSchema: z.ZodObject<{
+    type: z.ZodType<string, z.ZodTypeDef, string>;
+    values: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    default: z.ZodOptional<z.ZodUnknown>;
+    description: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    typeDetails: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    values?: readonly string[] | undefined;
+    description?: string | undefined;
+    default?: unknown;
+    required?: boolean | undefined;
+    constraints?: string[] | undefined;
+    typeDetails?: Record<string, unknown> | undefined;
+}, {
+    type: string;
+    values?: readonly string[] | undefined;
+    description?: string | undefined;
+    default?: unknown;
+    required?: boolean | undefined;
+    constraints?: string[] | undefined;
+    typeDetails?: Record<string, unknown> | undefined;
+}>;
+declare const componentRelationSchema: z.ZodObject<{
+    component: z.ZodString;
+    relationship: z.ZodEnum<["alternative", "sibling", "parent", "child", "composition", "complementary", "used-by"]>;
+    note: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    component: string;
+    relationship: "alternative" | "sibling" | "parent" | "child" | "composition" | "complementary" | "used-by";
+    note: string;
+}, {
+    component: string;
+    relationship: "alternative" | "sibling" | "parent" | "child" | "composition" | "complementary" | "used-by";
+    note: string;
+}>;
+declare const fragmentVariantSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    render: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    code: z.ZodOptional<z.ZodString>;
+    figma: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    render: (...args: unknown[]) => unknown;
+    code?: string | undefined;
+    figma?: string | undefined;
+}, {
+    name: string;
+    description: string;
+    render: (...args: unknown[]) => unknown;
+    code?: string | undefined;
+    figma?: string | undefined;
+}>;
+/**
+ * Schema for banned patterns in codebase
+ */
+declare const fragmentBanSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    pattern: string;
+    message: string;
+}, {
+    pattern: string;
+    message: string;
+}>;
+/**
+ * Schema for agent-optimized contract metadata
+ */
+declare const fragmentContractSchema: z.ZodObject<{
+    propsSummary: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    a11yRules: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    bans: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        pattern: z.ZodString;
+        message: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        pattern: string;
+        message: string;
+    }, {
+        pattern: string;
+        message: string;
+    }>, "many">>;
+    scenarioTags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    performanceBudget: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    propsSummary?: string[] | undefined;
+    a11yRules?: string[] | undefined;
+    bans?: {
+        pattern: string;
+        message: string;
+    }[] | undefined;
+    scenarioTags?: string[] | undefined;
+    performanceBudget?: number | undefined;
+}, {
+    propsSummary?: string[] | undefined;
+    a11yRules?: string[] | undefined;
+    bans?: {
+        pattern: string;
+        message: string;
+    }[] | undefined;
+    scenarioTags?: string[] | undefined;
+    performanceBudget?: number | undefined;
+}>;
+/**
+ * Schema for provenance tracking of generated fragments
+ */
+declare const fragmentGeneratedSchema: z.ZodObject<{
+    source: z.ZodEnum<["storybook", "manual", "ai"]>;
+    sourceFile: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    source: "storybook" | "manual" | "ai";
+    sourceFile?: string | undefined;
+    confidence?: number | undefined;
+    timestamp?: string | undefined;
+}, {
+    source: "storybook" | "manual" | "ai";
+    sourceFile?: string | undefined;
+    confidence?: number | undefined;
+    timestamp?: string | undefined;
+}>;
+/**
+ * Schema for AI-specific metadata for playground context generation
+ */
+declare const aiMetadataSchema: z.ZodObject<{
+    compositionPattern: z.ZodOptional<z.ZodEnum<["compound", "simple", "controlled", "wrapper"]>>;
+    subComponents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    requiredChildren: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    commonPatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    compositionPattern?: "compound" | "simple" | "controlled" | "wrapper" | undefined;
+    subComponents?: string[] | undefined;
+    requiredChildren?: string[] | undefined;
+    commonPatterns?: string[] | undefined;
+}, {
+    compositionPattern?: "compound" | "simple" | "controlled" | "wrapper" | undefined;
+    subComponents?: string[] | undefined;
+    requiredChildren?: string[] | undefined;
+    commonPatterns?: string[] | undefined;
+}>;
+/**
+ * Schema for block definitions
+ */
+declare const blockDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodString;
+    components: z.ZodArray<z.ZodString, "many">;
+    code: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    components: string[];
+    code: string;
+    name: string;
+    description: string;
+    category: string;
+    tags?: string[] | undefined;
+}, {
+    components: string[];
+    code: string;
+    name: string;
+    description: string;
+    category: string;
+    tags?: string[] | undefined;
+}>;
+declare const fragmentDefinitionSchema: z.ZodObject<{
+    component: z.ZodAny;
+    meta: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        category: z.ZodString;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        status: z.ZodOptional<z.ZodEnum<["stable", "beta", "deprecated", "experimental"]>>;
+        since: z.ZodOptional<z.ZodString>;
+        dependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }, {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }>, "many">>;
+        figma: z.ZodOptional<z.ZodString>;
+        figmaProps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<"__type", [z.ZodObject<{
+            __type: z.ZodLiteral<"figma-string">;
+            figmaProperty: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            __type: "figma-string";
+            figmaProperty: string;
+        }, {
+            __type: "figma-string";
+            figmaProperty: string;
+        }>, z.ZodObject<{
+            __type: z.ZodLiteral<"figma-boolean">;
+            figmaProperty: z.ZodString;
+            valueMapping: z.ZodOptional<z.ZodObject<{
+                true: z.ZodUnknown;
+                false: z.ZodUnknown;
+            }, "strip", z.ZodTypeAny, {
+                true?: unknown;
+                false?: unknown;
+            }, {
+                true?: unknown;
+                false?: unknown;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            __type: "figma-boolean";
+            figmaProperty: string;
+            valueMapping?: {
+                true?: unknown;
+                false?: unknown;
+            } | undefined;
+        }, {
+            __type: "figma-boolean";
+            figmaProperty: string;
+            valueMapping?: {
+                true?: unknown;
+                false?: unknown;
+            } | undefined;
+        }>, z.ZodObject<{
+            __type: z.ZodLiteral<"figma-enum">;
+            figmaProperty: z.ZodString;
+            valueMapping: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            __type: "figma-enum";
+            figmaProperty: string;
+            valueMapping: Record<string, unknown>;
+        }, {
+            __type: "figma-enum";
+            figmaProperty: string;
+            valueMapping: Record<string, unknown>;
+        }>, z.ZodObject<{
+            __type: z.ZodLiteral<"figma-instance">;
+            figmaProperty: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            __type: "figma-instance";
+            figmaProperty: string;
+        }, {
+            __type: "figma-instance";
+            figmaProperty: string;
+        }>, z.ZodObject<{
+            __type: z.ZodLiteral<"figma-children">;
+            layers: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            __type: "figma-children";
+            layers: string[];
+        }, {
+            __type: "figma-children";
+            layers: string[];
+        }>, z.ZodObject<{
+            __type: z.ZodLiteral<"figma-text-content">;
+            layer: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            __type: "figma-text-content";
+            layer: string;
+        }, {
+            __type: "figma-text-content";
+            layer: string;
+        }>]>>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        category: string;
+        status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+        tags?: string[] | undefined;
+        since?: string | undefined;
+        dependencies?: {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }[] | undefined;
+        figma?: string | undefined;
+        figmaProps?: Record<string, {
+            __type: "figma-string";
+            figmaProperty: string;
+        } | {
+            __type: "figma-boolean";
+            figmaProperty: string;
+            valueMapping?: {
+                true?: unknown;
+                false?: unknown;
+            } | undefined;
+        } | {
+            __type: "figma-enum";
+            figmaProperty: string;
+            valueMapping: Record<string, unknown>;
+        } | {
+            __type: "figma-instance";
+            figmaProperty: string;
+        } | {
+            __type: "figma-children";
+            layers: string[];
+        } | {
+            __type: "figma-text-content";
+            layer: string;
+        }> | undefined;
+    }, {
+        name: string;
+        description: string;
+        category: string;
+        status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+        tags?: string[] | undefined;
+        since?: string | undefined;
+        dependencies?: {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }[] | undefined;
+        figma?: string | undefined;
+        figmaProps?: Record<string, {
+            __type: "figma-string";
+            figmaProperty: string;
+        } | {
+            __type: "figma-boolean";
+            figmaProperty: string;
+            valueMapping?: {
+                true?: unknown;
+                false?: unknown;
+            } | undefined;
+        } | {
+            __type: "figma-enum";
+            figmaProperty: string;
+            valueMapping: Record<string, unknown>;
+        } | {
+            __type: "figma-instance";
+            figmaProperty: string;
+        } | {
+            __type: "figma-children";
+            layers: string[];
+        } | {
+            __type: "figma-text-content";
+            layer: string;
+        }> | undefined;
+    }>;
+    usage: z.ZodObject<{
+        when: z.ZodArray<z.ZodString, "many">;
+        whenNot: z.ZodArray<z.ZodString, "many">;
+        guidelines: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        accessibility: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        when: string[];
+        whenNot: string[];
+        guidelines?: string[] | undefined;
+        accessibility?: string[] | undefined;
+    }, {
+        when: string[];
+        whenNot: string[];
+        guidelines?: string[] | undefined;
+        accessibility?: string[] | undefined;
+    }>;
+    props: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodType<string, z.ZodTypeDef, string>;
+        values: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+        default: z.ZodOptional<z.ZodUnknown>;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        typeDetails: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        values?: readonly string[] | undefined;
+        description?: string | undefined;
+        default?: unknown;
+        required?: boolean | undefined;
+        constraints?: string[] | undefined;
+        typeDetails?: Record<string, unknown> | undefined;
+    }, {
+        type: string;
+        values?: readonly string[] | undefined;
+        description?: string | undefined;
+        default?: unknown;
+        required?: boolean | undefined;
+        constraints?: string[] | undefined;
+        typeDetails?: Record<string, unknown> | undefined;
+    }>>;
+    relations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        component: z.ZodString;
+        relationship: z.ZodEnum<["alternative", "sibling", "parent", "child", "composition", "complementary", "used-by"]>;
+        note: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        component: string;
+        relationship: "alternative" | "sibling" | "parent" | "child" | "composition" | "complementary" | "used-by";
+        note: string;
+    }, {
+        component: string;
+        relationship: "alternative" | "sibling" | "parent" | "child" | "composition" | "complementary" | "used-by";
+        note: string;
+    }>, "many">>;
+    variants: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        render: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        code: z.ZodOptional<z.ZodString>;
+        figma: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        render: (...args: unknown[]) => unknown;
+        code?: string | undefined;
+        figma?: string | undefined;
+    }, {
+        name: string;
+        description: string;
+        render: (...args: unknown[]) => unknown;
+        code?: string | undefined;
+        figma?: string | undefined;
+    }>, "many">;
+    contract: z.ZodOptional<z.ZodObject<{
+        propsSummary: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        a11yRules: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        bans: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            pattern: z.ZodString;
+            message: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            pattern: string;
+            message: string;
+        }, {
+            pattern: string;
+            message: string;
+        }>, "many">>;
+        scenarioTags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        performanceBudget: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        propsSummary?: string[] | undefined;
+        a11yRules?: string[] | undefined;
+        bans?: {
+            pattern: string;
+            message: string;
+        }[] | undefined;
+        scenarioTags?: string[] | undefined;
+        performanceBudget?: number | undefined;
+    }, {
+        propsSummary?: string[] | undefined;
+        a11yRules?: string[] | undefined;
+        bans?: {
+            pattern: string;
+            message: string;
+        }[] | undefined;
+        scenarioTags?: string[] | undefined;
+        performanceBudget?: number | undefined;
+    }>>;
+    ai: z.ZodOptional<z.ZodObject<{
+        compositionPattern: z.ZodOptional<z.ZodEnum<["compound", "simple", "controlled", "wrapper"]>>;
+        subComponents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        requiredChildren: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        commonPatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        compositionPattern?: "compound" | "simple" | "controlled" | "wrapper" | undefined;
+        subComponents?: string[] | undefined;
+        requiredChildren?: string[] | undefined;
+        commonPatterns?: string[] | undefined;
+    }, {
+        compositionPattern?: "compound" | "simple" | "controlled" | "wrapper" | undefined;
+        subComponents?: string[] | undefined;
+        requiredChildren?: string[] | undefined;
+        commonPatterns?: string[] | undefined;
+    }>>;
+    _generated: z.ZodOptional<z.ZodObject<{
+        source: z.ZodEnum<["storybook", "manual", "ai"]>;
+        sourceFile: z.ZodOptional<z.ZodString>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        source: "storybook" | "manual" | "ai";
+        sourceFile?: string | undefined;
+        confidence?: number | undefined;
+        timestamp?: string | undefined;
+    }, {
+        source: "storybook" | "manual" | "ai";
+        sourceFile?: string | undefined;
+        confidence?: number | undefined;
+        timestamp?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    meta: {
+        name: string;
+        description: string;
+        category: string;
+        status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+        tags?: string[] | undefined;
+        since?: string | undefined;
+        dependencies?: {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }[] | undefined;
+        figma?: string | undefined;
+        figmaProps?: Record<string, {
+            __type: "figma-string";
+            figmaProperty: string;
+        } | {
+            __type: "figma-boolean";
+            figmaProperty: string;
+            valueMapping?: {
+                true?: unknown;
+                false?: unknown;
+            } | undefined;
+        } | {
+            __type: "figma-enum";
+            figmaProperty: string;
+            valueMapping: Record<string, unknown>;
+        } | {
+            __type: "figma-instance";
+            figmaProperty: string;
+        } | {
+            __type: "figma-children";
+            layers: string[];
+        } | {
+            __type: "figma-text-content";
+            layer: string;
+        }> | undefined;
+    };
+    usage: {
+        when: string[];
+        whenNot: string[];
+        guidelines?: string[] | undefined;
+        accessibility?: string[] | undefined;
+    };
+    props: Record<string, {
+        type: string;
+        values?: readonly string[] | undefined;
+        description?: string | undefined;
+        default?: unknown;
+        required?: boolean | undefined;
+        constraints?: string[] | undefined;
+        typeDetails?: Record<string, unknown> | undefined;
+    }>;
+    variants: {
+        name: string;
+        description: string;
+        render: (...args: unknown[]) => unknown;
+        code?: string | undefined;
+        figma?: string | undefined;
+    }[];
+    ai?: {
+        compositionPattern?: "compound" | "simple" | "controlled" | "wrapper" | undefined;
+        subComponents?: string[] | undefined;
+        requiredChildren?: string[] | undefined;
+        commonPatterns?: string[] | undefined;
+    } | undefined;
+    component?: any;
+    relations?: {
+        component: string;
+        relationship: "alternative" | "sibling" | "parent" | "child" | "composition" | "complementary" | "used-by";
+        note: string;
+    }[] | undefined;
+    contract?: {
+        propsSummary?: string[] | undefined;
+        a11yRules?: string[] | undefined;
+        bans?: {
+            pattern: string;
+            message: string;
+        }[] | undefined;
+        scenarioTags?: string[] | undefined;
+        performanceBudget?: number | undefined;
+    } | undefined;
+    _generated?: {
+        source: "storybook" | "manual" | "ai";
+        sourceFile?: string | undefined;
+        confidence?: number | undefined;
+        timestamp?: string | undefined;
+    } | undefined;
+}, {
+    meta: {
+        name: string;
+        description: string;
+        category: string;
+        status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+        tags?: string[] | undefined;
+        since?: string | undefined;
+        dependencies?: {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }[] | undefined;
+        figma?: string | undefined;
+        figmaProps?: Record<string, {
+            __type: "figma-string";
+            figmaProperty: string;
+        } | {
+            __type: "figma-boolean";
+            figmaProperty: string;
+            valueMapping?: {
+                true?: unknown;
+                false?: unknown;
+            } | undefined;
+        } | {
+            __type: "figma-enum";
+            figmaProperty: string;
+            valueMapping: Record<string, unknown>;
+        } | {
+            __type: "figma-instance";
+            figmaProperty: string;
+        } | {
+            __type: "figma-children";
+            layers: string[];
+        } | {
+            __type: "figma-text-content";
+            layer: string;
+        }> | undefined;
+    };
+    usage: {
+        when: string[];
+        whenNot: string[];
+        guidelines?: string[] | undefined;
+        accessibility?: string[] | undefined;
+    };
+    props: Record<string, {
+        type: string;
+        values?: readonly string[] | undefined;
+        description?: string | undefined;
+        default?: unknown;
+        required?: boolean | undefined;
+        constraints?: string[] | undefined;
+        typeDetails?: Record<string, unknown> | undefined;
+    }>;
+    variants: {
+        name: string;
+        description: string;
+        render: (...args: unknown[]) => unknown;
+        code?: string | undefined;
+        figma?: string | undefined;
+    }[];
+    ai?: {
+        compositionPattern?: "compound" | "simple" | "controlled" | "wrapper" | undefined;
+        subComponents?: string[] | undefined;
+        requiredChildren?: string[] | undefined;
+        commonPatterns?: string[] | undefined;
+    } | undefined;
+    component?: any;
+    relations?: {
+        component: string;
+        relationship: "alternative" | "sibling" | "parent" | "child" | "composition" | "complementary" | "used-by";
+        note: string;
+    }[] | undefined;
+    contract?: {
+        propsSummary?: string[] | undefined;
+        a11yRules?: string[] | undefined;
+        bans?: {
+            pattern: string;
+            message: string;
+        }[] | undefined;
+        scenarioTags?: string[] | undefined;
+        performanceBudget?: number | undefined;
+    } | undefined;
+    _generated?: {
+        source: "storybook" | "manual" | "ai";
+        sourceFile?: string | undefined;
+        confidence?: number | undefined;
+        timestamp?: string | undefined;
+    } | undefined;
+}>;
+/**
+ * Config schema - validates required fields, passes through optional config objects.
+ * Type definitions are in types.ts - schema just ensures basic structure.
+ */
+declare const fragmentsConfigSchema: z.ZodObject<{
+    include: z.ZodArray<z.ZodString, "many">;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    components: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    outFile: z.ZodOptional<z.ZodString>;
+    framework: z.ZodOptional<z.ZodEnum<["react", "vue", "svelte"]>>;
+    figmaFile: z.ZodOptional<z.ZodString>;
+    figmaToken: z.ZodOptional<z.ZodString>;
+    screenshots: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+    service: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+    registry: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+    tokens: z.ZodOptional<z.ZodObject<{
+        include: z.ZodArray<z.ZodString, "many">;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        include: z.ZodArray<z.ZodString, "many">;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        include: z.ZodArray<z.ZodString, "many">;
+    }, z.ZodTypeAny, "passthrough">>>;
+    snippets: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<["warn", "error"]>>;
+        scope: z.ZodOptional<z.ZodEnum<["snippet", "snippet+render"]>>;
+        requireFullSnippet: z.ZodOptional<z.ZodBoolean>;
+        allowedExternalModules: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        mode?: "warn" | "error" | undefined;
+        scope?: "snippet" | "snippet+render" | undefined;
+        requireFullSnippet?: boolean | undefined;
+        allowedExternalModules?: string[] | undefined;
+    }, {
+        mode?: "warn" | "error" | undefined;
+        scope?: "snippet" | "snippet+render" | undefined;
+        requireFullSnippet?: boolean | undefined;
+        allowedExternalModules?: string[] | undefined;
+    }>>;
+    performance: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["strict", "standard", "relaxed"]>, z.ZodObject<{
+        preset: z.ZodOptional<z.ZodEnum<["strict", "standard", "relaxed"]>>;
+        budgets: z.ZodOptional<z.ZodObject<{
+            bundleSize: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            bundleSize?: number | undefined;
+        }, {
+            bundleSize?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        preset?: "strict" | "standard" | "relaxed" | undefined;
+        budgets?: {
+            bundleSize?: number | undefined;
+        } | undefined;
+    }, {
+        preset?: "strict" | "standard" | "relaxed" | undefined;
+        budgets?: {
+            bundleSize?: number | undefined;
+        } | undefined;
+    }>]>>;
+    storybook: z.ZodOptional<z.ZodObject<{
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        include: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        excludeDeprecated: z.ZodOptional<z.ZodBoolean>;
+        excludeTests: z.ZodOptional<z.ZodBoolean>;
+        excludeSvgIcons: z.ZodOptional<z.ZodBoolean>;
+        excludeSubComponents: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+        excludeDeprecated?: boolean | undefined;
+        excludeTests?: boolean | undefined;
+        excludeSvgIcons?: boolean | undefined;
+        excludeSubComponents?: boolean | undefined;
+    }, {
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+        excludeDeprecated?: boolean | undefined;
+        excludeTests?: boolean | undefined;
+        excludeSvgIcons?: boolean | undefined;
+        excludeSubComponents?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    include: string[];
+    components?: string[] | undefined;
+    screenshots?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    storybook?: {
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+        excludeDeprecated?: boolean | undefined;
+        excludeTests?: boolean | undefined;
+        excludeSvgIcons?: boolean | undefined;
+        excludeSubComponents?: boolean | undefined;
+    } | undefined;
+    exclude?: string[] | undefined;
+    outFile?: string | undefined;
+    framework?: "react" | "vue" | "svelte" | undefined;
+    figmaFile?: string | undefined;
+    figmaToken?: string | undefined;
+    service?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    registry?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    tokens?: z.objectOutputType<{
+        include: z.ZodArray<z.ZodString, "many">;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    snippets?: {
+        mode?: "warn" | "error" | undefined;
+        scope?: "snippet" | "snippet+render" | undefined;
+        requireFullSnippet?: boolean | undefined;
+        allowedExternalModules?: string[] | undefined;
+    } | undefined;
+    performance?: "strict" | "standard" | "relaxed" | {
+        preset?: "strict" | "standard" | "relaxed" | undefined;
+        budgets?: {
+            bundleSize?: number | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    include: string[];
+    components?: string[] | undefined;
+    screenshots?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    storybook?: {
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+        excludeDeprecated?: boolean | undefined;
+        excludeTests?: boolean | undefined;
+        excludeSvgIcons?: boolean | undefined;
+        excludeSubComponents?: boolean | undefined;
+    } | undefined;
+    exclude?: string[] | undefined;
+    outFile?: string | undefined;
+    framework?: "react" | "vue" | "svelte" | undefined;
+    figmaFile?: string | undefined;
+    figmaToken?: string | undefined;
+    service?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    registry?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    tokens?: z.objectInputType<{
+        include: z.ZodArray<z.ZodString, "many">;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    snippets?: {
+        mode?: "warn" | "error" | undefined;
+        scope?: "snippet" | "snippet+render" | undefined;
+        requireFullSnippet?: boolean | undefined;
+        allowedExternalModules?: string[] | undefined;
+    } | undefined;
+    performance?: "strict" | "standard" | "relaxed" | {
+        preset?: "strict" | "standard" | "relaxed" | undefined;
+        budgets?: {
+            bundleSize?: number | undefined;
+        } | undefined;
+    } | undefined;
+}>;
+/**
+ * @deprecated Use blockDefinitionSchema instead
+ */
+declare const recipeDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodString;
+    components: z.ZodArray<z.ZodString, "many">;
+    code: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    components: string[];
+    code: string;
+    name: string;
+    description: string;
+    category: string;
+    tags?: string[] | undefined;
+}, {
+    components: string[];
+    code: string;
+    name: string;
+    description: string;
+    category: string;
+    tags?: string[] | undefined;
+}>;
+
+/**
+ * Define a fragment for a component.
+ *
+ * This is the main API for creating fragment documentation.
+ * It provides runtime validation and type safety.
+ *
+ * @example
+ * ```tsx
+ * import { defineFragment } from '@fragments-sdk/cli/core';
+ * import { Button } from './Button';
+ *
+ * export default defineFragment({
+ *   component: Button,
+ *   meta: {
+ *     name: 'Button',
+ *     description: 'Primary action trigger',
+ *     category: 'actions',
+ *   },
+ *   usage: {
+ *     when: ['User needs to trigger an action'],
+ *     whenNot: ['Navigation without side effects'],
+ *   },
+ *   props: {
+ *     variant: {
+ *       type: 'enum',
+ *       values: ['primary', 'secondary'],
+ *       default: 'primary',
+ *       description: 'Visual style',
+ *     },
+ *   },
+ *   variants: [
+ *     {
+ *       name: 'Default',
+ *       description: 'Default button',
+ *       render: () => <Button>Click me</Button>,
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+declare function defineFragment<TProps>(definition: FragmentDefinition<TProps>): FragmentDefinition<TProps>;
+/**
+ * Compile a fragment definition to JSON-serializable format.
+ * Used for generating fragments.json for AI consumption.
+ */
+declare function compileFragment(definition: FragmentDefinition, filePath: string): CompiledFragment;
+/**
+ * Define a composition block.
+ *
+ * Blocks are pure data describing how design system components
+ * wire together for common use cases.
+ */
+declare function defineBlock(definition: BlockDefinition): BlockDefinition;
+/**
+ * @deprecated Use defineBlock instead
+ */
+declare const defineRecipe: typeof defineBlock;
+/**
+ * Compile a block definition to JSON-serializable format.
+ */
+declare function compileBlock(definition: BlockDefinition, filePath: string): CompiledBlock;
+/**
+ * @deprecated Use compileBlock instead
+ */
+declare const compileRecipe: typeof compileBlock;
+/**
+ * Type helper for extracting props type from a component
+ */
+type InferProps<T> = T extends FragmentComponent<infer P> ? P : never;
+
+declare const toId: typeof toId$1;
+declare const storyNameFromExport: typeof storyNameFromExport$1;
+declare const isExportStory: typeof isExportStory$1;
+
+/**
+ * Runtime adapter for converting Storybook CSF modules to Fragment definitions.
+ *
+ * This operates on IMPORTED modules at runtime, not source code parsing.
+ * By leveraging Vite's module system, we get 100% accurate render functions
+ * without any regex or AST parsing complexity.
+ *
+ * Supports Storybook 8.x with both CSF2 (Template.bind) and CSF3 (object stories).
+ */
+
+/**
+ * Storybook decorator function signature
+ */
+type Decorator = (Story: () => ReactNode, context: StoryContext) => ReactNode;
+/**
+ * Storybook loader function signature
+ */
+type Loader = (context: StoryContext) => Promise<Record<string, unknown>>;
+/**
+ * Storybook play function signature (internal, extends StoryContext)
+ */
+type StorybookPlayFunction = (context: StorybookPlayFunctionContext) => Promise<void>;
+/**
+ * Context passed to Storybook play functions (extends StoryContext for compatibility)
+ */
+interface StorybookPlayFunctionContext extends StoryContext {
+    canvasElement: HTMLElement;
+    step: (name: string, fn: () => Promise<void>) => Promise<void>;
+}
+/**
+ * Context passed to decorators and render functions
+ */
+interface StoryContext {
+    args: Record<string, unknown>;
+    argTypes: Record<string, StoryArgType>;
+    globals: Record<string, unknown>;
+    parameters: Record<string, unknown>;
+    id: string;
+    kind: string;
+    name: string;
+    story: string;
+    viewMode: "story" | "docs";
+    loaded: Record<string, unknown>;
+    abortSignal: AbortSignal;
+    componentId: string;
+    title: string;
+}
+/**
+ * Storybook Meta (default export)
+ */
+interface StoryMeta {
+    title?: string;
+    component?: ComponentType<unknown>;
+    subcomponents?: Record<string, ComponentType<unknown>>;
+    tags?: string[];
+    parameters?: Record<string, unknown> & {
+        docs?: {
+            description?: {
+                component?: string;
+            };
+        };
+    };
+    argTypes?: Record<string, StoryArgType>;
+    args?: Record<string, unknown>;
+    decorators?: Decorator[];
+    loaders?: Loader[];
+    render?: (args: Record<string, unknown>, context?: StoryContext) => ReactNode;
+    includeStories?: string[] | RegExp;
+    excludeStories?: string[] | RegExp;
+}
+/**
+ * Storybook argType definition
+ */
+interface StoryArgType {
+    control?: string | false | {
+        type: string;
+        min?: number;
+        max?: number;
+        step?: number;
+        presetColors?: string[];
+    };
+    options?: string[];
+    description?: string;
+    table?: {
+        defaultValue?: {
+            summary: string;
+        };
+        type?: {
+            summary: string;
+        };
+        category?: string;
+        subcategory?: string;
+        disable?: boolean;
+    };
+    type?: {
+        name: string;
+        required?: boolean;
+    };
+    name?: string;
+    defaultValue?: unknown;
+    if?: {
+        arg?: string;
+        exists?: boolean;
+    };
+    mapping?: Record<string, unknown>;
+    action?: string;
+}
+/**
+ * Storybook Story export (CSF3)
+ */
+interface Story {
+    args?: Record<string, unknown>;
+    argTypes?: Record<string, StoryArgType>;
+    render?: (args: Record<string, unknown>, context?: StoryContext) => ReactNode;
+    decorators?: Decorator[];
+    loaders?: Loader[];
+    play?: StorybookPlayFunction;
+    parameters?: Record<string, unknown> & {
+        docs?: {
+            description?: {
+                story?: string;
+            };
+        };
+    };
+    name?: string;
+    storyName?: string;
+    tags?: string[];
+}
+/**
+ * CSF2 story function (from Template.bind({})) with args attached
+ */
+type CSF2Story = ((args: Record<string, unknown>) => ReactNode) & {
+    args?: Record<string, unknown>;
+    argTypes?: Record<string, StoryArgType>;
+    decorators?: Decorator[];
+    loaders?: Loader[];
+    play?: StorybookPlayFunction;
+    parameters?: Record<string, unknown>;
+    storyName?: string;
+};
+/**
+ * A complete Storybook module with default meta and named story exports
+ */
+interface StoryModule {
+    default: StoryMeta;
+    [exportName: string]: Story | CSF2Story | StoryMeta | unknown;
+}
+/**
+ * Global configuration from preview.tsx
+ */
+interface PreviewConfig {
+    decorators?: Decorator[];
+    parameters?: Record<string, unknown>;
+    globalTypes?: Record<string, unknown>;
+    args?: Record<string, unknown>;
+    argTypes?: Record<string, StoryArgType>;
+    loaders?: Loader[];
+}
+/**
+ * Set the global preview configuration loaded from .storybook/preview.tsx
+ */
+declare function setPreviewConfig(config: PreviewConfig): void;
+/**
+ * Get the current global preview configuration
+ */
+declare function getPreviewConfig(): PreviewConfig;
+/**
+ * Convert a Storybook module to a Fragment definition at runtime.
+ *
+ * @param storyModule - The imported Storybook module
+ * @param filePath - File path for metadata extraction
+ * @returns A complete FragmentDefinition ready for the viewer
+ */
+declare function storyModuleToFragment(storyModule: StoryModule, filePath: string): FragmentDefinition | null;
+
+/**
+ * Smart filtering for Storybook adapter.
+ *
+ * Two layers:
+ * 1. Per-file heuristics — checkStoryExclusion() checks title, tags, component name, etc.
+ * 2. Cross-file sub-component detection — detectSubComponentPaths() uses directory structure.
+ *
+ * All functions are pure (no I/O, no side effects) for easy testing.
+ */
+
+type ExclusionReason = 'deprecated' | 'test-story' | 'svg-icon' | 'tag-excluded' | 'empty-variants' | 'sub-component' | 'config-excluded';
+interface ExclusionResult {
+    excluded: boolean;
+    reason?: ExclusionReason;
+    detail?: string;
+}
+interface CheckStoryExclusionOpts {
+    storybookTitle?: string;
+    componentName: string;
+    componentDisplayName?: string;
+    componentFunctionName?: string;
+    tags?: string[];
+    variantCount: number;
+    filePath: string;
+    config: StorybookFilterConfig;
+}
+/**
+ * Per-file exclusion check. Returns `{ excluded: true, reason, detail }` when
+ * the fragment should be filtered out, or `{ excluded: false }` when it should
+ * be kept.
+ *
+ * Config `include` trumps everything — if a name matches `include`, it is
+ * never excluded by heuristics.
+ */
+declare function checkStoryExclusion(opts: CheckStoryExclusionOpts): ExclusionResult;
+/**
+ * Given all story file relative paths, detect which ones are sub-components
+ * based on directory structure.
+ *
+ * Heuristic: within a directory, if one story file's base name matches the
+ * directory name, it is the "primary" component. All other story files in
+ * the same directory are considered sub-components.
+ *
+ * Example:
+ *   src/components/Form/Form.stories.tsx        → primary ("Form")
+ *   src/components/Form/Checkbox.stories.tsx     → sub-component of "Form"
+ *   src/components/Form/RadioGroup.stories.tsx   → sub-component of "Form"
+ *
+ * Returns a Map from relative path → parent component name.
+ * Paths NOT in the map are standalone components.
+ */
+declare function detectSubComponentPaths(storyFiles: Array<{
+    relativePath: string;
+}>): Map<string, string>;
+/**
+ * Check if a component name matches the `storybook.include` patterns.
+ * Include is a force-include that bypasses all heuristic filters.
+ */
+declare function isForceIncluded(name: string, config: StorybookFilterConfig): boolean;
+/**
+ * Check if a component name matches the `storybook.exclude` patterns.
+ */
+declare function isConfigExcluded(name: string, config: StorybookFilterConfig): boolean;
+
+/**
+ * Figma property mapping DSL
+ *
+ * Provides helpers for mapping Figma component properties to code props.
+ * Inspired by Figma Code Connect's API.
+ *
+ * @example
+ * ```tsx
+ * import { defineFragment, figma } from '@fragments-sdk/cli/core';
+ *
+ * export default defineFragment({
+ *   component: Button,
+ *   meta: {
+ *     name: 'Button',
+ *     description: 'Primary action trigger',
+ *     category: 'actions',
+ *     figma: 'https://figma.com/file/abc/Design?node-id=1-2',
+ *     figmaProps: {
+ *       children: figma.string('Label'),
+ *       disabled: figma.boolean('Disabled'),
+ *       variant: figma.enum('Type', {
+ *         'Primary': 'primary',
+ *         'Secondary': 'secondary',
+ *       }),
+ *     },
+ *   },
+ *   // ...
+ * });
+ * ```
+ */
+
+/**
+ * Map a Figma text property to a string prop.
+ *
+ * @param figmaProperty - The name of the text property in Figma
+ * @returns A string mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   label: figma.string('Button Text'),
+ *   placeholder: figma.string('Placeholder'),
+ * }
+ * ```
+ */
+declare function string(figmaProperty: string): FigmaStringMapping;
+/**
+ * Map a Figma boolean property to a boolean prop.
+ * Optionally map true/false to different values.
+ *
+ * @param figmaProperty - The name of the boolean property in Figma
+ * @param valueMapping - Optional mapping of true/false to other values
+ * @returns A boolean mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   disabled: figma.boolean('Disabled'),
+ *   // Map boolean to string values
+ *   size: figma.boolean('Large', { true: 'lg', false: 'md' }),
+ * }
+ * ```
+ */
+declare function boolean(figmaProperty: string, valueMapping?: {
+    true: unknown;
+    false: unknown;
+}): FigmaBooleanMapping;
+/**
+ * Map a Figma variant property to an enum prop.
+ *
+ * @param figmaProperty - The name of the variant property in Figma
+ * @param valueMapping - Mapping of Figma values to code values
+ * @returns An enum mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   variant: figma.enum('Type', {
+ *     'Primary': 'primary',
+ *     'Secondary': 'secondary',
+ *     'Outline': 'outline',
+ *   }),
+ *   size: figma.enum('Size', {
+ *     'Small': 'sm',
+ *     'Medium': 'md',
+ *     'Large': 'lg',
+ *   }),
+ * }
+ * ```
+ */
+declare function enumValue<T extends Record<string, unknown>>(figmaProperty: string, valueMapping: T): FigmaEnumMapping;
+/**
+ * Reference a nested Figma component instance.
+ * Use this when a prop accepts a component that's represented
+ * as an instance swap in Figma.
+ *
+ * @param figmaProperty - The name of the instance property in Figma
+ * @returns An instance mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   icon: figma.instance('Icon'),
+ *   avatar: figma.instance('Avatar'),
+ * }
+ * ```
+ */
+declare function instance(figmaProperty: string): FigmaInstanceMapping;
+/**
+ * Render children from specific Figma layers.
+ * Use this when children are represented as named layers in Figma.
+ *
+ * @param layers - Array of layer names to include as children
+ * @returns A children mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   children: figma.children(['Title', 'Description', 'Actions']),
+ * }
+ * ```
+ */
+declare function children(layers: string[]): FigmaChildrenMapping;
+/**
+ * Extract text content from a Figma text layer.
+ * Use this when a prop should be the actual text from a layer.
+ *
+ * @param layer - The name of the text layer in Figma
+ * @returns A text content mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   title: figma.textContent('Header Text'),
+ *   description: figma.textContent('Body Text'),
+ * }
+ * ```
+ */
+declare function textContent(layer: string): FigmaTextContentMapping;
+/**
+ * Figma property mapping helpers.
+ *
+ * Use these to define how Figma properties map to your component props.
+ * The mappings are used for:
+ * - Generating accurate code snippets in Figma Dev Mode
+ * - AI agents understanding the design-to-code relationship
+ * - Automated design verification
+ */
+declare const figma: {
+    readonly string: typeof string;
+    readonly boolean: typeof boolean;
+    readonly enum: typeof enumValue;
+    readonly instance: typeof instance;
+    readonly children: typeof children;
+    readonly textContent: typeof textContent;
+};
+/**
+ * Helper type to check if a value is a Figma prop mapping
+ */
+declare function isFigmaPropMapping(value: unknown): value is FigmaStringMapping | FigmaBooleanMapping | FigmaEnumMapping | FigmaInstanceMapping | FigmaChildrenMapping | FigmaTextContentMapping;
+/**
+ * Resolve a Figma prop mapping to an actual value given Figma property values.
+ *
+ * @param mapping - The Figma prop mapping
+ * @param figmaValues - Object containing Figma property values
+ * @returns The resolved value for the code prop
+ */
+declare function resolveFigmaMapping(mapping: FigmaStringMapping | FigmaBooleanMapping | FigmaEnumMapping | FigmaInstanceMapping | FigmaChildrenMapping | FigmaTextContentMapping, figmaValues: Record<string, unknown>): unknown;
+
+/**
+ * TypeScript types for Fragment JSON files.
+ * These types correspond to the JSON schemas in ./schema/
+ */
+/**
+ * Figma design links and mappings
+ */
+interface FragmentFigma {
+    /** Figma file URL */
+    file?: string;
+    /** Default Figma node ID for this component */
+    nodeId?: string;
+    /** Mapping of variant names to Figma node IDs */
+    variants?: Record<string, string>;
+}
+/**
+ * Anti-pattern with optional alternative
+ */
+interface FragmentDoNotItem {
+    /** What not to do */
+    text: string;
+    /** Component name to use instead */
+    instead?: string;
+}
+/**
+ * Usage pattern with code example
+ */
+interface FragmentPattern {
+    /** Pattern name */
+    name: string;
+    /** Code example */
+    code: string;
+    /** When to use this pattern */
+    description?: string;
+}
+/**
+ * Usage guidelines for AI agents and developers
+ */
+interface FragmentUsage {
+    /** Scenarios when this component should be used */
+    when?: string[];
+    /** Anti-patterns and what to use instead */
+    doNot?: (string | FragmentDoNotItem)[];
+    /** Common usage patterns with code examples */
+    patterns?: FragmentPattern[];
+}
+/**
+ * Accessibility requirements and guidelines
+ */
+interface FragmentAccessibility {
+    /** ARIA role this component implements */
+    role?: string;
+    /** Accessibility requirements */
+    requirements?: string[];
+    /** Keyboard interaction patterns (key -> description) */
+    keyboard?: Record<string, string>;
+}
+/**
+ * Relationships to other components
+ */
+interface FragmentRelated {
+    /** Similar components that might be alternatives */
+    similar?: string[];
+    /** Components commonly used together with this one */
+    composedWith?: string[];
+    /** Parent components or patterns where this is commonly used */
+    usedIn?: string[];
+}
+/**
+ * Administrative metadata
+ */
+interface FragmentMeta {
+    /** Team or person responsible for this component */
+    owner?: string;
+    /** Component lifecycle status */
+    status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
+    /** Version when this component was introduced */
+    since?: string;
+    /** Version when this component was deprecated */
+    deprecatedSince?: string;
+    /** Why this component was deprecated and what to use instead */
+    deprecatedReason?: string;
+    /** Tags for categorization and search */
+    tags?: string[];
+}
+/**
+ * Fragment JSON file structure (.fragment.json)
+ * Contains enrichment metadata for a component
+ */
+interface Fragment {
+    /** JSON Schema reference */
+    $schema?: string;
+    /** Component name (must match the component export name) */
+    name: string;
+    /** Brief description of the component's purpose */
+    description?: string;
+    /** Figma design links and mappings */
+    figma?: FragmentFigma;
+    /** Usage guidelines for AI agents and developers */
+    usage?: FragmentUsage;
+    /** Accessibility requirements and guidelines */
+    accessibility?: FragmentAccessibility;
+    /** Relationships to other components */
+    related?: FragmentRelated;
+    /** Administrative metadata */
+    meta?: FragmentMeta;
+}
+/**
+ * Prop entry in the registry
+ */
+interface RegistryPropEntry {
+    /** TypeScript type (e.g., 'string', 'boolean', enum values) */
+    type?: string;
+    /** Simplified type category */
+    typeKind?: "string" | "number" | "boolean" | "enum" | "object" | "array" | "function" | "node" | "element" | "union" | "unknown";
+    /** For enum types, the allowed values */
+    options?: string[];
+    /** Default value if specified */
+    default?: unknown;
+    /** Whether this prop is required */
+    required?: boolean;
+    /** Prop description from JSDoc or TypeScript */
+    description?: string;
+}
+/**
+ * Component entry in the registry (simplified - focuses on paths and enrichment)
+ */
+interface RegistryComponentEntry {
+    /** Relative path to the component source file */
+    path: string;
+    /** Relative path to the .fragment.json file (if exists) */
+    fragmentPath?: string;
+    /** Relative path to the .stories.tsx file (if exists) */
+    storyPath?: string;
+    /** Component category (inferred from directory or fragment) */
+    category?: string;
+    /** Component lifecycle status (from fragment) */
+    status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
+    /** Component description (from fragment or JSDoc) */
+    description?: string;
+    /** Has human-authored enrichment (fragment file exists with content beyond skeleton) */
+    hasEnrichment?: boolean;
+    /** Extracted prop definitions - only included if config.registry.includeProps is true */
+    props?: Record<string, RegistryPropEntry>;
+    /** Named exports from the component file */
+    exports?: string[];
+    /** Component dependencies (other components used) */
+    dependencies?: string[];
+    /** Merged fragment enrichment data - only included if config.registry.embedFragments is true */
+    fragment?: Fragment;
+}
+/**
+ * Minimal component index (.fragments/index.json)
+ * Ultra-light name → path mapping for quick lookups
+ */
+interface FragmentIndex {
+    /** Schema version */
+    version: string;
+    /** When this index was generated */
+    generatedAt: string;
+    /** Simple name → path mapping */
+    components: Record<string, string>;
+    /** Categories for grouping */
+    categories?: Record<string, string[]>;
+}
+/**
+ * Registry file structure (.fragments/registry.json)
+ * Component index with resolved paths and optional metadata
+ */
+interface FragmentRegistry {
+    /** JSON Schema reference */
+    $schema?: string;
+    /** Schema version */
+    version: string;
+    /** When this registry was generated */
+    generatedAt: string;
+    /** Component count for quick reference */
+    componentCount: number;
+    /** Component index keyed by component name */
+    components: Record<string, RegistryComponentEntry>;
+    /** Components grouped by category */
+    categories?: Record<string, string[]>;
+}
+/**
+ * Context file options for generation
+ */
+interface FragmentContextOptions {
+    /** Output format */
+    format?: "markdown" | "json";
+    /** Compact mode - minimal output for token efficiency */
+    compact?: boolean;
+    /** What to include in the output */
+    include?: {
+        /** Include prop details (default: true) */
+        props?: boolean;
+        /** Include code examples (default: false) */
+        code?: boolean;
+        /** Include related components (default: true) */
+        relations?: boolean;
+    };
+}
+
+/**
+ * Token Parser — extracts CSS custom property declarations from SCSS/CSS files.
+ *
+ * Parses files for `--prefix-*: value;` declarations and groups them
+ * by SCSS comment sections (e.g., `// Typography`, `// Colors`).
+ * Falls back to naming-convention-based categorization when comments
+ * are absent.
+ */
+interface ParsedToken {
+    /** Full CSS variable name (e.g., "--fui-color-accent") */
+    name: string;
+    /** Raw value from the declaration (e.g., "#{$fui-space-4}" or "16px") */
+    value?: string;
+    /** Resolved value after SCSS variable substitution (e.g., "16px") */
+    resolvedValue?: string;
+    /** Category inferred from SCSS comment or naming convention */
+    category: string;
+    /** Description from inline comment, if any */
+    description?: string;
+}
+interface TokenParseOutput {
+    /** Detected prefix (e.g., "--fui-") */
+    prefix: string;
+    /** Tokens grouped by category */
+    categories: Record<string, ParsedToken[]>;
+    /** Total number of tokens found */
+    total: number;
+}
+/**
+ * Parse a SCSS or CSS file and extract CSS custom property declarations.
+ *
+ * Handles two grouping strategies:
+ * 1. Comment-based: Uses `// Category` comments above groups of declarations
+ * 2. Naming-based: Falls back to inferring category from variable name patterns
+ *
+ * Also resolves SCSS variable interpolations (e.g., `#{$fui-space-4}` → `16px`)
+ * when the SCSS variable definitions are found in the same file content.
+ */
+declare function parseTokenFile(content: string, filePath: string): TokenParseOutput;
+
+interface CompositionWarning {
+    type: "missing_parent" | "missing_child" | "missing_composition" | "redundant_alternative" | "deprecated" | "experimental";
+    component: string;
+    message: string;
+    relatedComponent?: string;
+}
+interface CompositionSuggestion {
+    component: string;
+    reason: string;
+    relationship: RelationshipType | "category_gap";
+    sourceComponent: string;
+}
+interface CompositionGuideline {
+    component: string;
+    guideline: string;
+}
+interface CompositionAnalysis {
+    /** The validated component names (filtered to those that exist) */
+    components: string[];
+    /** Components requested but not found in the registry */
+    unknown: string[];
+    /** Issues with the current selection */
+    warnings: CompositionWarning[];
+    /** Components to consider adding */
+    suggestions: CompositionSuggestion[];
+    /** Relevant usage guidelines for the selected components */
+    guidelines: CompositionGuideline[];
+}
+/**
+ * Analyzes a set of components as a composition group.
+ * Returns warnings about missing relations, usage conflicts,
+ * and suggestions for additional components.
+ *
+ * When a ComponentGraph is provided via `options.graph`, the analysis is
+ * enhanced with graph-based dependency detection and block-based suggestions.
+ *
+ * Browser-safe: no Node.js APIs used.
+ */
+declare function analyzeComposition(fragments: Record<string, CompiledFragment>, componentNames: string[], _context?: string, options?: {
+    graph?: ComponentGraph;
+}): CompositionAnalysis;
+
+/**
+ * Minimal contract for rendering a preview variant.
+ * Compatible with fragment variants and Storybook-adapted variants.
+ */
+interface PreviewVariantLike {
+    render: (options?: VariantRenderOptions) => ReactNode;
+    loaders?: VariantLoader[];
+}
+interface PreviewRuntimeState {
+    content: ReactNode | null;
+    isLoading: boolean;
+    error: Error | null;
+    loadedData?: Record<string, unknown>;
+}
+interface PreviewRuntimeOptions {
+    variant?: PreviewVariantLike | null;
+    loadedData?: Record<string, unknown>;
+}
+/**
+ * Execute all variant loaders and merge their payloads.
+ * `loadedData` is applied last so host-level overrides win.
+ */
+declare function executeVariantLoaders(loaders: VariantLoader[] | undefined, loadedData?: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+/**
+ * Resolve a full runtime state (loader execution + render) in one async call.
+ * This is useful for testing and for hook/component orchestration.
+ */
+declare function resolvePreviewRuntimeState(options: PreviewRuntimeOptions): Promise<PreviewRuntimeState>;
+/**
+ * Hook for rendering a preview variant with loader support.
+ */
+declare function usePreviewVariantRuntime(options: PreviewRuntimeOptions): PreviewRuntimeState;
+interface PreviewVariantRuntimeProps extends PreviewRuntimeOptions {
+    children: (state: PreviewRuntimeState) => ReactNode;
+}
+/**
+ * Render-prop component wrapper around `usePreviewVariantRuntime`.
+ */
+declare function PreviewVariantRuntime({ variant, loadedData, children, }: PreviewVariantRuntimeProps): react_jsx_runtime.JSX.Element;
+
+export { type AIMetadata, BRAND, type BaselineInfo, type BlockDefinition, type BoundingBox, type Brand, type CSF2Story, type CheckStoryExclusionOpts, type CompiledRecipe, type ComplexityTier, type ComponentRelation, type CompositionAnalysis, type CompositionGuideline, type CompositionSuggestion, type CompositionWarning, type ControlType, DEFAULTS, type Decorator, type Defaults, type DesignToken, type DiffResult, type EnhancedStyleDiffItem, type ExclusionReason, type ExclusionResult, type FigmaBooleanMapping, type FigmaChildrenMapping, type FigmaEnumMapping, type FigmaInstanceMapping, type FigmaPropMapping, type FigmaStringMapping, type FigmaTextContentMapping, type Fragment, type FragmentAccessibility, type FragmentComponent, type FragmentContextOptions, type FragmentContract, type FragmentDefinition, type FragmentDoNotItem, type FragmentFigma, type FragmentGenerated, type FragmentIndex, type FragmentMeta as FragmentJsonMeta, type FragmentUsage as FragmentJsonUsage, type FragmentMeta$1 as FragmentMeta, type FragmentPattern, type FragmentRegistry, type FragmentRelated, type FragmentUsage$1 as FragmentUsage, type FragmentVariant, type FragmentsConfig, type InferProps, type Loader, type Manifest, PRESET_NAMES, type ParsedToken, type PerformanceData as PerfData, type PerformanceSummary as PerfSummary, type PerformanceBudgets, type PerformanceConfig, type PlayFunction, type PlayFunctionContext, type PreviewConfig, type PreviewRuntimeOptions, type PreviewRuntimeState, type PreviewVariantLike, PreviewVariantRuntime, type PropDefinition, type PropType, type RecipeDefinition, type RegistryComponentEntry, type RegistryOptions, type RegistryPropEntry, type RelationshipType, type Screenshot, type ScreenshotConfig, type ScreenshotMetadata, type ServiceConfig, type SnippetPolicyConfig, type Story, type StoryArgType, type StoryContext, type StoryMeta, type StoryModule, type StorybookFilterConfig, type Theme, type TokenCategory, type TokenConfig, type TokenFix, type TokenMatchRequest, type TokenMatchResult, type TokenParseError, type TokenParseOutput, type TokenParseResult, type TokenRegistry, type TokenRegistryMeta, type TokenUsageSummary, type VariantLoader, type VerifyRequest, type VerifyResult, type Viewport, aiMetadataSchema, analyzeComposition, blockDefinitionSchema, budgetBar, checkStoryExclusion, classifyComplexity, compileBlock, compileFragment, compileRecipe, componentRelationSchema, defineBlock, defineFragment, defineRecipe, detectSubComponentPaths, executeVariantLoaders, figma, figmaPropMappingSchema, formatBytes, fragmentBanSchema, fragmentContractSchema, fragmentDefinitionSchema, fragmentGeneratedSchema, fragmentMetaSchema, fragmentUsageSchema, fragmentVariantSchema, fragmentsConfigSchema, getPreviewConfig, isConfigExcluded, isExportStory, isFigmaPropMapping, isForceIncluded, parseTokenFile, propDefinitionSchema, recipeDefinitionSchema, resolveFigmaMapping, resolvePerformanceConfig, resolvePreviewRuntimeState, setPreviewConfig, storyModuleToFragment, storyNameFromExport, toId, usePreviewVariantRuntime };