@usefragments/core 1.10.2 → 2.0.0

package/src/types.ts

@@ -1,5 +1,9 @@
 import type { ComponentType, ReactNode, JSX } from "react";
-import type { GovernanceConfig } from "./governance.js";
+import type {
+  ComponentGovernanceBuilder,
+  ComponentGovernanceRecord,
+  GovernanceConfig,
+} from "./governance.js";
 import type { InspectConfig } from "./local-canonical.js";
 import type { Topology } from "./topology/resolve-area.js";
 
@@ -115,6 +119,19 @@ export interface FragmentUsage {
   /** When NOT to use this component (with alternatives) */
   whenNot: string[];
 
+  /** Optional v3 choose-among-alternates guidance carried into the wire document */
+  choose?: Record<string, string>;
+
+  /**
+   * Serialized v3 anti-pattern guidance. The source API keeps `good` as JSX;
+   * the compiled catalog stores its exact checked source span as a string.
+   */
+  dont?: Array<{
+    reason: string;
+    bad: string;
+    good: string;
+  }>;
+
   /** Additional usage guidelines and best practices */
   guidelines?: string[];
 
@@ -288,6 +305,13 @@ export interface FragmentVariant {
   /** Async loaders to execute before rendering (from Storybook loaders) */
   loaders?: VariantLoader[];
 
+  /**
+   * The adapted Storybook story declared one or more loaders. Their original
+   * Storybook context is not available to a Fragment variant, so adapters
+   * report presence without attempting to execute them.
+   */
+  hasUnsupportedStorybookLoaders?: boolean;
+
   /** The args/props used to render this variant (for code generation) */
   args?: Record<string, unknown>;
 }
@@ -337,7 +361,7 @@ export interface FragmentContract {
  */
 export interface FragmentGenerated {
   /** Source of this fragment definition */
-  source: "storybook" | "manual" | "ai" | "extracted" | "merged" | "migrated";
+  source: "storybook" | "manual" | "ai" | "scan" | "extracted" | "merged" | "migrated";
 
   /** Original source file (e.g., "Button.stories.tsx") */
   sourceFile?: string;
@@ -455,7 +479,7 @@ export interface FragmentProvenance {
   confidence?: number;
 
   /** Whether the fragment has been verified against source */
-  verified: boolean;
+  verified?: boolean;
 
   /** Framework support level */
   frameworkSupport?: "native" | "manual-only";
@@ -514,6 +538,177 @@ export interface FragmentDefinitionV2<TProps = unknown> {
   _provenance?: FragmentProvenance;
 }
 
+// ---------------------------------------------------------------------------
+// v3 API — component-bound, arity-discriminated authoring
+// ---------------------------------------------------------------------------
+
+/**
+ * v3 component metadata. `purpose` is the required plain-English line for
+ * exec/agent surfaces; intent-search vocabulary lives in `aliases`.
+ *
+ * @since 3.0
+ */
+export interface FragmentMetaV3 {
+  name: string;
+  purpose: string;
+  category: string;
+  status?: "stable" | "beta" | "deprecated" | "experimental";
+  aliases?: string[];
+  tags?: string[];
+  since?: string;
+  dependencies?: Array<{
+    name: string;
+    version: string;
+    reason?: string;
+  }>;
+  figma?: string;
+  figmaProps?: Record<string, FigmaPropMapping>;
+}
+
+/**
+ * A single authored state. Display `code` is extracted from the checked JSX
+ * AST by the compiler — authored `code` strings are forbidden in v3.
+ *
+ * @since 3.0
+ */
+export interface FragmentStateV3 {
+  /** Type-checked JSX (element or render thunk). Never an authored code string. */
+  render: Exclude<ReactNode, string | undefined> | ((options?: VariantRenderOptions) => ReactNode);
+  note?: string;
+  canonical?: boolean;
+  /** Forbidden in v3 — display code is extracted from `render`. */
+  code?: never;
+}
+
+/**
+ * Negative example with a type-checked `good` replacement.
+ *
+ * @since 3.0
+ */
+export interface FragmentDontExampleV3 {
+  reason: string;
+  /** Anti-pattern shown as a string (intentionally not type-checked). */
+  bad: string;
+  /** Correct replacement — real JSX bound to the component. */
+  good: Exclude<ReactNode, string | undefined> | ((options?: VariantRenderOptions) => ReactNode);
+}
+
+/**
+ * v3 guidance: v2 when/whenNot plus choose/dont.
+ *
+ * @since 3.0
+ */
+export interface FragmentGuidanceV3 {
+  when: string[];
+  whenNot: string[];
+  choose?: Record<string, string>;
+  dont?: FragmentDontExampleV3[];
+  guidelines?: string[];
+  accessibility?: string[];
+}
+
+/**
+ * Workshop matrix axes. `"auto"` means extraction fills proven prop enums.
+ *
+ * @since 3.0
+ */
+export interface FragmentMatrixV3 {
+  axes?: Record<string, "auto" | readonly string[]>;
+  forced?: string[];
+  worstCase?: Record<string, unknown>;
+}
+
+/**
+ * Preview runtime hints (providers + visual-diff masks).
+ *
+ * @since 3.0
+ */
+export interface FragmentPreviewV3 {
+  providers?: unknown[];
+  dynamicRegions?: string[];
+}
+
+/**
+ * Optional design-tool comparison input.
+ *
+ * @since 3.0
+ */
+export interface FragmentDesignV3 {
+  figmaNode?: string;
+}
+
+/**
+ * Prop annotations annotate extracted truth — they never redefine `type`,
+ * `default`, `values`, or `required`.
+ *
+ * @since 3.0
+ */
+export interface PropAnnotation {
+  description?: string;
+  controlType?: ControlType;
+  controlOptions?: Record<string, unknown>;
+  visibility?: "public" | "internal" | "hidden";
+  constraints?: string[];
+  /** Forbidden — derived from component types. */
+  type?: never;
+  /** Forbidden — derived from component defaults. */
+  default?: never;
+  values?: never;
+  required?: never;
+}
+
+/**
+ * Freeform authoring annotations (docs notes, review markers). Separate from
+ * prop annotations, which live under `props`.
+ *
+ * @since 3.0
+ */
+export interface FragmentAnnotationsV3 {
+  notes?: string[];
+  review?: string[];
+  [key: string]: unknown;
+}
+
+type FragmentPropAnnotations<TProps> = [keyof TProps] extends [never]
+  ? Record<string, PropAnnotation>
+  : { [K in Extract<keyof TProps, string>]?: PropAnnotation };
+
+/**
+ * v3 definition body — the second argument to
+ * `defineFragment(Component, definition)`. The component is bound by arity,
+ * not authored inside the body.
+ *
+ * @since 3.0
+ */
+export interface FragmentDefinitionV3Body<TProps = unknown> {
+  meta: FragmentMetaV3;
+  states: Record<string, FragmentStateV3>;
+  guidance: FragmentGuidanceV3;
+  matrix?: FragmentMatrixV3;
+  preview?: FragmentPreviewV3;
+  design?: FragmentDesignV3;
+  annotations?: FragmentAnnotationsV3;
+  /** Annotate-only prop docs keyed by prop name. */
+  props?: FragmentPropAnnotations<TProps>;
+  relations?: ComponentRelation[];
+  composition?: CompositionMetadata;
+  contract?: FragmentContract;
+  _provenance?: FragmentProvenance;
+  /** Optional governance authoring (resolved when present). */
+  govern?: (g: ComponentGovernanceBuilder<TProps>) => ComponentGovernanceRecord[];
+  governance?: ComponentGovernanceRecord[];
+}
+
+/**
+ * Resolved v3 fragment after `defineFragment(Component, body)` binds the
+ * component. Governance is always resolved (empty array when none authored).
+ *
+ * @since 3.0
+ */
+export interface FragmentDefinitionV3<TProps = unknown> extends FragmentDefinitionV3Body<TProps> {
+  component: FragmentComponent<TProps>;
+  governance: ComponentGovernanceRecord[];
+}
 /**
  * Registry generation options
  */
@@ -529,9 +724,64 @@ export interface RegistryOptions {
 
   /** Include props in registry (default: false - AI can read TypeScript directly) */
   includeProps?: boolean;
+}
+
+/** Prop entry in the lightweight source registry. */
+export interface RegistryPropEntry {
+  type?: string;
+  typeKind?:
+    | "string"
+    | "number"
+    | "boolean"
+    | "enum"
+    | "object"
+    | "array"
+    | "function"
+    | "node"
+    | "element"
+    | "union"
+    | "unknown";
+  options?: string[];
+  default?: unknown;
+  required?: boolean;
+  description?: string;
+}
+
+/** Component entry in the lightweight source registry. */
+export interface RegistryComponentEntry {
+  path: string;
+  storyPath?: string;
+  category?: string;
+  props?: Record<string, RegistryPropEntry>;
+  exports?: string[];
+  dependencies?: string[];
+}
+
+/** Minimal component index for quick source navigation. */
+export interface FragmentIndex {
+  version: string;
+  generatedAt: string;
+  components: Record<string, string>;
+  categories?: Record<string, string[]>;
+}
+
+/** Source registry with resolved component paths and optional extracted props. */
+export interface FragmentRegistry {
+  $schema?: string;
+  version: string;
+  generatedAt: string;
+  componentCount: number;
+  components: Record<string, RegistryComponentEntry>;
+  categories?: Record<string, string[]>;
+}
 
-  /** Include full fragment data in registry (default: false - reference fragmentPath instead) */
-  embedFragments?: boolean;
+/** Context file options for source-registry generation. */
+export interface FragmentContextOptions {
+  format?: "markdown" | "json";
+  compact?: boolean;
+  include?: {
+    props?: boolean;
+  };
 }
 
 /**
@@ -661,25 +911,6 @@ export interface SnippetPolicyConfig {
   allowedExternalModules?: string[];
 }
 
-/**
- * Storybook adapter filtering configuration.
- * Controls which Storybook stories are included when generating fragments.
- */
-export interface StorybookFilterConfig {
-  /** Glob-style patterns for component names to explicitly exclude */
-  exclude?: string[];
-  /** Glob-style patterns for component names to force-include (bypasses all heuristic filters) */
-  include?: string[];
-  /** Exclude stories with "Deprecated" in the title (default: true) */
-  excludeDeprecated?: boolean;
-  /** Exclude test stories (title ending /test(s) or *.test.stories.* files) (default: true) */
-  excludeTests?: boolean;
-  /** Exclude SVG icon components (names matching Svg[A-Z]*) (default: true) */
-  excludeSvgIcons?: boolean;
-  /** Exclude sub-components detected by directory structure (default: true) */
-  excludeSubComponents?: boolean;
-}
-
 /**
  * Theme seed configuration.
  * The 5 root values that derive 120+ CSS custom properties.
@@ -691,9 +922,6 @@ export interface ThemeSeeds {
   /** Neutral palette name */
   neutral?: "stone" | "ice" | "earth" | "sand" | "fire" | "fragments";
 
-  /** Spacing density scale */
-  density?: "compact" | "default" | "relaxed";
-
   /** Border radius style */
   radiusStyle?: "sharp" | "subtle" | "default" | "rounded" | "pill";
 
@@ -776,9 +1004,6 @@ export interface FragmentsConfig {
   /** Performance budgets: preset name or custom config */
   performance?: string | { preset?: string; budgets?: { bundleSize?: number } };
 
-  /** Storybook adapter filtering configuration */
-  storybook?: StorybookFilterConfig;
-
   /** Theme seed values for the 5-seed theming system */
   theme?: ThemeSeeds;
 
@@ -1070,6 +1295,9 @@ export interface VerifyResult {
 // Compiled types — re-exported from ./compiled-types.
 export type {
   CompiledFragment,
+  CompiledFragmentDesign,
+  CompiledFragmentMatrix,
+  CompiledFragmentPreview,
   CompiledBlock,
   CompiledTokenEntry,
   CompiledTokenData,
@@ -1092,13 +1320,3 @@ export interface BlockDefinition {
   code: string;
   tags?: string[];
 }
-
-/**
- * @deprecated Use BlockDefinition instead
- */
-export type RecipeDefinition = BlockDefinition;
-
-/**
- * @deprecated Use CompiledBlock instead
- */
-export type CompiledRecipe = _CompiledBlock;

package/dist/chunk-3LLRNCPX.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/topology/resolve-area.ts"],"sourcesContent":["/**\n * Topology — map a repo-relative file path to its product area.\n *\n * This is the DRY keystone of the topology layer: the ONLY area-matching\n * implementation in the monorepo. Consumers (CLI scan, Cloud managed-editor\n * preview, cross-repo reconciliation) import it; none reimplements glob/area\n * logic. Pure and browser-safe — no Node, no parser deps.\n *\n * See `apps/cloud/docs/topology/01-architecture.md §1`.\n */\n\nexport type AreaCriticality = \"low\" | \"medium\" | \"high\" | \"revenue\" | \"regulated\";\n\nexport interface Area {\n  id: string;\n  name: string;\n  criticality: AreaCriticality;\n  owners: string[];\n  /** Globs matched against repo-relative file paths in v0. */\n  files: string[];\n  /** Stored for later route-topology adapters; NOT matched in v0. */\n  routes?: string[];\n  /** Tie-break: higher wins. Defaults to declaration order. */\n  priority?: number;\n}\n\nexport interface Topology {\n  /** Bump signals \"re-tag\" to consumers that cache. */\n  version: number;\n  /** Whether area file globs are matched relative to app.path or repo root. Defaults to \"app\". */\n  base?: \"app\" | \"repo\";\n  /** Array (not a keyed record) so precedence is deterministic. */\n  areas: Area[];\n}\n\nexport interface AreaMatch {\n  areaId: string;\n  areaName: string;\n  criticality: AreaCriticality;\n  owners: string[];\n  /** The winning pattern — surfaced in reports for transparency. */\n  matchedGlob: string;\n}\n\n/**\n * Compile a minimal glob to an anchored RegExp. We intentionally do NOT depend\n * on picomatch: core stays lean, the surface we need is small, and we want\n * exact control over Next.js route-group parens (`(marketing)` is a literal\n * path segment here, not an extglob group).\n *\n * Semantics:\n *   - `/**` at a segment boundary (end-of-glob or before `/`) → \"this directory\n *     and everything under it\": the leading slash is optional, so\n *     `src/app/checkout/**` matches `src/app/checkout` AND any descendant.\n *   - a bare/leading `**` → matches across path separators (`.*`). Note a\n *     leading globstar-then-slash does NOT match the root (use a lone `**`\n *     for \"everything\").\n *   - `*`   → matches within a single segment (`[^/]*`)\n *   - `?`   → a single non-separator char\n *   - `{a,b}` → alternation `(?:a|b)`\n *   - every other regex-significant char (`.`, `(`, `)`, `+`, …) is literal\n *\n * Throws on a malformed pattern (e.g. an unbalanced `{`). Callers compile via\n * `compile()`, which catches the throw so a config typo degrades one glob to a\n * non-match instead of aborting the whole scan.\n */\nfunction globToRegExp(glob: string): RegExp {\n  let out = \"\";\n  let braceDepth = 0;\n  let i = 0;\n  while (i < glob.length) {\n    const ch = glob[i];\n\n    // `/**` at a segment boundary → optional slash + anything-below. Matches\n    // the directory itself (`a/**` ⇒ `a`) and every descendant.\n    if (\n      ch === \"/\" &&\n      glob[i + 1] === \"*\" &&\n      glob[i + 2] === \"*\" &&\n      (glob[i + 3] === undefined || glob[i + 3] === \"/\")\n    ) {\n      out += \"(?:/.*)?\";\n      i += 3; // consume `/**`; a trailing `/` (in `a/**/b`) is handled next pass\n      continue;\n    }\n\n    // Bare/leading globstar — crosses path separators.\n    if (ch === \"*\" && glob[i + 1] === \"*\") {\n      out += \".*\";\n      i += 2;\n      continue;\n    }\n\n    switch (ch) {\n      case \"*\":\n        out += \"[^/]*\"; // single segment\n        break;\n      case \"?\":\n        out += \"[^/]\";\n        break;\n      case \"{\":\n        braceDepth += 1;\n        out += \"(?:\";\n        break;\n      case \"}\":\n        if (braceDepth > 0) {\n          braceDepth -= 1;\n          out += \")\";\n        } else {\n          out += \"\\\\}\";\n        }\n        break;\n      case \",\":\n        out += braceDepth > 0 ? \"|\" : \",\";\n        break;\n      // Regex-significant chars kept literal (parens cover route groups).\n      case \".\":\n      case \"(\":\n      case \")\":\n      case \"+\":\n      case \"^\":\n      case \"$\":\n      case \"|\":\n      case \"[\":\n      case \"]\":\n      case \"\\\\\":\n        out += `\\\\${ch}`;\n        break;\n      default:\n        out += ch;\n    }\n    i += 1;\n  }\n  return new RegExp(`^${out}$`);\n}\n\ninterface CompiledArea {\n  area: Area;\n  matchers: { glob: string; re: RegExp }[];\n}\n\n/**\n * Cache compiled matchers per topology object. Consumers pass the same\n * `topology` for every finding in a run, so this turns N×globs recompiles into\n * one. A reloaded config is a new object → fresh entry, so `version` bumps need\n * no manual invalidation.\n */\nconst compiledCache = new WeakMap<Topology, CompiledArea[]>();\n\nfunction compile(topology: Topology): CompiledArea[] {\n  const cached = compiledCache.get(topology);\n  if (cached) return cached;\n\n  // Order by (priority desc, declaration order). Decorate-sort-undecorate keeps\n  // the sort stable across engines.\n  const ordered = topology.areas\n    .map((area, index) => ({ area, index }))\n    .sort((a, b) => {\n      const pa = a.area.priority ?? 0;\n      const pb = b.area.priority ?? 0;\n      if (pa !== pb) return pb - pa;\n      return a.index - b.index;\n    })\n    .map(({ area }) => ({\n      area,\n      matchers: area.files.flatMap((glob) => {\n        try {\n          return [{ glob, re: globToRegExp(glob) }];\n        } catch {\n          // A malformed glob (e.g. unbalanced `{`) compiles to an invalid\n          // RegExp. Skip it rather than aborting the entire scan — topology\n          // config is user-authored, so one typo must not take down\n          // `fragments check`. Its files simply fall through to \"Unassigned\".\n          if (typeof console !== \"undefined\") {\n            console.warn(\n              `[topology] ignoring invalid glob in area \"${area.id}\": ${JSON.stringify(glob)}`\n            );\n          }\n          return [];\n        }\n      }),\n    }));\n\n  compiledCache.set(topology, ordered);\n  return ordered;\n}\n\n/** Normalize to a POSIX, repo-relative path before matching. */\nfunction normalizePath(repoRelPath: string): string {\n  return repoRelPath.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\").replace(/^\\/+/, \"\");\n}\n\n/**\n * Resolve the product area for a repo-relative path. First match by\n * `(priority desc, declaration order)`. Returns `null` when nothing matches —\n * the caller buckets that as the explicit \"Unassigned\" area (never dropped;\n * dropping unmatched evidence would make coverage lie).\n */\nexport function resolveArea(repoRelPath: string, topology: Topology): AreaMatch | null {\n  const path = normalizePath(repoRelPath);\n  for (const { area, matchers } of compile(topology)) {\n    for (const { glob, re } of matchers) {\n      if (re.test(path)) {\n        return {\n          areaId: area.id,\n          areaName: area.name,\n          criticality: area.criticality,\n          owners: area.owners,\n          matchedGlob: glob,\n        };\n      }\n    }\n  }\n  return null;\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-RANPUC6C.js

@@ -1,72 +0,0 @@
-// src/compiled-types/index.ts
-var CompiledFragmentsFileValidationError = class extends Error {
-  constructor(source, issues) {
-    super(`Invalid compiled Fragments catalog at ${source}: ${issues.join("; ")}`);
-    this.source = source;
-    this.issues = issues;
-    this.name = "CompiledFragmentsFileValidationError";
-  }
-  source;
-  issues;
-};
-function parseCompiledFragmentsFile(input, source = "fragments.json") {
-  let value = input;
-  if (typeof input === "string") {
-    try {
-      value = JSON.parse(input);
-    } catch (error) {
-      throw new CompiledFragmentsFileValidationError(source, [
-        `invalid JSON (${error instanceof Error ? error.message : String(error)})`
-      ]);
-    }
-  }
-  const issues = [];
-  if (!isRecord(value)) {
-    throw new CompiledFragmentsFileValidationError(source, ["root must be an object"]);
-  }
-  if (typeof value.version !== "string" || value.version.length === 0) {
-    issues.push("version must be a non-empty string");
-  }
-  if (typeof value.generatedAt !== "string" || value.generatedAt.length === 0) {
-    issues.push("generatedAt must be a non-empty string");
-  }
-  if (!isRecord(value.fragments)) {
-    issues.push("fragments must be an object");
-  } else {
-    for (const [key, fragment] of Object.entries(value.fragments)) {
-      validateCompiledFragment(key, fragment, issues);
-    }
-  }
-  if (value.graph !== void 0) {
-    if (!isRecord(value.graph) || !Array.isArray(value.graph.nodes) || !Array.isArray(value.graph.edges) || !isRecord(value.graph.health)) {
-      issues.push("graph must contain nodes[], edges[], and health");
-    }
-  }
-  if (issues.length > 0) throw new CompiledFragmentsFileValidationError(source, issues);
-  return value;
-}
-function validateCompiledFragment(key, value, issues) {
-  const path = `fragments.${key}`;
-  if (!isRecord(value)) {
-    issues.push(`${path} must be an object`);
-    return;
-  }
-  if (typeof value.filePath !== "string") issues.push(`${path}.filePath must be a string`);
-  if (!isRecord(value.meta) || typeof value.meta.name !== "string") {
-    issues.push(`${path}.meta.name must be a string`);
-  }
-  if (!isRecord(value.props)) issues.push(`${path}.props must be an object`);
-  if (!Array.isArray(value.variants)) issues.push(`${path}.variants must be an array`);
-  if (!isRecord(value.usage) || !Array.isArray(value.usage.when) || !Array.isArray(value.usage.whenNot)) {
-    issues.push(`${path}.usage must contain when[] and whenNot[]`);
-  }
-}
-function isRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-export {
-  CompiledFragmentsFileValidationError,
-  parseCompiledFragmentsFile
-};
-//# sourceMappingURL=chunk-RANPUC6C.js.map

package/dist/chunk-RANPUC6C.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/compiled-types/index.ts"],"sourcesContent":["/**\n * Compiled fragment types — shared between CLI and MCP packages.\n *\n * These are the JSON-serializable types used in fragments.json and consumed\n * by AI agents, MCP servers, and context generators.\n */\n\nimport type { ComponentGovernanceRecord } from '../governance.js';\n\n/**\n * Component metadata\n */\nexport interface FragmentMeta {\n  name: string;\n  description: string;\n  category: string;\n  tags?: string[];\n  status?: \"stable\" | \"beta\" | \"deprecated\" | \"experimental\";\n  since?: string;\n  dependencies?: Array<{ name: string; version: string; reason?: string }>;\n  figma?: string;\n  figmaProps?: Record<string, unknown>;\n}\n\n/**\n * Usage guidelines for AI agents and developers\n */\nexport interface FragmentUsage {\n  when: string[];\n  whenNot: string[];\n  guidelines?: string[];\n  accessibility?: string[];\n}\n\n/**\n * Definition for a single prop\n */\nexport interface PropDefinition {\n  type: string;\n  values?: readonly string[];\n  default?: unknown;\n  description: string;\n  required?: boolean;\n  constraints?: string[];\n  typeDetails?: Record<string, unknown>;\n  controlType?: string;\n  controlOptions?: {\n    min?: number;\n    max?: number;\n    step?: number;\n    presetColors?: string[];\n  };\n}\n\n/**\n * Relationship to another component\n */\nexport interface ComponentRelation {\n  component: string;\n  relationship: string;\n  note: string;\n}\n\n/**\n * Agent-optimized contract metadata\n */\nexport interface FragmentContract {\n  propsSummary?: string[];\n  a11yRules?: string[];\n  bans?: Array<{ pattern: string; message: string }>;\n  scenarioTags?: string[];\n  /** Per-component performance budget override in bytes (gzipped) */\n  performanceBudget?: number;\n  /** Sub-component slot metadata for compound components */\n  compoundChildren?: Record<string, {\n    required?: boolean;\n    accepts?: string[];\n    description?: string;\n  }>;\n  /** Canonical JSX usage examples showing how to assemble the component */\n  canonicalUsage?: string[];\n}\n\n/**\n * Provenance tracking for generated fragments\n */\nexport interface FragmentGenerated {\n  source: \"storybook\" | \"manual\" | \"ai\" | \"extracted\" | \"merged\" | \"migrated\";\n  sourceFile?: string;\n  /** @deprecated Use provenance.verified instead */\n  confidence?: number;\n  verified?: boolean;\n  timestamp?: string;\n}\n\n/**\n * AI-specific metadata\n */\nexport interface AIMetadata {\n  compositionPattern?: \"compound\" | \"simple\" | \"controlled\" | \"wrapper\";\n  subComponents?: string[];\n  requiredChildren?: string[];\n  commonPatterns?: string[];\n}\n\n/**\n * Performance data for a component (from bundle size measurement)\n */\n/**\n * A single import contributing to bundle size\n */\nexport interface ImportEntry {\n  /** Resolved file path (relative to project root) */\n  path: string;\n  /** Bytes contributed to the bundle */\n  bytes: number;\n  /** Percentage of total bundle size */\n  percent: number;\n}\n\nexport interface PerformanceData {\n  /** Gzipped bundle size in bytes */\n  bundleSize: number;\n  /** Raw (minified, not gzipped) bundle size in bytes */\n  rawSize: number;\n  /** Complexity classification */\n  complexity: 'lightweight' | 'moderate' | 'heavy';\n  /** Percentage of budget used (0-100+) */\n  budgetPercent: number;\n  /** Whether the component exceeds its budget */\n  overBudget: boolean;\n  /** ISO timestamp when measured */\n  measuredAt: string;\n  /** Top imports by size (largest first) */\n  imports?: ImportEntry[];\n}\n\nexport interface ObservedUsageProp {\n  name: string;\n  kind: 'static' | 'dynamic' | 'spread' | 'jsx' | 'boolean' | 'null';\n  value?: string | number | boolean | null;\n}\n\nexport interface ObservedComponentUsage {\n  /** Source file path relative to the fragments config root */\n  file: string;\n  /** 1-indexed source line */\n  line: number;\n  /** 0-indexed source column */\n  column: number;\n  props: ObservedUsageProp[];\n  parentElement?: string;\n  conditional?: boolean;\n}\n\n/**\n * Compiled fragment data (JSON-serializable for AI consumption)\n */\nexport interface CompiledFragment {\n  filePath: string;\n  meta: FragmentMeta;\n  /** Canonical v2 guidance. `usage` is retained for compatibility. */\n  guidance?: FragmentUsage;\n  usage: FragmentUsage;\n  props: Record<string, PropDefinition>;\n  /** Normalized component governance records emitted from *.fragment.ts. */\n  governance?: ComponentGovernanceRecord[];\n  relations?: ComponentRelation[];\n  variants: Array<{\n    name: string;\n    description: string;\n    code?: string;\n    figma?: string;\n    args?: Record<string, unknown>;\n  }>;\n  contract?: FragmentContract;\n  ai?: AIMetadata;\n  /** Framework hint from contract, used by preview adapters and Cloud */\n  framework?: string;\n  /** Top-level compact prop summaries for agent first-pass */\n  propsSummary?: string[];\n  /** Source file path relative to config root (for contract-sourced fragments) */\n  sourcePath?: string;\n  /** Named export for preview adapter resolution */\n  exportName?: string;\n  /** Clean provenance tracking (V2) */\n  provenance?: {\n    source: string;\n    verified: boolean;\n    frameworkSupport?: string;\n    sourceHash?: string;\n    extractedAt?: string;\n  };\n  /** Component performance data from bundle size measurement */\n  performance?: PerformanceData;\n  /** Observed JSX call sites captured during `fragments scan` */\n  usages?: ObservedComponentUsage[];\n  _generated?: FragmentGenerated;\n}\n\n/**\n * Compiled block data (JSON-serializable for AI consumption)\n */\nexport interface CompiledBlock {\n  filePath: string;\n  name: string;\n  description: string;\n  category: string;\n  components: string[];\n  code: string;\n  tags?: string[];\n}\n\n/**\n * A single token entry in the compiled output\n */\nexport interface CompiledTokenEntry {\n  name: string;\n  value?: string;\n  description?: string;\n}\n\n/**\n * Compiled token data stored in fragments.json\n */\nexport interface CompiledTokenData {\n  prefix: string;\n  total: number;\n  categories: Record<string, CompiledTokenEntry[]>;\n}\n\n/**\n * Performance summary across all components\n */\nexport interface PerformanceSummary {\n  /** Preset name used */\n  preset: string;\n  /** Budget applied in bytes */\n  budget: number;\n  /** Total components measured */\n  total: number;\n  /** Number of components over budget */\n  overBudget: number;\n  /** Distribution by tier */\n  tiers: Record<string, number>;\n}\n\n/**\n * The compiled fragments.json structure\n */\nexport interface CompiledFragmentsFile {\n  version: string;\n  generatedAt: string;\n  /** CLI version that produced this file, used for freshness checks */\n  generatorVersion?: string;\n  /** Relative source/config inputs used to build this file, used for freshness checks */\n  buildInputs?: string[];\n  packageName?: string;\n  fragments: Record<string, CompiledFragment>;\n  blocks?: Record<string, CompiledBlock>;\n  tokens?: CompiledTokenData;\n  /** Component relationship graph for AI structural queries */\n  graph?: import('../graph/types.js').SerializedComponentGraph;\n  /** Performance measurement summary */\n  performanceSummary?: PerformanceSummary;\n  /** @deprecated Use blocks instead */\n  recipes?: Record<string, CompiledBlock>;\n}\n\nexport class CompiledFragmentsFileValidationError extends Error {\n  constructor(\n    readonly source: string,\n    readonly issues: string[]\n  ) {\n    super(`Invalid compiled Fragments catalog at ${source}: ${issues.join(\"; \")}`);\n    this.name = \"CompiledFragmentsFileValidationError\";\n  }\n}\n\nexport function parseCompiledFragmentsFile(\n  input: string | unknown,\n  source = \"fragments.json\"\n): CompiledFragmentsFile {\n  let value: unknown = input;\n  if (typeof input === \"string\") {\n    try {\n      value = JSON.parse(input);\n    } catch (error) {\n      throw new CompiledFragmentsFileValidationError(source, [\n        `invalid JSON (${error instanceof Error ? error.message : String(error)})`,\n      ]);\n    }\n  }\n\n  const issues: string[] = [];\n  if (!isRecord(value)) {\n    throw new CompiledFragmentsFileValidationError(source, [\"root must be an object\"]);\n  }\n  if (typeof value.version !== \"string\" || value.version.length === 0) {\n    issues.push(\"version must be a non-empty string\");\n  }\n  if (typeof value.generatedAt !== \"string\" || value.generatedAt.length === 0) {\n    issues.push(\"generatedAt must be a non-empty string\");\n  }\n  if (!isRecord(value.fragments)) {\n    issues.push(\"fragments must be an object\");\n  } else {\n    for (const [key, fragment] of Object.entries(value.fragments)) {\n      validateCompiledFragment(key, fragment, issues);\n    }\n  }\n  if (value.graph !== undefined) {\n    if (\n      !isRecord(value.graph) ||\n      !Array.isArray(value.graph.nodes) ||\n      !Array.isArray(value.graph.edges) ||\n      !isRecord(value.graph.health)\n    ) {\n      issues.push(\"graph must contain nodes[], edges[], and health\");\n    }\n  }\n  if (issues.length > 0) throw new CompiledFragmentsFileValidationError(source, issues);\n  return value as unknown as CompiledFragmentsFile;\n}\n\nfunction validateCompiledFragment(key: string, value: unknown, issues: string[]): void {\n  const path = `fragments.${key}`;\n  if (!isRecord(value)) {\n    issues.push(`${path} must be an object`);\n    return;\n  }\n  if (typeof value.filePath !== \"string\") issues.push(`${path}.filePath must be a string`);\n  if (!isRecord(value.meta) || typeof value.meta.name !== \"string\") {\n    issues.push(`${path}.meta.name must be a string`);\n  }\n  if (!isRecord(value.props)) issues.push(`${path}.props must be an object`);\n  if (!Array.isArray(value.variants)) issues.push(`${path}.variants must be an array`);\n  if (\n    !isRecord(value.usage) ||\n    !Array.isArray(value.usage.when) ||\n    !Array.isArray(value.usage.whenNot)\n  ) {\n    issues.push(`${path}.usage must contain when[] and whenNot[]`);\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\n/**\n * Theme identifier\n */\nexport type Theme = \"light\" | \"dark\";\n\n/**\n * Verification result\n */\nexport interface VerifyResult {\n  verdict: \"pass\" | \"fail\" | \"error\";\n  matches: boolean;\n  diffPercentage: number;\n  screenshot: string;\n  baseline: string;\n  diffImage?: string;\n  notes: string[];\n  error?: string;\n  timing: {\n    renderMs: number;\n    captureMs: number;\n    diffMs: number;\n    totalMs: number;\n  };\n}\n"],"mappings":";AA6QO,IAAM,uCAAN,cAAmD,MAAM;AAAA,EAC9D,YACW,QACA,QACT;AACA,UAAM,yCAAyC,MAAM,KAAK,OAAO,KAAK,IAAI,CAAC,EAAE;AAHpE;AACA;AAGT,SAAK,OAAO;AAAA,EACd;AAAA,EALW;AAAA,EACA;AAKb;AAEO,SAAS,2BACd,OACA,SAAS,kBACc;AACvB,MAAI,QAAiB;AACrB,MAAI,OAAO,UAAU,UAAU;AAC7B,QAAI;AACF,cAAQ,KAAK,MAAM,KAAK;AAAA,IAC1B,SAAS,OAAO;AACd,YAAM,IAAI,qCAAqC,QAAQ;AAAA,QACrD,iBAAiB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAAA,MACzE,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,SAAmB,CAAC;AAC1B,MAAI,CAAC,SAAS,KAAK,GAAG;AACpB,UAAM,IAAI,qCAAqC,QAAQ,CAAC,wBAAwB,CAAC;AAAA,EACnF;AACA,MAAI,OAAO,MAAM,YAAY,YAAY,MAAM,QAAQ,WAAW,GAAG;AACnE,WAAO,KAAK,oCAAoC;AAAA,EAClD;AACA,MAAI,OAAO,MAAM,gBAAgB,YAAY,MAAM,YAAY,WAAW,GAAG;AAC3E,WAAO,KAAK,wCAAwC;AAAA,EACtD;AACA,MAAI,CAAC,SAAS,MAAM,SAAS,GAAG;AAC9B,WAAO,KAAK,6BAA6B;AAAA,EAC3C,OAAO;AACL,eAAW,CAAC,KAAK,QAAQ,KAAK,OAAO,QAAQ,MAAM,SAAS,GAAG;AAC7D,+BAAyB,KAAK,UAAU,MAAM;AAAA,IAChD;AAAA,EACF;AACA,MAAI,MAAM,UAAU,QAAW;AAC7B,QACE,CAAC,SAAS,MAAM,KAAK,KACrB,CAAC,MAAM,QAAQ,MAAM,MAAM,KAAK,KAChC,CAAC,MAAM,QAAQ,MAAM,MAAM,KAAK,KAChC,CAAC,SAAS,MAAM,MAAM,MAAM,GAC5B;AACA,aAAO,KAAK,iDAAiD;AAAA,IAC/D;AAAA,EACF;AACA,MAAI,OAAO,SAAS,EAAG,OAAM,IAAI,qCAAqC,QAAQ,MAAM;AACpF,SAAO;AACT;AAEA,SAAS,yBAAyB,KAAa,OAAgB,QAAwB;AACrF,QAAM,OAAO,aAAa,GAAG;AAC7B,MAAI,CAAC,SAAS,KAAK,GAAG;AACpB,WAAO,KAAK,GAAG,IAAI,oBAAoB;AACvC;AAAA,EACF;AACA,MAAI,OAAO,MAAM,aAAa,SAAU,QAAO,KAAK,GAAG,IAAI,4BAA4B;AACvF,MAAI,CAAC,SAAS,MAAM,IAAI,KAAK,OAAO,MAAM,KAAK,SAAS,UAAU;AAChE,WAAO,KAAK,GAAG,IAAI,6BAA6B;AAAA,EAClD;AACA,MAAI,CAAC,SAAS,MAAM,KAAK,EAAG,QAAO,KAAK,GAAG,IAAI,0BAA0B;AACzE,MAAI,CAAC,MAAM,QAAQ,MAAM,QAAQ,EAAG,QAAO,KAAK,GAAG,IAAI,4BAA4B;AACnF,MACE,CAAC,SAAS,MAAM,KAAK,KACrB,CAAC,MAAM,QAAQ,MAAM,MAAM,IAAI,KAC/B,CAAC,MAAM,QAAQ,MAAM,MAAM,OAAO,GAClC;AACA,WAAO,KAAK,GAAG,IAAI,0CAA0C;AAAA,EAC/D;AACF;AAEA,SAAS,SAAS,OAAkD;AAClE,SAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK;AAC5E;","names":[]}