@fragments-sdk/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1431 @@
+// src/constants.ts
+var BRAND = {
+  /** Display name (e.g., "Fragments") */
+  name: "Fragments",
+  /** Lowercase name for file paths and CLI (e.g., "fragments") */
+  nameLower: "fragments",
+  /** File extension for fragment definition files (e.g., ".fragment.tsx") */
+  fileExtension: ".fragment.tsx",
+  /** Legacy file extension for segments (still supported for migration) */
+  legacyFileExtension: ".segment.tsx",
+  /** JSON file extension for compiled output */
+  jsonExtension: ".fragment.json",
+  /** Default output file name (e.g., "fragments.json") */
+  outFile: "fragments.json",
+  /** Config file name (e.g., "fragments.config.ts") */
+  configFile: "fragments.config.ts",
+  /** Legacy config file name (still supported for migration) */
+  legacyConfigFile: "segments.config.ts",
+  /** CLI command name (e.g., "fragments") */
+  cliCommand: "fragments",
+  /** Package scope (e.g., "@fragments") */
+  packageScope: "@fragments",
+  /** Directory for storing fragments, registry, and cache */
+  dataDir: ".fragments",
+  /** Components subdirectory within .fragments/ */
+  componentsDir: "components",
+  /** Registry file name */
+  registryFile: "registry.json",
+  /** Context file name (AI-ready markdown) */
+  contextFile: "context.md",
+  /** Screenshots subdirectory */
+  screenshotsDir: "screenshots",
+  /** Cache subdirectory (gitignored) */
+  cacheDir: "cache",
+  /** Diff output subdirectory (gitignored) */
+  diffDir: "diff",
+  /** Manifest filename */
+  manifestFile: "manifest.json",
+  /** Prefix for localStorage keys (e.g., "fragments-") */
+  storagePrefix: "fragments-",
+  /** Static viewer HTML file name */
+  viewerHtmlFile: "fragments-viewer.html",
+  /** MCP tool name prefix (e.g., "fragments_") */
+  mcpToolPrefix: "fragments_",
+  /** File extension for block definition files */
+  blockFileExtension: ".block.ts",
+  /** @deprecated Use blockFileExtension instead */
+  recipeFileExtension: ".recipe.ts",
+  /** Vite plugin namespace */
+  vitePluginNamespace: "fragments-core-shim"
+};
+var DEFAULTS = {
+  /** Default viewport dimensions */
+  viewport: {
+    width: 1280,
+    height: 800
+  },
+  /** Default diff threshold (percentage) */
+  diffThreshold: 5,
+  /** Browser pool size */
+  poolSize: 3,
+  /** Idle timeout before browser shutdown (ms) - 5 minutes */
+  idleTimeoutMs: 5 * 60 * 1e3,
+  /** Delay after render before capture (ms) */
+  captureDelayMs: 100,
+  /** Font loading timeout (ms) */
+  fontTimeoutMs: 3e3,
+  /** Default theme */
+  theme: "light",
+  /** Dev server port */
+  port: 6006
+};
+
+// src/performance-presets.ts
+var PRESETS = {
+  strict: { bundleSize: 8 * 1024 },
+  // 8KB gzipped
+  standard: { bundleSize: 15 * 1024 },
+  // 15KB gzipped
+  relaxed: { bundleSize: 30 * 1024 }
+  // 30KB gzipped
+};
+var PRESET_NAMES = Object.keys(PRESETS);
+function resolvePerformanceConfig(input) {
+  if (!input) {
+    return { preset: "standard", budgets: PRESETS.standard };
+  }
+  if (typeof input === "string") {
+    const budgets = PRESETS[input];
+    if (!budgets) {
+      throw new Error(
+        `Unknown performance preset "${input}". Available: ${PRESET_NAMES.join(", ")}`
+      );
+    }
+    return { preset: input, budgets };
+  }
+  const presetName = input.preset ?? "standard";
+  const baseBudgets = PRESETS[presetName];
+  if (!baseBudgets) {
+    throw new Error(
+      `Unknown performance preset "${presetName}". Available: ${PRESET_NAMES.join(", ")}`
+    );
+  }
+  return {
+    preset: presetName,
+    budgets: {
+      bundleSize: input.budgets?.bundleSize ?? baseBudgets.bundleSize
+    }
+  };
+}
+function classifyComplexity(gzipBytes) {
+  if (gzipBytes < 5 * 1024) return "lightweight";
+  if (gzipBytes < 15 * 1024) return "moderate";
+  return "heavy";
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  const kb = bytes / 1024;
+  return kb < 10 ? `${kb.toFixed(1)}KB` : `${Math.round(kb)}KB`;
+}
+function budgetBar(percent, width = 20) {
+  const filled = Math.min(Math.round(percent / 100 * width), width);
+  const bar = "\u2588".repeat(filled) + "\u2591".repeat(width - filled);
+  return percent > 100 ? `\x1B[31m${bar}\x1B[0m` : `\x1B[32m${bar}\x1B[0m`;
+}
+
+// src/schema.ts
+import { z } from "zod";
+var figmaStringMappingSchema = z.object({
+  __type: z.literal("figma-string"),
+  figmaProperty: z.string().min(1)
+});
+var figmaBooleanMappingSchema = z.object({
+  __type: z.literal("figma-boolean"),
+  figmaProperty: z.string().min(1),
+  valueMapping: z.object({ true: z.unknown(), false: z.unknown() }).optional()
+});
+var figmaEnumMappingSchema = z.object({
+  __type: z.literal("figma-enum"),
+  figmaProperty: z.string().min(1),
+  valueMapping: z.record(z.unknown())
+});
+var figmaInstanceMappingSchema = z.object({
+  __type: z.literal("figma-instance"),
+  figmaProperty: z.string().min(1)
+});
+var figmaChildrenMappingSchema = z.object({
+  __type: z.literal("figma-children"),
+  layers: z.array(z.string().min(1))
+});
+var figmaTextContentMappingSchema = z.object({
+  __type: z.literal("figma-text-content"),
+  layer: z.string().min(1)
+});
+var figmaPropMappingSchema = z.discriminatedUnion("__type", [
+  figmaStringMappingSchema,
+  figmaBooleanMappingSchema,
+  figmaEnumMappingSchema,
+  figmaInstanceMappingSchema,
+  figmaChildrenMappingSchema,
+  figmaTextContentMappingSchema
+]);
+var fragmentMetaSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  category: z.string().min(1),
+  tags: z.array(z.string()).optional(),
+  status: z.enum(["stable", "beta", "deprecated", "experimental"]).optional(),
+  since: z.string().optional(),
+  dependencies: z.array(z.object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    reason: z.string().optional()
+  })).optional(),
+  figma: z.string().url().optional(),
+  figmaProps: z.record(figmaPropMappingSchema).optional()
+});
+var fragmentUsageSchema = z.object({
+  when: z.array(z.string()),
+  whenNot: z.array(z.string()),
+  guidelines: z.array(z.string()).optional(),
+  accessibility: z.array(z.string()).optional()
+});
+var propTypeSchema = z.enum([
+  "string",
+  "number",
+  "boolean",
+  "enum",
+  "function",
+  "node",
+  "element",
+  "object",
+  "array",
+  "union",
+  "custom"
+]);
+var propDefinitionSchema = z.object({
+  type: propTypeSchema,
+  values: z.array(z.string()).readonly().optional(),
+  default: z.unknown().optional(),
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  constraints: z.array(z.string()).optional(),
+  typeDetails: z.record(z.unknown()).optional()
+});
+var relationshipTypeSchema = z.enum([
+  "alternative",
+  "sibling",
+  "parent",
+  "child",
+  "composition",
+  "complementary",
+  "used-by"
+]);
+var componentRelationSchema = z.object({
+  component: z.string().min(1),
+  relationship: relationshipTypeSchema,
+  note: z.string().min(1)
+});
+var fragmentVariantSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  render: z.function().returns(z.unknown()),
+  code: z.string().optional(),
+  figma: z.string().url().optional()
+});
+var fragmentBanSchema = z.object({
+  pattern: z.string().min(1),
+  message: z.string().min(1)
+});
+var fragmentContractSchema = z.object({
+  propsSummary: z.array(z.string()).optional(),
+  a11yRules: z.array(z.string()).optional(),
+  bans: z.array(fragmentBanSchema).optional(),
+  scenarioTags: z.array(z.string()).optional(),
+  performanceBudget: z.number().positive().optional()
+});
+var fragmentGeneratedSchema = z.object({
+  source: z.enum(["storybook", "manual", "ai"]),
+  sourceFile: z.string().optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  timestamp: z.string().datetime().optional()
+});
+var aiMetadataSchema = z.object({
+  compositionPattern: z.enum(["compound", "simple", "controlled", "wrapper"]).optional(),
+  subComponents: z.array(z.string()).optional(),
+  requiredChildren: z.array(z.string()).optional(),
+  commonPatterns: z.array(z.string()).optional()
+});
+var blockDefinitionSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  category: z.string().min(1),
+  components: z.array(z.string().min(1)).min(1),
+  code: z.string().min(1),
+  tags: z.array(z.string()).optional()
+});
+var fragmentDefinitionSchema = z.object({
+  component: z.any(),
+  // Allow any component type (function, class, forwardRef, etc.)
+  meta: fragmentMetaSchema,
+  usage: fragmentUsageSchema,
+  props: z.record(propDefinitionSchema),
+  relations: z.array(componentRelationSchema).optional(),
+  variants: z.array(fragmentVariantSchema),
+  // Allow empty variants array
+  contract: fragmentContractSchema.optional(),
+  ai: aiMetadataSchema.optional(),
+  _generated: fragmentGeneratedSchema.optional()
+});
+var fragmentsConfigSchema = z.object({
+  include: z.array(z.string()).min(1),
+  exclude: z.array(z.string()).optional(),
+  components: z.array(z.string()).optional(),
+  outFile: z.string().optional(),
+  framework: z.enum(["react", "vue", "svelte"]).optional(),
+  figmaFile: z.string().url().optional(),
+  figmaToken: z.string().optional(),
+  screenshots: z.object({}).passthrough().optional(),
+  service: z.object({}).passthrough().optional(),
+  registry: z.object({}).passthrough().optional(),
+  tokens: z.object({
+    include: z.array(z.string()).min(1)
+  }).passthrough().optional(),
+  snippets: z.object({
+    mode: z.enum(["warn", "error"]).optional(),
+    scope: z.enum(["snippet", "snippet+render"]).optional(),
+    requireFullSnippet: z.boolean().optional(),
+    allowedExternalModules: z.array(z.string().min(1)).optional()
+  }).optional(),
+  performance: z.union([
+    z.enum(["strict", "standard", "relaxed"]),
+    z.object({
+      preset: z.enum(["strict", "standard", "relaxed"]).optional(),
+      budgets: z.object({
+        bundleSize: z.number().positive().optional()
+      }).optional()
+    })
+  ]).optional(),
+  storybook: z.object({
+    exclude: z.array(z.string()).optional(),
+    include: z.array(z.string()).optional(),
+    excludeDeprecated: z.boolean().optional(),
+    excludeTests: z.boolean().optional(),
+    excludeSvgIcons: z.boolean().optional(),
+    excludeSubComponents: z.boolean().optional()
+  }).optional()
+});
+var recipeDefinitionSchema = blockDefinitionSchema;
+
+// src/defineFragment.ts
+function defineFragment(definition) {
+  if (process.env.NODE_ENV !== "production") {
+    const result = fragmentDefinitionSchema.safeParse(definition);
+    if (!result.success) {
+      const errors = result.error.errors.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
+      throw new Error(
+        `Invalid fragment definition for "${definition.meta?.name || "unknown"}":
+${errors}`
+      );
+    }
+  }
+  return definition;
+}
+function compileFragment(definition, filePath) {
+  return {
+    filePath,
+    meta: definition.meta,
+    usage: definition.usage,
+    props: definition.props,
+    relations: definition.relations,
+    variants: definition.variants.map((v) => ({
+      name: v.name,
+      description: v.description,
+      code: v.code,
+      figma: v.figma
+    })),
+    contract: definition.contract,
+    _generated: definition._generated
+  };
+}
+function defineBlock(definition) {
+  if (process.env.NODE_ENV !== "production") {
+    const result = blockDefinitionSchema.safeParse(definition);
+    if (!result.success) {
+      const errors = result.error.errors.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
+      throw new Error(
+        `Invalid block definition for "${definition.name || "unknown"}":
+${errors}`
+      );
+    }
+  }
+  return definition;
+}
+var defineRecipe = defineBlock;
+function compileBlock(definition, filePath) {
+  return {
+    filePath,
+    name: definition.name,
+    description: definition.description,
+    category: definition.category,
+    components: definition.components,
+    code: definition.code,
+    tags: definition.tags
+  };
+}
+var compileRecipe = compileBlock;
+
+// src/storyAdapter.ts
+import { createElement } from "react";
+
+// src/storybook-csf.ts
+import {
+  toId as storybookToId,
+  storyNameFromExport as storybookStoryNameFromExport,
+  isExportStory as storybookIsExportStory
+} from "@storybook/csf";
+var toId = (...args) => storybookToId(...args);
+var storyNameFromExport = (...args) => storybookStoryNameFromExport(...args);
+var isExportStory = (...args) => storybookIsExportStory(...args);
+
+// src/storyAdapter.ts
+var globalPreviewConfig = {};
+function setPreviewConfig(config) {
+  globalPreviewConfig = config;
+}
+function getPreviewConfig() {
+  return globalPreviewConfig;
+}
+function storyModuleToFragment(storyModule, filePath) {
+  const meta = storyModule.default;
+  const component = meta.component;
+  if (!component) {
+    return null;
+  }
+  const componentName = extractComponentName(meta, filePath);
+  const category = extractCategory(meta.title);
+  const props = convertArgTypes(meta.argTypes ?? {}, globalPreviewConfig.argTypes);
+  const variants = extractVariants(storyModule, component, meta);
+  const figmaUrl = extractFigmaUrl(meta.parameters);
+  const fragmentMeta = {
+    name: componentName,
+    description: meta.parameters?.docs?.description?.component ?? `${componentName} component`,
+    category,
+    tags: meta.tags?.filter((t) => t !== "autodocs"),
+    status: "stable",
+    figma: figmaUrl
+  };
+  const usage = {
+    when: [`Use ${componentName} for its intended purpose`],
+    whenNot: ["When a more specific component is available"]
+  };
+  return {
+    component,
+    meta: fragmentMeta,
+    usage,
+    props,
+    variants
+  };
+}
+function extractComponentName(meta, filePath) {
+  if (meta.title) {
+    const parts = meta.title.split("/");
+    return parts[parts.length - 1];
+  }
+  if (meta.component?.displayName) {
+    return meta.component.displayName;
+  }
+  if (meta.component?.name && meta.component.name !== "Component") {
+    return meta.component.name;
+  }
+  const match = filePath.match(/([^/\\]+)\.stories\.(tsx?|jsx?)$/);
+  return match?.[1] ?? "Unknown";
+}
+function extractCategory(title) {
+  if (!title) return "general";
+  const parts = title.split("/");
+  if (parts.length >= 3) {
+    return parts[parts.length - 2].toLowerCase();
+  }
+  return "general";
+}
+function extractFigmaUrl(parameters) {
+  if (!parameters) return void 0;
+  const design = parameters.design;
+  if (design?.url && typeof design.url === "string") {
+    return design.url;
+  }
+  if (typeof parameters.figma === "string") {
+    return parameters.figma;
+  }
+  return void 0;
+}
+function convertArgTypes(argTypes, globalArgTypes) {
+  const props = {};
+  const mergedArgTypes = { ...globalArgTypes, ...argTypes };
+  for (const [name, argType] of Object.entries(mergedArgTypes)) {
+    if (argType.table?.disable) continue;
+    if (argType.control === false && argType.action) continue;
+    const { controlType, controlOptions } = extractControlInfo(argType);
+    props[name] = {
+      type: inferPropType(argType),
+      description: argType.description ?? `${name} prop`,
+      ...argType.options && { values: argType.options },
+      ...argType.table?.defaultValue && {
+        default: argType.table.defaultValue.summary
+      },
+      ...argType.defaultValue !== void 0 && {
+        default: argType.defaultValue
+      },
+      ...argType.type?.required && { required: true },
+      ...controlType && { controlType },
+      ...controlOptions && Object.keys(controlOptions).length > 0 && { controlOptions }
+    };
+  }
+  return props;
+}
+function extractControlInfo(argType) {
+  if (argType.control === void 0 || argType.control === false) {
+    return {};
+  }
+  const control = typeof argType.control === "string" ? { type: argType.control } : argType.control;
+  const validControlTypes = [
+    "text",
+    "number",
+    "range",
+    "boolean",
+    "select",
+    "multi-select",
+    "radio",
+    "inline-radio",
+    "check",
+    "inline-check",
+    "object",
+    "file",
+    "color",
+    "date"
+  ];
+  const controlType = validControlTypes.includes(control.type) ? control.type : void 0;
+  const controlOptions = {};
+  if (control.min !== void 0) controlOptions.min = control.min;
+  if (control.max !== void 0) controlOptions.max = control.max;
+  if (control.step !== void 0) controlOptions.step = control.step;
+  if (control.presetColors) controlOptions.presetColors = control.presetColors;
+  return {
+    controlType,
+    controlOptions: Object.keys(controlOptions).length > 0 ? controlOptions : void 0
+  };
+}
+function inferPropType(argType) {
+  if (argType.action) return "function";
+  if (argType.options?.length) return "enum";
+  if (argType.type?.name) {
+    const typeMap = {
+      string: "string",
+      number: "number",
+      boolean: "boolean",
+      object: "object",
+      array: "array",
+      function: "function"
+    };
+    const mapped = typeMap[argType.type.name];
+    if (mapped) return mapped;
+  }
+  const control = typeof argType.control === "string" ? argType.control : argType.control ? argType.control.type : void 0;
+  if (control) {
+    const controlMap = {
+      // Text controls
+      text: "string",
+      // Number controls
+      number: "number",
+      range: "number",
+      // Boolean controls
+      boolean: "boolean",
+      check: "boolean",
+      "inline-check": "boolean",
+      // Enum/selection controls
+      select: "enum",
+      "multi-select": "enum",
+      radio: "enum",
+      "inline-radio": "enum",
+      // Object controls
+      object: "object",
+      file: "object",
+      // Special string controls
+      color: "string",
+      date: "string"
+    };
+    const mapped = controlMap[control];
+    if (mapped) return mapped;
+  }
+  return "string";
+}
+function isStory(value) {
+  if (typeof value === "object" && value !== null) {
+    const obj = value;
+    if ("args" in obj || "render" in obj || "play" in obj) return true;
+  }
+  if (typeof value === "function") {
+    const fn = value;
+    if ("args" in fn) return true;
+  }
+  return false;
+}
+function extractVariants(storyModule, component, meta) {
+  const variants = [];
+  for (const [exportName, exportValue] of Object.entries(storyModule)) {
+    if (exportName === "default") continue;
+    if (!isExportStory(exportName, meta)) continue;
+    if (!isStory(exportValue)) continue;
+    const story = exportValue;
+    const storyName = typeof story === "object" && story.name || typeof story === "object" && story.storyName || typeof story === "function" && story.storyName || storyNameFromExport(exportName);
+    const storyId = toId(meta.title || "Unknown", exportName);
+    let description = `${storyName} variant`;
+    if (typeof story === "object" && story.parameters?.docs?.description?.story) {
+      description = story.parameters.docs.description.story;
+    }
+    const storyPlayFn = typeof story === "object" ? story.play : story.play;
+    const hasPlayFunction = !!storyPlayFn;
+    const wrappedPlay = storyPlayFn ? async (context) => {
+      const args = {
+        ...globalPreviewConfig.args,
+        ...meta.args,
+        ...typeof story === "function" ? story.args : story.args
+      };
+      const fullContext = buildStoryContext(meta, story, args, storyId, storyName);
+      const playContext = {
+        ...fullContext,
+        canvasElement: context.canvasElement,
+        args: context.args,
+        step: context.step
+      };
+      await storyPlayFn(playContext);
+    } : void 0;
+    const storyTags = typeof story === "object" ? story.tags : void 0;
+    const loaders = collectLoaders(meta, story);
+    const variantArgs = {
+      ...globalPreviewConfig.args,
+      ...meta.args,
+      ...typeof story === "function" ? story.args : story.args
+    };
+    const hasArgs = Object.keys(variantArgs).length > 0;
+    variants.push({
+      name: storyName,
+      description,
+      render: createRenderFunction(story, component, meta, storyId, storyName),
+      // Store Storybook-specific metadata
+      ...hasPlayFunction && { hasPlayFunction: true },
+      ...wrappedPlay && { play: wrappedPlay },
+      ...storyId && { storyId },
+      ...storyTags && { tags: storyTags },
+      ...loaders.length > 0 && { loaders },
+      ...hasArgs && { args: variantArgs }
+    });
+  }
+  return variants;
+}
+function collectLoaders(meta, story) {
+  const allLoaders = [
+    ...globalPreviewConfig.loaders ?? [],
+    ...meta.loaders ?? [],
+    ...typeof story === "function" ? story.loaders ?? [] : story.loaders ?? []
+  ];
+  if (allLoaders.length === 0) {
+    return [];
+  }
+  return allLoaders.map((loader) => {
+    return async () => {
+      const minimalContext = {
+        args: {},
+        argTypes: {},
+        globals: {},
+        parameters: {},
+        id: "",
+        kind: meta.title || "Unknown",
+        name: "",
+        story: "",
+        viewMode: "story",
+        loaded: {},
+        abortSignal: new AbortController().signal,
+        componentId: "",
+        title: meta.title || "Unknown"
+      };
+      return loader(minimalContext);
+    };
+  });
+}
+function buildStoryContext(meta, story, args, storyId, storyName, loadedData) {
+  const mergedArgs = {
+    ...globalPreviewConfig.args,
+    ...meta.args,
+    ...typeof story === "object" ? story.args : story.args,
+    ...args
+  };
+  const mergedArgTypes = {
+    ...globalPreviewConfig.argTypes,
+    ...meta.argTypes,
+    ...typeof story === "object" ? story.argTypes : story.argTypes
+  };
+  const mergedParameters = {
+    ...globalPreviewConfig.parameters,
+    ...meta.parameters,
+    ...typeof story === "object" ? story.parameters : story.parameters
+  };
+  return {
+    args: mergedArgs,
+    argTypes: mergedArgTypes ?? {},
+    globals: {},
+    parameters: mergedParameters ?? {},
+    id: storyId,
+    kind: meta.title || "Unknown",
+    name: storyName,
+    story: storyName,
+    viewMode: "story",
+    loaded: loadedData ?? {},
+    abortSignal: new AbortController().signal,
+    componentId: toId(meta.title || "Unknown", ""),
+    title: meta.title || "Unknown"
+  };
+}
+function createRenderFunction(story, component, meta, storyId, storyName) {
+  return (options) => {
+    const args = {
+      ...globalPreviewConfig.args,
+      ...meta.args,
+      ...typeof story === "function" ? story.args : story.args,
+      ...options?.args
+      // Runtime overrides from viewer props panel
+    };
+    const loadedData = options?.loadedData;
+    const context = buildStoryContext(meta, story, args, storyId, storyName, loadedData);
+    let renderFn;
+    if (typeof story === "function") {
+      renderFn = () => story(args);
+    } else if (story.render) {
+      renderFn = () => story.render.length >= 2 ? story.render(args, context) : story.render(args);
+    } else if (meta.render) {
+      renderFn = () => meta.render.length >= 2 ? meta.render(args, context) : meta.render(args);
+    } else {
+      renderFn = () => createElement(component, args);
+    }
+    const allDecorators = [
+      ...globalPreviewConfig.decorators ?? [],
+      ...meta.decorators ?? [],
+      ...typeof story === "function" ? story.decorators ?? [] : story.decorators ?? []
+    ].reverse();
+    if (allDecorators.length > 0) {
+      return applyDecorators(renderFn, allDecorators, context);
+    }
+    return renderFn();
+  };
+}
+function applyDecorators(renderFn, decorators, context) {
+  let storyFn = renderFn;
+  for (const decorator of decorators) {
+    const wrappedFn = storyFn;
+    storyFn = () => decorator(wrappedFn, context);
+  }
+  return storyFn();
+}
+
+// src/storyFilters.ts
+var EXCLUDED_TAGS = /* @__PURE__ */ new Set(["hidden", "internal", "no-fragment"]);
+var SVG_ICON_RE = /^Svg[A-Z]/;
+var TEST_TITLE_RE = /\/tests?$/i;
+var TEST_FILE_RE = /\.test\.stories\./;
+var DEPRECATED_TITLE_RE = /\bDeprecated\b/i;
+function checkStoryExclusion(opts) {
+  const { config } = opts;
+  if (isForceIncluded(opts.componentName, config)) {
+    return { excluded: false };
+  }
+  if (isConfigExcluded(opts.componentName, config)) {
+    return {
+      excluded: true,
+      reason: "config-excluded",
+      detail: `'${opts.componentName}' matches storybook.exclude pattern`
+    };
+  }
+  if (config.excludeDeprecated !== false && opts.storybookTitle && DEPRECATED_TITLE_RE.test(opts.storybookTitle)) {
+    return {
+      excluded: true,
+      reason: "deprecated",
+      detail: `Title "${opts.storybookTitle}" contains "Deprecated"`
+    };
+  }
+  if (config.excludeTests !== false) {
+    if (opts.storybookTitle && TEST_TITLE_RE.test(opts.storybookTitle)) {
+      return {
+        excluded: true,
+        reason: "test-story",
+        detail: `Title "${opts.storybookTitle}" ends with /test(s)`
+      };
+    }
+    if (TEST_FILE_RE.test(opts.filePath)) {
+      return {
+        excluded: true,
+        reason: "test-story",
+        detail: `File path matches *.test.stories.*`
+      };
+    }
+  }
+  if (config.excludeSvgIcons !== false) {
+    const names = [opts.componentName, opts.componentDisplayName, opts.componentFunctionName].filter(Boolean);
+    for (const name of names) {
+      if (SVG_ICON_RE.test(name)) {
+        return {
+          excluded: true,
+          reason: "svg-icon",
+          detail: `Component name "${name}" matches Svg[A-Z] pattern`
+        };
+      }
+    }
+  }
+  if (opts.tags?.length) {
+    const hit = opts.tags.find((t) => EXCLUDED_TAGS.has(t));
+    if (hit) {
+      return {
+        excluded: true,
+        reason: "tag-excluded",
+        detail: `Tag "${hit}" is in the exclusion set`
+      };
+    }
+  }
+  if (opts.variantCount === 0) {
+    return {
+      excluded: true,
+      reason: "empty-variants",
+      detail: "Zero renderable story exports"
+    };
+  }
+  return { excluded: false };
+}
+function detectSubComponentPaths(storyFiles) {
+  const byDir = /* @__PURE__ */ new Map();
+  for (const file of storyFiles) {
+    const parts = file.relativePath.split("/");
+    if (parts.length < 2) continue;
+    const fileName = parts[parts.length - 1];
+    const baseMatch = fileName.match(/^([^.]+)\.stories\./);
+    if (!baseMatch) continue;
+    const dir = parts.slice(0, -1).join("/");
+    const baseName = baseMatch[1];
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push({ relativePath: file.relativePath, baseName });
+  }
+  const subComponentMap = /* @__PURE__ */ new Map();
+  for (const [dir, files] of byDir) {
+    if (files.length <= 1) continue;
+    const dirName = dir.split("/").pop();
+    const primary = files.find((f) => f.baseName === dirName);
+    if (!primary) continue;
+    for (const file of files) {
+      if (file.relativePath === primary.relativePath) continue;
+      subComponentMap.set(file.relativePath, primary.baseName);
+    }
+  }
+  return subComponentMap;
+}
+function isForceIncluded(name, config) {
+  if (!config.include?.length) return false;
+  return config.include.some((pattern) => matchesPattern(name, pattern));
+}
+function isConfigExcluded(name, config) {
+  if (!config.exclude?.length) return false;
+  return config.exclude.some((pattern) => matchesPattern(name, pattern));
+}
+function matchesPattern(name, pattern) {
+  if (!pattern.includes("*")) {
+    return name === pattern;
+  }
+  const parts = pattern.split("*");
+  if (parts.length === 2) {
+    const [prefix, suffix] = parts;
+    if (prefix && suffix) return name.startsWith(prefix) && name.endsWith(suffix);
+    if (prefix) return name.startsWith(prefix);
+    if (suffix) return name.endsWith(suffix);
+    return true;
+  }
+  const escaped = parts.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+  return new RegExp(`^${escaped}$`).test(name);
+}
+
+// src/context.ts
+import { generateContext, filterPlaceholders, PLACEHOLDER_PATTERNS } from "@fragments-sdk/context/generate";
+
+// src/figma.ts
+function string(figmaProperty) {
+  return {
+    __type: "figma-string",
+    figmaProperty
+  };
+}
+function boolean(figmaProperty, valueMapping) {
+  return {
+    __type: "figma-boolean",
+    figmaProperty,
+    valueMapping
+  };
+}
+function enumValue(figmaProperty, valueMapping) {
+  return {
+    __type: "figma-enum",
+    figmaProperty,
+    valueMapping
+  };
+}
+function instance(figmaProperty) {
+  return {
+    __type: "figma-instance",
+    figmaProperty
+  };
+}
+function children(layers) {
+  return {
+    __type: "figma-children",
+    layers
+  };
+}
+function textContent(layer) {
+  return {
+    __type: "figma-text-content",
+    layer
+  };
+}
+var figma = {
+  string,
+  boolean,
+  enum: enumValue,
+  instance,
+  children,
+  textContent
+};
+function isFigmaPropMapping(value) {
+  if (typeof value !== "object" || value === null || !("__type" in value)) {
+    return false;
+  }
+  const typeValue = value.__type;
+  return typeof typeValue === "string" && typeValue.startsWith("figma-");
+}
+function resolveFigmaMapping(mapping, figmaValues) {
+  switch (mapping.__type) {
+    case "figma-string":
+      return figmaValues[mapping.figmaProperty] ?? "";
+    case "figma-boolean": {
+      const boolValue = figmaValues[mapping.figmaProperty];
+      if (mapping.valueMapping) {
+        return boolValue ? mapping.valueMapping.true : mapping.valueMapping.false;
+      }
+      return boolValue;
+    }
+    case "figma-enum": {
+      const enumKey = figmaValues[mapping.figmaProperty];
+      return mapping.valueMapping[enumKey] ?? enumKey;
+    }
+    case "figma-instance":
+      return figmaValues[mapping.figmaProperty];
+    case "figma-children":
+      return mapping.layers.map((layer) => figmaValues[layer]);
+    case "figma-text-content":
+      return figmaValues[mapping.layer] ?? "";
+    default:
+      return void 0;
+  }
+}
+
+// src/token-parser.ts
+var NAMING_RULES = [
+  { pattern: /--\w+-font-/, category: "typography" },
+  { pattern: /--\w+-line-height-/, category: "typography" },
+  { pattern: /--\w+-space-/, category: "spacing" },
+  { pattern: /--\w+-padding-/, category: "spacing" },
+  { pattern: /--\w+-radius-/, category: "radius" },
+  { pattern: /--\w+-color-/, category: "colors" },
+  { pattern: /--\w+-bg-/, category: "surfaces" },
+  { pattern: /--\w+-text-/, category: "text" },
+  { pattern: /--\w+-border/, category: "borders" },
+  { pattern: /--\w+-shadow-/, category: "shadows" },
+  { pattern: /--\w+-focus-/, category: "focus" },
+  { pattern: /--\w+-transition-/, category: "transitions" },
+  { pattern: /--\w+-scrollbar-/, category: "scrollbar" },
+  { pattern: /--\w+-z-index/, category: "z-index" },
+  { pattern: /--\w+-(button|input|touch)-/, category: "component-sizing" },
+  { pattern: /--\w+-appshell-/, category: "layout" },
+  { pattern: /--\w+-header-/, category: "layout" },
+  { pattern: /--\w+-code-/, category: "code" },
+  { pattern: /--\w+-tooltip-/, category: "tooltip" },
+  { pattern: /--\w+-hero-/, category: "marketing" }
+];
+function inferCategory(name) {
+  for (const rule of NAMING_RULES) {
+    if (rule.pattern.test(name)) {
+      return rule.category;
+    }
+  }
+  return "other";
+}
+function detectPrefix(names) {
+  if (names.length === 0) return "--";
+  const stripped = names.map((n) => n.slice(2));
+  let prefix = "";
+  const first = stripped[0];
+  for (let i = 0; i < first.length; i++) {
+    const ch = first[i];
+    if (stripped.every((s) => s[i] === ch)) {
+      prefix += ch;
+    } else {
+      break;
+    }
+  }
+  const lastHyphen = prefix.lastIndexOf("-");
+  if (lastHyphen > 0) {
+    prefix = prefix.slice(0, lastHyphen + 1);
+  }
+  return `--${prefix}`;
+}
+function normalizeCategory(comment) {
+  const text = comment.trim().replace(/^\/\/\s*/, "").replace(/^\/\*+\s*/, "").replace(/\s*\*+\/$/, "").trim().toLowerCase();
+  const mappings = {
+    "base configuration": "base",
+    "typography": "typography",
+    "spacing (micro)": "spacing",
+    "spacing": "spacing",
+    "density padding": "spacing",
+    "border radius": "radius",
+    "transitions": "transitions",
+    "colors": "colors",
+    "surfaces": "surfaces",
+    "text": "text",
+    "borders": "borders",
+    "shadows": "shadows",
+    "focus": "focus",
+    "scrollbar": "scrollbar",
+    "component heights": "component-sizing",
+    "appshell layout": "layout",
+    "codeblock": "code",
+    "tooltip": "tooltip",
+    "hero/marketing gradient": "marketing"
+  };
+  return mappings[text] ?? text.replace(/\s+/g, "-");
+}
+function extractScssVariables(content) {
+  const vars = /* @__PURE__ */ new Map();
+  const scssVarRegex = /^\s*(\$[\w-]+)\s*:\s*(.+?)\s*(?:!default\s*)?;/gm;
+  let match;
+  while ((match = scssVarRegex.exec(content)) !== null) {
+    const name = match[1];
+    const value = match[2].replace(/\s*\/\/.*$/, "").trim();
+    if (!vars.has(name)) {
+      vars.set(name, value);
+    }
+  }
+  return vars;
+}
+function resolveTokenValue(rawValue, scssVars, cssVarValues, depth = 0) {
+  if (depth > 5) return rawValue;
+  let resolved = rawValue;
+  resolved = resolved.replace(/#\{(\$[\w-]+)\}/g, (_, varName) => {
+    const val = scssVars.get(varName);
+    return val !== void 0 ? resolveTokenValue(val, scssVars, cssVarValues, depth + 1) : `#{${varName}}`;
+  });
+  resolved = resolved.replace(/(?<![#\{])(\$[\w-]+)/g, (_, varName) => {
+    const val = scssVars.get(varName);
+    return val !== void 0 ? resolveTokenValue(val, scssVars, cssVarValues, depth + 1) : varName;
+  });
+  resolved = resolved.replace(
+    /var\((--[\w-]+)(?:\s*,\s*(.+?))?\)/g,
+    (original, tokenName, fallback) => {
+      const tokenVal = cssVarValues.get(tokenName);
+      if (tokenVal !== void 0) {
+        return resolveTokenValue(tokenVal, scssVars, cssVarValues, depth + 1);
+      }
+      if (fallback) {
+        return resolveTokenValue(fallback.trim(), scssVars, cssVarValues, depth + 1);
+      }
+      return original;
+    }
+  );
+  return resolved;
+}
+function parseTokenFile(content, filePath) {
+  const lines = content.split("\n");
+  const tokens = [];
+  const seenNames = /* @__PURE__ */ new Set();
+  let currentCategory = "other";
+  let hasCommentCategories = false;
+  const scssVars = extractScssVariables(content);
+  const varDeclRegex = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;/;
+  const sectionCommentRegex = /^\s*\/\/\s+([A-Z].+)$/;
+  for (const line of lines) {
+    const commentMatch = line.match(sectionCommentRegex);
+    if (commentMatch) {
+      const normalized = normalizeCategory(commentMatch[0]);
+      if (normalized) {
+        currentCategory = normalized;
+        hasCommentCategories = true;
+      }
+      continue;
+    }
+    const varMatch = line.match(varDeclRegex);
+    if (varMatch) {
+      const name = varMatch[1];
+      const rawValue = varMatch[2];
+      if (seenNames.has(name)) continue;
+      seenNames.add(name);
+      const inlineComment = line.match(/\/\/\s*(.+)$/);
+      const description = inlineComment ? inlineComment[1].trim() : void 0;
+      const cleanValue = rawValue.replace(/\s*\/\/.*$/, "").trim();
+      tokens.push({
+        name,
+        value: cleanValue || void 0,
+        category: hasCommentCategories ? currentCategory : inferCategory(name),
+        description
+      });
+    }
+  }
+  const cssVarValues = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    if (token.value) {
+      cssVarValues.set(token.name, token.value);
+    }
+  }
+  for (const token of tokens) {
+    if (token.value) {
+      const resolved = resolveTokenValue(token.value, scssVars, cssVarValues);
+      if (resolved !== token.value && !resolved.includes("#{") && !resolved.includes("$")) {
+        token.resolvedValue = resolved;
+      }
+    }
+  }
+  const categories = {};
+  for (const token of tokens) {
+    if (!categories[token.category]) {
+      categories[token.category] = [];
+    }
+    categories[token.category].push(token);
+  }
+  const prefix = detectPrefix(tokens.map((t) => t.name));
+  return {
+    prefix,
+    categories,
+    total: tokens.length
+  };
+}
+
+// src/composition.ts
+import { ComponentGraphEngine } from "@fragments-sdk/context/graph";
+var CATEGORY_AFFINITIES = {
+  forms: ["feedback"],
+  actions: ["feedback"]
+};
+function analyzeComposition(fragments, componentNames, _context, options) {
+  const allNames = new Set(Object.keys(fragments));
+  const components = [];
+  const unknown = [];
+  for (const name of componentNames) {
+    if (allNames.has(name)) {
+      components.push(name);
+    } else {
+      unknown.push(name);
+    }
+  }
+  const selectedSet = new Set(components);
+  const warnings = [];
+  const suggestions = [];
+  const guidelines = [];
+  const suggestedSet = /* @__PURE__ */ new Set();
+  for (const name of components) {
+    const fragment = fragments[name];
+    if (fragment.relations) {
+      for (const rel of fragment.relations) {
+        switch (rel.relationship) {
+          case "parent":
+            if (!selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "missing_parent",
+                component: name,
+                message: `"${name}" expects to be wrapped by "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component
+              });
+            }
+            break;
+          case "child":
+            if (!selectedSet.has(rel.component) && !suggestedSet.has(rel.component)) {
+              suggestions.push({
+                component: rel.component,
+                reason: `"${name}" typically contains "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relationship: "child",
+                sourceComponent: name
+              });
+              suggestedSet.add(rel.component);
+            }
+            break;
+          case "composition":
+            if (!selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "missing_composition",
+                component: name,
+                message: `"${name}" is typically used together with "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component
+              });
+            }
+            break;
+          case "sibling":
+            if (!selectedSet.has(rel.component) && !suggestedSet.has(rel.component)) {
+              suggestions.push({
+                component: rel.component,
+                reason: `"${rel.component}" is a sibling of "${name}"${rel.note ? `: ${rel.note}` : ""}`,
+                relationship: "sibling",
+                sourceComponent: name
+              });
+              suggestedSet.add(rel.component);
+            }
+            break;
+          case "alternative":
+            if (selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "redundant_alternative",
+                component: name,
+                message: `"${name}" and "${rel.component}" are alternatives \u2014 using both may be redundant${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component
+              });
+            }
+            break;
+        }
+      }
+    }
+    if (fragment.usage?.whenNot) {
+      for (const whenNotEntry of fragment.usage.whenNot) {
+        const lower = whenNotEntry.toLowerCase();
+        for (const other of components) {
+          if (other !== name && lower.includes(other.toLowerCase())) {
+            guidelines.push({
+              component: name,
+              guideline: `Potential conflict with "${other}": ${whenNotEntry}`
+            });
+          }
+        }
+      }
+    }
+    if (fragment.meta.status === "deprecated") {
+      warnings.push({
+        type: "deprecated",
+        component: name,
+        message: fragment.meta.description ? `"${name}" is deprecated: ${fragment.meta.description}` : `"${name}" is deprecated`
+      });
+    } else if (fragment.meta.status === "experimental") {
+      warnings.push({
+        type: "experimental",
+        component: name,
+        message: `"${name}" is experimental and may change without notice`
+      });
+    }
+  }
+  const selectedCategories = new Set(
+    components.map((name) => fragments[name].meta.category)
+  );
+  for (const [category, affinities] of Object.entries(CATEGORY_AFFINITIES)) {
+    if (!selectedCategories.has(category)) continue;
+    for (const neededCategory of affinities) {
+      if (selectedCategories.has(neededCategory)) continue;
+      const candidate = findBestCategoryCandidate(
+        fragments,
+        neededCategory,
+        selectedSet,
+        suggestedSet
+      );
+      if (candidate) {
+        suggestions.push({
+          component: candidate,
+          reason: `Compositions using "${category}" components often benefit from a "${neededCategory}" component`,
+          relationship: "category_gap",
+          sourceComponent: components.find(
+            (n) => fragments[n].meta.category === category
+          )
+        });
+        suggestedSet.add(candidate);
+      }
+    }
+  }
+  if (options?.graph) {
+    const engine = new ComponentGraphEngine(options.graph);
+    for (const name of components) {
+      const deps = engine.dependencies(name, ["imports", "hook-depends"]);
+      for (const dep of deps) {
+        if (!selectedSet.has(dep.target) && !suggestedSet.has(dep.target) && allNames.has(dep.target)) {
+          suggestions.push({
+            component: dep.target,
+            reason: `"${name}" ${dep.type === "hook-depends" ? "uses a hook from" : "imports"} "${dep.target}"`,
+            relationship: "composition",
+            sourceComponent: name
+          });
+          suggestedSet.add(dep.target);
+        }
+      }
+    }
+    for (const name of components) {
+      const blocks = engine.blocksUsing(name);
+      for (const blockName of blocks) {
+        const blockComps = options.graph.edges.filter(
+          (e) => e.type === "composes" && e.provenance === `block:${blockName}` && (e.source === name || e.target === name)
+        ).map((e) => e.source === name ? e.target : e.source);
+        for (const comp of blockComps) {
+          if (!selectedSet.has(comp) && !suggestedSet.has(comp) && allNames.has(comp)) {
+            suggestions.push({
+              component: comp,
+              reason: `"${name}" and "${comp}" are used together in the "${blockName}" block`,
+              relationship: "composition",
+              sourceComponent: name
+            });
+            suggestedSet.add(comp);
+          }
+        }
+      }
+    }
+  }
+  return { components, unknown, warnings, suggestions, guidelines };
+}
+function findBestCategoryCandidate(fragments, category, selectedSet, suggestedSet) {
+  let best = null;
+  let bestScore = -1;
+  for (const [name, fragment] of Object.entries(fragments)) {
+    if (fragment.meta.category !== category) continue;
+    if (selectedSet.has(name) || suggestedSet.has(name)) continue;
+    const status = fragment.meta.status ?? "stable";
+    let score = 0;
+    if (status === "stable") score = 3;
+    else if (status === "beta") score = 2;
+    else if (status === "experimental") score = 1;
+    if (score > bestScore) {
+      bestScore = score;
+      best = name;
+    }
+  }
+  return best;
+}
+
+// src/preview-runtime.tsx
+import { useEffect, useState } from "react";
+import { Fragment, jsx } from "react/jsx-runtime";
+var EMPTY_STATE = {
+  content: null,
+  isLoading: false,
+  error: null,
+  loadedData: void 0
+};
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+async function executeVariantLoaders(loaders, loadedData) {
+  const hasLoaders = !!loaders && loaders.length > 0;
+  if (!hasLoaders) {
+    return loadedData;
+  }
+  const results = await Promise.all(loaders.map((loader) => loader()));
+  const mergedFromLoaders = results.reduce(
+    (acc, result) => ({ ...acc, ...result }),
+    {}
+  );
+  return loadedData ? { ...mergedFromLoaders, ...loadedData } : mergedFromLoaders;
+}
+async function resolvePreviewRuntimeState(options) {
+  const { variant, loadedData } = options;
+  if (!variant) {
+    return EMPTY_STATE;
+  }
+  try {
+    const mergedLoadedData = await executeVariantLoaders(variant.loaders, loadedData);
+    const content = variant.render({ loadedData: mergedLoadedData });
+    return {
+      content,
+      isLoading: false,
+      error: null,
+      loadedData: mergedLoadedData
+    };
+  } catch (error) {
+    return {
+      content: null,
+      isLoading: false,
+      error: toError(error),
+      loadedData: void 0
+    };
+  }
+}
+function usePreviewVariantRuntime(options) {
+  const { variant, loadedData } = options;
+  const [state, setState] = useState(EMPTY_STATE);
+  useEffect(() => {
+    let cancelled = false;
+    if (!variant) {
+      setState(EMPTY_STATE);
+      return () => {
+        cancelled = true;
+      };
+    }
+    const hasLoaders = !!variant.loaders && variant.loaders.length > 0;
+    setState({
+      content: null,
+      isLoading: hasLoaders,
+      error: null,
+      loadedData: void 0
+    });
+    resolvePreviewRuntimeState({ variant, loadedData }).then((nextState) => {
+      if (!cancelled) {
+        setState(nextState);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [variant, loadedData]);
+  return state;
+}
+function PreviewVariantRuntime({
+  variant,
+  loadedData,
+  children: children2
+}) {
+  const state = usePreviewVariantRuntime({ variant, loadedData });
+  return /* @__PURE__ */ jsx(Fragment, { children: children2(state) });
+}
+export {
+  BRAND,
+  DEFAULTS,
+  PRESET_NAMES,
+  PreviewVariantRuntime,
+  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,
+  generateContext,
+  getPreviewConfig,
+  isConfigExcluded,
+  isExportStory,
+  isFigmaPropMapping,
+  isForceIncluded,
+  parseTokenFile,
+  propDefinitionSchema,
+  recipeDefinitionSchema,
+  resolveFigmaMapping,
+  resolvePerformanceConfig,
+  resolvePreviewRuntimeState,
+  setPreviewConfig,
+  storyModuleToFragment,
+  storyNameFromExport,
+  toId,
+  usePreviewVariantRuntime
+};
+//# sourceMappingURL=index.js.map