@fragments-sdk/classifier 0.2.0

package/src/signals/prop-fingerprint.ts

@@ -0,0 +1,121 @@
+// PROP_FINGERPRINT — `01-architecture.md` §9.5.
+//
+// Medium-precision signal (base weight 0.3). For each canonical fingerprint:
+//   - All required tests must pass to fire.
+//   - Optional matches add 0.05 each, capped so total weight ≤ 0.6.
+//   - Anti-fingerprint hits subtract 0.15 each (per-canonical).
+//   - Polymorphic prop (`as`/`component`/...) reduces every hypothesis by 0.1
+//     (applied at emit time).
+
+import type { PropFact, UniversalComponentFact } from '@fragments-sdk/extract';
+
+import type { CanonicalId, SignalExtractor, SignalRecord } from '../types.js';
+import {
+  POLYMORPHIC_PROP_NAMES,
+  PROP_FINGERPRINTS,
+  type AntiPropTest,
+  type OptionalPropTest,
+  type RequiredPropTest,
+} from '../vocabulary/prop-fingerprints.js';
+
+const BASE_WEIGHT = 0.3;
+const OPTIONAL_INCREMENT = 0.05;
+const ANTI_DECREMENT = 0.15;
+const POLYMORPHIC_PENALTY = 0.1;
+const MAX_WEIGHT = 0.6;
+
+function findProp(props: ReadonlyArray<PropFact>, name: string): PropFact | undefined {
+  // Aliases like `aria-label` come through verbatim; case-sensitive match.
+  return props.find((p) => p.name === name);
+}
+
+function requiredMatches(
+  props: ReadonlyArray<PropFact>,
+  test: RequiredPropTest,
+): { matched: true; via: string } | { matched: false } {
+  for (const candidate of test.oneOf) {
+    const prop = findProp(props, candidate.name);
+    if (!prop) continue;
+    if (candidate.typeMatcher && !candidate.typeMatcher(prop.typeText)) continue;
+    return { matched: true, via: candidate.name };
+  }
+  return { matched: false };
+}
+
+function optionalMatches(
+  props: ReadonlyArray<PropFact>,
+  test: OptionalPropTest,
+): boolean {
+  const prop = findProp(props, test.name);
+  if (!prop) return false;
+  if (test.typeMatcher && !test.typeMatcher(prop.typeText)) return false;
+  return true;
+}
+
+function antiMatches(
+  props: ReadonlyArray<PropFact>,
+  test: AntiPropTest,
+): boolean {
+  const prop = findProp(props, test.name);
+  if (!prop) return false;
+  if (test.typeMatcher && !test.typeMatcher(prop.typeText)) return false;
+  return true;
+}
+
+function isPolymorphic(props: ReadonlyArray<PropFact>): boolean {
+  return props.some((prop) => POLYMORPHIC_PROP_NAMES.has(prop.name));
+}
+
+const propFingerprint: SignalExtractor = (
+  ucf: UniversalComponentFact,
+): SignalRecord[] => {
+  const polymorphic = isPolymorphic(ucf.props);
+  const out: SignalRecord[] = [];
+
+  for (const [canonical, fingerprint] of PROP_FINGERPRINTS.entries()) {
+    const requiredHits: string[] = [];
+    let allRequired = true;
+    for (const required of fingerprint.required) {
+      const result = requiredMatches(ucf.props, required);
+      if (!result.matched) {
+        allRequired = false;
+        break;
+      }
+      requiredHits.push(result.via);
+    }
+    if (!allRequired) continue;
+
+    const optionalHits: string[] = [];
+    for (const optional of fingerprint.optional) {
+      if (optionalMatches(ucf.props, optional)) optionalHits.push(optional.name);
+    }
+
+    const antiHits: string[] = [];
+    for (const anti of fingerprint.anti) {
+      if (antiMatches(ucf.props, anti)) antiHits.push(anti.name);
+    }
+
+    let weight = BASE_WEIGHT + optionalHits.length * OPTIONAL_INCREMENT;
+    weight -= antiHits.length * ANTI_DECREMENT;
+    if (polymorphic) weight -= POLYMORPHIC_PENALTY;
+
+    if (weight <= 0) continue;
+    if (weight > MAX_WEIGHT) weight = MAX_WEIGHT;
+
+    out.push({
+      type: 'PROP_FINGERPRINT',
+      canonical: canonical as CanonicalId,
+      weight,
+      evidence: {
+        requiredHits,
+        optionalHits,
+        antiHits,
+        polymorphic,
+      },
+    });
+  }
+
+  return out;
+};
+
+export default propFingerprint;

package/src/types.ts

@@ -0,0 +1,58 @@
+// @fragments-sdk/classifier — public types.
+//
+// Mirrors `apps/cloud/docs/canonical-primitive-map/01-architecture.md` §9.
+// Each heuristic signal extractor is a pure function `(ucf) => SignalRecord[]`.
+// The combiner (brief 04) iterates these and applies §10 confidence math.
+
+import type { UniversalComponentFact } from '@fragments-sdk/extract';
+
+export type CanonicalId = string & { readonly __brand: 'CanonicalId' };
+
+export function canonicalId(value: string): CanonicalId {
+  return value as CanonicalId;
+}
+
+export type SignalType =
+  | 'LIBRARY_REEXPORT'
+  | 'HTML_ROOT'
+  | 'ARIA_ROLE'
+  | 'INPUT_TYPE'
+  | 'PROP_FINGERPRINT'
+  | 'NAME_MATCH'
+  | 'PATH_HINT'
+  | 'BARREL_EXPORT'
+  | 'AI_SEMANTIC';
+
+export type HeuristicSignalType = Exclude<SignalType, 'AI_SEMANTIC'>;
+
+export interface SignalRecord {
+  type: SignalType;
+  canonical: CanonicalId;
+  weight: number;
+  evidence: Record<string, unknown>;
+}
+
+export type SignalExtractor = (ucf: UniversalComponentFact) => SignalRecord[];
+
+export type SignalRegistry = Record<HeuristicSignalType, SignalExtractor>;
+
+// `01-architecture.md` §10.3 — confidence band assigned by the combiner.
+export type Band = 'auto' | 'suggested' | 'possible' | 'unknown';
+
+export interface ClassificationAlternate {
+  canonical: CanonicalId;
+  confidence: number;
+  signals: SignalRecord[];
+}
+
+// `01-architecture.md` §10.5 — "show your work" payload.
+export interface Classification {
+  canonical: CanonicalId | 'unknown';
+  confidence: number; // adjusted, post-disagreement-penalty
+  rawConfidence: number; // pre-penalty composition
+  band: Band;
+  signals: SignalRecord[]; // contributing signals for the leading canonical
+  alternates: ClassificationAlternate[];
+  classifierVersion: string;
+  vocabVersion: string;
+}

package/src/vocabulary/canonicals.ts

@@ -0,0 +1,106 @@
+// Vocabulary v0 — ~50 canonical primitives across six categories.
+// Verbatim port of `01-architecture.md` §5.
+
+import { canonicalId, type CanonicalId } from '../types.js';
+
+export type CanonicalCategory =
+  | 'inputs'
+  | 'overlays'
+  | 'navigation'
+  | 'feedback'
+  | 'data'
+  | 'layout';
+
+export interface CanonicalEntry {
+  id: CanonicalId;
+  category: CanonicalCategory;
+  primaryHtmlElement?: string;
+  primaryAriaRole?: string;
+}
+
+const c = canonicalId;
+
+export const VOCAB_V0_VERSION = 'vocab_v0';
+
+export const VOCAB_V0: ReadonlyArray<CanonicalEntry> = [
+  // §5.1 inputs & form controls
+  { id: c('Button'), category: 'inputs', primaryHtmlElement: 'button', primaryAriaRole: 'button' },
+  { id: c('IconButton'), category: 'inputs', primaryHtmlElement: 'button', primaryAriaRole: 'button' },
+  { id: c('ToggleButton'), category: 'inputs', primaryHtmlElement: 'button', primaryAriaRole: 'button' },
+  { id: c('Input'), category: 'inputs', primaryHtmlElement: 'input', primaryAriaRole: 'textbox' },
+  { id: c('Textarea'), category: 'inputs', primaryHtmlElement: 'textarea', primaryAriaRole: 'textbox' },
+  { id: c('NumberInput'), category: 'inputs', primaryHtmlElement: 'input', primaryAriaRole: 'spinbutton' },
+  { id: c('PasswordInput'), category: 'inputs', primaryHtmlElement: 'input', primaryAriaRole: 'textbox' },
+  { id: c('Checkbox'), category: 'inputs', primaryHtmlElement: 'input', primaryAriaRole: 'checkbox' },
+  { id: c('Radio'), category: 'inputs', primaryHtmlElement: 'input', primaryAriaRole: 'radio' },
+  { id: c('RadioGroup'), category: 'inputs', primaryAriaRole: 'radiogroup' },
+  { id: c('Switch'), category: 'inputs', primaryHtmlElement: 'input', primaryAriaRole: 'switch' },
+  { id: c('Slider'), category: 'inputs', primaryAriaRole: 'slider' },
+  { id: c('Select'), category: 'inputs', primaryHtmlElement: 'select', primaryAriaRole: 'combobox' },
+  { id: c('Combobox'), category: 'inputs', primaryAriaRole: 'combobox' },
+  { id: c('MultiSelect'), category: 'inputs', primaryAriaRole: 'listbox' },
+  { id: c('DatePicker'), category: 'inputs' },
+  { id: c('TimePicker'), category: 'inputs' },
+  { id: c('Calendar'), category: 'inputs' },
+  { id: c('Form'), category: 'inputs', primaryHtmlElement: 'form', primaryAriaRole: 'form' },
+  { id: c('Field'), category: 'inputs' },
+  { id: c('Label'), category: 'inputs', primaryHtmlElement: 'label' },
+  { id: c('FieldError'), category: 'inputs', primaryAriaRole: 'alert' },
+  { id: c('FieldHint'), category: 'inputs' },
+
+  // §5.2 disclosure & overlays
+  { id: c('Dialog'), category: 'overlays', primaryHtmlElement: 'dialog', primaryAriaRole: 'dialog' },
+  { id: c('AlertDialog'), category: 'overlays', primaryHtmlElement: 'dialog', primaryAriaRole: 'alertdialog' },
+  { id: c('Drawer'), category: 'overlays', primaryAriaRole: 'dialog' },
+  { id: c('Sheet'), category: 'overlays', primaryAriaRole: 'dialog' },
+  { id: c('Popover'), category: 'overlays', primaryAriaRole: 'dialog' },
+  { id: c('Tooltip'), category: 'overlays', primaryAriaRole: 'tooltip' },
+  { id: c('HoverCard'), category: 'overlays' },
+  { id: c('Toast'), category: 'overlays', primaryAriaRole: 'status' },
+
+  // §5.3 navigation & disclosure-group
+  { id: c('Tabs'), category: 'navigation', primaryAriaRole: 'tablist' },
+  { id: c('Accordion'), category: 'navigation' },
+  { id: c('Disclosure'), category: 'navigation', primaryHtmlElement: 'details' },
+  { id: c('Menu'), category: 'navigation', primaryAriaRole: 'menu' },
+  { id: c('ContextMenu'), category: 'navigation', primaryAriaRole: 'menu' },
+  { id: c('MenuBar'), category: 'navigation', primaryAriaRole: 'menubar' },
+  { id: c('Breadcrumb'), category: 'navigation', primaryHtmlElement: 'nav', primaryAriaRole: 'navigation' },
+  { id: c('Pagination'), category: 'navigation', primaryHtmlElement: 'nav', primaryAriaRole: 'navigation' },
+  { id: c('Stepper'), category: 'navigation' },
+  { id: c('NavigationMenu'), category: 'navigation', primaryHtmlElement: 'nav', primaryAriaRole: 'navigation' },
+
+  // §5.4 display & feedback
+  { id: c('Card'), category: 'feedback' },
+  { id: c('Badge'), category: 'feedback' },
+  { id: c('Chip'), category: 'feedback' },
+  { id: c('Tag'), category: 'feedback' },
+  { id: c('Avatar'), category: 'feedback' },
+  { id: c('Alert'), category: 'feedback', primaryAriaRole: 'alert' },
+  { id: c('Banner'), category: 'feedback' },
+  { id: c('Skeleton'), category: 'feedback' },
+  { id: c('Spinner'), category: 'feedback', primaryAriaRole: 'progressbar' },
+  { id: c('Progress'), category: 'feedback', primaryHtmlElement: 'progress', primaryAriaRole: 'progressbar' },
+  { id: c('Separator'), category: 'feedback', primaryHtmlElement: 'hr', primaryAriaRole: 'separator' },
+
+  // §5.5 data display
+  { id: c('Table'), category: 'data', primaryHtmlElement: 'table', primaryAriaRole: 'table' },
+  { id: c('DataTable'), category: 'data', primaryHtmlElement: 'table', primaryAriaRole: 'grid' },
+  { id: c('List'), category: 'data', primaryHtmlElement: 'ul', primaryAriaRole: 'list' },
+  { id: c('Tree'), category: 'data', primaryAriaRole: 'tree' },
+  { id: c('ScrollArea'), category: 'data' },
+
+  // §5.6 layout primitives (controversial — see §22)
+  { id: c('Stack'), category: 'layout' },
+  { id: c('Grid'), category: 'layout' },
+  { id: c('Box'), category: 'layout' },
+  { id: c('Container'), category: 'layout' },
+];
+
+export const VOCAB_V0_INDEX: ReadonlyMap<string, CanonicalEntry> = new Map(
+  VOCAB_V0.map((entry) => [entry.id as string, entry]),
+);
+
+export function isCanonicalId(value: string): value is CanonicalId {
+  return VOCAB_V0_INDEX.has(value);
+}

package/src/vocabulary/library-map.ts

@@ -0,0 +1,301 @@
+// LIBRARY_REEXPORT lookup table — `01-architecture.md` §9.1.
+//
+// Keyed by `package → importedName → canonical`. The signal fires when a
+// component imports a known primitive AND uses the local binding as a JSX
+// root. Sub-primitive policy (§9.1 final paragraph): only root-aligned wrappers
+// emit, so we map only the root-level identifier per package and let
+// compound-children detection on the parent classify the sub-parts.
+
+import { canonicalId, type CanonicalId } from '../types.js';
+
+export interface LibraryMapEntry {
+  canonical: CanonicalId;
+}
+
+export type LibraryMap = ReadonlyMap<
+  string,
+  ReadonlyMap<string, LibraryMapEntry>
+>;
+
+const c = canonicalId;
+
+function entries(
+  pkg: string,
+  ...rows: Array<[string, CanonicalId]>
+): [string, ReadonlyMap<string, LibraryMapEntry>] {
+  return [pkg, new Map(rows.map(([imported, canon]) => [imported, { canonical: canon }]))];
+}
+
+// Default exports use the literal key 'default'. Namespace imports (`* as ns`)
+// are matched per-name by walking the namespace usage at signal time.
+export const LIBRARY_MAP: LibraryMap = new Map([
+  // ── Radix UI ──────────────────────────────────────────────────────
+  entries('@radix-ui/react-dialog', ['Root', c('Dialog')], ['default', c('Dialog')]),
+  entries('@radix-ui/react-tooltip', ['Root', c('Tooltip')]),
+  entries('@radix-ui/react-popover', ['Root', c('Popover')]),
+  entries('@radix-ui/react-tabs', ['Root', c('Tabs')]),
+  entries('@radix-ui/react-accordion', ['Root', c('Accordion')]),
+  entries('@radix-ui/react-checkbox', ['Root', c('Checkbox')]),
+  entries('@radix-ui/react-switch', ['Root', c('Switch')]),
+  entries('@radix-ui/react-slider', ['Root', c('Slider')]),
+  entries('@radix-ui/react-select', ['Root', c('Select')]),
+  entries('@radix-ui/react-radio-group', ['Root', c('RadioGroup')]),
+  entries('@radix-ui/react-progress', ['Root', c('Progress')]),
+  entries('@radix-ui/react-separator', ['Root', c('Separator')]),
+  entries('@radix-ui/react-alert-dialog', ['Root', c('AlertDialog')]),
+  entries('@radix-ui/react-context-menu', ['Root', c('ContextMenu')]),
+  entries('@radix-ui/react-dropdown-menu', ['Root', c('Menu')]),
+  entries('@radix-ui/react-hover-card', ['Root', c('HoverCard')]),
+  entries('@radix-ui/react-menubar', ['Root', c('MenuBar')]),
+  entries('@radix-ui/react-navigation-menu', ['Root', c('NavigationMenu')]),
+  entries('@radix-ui/react-scroll-area', ['Root', c('ScrollArea')]),
+  entries('@radix-ui/react-toast', ['Root', c('Toast')]),
+  entries('@radix-ui/react-toggle', ['Root', c('ToggleButton')]),
+  entries('@radix-ui/react-toggle-group', ['Root', c('ToggleButton')]),
+  entries('@radix-ui/react-avatar', ['Root', c('Avatar')]),
+  entries('@radix-ui/react-label', ['Root', c('Label')]),
+  entries('@radix-ui/react-form', ['Root', c('Form')]),
+
+  // ── Base UI ───────────────────────────────────────────────────────
+  entries('@base-ui-components/react/dialog', ['Root', c('Dialog')], ['Dialog', c('Dialog')]),
+  entries('@base-ui-components/react/tooltip', ['Root', c('Tooltip')], ['Tooltip', c('Tooltip')]),
+  entries('@base-ui-components/react/menu', ['Root', c('Menu')], ['Menu', c('Menu')]),
+  entries('@base-ui-components/react/select', ['Root', c('Select')], ['Select', c('Select')]),
+  entries('@base-ui-components/react/combobox', ['Root', c('Combobox')], ['Combobox', c('Combobox')]),
+  entries('@base-ui-components/react/tabs', ['Root', c('Tabs')], ['Tabs', c('Tabs')]),
+  entries('@base-ui-components/react/popover', ['Root', c('Popover')], ['Popover', c('Popover')]),
+  entries('@base-ui-components/react/checkbox', ['Root', c('Checkbox')], ['Checkbox', c('Checkbox')]),
+  entries('@base-ui-components/react/switch', ['Root', c('Switch')], ['Switch', c('Switch')]),
+  entries('@base-ui-components/react/slider', ['Root', c('Slider')], ['Slider', c('Slider')]),
+  entries('@base-ui-components/react/radio-group', ['Root', c('RadioGroup')], ['RadioGroup', c('RadioGroup')]),
+  entries('@base-ui-components/react/accordion', ['Root', c('Accordion')], ['Accordion', c('Accordion')]),
+  entries('@base-ui-components/react/separator', ['Root', c('Separator')], ['Separator', c('Separator')]),
+  entries('@base-ui-components/react/progress', ['Root', c('Progress')], ['Progress', c('Progress')]),
+  entries('@base-ui-components/react/scroll-area', ['Root', c('ScrollArea')]),
+  entries('@base-ui-components/react/toggle', ['Root', c('ToggleButton')]),
+  entries('@base-ui-components/react/toggle-group', ['Root', c('ToggleButton')]),
+  entries('@base-ui-components/react/alert-dialog', ['Root', c('AlertDialog')]),
+  entries('@base-ui-components/react/context-menu', ['Root', c('ContextMenu')]),
+  entries('@base-ui-components/react/menubar', ['Root', c('MenuBar')]),
+  entries('@base-ui-components/react/navigation-menu', ['Root', c('NavigationMenu')]),
+  entries('@base-ui-components/react/avatar', ['Root', c('Avatar')]),
+  entries('@base-ui-components/react/field', ['Root', c('Field')]),
+  entries('@base-ui-components/react/form', ['Root', c('Form')]),
+
+  // ── Headless UI ───────────────────────────────────────────────────
+  entries(
+    '@headlessui/react',
+    ['Dialog', c('Dialog')],
+    ['Menu', c('Menu')],
+    ['Listbox', c('Select')],
+    ['Combobox', c('Combobox')],
+    ['Switch', c('Switch')],
+    ['RadioGroup', c('RadioGroup')],
+    ['Tab', c('Tabs')],
+    ['Disclosure', c('Disclosure')],
+    ['Popover', c('Popover')],
+    ['Transition', c('Box')],
+  ),
+
+  // ── React Aria Components ─────────────────────────────────────────
+  entries(
+    'react-aria-components',
+    ['Button', c('Button')],
+    ['ToggleButton', c('ToggleButton')],
+    ['Checkbox', c('Checkbox')],
+    ['Radio', c('Radio')],
+    ['RadioGroup', c('RadioGroup')],
+    ['Switch', c('Switch')],
+    ['Slider', c('Slider')],
+    ['Select', c('Select')],
+    ['ComboBox', c('Combobox')],
+    ['ListBox', c('Select')],
+    ['Menu', c('Menu')],
+    ['Dialog', c('Dialog')],
+    ['Modal', c('Dialog')],
+    ['Popover', c('Popover')],
+    ['Tooltip', c('Tooltip')],
+    ['Tabs', c('Tabs')],
+    ['DateField', c('DatePicker')],
+    ['DatePicker', c('DatePicker')],
+    ['Calendar', c('Calendar')],
+    ['NumberField', c('NumberInput')],
+    ['TextField', c('Input')],
+    ['SearchField', c('Input')],
+    ['ProgressBar', c('Progress')],
+    ['Breadcrumbs', c('Breadcrumb')],
+  ),
+
+  // ── MUI ───────────────────────────────────────────────────────────
+  entries('@mui/material', ['Button', c('Button')], ['default', c('Button')]),
+  entries('@mui/material/Button', ['default', c('Button')]),
+  entries('@mui/material/IconButton', ['default', c('IconButton')]),
+  entries('@mui/material/ToggleButton', ['default', c('ToggleButton')]),
+  entries('@mui/material/TextField', ['default', c('Input')]),
+  entries('@mui/material/OutlinedInput', ['default', c('Input')]),
+  entries('@mui/material/FilledInput', ['default', c('Input')]),
+  entries('@mui/material/Input', ['default', c('Input')]),
+  entries('@mui/material/InputBase', ['default', c('Input')]),
+  entries('@mui/material/Checkbox', ['default', c('Checkbox')]),
+  entries('@mui/material/Radio', ['default', c('Radio')]),
+  entries('@mui/material/RadioGroup', ['default', c('RadioGroup')]),
+  entries('@mui/material/Switch', ['default', c('Switch')]),
+  entries('@mui/material/Slider', ['default', c('Slider')]),
+  entries('@mui/material/Select', ['default', c('Select')]),
+  entries('@mui/material/Autocomplete', ['default', c('Combobox')]),
+  entries('@mui/material/Dialog', ['default', c('Dialog')]),
+  entries('@mui/material/Drawer', ['default', c('Drawer')]),
+  entries('@mui/material/Popover', ['default', c('Popover')]),
+  entries('@mui/material/Tooltip', ['default', c('Tooltip')]),
+  entries('@mui/material/Snackbar', ['default', c('Toast')]),
+  entries('@mui/material/Alert', ['default', c('Alert')]),
+  entries('@mui/material/Tabs', ['default', c('Tabs')]),
+  entries('@mui/material/Tab', ['default', c('Tabs')]),
+  entries('@mui/material/Accordion', ['default', c('Accordion')]),
+  entries('@mui/material/Menu', ['default', c('Menu')]),
+  entries('@mui/material/Breadcrumbs', ['default', c('Breadcrumb')]),
+  entries('@mui/material/Pagination', ['default', c('Pagination')]),
+  entries('@mui/material/Stepper', ['default', c('Stepper')]),
+  entries('@mui/material/Avatar', ['default', c('Avatar')]),
+  entries('@mui/material/Badge', ['default', c('Badge')]),
+  entries('@mui/material/Chip', ['default', c('Chip')]),
+  entries('@mui/material/Card', ['default', c('Card')]),
+  entries('@mui/material/Skeleton', ['default', c('Skeleton')]),
+  entries('@mui/material/CircularProgress', ['default', c('Spinner')]),
+  entries('@mui/material/LinearProgress', ['default', c('Progress')]),
+  entries('@mui/material/Divider', ['default', c('Separator')]),
+  entries('@mui/material/Table', ['default', c('Table')]),
+  entries('@mui/material/List', ['default', c('List')]),
+  entries('@mui/material/Stack', ['default', c('Stack')]),
+  entries('@mui/material/Grid', ['default', c('Grid')]),
+  entries('@mui/material/Box', ['default', c('Box')]),
+  entries('@mui/material/Container', ['default', c('Container')]),
+  entries('@mui/material/FormLabel', ['default', c('Label')]),
+  entries('@mui/material/FormHelperText', ['default', c('FieldHint')]),
+  entries('@mui/material/FormControl', ['default', c('Field')]),
+  entries('@mui/x-date-pickers/DatePicker', ['DatePicker', c('DatePicker')]),
+  entries('@mui/x-date-pickers/TimePicker', ['TimePicker', c('TimePicker')]),
+  entries('@mui/x-date-pickers/DateCalendar', ['DateCalendar', c('Calendar')]),
+  entries('@mui/x-data-grid', ['DataGrid', c('DataTable')]),
+
+  // ── Chakra ────────────────────────────────────────────────────────
+  entries(
+    '@chakra-ui/react',
+    ['Button', c('Button')],
+    ['IconButton', c('IconButton')],
+    ['Input', c('Input')],
+    ['Textarea', c('Textarea')],
+    ['NumberInput', c('NumberInput')],
+    ['Checkbox', c('Checkbox')],
+    ['Radio', c('Radio')],
+    ['RadioGroup', c('RadioGroup')],
+    ['Switch', c('Switch')],
+    ['Slider', c('Slider')],
+    ['Select', c('Select')],
+    ['Modal', c('Dialog')],
+    ['AlertDialog', c('AlertDialog')],
+    ['Drawer', c('Drawer')],
+    ['Popover', c('Popover')],
+    ['Tooltip', c('Tooltip')],
+    ['Toast', c('Toast')],
+    ['Alert', c('Alert')],
+    ['Tabs', c('Tabs')],
+    ['Accordion', c('Accordion')],
+    ['Menu', c('Menu')],
+    ['Breadcrumb', c('Breadcrumb')],
+    ['Avatar', c('Avatar')],
+    ['Badge', c('Badge')],
+    ['Tag', c('Tag')],
+    ['Card', c('Card')],
+    ['Skeleton', c('Skeleton')],
+    ['Spinner', c('Spinner')],
+    ['Progress', c('Progress')],
+    ['Divider', c('Separator')],
+    ['Table', c('Table')],
+    ['List', c('List')],
+    ['Stack', c('Stack')],
+    ['HStack', c('Stack')],
+    ['VStack', c('Stack')],
+    ['Grid', c('Grid')],
+    ['Box', c('Box')],
+    ['Container', c('Container')],
+    ['FormLabel', c('Label')],
+    ['FormHelperText', c('FieldHint')],
+    ['FormErrorMessage', c('FieldError')],
+    ['FormControl', c('Field')],
+  ),
+  entries('@chakra-ui/button', ['Button', c('Button')], ['IconButton', c('IconButton')]),
+
+  // ── Mantine ───────────────────────────────────────────────────────
+  entries(
+    '@mantine/core',
+    ['Button', c('Button')],
+    ['ActionIcon', c('IconButton')],
+    ['UnstyledButton', c('Button')],
+    ['TextInput', c('Input')],
+    ['PasswordInput', c('PasswordInput')],
+    ['NumberInput', c('NumberInput')],
+    ['Textarea', c('Textarea')],
+    ['Checkbox', c('Checkbox')],
+    ['Radio', c('Radio')],
+    ['Switch', c('Switch')],
+    ['Slider', c('Slider')],
+    ['RangeSlider', c('Slider')],
+    ['Select', c('Select')],
+    ['MultiSelect', c('MultiSelect')],
+    ['Autocomplete', c('Combobox')],
+    ['Combobox', c('Combobox')],
+    ['Modal', c('Dialog')],
+    ['Drawer', c('Drawer')],
+    ['Popover', c('Popover')],
+    ['Tooltip', c('Tooltip')],
+    ['HoverCard', c('HoverCard')],
+    ['Notification', c('Toast')],
+    ['Alert', c('Alert')],
+    ['Tabs', c('Tabs')],
+    ['Accordion', c('Accordion')],
+    ['Menu', c('Menu')],
+    ['Breadcrumbs', c('Breadcrumb')],
+    ['Pagination', c('Pagination')],
+    ['Stepper', c('Stepper')],
+    ['Avatar', c('Avatar')],
+    ['Badge', c('Badge')],
+    ['Chip', c('Chip')],
+    ['Card', c('Card')],
+    ['Skeleton', c('Skeleton')],
+    ['Loader', c('Spinner')],
+    ['Progress', c('Progress')],
+    ['Divider', c('Separator')],
+    ['Table', c('Table')],
+    ['List', c('List')],
+    ['Stack', c('Stack')],
+    ['Group', c('Stack')],
+    ['Grid', c('Grid')],
+    ['Box', c('Box')],
+    ['Container', c('Container')],
+    ['ScrollArea', c('ScrollArea')],
+    ['NavLink', c('NavigationMenu')],
+  ),
+  entries('@mantine/dates', ['DatePicker', c('DatePicker')], ['DateInput', c('DatePicker')], ['TimeInput', c('TimePicker')], ['Calendar', c('Calendar')]),
+
+  // ── Specialised utility libraries (§9.1 named utilities) ──────────
+  entries('cmdk', ['Command', c('Combobox')], ['default', c('Combobox')]),
+  entries('vaul', ['Drawer', c('Drawer')], ['default', c('Drawer')]),
+  entries('react-day-picker', ['DayPicker', c('Calendar')], ['default', c('Calendar')]),
+  entries('react-datepicker', ['default', c('DatePicker')]),
+  entries('react-modal', ['default', c('Dialog')]),
+  entries('react-tooltip', ['Tooltip', c('Tooltip')]),
+  entries('react-toastify', ['ToastContainer', c('Toast')], ['toast', c('Toast')]),
+  entries('react-hot-toast', ['Toaster', c('Toast')], ['default', c('Toast')]),
+  entries('sonner', ['Toaster', c('Toast')], ['toast', c('Toast')]),
+  entries('react-select', ['default', c('Select')]),
+  entries('downshift', ['default', c('Combobox')], ['useCombobox', c('Combobox')]),
+]);
+
+// Quick lookup: package + imported name → canonical id (or undefined).
+export function lookupLibraryImport(
+  pkg: string,
+  importedName: string,
+): CanonicalId | undefined {
+  return LIBRARY_MAP.get(pkg)?.get(importedName)?.canonical;
+}