@usefragments/core 1.10.2 → 1.11.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;
+}
 
-  /** Include full fragment data in registry (default: false - reference fragmentPath instead) */
-  embedFragments?: boolean;
+/** 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[]>;
+}
+
+/** 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.
@@ -776,9 +1007,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 +1298,9 @@ export interface VerifyResult {
 // Compiled types — re-exported from ./compiled-types.
 export type {
   CompiledFragment,
+  CompiledFragmentDesign,
+  CompiledFragmentMatrix,
+  CompiledFragmentPreview,
   CompiledBlock,
   CompiledTokenEntry,
   CompiledTokenData,
@@ -1092,13 +1323,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-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":[]}