@3fn/core 14.1.0 → 15.0.0

package/src/generators/generateTokenFiles.ts

@@ -1,337 +0,0 @@
-/**
- * Generate Token Files Script
- * 
- * Generates platform-specific token constant files and writes them to the output directory.
- * Run this script to create DesignTokens.web.css, DesignTokens.ios.swift, and DesignTokens.android.kt
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { TokenFileGenerator } from './TokenFileGenerator';
-import { SemanticTokenValidator } from '../validators/SemanticTokenValidator';
-import { PrimitiveTokenRegistry } from '../registries/PrimitiveTokenRegistry';
-import { SemanticTokenRegistry } from '../registries/SemanticTokenRegistry';
-import { SemanticOverrideResolver } from '../resolvers/SemanticOverrideResolver';
-import { resolveSemanticTokenValue } from '../resolvers/SemanticValueResolver';
-import { ThemeRegistry } from '../themes/ThemeRegistry';
-// Theme overrides remain as static imports — they resolve from the config's themes array,
-// independent of tokenSource. These are the base system's built-in themes shipped with @3fn/core.
-import { darkSemanticOverrides } from '../tokens/themes/dark/SemanticOverrides';
-import { wcagSemanticOverrides } from '../tokens/themes/wcag/SemanticOverrides';
-import { darkWcagSemanticOverrides } from '../tokens/themes/dark-wcag/SemanticOverrides';
-import { composedColorMap } from '../tokens/color';
-import { getOklchMetadata } from './oklch/OklchTokenIndexMetadata';
-import type { ModeResolvedTokens } from './ModeResolvedTokens';
-import type { ResolvedConfig } from '../config/ConfigLoader';
-import type { TokenInput } from '../cli/resolveTokens';
-
-/**
- * Empty mode-resolved result returned on early-abort paths (validation failures).
- * Callers that wire the index will receive empty data and skip index population rather
- * than re-deriving stale values.
- */
-const EMPTY_MODE_RESOLVED: ModeResolvedTokens = {
-  resolvedLight: [],
-  resolvedDark: [],
-  themeVaryingTokens: new Set<string>(),
-  primitiveOklch: new Map(),
-};
-
-/**
- * Main generation function.
- *
- * Performs the single shared mode resolution (Spec 117 Task 3) and returns it as
- * {@link ModeResolvedTokens} so the token index consumes the SAME resolved truth dist
- * writes — eliminating the prior three-way drift between dist, the index's primitive
- * values, and a separate theme-varying computation.
- *
- * @param tokens - Resolved token arrays (primitive and semantic) from the configured source.
- * @param config - Resolved config from ConfigLoader.
- * @returns The mode-resolved truth (resolved light/dark sets, base-scoped theme-varying
- *   set, per-primitive OKLCH). On validation-abort paths, an empty result.
- */
-export function generateTokenFiles(tokens: TokenInput, config: ResolvedConfig): ModeResolvedTokens {
-  const effectiveOutputDir = config.outputDir;
-  console.log('🚀 Starting token file generation...\n');
-
-  // Create output directory if it doesn't exist
-  if (!fs.existsSync(effectiveOutputDir)) {
-    fs.mkdirSync(effectiveOutputDir, { recursive: true });
-    console.log(`📁 Created output directory: ${effectiveOutputDir}\n`);
-  }
-
-  // Validate semantic token references before generation
-  console.log('🔍 Validating semantic token references...\n');
-  
-  const primitiveRegistry = new PrimitiveTokenRegistry();
-  const semanticRegistry = new SemanticTokenRegistry(primitiveRegistry);
-  const validator = new SemanticTokenValidator(primitiveRegistry, semanticRegistry);
-  
-  const primitiveTokens = tokens.primitiveTokens;
-  const semanticTokens = tokens.semanticTokens;
-
-  // Register semantic tokens so override resolver can validate against them
-  for (const token of semanticTokens) {
-    semanticRegistry.register(token);
-  }
-  
-  const validationResult = validator.validateSemanticReferences(semanticTokens, primitiveTokens);
-  
-  if (validationResult.level === 'Error') {
-    console.error('❌ Semantic token validation failed:\n');
-    console.error(`   ${validationResult.message}`);
-    console.error(`   ${validationResult.rationale}\n`);
-    
-    if (validationResult.suggestions) {
-      console.error('💡 Suggestions:');
-      validationResult.suggestions.forEach(suggestion => {
-        console.error(`   - ${suggestion}`);
-      });
-      console.error('');
-    }
-    
-    console.error('⚠️  Token generation aborted due to validation errors.\n');
-    return EMPTY_MODE_RESOLVED;
-  }
-  
-  if (validationResult.level === 'Warning') {
-    console.warn('⚠️  Semantic token validation passed with warnings:\n');
-    console.warn(`   ${validationResult.message}`);
-    console.warn(`   ${validationResult.rationale}\n`);
-  } else {
-    console.log('✅ Semantic token validation passed\n');
-  }
-
-  // Initialize generator
-  const generator = new TokenFileGenerator();
-
-  // Mode + theme resolution via ThemeRegistry (Spec 094)
-  const themeRegistry = new ThemeRegistry();
-  themeRegistry.setSemanticValidator((name) => semanticRegistry.has(name));
-
-  // Register existing themes with pre-composed override maps matching legacy behavior.
-  // 'wcag' mode 'both': light-wcag uses wcag overrides, dark-wcag uses merged dark+wcag+dark-wcag.
-  // To produce identical output, we register two themes:
-  //   - 'dark' (mode 'dark'): dark overrides only → produces dark-base context
-  //   - 'wcag' (mode 'both'): light gets wcag overrides, dark gets merged overrides
-  // The base light context has no overrides (handled by resolveForRegistry's baseline).
-
-  // For the WCAG theme, we need different overrides per mode.
-  // The registry stores one override map per theme. To match legacy behavior where
-  // dark-wcag = dark + wcag + dark-wcag merged, we register the WCAG theme with
-  // the light-wcag overrides and handle the dark-wcag composition in the resolver.
-  // BUT — for migration safety, we use the legacy resolveAllContexts path and
-  // convert its output to ResolvedThemeSet format. This guarantees identical output.
-
-  const overrideResolver = new SemanticOverrideResolver(semanticRegistry, darkSemanticOverrides);
-  const overrideValidation = overrideResolver.validate();
-  if (!overrideValidation.valid) {
-    console.error('❌ Semantic override validation failed:\n');
-    overrideValidation.errors.forEach(err => console.error(`   ${err}`));
-    console.error('\n⚠️  Token generation aborted due to override validation errors.\n');
-    return EMPTY_MODE_RESOLVED;
-  }
-
-  // Register themes in the registry for downstream consumers (getThemeVaryingTokens, etc.)
-  themeRegistry.register({
-    name: 'dark',
-    mode: 'dark',
-    overrides: darkSemanticOverrides,
-  });
-  themeRegistry.register({
-    name: 'wcag',
-    mode: 'both',
-    overrides: { ...wcagSemanticOverrides, ...darkWcagSemanticOverrides },
-  });
-
-  // Use legacy resolution path to guarantee identical output during migration.
-  // The registry is populated for getThemeVaryingTokens() and future consumers,
-  // but generation still uses the proven ContextOverrideSet path.
-  const contextOverrides = {
-    'light-wcag': wcagSemanticOverrides,
-    'dark-base': darkSemanticOverrides,
-    'dark-wcag': { ...darkSemanticOverrides, ...wcagSemanticOverrides, ...darkWcagSemanticOverrides },
-  } as import('../tokens/themes/types').ContextOverrideSet;
-
-  const contextValidation = overrideResolver.validateAll(contextOverrides);
-  if (!contextValidation.valid) {
-    console.error('❌ Context override validation failed:\n');
-    contextValidation.errors.forEach(err => console.error(`   ${err}`));
-    console.error('\n⚠️  Token generation aborted due to override validation errors.\n');
-    return EMPTY_MODE_RESOLVED;
-  }
-  console.log('✅ Semantic override validation passed\n');
-
-  const contextSets = overrideResolver.resolveAllContexts(semanticTokens, contextOverrides);
-
-  // Level 1: Resolve primitive references to concrete rgba values per context
-  const resolvedLight = contextSets['light-base'].map(t => resolveSemanticTokenValue(t, 'light', 'base'));
-  const resolvedDark = contextSets['dark-base'].map(t => resolveSemanticTokenValue(t, 'dark', 'base'));
-  const resolvedLightWcag = contextSets['light-wcag'].map(t => resolveSemanticTokenValue(t, 'light', 'wcag'));
-  const resolvedDarkWcag = contextSets['dark-wcag'].map(t => resolveSemanticTokenValue(t, 'dark', 'wcag'));
-
-  // Generate all platform files (passing resolved tokens for all 4 contexts)
-  const wcagOverrideKeys = new Set([
-    ...Object.keys(wcagSemanticOverrides),
-    ...Object.keys(darkWcagSemanticOverrides),
-  ]);
-
-  // Compute theme-varying tokens for the NON-WEB platform generators: registry overrides
-  // (unions ALL registered themes — dark AND wcag) ∪ base light/dark differences. This
-  // registry-wide Set (10 under the shipped config) is what the non-web generators consume.
-  const themeVaryingTokens = themeRegistry.getThemeVaryingTokens();
-  const darkMap = new Map(resolvedDark.map(t => [t.name, t]));
-  for (const lt of resolvedLight) {
-    if (lt.category !== 'color') continue;
-    const dt = darkMap.get(lt.name);
-    if (!dt) continue;
-    const lv = lt.primitiveReferences?.value ?? '';
-    const dv = dt.primitiveReferences?.value ?? '';
-    if (lv !== dv) themeVaryingTokens.add(lt.name);
-  }
-
-  // BASE-SCOPED theme-varying set for the INDEX (Spec 117 §4.1) — seeded EMPTY, populated
-  // ONLY from the base light-vs-dark resolved value diff. This is the SAME predicate the
-  // web base `:root` block uses to decide `light-dark()` emission, so the index's
-  // `themeVarying` flag binds to dist's base CSS by construction. It excludes WCAG-only
-  // override keys (which differ across the wcag THEME, not across base light/dark MODE) and
-  // is therefore DISTINCT from the registry-wide `themeVaryingTokens` above. Do NOT merge
-  // these two sets — that re-introduces the R5 over-marking (committed's stale 10).
-  const baseThemeVaryingTokens = new Set<string>();
-  for (const lt of resolvedLight) {
-    if (lt.category !== 'color') continue;
-    const dt = darkMap.get(lt.name);
-    if (!dt) continue;
-    const lv = lt.primitiveReferences?.value ?? '';
-    const dv = dt.primitiveReferences?.value ?? '';
-    if (lv !== dv) baseThemeVaryingTokens.add(lt.name);
-  }
-
-  // Per-primitive mode-resolved OKLCH for the index's R3 value readout. For OKLCH color
-  // primitives light === dark (the OKLCH model has no primitive-tier mode variance), so
-  // both halves carry the same metadata; the nested shape preserves the MCP value contract.
-  const primitiveOklch = new Map<string, import('./ModeResolvedTokens').PrimitiveOklchModes>();
-  for (const token of primitiveTokens) {
-    if (token.category !== 'color') continue;
-    const composed = composedColorMap.get(token.name);
-    if (!composed) continue;
-    const metadata = getOklchMetadata(composed);
-    primitiveOklch.set(token.name, { light: metadata, dark: metadata });
-  }
-
-  const results = generator.generateAll({
-    outputDir: effectiveOutputDir,
-    version: '1.0.0',
-    includeComments: true,
-    groupByCategory: true,
-    primitiveTokens,
-    semanticTokens: resolvedLight,
-    darkSemanticTokens: resolvedDark,
-    wcagSemanticTokens: resolvedLightWcag,
-    darkWcagSemanticTokens: resolvedDarkWcag,
-    wcagOverrideKeys,
-    themeVaryingTokens
-  });
-
-  // Write files to disk
-  console.log('📝 Writing token files...\n');
-  
-  for (const result of results) {
-    const filePath = path.join(result.filePath);
-    
-    try {
-      fs.writeFileSync(filePath, result.content, 'utf-8');
-      
-      if (result.valid) {
-        console.log(`✅ ${result.platform.toUpperCase()}: ${path.basename(filePath)}`);
-        console.log(`   Tokens: ${result.tokenCount}`);
-        console.log(`   Path: ${filePath}\n`);
-      } else {
-        console.log(`❌ ${result.platform.toUpperCase()}: ${path.basename(filePath)} - VALIDATION FAILED`);
-        console.log(`   Errors: ${result.errors?.join(', ')}\n`);
-      }
-    } catch (error) {
-      console.error(`❌ Failed to write ${result.platform} file:`, error);
-    }
-  }
-
-  // Validate cross-platform consistency
-  console.log('🔍 Validating cross-platform consistency...\n');
-  const validation = generator.validateCrossPlatformConsistency(results);
-
-  if (validation.consistent) {
-    console.log('✅ All platforms are mathematically consistent!\n');
-  } else {
-    console.log('⚠️  Cross-platform consistency issues detected:\n');
-    validation.issues.forEach(issue => {
-      console.log(`   - ${issue}`);
-    });
-    console.log('');
-  }
-
-  // Summary
-  console.log('📊 Generation Summary:');
-  console.log(`   Total platforms: ${results.length}`);
-  console.log(`   Successful: ${results.filter(r => r.valid).length}`);
-  console.log(`   Failed: ${results.filter(r => !r.valid).length}`);
-  console.log(`   Total tokens per platform: ${results[0]?.tokenCount || 0}`);
-
-  // --- Component Token Generation ---
-  const componentResults = generator.generateComponentTokens({
-    outputDir: effectiveOutputDir,
-    version: '1.0.0',
-    includeComments: true,
-  });
-
-  for (const result of componentResults) {
-    if (result.valid) {
-      fs.writeFileSync(result.filePath, result.content, 'utf-8');
-    }
-  }
-
-  const componentTokenCount = componentResults[0]?.tokenCount || 0;
-  if (componentTokenCount > 0) {
-    console.log(`   Component tokens: ${componentTokenCount} (${componentResults.filter(r => r.valid).length} platforms)`);
-  }
-
-  // --- DTCG Format Generation ---
-  try {
-    const { DTCGFormatGenerator } = require('./DTCGFormatGenerator');
-    const dtcgGenerator = new DTCGFormatGenerator();
-    const dtcgOutputPath = path.join(effectiveOutputDir, 'DesignTokens.dtcg.json');
-    dtcgGenerator.writeToFile(dtcgOutputPath);
-    console.log(`   DTCG: DesignTokens.dtcg.json`);
-  } catch (dtcgError) {
-    console.error('   ⚠️  DTCG generation failed (non-blocking):', dtcgError instanceof Error ? dtcgError.message : dtcgError);
-  }
-
-  // --- Figma Format Generation (depends on DTCG) ---
-  try {
-    const dtcgPath = path.join(effectiveOutputDir, 'DesignTokens.dtcg.json');
-    if (fs.existsSync(dtcgPath)) {
-      const { FigmaTransformer } = require('./transformers/FigmaTransformer');
-      const dtcgContent = JSON.parse(fs.readFileSync(dtcgPath, 'utf-8'));
-      const transformer = new FigmaTransformer();
-      if (transformer.canTransform(dtcgContent)) {
-        const result = transformer.transform(dtcgContent);
-        const figmaOutputPath = path.join(effectiveOutputDir, 'DesignTokens.figma.json');
-        fs.writeFileSync(figmaOutputPath, result.content, 'utf-8');
-        console.log(`   Figma: DesignTokens.figma.json`);
-      }
-    }
-  } catch (figmaError) {
-    console.error('   ⚠️  Figma generation failed (non-blocking):', figmaError instanceof Error ? figmaError.message : figmaError);
-  }
-
-  console.log('\n✨ Token file generation complete!');
-
-  // Return the single shared mode-resolved truth for the index. Note `themeVaryingTokens`
-  // here is the BASE-SCOPED set (distinct from the registry-wide `themeVaryingTokens` local
-  // passed to the non-web generators above) — see ModeResolvedTokens doc-comment.
-  return {
-    resolvedLight,
-    resolvedDark,
-    themeVaryingTokens: baseThemeVaryingTokens,
-    primitiveOklch,
-  };
-}

package/src/generators/generateTokenIndex.ts

@@ -1,258 +0,0 @@
-/**
- * Token Index Generator
- *
- * Produces three YAML files (primitives, semantics, components) for the
- * Application MCP's token query tools.
- *
- * @see Spec 096 design.md
- * @see Spec 114 — data flow restructure (barrel imports removed)
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import * as yaml from 'js-yaml';
-import { TokenCategory } from '../types/PrimitiveToken';
-import type { PrimitiveToken } from '../types/PrimitiveToken';
-import type { SemanticToken } from '../types/SemanticToken';
-import type { RegisteredComponentToken } from '../registries/ComponentTokenRegistry';
-import { WebFormatGenerator } from '../providers/WebFormatGenerator';
-import { iOSFormatGenerator } from '../providers/iOSFormatGenerator';
-import { AndroidFormatGenerator } from '../providers/AndroidFormatGenerator';
-import type { ModeResolvedTokens, PrimitiveOklchModes } from './ModeResolvedTokens';
-
-/**
- * Required input for token-index generation.
- * All data must be explicitly provided — no barrel import fallbacks.
- */
-export interface TokenIndexInput {
-  primitiveTokens: PrimitiveToken[];
-  semanticTokens: SemanticToken[];
-  componentTokens: RegisteredComponentToken[];
-  /**
-   * The single shared mode-resolved truth from `generateTokenFiles` (Spec 117 Task 3).
-   * Carries the base-scoped theme-varying set AND per-primitive mode-resolved OKLCH, so the
-   * index emits the SAME values dist wrote rather than re-deriving (and drifting).
-   */
-  modeResolved: ModeResolvedTokens;
-  /**
-   * Absolute path to the consumer's component-schema scan root — the directory whose
-   * `<Component>/*.schema.yaml` files seed the token→[components] consumer map
-   * (Spec 118 Task 9.5.2, Class C′; ratified default-only). This is resolved by the
-   * CALLER from the active config (default `<configDir>/src/components/core`) and passed
-   * in, so `generateTokenIndex` stays a pure function of its inputs — it no longer
-   * computes the scan root from `__dirname` (which hard-bound the scan to the PACKAGE's
-   * components, ignoring the schemas a consumer adds/edits in their own repo and the
-   * same source the application MCP already reads via `COMPONENTS_DIR`).
-   */
-  componentSchemaDir: string;
-}
-
-/** Build the mode-nested OKLCH value + sibling channel metadata for a color primitive. */
-function buildOklchEntry(modes: PrimitiveOklchModes): {
-  value: { light: { base: string; wcag: string }; dark: { base: string; wcag: string } };
-  oklch: Record<'light' | 'dark', { l: number; c: number; h: number; channels: { hue: string; lightness: string; chroma: string } }>;
-} {
-  // Match dist's exact OKLCH string format (WebFormatGenerator.formatOklchColor):
-  // `oklch(${l} ${c} ${h})`. No primitive-tier WCAG mechanism exists, so wcag === base.
-  const fmt = (m: PrimitiveOklchModes['light']) => `oklch(${m.oklch.l} ${m.oklch.c} ${m.oklch.h})`;
-  const lightStr = fmt(modes.light);
-  const darkStr = fmt(modes.dark);
-  return {
-    value: {
-      light: { base: lightStr, wcag: lightStr },
-      dark: { base: darkStr, wcag: darkStr },
-    },
-    oklch: {
-      light: { l: modes.light.oklch.l, c: modes.light.oklch.c, h: modes.light.oklch.h, channels: modes.light.channels },
-      dark: { l: modes.dark.oklch.l, c: modes.dark.oklch.c, h: modes.dark.oklch.h, channels: modes.dark.channels },
-    },
-  };
-}
-
-/** Build a map of token name → consuming component names from schema.yaml files. */
-function buildConsumerMap(componentsDir: string): Map<string, string[]> {
-  const map = new Map<string, string[]>();
-
-  if (!fs.existsSync(componentsDir)) return map;
-
-  for (const dir of fs.readdirSync(componentsDir, { withFileTypes: true })) {
-    if (!dir.isDirectory()) continue;
-    const schemaFiles = fs.readdirSync(path.join(componentsDir, dir.name))
-      .filter(f => f.endsWith('.schema.yaml'));
-
-    for (const schemaFile of schemaFiles) {
-      try {
-        const content = fs.readFileSync(path.join(componentsDir, dir.name, schemaFile), 'utf-8');
-        const schema = yaml.load(content) as any;
-        if (!schema?.tokens) continue;
-
-        const componentName = schema.name || dir.name;
-        // `tokens:` is a map of group-name → token refs. The canonical (Stemma) form
-        // is an ARRAY of refs per group (e.g. `inherited: [color.action.primary, ...]`);
-        // earlier scalar/object forms are tolerated for back-compat. Flatten both.
-        // (Spec 118 Task 9.5.2: prior reader treated each group value as a single ref,
-        // so array groups were silently skipped — the consumers map was dead, 0/193.)
-        for (const groupValue of Object.values(schema.tokens) as any[]) {
-          const refs = Array.isArray(groupValue) ? groupValue : [groupValue];
-          for (const tokenRef of refs) {
-            const tokenName = typeof tokenRef === 'string' ? tokenRef : tokenRef?.reference || tokenRef?.name;
-            if (tokenName) {
-              const consumers = map.get(tokenName) || [];
-              if (!consumers.includes(componentName)) consumers.push(componentName);
-              map.set(tokenName, consumers);
-            }
-          }
-        }
-      } catch {
-        // Skip unparseable schemas
-      }
-    }
-  }
-
-  return map;
-}
-
-/**
- * Generate the token index YAML files.
- *
- * @param tokenIndexDir - Absolute or relative (to cwd) path for output. Defaults to 'token-index'.
- * @param input - Required resolved token data from the CLI.
- */
-export function generateTokenIndex(tokenIndexDir: string = 'token-index', input: TokenIndexInput): void {
-  const outputDir = path.isAbsolute(tokenIndexDir)
-    ? tokenIndexDir
-    : path.resolve(process.cwd(), tokenIndexDir);
-
-  console.log('📊 Generating token index...\n');
-
-  const webGen = new WebFormatGenerator();
-  const iosGen = new iOSFormatGenerator();
-  const androidGen = new AndroidFormatGenerator('kotlin');
-
-  const themeVarying = input.modeResolved.themeVaryingTokens;
-  const primitiveOklch = input.modeResolved.primitiveOklch;
-  const primitives = input.primitiveTokens;
-  const semantics = input.semanticTokens;
-
-  // Build consumer map from the consumer's component schemas (Spec 118 Task 9.5.2,
-  // Class C′). The scan root is resolved by the caller from the active config and
-  // passed in via `input.componentSchemaDir` — NOT computed from `__dirname` here.
-  // This aligns the relationship map with the consumer's design system (the same
-  // source the application MCP reads via COMPONENTS_DIR), so a consumer's added/edited
-  // component appears in their generated index.
-  const consumerMap = buildConsumerMap(input.componentSchemaDir);
-
-  // Families that generate inside nested namespaces (enum/object) on iOS/Android.
-  const NESTED_PRIMITIVE_FAMILIES = new Set([
-    TokenCategory.DURATION, TokenCategory.EASING, TokenCategory.SCALE,
-  ]);
-
-  // Generate primitives index
-  const primitivesIndex: Record<string, any> = {};
-  for (const token of primitives) {
-    const isNested = NESTED_PRIMITIVE_FAMILIES.has(token.category as TokenCategory);
-    let iosPath = iosGen.getTokenName(token.name, token.category);
-    let androidPath = androidGen.getTokenName(token.name, token.category);
-
-    if (isNested) {
-      const namespace = token.category.charAt(0).toUpperCase() + token.category.slice(1);
-      iosPath = `${namespace}.${iosPath}`;
-      const androidProp = token.name
-        .split(/[.\-]/)
-        .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-        .join('');
-      androidPath = `${namespace}.${androidProp}`;
-    }
-
-    // R3: color primitives emit mode-resolved OKLCH (value + channels) from the shared
-    // source — never the collapsed rgba snapshot. Non-color primitives keep web.value.
-    const oklchModes = primitiveOklch.get(token.name);
-    const entry: Record<string, any> = {
-      family: token.category,
-      ...(oklchModes
-        ? buildOklchEntry(oklchModes)
-        : { value: token.platforms.web.value }),
-      formula: token.mathematicalRelationship || null,
-      platforms: {
-        web: webGen.getTokenName(token.name, token.category),
-        ios: iosPath,
-        android: androidPath,
-      },
-    };
-
-    primitivesIndex[token.name] = entry;
-  }
-
-  // Generate semantics index
-  const semanticsIndex: Record<string, any> = {};
-  for (const token of semantics) {
-    const isThemeVarying = themeVarying.has(token.name);
-    const iosName = iosGen.getTokenName(token.name, token.category);
-    const androidName = androidGen.getTokenName(token.name, token.category);
-
-    semanticsIndex[token.name] = {
-      category: token.category,
-      primitiveReferences: token.primitiveReferences || null,
-      themeVarying: isThemeVarying,
-      platforms: {
-        web: webGen.getTokenName(token.name, token.category),
-        ios: isThemeVarying ? `theme.${iosName}` : iosName,
-        android: isThemeVarying ? `theme.${androidName}` : androidName,
-      },
-      consumers: consumerMap.get(token.name) || [],
-    };
-  }
-
-  // Generate component tokens index
-  const componentTokensIndex: Record<string, any> = {};
-  const allComponentTokens = input.componentTokens;
-  for (const ct of allComponentTokens) {
-    const enumName = `${ct.component}Tokens`;
-    const parts = ct.name.split('.');
-    const propertyName = parts.slice(1).map((part, i) =>
-      i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)
-    ).join('');
-
-    componentTokensIndex[ct.name] = {
-      component: ct.component,
-      primitiveReferences: ct.primitiveReference ? { value: ct.primitiveReference } : { value: String(ct.value) },
-      platforms: {
-        web: webGen.getTokenName(ct.name, 'component'),
-        ios: `${enumName}.${propertyName}`,
-        android: `${enumName}.${propertyName}`,
-      },
-    };
-  }
-
-  // Write YAML files
-  if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
-  }
-
-  fs.writeFileSync(
-    path.join(outputDir, 'primitives.yaml'),
-    yaml.dump({ tokens: primitivesIndex }, { lineWidth: -1 }),
-    'utf-8'
-  );
-  fs.writeFileSync(
-    path.join(outputDir, 'semantics.yaml'),
-    yaml.dump({ tokens: semanticsIndex }, { lineWidth: -1 }),
-    'utf-8'
-  );
-  fs.writeFileSync(
-    path.join(outputDir, 'components.yaml'),
-    yaml.dump({ tokens: componentTokensIndex }, { lineWidth: -1 }),
-    'utf-8'
-  );
-
-  const counts = {
-    primitives: Object.keys(primitivesIndex).length,
-    semantics: Object.keys(semanticsIndex).length,
-    components: Object.keys(componentTokensIndex).length,
-  };
-
-  console.log(`✅ Token index generated at ${outputDir}`);
-  console.log(`   Primitives: ${counts.primitives}`);
-  console.log(`   Semantics: ${counts.semantics}`);
-  console.log(`   Component tokens: ${counts.components}\n`);
-}

package/src/generators/oklch/OklchExportUtils.ts

@@ -1,57 +0,0 @@
-/**
- * OKLCH Export Utilities — Converts OKLCH colors to sRGB hex for DTCG/Figma output.
- *
- * Uses CSS Color Level 4 §13.2 gamut mapping when values exceed sRGB.
- * Deterministic: same OKLCH input always produces same hex output.
- *
- * @see Spec 112 R5 AC1-5
- */
-
-import { toSrgbHex, isInSrgbGamut, clampToGamut, type Oklch } from '../../color/OklchConverter';
-
-export interface OklchExportResult {
-  hex: string;
-  gamutClamped: boolean;
-  original: Oklch;
-}
-
-/**
- * Convert OKLCH to sRGB hex for DTCG/Figma export.
- * Clamps out-of-gamut values using CSS L4 algorithm and flags them.
- */
-export function oklchToExportHex(l: number, c: number, h: number): OklchExportResult {
-  if (isInSrgbGamut(l, c, h)) {
-    return { hex: toSrgbHex(l, c, h), gamutClamped: false, original: { l, c, h } };
-  }
-
-  const clamped = clampToGamut(l, c, h);
-  return {
-    hex: toSrgbHex(clamped.l, clamped.c, clamped.h),
-    gamutClamped: true,
-    original: { l, c, h },
-  };
-}
-
-/**
- * Format a DTCG color token entry from OKLCH source.
- * Output: `{ "$value": "#ff2a6d", "$type": "color" }`
- */
-export function formatDtcgColorToken(name: string, l: number, c: number, h: number): {
-  $value: string;
-  $type: 'color';
-  $extensions?: { 'com.designerpunk': { oklch: Oklch; gamutClamped: boolean } };
-} {
-  const result = oklchToExportHex(l, c, h);
-  const entry: any = {
-    $value: result.hex,
-    $type: 'color' as const,
-  };
-  // Include OKLCH source in extensions for traceability
-  entry.$extensions = {
-    'com.designerpunk': {
-      oklch: result.original,
-      gamutClamped: result.gamutClamped,
-    },
-  };
-  return entry;
-}

package/src/generators/oklch/OklchTokenIndexMetadata.ts

@@ -1,30 +0,0 @@
-/**
- * OKLCH Token-Index Metadata — Enriches token-index color entries with OKLCH channels.
- *
- * Channel data is metadata on composed colors (not separate top-level entries).
- * Application MCP `get_token_details` returns these values alongside platform names.
- *
- * @see Spec 112 R9 AC1-4
- */
-
-import type { Oklch } from '../../color/OklchConverter';
-import type { ComposedColor } from '../../tokens/color/primitives/chromatic';
-
-export interface OklchTokenMetadata {
-  oklch: Oklch;
-  channels: {
-    hue: string;
-    lightness: string;
-    chroma: string;
-  };
-}
-
-/**
- * Generate OKLCH metadata for a composed color token's token-index entry.
- */
-export function getOklchMetadata(color: ComposedColor): OklchTokenMetadata {
-  return {
-    oklch: color.resolved,
-    channels: color.channels,
-  };
-}