@usefragments/core 1.4.0 → 1.5.0

package/dist/react-types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, ReactNode, JSX } from 'react';
-export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-DxdJV6lx.js';
+export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-BLsyk56o.js';
 import 'zod';
 import './topology/index.js';
 import './types-xJ2xyp_G.js';

package/dist/registry.d.ts

@@ -216,7 +216,7 @@ declare const registryComponentSchema: z.ZodObject<{
     componentId: string;
     name: string;
     publicRef: string;
-    tier: "custom" | "utility" | "composition" | "core";
+    tier: "core" | "custom" | "utility" | "composition";
     examples: unknown[];
     files: {
         path: string;
@@ -264,7 +264,7 @@ declare const registryComponentSchema: z.ZodObject<{
     provenance?: Record<string, unknown> | undefined;
     category?: string | undefined;
     contract?: unknown;
-    tier?: "custom" | "utility" | "composition" | "core" | undefined;
+    tier?: "core" | "custom" | "utility" | "composition" | undefined;
     examples?: unknown[] | undefined;
     styleFiles?: string[] | undefined;
     tokenDependencies?: string[] | undefined;
@@ -498,7 +498,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "custom" | "utility" | "composition" | "core";
+        tier: "core" | "custom" | "utility" | "composition";
         examples: unknown[];
         files: {
             path: string;
@@ -546,7 +546,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "custom" | "utility" | "composition" | "core" | undefined;
+        tier?: "core" | "custom" | "utility" | "composition" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -611,7 +611,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "custom" | "utility" | "composition" | "core";
+        tier: "core" | "custom" | "utility" | "composition";
         examples: unknown[];
         files: {
             path: string;
@@ -713,7 +713,7 @@ declare const registryManifestDraftSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "custom" | "utility" | "composition" | "core" | undefined;
+        tier?: "core" | "custom" | "utility" | "composition" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -971,7 +971,7 @@ declare const registryManifestSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "custom" | "utility" | "composition" | "core";
+        tier: "core" | "custom" | "utility" | "composition";
         examples: unknown[];
         files: {
             path: string;
@@ -1019,7 +1019,7 @@ declare const registryManifestSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "custom" | "utility" | "composition" | "core" | undefined;
+        tier?: "core" | "custom" | "utility" | "composition" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -1086,7 +1086,7 @@ declare const registryManifestSchema: z.ZodObject<{
         componentId: string;
         name: string;
         publicRef: string;
-        tier: "custom" | "utility" | "composition" | "core";
+        tier: "core" | "custom" | "utility" | "composition";
         examples: unknown[];
         files: {
             path: string;
@@ -1189,7 +1189,7 @@ declare const registryManifestSchema: z.ZodObject<{
         provenance?: Record<string, unknown> | undefined;
         category?: string | undefined;
         contract?: unknown;
-        tier?: "custom" | "utility" | "composition" | "core" | undefined;
+        tier?: "core" | "custom" | "utility" | "composition" | undefined;
         examples?: unknown[] | undefined;
         styleFiles?: string[] | undefined;
         tokenDependencies?: string[] | undefined;
@@ -1450,7 +1450,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "custom" | "utility" | "composition" | "core";
+            tier: "core" | "custom" | "utility" | "composition";
             examples: unknown[];
             files: {
                 path: string;
@@ -1498,7 +1498,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "custom" | "utility" | "composition" | "core" | undefined;
+            tier?: "core" | "custom" | "utility" | "composition" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -1565,7 +1565,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "custom" | "utility" | "composition" | "core";
+            tier: "core" | "custom" | "utility" | "composition";
             examples: unknown[];
             files: {
                 path: string;
@@ -1668,7 +1668,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "custom" | "utility" | "composition" | "core" | undefined;
+            tier?: "core" | "custom" | "utility" | "composition" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -1773,7 +1773,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "custom" | "utility" | "composition" | "core";
+            tier: "core" | "custom" | "utility" | "composition";
             examples: unknown[];
             files: {
                 path: string;
@@ -1886,7 +1886,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "custom" | "utility" | "composition" | "core" | undefined;
+            tier?: "core" | "custom" | "utility" | "composition" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;
@@ -1979,7 +1979,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             componentId: string;
             name: string;
             publicRef: string;
-            tier: "custom" | "utility" | "composition" | "core";
+            tier: "core" | "custom" | "utility" | "composition";
             examples: unknown[];
             files: {
                 path: string;
@@ -2092,7 +2092,7 @@ declare const registryArtifactSchema: z.ZodEffects<z.ZodObject<{
             provenance?: Record<string, unknown> | undefined;
             category?: string | undefined;
             contract?: unknown;
-            tier?: "custom" | "utility" | "composition" | "core" | undefined;
+            tier?: "core" | "custom" | "utility" | "composition" | undefined;
             examples?: unknown[] | undefined;
             styleFiles?: string[] | undefined;
             tokenDependencies?: string[] | undefined;

package/dist/schemas/index.d.ts

@@ -1,3 +1,3 @@
 import 'zod';
 export { LegacySeverityLevel, Severity, SeverityLevel, legacySeverityLevelSchema, severityLevelSchema, severitySchema } from '../severity.js';
-export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-0lmh0Lbo.js';
+export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-h_yWj15D.js';

package/dist/test-utils.d.ts

@@ -1,4 +1,4 @@
-import { C as CompiledBlock, b as CompiledFragment } from './governance-DxdJV6lx.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-BLsyk56o.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",

package/src/codes/codes.ts

@@ -108,6 +108,15 @@ export const CODES = [
     fixAvailable: false,
     evidenceRequired: true,
   }),
+  ruleCode({
+    code: "FUI1007",
+    ruleId: "components/shadow-component",
+    category: "canonical-usage",
+    defaultSeverity: "moderate",
+    title: "Component shadows a canonical primitive",
+    lifecycle: "experimental",
+    evidenceRequired: true,
+  }),
   code({
     code: "FUI2001",
     ruleId: "tokens/require-design-tokens",

package/src/conform.ts

@@ -20,6 +20,11 @@ export interface ConformInput {
   filename?: string;
   /** deterministic (default) applies safe edits; none returns findings only. */
   apply?: "deterministic" | "none";
+  /** Explicit request to consolidate a known shadow into its canonical root. */
+  shadowConsolidation?: {
+    shadow: string;
+    canonicalTarget?: string;
+  };
 }
 
 export interface ConformLocation {

package/src/facts/builders.ts

@@ -9,7 +9,7 @@
  */
 
 import type { GovernanceSeverity } from "../governance.js";
-import { factId } from "./ids.js";
+import { asComponentId, factId } from "./ids.js";
 import type {
   A11yNameRequiredFact,
   CanonicalCandidateFact,
@@ -20,7 +20,9 @@ import type {
   ClassNameLiteralFact,
   ClassNameOrigin,
   ComponentCapabilityFact,
+  ComponentDefinitionFact,
   ComponentId,
+  ComponentIdentityFact,
   ComponentMetadataFact,
   FactLocation,
   GovernanceRuleConfigFact,
@@ -99,6 +101,48 @@ export function makeComponentCapabilityFact(input: {
   };
 }
 
+export function makeComponentDefinitionFact(input: {
+  file: string;
+  exportName: string;
+  componentKey: string;
+  renderRoot: ComponentDefinitionFact["renderRoot"];
+  propSurface: string[];
+  stylingChannel?: ComponentDefinitionFact["stylingChannel"];
+}): ComponentDefinitionFact {
+  return {
+    id: factId("component_definition", { componentKey: input.componentKey }),
+    kind: "component_definition",
+    componentId: asComponentId(input.componentKey),
+    file: input.file,
+    exportName: input.exportName,
+    componentKey: input.componentKey,
+    renderRoot: input.renderRoot,
+    propSurface: [...input.propSurface],
+    ...(input.stylingChannel ? { stylingChannel: { ...input.stylingChannel } } : {}),
+  };
+}
+
+export function makeComponentIdentityFact(input: {
+  componentKey: string;
+  state: ComponentIdentityFact["state"];
+  confidence: ComponentIdentityFact["confidence"];
+  canonicalTarget?: string;
+  decisionId?: string;
+  evidence: FactId[];
+}): ComponentIdentityFact {
+  return {
+    id: factId("component_identity", { componentKey: input.componentKey }),
+    kind: "component_identity",
+    componentId: asComponentId(input.componentKey),
+    componentKey: input.componentKey,
+    state: input.state,
+    confidence: input.confidence,
+    ...(input.canonicalTarget ? { canonicalTarget: input.canonicalTarget } : {}),
+    ...(input.decisionId ? { decisionId: input.decisionId } : {}),
+    evidence: [...input.evidence],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Classifier facts
 // ---------------------------------------------------------------------------

package/src/facts/facts.test.ts

@@ -10,6 +10,8 @@ import {
   compileGlobalGovernanceFacts,
   g,
   makeTokenDefinitionFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makeUsageNodeFact,
 } from "../index.js";
 import type { ComponentId, FactId, PropValueForbiddenFact } from "../index.js";
@@ -151,6 +153,34 @@ describe("fact IR — content-addressed IDs", () => {
     expect(a).toBe(b);
   });
 
+  it("keys definition and identity facts by the portable componentKey", () => {
+    const first = makeComponentDefinitionFact({
+      file: "src/a/Button.tsx",
+      exportName: "Button",
+      componentKey: "src/a/Button.tsx#Button",
+      renderRoot: { resolution: "intrinsic", tag: "button", interactive: true },
+      propSurface: ["disabled"],
+    });
+    const second = makeComponentDefinitionFact({
+      file: "src/b/Button.tsx",
+      exportName: "Button",
+      componentKey: "src/b/Button.tsx#Button",
+      renderRoot: { resolution: "intrinsic", tag: "button", interactive: true },
+      propSurface: ["disabled"],
+    });
+    const identity = makeComponentIdentityFact({
+      componentKey: first.componentKey,
+      state: "shadow",
+      confidence: "confirmed",
+      canonicalTarget: "Button",
+      evidence: [first.id],
+    });
+
+    expect(first.id).not.toBe(second.id);
+    expect(String(identity.componentId)).toBe(first.componentKey);
+    expect(identity.evidence).toEqual([first.id]);
+  });
+
   it("keeps v1 IDs stable across owned package spellings only in typed identity fields", () => {
     const legacyComponentId = asComponentId("@fragments-sdk/ui#Button");
     const currentComponentId = asComponentId("@usefragments/ui#Button");

package/src/facts/index.ts

@@ -18,6 +18,10 @@ export type {
   CanonicalMappingFact,
   CanonicalReplacementFact,
   ComponentLevelFact,
+  ComponentDefinitionFact,
+  ComponentDefinitionRenderRoot,
+  ComponentIdentityFact,
+  IdentityFact,
   PolicyFact,
   UsageFact,
   ComponentMetadataFact,
@@ -73,6 +77,8 @@ export { componentId, asComponentId, factId, hash64Hex, canonicalJson } from "./
 export {
   makeComponentMetadataFact,
   makeComponentCapabilityFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makePropMetadataFact,
   makePropValueAvoidedFact,
   makePropValueForbiddenFact,

package/src/facts/types.ts

@@ -13,6 +13,7 @@
  */
 
 import type { GovernanceSeverity } from "../governance.js";
+import type { IdentityConfidence, IdentityState } from "../identity/classify.js";
 
 // ---------------------------------------------------------------------------
 // Branded IDs
@@ -574,6 +575,63 @@ export interface CanonicalReplacementFact extends BaseFact {
   location?: FactLocation;
 }
 
+// ---------------------------------------------------------------------------
+// Component identity facts
+// ---------------------------------------------------------------------------
+
+export type ComponentDefinitionRenderRoot =
+  | {
+      resolution: "canonical";
+      canonical: string;
+      importSource: string;
+    }
+  | {
+      resolution: "intrinsic";
+      tag: string;
+      role?: string;
+      interactive?: boolean;
+    }
+  | {
+      resolution: "mixed";
+      canonicals: string[];
+      intrinsics: string[];
+    }
+  | {
+      resolution: "external";
+      importSource: string;
+    }
+  | {
+      resolution: "unresolved";
+      reason: string;
+    };
+
+export interface ComponentDefinitionFact extends BaseFact {
+  kind: "component_definition";
+  /** Index-compatible projection of `componentKey`. */
+  componentId: ComponentId;
+  file: string;
+  exportName: string;
+  componentKey: string;
+  renderRoot: ComponentDefinitionRenderRoot;
+  propSurface: string[];
+  stylingChannel?: {
+    module: string;
+    ownsVisualRole: boolean;
+  };
+}
+
+export interface ComponentIdentityFact extends BaseFact {
+  kind: "component_identity";
+  /** Index-compatible projection of `componentKey`. */
+  componentId: ComponentId;
+  componentKey: string;
+  state: IdentityState;
+  confidence: IdentityConfidence;
+  canonicalTarget?: string;
+  decisionId?: string;
+  evidence: FactId[];
+}
+
 // ---------------------------------------------------------------------------
 // Discriminated unions
 // ---------------------------------------------------------------------------
@@ -622,7 +680,9 @@ export type UsageFact =
   | StructuralConfidenceFact
   | CanonicalReplacementFact;
 
-export type Fact = ComponentLevelFact | PolicyFact | UsageFact;
+export type IdentityFact = ComponentDefinitionFact | ComponentIdentityFact;
+
+export type Fact = ComponentLevelFact | PolicyFact | UsageFact | IdentityFact;
 
 export type FactKind = Fact["kind"];
 

package/src/governance.test.ts

@@ -139,6 +139,32 @@ describe("governance DSL", () => {
     });
   });
 
+  it("preserves top-level component identity decisions", () => {
+    const config = defineConfig({
+      identity: {
+        decisions: [
+          {
+            component: "src/components/AppDialog.tsx#AppDialog",
+            kind: "sanction",
+            canonicalTarget: "Dialog",
+            reason: "Owns the application modal defaults.",
+            decisionId: "local:app-dialog",
+          },
+        ],
+      },
+    });
+
+    expect(config.identity?.decisions).toEqual([
+      {
+        component: "src/components/AppDialog.tsx#AppDialog",
+        kind: "sanction",
+        canonicalTarget: "Dialog",
+        reason: "Owns the application modal defaults.",
+        decisionId: "local:app-dialog",
+      },
+    ]);
+  });
+
   it("rejects unsafe registry canonical source paths", () => {
     expect(() =>
       defineConfig({

package/src/identity/classify.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+
+import { classifyIdentity, type ClassifyIdentityInput } from "./classify.js";
+
+const definition = {
+  componentKey: "src/MyButton.tsx#MyButton",
+  exportName: "MyButton",
+  canonical: false,
+};
+
+function classify(overrides: Partial<ClassifyIdentityInput>) {
+  return classifyIdentity({
+    definition,
+    renderRoot: { kind: "unresolved", reason: "test" },
+    ...overrides,
+  });
+}
+
+describe("classifyIdentity", () => {
+  it("gives canonical membership primary authority", () => {
+    expect(
+      classify({
+        definition: { ...definition, canonical: true },
+        renderRoot: { kind: "external", localName: "Primitive", source: "third-party" },
+      })
+    ).toEqual({ state: "canonical", confidence: "confirmed" });
+  });
+
+  it("keeps an undecided canonical-root wrapper at review confidence", () => {
+    expect(
+      classify({
+        renderRoot: {
+          kind: "canonical",
+          localName: "Button",
+          target: { componentKey: "packages/ui/Button.tsx#Button", role: "Button" },
+        },
+      })
+    ).toEqual({
+      state: "variant",
+      confidence: "review",
+      canonicalTarget: "packages/ui/Button.tsx#Button",
+    });
+  });
+
+  it("classifies an evidenced intrinsic only when the declared vocabulary has its role", () => {
+    expect(
+      classify({
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "button",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "exact-html",
+          canonicalTargets: [{ componentKey: "packages/ui/Button.tsx#Button", role: "Button" }],
+        },
+      })
+    ).toEqual({ state: "shadow", confidence: "confirmed", canonicalTarget: "Button" });
+
+    expect(
+      classify({
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "button",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "exact-html",
+          canonicalTargets: [],
+        },
+      })
+    ).toEqual({ state: "unresolved", confidence: "review" });
+  });
+
+  it("uses supporting evidence only to upgrade confidence", () => {
+    expect(
+      classify({
+        propSurfaceOverlap: 0.8,
+        stylingOwnership: "visual-role",
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "textarea",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "html-advisory",
+          canonicalTargets: [
+            { componentKey: "packages/ui/Textarea.tsx#Textarea", role: "Textarea" },
+          ],
+        },
+      })
+    ).toEqual({ state: "shadow", confidence: "confirmed", canonicalTarget: "Textarea" });
+
+    expect(
+      classify({
+        propSurfaceOverlap: 0.8,
+        stylingOwnership: "layout-only",
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "textarea",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "html-advisory",
+          canonicalTargets: [
+            { componentKey: "packages/ui/Textarea.tsx#Textarea", role: "Textarea" },
+          ],
+        },
+      })
+    ).toEqual({ state: "shadow", confidence: "likely", canonicalTarget: "Textarea" });
+  });
+
+  it("applies wrapper decisions as classification inputs", () => {
+    const renderRoot: ClassifyIdentityInput["renderRoot"] = {
+      kind: "canonical",
+      localName: "Button",
+      target: { componentKey: "packages/ui/Button.tsx#Button", role: "Button" },
+    };
+    expect(
+      classify({
+        renderRoot,
+        decisions: [{ componentKey: definition.componentKey, decision: "sanctioned-wrapper" }],
+      })
+    ).toEqual({
+      state: "variant",
+      confidence: "confirmed",
+      canonicalTarget: "packages/ui/Button.tsx#Button",
+    });
+    expect(
+      classify({
+        renderRoot,
+        decisions: [{ componentKey: definition.componentKey, decision: "rejected-wrapper" }],
+      })
+    ).toEqual({ state: "shadow", confidence: "confirmed", canonicalTarget: "Button" });
+  });
+
+  it("classifies canonical mixtures as composites", () => {
+    expect(
+      classify({
+        renderRoot: {
+          kind: "mixed",
+          canonicalTargets: [{ componentKey: "packages/ui/Card.tsx#Card", role: "Card" }],
+          localTargets: [
+            { componentKey: "src/UserAvatar.tsx#UserAvatar", exportName: "UserAvatar" },
+          ],
+          externalTargets: [],
+          intrinsics: [],
+          unresolvedNames: [],
+        },
+      })
+    ).toEqual({
+      state: "composite",
+      confidence: "confirmed",
+      canonicalTarget: "packages/ui/Card.tsx#Card",
+    });
+  });
+
+  it("distinguishes a canonical consumer from a pass-through wrapper", () => {
+    expect(
+      classify({
+        usageCounts: { staticTextChildren: 1 },
+        renderRoot: {
+          kind: "canonical",
+          localName: "Button",
+          target: { componentKey: "packages/ui/Button.tsx#Button", role: "Button" },
+        },
+      })
+    ).toEqual({
+      state: "composite",
+      confidence: "confirmed",
+      canonicalTarget: "packages/ui/Button.tsx#Button",
+    });
+  });
+
+  it("classifies third-party roots and keeps name similarity message-only", () => {
+    expect(
+      classify({
+        renderRoot: { kind: "external", localName: "Widget", source: "third-party" },
+      })
+    ).toEqual({ state: "external", confidence: "confirmed" });
+
+    expect(
+      classify({
+        nameSimilarityTargets: ["Card", "Button"],
+        renderRoot: { kind: "unresolved", reason: "dynamic factory" },
+      })
+    ).toEqual({ state: "unresolved", confidence: "review", canonicalTarget: "Button" });
+  });
+});