@usefragments/core 1.10.2 → 1.11.0

package/src/governance.ts

@@ -133,10 +133,15 @@ const componentCapabilityRecordSchema = z.object({
   capability: z.string().min(1),
 });
 
+const requiredComponentGovernanceValueSchema = z.custom<unknown>(
+  (value) => value !== undefined,
+  "Expected an explicitly present governance value"
+);
+
 const propValueAvoidRecordSchema = z.object({
   kind: z.literal("prop.value.avoid"),
   prop: z.string().min(1),
-  value: z.unknown(),
+  value: requiredComponentGovernanceValueSchema,
   because: z.string(),
   suggest: z.string().optional(),
   severity: governanceSeveritySchema,
@@ -145,10 +150,10 @@ const propValueAvoidRecordSchema = z.object({
 const propValueForbidRecordSchema = z.object({
   kind: z.literal("prop.value.forbid"),
   prop: z.string().min(1),
-  value: z.unknown(),
+  value: requiredComponentGovernanceValueSchema,
   when: z.object({ path: z.string().min(1).optional() }).optional(),
   because: z.string(),
-  fix: z.object({ replaceWith: z.unknown() }).optional(),
+  fix: z.object({ replaceWith: requiredComponentGovernanceValueSchema }).optional(),
   severity: governanceSeveritySchema,
 });
 
@@ -587,10 +592,15 @@ export interface ComponentGovernanceBuilder<TProps> {
   accessibility(): AccessibilityGovernanceBuilder;
 }
 
-export interface GovernedFragmentDefinition<
+/**
+ * One-argument governed definition. Requires an explicit `govern` function
+ * and/or `governance` records — both optional keys previously let plain v2
+ * definitions satisfy this type (the optional-key type lie).
+ */
+type GovernedFragmentDefinitionBase<
   TProps = unknown,
   TComponent extends FragmentComponent<TProps> = FragmentComponent<TProps>,
-> {
+> = {
   component: TComponent;
   meta: FragmentMeta;
   guidance: FragmentGuidance;
@@ -605,9 +615,22 @@ export interface GovernedFragmentDefinition<
   };
   contract?: FragmentContract;
   _provenance?: FragmentProvenance;
-  govern?: (g: ComponentGovernanceBuilder<TProps>) => ComponentGovernanceRecord[];
-  governance?: ComponentGovernanceRecord[];
-}
+};
+
+export type GovernedFragmentDefinition<
+  TProps = unknown,
+  TComponent extends FragmentComponent<TProps> = FragmentComponent<TProps>,
+> = GovernedFragmentDefinitionBase<TProps, TComponent> &
+  (
+    | {
+        govern: (g: ComponentGovernanceBuilder<TProps>) => ComponentGovernanceRecord[];
+        governance?: ComponentGovernanceRecord[];
+      }
+    | {
+        governance: ComponentGovernanceRecord[];
+        govern?: (g: ComponentGovernanceBuilder<TProps>) => ComponentGovernanceRecord[];
+      }
+  );
 
 export type ResolvedGovernedFragmentDefinition<
   TProps = unknown,
@@ -668,6 +691,27 @@ export function resolveComponentGovernance<TProps>(
   return componentGovernanceRecordsSchema.parse(records);
 }
 
+/**
+ * Resolve the component governance records that belong in the FCID preimage.
+ *
+ * Prefer an already-resolved `governance` array (Cloud mint / compiled payloads).
+ * Fall back to evaluating `govern` when present. Returns `undefined` when the
+ * fragment carries no governance surface — callers omit the field from identity.
+ */
+export function resolveGovernanceRecordsForIdentity(
+  definition: Pick<GovernedFragmentDefinition, "govern" | "governance"> | null | undefined
+): ComponentGovernanceRecord[] | undefined {
+  if (!definition) return undefined;
+  if (Array.isArray(definition.governance)) {
+    return componentGovernanceRecordsSchema.parse(definition.governance);
+  }
+  if (typeof definition.govern === "function") {
+    const builder = createComponentGovernanceBuilder();
+    return componentGovernanceRecordsSchema.parse(definition.govern(builder));
+  }
+  return undefined;
+}
+
 export function normalizeGovernanceConfig<TConfig extends { govern?: GovernanceConfig }>(
   config: TConfig
 ): TConfig {

package/src/index.ts

@@ -4,7 +4,7 @@
  */
 
 // Brand and default constants
-export { BRAND, DEFAULTS } from "./constants.js";
+export { BRAND, DEFAULTS, FRAGMENT_V3_SCHEMA_URL } from "./constants.js";
 export type { Brand, Defaults } from "./constants.js";
 
 export {
@@ -167,14 +167,20 @@ export type {
   FragmentsConfig,
   SnippetPolicyConfig,
   RegistryOptions,
+  FragmentIndex,
+  FragmentRegistry,
+  RegistryComponentEntry,
+  RegistryPropEntry,
+  FragmentContextOptions,
   CompiledFragment,
+  CompiledFragmentDesign,
+  CompiledFragmentMatrix,
+  CompiledFragmentPreview,
   CompiledFragmentsFile,
   ObservedComponentUsage,
   ObservedUsageProp,
   BlockDefinition,
   CompiledBlock,
-  RecipeDefinition, // @deprecated - use BlockDefinition
-  CompiledRecipe, // @deprecated - use CompiledBlock
   // Contract and provenance types
   FragmentContract,
   FragmentGenerated,
@@ -186,6 +192,18 @@ export type {
   CompositionMetadata,
   FragmentProvenance,
   FragmentDefinitionV2,
+  // v3 types (arity-discriminated)
+  FragmentMetaV3,
+  FragmentStateV3,
+  FragmentDontExampleV3,
+  FragmentGuidanceV3,
+  FragmentMatrixV3,
+  FragmentPreviewV3,
+  FragmentDesignV3,
+  PropAnnotation,
+  FragmentAnnotationsV3,
+  FragmentDefinitionV3Body,
+  FragmentDefinitionV3,
   // Screenshot types
   ScreenshotConfig,
   ServiceConfig,
@@ -207,8 +225,6 @@ export type {
   FigmaInstanceMapping,
   FigmaChildrenMapping,
   FigmaTextContentMapping,
-  // Storybook filter configuration
-  StorybookFilterConfig,
   // Token configuration
   AppConfig,
   DesignSystemConfig,
@@ -284,12 +300,18 @@ export type {
 // Fragments Registry Protocol contracts
 export {
   REGISTRY_ARTIFACT_SCHEMA_VERSION,
+  REGISTRY_INDEX_SCHEMA_VERSION,
   REGISTRY_INSTALL_RECEIPT_SCHEMA_VERSION,
   REGISTRY_MANIFEST_SCHEMA_VERSION,
+  REGISTRY_POINTER_SCHEMA_VERSION,
+  REGISTRY_SHARD_SCHEMA_VERSION,
+  assembleRegistryArtifact,
   assertValidRegistryArtifact,
   buildRegistryArtifact,
   buildRegistryFile,
+  buildRegistryPointer,
   computeRegistryHash,
+  defaultRegistryShardPath,
   finalizeRegistryManifest,
   hashRegistryFileContent,
   registryArtifactDigest,
@@ -303,14 +325,21 @@ export {
   registryFileRoleSchema,
   registryFileSchema,
   registryFileSize,
+  registryIndexSchema,
   registryInstallProfileSchema,
   registryInstallReceiptComponentSchema,
   registryInstallReceiptFileSchema,
   registryInstallReceiptSchema,
   registryManifestCanonicalPreimage,
   registryManifestDraftSchema,
+  registryManifestFileMetadata,
+  registryManifestFilePaths,
   registryManifestSchema,
+  registryPointerSchema,
+  registryShardSchema,
+  registryShardsForPaths,
   registrySourceSchema,
+  shardRegistryArtifact,
 } from "./registry.js";
 export type {
   RegistryArtifact,
@@ -324,13 +353,17 @@ export type {
   RegistryFileContent,
   RegistryFileInput,
   RegistryFileRole,
+  RegistryIndex,
   RegistryInstallProfile,
   RegistryInstallReceipt,
   RegistryInstallReceiptComponent,
   RegistryInstallReceiptFile,
   RegistryManifest,
   RegistryManifestDraft,
+  RegistryPointer,
+  RegistryShard,
   RegistrySource,
+  ShardedRegistryArtifact,
 } from "./registry.js";
 
 export {
@@ -338,13 +371,21 @@ export {
   buildRegistryInstallPlan,
   buildRegistryInstallReceipt,
   collectRegistryInstallDependencies,
+  expandRegistryComponentClosure,
   normalizeRegistryRepoPath,
-  selectedRegistryComponentNames,
+  resolveRegistryComponentId,
+  resolveRegistryInstallSelection,
+  resolveRegistryInstallSources,
   sourceToRegistryTargetPath,
 } from "./registry-install-plan.js";
 export type {
   BuildRegistryInstallPlanInput,
   RegistryInstallPlan,
+  RegistryInstallSelection,
+  RegistryInstallSelectionInput,
+  RegistryInstallSourceFile,
+  RegistryInstallSources,
+  RegistryInstallSourcesInput,
   RegistryWritePlan,
 } from "./registry-install-plan.js";
 
@@ -427,10 +468,10 @@ export {
   figmaPropMappingSchema,
   // Contract and provenance schemas
   fragmentContractSchema,
+  fragmentSourceValues,
   fragmentGeneratedSchema,
   fragmentBanSchema,
   blockDefinitionSchema,
-  recipeDefinitionSchema, // @deprecated - use blockDefinitionSchema
   // AI metadata schema
   aiMetadataSchema,
   // v2 schemas
@@ -438,6 +479,18 @@ export {
   fragmentProvenanceSchema,
   fragmentDefinitionV2Schema,
   governedFragmentDefinitionSchema,
+  // v3 schemas
+  fragmentMetaV3Schema,
+  fragmentStateV3Schema,
+  fragmentDontExampleV3Schema,
+  fragmentGuidanceV3Schema,
+  fragmentMatrixV3Schema,
+  fragmentPreviewV3Schema,
+  fragmentDesignV3Schema,
+  propAnnotationSchema,
+  fragmentAnnotationsV3Schema,
+  fragmentDefinitionV3BodySchema,
+  fragmentDefinitionV3Schema,
 } from "./schema.js";
 
 // Main API
@@ -448,8 +501,6 @@ export {
   normalizeToV1,
   defineBlock,
   compileBlock,
-  defineRecipe,
-  compileRecipe,
 } from "./defineFragment.js";
 export type { InferProps } from "./defineFragment.js";
 
@@ -467,6 +518,8 @@ export {
   isPresetSourcedRule,
   markPresetSourcedRules,
   normalizeGovernanceConfig,
+  resolveComponentGovernance,
+  resolveGovernanceRecordsForIdentity,
   scaleGovernanceRecordSchema,
 } from "./governance.js";
 export type {
@@ -501,15 +554,6 @@ export {
 } from "./policy-exclude.js";
 export type { PolicyExclude, PolicyExcludeInput } from "./policy-exclude.js";
 
-// Storybook adapter filtering
-export {
-  checkStoryExclusion,
-  detectSubComponentPaths,
-  isForceIncluded,
-  isConfigExcluded,
-} from "./storyFilters.js";
-export type { ExclusionReason, ExclusionResult, CheckStoryExclusionOpts } from "./storyFilters.js";
-
 // Context generation for AI agents
 export { generateContext } from "./context.js";
 export type { ContextOptions, ContextResult } from "./context.js";
@@ -517,23 +561,6 @@ export type { ContextOptions, ContextResult } from "./context.js";
 // Figma property mapping DSL
 export { figma, isFigmaPropMapping, resolveFigmaMapping } from "./figma.js";
 
-// Fragment JSON types (for .fragment.json files)
-export type {
-  Fragment,
-  FragmentFigma,
-  FragmentUsage as FragmentJsonUsage,
-  FragmentDoNotItem,
-  FragmentPattern,
-  FragmentAccessibility,
-  FragmentRelated,
-  FragmentMeta as FragmentJsonMeta,
-  FragmentIndex,
-  FragmentRegistry,
-  RegistryComponentEntry,
-  RegistryPropEntry,
-  FragmentContextOptions,
-} from "./fragment-types.js";
-
 // Token parsing and token-domain helpers
 export {
   calculateDeltaE,
@@ -649,6 +676,12 @@ export {
   ruleA11yRequiredAccessibleName,
   ruleA11yStandard,
 } from "./rules/index.js";
+export {
+  capConfiguredSeverity,
+  configuredFindingSeverity,
+  readRuleConfig,
+  type RuleConfigView,
+} from "./rules/rule-config.js";
 export { indexComponentIdentityUsage, type ComponentIdentityUsage } from "./identity/usage.js";
 export { nearestSignedScaleValue } from "./rules/utils.js";
 export {
@@ -705,7 +738,11 @@ export type { RuleTier, PresetRuleState } from "./rules/index.js";
 // Contract-site health denominator: how many style-declaration sites the
 // token-vocabulary rule actually judged. Consumed by the CLI's per-scan
 // `contract-site-health:v1` metric next to the identity usage index.
-export { contractTokenReferenceCensus } from "./rules/index.js";
+export {
+  contractTokenReferenceCensus,
+  EMPTY_VOCABULARY_MESSAGE,
+  emptyVocabularyConfigFile,
+} from "./rules/index.js";
 export type { ContractTokenReferenceCensus } from "./rules/index.js";
 
 // Rule families — the ONE expansion of a broad `govern.rules` id (`tokens/hardcoded-values`)
@@ -826,24 +863,39 @@ export {
 } from "./facts/index.js";
 export type { SupersededImportPathPreference } from "./facts/index.js";
 export {
-  canonicalPreimage,
   AGENT_CONTEXT_RELATIVE_PATH,
+  artifactContentHash,
   CATALOG_FIXTURE_A_FCID,
   catalogFixtureA,
   catalogFixtureAContractPayload,
   catalogFixtureATokensDtcg,
+  canonicalPreimage,
+  CONTRACT_DISPLAY_ONLY_FIELDS,
   CONTRACT_DOMAINS,
+  CONTRACT_ENFORCEMENT_FIELDS,
   CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
+  ContractCatalogValidationError,
   contractComponentsFromFragments,
   contractHash,
   contractPolicyFromGovernanceConfig,
+  deriveArtifactId,
   diffContractDomains,
   formatStampHeader,
   formatStampPin,
   formatStampVersionHash,
+  FRAGMENTS_MANIFEST_FILENAME,
+  FRAGMENTS_MANIFEST_SCHEMA_VERSION,
+  FRAGMENTS_MANIFEST_TOKEN_RULE,
+  fragmentsManifestFcid,
+  fragmentsManifestGrammarSchema,
+  fragmentsManifestPatternSchema,
+  fragmentsManifestPrimitiveSchema,
+  fragmentsManifestSchema,
   parseContractStamp,
+  parseFragmentsManifest,
   projectContractPreimage,
+  projectEnforcementContract,
   serializeContractStamp,
   sha256Hex,
   verifiedContractPreimageFromPin,
@@ -866,6 +918,7 @@ export type {
   ContractCatalogInput,
   ContractComponentInput,
   ContractDomain,
+  ContractEnforcementField,
   ContractIdentityPin,
   ContractPolicyInput,
   ContractPreimage,
@@ -874,6 +927,10 @@ export type {
   ContractStampRecord,
   ContractTokenInput,
   ContractWaiverInput,
+  FragmentsManifest,
+  FragmentsManifestGrammar,
+  FragmentsManifestPattern,
+  FragmentsManifestPrimitive,
 } from "./contract/index.js";
 export {
   governanceConfigWithLocalCanonical,
@@ -920,6 +977,9 @@ export type {
   FactLocation,
   FactEvidence,
   CanonicalCandidateFact,
+  CanonicalFactConflictV1,
+  CanonicalFactConflictValueV1,
+  CanonicalFactIntegrityV1,
   CanonicalMappingFact,
   CanonicalReplacementFact,
   ComponentLevelFact,
@@ -978,8 +1038,210 @@ export type {
   SuppressionDirectiveFact,
   ComponentFactInput,
 } from "./facts/index.js";
+export {
+  CANONICAL_FACT_MAX_CONFLICTS_V1,
+  CANONICAL_FACT_MAX_PROVENANCE_PER_VALUE_V1,
+  CANONICAL_FACT_MAX_VALUES_PER_CONFLICT_V1,
+  canonicalFactConflictV1Schema,
+  canonicalFactConflictValueV1Schema,
+  canonicalFactIntegrityV1Schema,
+  normalizeCanonicalFactIntegrityV1,
+} from "./facts/index.js";
+
+// V1 authority and analysis contracts. These remain browser-safe and have no
+// Cloud, provider, engine, model, or Node-only dependency.
+export {
+  analysisPlanIdFromDigest,
+  analysisPlanIdSchema,
+  analysisPlanIdStringSchema,
+  digestHexSchema,
+  digestHexStringSchema,
+  evaluationReceiptIdFromDigest,
+  mintEvaluationReceiptId,
+  evaluationReceiptIdSchema,
+  evaluationReceiptIdStringSchema,
+  featurePlanIdFromEntropy,
+  featurePlanIdSchema,
+  featurePlanIdStringSchema,
+  featureRevisionIdFromDigest,
+  featureRevisionIdSchema,
+  featureRevisionIdStringSchema,
+  parseAnalysisPlanId,
+  parseDigestHex,
+  parseEvaluationReceiptId,
+  parseFeaturePlanId,
+  parseFeatureRevisionId,
+} from "./domain-ids.js";
+export type {
+  AnalysisPlanId,
+  DigestHex,
+  EvaluationReceiptId,
+  FeaturePlanId,
+  FeatureRevisionId,
+} from "./domain-ids.js";
+export {
+  PROVIDER_ID_MAX_BYTES_V1,
+  REPOSITORY_BINDING_ID_MAX_BYTES_V1,
+  normalizeRepositoryBindingKeyV1,
+  repositoryBindingDigestV1,
+  repositoryBindingKeyV1Schema,
+} from "./repository-binding.js";
+export type { RepositoryBindingKeyV1, RepositoryBindingKeyV1Input } from "./repository-binding.js";
+export {
+  ANALYSIS_LIMIT_CEILINGS_V1,
+  ANALYSIS_PLAN_MAX_CAPABILITIES_V1,
+  ANALYSIS_PLAN_MAX_DIALECTS_PER_REGION_V1,
+  ANALYSIS_PLAN_MAX_REGIONS_V1,
+  CoverageValidationErrorV1,
+  analysisLimitsV1Schema,
+  analysisObligationsDigestV1,
+  analysisPlanDigestV1,
+  analysisPlanInputV1Schema,
+  analysisPlanV1Schema,
+  analysisRegionV1Schema,
+  buildAnalysisPlanV1,
+  coverageArtifactDigestV1,
+  coverageRegionV1Schema,
+  coverageStateV1Schema,
+  coverageSummaryV1Schema,
+  deriveCoverageSummaryV1,
+  normalizeAnalysisPlanInputV1,
+  parseAnalysisPlanV1,
+} from "./analysis-plan/index.js";
+export type {
+  AnalysisLimitsV1,
+  AnalysisPlanInputV1,
+  AnalysisPlanV1,
+  AnalysisRegionV1,
+  CoverageRegionV1,
+  CoverageStateV1,
+  CoverageSummaryV1,
+} from "./analysis-plan/index.js";
+
+export {
+  AGENT_FEATURE_CONTEXT_MAX_BYTES_V1,
+  FEATURE_PLAN_MAX_ACCEPTANCE_ITEMS_V1,
+  FEATURE_PLAN_MAX_DECISIONS_V1,
+  FEATURE_PLAN_MAX_EVIDENCE_REFS_V1,
+  FEATURE_PLAN_MAX_GAPS_V1,
+  FEATURE_PLAN_MAX_SCENARIOS_V1,
+  FEATURE_PLAN_MAX_TEXT_BYTES_V1,
+  FEATURE_PLAN_MAX_USES_PER_KIND_V1,
+  agentFeatureContextV1Schema,
+  approvedFeatureManifestInputV1Schema,
+  approvedFeatureManifestRevisionDigestV1,
+  approvedFeatureManifestV1Schema,
+  buildApprovedFeatureManifestV1,
+  buildFeatureProposalV1,
+  capabilityGapV1Schema,
+  componentUseDecisionV1Schema,
+  decisionRequestV1Schema,
+  decisionResolutionV1Schema,
+  evidenceRefV1Schema,
+  featureAcceptanceItemV1Schema,
+  featurePinsV1Schema,
+  featureProposalInputV1Schema,
+  featureProposalRevisionDigestV1,
+  featureProposalV1Schema,
+  gapDispositionV1Schema,
+  layoutConcernV1Schema,
+  layoutOwnershipV1Schema,
+  normalizeApprovedFeatureManifestInputV1,
+  normalizeFeatureProposalInputV1,
+  parseAgentFeatureContextV1,
+  parseApprovedFeatureManifestV1,
+  parseFeatureProposalV1,
+  patternStatusV1Schema,
+  patternUseDecisionV1Schema,
+  placementDecisionV1Schema,
+  responsiveDecisionV1Schema,
+  scenarioRequirementV1Schema,
+  tokenUseDecisionV1Schema,
+} from "./feature-plan/index.js";
+export type {
+  AgentFeatureContextV1,
+  ApprovedFeatureManifestInputV1,
+  ApprovedFeatureManifestV1,
+  CapabilityGapV1,
+  ComponentUseDecisionV1,
+  DecisionRequestV1,
+  DecisionResolutionV1,
+  EvidenceRefV1,
+  FeatureAcceptanceItemV1,
+  FeaturePinsV1,
+  FeatureProposalInputV1,
+  FeatureProposalV1,
+  GapDispositionV1,
+  LayoutConcernV1,
+  LayoutOwnershipV1,
+  PatternStatusV1,
+  PatternUseDecisionV1,
+  PlacementDecisionV1,
+  ResponsiveDecisionV1,
+  ScenarioRequirementV1,
+  TokenUseDecisionV1,
+} from "./feature-plan/index.js";
 
 // Topology — map file paths to product areas (area-scoped governance).
 // Also available at the `@usefragments/core/topology` subpath.
 export { resolveArea } from "./topology/index.js";
 export type { Area, AreaCriticality, AreaMatch, Topology } from "./topology/index.js";
+
+// Evaluation Module — the pure governance kernel (architecture spec §§1–2):
+// deterministic verdicts with kernel-owned FCID verification, four-state
+// finding classification, and three-state trust facts. Shipped in shadow mode
+// alongside the legacy CLI/Cloud verdict machines.
+export {
+  EVALUATION_MAX_FINDINGS_V2,
+  EVALUATION_MAX_MAP_ENTRIES_V2,
+  EVALUATION_MAX_POLICY_RULES_V2,
+  EVALUATION_MAX_REASON_CODES_V2,
+  EVALUATION_MAX_WAIVERS_V2,
+  EVALUATION_MAX_WAIVER_MATCHES_V2,
+  EVALUATION_RECEIPT_STRING_MAX_BYTES_V1,
+  EVALUATOR_VERSION,
+  EVALUATOR_VERSION_V2,
+  effectiveEvaluationWaiverV2Schema,
+  evaluate,
+  evaluationInputV2Schema,
+  evaluationReceiptDigestV1,
+  evaluationReceiptMintInputV1Schema,
+  evaluationReceiptV1Schema,
+  evaluationResultV2Schema,
+  parseEvaluationReceiptV1,
+  providerProofDigestV1,
+  providerProofV1Schema,
+} from "./evaluation/index.js";
+export type {
+  EffectivePolicy,
+  EffectiveRulePolicy,
+  EvaluatedFinding,
+  EvaluationBaseline,
+  EvaluationContractInput,
+  EvaluationEvidence,
+  EvaluationFindingInput,
+  EvaluationFindingState,
+  EvaluationInput,
+  EvaluationIntegrityInput,
+  EvaluationMappingTrust,
+  EvaluationReason,
+  EvaluationResult,
+  EvaluationScope,
+  EvaluationSourceTrust,
+  EvaluationTrust,
+  EvaluationVerdict,
+  EvaluationWaiver,
+  EffectiveEvaluationWaiverV2,
+  EvaluationAuthorityV1,
+  EvaluationEvidenceTrustV1,
+  EvaluationInputV2,
+  EvaluationIntegrityInputV2,
+  EvaluationReasonV2,
+  EvaluationReceiptMintInputV1,
+  EvaluationReceiptSemanticV1,
+  EvaluationReceiptV1,
+  EvaluationResultV2,
+  FindingV2,
+  ProviderProofSemanticV1,
+  ProviderProofV1,
+} from "./evaluation/index.js";

package/src/preview/validation.test.ts

@@ -128,6 +128,68 @@ describe("@usefragments/core/preview artifact validation", () => {
     ).toThrow(/unsupported source "storybook"/);
   });
 
+  it("requires component map keys to match unique normalized component keys", () => {
+    const mismatched = {
+      ...manifest,
+      components: {
+        RenamedButton: {
+          ...manifest.components.Button,
+          componentKey: "Button",
+        },
+      },
+    };
+    const duplicated = {
+      ...manifest,
+      components: {
+        Button: manifest.components.Button,
+        " Button ": {
+          ...manifest.components.Button,
+          componentKey: " Button ",
+        },
+      },
+    };
+
+    expect(() =>
+      definePreviewArtifactManifest(mismatched as unknown as PreviewArtifactManifest)
+    ).toThrow(/componentKey must match its components map key/);
+    expect(() =>
+      definePreviewArtifactManifest(duplicated as unknown as PreviewArtifactManifest)
+    ).toThrow(/duplicate normalized componentKey/);
+  });
+
+  it("requires supported previewability values and unique non-empty variant ids", () => {
+    const invalid = {
+      ...manifest,
+      components: {
+        Button: {
+          ...manifest.components.Button,
+          previewability: "unknown",
+          variants: [
+            ...manifest.components.Button.variants,
+            {
+              ...manifest.components.Button.variants[0],
+              id: " default ",
+            },
+            {
+              ...manifest.components.Button.variants[0],
+              id: " ",
+            },
+          ],
+        },
+      },
+    };
+
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/previewability must be one of/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/variants.1.id must be unique within the component/);
+    expect(() =>
+      definePreviewArtifactManifest(invalid as unknown as PreviewArtifactManifest)
+    ).toThrow(/variants.2.id must be a non-empty string/);
+  });
+
   it("rejects malformed design comparison evidence", () => {
     const invalid = {
       ...manifest,