@usefragments/core 1.3.0 → 1.5.0

package/dist/index.js

@@ -71,6 +71,8 @@ import {
   makeClassNameDynamicFact,
   makeClassNameLiteralFact,
   makeComponentCapabilityFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makeComponentMetadataFact,
   makeContractTokenFact,
   makeJsxComponentPreferredFact,
@@ -109,7 +111,7 @@ import {
   ownedImportsEqual,
   resolveComponentGovernance,
   scaleGovernanceRecordSchema
-} from "./chunk-MLRDNSSA.js";
+} from "./chunk-HXGE3O2F.js";
 import {
   AGENT_FORMAT_SCHEMA_VERSION,
   agentErrorEnvelopeSchema,
@@ -185,6 +187,8 @@ var BRAND = {
   legacyConfigFile: "segments.config.ts",
   /** CLI command name (e.g., "fragments") */
   cliCommand: "fragments",
+  /** Full user-facing CLI invocation for copy printed to end users (e.g., "npx @usefragments/cli") */
+  cliInvocation: "npx @usefragments/cli",
   /** Directory for storing fragments, registry, and cache */
   dataDir: ".fragments",
   /** Components subdirectory within .fragments/ */
@@ -1679,16 +1683,20 @@ var tokenSourceSchema = z4.object({
 var tokenConfigSchema = z4.object({
   include: repoRelativePathsSchema.optional(),
   sources: z4.array(tokenSourceSchema).min(1).optional(),
+  // Declared design-system packages whose shipped fragments.json token
+  // vocabulary seeds the known-token set (#7c). A packages-only tokens block
+  // is valid — see the superRefine below.
+  packages: z4.array(z4.string().min(1)).optional(),
   exclude: z4.array(repoRelativePathSchema).optional(),
   themeSelectors: z4.record(z4.string()).optional(),
   enabled: z4.boolean().optional(),
   format: z4.enum(["auto", "css", "scss", "dtcg", "tailwind"]).optional(),
   namespace: z4.string().min(1).optional()
 }).passthrough().superRefine((tokens, ctx) => {
-  if (!tokens.include?.length && !tokens.sources?.length) {
+  if (!tokens.include?.length && !tokens.sources?.length && !tokens.packages?.length) {
     ctx.addIssue({
       code: z4.ZodIssueCode.custom,
-      message: "Add tokens.include or tokens.sources",
+      message: "Add tokens.include, tokens.sources, or tokens.packages",
       path: ["sources"]
     });
   }
@@ -1770,7 +1778,18 @@ var fragmentsConfigSchema = z4.object({
       })
     ).optional()
   }).optional(),
-  recognizedClassHelpers: z4.array(z4.string().min(1)).optional()
+  recognizedClassHelpers: z4.array(z4.string().min(1)).optional(),
+  identity: z4.object({
+    decisions: z4.array(
+      z4.object({
+        component: z4.string().min(1),
+        kind: z4.enum(["sanction", "reject", "dismiss"]),
+        canonicalTarget: z4.string().min(1).optional(),
+        reason: z4.string().optional(),
+        decisionId: z4.string().min(1).optional()
+      })
+    ).optional()
+  }).optional()
 });
 var compositionMetadataSchema = z4.object({
   pattern: z4.enum(["compound", "simple", "controlled", "wrapper"]).optional(),
@@ -2931,30 +2950,41 @@ function inferTokenGroup(name) {
       return category;
   }
 }
+var TOKEN_GROUP_COMMENT_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"
+};
+function looksLikeCleanHeading(text) {
+  if (!/^[a-z0-9][a-z0-9 -]*$/.test(text)) return false;
+  const wordCount = text.split(/\s+/).filter(Boolean).length;
+  return wordCount > 0 && wordCount <= 3;
+}
 function normalizeTokenGroupComment(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, "-");
+  if (text in TOKEN_GROUP_COMMENT_MAPPINGS) {
+    return TOKEN_GROUP_COMMENT_MAPPINGS[text];
+  }
+  if (!looksLikeCleanHeading(text)) {
+    return null;
+  }
+  return text.replace(/\s+/g, "-");
 }
 
 // src/tokens/scss.ts
@@ -3021,7 +3051,7 @@ function parseScssTokens(content, filePath = "tokens.scss") {
   const tokens = [];
   const seenNames = /* @__PURE__ */ new Set();
   let currentCategory = "other";
-  let hasCommentCategories = false;
+  let currentCategoryIsCurated = false;
   const scssVars = parseScssVariables(content);
   const varDeclRegex = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;/;
   const sectionCommentRegex = /^\s*\/\/\s+([A-Z].+)$/;
@@ -3031,7 +3061,9 @@ function parseScssTokens(content, filePath = "tokens.scss") {
       const normalized = normalizeTokenGroupComment(commentMatch[0]);
       if (normalized) {
         currentCategory = normalized;
-        hasCommentCategories = true;
+        currentCategoryIsCurated = true;
+      } else {
+        currentCategoryIsCurated = false;
       }
       continue;
     }
@@ -3047,7 +3079,7 @@ function parseScssTokens(content, filePath = "tokens.scss") {
       tokens.push({
         name,
         value: cleanValue || void 0,
-        category: hasCommentCategories ? currentCategory : inferTokenGroup(name),
+        category: currentCategoryIsCurated ? currentCategory : inferTokenGroup(name),
         description
       });
     }
@@ -3058,7 +3090,7 @@ function parseScssTokens(content, filePath = "tokens.scss") {
     tokens.push({
       name,
       value,
-      category: hasCommentCategories ? currentCategory : inferTokenGroup(name)
+      category: currentCategoryIsCurated ? currentCategory : inferTokenGroup(name)
     });
   }
   const cssVarValues = /* @__PURE__ */ new Map();
@@ -5057,11 +5089,15 @@ function ruleComponentsPreferLibrary(ix) {
   const textByNode = indexTextChildrenByNodeId(ix);
   const classTokensByNode = indexClassTokensByNode(ix);
   const reimplTargets = canonicalReimplTargets(sources, mappings);
+  const canonicalDirectoryResolvedNodes = indexCanonicalDirectoryResolvedNodes(ix, sources);
+  const shadowRenderRootNodeIds = indexShadowRenderRootNodeIds(ix);
   const findings = [];
   const seenImportFixes = /* @__PURE__ */ new Set();
   for (const node of ix.byKind("usage_node")) {
     if (isCanonicalSourceImplementationFile(node.file, sources)) continue;
     if (node.element.includes(".")) continue;
+    if (canonicalDirectoryResolvedNodes.has(node.id)) continue;
+    if (shadowRenderRootNodeIds.has(node.id)) continue;
     const props = propsByNode.get(node.id) ?? [];
     const textChildren = textByNode.get(node.id) ?? [];
     const importsForFile = importsByFileAndLocal.get(node.file);
@@ -5309,6 +5345,18 @@ function ruleComponentsPreferLibrary(ix) {
   }
   return findings;
 }
+function indexShadowRenderRootNodeIds(ix) {
+  const identities = ix.byKind("component_identity");
+  if (identities.length === 0) return /* @__PURE__ */ new Set();
+  const nodeIds = /* @__PURE__ */ new Set();
+  for (const identity of identities) {
+    if (identity.state !== "shadow") continue;
+    for (const evidenceId of identity.evidence) {
+      if (ix.get(evidenceId)?.kind === "usage_node") nodeIds.add(evidenceId);
+    }
+  }
+  return nodeIds;
+}
 function findBuiltInRawHtmlMatch(node, props, textChildren, inputType) {
   if (isIconOnlyButton(node, props, textChildren)) {
     return { canonical: "IconButton", tier: "icon-only" };
@@ -5587,7 +5635,27 @@ function sourceLabel(source) {
 function canonicalImportPath(source) {
   if (source.kind === "npm") return source.specifier;
   if (source.kind === "registry") return source.importPath;
-  return void 0;
+  return source.include?.length ? source.path : void 0;
+}
+function indexCanonicalDirectoryResolvedNodes(ix, sources) {
+  const out = /* @__PURE__ */ new Set();
+  const directoryPaths = sources.filter(
+    (source) => source.kind === "directory"
+  ).map((source) => normalizePath(source.path));
+  if (directoryPaths.length === 0) return out;
+  for (const fact of ix.byKind("usage_component")) {
+    const module = componentIdModule(fact.componentId);
+    if (module === void 0) continue;
+    const normalizedModule = normalizePath(module);
+    if (directoryPaths.some((path) => isPathInSource(normalizedModule, path))) {
+      out.add(fact.nodeId);
+    }
+  }
+  return out;
+}
+function componentIdModule(componentId2) {
+  const hash = componentId2.indexOf("#");
+  return hash > 0 ? componentId2.slice(0, hash) : void 0;
 }
 function isCanonicalSourceImplementationFile(file, sources) {
   const normalizedFile = normalizePath(file);
@@ -5615,9 +5683,95 @@ function isIdentifier(value) {
   return /^[A-Za-z_$][\w$]*$/.test(value);
 }
 
-// src/rules/components-forbidden-prop-value.ts
-var RULE_ID3 = "components/forbidden-prop-value";
+// src/identity/usage.ts
+function indexComponentIdentityUsage(ix) {
+  const nodesById = new Map(ix.byKind("usage_node").map((node) => [node.id, node]));
+  const nodesByComponent = /* @__PURE__ */ new Map();
+  for (const usage of ix.byKind("usage_component")) {
+    const node = nodesById.get(usage.nodeId);
+    if (!node) continue;
+    const componentKey = String(usage.componentId);
+    const nodes = nodesByComponent.get(componentKey) ?? /* @__PURE__ */ new Map();
+    nodes.set(node.id, node);
+    nodesByComponent.set(componentKey, nodes);
+  }
+  return new Map(
+    [...nodesByComponent].map(([componentKey, nodesByIdForComponent]) => {
+      const nodes = [...nodesByIdForComponent.values()];
+      return [
+        componentKey,
+        {
+          usageCount: nodes.length,
+          blastRadius: new Set(nodes.map((node) => node.file)).size,
+          nodes
+        }
+      ];
+    })
+  );
+}
+
+// src/rules/components-shadow-component.ts
+var RULE_ID3 = "components/shadow-component";
 var RULE_VERSION3 = "1";
+function ruleComponentsShadowComponent(ix) {
+  const policy = ix.policy.ruleConfig(RULE_ID3);
+  if (!policy?.enabled) return [];
+  const definitions = new Map(
+    ix.byKind("component_definition").map((definition) => [definition.componentKey, definition])
+  );
+  const usageByComponent = indexComponentIdentityUsage(ix);
+  const findings = [];
+  for (const identity of ix.byKind("component_identity")) {
+    const reviewVariant = identity.state === "variant" && identity.confidence === "review";
+    if (identity.state !== "shadow" && !reviewVariant) continue;
+    const definition = definitions.get(identity.componentKey);
+    if (!definition) continue;
+    const usage = usageByComponent.get(identity.componentKey);
+    const usageCount = usage?.usageCount ?? 0;
+    const blastRadius = usage?.blastRadius ?? 0;
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID3,
+        ruleVersion: RULE_VERSION3,
+        severity: reviewVariant ? "info" : policy.severity ?? "warn",
+        message: reviewVariant ? `${definition.exportName} wraps ${identity.canonicalTarget ?? "a canonical component"}; sanction it as a variant or consolidate its usages.` : `${definition.exportName} shadows ${identity.canonicalTarget ?? "a canonical component"} across ${usageCount} usage${usageCount === 1 ? "" : "s"}.`,
+        location: definitionLocation(ix, definition, identity),
+        evidence: ix.evidence(identity.evidence),
+        fingerprintIdentity: {
+          componentKey: identity.componentKey,
+          canonicalTarget: identity.canonicalTarget
+        },
+        attributes: {
+          canonicalTarget: identity.canonicalTarget,
+          usageCount,
+          blastRadius,
+          confidence: identity.confidence,
+          state: identity.state,
+          ...reviewVariant ? { advisory: true } : {}
+        }
+      })
+    );
+  }
+  return findings;
+}
+function definitionLocation(ix, definition, identity) {
+  const evidence = ix.evidence(identity.evidence).map(({ fact }) => fact);
+  const inDefinitionFile = evidence.find(
+    (fact) => "location" in fact && fact.location?.file === definition.file
+  );
+  if (inDefinitionFile && "location" in inDefinitionFile && inDefinitionFile.location) {
+    return inDefinitionFile.location;
+  }
+  const sourceLocated = evidence.find((fact) => "location" in fact && fact.location);
+  if (sourceLocated && "location" in sourceLocated && sourceLocated.location) {
+    return sourceLocated.location;
+  }
+  return { file: definition.file, line: 1, column: 0 };
+}
+
+// src/rules/components-forbidden-prop-value.ts
+var RULE_ID4 = "components/forbidden-prop-value";
+var RULE_VERSION4 = "1";
 function ruleComponentsForbiddenPropValue(ix) {
   const findings = [];
   const componentByNode = indexComponentByNodeId(ix);
@@ -5647,8 +5801,8 @@ function ruleComponentsForbiddenPropValue(ix) {
       } : void 0;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID3,
-          ruleVersion: RULE_VERSION3,
+          ruleId: RULE_ID4,
+          ruleVersion: RULE_VERSION4,
           severity: policy.severity,
           message: buildMessage(
             node.element,
@@ -5692,8 +5846,8 @@ function buildMessage(element, prop, value, because, replacement) {
 }
 
 // src/rules/components-unknown-prop.ts
-var RULE_ID4 = "components/unknown-prop";
-var RULE_VERSION4 = "1";
+var RULE_ID5 = "components/unknown-prop";
+var RULE_VERSION5 = "1";
 function ruleComponentsUnknownProp(ix) {
   const policy = ix.policy.jsxUnknownPropsForbidden();
   if (!policy) return [];
@@ -5714,8 +5868,8 @@ function ruleComponentsUnknownProp(ix) {
       if (knownNames.has(propUsage.prop)) continue;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID4,
-          ruleVersion: RULE_VERSION4,
+          ruleId: RULE_ID5,
+          ruleVersion: RULE_VERSION5,
           severity: policy.severity,
           message: `Unknown prop "${propUsage.prop}" on <${node.element}>. Allowed props: ${formatPropList(knownNames)}.`,
           location: node.location,
@@ -5747,7 +5901,7 @@ function formatPropList(names) {
 // src/rules/composition-pattern.ts
 var CARDINALITY_RULE_ID = "composition/cardinality";
 var CO_OCCURRENCE_RULE_ID = "composition/co-occurrence";
-var RULE_VERSION5 = "1";
+var RULE_VERSION6 = "1";
 function ruleCompositionCardinality(ix) {
   return evaluate(ix, CARDINALITY_RULE_ID, "cardinality");
 }
@@ -5815,7 +5969,7 @@ function checkCardinality(ctx, region, pattern, constraint, selected) {
     const extras = selected.slice(constraint.max);
     return makeFinding({
       ruleId: ctx.ruleId,
-      ruleVersion: RULE_VERSION5,
+      ruleVersion: RULE_VERSION6,
       severity: ctx.severity,
       message: cardinalityMaxMessage(pattern, constraint.max, count),
       location: extras[0].location,
@@ -5826,7 +5980,7 @@ function checkCardinality(ctx, region, pattern, constraint, selected) {
   if (constraint.min !== void 0 && count < constraint.min) {
     return makeFinding({
       ruleId: ctx.ruleId,
-      ruleVersion: RULE_VERSION5,
+      ruleVersion: RULE_VERSION6,
       severity: ctx.severity,
       message: cardinalityMinMessage(pattern, constraint.min, count),
       location: region.container.location,
@@ -5847,7 +6001,7 @@ function checkCoOccurrence(ctx, region, pattern, constraint, selected) {
   if (satisfied) return null;
   return makeFinding({
     ruleId: ctx.ruleId,
-    ruleVersion: RULE_VERSION5,
+    ruleVersion: RULE_VERSION6,
     severity: ctx.severity,
     message: coOccurrenceMessage(pattern, constraint),
     location: region.container.location,
@@ -5899,8 +6053,8 @@ function coOccurrenceMessage(pattern, constraint) {
 }
 
 // src/rules/jsx-preferred-component.ts
-var RULE_ID5 = "components/preferred-component";
-var RULE_VERSION6 = "1";
+var RULE_ID6 = "components/preferred-component";
+var RULE_VERSION7 = "1";
 function ruleJsxPreferredComponent(ix) {
   const policies = ix.policy.jsxComponentPreferred();
   if (policies.length === 0) return [];
@@ -5916,8 +6070,8 @@ function ruleJsxPreferredComponent(ix) {
       if (!replacement) continue;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID5,
-          ruleVersion: RULE_VERSION6,
+          ruleId: RULE_ID6,
+          ruleVersion: RULE_VERSION7,
           severity: policy.severity,
           message: `<${node.element}> should use <${replacement}>.`,
           location: node.location,
@@ -5954,8 +6108,8 @@ function componentNameFromId(componentId2) {
 }
 
 // src/rules/jsx-preferred-import-path.ts
-var RULE_ID6 = "imports/preferred-path";
-var RULE_VERSION7 = "1";
+var RULE_ID7 = "imports/preferred-path";
+var RULE_VERSION8 = "1";
 function ruleJsxPreferredImportPath(ix) {
   const policies = ix.policy.jsxImportPathPreferred();
   if (policies.length === 0) return [];
@@ -5975,8 +6129,8 @@ function ruleJsxPreferredImportPath(ix) {
       seen.add(key);
       findings.push(
         makeFinding({
-          ruleId: RULE_ID6,
-          ruleVersion: RULE_VERSION7,
+          ruleId: RULE_ID7,
+          ruleVersion: RULE_VERSION8,
           severity: policy.severity,
           message: `Import from "${usage.source}" should use "${policy.to}".`,
           location: usage.location,
@@ -6011,10 +6165,10 @@ function ruleJsxPreferredImportPath(ix) {
 }
 
 // src/rules/props-invalid-value.ts
-var RULE_ID7 = "props/invalid-value";
-var RULE_VERSION8 = "1";
+var RULE_ID8 = "props/invalid-value";
+var RULE_VERSION9 = "1";
 function rulePropsInvalidValue(ix) {
-  const policy = ix.policy.ruleConfig(RULE_ID7);
+  const policy = ix.policy.ruleConfig(RULE_ID8);
   if (!policy?.enabled) return [];
   const findings = [];
   const componentByNode = indexComponentByNodeId(ix);
@@ -6043,8 +6197,8 @@ function rulePropsInvalidValue(ix) {
       } : void 0;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID7,
-          ruleVersion: RULE_VERSION8,
+          ruleId: RULE_ID8,
+          ruleVersion: RULE_VERSION9,
           severity: policy.severity ?? "warn",
           message: buildMessage2(node.element, propUsage.prop, propUsage.value, allowedValues),
           location: propUsage.location ?? node.location,
@@ -6220,14 +6374,15 @@ function srgbGamma(linear) {
 }
 
 // src/rules/styles-no-raw-color.ts
-var RULE_ID8 = "styles/no-raw-color";
-var RULE_VERSION9 = "1";
+var RULE_ID9 = "styles/no-raw-color";
+var RULE_VERSION10 = "1";
 function ruleStylesNoRawColor(ix) {
   const policy = ix.policy.rawColorPolicy();
   if (!policy) return [];
   const colorTokens = ix.tokens.byCategory("color");
   const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
   const findings = [];
+  const advisorySeverity = policy.severity === "error" ? "warn" : policy.severity;
   for (const decl of ix.byKind("style_declaration")) {
     if (decl.property.startsWith("--") && decl.declaredTokenSource === true) continue;
     const color = detectRawColor(decl.value);
@@ -6238,8 +6393,8 @@ function ruleStylesNoRawColor(ix) {
     const evidenceIds = resolution ? [decl.id, policy.id, resolution.token.id] : [decl.id, policy.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID8,
-        ruleVersion: RULE_VERSION9,
+        ruleId: RULE_ID9,
+        ruleVersion: RULE_VERSION10,
         severity: policy.severity,
         message: colorMessage(color, `\`${decl.property}\``, resolution, preferLabel),
         location: decl.location,
@@ -6267,6 +6422,37 @@ function ruleStylesNoRawColor(ix) {
   }
   const componentByNode = indexComponentByNodeId(ix);
   for (const inline of ix.byKind("usage_inline_style")) {
+    if (inline.valueKind === "dynamic-raw") {
+      const node2 = readUsageNode(ix, inline.nodeId);
+      if (!node2) continue;
+      const componentEvidenceId2 = componentByNode.get(node2.id)?.id;
+      const evidenceIds2 = componentEvidenceId2 ? [node2.id, componentEvidenceId2, inline.id, policy.id] : [node2.id, inline.id, policy.id];
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID9,
+          ruleVersion: RULE_VERSION10,
+          severity: advisorySeverity,
+          message: `Runtime-constructed raw color \`${inline.value}\` on inline \`${inline.property}\`. Use a ${preferLabel} instead.`,
+          location: node2.location,
+          evidence: ix.evidence(evidenceIds2),
+          fingerprintIdentity: {
+            source: "usage_inline_style_dynamic",
+            file: node2.file,
+            nodePath: node2.nodePath,
+            element: node2.element,
+            property: inline.property,
+            value: inline.value
+          },
+          attributes: {
+            property: inline.property,
+            rawValue: inline.value,
+            source: "jsx",
+            dynamic: true
+          }
+        })
+      );
+      continue;
+    }
     if (inline.valueKind === "css-variable") continue;
     const color = detectRawColor(inline.value);
     if (!color) continue;
@@ -6280,8 +6466,8 @@ function ruleStylesNoRawColor(ix) {
     const evidenceIds = resolution ? [...baseEvidence, resolution.token.id] : baseEvidence;
     findings.push(
       makeFinding({
-        ruleId: RULE_ID8,
-        ruleVersion: RULE_VERSION9,
+        ruleId: RULE_ID9,
+        ruleVersion: RULE_VERSION10,
         severity: policy.severity,
         message: colorMessage(color, `inline \`${inline.property}\``, resolution, preferLabel),
         location: node.location,
@@ -6307,8 +6493,68 @@ function ruleStylesNoRawColor(ix) {
       })
     );
   }
+  for (const prop of ix.byKind("usage_prop_resolved")) {
+    if (prop.resolution !== "static") continue;
+    if (typeof prop.value !== "string") continue;
+    if (!SVG_PAINT_ATTRS.has(prop.prop)) continue;
+    const color = detectRawColor(prop.value);
+    if (!color) continue;
+    if (isExemptColor(color, policy.except)) continue;
+    const node = readUsageNode(ix, prop.nodeId);
+    if (!node) continue;
+    const componentEvidenceId = componentByNode.get(node.id)?.id;
+    const cssProperty = SVG_PAINT_CSS_PROPERTY[prop.prop] ?? prop.prop;
+    const resolution = resolveColorToken(cssProperty, color, colorTokens);
+    const fixEmission = resolution?.kind === "exact" ? buildTokenFix(cssProperty, prop.value, color, resolution, ix) : void 0;
+    const baseEvidence = componentEvidenceId ? [node.id, componentEvidenceId, prop.id, policy.id] : [node.id, prop.id, policy.id];
+    const evidenceIds = resolution ? [...baseEvidence, resolution.token.id] : baseEvidence;
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID9,
+        ruleVersion: RULE_VERSION10,
+        severity: advisorySeverity,
+        message: colorMessage(color, `\`${prop.prop}\``, resolution, preferLabel),
+        location: prop.location ?? node.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: {
+          source: "usage_prop_resolved",
+          file: node.file,
+          nodePath: node.nodePath,
+          element: node.element,
+          property: prop.prop,
+          value: color
+        },
+        fix: fixEmission?.fix,
+        attributes: {
+          property: prop.prop,
+          rawValue: prop.value,
+          color,
+          source: "jsx",
+          suggestedToken: resolution?.token.name,
+          ...resolution ? { tokenMatch: resolution.kind } : {},
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
+        }
+      })
+    );
+  }
   return findings;
 }
+var SVG_PAINT_ATTRS = /* @__PURE__ */ new Set([
+  "fill",
+  "stroke",
+  "color",
+  "stop-color",
+  "stopColor",
+  "flood-color",
+  "floodColor",
+  "lighting-color",
+  "lightingColor"
+]);
+var SVG_PAINT_CSS_PROPERTY = {
+  stopColor: "stop-color",
+  floodColor: "flood-color",
+  lightingColor: "lighting-color"
+};
 function resolveColorToken(property, raw, tokens) {
   const exact = findTokenMatch(property, raw, tokens);
   if (exact) return { kind: "exact", token: exact.token, ambiguous: exact.ambiguous };
@@ -6416,8 +6662,8 @@ function escapeRegExp(value) {
 }
 
 // src/rules/styles-no-raw-dimensions.ts
-var RULE_ID9 = "styles/no-raw-dimensions";
-var RULE_VERSION10 = "1";
+var RULE_ID10 = "styles/no-raw-dimensions";
+var RULE_VERSION11 = "1";
 function ruleStylesNoRawDimensions(ix) {
   const policy = ix.policy.rawDimensionPolicy();
   if (!policy) return [];
@@ -6437,8 +6683,8 @@ function ruleStylesNoRawDimensions(ix) {
     const fixEmission = dimensionFix(decl.property, resolution, ix);
     findings.push(
       makeFinding({
-        ruleId: RULE_ID9,
-        ruleVersion: RULE_VERSION10,
+        ruleId: RULE_ID10,
+        ruleVersion: RULE_VERSION11,
         severity: policy.severity,
         message: dimensionMessage(decl.value, decl.property, preferLabel, resolution, false),
         location: decl.location,
@@ -6479,8 +6725,8 @@ function ruleStylesNoRawDimensions(ix) {
     const fixEmission = dimensionFix(inline.property, resolution, ix);
     findings.push(
       makeFinding({
-        ruleId: RULE_ID9,
-        ruleVersion: RULE_VERSION10,
+        ruleId: RULE_ID10,
+        ruleVersion: RULE_VERSION11,
         severity: policy.severity,
         message: dimensionMessage(inline.value, inline.property, preferLabel, resolution, true),
         location: node.location,
@@ -6750,8 +6996,8 @@ function parseLengthParts(raw) {
 }
 
 // src/rules/styles-no-raw-spacing.ts
-var RULE_ID10 = "styles/no-raw-spacing";
-var RULE_VERSION11 = "1";
+var RULE_ID11 = "styles/no-raw-spacing";
+var RULE_VERSION12 = "1";
 function ruleStylesNoRawSpacing(ix) {
   const findings = [];
   const lookupCache = /* @__PURE__ */ new Map();
@@ -6793,8 +7039,8 @@ function checkDeclaration(ix, decl, lookupFor) {
   if (!checked) return null;
   const fixEmission = buildSpacingFix(decl.property, checked, ix);
   return makeFinding({
-    ruleId: RULE_ID10,
-    ruleVersion: RULE_VERSION11,
+    ruleId: RULE_ID11,
+    ruleVersion: RULE_VERSION12,
     severity: policy.severity,
     message: spacingMessage(decl.property, decl.value, allowed, scale.unit, checked),
     location: decl.location,
@@ -6848,8 +7094,8 @@ function checkInlineStyle(ix, inline, componentByNode, lookupFor) {
   const componentEvidenceId = componentByNode.get(node.id)?.id;
   const evidenceIds = componentEvidenceId ? [node.id, componentEvidenceId, inline.id, policy.id, scale.id] : [node.id, inline.id, policy.id, scale.id];
   return makeFinding({
-    ruleId: RULE_ID10,
-    ruleVersion: RULE_VERSION11,
+    ruleId: RULE_ID11,
+    ruleVersion: RULE_VERSION12,
     severity: policy.severity,
     message: spacingMessage(inline.property, inline.value, allowed, scale.unit, checked),
     location: node.location,
@@ -6910,8 +7156,8 @@ function spacingMessage(property, value, allowed, unit, checked) {
 }
 
 // src/rules/styles-no-raw-typography.ts
-var RULE_ID11 = "styles/no-raw-typography";
-var RULE_VERSION12 = "1";
+var RULE_ID12 = "styles/no-raw-typography";
+var RULE_VERSION13 = "1";
 var FONT_SIZE_PROPERTIES = /* @__PURE__ */ new Set(["font-size", "fontsize"]);
 function ruleStylesNoRawTypography(ix) {
   const policy = ix.policy.fontSizeScale();
@@ -6929,8 +7175,8 @@ function ruleStylesNoRawTypography(ix) {
     const fixEmission = buildFix(decl.property, checked, ix);
     findings.push(
       makeFinding({
-        ruleId: RULE_ID11,
-        ruleVersion: RULE_VERSION12,
+        ruleId: RULE_ID12,
+        ruleVersion: RULE_VERSION13,
         severity: policy.severity,
         message: typographyMessage(decl.property, decl.value, allowed, scale.unit, checked),
         location: decl.location,
@@ -6976,8 +7222,8 @@ function ruleStylesNoRawTypography(ix) {
     const evidenceIds = componentEvidenceId ? [node.id, componentEvidenceId, inline.id, policy.id, scale.id] : [node.id, inline.id, policy.id, scale.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID11,
-        ruleVersion: RULE_VERSION12,
+        ruleId: RULE_ID12,
+        ruleVersion: RULE_VERSION13,
         severity: policy.severity,
         message: typographyMessage(inline.property, inline.value, allowed, scale.unit, checked),
         location: node.location,
@@ -7079,15 +7325,15 @@ function typographyMessage(property, value, allowed, unit, checked) {
 }
 
 // src/rules/theme-no-theme-coupled-literal.ts
-var RULE_ID12 = "theme/no-theme-coupled-literal";
-var RULE_VERSION13 = "1";
+var RULE_ID13 = "theme/no-theme-coupled-literal";
+var RULE_VERSION14 = "1";
 var COLOR_LITERAL_GLOBAL = /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?|oklab|oklch|lab|lch)\(\s*[\d.%\s,\/]+\s*\)/g;
 var WHITE_RGBA = /^rgba?\(\s*255\s*,\s*255\s*,\s*255/i;
 var BLACK_RGBA = /^rgba?\(\s*0\s*,\s*0\s*,\s*0/i;
 var BOX_SHADOW_PROP = /^(?:-webkit-|-moz-)?box-shadow$/i;
 var NEUTRAL_SHADOW = /^(?:none|inherit|initial|unset|revert|revert-layer)\s*$/i;
 function ruleThemeNoThemeCoupledLiteral(ix) {
-  const policy = ix.policy.ruleConfig(RULE_ID12);
+  const policy = ix.policy.ruleConfig(RULE_ID13);
   if (!policy?.enabled) return [];
   const findings = [];
   for (const decl of ix.byKind("style_declaration")) {
@@ -7096,8 +7342,8 @@ function ruleThemeNoThemeCoupledLiteral(ix) {
     if (!hit) continue;
     findings.push(
       makeFinding({
-        ruleId: RULE_ID12,
-        ruleVersion: RULE_VERSION13,
+        ruleId: RULE_ID13,
+        ruleVersion: RULE_VERSION14,
         severity: policy.severity ?? "warn",
         message: hit.message,
         location: decl.location,
@@ -7187,8 +7433,8 @@ function isTokenFile(filePath) {
 }
 
 // src/rules/tailwind-arbitrary-color.ts
-var RULE_ID13 = "tailwind/arbitrary-color";
-var RULE_VERSION14 = "1";
+var RULE_ID14 = "tailwind/arbitrary-color";
+var RULE_VERSION15 = "1";
 var COLOR_UTILITIES = /* @__PURE__ */ new Set([
   "accent",
   "bg",
@@ -7230,8 +7476,8 @@ function ruleTailwindArbitraryColor(ix) {
     const evidenceIds = node ? [node.id, klass.id, policy.id] : [klass.id, policy.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID13,
-        ruleVersion: RULE_VERSION14,
+        ruleId: RULE_ID14,
+        ruleVersion: RULE_VERSION15,
         severity: policy.severity,
         message: `\`${klass.raw}\` uses arbitrary raw color ${color}. Use a ${policy.prefer === "token" ? "design token" : "CSS variable"} instead.`,
         location: klass.location,
@@ -7262,8 +7508,8 @@ function fingerprintIdentity(klass, color) {
 }
 
 // src/rules/tailwind-arbitrary-spacing.ts
-var RULE_ID14 = "tailwind/arbitrary-spacing";
-var RULE_VERSION15 = "1";
+var RULE_ID15 = "tailwind/arbitrary-spacing";
+var RULE_VERSION16 = "1";
 var SPACING_UTILITY_TO_PROPERTY = /* @__PURE__ */ new Map([
   ["m", "margin"],
   ["mt", "margin"],
@@ -7309,8 +7555,8 @@ function ruleTailwindArbitrarySpacing(ix) {
     const fix = buildFix2(klass);
     findings.push(
       makeFinding({
-        ruleId: RULE_ID14,
-        ruleVersion: RULE_VERSION15,
+        ruleId: RULE_ID15,
+        ruleVersion: RULE_VERSION16,
         severity: policy.severity,
         message: `\`${klass.raw}\` is an arbitrary spacing value not on the project's spacing scale.`,
         location: klass.location,
@@ -7441,8 +7687,8 @@ function matchesTokenGlob(value, pattern) {
 }
 
 // src/rules/tailwind-forbidden-palette.ts
-var RULE_ID15 = "tailwind/forbidden-palette";
-var RULE_VERSION16 = "1";
+var RULE_ID16 = "tailwind/forbidden-palette";
+var RULE_VERSION17 = "1";
 function ruleTailwindForbiddenPalette(ix) {
   const deny = ix.policy.tailwindPaletteDeny();
   const allow = ix.policy.tailwindPaletteAllow();
@@ -7467,8 +7713,8 @@ function ruleTailwindForbiddenPalette(ix) {
     const evidenceIds = node ? [node.id, klass.id, resolved.id, policy.id] : [klass.id, resolved.id, policy.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID15,
-        ruleVersion: RULE_VERSION16,
+        ruleId: RULE_ID16,
+        ruleVersion: RULE_VERSION17,
         severity: policy.severity,
         message: messageFor(klass, token, deniedPattern, allow?.patterns ?? []),
         location: klass.location,
@@ -7515,8 +7761,8 @@ function buildFix3(klass) {
 }
 
 // src/rules/tailwind-off-scale-spacing-token.ts
-var RULE_ID16 = "tailwind/off-scale-spacing-token";
-var RULE_VERSION17 = "1";
+var RULE_ID17 = "tailwind/off-scale-spacing-token";
+var RULE_VERSION18 = "1";
 function ruleTailwindOffScaleSpacingToken(ix) {
   const resolvedByKey = indexResolvedTailwindTokens(ix);
   const findings = [];
@@ -7542,8 +7788,8 @@ function ruleTailwindOffScaleSpacingToken(ix) {
     const evidenceIds = node ? [node.id, klass.id, resolved.id, policy.id, scale.id] : [klass.id, resolved.id, policy.id, scale.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID16,
-        ruleVersion: RULE_VERSION17,
+        ruleId: RULE_ID17,
+        ruleVersion: RULE_VERSION18,
         severity: policy.severity,
         message: `\`${klass.raw}\` resolves to ${formatResolvedValue(signedValue, scale.unit)}, which is not on the project's spacing scale [${allowed.join(", ")}].`,
         location: klass.location,
@@ -7592,8 +7838,8 @@ function buildFix4(raw, utility) {
 }
 
 // src/rules/tailwind-raw-color-via-token.ts
-var RULE_ID17 = "tailwind/raw-color-via-token";
-var RULE_VERSION18 = "1";
+var RULE_ID18 = "tailwind/raw-color-via-token";
+var RULE_VERSION19 = "1";
 function ruleTailwindRawColorViaToken(ix) {
   const allow = ix.policy.tailwindPaletteAllow();
   if (!allow || allow.patterns.length === 0) return [];
@@ -7613,8 +7859,8 @@ function ruleTailwindRawColorViaToken(ix) {
     const evidenceIds = node ? [node.id, klass.id, resolved.id, allow.id] : [klass.id, resolved.id, allow.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID17,
-        ruleVersion: RULE_VERSION18,
+        ruleId: RULE_ID18,
+        ruleVersion: RULE_VERSION19,
         severity: allow.severity,
         message: `\`${klass.raw}\` resolves to raw color \`${color}\` (${sourceLabel2(resolved.resolved.source)}). Project policy requires \`${allow.patterns.join("`, `")}\` palette tokens.`,
         location: klass.location,
@@ -7647,8 +7893,8 @@ function sourceLabel2(source) {
 }
 
 // src/rules/tailwind-unknown-class.ts
-var RULE_ID18 = "tailwind/unknown-class";
-var RULE_VERSION19 = "1";
+var RULE_ID19 = "tailwind/unknown-class";
+var RULE_VERSION20 = "1";
 var UNIVERSAL_COLOR_KEYWORDS = /* @__PURE__ */ new Set([
   "white",
   "black",
@@ -7669,8 +7915,8 @@ function ruleTailwindUnknownClass(ix) {
       const evidenceIds2 = node2 ? [node2.id, klass.id, policy.id] : [klass.id, policy.id];
       findings.push(
         makeFinding({
-          ruleId: RULE_ID18,
-          ruleVersion: RULE_VERSION19,
+          ruleId: RULE_ID19,
+          ruleVersion: RULE_VERSION20,
           severity: policy.severity,
           message: `\`${klass.raw}\` could not be parsed as a known Tailwind utility.`,
           location: klass.location,
@@ -7704,8 +7950,8 @@ function ruleTailwindUnknownClass(ix) {
     const evidenceIds = node ? [node.id, klass.id, resolved.id, policy.id] : [klass.id, resolved.id, policy.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID18,
-        ruleVersion: RULE_VERSION19,
+        ruleId: RULE_ID19,
+        ruleVersion: RULE_VERSION20,
         severity: policy.severity,
         message: `\`${klass.raw}\` did not resolve to any known palette token.`,
         location: klass.location,
@@ -7733,12 +7979,12 @@ function ruleTailwindUnknownClass(ix) {
 }
 
 // src/rules/tokens-require-dual-fallback.ts
-var RULE_ID19 = "tokens/require-dual-fallback";
-var RULE_VERSION20 = "1";
+var RULE_ID20 = "tokens/require-dual-fallback";
+var RULE_VERSION21 = "1";
 var CSS_VAR_WITH_OPTIONAL_FALLBACK = /var\(\s*(--[A-Za-z0-9_-]+)(\s*,\s*[^)]*)?\)/g;
 var SASS_FILE = /\.(scss|sass)$/i;
 function ruleTokensRequireDualFallback(ix) {
-  const policy = ix.policy.ruleConfig(RULE_ID19);
+  const policy = ix.policy.ruleConfig(RULE_ID20);
   if (!policy?.enabled) return [];
   const tokensByCssVariable = indexTokensByCssVariable(ix.tokens.list());
   const findings = [];
@@ -7773,8 +8019,8 @@ function ruleTokensRequireDualFallback(ix) {
       ) : void 0;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID19,
-          ruleVersion: RULE_VERSION20,
+          ruleId: RULE_ID20,
+          ruleVersion: RULE_VERSION21,
           severity: policy.severity ?? "warn",
           message: hasScssVariable ? `var(${tokenName}) is missing an SCSS fallback. Use var(${tokenName}, ${scssVar}).` : `var(${tokenName}) is missing a fallback. No matching SCSS variable was found in the token source; add a fallback manually or define ${scssVar}.`,
           location: decl.location,
@@ -7814,8 +8060,8 @@ function indexTokensByCssVariable(tokens) {
 }
 
 // src/rules/tokens-css-vars-must-be-defined.ts
-var RULE_ID20 = "tokens/css-vars-must-be-defined";
-var RULE_VERSION21 = "1";
+var RULE_ID21 = "tokens/css-vars-must-be-defined";
+var RULE_VERSION22 = "1";
 var CSS_VAR_REFERENCE = /var\(\s*(--[A-Za-z0-9_-]+)/gi;
 function ruleTokensCssVarsMustBeDefined(ix) {
   const policy = ix.policy.cssVarsMustBeDefined();
@@ -7842,8 +8088,8 @@ function ruleTokensCssVarsMustBeDefined(ix) {
       seen.add(tokenName);
       findings.push(
         makeFinding({
-          ruleId: RULE_ID20,
-          ruleVersion: RULE_VERSION21,
+          ruleId: RULE_ID21,
+          ruleVersion: RULE_VERSION22,
           severity: policy.severity,
           message: `var(${tokenName}) is not in the contract token vocabulary. Use a token defined in your contract's token source files.`,
           location: decl.location,
@@ -7923,6 +8169,8 @@ function isDenyEligible(finding, failOnWarnings) {
 // src/rules/tiers.ts
 var RULE_TIER = {
   // ---- Tier A — contract vocabulary -------------------------------------
+  "components/shadow-component": "contract",
+  // canonical-component identity drift
   "components/prefer-library": "contract",
   // canonical-component bypass (FUI1004)
   "tokens/css-vars-must-be-defined": "contract",
@@ -7968,6 +8216,7 @@ function hygieneTierRuleIds() {
   return Object.keys(RULE_TIER).filter((id) => !isContractTierRule(id));
 }
 var VOCABULARY_ORDER = [
+  "components/shadow-component",
   "components/prefer-library",
   "tokens/css-vars-must-be-defined"
 ];
@@ -8028,6 +8277,11 @@ var RULES = [
     version: "1",
     run: ruleComponentsPreferLibrary
   },
+  {
+    id: "components/shadow-component",
+    version: "1",
+    run: ruleComponentsShadowComponent
+  },
   {
     id: "styles/no-raw-color",
     version: "1",
@@ -8622,6 +8876,133 @@ function readPreferLibraryRule(config) {
   const raw = config?.rules?.["components/prefer-library"];
   return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
 }
+
+// src/identity/component-key.ts
+function buildComponentKey({ repoRelativeFile, exportName }) {
+  const file = normalizeRepoRelativeFile(repoRelativeFile);
+  const name = exportName.trim();
+  if (!file) throw new Error("repoRelativeFile must not be empty");
+  if (!name) throw new Error("exportName must not be empty");
+  return `${file}#${name}`;
+}
+function normalizeRepoRelativeFile(file) {
+  const slashNormalized = file.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+  const absolute = slashNormalized.startsWith("/");
+  const parts = [];
+  for (const part of slashNormalized.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === ".." && parts.length > 0 && parts.at(-1) !== "..") {
+      parts.pop();
+      continue;
+    }
+    parts.push(part);
+  }
+  return `${absolute ? "/" : ""}${parts.join("/")}`;
+}
+
+// src/identity/classify.ts
+function classifyIdentity(input) {
+  const { definition, renderRoot } = input;
+  if (definition.canonical) return { state: "canonical", confidence: "confirmed" };
+  const decision = input.decisions?.find(
+    (candidate) => candidate.componentKey === definition.componentKey
+  );
+  if (decision?.decision === "sanctioned-wrapper") {
+    return withTarget("variant", "confirmed", decision.canonicalTarget ?? rootTarget(input));
+  }
+  if (decision?.decision === "rejected-wrapper") {
+    return withTarget("shadow", "confirmed", decision.canonicalTarget ?? shadowTarget(input));
+  }
+  if (renderRoot.kind === "canonical") {
+    if ((input.usageCounts?.nestedElements ?? 0) > 0 || (input.usageCounts?.staticTextChildren ?? 0) > 0) {
+      return withTarget("composite", "confirmed", renderRoot.target.componentKey);
+    }
+    const confidence = strongOverlap(input.propSurfaceOverlap) ? "likely" : "review";
+    return withTarget("variant", confidence, renderRoot.target.componentKey);
+  }
+  if (renderRoot.kind === "intrinsic") {
+    return classifyIntrinsic(input, renderRoot);
+  }
+  if (renderRoot.kind === "mixed") {
+    if (renderRoot.canonicalTargets.length > 0) {
+      const target = bestCanonicalReference(
+        definition.exportName,
+        renderRoot.canonicalTargets
+      )?.componentKey;
+      const fullyResolved = renderRoot.externalTargets.length === 0 && renderRoot.unresolvedNames.length === 0;
+      return withTarget("composite", fullyResolved ? "confirmed" : "likely", target);
+    }
+    if (renderRoot.externalTargets.length > 0 && renderRoot.localTargets.length === 0 && renderRoot.unresolvedNames.length === 0) {
+      return { state: "external", confidence: "likely" };
+    }
+    return withTarget("unresolved", "review", rootTarget(input));
+  }
+  if (renderRoot.kind === "external") {
+    return { state: "external", confidence: "confirmed" };
+  }
+  return withTarget("unresolved", "review", rootTarget(input));
+}
+function classifyIntrinsic(input, root) {
+  const target = bestCanonicalReference(input.definition.exportName, root.canonicalTargets);
+  if (!target || !root.interactive && !root.hasRole) {
+    return withTarget("unresolved", "review", rootTarget(input));
+  }
+  let confidence = root.precisionTier === "exact-html" || root.precisionTier === "role-reimpl" ? "confirmed" : "likely";
+  if (confidence === "likely" && input.stylingOwnership !== "layout-only" && (strongOverlap(input.propSurfaceOverlap) || input.stylingOwnership === "visual-role")) {
+    confidence = "confirmed";
+  }
+  return { state: "shadow", confidence, canonicalTarget: target.role };
+}
+function rootTarget(input) {
+  const { renderRoot } = input;
+  if (renderRoot.kind === "canonical") return renderRoot.target.componentKey;
+  if (renderRoot.kind === "intrinsic") {
+    return bestCanonicalReference(input.definition.exportName, renderRoot.canonicalTargets)?.role;
+  }
+  if (renderRoot.kind === "mixed") {
+    return bestCanonicalReference(input.definition.exportName, renderRoot.canonicalTargets)?.componentKey;
+  }
+  return bestMessageTarget(input.definition.exportName, input.nameSimilarityTargets ?? []);
+}
+function shadowTarget(input) {
+  const { renderRoot } = input;
+  if (renderRoot.kind === "canonical") return renderRoot.target.role;
+  if (renderRoot.kind === "intrinsic") {
+    return bestCanonicalReference(input.definition.exportName, renderRoot.canonicalTargets)?.role;
+  }
+  if (renderRoot.kind === "mixed") {
+    return bestCanonicalReference(input.definition.exportName, renderRoot.canonicalTargets)?.role;
+  }
+  return bestMessageTarget(input.definition.exportName, input.nameSimilarityTargets ?? []);
+}
+function bestCanonicalReference(definitionName, candidates) {
+  return [...candidates].sort(
+    (left, right) => nameSimilarityScore(definitionName, right.role) - nameSimilarityScore(definitionName, left.role) || left.componentKey.localeCompare(right.componentKey)
+  )[0];
+}
+function bestMessageTarget(definitionName, candidates) {
+  return [...candidates].sort(
+    (left, right) => nameSimilarityScore(definitionName, right) - nameSimilarityScore(definitionName, left) || left.localeCompare(right)
+  )[0];
+}
+function nameSimilarityScore(definitionName, target) {
+  const definition = normalizeName(definitionName);
+  const candidate = normalizeName(target);
+  if (!candidate) return 0;
+  if (definition === candidate) return 3;
+  if (definition.endsWith(candidate) || definition.startsWith(candidate)) return 2;
+  if (definition.includes(candidate) || candidate.includes(definition)) return 1;
+  return 0;
+}
+function normalizeName(value) {
+  return value.split(/[.#/]/).at(-1)?.replace(/[^a-z0-9]/gi, "").toLowerCase() ?? "";
+}
+function strongOverlap(overlap) {
+  return overlap !== void 0 && overlap >= 0.7;
+}
+function withTarget(state, confidence, canonicalTarget) {
+  return canonicalTarget ? { state, confidence, canonicalTarget } : { state, confidence };
+}
 export {
   AGENT_CONTEXT_RELATIVE_PATH,
   AGENT_FORMAT_SCHEMA_VERSION,
@@ -8672,6 +9053,7 @@ export {
   bridgeSourceViolations,
   budgetBar,
   buildAgentFormat,
+  buildComponentKey,
   buildRegistryArtifact,
   buildRegistryFile,
   buildRegistryInstallPlan,
@@ -8698,6 +9080,7 @@ export {
   checkStoryExclusion,
   clampMaxPasses,
   classifyComplexity,
+  classifyIdentity,
   collectRegistryInstallDependencies,
   colorSimilarity,
   compareByVocabularyRank,
@@ -8793,6 +9176,7 @@ export {
   hashRegistryFileContent,
   hexToRgb,
   hygieneTierRuleIds,
+  indexComponentIdentityUsage,
   inferTokenCategory,
   inferTokenGroup,
   isColorLike,
@@ -8819,6 +9203,8 @@ export {
   makeClassNameDynamicFact,
   makeClassNameLiteralFact,
   makeComponentCapabilityFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makeComponentMetadataFact,
   makeContractTokenFact,
   makeFinding,
@@ -8943,6 +9329,7 @@ export {
   ruleA11yRequiredAccessibleName,
   ruleComponentsForbiddenPropValue,
   ruleComponentsPreferLibrary,
+  ruleComponentsShadowComponent,
   ruleComponentsUnknownProp,
   ruleJsxPreferredComponent,
   ruleJsxPreferredImportPath,