@fragments-sdk/cli 0.7.9 → 0.7.10

package/dist/core/index.d.ts

@@ -0,0 +1,1944 @@
+import { b as FragmentDefinition, c as FigmaStringMapping, e as FigmaBooleanMapping, f as FigmaEnumMapping, g as FigmaInstanceMapping, h as FigmaChildrenMapping, i as FigmaTextContentMapping, R as RelationshipType } from '../defineFragment-C6PFzZyo.js';
+export { A as AIMetadata, H as BaselineInfo, B as BlockDefinition, G as BoundingBox, t as CompiledRecipe, n as ComponentRelation, C as ControlType, D as DiffResult, K as FigmaPropMapping, j as FragmentComponent, u as FragmentContract, v as FragmentGenerated, k as FragmentMeta, l as FragmentUsage, q as FragmentVariant, F as FragmentsConfig, W as InferProps, M as Manifest, o as PlayFunction, p as PlayFunctionContext, m as PropDefinition, P as PropType, s as RecipeDefinition, r as RegistryOptions, z as Screenshot, w as ScreenshotConfig, E as ScreenshotMetadata, x as ServiceConfig, S as SnippetPolicyConfig, T as Theme, L as TokenConfig, V as VariantLoader, I as VerifyRequest, J as VerifyResult, y as Viewport, O as compileBlock, N as compileFragment, U as compileRecipe, a as defineBlock, d as defineFragment, Q as defineRecipe } from '../defineFragment-C6PFzZyo.js';
+import { z } from 'zod';
+import { ComponentType, ReactNode } from 'react';
+export { ContextOptions, ContextResult, generateContext } from '@fragments-sdk/context/generate';
+import { ComponentGraph } from '@fragments-sdk/context/graph';
+import { CompiledFragment } from '@fragments-sdk/context/types';
+export { CompiledBlock, CompiledFragment, CompiledFragmentsFile, CompiledTokenData, CompiledTokenEntry } from '@fragments-sdk/context/types';
+import { toId as toId$1, storyNameFromExport as storyNameFromExport$1, isExportStory as isExportStory$1 } from '@storybook/csf';
+
+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;
+
+/**
+ * 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;
+    };
+}
+
+/**
+ * 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;
+
+/**
+ * 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;
+    category: string;
+    description: string;
+    figma?: string | undefined;
+    tags?: string[] | undefined;
+    status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+    since?: string | undefined;
+    dependencies?: {
+        name: string;
+        version: string;
+        reason?: string | undefined;
+    }[] | 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;
+    category: string;
+    description: string;
+    figma?: string | undefined;
+    tags?: string[] | undefined;
+    status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+    since?: string | undefined;
+    dependencies?: {
+        name: string;
+        version: string;
+        reason?: string | undefined;
+    }[] | 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;
+    default?: unknown;
+    values?: readonly string[] | undefined;
+    description?: string | undefined;
+    required?: boolean | undefined;
+    constraints?: string[] | undefined;
+    typeDetails?: Record<string, unknown> | undefined;
+}, {
+    type: string;
+    default?: unknown;
+    values?: readonly string[] | undefined;
+    description?: string | undefined;
+    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;
+    figma?: string | undefined;
+    code?: string | undefined;
+}, {
+    name: string;
+    description: string;
+    render: (...args: unknown[]) => unknown;
+    figma?: string | undefined;
+    code?: 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">>;
+}, "strip", z.ZodTypeAny, {
+    propsSummary?: string[] | undefined;
+    a11yRules?: string[] | undefined;
+    bans?: {
+        pattern: string;
+        message: string;
+    }[] | undefined;
+    scenarioTags?: string[] | undefined;
+}, {
+    propsSummary?: string[] | undefined;
+    a11yRules?: string[] | undefined;
+    bans?: {
+        pattern: string;
+        message: string;
+    }[] | undefined;
+    scenarioTags?: string[] | 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: "ai" | "storybook" | "manual";
+    sourceFile?: string | undefined;
+    confidence?: number | undefined;
+    timestamp?: string | undefined;
+}, {
+    source: "ai" | "storybook" | "manual";
+    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[];
+    name: string;
+    category: string;
+    code: string;
+    description: string;
+    tags?: string[] | undefined;
+}, {
+    components: string[];
+    name: string;
+    category: string;
+    code: string;
+    description: 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;
+        category: string;
+        description: string;
+        figma?: string | undefined;
+        tags?: string[] | undefined;
+        status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+        since?: string | undefined;
+        dependencies?: {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }[] | 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;
+        category: string;
+        description: string;
+        figma?: string | undefined;
+        tags?: string[] | undefined;
+        status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+        since?: string | undefined;
+        dependencies?: {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }[] | 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;
+        default?: unknown;
+        values?: readonly string[] | undefined;
+        description?: string | undefined;
+        required?: boolean | undefined;
+        constraints?: string[] | undefined;
+        typeDetails?: Record<string, unknown> | undefined;
+    }, {
+        type: string;
+        default?: unknown;
+        values?: readonly string[] | undefined;
+        description?: string | undefined;
+        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;
+        figma?: string | undefined;
+        code?: string | undefined;
+    }, {
+        name: string;
+        description: string;
+        render: (...args: unknown[]) => unknown;
+        figma?: string | undefined;
+        code?: 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">>;
+    }, "strip", z.ZodTypeAny, {
+        propsSummary?: string[] | undefined;
+        a11yRules?: string[] | undefined;
+        bans?: {
+            pattern: string;
+            message: string;
+        }[] | undefined;
+        scenarioTags?: string[] | undefined;
+    }, {
+        propsSummary?: string[] | undefined;
+        a11yRules?: string[] | undefined;
+        bans?: {
+            pattern: string;
+            message: string;
+        }[] | undefined;
+        scenarioTags?: string[] | 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: "ai" | "storybook" | "manual";
+        sourceFile?: string | undefined;
+        confidence?: number | undefined;
+        timestamp?: string | undefined;
+    }, {
+        source: "ai" | "storybook" | "manual";
+        sourceFile?: string | undefined;
+        confidence?: number | undefined;
+        timestamp?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    variants: {
+        name: string;
+        description: string;
+        render: (...args: unknown[]) => unknown;
+        figma?: string | undefined;
+        code?: string | undefined;
+    }[];
+    meta: {
+        name: string;
+        category: string;
+        description: string;
+        figma?: string | undefined;
+        tags?: string[] | undefined;
+        status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+        since?: string | undefined;
+        dependencies?: {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }[] | 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;
+        default?: unknown;
+        values?: readonly string[] | undefined;
+        description?: string | undefined;
+        required?: boolean | undefined;
+        constraints?: string[] | undefined;
+        typeDetails?: Record<string, unknown> | 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;
+    } | undefined;
+    _generated?: {
+        source: "ai" | "storybook" | "manual";
+        sourceFile?: string | undefined;
+        confidence?: number | undefined;
+        timestamp?: string | undefined;
+    } | undefined;
+}, {
+    variants: {
+        name: string;
+        description: string;
+        render: (...args: unknown[]) => unknown;
+        figma?: string | undefined;
+        code?: string | undefined;
+    }[];
+    meta: {
+        name: string;
+        category: string;
+        description: string;
+        figma?: string | undefined;
+        tags?: string[] | undefined;
+        status?: "stable" | "beta" | "deprecated" | "experimental" | undefined;
+        since?: string | undefined;
+        dependencies?: {
+            name: string;
+            version: string;
+            reason?: string | undefined;
+        }[] | 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;
+        default?: unknown;
+        values?: readonly string[] | undefined;
+        description?: string | undefined;
+        required?: boolean | undefined;
+        constraints?: string[] | undefined;
+        typeDetails?: Record<string, unknown> | 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;
+    } | undefined;
+    _generated?: {
+        source: "ai" | "storybook" | "manual";
+        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;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    include: string[];
+    components?: string[] | undefined;
+    screenshots?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    tokens?: z.objectOutputType<{
+        include: z.ZodArray<z.ZodString, "many">;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    registry?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | 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;
+    snippets?: {
+        mode?: "warn" | "error" | undefined;
+        scope?: "snippet" | "snippet+render" | undefined;
+        requireFullSnippet?: boolean | undefined;
+        allowedExternalModules?: string[] | undefined;
+    } | undefined;
+}, {
+    include: string[];
+    components?: string[] | undefined;
+    screenshots?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    tokens?: z.objectInputType<{
+        include: z.ZodArray<z.ZodString, "many">;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    registry?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | 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;
+    snippets?: {
+        mode?: "warn" | "error" | undefined;
+        scope?: "snippet" | "snippet+render" | undefined;
+        requireFullSnippet?: boolean | undefined;
+        allowedExternalModules?: string[] | 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[];
+    name: string;
+    category: string;
+    code: string;
+    description: string;
+    tags?: string[] | undefined;
+}, {
+    components: string[];
+    name: string;
+    category: string;
+    code: string;
+    description: string;
+    tags?: string[] | undefined;
+}>;
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+export { BRAND, type Brand, type CSF2Story, type CompositionAnalysis, type CompositionGuideline, type CompositionSuggestion, type CompositionWarning, DEFAULTS, type Decorator, type Defaults, type DesignToken, type EnhancedStyleDiffItem, FigmaBooleanMapping, FigmaChildrenMapping, FigmaEnumMapping, FigmaInstanceMapping, FigmaStringMapping, FigmaTextContentMapping, type Fragment, type FragmentAccessibility, type FragmentContextOptions, FragmentDefinition, type FragmentDoNotItem, type FragmentFigma, type FragmentIndex, type FragmentMeta as FragmentJsonMeta, type FragmentUsage as FragmentJsonUsage, type FragmentPattern, type FragmentRegistry, type FragmentRelated, type Loader, type ParsedToken, type PreviewConfig, type RegistryComponentEntry, type RegistryPropEntry, RelationshipType, type Story, type StoryArgType, type StoryContext, type StoryMeta, type StoryModule, type TokenCategory, type TokenFix, type TokenMatchRequest, type TokenMatchResult, type TokenParseError, type TokenParseOutput, type TokenParseResult, type TokenRegistry, type TokenRegistryMeta, type TokenUsageSummary, aiMetadataSchema, analyzeComposition, blockDefinitionSchema, componentRelationSchema, figma, figmaPropMappingSchema, fragmentBanSchema, fragmentContractSchema, fragmentDefinitionSchema, fragmentGeneratedSchema, fragmentMetaSchema, fragmentUsageSchema, fragmentVariantSchema, fragmentsConfigSchema, getPreviewConfig, isExportStory, isFigmaPropMapping, parseTokenFile, propDefinitionSchema, recipeDefinitionSchema, resolveFigmaMapping, setPreviewConfig, storyModuleToFragment, storyNameFromExport, toId };