@ccheever/exact-facet-core 0.1.0

package/src/__tests__/theme-definition-resolution.test.ts

@@ -0,0 +1,235 @@
+/// <reference path="../../../../js/src/types/bun-test.d.ts" />
+// LLP 0269 Theme Verification: the definition-to-resolved-token golden.
+//
+// `resolve(definition)` is the styling layer's pure function. This golden pins
+// the stable resolved anchors of the default definition (the shipped Facet
+// look), asserts the resolver is deterministic, that every dial actually moves
+// the tokens below it, that the runtime inputs (scheme / reduced motion / text
+// scale / contrast / size class) resolve coherently, and that the default
+// resolves AA-clean. A drift in any of these fails here before it ships.
+
+import { afterEach, describe, expect, it } from 'bun:test';
+
+import {
+  resolveCompactInset,
+  resolveDensityPadding,
+  resolveFieldInputStyle,
+  validateFacetContrast,
+  type Scheme,
+} from '../internals.js';
+import {
+  resolveButtonPadding,
+  resolveCardPadding,
+  setFacetParamOverrides,
+} from '../facet-overrides.js';
+import {
+  concentricOuterRadius,
+  concentricRadius,
+  defaultThemeDefinition,
+  resolveFacetTheme,
+  type FacetThemeDefinition,
+} from '../theme-definition.js';
+
+describe('resolve(definition) golden (LLP 0269)', () => {
+  it('is deterministic — same definition + inputs yields a deep-equal theme', () => {
+    const a = resolveFacetTheme(defaultThemeDefinition, { scheme: 'light' });
+    const b = resolveFacetTheme(defaultThemeDefinition, { scheme: 'light' });
+    expect(a).toEqual(b);
+  });
+
+  it('pins the default light resolved anchors', () => {
+    const t = resolveFacetTheme(defaultThemeDefinition, { scheme: 'light' });
+    expect(t.scheme).toBe('light');
+    // Surfaces: old surface→card (raised white), old surfaceAlt→surface (recessed).
+    expect(t.color.background.body).toBe('#fbfbfc');
+    expect(t.color.background.surface).toBe('#f3f3f5');
+    expect(t.color.background.card).toBe('#ffffff');
+    expect(t.color.text.primary).toBe('#1c1d21');
+    expect(t.color.text.secondary).toBe('#5f636c');
+    expect(t.color.border.default).toBe('#e4e4e9');
+    // Accent family generated from the single dial.
+    expect(t.color.accent.fill).toBe('#5e6ad2');
+    expect(t.color.accent.onFill).toBe('#ffffff');
+    expect(t.color.accent.hover).not.toBe(t.color.accent.fill);
+    expect(t.color.accent.pressed).not.toBe(t.color.accent.hover);
+    // Space / radius / density / type anchors.
+    expect(t.space).toEqual({ xs: 6, sm: 10, md: 14, lg: 20, xl: 28 });
+    expect(t.radius).toEqual({ none: 0, inner: 6, element: 8, container: 10, page: 14, full: 999 });
+    expect(t.density.mode).toBe('default');
+    expect(t.density.controlHeight.md).toBe(40);
+    expect(t.type.body.fontSize).toBe(14);
+    expect(t.type.body.lineHeight).toBe(21);
+    expect(t.type.caption.fontSize).toBe(12);
+    expect(t.type.title.fontSize).toBe(17);
+    expect(t.type.heading.fontSize).toBe(20);
+    expect(t.type.display.fontSize).toBe(24);
+    expect(t.zIndex.modal).toBe(1400);
+    expect(t.motion.reducedMotion).toBe(false);
+    expect(t.motion.duration.fast).toBe(100);
+    expect(t.adaptation.platform).toBe('web');
+  });
+
+  it('pins the default dark resolved anchors', () => {
+    const t = resolveFacetTheme(defaultThemeDefinition, { scheme: 'dark' });
+    expect(t.scheme).toBe('dark');
+    expect(t.color.background.body).toBe('#08090a');
+    expect(t.color.background.card).toBe('#0f1011');
+    expect(t.color.background.surface).toBe('#141517');
+    expect(t.color.text.primary).toBe('#f7f8f8');
+    expect(t.color.accent.fill).toBe('#5e6ad2');
+  });
+
+  it('every dial moves the tokens below it', () => {
+    const base = resolveFacetTheme(defaultThemeDefinition, { scheme: 'light' });
+
+    const accent = resolveFacetTheme({ ...defaultThemeDefinition, accent: '#1d9bf0' }, { scheme: 'light' });
+    expect(accent.color.accent.fill).toBe('#1d9bf0');
+    expect(accent.color.accent.hover).not.toBe(base.color.accent.hover);
+
+    const dense = resolveFacetTheme({ ...defaultThemeDefinition, density: 'compact' }, { scheme: 'light' });
+    expect(dense.density.controlHeight.md).toBeLessThan(base.density.controlHeight.md);
+
+    const ratio = resolveFacetTheme(
+      { ...defaultThemeDefinition, type: { ...defaultThemeDefinition.type, ratio: 'golden' } },
+      { scheme: 'light' },
+    );
+    expect(ratio.type.heading.fontSize).toBeGreaterThan(base.type.heading.fontSize);
+
+    const rounder = resolveFacetTheme(
+      { ...defaultThemeDefinition, radius: { scale: 'facetDefault', multiplier: 2 } },
+      { scheme: 'light' },
+    );
+    expect(rounder.radius.element).toBe(base.radius.element * 2);
+
+    const slower = resolveFacetTheme(
+      { ...defaultThemeDefinition, motion: { multiplier: 2 } },
+      { scheme: 'light' },
+    );
+    expect(slower.motion.duration.fast).toBe(base.motion.duration.fast * 2);
+    expect(slower.motion.multiplier).toBe(2);
+  });
+
+  it('folds runtime inputs (reduced motion, text scale, contrast) coherently', () => {
+    const reduced = resolveFacetTheme(defaultThemeDefinition, { scheme: 'light', reducedMotion: true });
+    expect(reduced.motion.reducedMotion).toBe(true);
+    expect(reduced.motion.preset.controlPress.transform).toBeUndefined();
+    expect(reduced.adaptation.reducedMotion).toBe(true);
+
+    const scaled = resolveFacetTheme(defaultThemeDefinition, { scheme: 'light', textScale: 1.5 });
+    expect(scaled.type.body.fontSize).toBe(21); // round(14 * 1.5)
+    expect(scaled.adaptation.textScale).toBe(1.5);
+
+    const increased = resolveFacetTheme(defaultThemeDefinition, { scheme: 'light', contrast: 'increased' });
+    expect(increased.adaptation.contrast).toBe('increased');
+    expect(increased.color.text.secondary).not.toBe(
+      resolveFacetTheme(defaultThemeDefinition, { scheme: 'light' }).color.text.secondary,
+    );
+  });
+
+  it('resolves the default AA-clean in both schemes', () => {
+    for (const scheme of ['light', 'dark'] as Scheme[]) {
+      expect(validateFacetContrast(resolveFacetTheme(defaultThemeDefinition, { scheme }))).toEqual([]);
+    }
+  });
+
+  it('flips the accent on-color toward ink for a light accent', () => {
+    // A bright accent cannot carry white text; the resolver must pick the dark
+    // ink on-color (not blindly keep white), and that pairing stays legible.
+    const def: FacetThemeDefinition = { ...defaultThemeDefinition, accent: '#f5d90a' };
+    const t = resolveFacetTheme(def, { scheme: 'light' });
+    expect(t.color.accent.onFill).toBe('#0e0f12');
+    expect(validateFacetContrast(t).filter((f) => f.startsWith('accent.onFill'))).toEqual([]);
+  });
+});
+
+// LLP 0283 D10 / LLP 0269 §5–§6: the recipe-consumption gate. The resolver
+// emitting `paddingScale` and `concentricRadius` is not enough — these pins
+// prove the apply-time mechanisms actually move recipe output, so the
+// density dial is *felt* and concentricity is computed, not decorative.
+describe('density and concentricity reach recipes (LLP 0283 D10)', () => {
+  const atDensity = (density: FacetThemeDefinition['density']) =>
+    resolveFacetTheme({ ...defaultThemeDefinition, density }, { scheme: 'light' });
+
+  afterEach(() => {
+    setFacetParamOverrides(null);
+  });
+
+  it('resolveDensityPadding is identity at default density (byte-identical shipped look)', () => {
+    const t = atDensity('default');
+    expect(t.density.paddingScale).toBe(1);
+    for (const base of [6, 10, 14, 20, 28]) {
+      expect(resolveDensityPadding(t, base)).toBe(base);
+    }
+  });
+
+  it('resolveDensityPadding scales with the density dial and guards bad scales', () => {
+    expect(resolveDensityPadding(atDensity('compact'), 14)).toBe(12); // 14 * 0.85
+    expect(resolveDensityPadding(atDensity('comfortable'), 14)).toBe(16); // 14 * 1.15
+    expect(resolveDensityPadding(atDensity('gigantic'), 14)).toBe(20); // 14 * 1.4
+    const broken = atDensity('default');
+    (broken.density as { paddingScale: number }).paddingScale = Number.NaN;
+    expect(resolveDensityPadding(broken, 14)).toBe(14); // falls back to 1, never 0
+  });
+
+  it('button padding derives from the density dial (default pins the shipped 14/6)', () => {
+    expect(resolveButtonPadding(atDensity('default'), 'primary')).toEqual({
+      paddingX: 14,
+      paddingY: 6,
+    });
+    expect(resolveButtonPadding(atDensity('compact'), 'primary')).toEqual({
+      paddingX: 12,
+      paddingY: 5,
+    });
+    expect(resolveButtonPadding(atDensity('gigantic'), 'primary')).toEqual({
+      paddingX: 20,
+      paddingY: 8,
+    });
+  });
+
+  it('card padding derives from the density dial (default pins the shipped 20)', () => {
+    expect(resolveCardPadding(atDensity('default'))).toBe(20);
+    expect(resolveCardPadding(atDensity('compact'))).toBe(17);
+    expect(resolveCardPadding(atDensity('gigantic'))).toBe(28);
+  });
+
+  it('an explicit facet override is absolute — density does not re-scale it', () => {
+    setFacetParamOverrides({ FacetButton: { base: { paddingX: 24 } } });
+    expect(resolveButtonPadding(atDensity('default'), 'primary').paddingX).toBe(24);
+    expect(resolveButtonPadding(atDensity('gigantic'), 'primary').paddingX).toBe(24);
+    // The un-overridden axis still tracks the dial.
+    expect(resolveButtonPadding(atDensity('gigantic'), 'primary').paddingY).toBe(8);
+  });
+
+  it('field input padding derives from the density dial (default pins the shipped 14/10)', () => {
+    const defaultStyle = resolveFieldInputStyle(atDensity('default'), {
+      variant: 'default',
+      loading: false,
+    });
+    expect(defaultStyle.paddingLeft).toBe(14);
+    expect(defaultStyle.paddingTop).toBe(10);
+    const gigantic = resolveFieldInputStyle(atDensity('gigantic'), {
+      variant: 'default',
+      loading: false,
+    });
+    expect(gigantic.paddingLeft).toBe(20);
+    expect(gigantic.paddingTop).toBe(14);
+  });
+
+  it('concentric radii are computed at apply time from instance geometry', () => {
+    const t = atDensity('default');
+    // Checkbox control: inward concentricity across the compact inset —
+    // pins the shipped 6 (element 8 − inset 2).
+    expect(concentricRadius(t.radius.element, resolveCompactInset(t))).toBe(6);
+    // Field focus halo: outward concentricity across the ring inset —
+    // container 10 + inset 3 hugs the chrome (the pre-D10 hardcoded
+    // radius.page=14 did not track the radius dials).
+    expect(concentricOuterRadius(t.radius.container, Math.max(1, Math.round(t.space.xs / 2)))).toBe(13);
+    // Under a different radius scale the ring keeps hugging the chrome.
+    const round = resolveFacetTheme(
+      { ...defaultThemeDefinition, radius: { scale: 'round', multiplier: 1 } },
+      { scheme: 'light' },
+    );
+    expect(concentricOuterRadius(round.radius.container, 3)).toBe(25);
+    expect(concentricRadius(0, 5)).toBe(0); // clamped, never negative
+  });
+});

package/src/__tests__/theme-store-parity.test.ts

@@ -0,0 +1,283 @@
+/// <reference path="../../../../js/src/types/bun-test.d.ts" />
+// LLP 0157 §2 / LLP 0269: theme-store resolution matrix.
+//
+// After the LLP 0269 revision the store resolves the theme as
+// `resolve(definition)` plus the override cascade. The reference arm is a
+// frozen, independent copy of that resolution (definition → resolveFacetTheme →
+// deep-merged overrides → reduced-motion + size-class), so the matrix still
+// catches store/resolver drift across
+// (scheme/system/custom theme × token overrides × agent override × reduced
+// motion). A separate block exercises the definition-dial path the revision
+// added.
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+
+import {
+  _resetExperienceRegistryForTests,
+  getThemeOverride,
+  getThemeSnapshot,
+  setThemeOverride,
+} from '@exact/core/agent';
+
+import {
+  applyMotionPreference,
+  deepMerge,
+  resolveSizeClassForWidth,
+  type DeepPartial,
+  type FacetTheme,
+  type Scheme,
+} from '../internals.js';
+import {
+  darkTheme,
+  defaultThemeDefinition,
+  resolveFacetTheme,
+} from '../theme-definition.js';
+import { _resetFacetOverridesForTests, setThemeDefinitionOverrides } from '../facet-overrides.js';
+import {
+  _resetThemeStoreForTesting,
+  registerThemeScope,
+  resolveThemeForConfig,
+  setThemeReducedMotion,
+  setThemeSystemAppearance,
+  type ThemeScopeConfig,
+} from '../theme-store.js';
+
+// The store's default viewport input (store-machinery createHostInput(390)).
+const DEFAULT_VIEWPORT = 390;
+
+/**
+ * Frozen, independent copy of the store's resolution (do not refactor to share
+ * code with the store — the duplication is the point of the parity test).
+ */
+function referenceResolve(
+  props: {
+    theme?: Scheme | 'system' | FacetTheme;
+    scheme?: Scheme | 'system';
+    overrides?: DeepPartial<FacetTheme>;
+  },
+  systemScheme: Scheme,
+  prefersReducedMotion: boolean,
+  registryOverride: Record<string, unknown> | null,
+): FacetTheme {
+  const requestedTheme = props.theme ?? props.scheme ?? 'system';
+  const baseTheme =
+    typeof requestedTheme === 'object'
+      ? requestedTheme
+      : resolveFacetTheme(defaultThemeDefinition, {
+          scheme: (requestedTheme === 'system' ? systemScheme : requestedTheme) === 'dark' ? 'dark' : 'light',
+          reducedMotion: prefersReducedMotion,
+          viewportWidth: DEFAULT_VIEWPORT,
+        });
+  const mergedTheme = deepMerge(
+    deepMerge(baseTheme, props.overrides),
+    registryOverride as DeepPartial<FacetTheme> | null | undefined,
+  );
+  return {
+    ...mergedTheme,
+    sizeClass: resolveSizeClassForWidth(DEFAULT_VIEWPORT, mergedTheme.sizeClasses),
+    motion: applyMotionPreference(mergedTheme.motion, prefersReducedMotion),
+  };
+}
+
+const customTheme: FacetTheme = {
+  ...darkTheme,
+  name: 'custom-test',
+  color: { ...darkTheme.color, accent: { ...darkTheme.color.accent, fill: '#123456' } },
+};
+
+const SCHEME_CELLS: Array<{
+  label: string;
+  config: ThemeScopeConfig;
+}> = [
+  { label: 'theme=light', config: { theme: 'light' } },
+  { label: 'theme=dark', config: { theme: 'dark' } },
+  { label: 'theme=system', config: { theme: 'system' } },
+  { label: 'scheme=dark', config: { scheme: 'dark' } },
+  { label: 'default (system)', config: {} },
+  { label: 'custom theme object', config: { theme: customTheme } },
+];
+
+const OVERRIDE_CELLS: Array<DeepPartial<FacetTheme> | undefined> = [
+  undefined,
+  { color: { accent: { fill: '#ff5500' }, text: { primary: '#101010' } }, radius: { container: 5 } },
+];
+
+const AGENT_OVERRIDE_CELLS: Array<Record<string, unknown> | null> = [
+  null,
+  { color: { background: { body: '#000011' }, accent: { fill: '#22ddaa' } } },
+];
+
+const SYSTEM_CELLS: Scheme[] = ['light', 'dark'];
+const REDUCED_MOTION_CELLS = [false, true];
+
+beforeEach(() => {
+  _resetThemeStoreForTesting();
+  _resetFacetOverridesForTests();
+  _resetExperienceRegistryForTests();
+});
+
+afterEach(() => {
+  _resetThemeStoreForTesting();
+  _resetFacetOverridesForTests();
+  _resetExperienceRegistryForTests();
+});
+
+describe('theme store resolution matrix (LLP 0157 §2 / LLP 0269)', () => {
+  it('matches an independent resolve(definition) + cascade for every matrix cell', () => {
+    for (const schemeCell of SCHEME_CELLS) {
+      for (const overrides of OVERRIDE_CELLS) {
+        for (const agentOverride of AGENT_OVERRIDE_CELLS) {
+          for (const systemScheme of SYSTEM_CELLS) {
+            for (const reducedMotion of REDUCED_MOTION_CELLS) {
+              setThemeOverride(agentOverride);
+              setThemeSystemAppearance(systemScheme);
+              setThemeReducedMotion(reducedMotion);
+
+              const config: ThemeScopeConfig = {
+                ...schemeCell.config,
+                overrides,
+              };
+              const storeResolved = resolveThemeForConfig(config);
+              const reference = referenceResolve(
+                {
+                  theme: schemeCell.config.theme,
+                  scheme: schemeCell.config.scheme,
+                  overrides,
+                },
+                systemScheme,
+                reducedMotion,
+                agentOverride,
+              );
+
+              expect(
+                storeResolved,
+                `cell: ${schemeCell.label} overrides=${!!overrides} agent=${!!agentOverride} system=${systemScheme} rm=${reducedMotion}`,
+              ).toEqual(reference);
+            }
+          }
+        }
+      }
+    }
+  });
+
+  it('matches when the render path supplies explicit inputs (React binding path)', () => {
+    setThemeSystemAppearance('light');
+    setThemeReducedMotion(false);
+
+    const resolved = resolveThemeForConfig(
+      { theme: 'system' },
+      { systemAppearance: 'dark', reducedMotion: true },
+    );
+    const reference = referenceResolve({ theme: 'system' }, 'dark', true, null);
+    expect(resolved).toEqual(reference);
+  });
+});
+
+describe('definition dials (LLP 0269)', () => {
+  it('a density dial edit on the definition flows into the resolved theme', () => {
+    const before = resolveThemeForConfig({ theme: 'light' });
+    expect(before.density.mode).toBe('default');
+
+    setThemeDefinitionOverrides({ density: 'comfortable' });
+    const after = resolveThemeForConfig({ theme: 'light' });
+    expect(after.density.mode).toBe('comfortable');
+    expect(after.density.controlHeight.md).toBeGreaterThan(before.density.controlHeight.md);
+  });
+
+  it('an accent dial edit regenerates the accent family', () => {
+    setThemeDefinitionOverrides({ accent: '#1d9bf0' });
+    const resolved = resolveThemeForConfig({ theme: 'light' });
+    expect(resolved.color.accent.fill).toBe('#1d9bf0');
+    // Hover/pressed are generated from the dial, not left at the indigo default.
+    expect(resolved.color.accent.hover).not.toBe(darkTheme.color.accent.hover);
+  });
+});
+
+describe('agent snapshot golden shape (LLP 0157 §2, F0 checklist item 3)', () => {
+  it('publishes the default scope snapshot in the stable 7-token shape', () => {
+    const scope = registerThemeScope({ theme: 'dark' });
+    const snapshot = getThemeSnapshot();
+
+    expect(snapshot).not.toBeNull();
+    expect(Object.keys(snapshot!).sort()).toEqual(
+      ['scheme', 'themeName', 'tokens', 'updatedAt'].sort(),
+    );
+    expect(Object.keys(snapshot!.tokens).sort()).toEqual(
+      ['accent', 'background', 'border', 'muted', 'surface', 'surfaceAlt', 'text'].sort(),
+    );
+    expect(snapshot!.scheme).toBe('dark');
+    expect(snapshot!.themeName).toBe('facet');
+    expect(snapshot!.tokens.background).toBe(darkTheme.color.background.body);
+    expect(snapshot!.tokens.accent).toBe(darkTheme.color.accent.fill);
+    expect(typeof snapshot!.updatedAt).toBe('number');
+    scope.dispose();
+  });
+
+  it('routes POST /agent/theme/override writes into resolution and the snapshot', () => {
+    const scope = registerThemeScope({ theme: 'light' });
+    // Same write the agent endpoint handler performs.
+    setThemeOverride({ color: { accent: { fill: '#ff0000' } } });
+
+    expect(getThemeOverride()).toEqual({ color: { accent: { fill: '#ff0000' } } });
+    expect(scope.getTheme().color.accent.fill).toBe('#ff0000');
+    // Agent override outranks scope overrides (highest precedence).
+    scope.update({ theme: 'light', overrides: { color: { accent: { fill: '#00ff00' } } } });
+    expect(scope.getTheme().color.accent.fill).toBe('#ff0000');
+
+    const snapshot = getThemeSnapshot();
+    expect(snapshot!.tokens.accent).toBe('#ff0000');
+    scope.dispose();
+  });
+
+  it('notifies scope subscribers when the agent override changes', () => {
+    const scope = registerThemeScope({});
+    let notified = 0;
+    const unsubscribe = scope.subscribe(() => {
+      notified += 1;
+    });
+    setThemeOverride({ color: { accent: { fill: '#abcdef' } } });
+    expect(notified).toBeGreaterThan(0);
+    unsubscribe();
+    scope.dispose();
+  });
+
+  it('designates the newest live scope as default and hands back on dispose', () => {
+    const first = registerThemeScope({ theme: 'light' });
+    expect(first.isDefault()).toBe(true);
+    expect(getThemeSnapshot()!.scheme).toBe('light');
+
+    const second = registerThemeScope({ theme: 'dark' });
+    expect(second.isDefault()).toBe(true);
+    expect(first.isDefault()).toBe(false);
+    expect(getThemeSnapshot()!.scheme).toBe('dark');
+
+    // A non-default scope's update must not steal the snapshot.
+    first.update({ theme: 'light' });
+    expect(getThemeSnapshot()!.scheme).toBe('dark');
+
+    second.dispose();
+    expect(first.isDefault()).toBe(true);
+    expect(getThemeSnapshot()!.scheme).toBe('light');
+    first.dispose();
+  });
+});
+
+describe('scope-config reactivity', () => {
+  it('resolves system scheme through the host-fed input', () => {
+    const scope = registerThemeScope({ theme: 'system' });
+    setThemeSystemAppearance('dark');
+    expect(scope.getTheme().scheme).toBe('dark');
+    setThemeSystemAppearance('light');
+    expect(scope.getTheme().scheme).toBe('light');
+    scope.dispose();
+  });
+
+  it('applies reduced motion at resolution time', () => {
+    const scope = registerThemeScope({ theme: 'light' });
+    setThemeReducedMotion(true);
+    const theme = scope.getTheme();
+    expect(theme.motion.reducedMotion).toBe(true);
+    expect(theme.motion.preset.controlPress.transform).toBeUndefined();
+    scope.dispose();
+  });
+});

package/src/facet-catalog.ts

@@ -0,0 +1,75 @@
+import facetRegistryManifest from '../facet-registry.json';
+
+export interface FacetCatalogVariantDefinition {
+  name: string;
+  values: string[];
+}
+
+/**
+ * Per-framework source locations for a catalog entry (LLP 0157 §7).
+ * `sourceFilePath` remains the React-default legacy field; the
+ * `facet-catalog-schema` check enforces that the two never disagree.
+ */
+export interface FacetCatalogSources {
+  react: string;
+  contract?: string;
+}
+
+export interface FacetCatalogEntry {
+  name: string;
+  aliases?: string[];
+  category: string;
+  description: string;
+  tier: string;
+  status: string;
+  sourceFilePath: string;
+  sources?: FacetCatalogSources;
+  variants?: FacetCatalogVariantDefinition[];
+  dependencies?: string[];
+  annotations?: Record<string, unknown>;
+}
+
+function cloneVariants(
+  variants: FacetCatalogEntry['variants'],
+): FacetCatalogEntry['variants'] {
+  return variants?.map((variant) => ({
+    ...variant,
+    values: variant.values.slice(),
+  }));
+}
+
+function cloneEntry(entry: FacetCatalogEntry): FacetCatalogEntry {
+  return {
+    ...entry,
+    aliases: entry.aliases?.slice(),
+    dependencies: entry.dependencies?.slice(),
+    variants: cloneVariants(entry.variants),
+    sources: entry.sources ? { ...entry.sources } : undefined,
+    annotations: entry.annotations ? { ...entry.annotations } : undefined,
+  };
+}
+
+// Keep the runtime-facing catalog as a defensive clone of the manifest so the
+// experience registry and tests cannot accidentally mutate the canonical data
+// that the CLI also consumes.
+export const facetCatalog: FacetCatalogEntry[] = (
+  facetRegistryManifest as unknown as FacetCatalogEntry[]
+).map(cloneEntry);
+
+export type FacetFramework = 'react' | 'contract';
+
+/**
+ * Per-framework coverage status derived from the registry's `sources` field.
+ * Doubles as LLP 0156's conversion tracker for Facet-dependent surfaces.
+ */
+export function facetFrameworkCoverage(): Record<string, FacetFramework[]> {
+  const coverage: Record<string, FacetFramework[]> = {};
+  for (const entry of facetCatalog) {
+    const frameworks: FacetFramework[] = ['react'];
+    if (entry.sources?.contract) {
+      frameworks.push('contract');
+    }
+    coverage[entry.name] = frameworks;
+  }
+  return coverage;
+}