chaincss 1.12.14 → 1.13.0

package/README.md

@@ -144,4 +144,4 @@ just go to the docs section of [https://chaincss.dev](https://www.chaincss.dev)
 
 ## License
 
-MIT © [Rommel Caneos](https://github.com/melcanz08)
+MIT © [Rommel Caneos](https://github.com/melcanz08)

package/browser/react-hooks.js

@@ -1,4 +1,5 @@
-import React, { useMemo, useEffect, useRef, useState } from 'react';
+import React from 'react';
+const { useMemo, useEffect, useRef, useState } = React;
 import { $, compile, chain } from './rtt';
 
 const styleCache = new Map();
@@ -135,4 +136,27 @@ export function withChainStyles(styles, options = {}) {
 
 export function cx(...classes) {
   return classes.filter(Boolean).join(' ');
+}
+
+let debugEnabled = false;
+
+export function enableChainCSSDebug() {
+  if (typeof window !== 'undefined') {
+    debugEnabled = true;
+    window.__CHAINCSS_DEBUG__ = true;
+    console.log('🔍 ChainCSS Debug Mode Enabled');
+    console.log('💡 Tip: Hover over elements to see their atomic classes');
+  }
+}
+
+export function disableChainCSSDebug() {
+  if (typeof window !== 'undefined') {
+    debugEnabled = false;
+    window.__CHAINCSS_DEBUG__ = false;
+    console.log('🔍 ChainCSS Debug Mode Disabled');
+  }
+}
+
+export function isDebugEnabled() {
+  return debugEnabled || (typeof window !== 'undefined' && window.__CHAINCSS_DEBUG__);
 }

package/node/btt.js

@@ -353,6 +353,82 @@ function $(useTokens = true) {
         };
       }
 
+      // theme method
+      if (prop === 'theme') {
+        return function(themeTokens, callback) {
+          // Store original tokens to restore later
+          const originalTokens = tokens;
+          
+          // Create a temporary token store for this theme
+          const themeTokenStore = {
+            get: (path) => {
+              // Try to get from theme tokens first, fallback to original
+              const themeValue = themeTokens.get ? themeTokens.get(path) : null;
+              if (themeValue !== null && themeValue !== undefined) {
+                return themeValue;
+              }
+              return originalTokens.get(path);
+            },
+            // Make it look like the original tokens object
+            ...themeTokens
+          };
+          
+          // Create a proxy to intercept token resolution
+          const tokenProxy = new Proxy(themeTokenStore, {
+            get: (target, prop) => {
+              if (prop === 'get') {
+                return target.get.bind(target);
+              }
+              return target[prop];
+            }
+          });
+          
+          // Temporarily override the global tokens
+          const originalTokensRef = globalThis.__CHAINCSS_TOKENS__ || tokens;
+          const tempTokens = themeTokenStore;
+          
+          // Create a new $ function that uses the theme tokens
+          const themed$ = (useTokens = true) => {
+            // Store original resolver
+            const originalResolver = resolveToken;
+            
+            // Create temporary token resolver
+            const themeResolver = (value, useTokensFlag) => {
+              if (!useTokensFlag || typeof value !== 'string' || !value.startsWith('$')) {
+                return value;
+              }
+              const tokenPath = value.slice(1);
+              const tokenValue = tempTokens.get(tokenPath);
+              return tokenValue || value;
+            };
+            
+            // Temporarily replace resolveToken
+            globalThis.__CHAINCSS_TEMP_RESOLVER__ = themeResolver;
+            
+            const result = $(useTokens);
+            
+            // Restore original resolver
+            delete globalThis.__CHAINCSS_TEMP_RESOLVER__;
+            
+            return result;
+          };
+          
+          // Execute callback with themed chain
+          const result = callback(themed$);
+          
+          // Store theme data for CSS generation
+          if (!catcher.themes) catcher.themes = [];
+          catcher.themes.push({
+            name: `theme-${Date.now()}`,
+            styles: result,
+            tokens: themeTokens,
+            fallback: originalTokens
+          });
+          
+          return proxy;
+        };
+      }
+
       // Regular CSS properties
       const cssProperty = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
       if (validProperties && validProperties.length > 0 && !validProperties.includes(cssProperty)) {
@@ -657,6 +733,29 @@ const compile = (obj) => {
     if (!obj.hasOwnProperty(key)) continue;
     const element = obj[key];
 
+    // Handle themes
+    if (element.themes && Array.isArray(element.themes)) {
+      element.themes.forEach(theme => {
+        // Generate CSS for each theme variant
+        if (theme.styles && theme.styles.selectors) {
+          let themeCSS = '';
+          let themeSelectors = theme.styles.selectors || [];
+          
+          for (let prop in theme.styles) {
+            if (prop !== 'selectors' && theme.styles.hasOwnProperty(prop)) {
+              const kebabKey = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+              themeCSS += `  ${kebabKey}: ${theme.styles[prop]};\n`;
+            }
+          }
+          
+          if (themeCSS) {
+            cssString += `${themeSelectors.join(', ')} {\n${themeCSS}}\n`;
+          }
+        }
+      });
+      continue;
+    }
+
     if (element.atRules && Array.isArray(element.atRules)) {
       element.atRules.forEach(rule => { 
         cssString += processAtRule(rule, null); 
@@ -676,17 +775,9 @@ const compile = (obj) => {
           element[prop].forEach(rule => { 
             atRulesCSS += processAtRule(rule, element.selectors); 
           });
-        } else if (prop === 'nestedRules' && Array.isArray(element[prop])) {
-          element[prop].forEach(rule => {
-            let nestedBody = '';
-            for (let nestedProp in rule.styles) {
-              const kebabKey = nestedProp.replace(/([A-Z])/g, '-$1').toLowerCase();
-              nestedBody += `    ${kebabKey}: ${rule.styles[nestedProp]};\n`;
-            }
-            if (nestedBody) {
-              atRulesCSS += `${element.selectors.join(', ')} ${rule.selector} {\n${nestedBody}  }\n`;
-            }
-          });
+        } else if (prop === 'themes' && Array.isArray(element[prop])) {
+          // Process themes (already handled above)
+          continue;
         } else if (prop === 'hover' && typeof element[prop] === 'object') {
           let hoverBody = '';
           for (let hoverKey in element[prop]) {

package/node/chaincss.js

@@ -124,6 +124,8 @@ function parseArgs(args) {
       result.inputFile = arg;
     } else if (!result.outputFile) {
       result.outputFile = arg;
+    }else if (arg === '--validate-themes') {
+      result.validateThemes = true;
     }
   }
   return result;
@@ -148,6 +150,14 @@ const applyCliOptions = (cliOptions) => {
   if (cliOptions.atomic) {
     config.atomic.enabled = true;
   }
+  /*if (cliOptions.validateThemes) {
+    const configPath = path.join(process.cwd(), 'chaincss.config.cjs');
+    if (fs.existsSync(configPath)) {
+        await import('./theme-validator.js').then(module => {
+        module.validateThemeFiles(configPath);
+      });
+    }
+  }*/
 };
 
 function watch(inputFile, outputFile) {

package/node/plugins/next-plugin.js

@@ -1,10 +1,10 @@
-// node/plugins/next-plugin.js
 const path = require('path');
 
 module.exports = function withChainCSS(nextConfig = {}) {
   return {
     ...nextConfig,
     webpack(config, options) {
+      // Add loader for .jcss files (works in RSC)
       config.module.rules.push({
         test: /\.jcss$/,
         use: [
@@ -12,18 +12,109 @@ module.exports = function withChainCSS(nextConfig = {}) {
           {
             loader: path.resolve(__dirname, '../loaders/chaincss-loader.js'),
             options: {
-              mode: process.env.NODE_ENV === 'production' ? 'build' : 'runtime',
-              atomic: process.env.NODE_ENV === 'production'
+              mode: 'build',  // Build mode for RSC - extracts CSS
+              atomic: true
             }
           }
         ]
       });
 
+      // Enable CSS extraction for RSC
+      if (options.isServer) {
+        config.optimization = {
+          ...config.optimization,
+          splitChunks: {
+            cacheGroups: {
+              styles: {
+                name: 'styles',
+                type: 'css/mini-extract',
+                chunks: 'all',
+                enforce: true
+              }
+            }
+          }
+        };
+      }
+
+      if (typeof nextConfig.webpack === 'function') {
+        return nextConfig.webpack(config, options);
+      }
+      return config;
+    },
+    
+    // Enable CSS support in App Router
+    experimental: {
+      ...nextConfig.experimental,
+      turbo: {
+        ...nextConfig.experimental?.turbo,
+        rules: {
+          ...nextConfig.experimental?.turbo?.rules,
+          '*.jcss': {
+            loaders: ['chaincss/loader'],
+            as: '*.css'
+          }
+        }
+      }
+    }
+  };
+};
+const path = require('path');
+
+module.exports = function withChainCSS(nextConfig = {}) {
+  return {
+    ...nextConfig,
+    webpack(config, options) {
+      // Add loader for .jcss files (works in RSC)
+      config.module.rules.push({
+        test: /\.jcss$/,
+        use: [
+          options.defaultLoaders.babel,
+          {
+            loader: path.resolve(__dirname, '../loaders/chaincss-loader.js'),
+            options: {
+              mode: 'build',  // Build mode for RSC - extracts CSS
+              atomic: true
+            }
+          }
+        ]
+      });
+
+      // Enable CSS extraction for RSC
+      if (options.isServer) {
+        config.optimization = {
+          ...config.optimization,
+          splitChunks: {
+            cacheGroups: {
+              styles: {
+                name: 'styles',
+                type: 'css/mini-extract',
+                chunks: 'all',
+                enforce: true
+              }
+            }
+          }
+        };
+      }
+
       if (typeof nextConfig.webpack === 'function') {
         return nextConfig.webpack(config, options);
       }
       return config;
     },
-    pageExtensions: [...(nextConfig.pageExtensions || []), 'jcss']
+    
+    // Enable CSS support in App Router
+    experimental: {
+      ...nextConfig.experimental,
+      turbo: {
+        ...nextConfig.experimental?.turbo,
+        rules: {
+          ...nextConfig.experimental?.turbo?.rules,
+          '*.jcss': {
+            loaders: ['chaincss/loader'],
+            as: '*.css'
+          }
+        }
+      }
+    }
   };
 };

package/node/plugins/vite-plugin.js

@@ -1,4 +1,3 @@
-// node/plugins/vite-plugin.js
 import path from 'node:path';
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
@@ -25,10 +24,8 @@ const compiledCache = new Map();
 const compileScript = (scriptBlock, filename, get) => {
   const dirname = path.dirname(filename);
   
-  // Reset CSS output
   chain.cssOutput = '';
   
-  // Create a function from the script - no temp files!
   const fn = new Function(
     '$',
     'run',
@@ -40,7 +37,6 @@ const compileScript = (scriptBlock, filename, get) => {
     scriptBlock
   );
   
-  // Execute with helpers
   fn($, run, originalCompile, chain, get, filename, dirname);
   
   return chain.cssOutput || '';
@@ -52,10 +48,8 @@ const processJavascriptBlocks = (content, filename, get) => {
   
   for (let i = 0; i < blocks.length; i++) {
     if (i % 2 === 0) {
-      // Static content
       output += blocks[i];
     } else {
-      // JavaScript block
       const css = compileScript(blocks[i], filename, get);
       if (css && typeof css === 'string') {
         output += css;
@@ -69,10 +63,8 @@ const processJavascriptBlocks = (content, filename, get) => {
 const processJCSSFile = (filePath) => {
   const abs = path.resolve(filePath);
   
-  // Return cached result if available
   if (fileCache.has(abs)) return fileCache.get(abs);
   
-  // Check if file exists
   if (!fs.existsSync(abs)) {
     throw new Error(`ChainCSS: File not found: ${abs}`);
   }
@@ -80,26 +72,21 @@ const processJCSSFile = (filePath) => {
   const content = fs.readFileSync(abs, 'utf8');
   const dirname = path.dirname(abs);
   
-  // Create get function for this file
   const get = (relativePath) => {
     const targetPath = path.resolve(dirname, relativePath);
     return processJCSSFile(targetPath);
   };
   
-  // Process the file
   const result = processJavascriptBlocks(content, abs, get);
   
-  // Cache the result
   fileCache.set(abs, result);
   return result;
 };
 
-// Minify and prefix CSS
 const processCSS = async (css, filepath, options = {}) => {
   const { minify = true, prefix = true } = options;
   let processed = css;
   
-  // Add prefixing
   if (prefix && prefixer) {
     try {
       const result = await prefixer.process(css, { from: filepath });
@@ -109,7 +96,6 @@ const processCSS = async (css, filepath, options = {}) => {
     }
   }
   
-  // Minify
   if (minify) {
     const minified = new CleanCSS({ level: 2 }).minify(processed);
     if (minified.errors.length) {
@@ -121,45 +107,152 @@ const processCSS = async (css, filepath, options = {}) => {
   return processed;
 };
 
+// Helper to track used selectors for tree shaking
+const trackUsedSelectors = (bundle) => {
+  const usedSelectors = new Set();
+  if (!bundle) return usedSelectors;
+  
+  const classRegex = /class(?:Name)?=["']([^"']+)["']/g;
+  let match;
+  while ((match = classRegex.exec(bundle)) !== null) {
+    match[1].split(' ').forEach(cls => {
+      if (cls && cls !== '') {
+        usedSelectors.add(`.${cls}`);
+      }
+    });
+  }
+  return usedSelectors;
+};
+
+// Helper to filter unused CSS
+function filterUsedCSS(css, usedSelectors) {
+  const lines = css.split('\n');
+  const filteredLines = [];
+  let inRule = false;
+  
+  for (const line of lines) {
+    const selectorMatch = line.match(/^([^{]+){/);
+    if (selectorMatch) {
+      const selectors = selectorMatch[1].split(',').map(s => s.trim());
+      const isUsed = selectors.some(selector => {
+        const baseSelector = selector.split(':')[0];
+        return usedSelectors.has(baseSelector);
+      });
+      
+      if (isUsed) {
+        filteredLines.push(line);
+        inRule = true;
+      } else {
+        inRule = false;
+      }
+    } else if (inRule) {
+      filteredLines.push(line);
+      if (line.includes('}')) {
+        inRule = false;
+      }
+    } else if (!line.includes('}')) {
+      filteredLines.push(line);
+    }
+  }
+  
+  return filteredLines.join('\n');
+}
+
 export default function chaincssVite(opts = {}) {
   const {
     extension = '.jcss',
     minify = process.env.NODE_ENV === 'production',
     prefix = true,
-    hmr = true
+    hmr = true,
+    debug = process.env.NODE_ENV === 'development',
+    treeShake = process.env.NODE_ENV === 'production'
   } = opts;
   
+  let generatedCSS = '';
+  let generatedClassMap = {};
+  
   return {
     name: 'vite-plugin-chaincss',
     enforce: 'pre',
     
-    // Transform .jcss files
     async transform(code, id) {
       if (!id.endsWith(extension)) return null;
       
       try {
-        // Create get function for root file
         const dirname = path.dirname(id);
         const get = (relativePath) => {
           const targetPath = path.resolve(dirname, relativePath);
           return processJCSSFile(targetPath);
         };
         
-        // Process the file
         let css = processJavascriptBlocks(code, id, get);
         
-        // Process CSS (prefix + minify)
+        generatedCSS = css;
+        if (chain.classMap) {
+          generatedClassMap = chain.classMap;
+        }
+        
         css = await processCSS(css, id, { minify, prefix });
         
-        // In development, inject CSS for HMR
+        // Development with Debug Mode
+        if (process.env.NODE_ENV !== 'production' && debug) {
+          const classMapStr = JSON.stringify(generatedClassMap);
+          return {
+            code: `
+              // ChainCSS with Debug Mode
+              const id = ${JSON.stringify(id)};
+              const css = ${JSON.stringify(css)};
+              const classMap = ${classMapStr};
+              
+              let style = document.querySelector(\`style[data-chaincss="\${id}"]\`);
+              if (!style) {
+                style = document.createElement('style');
+                style.setAttribute('data-chaincss', id);
+                document.head.appendChild(style);
+              }
+              style.textContent = css;
+              
+              // Debug Mode: Add inspector attributes
+              if (typeof window !== 'undefined' && window.__CHAINCSS_DEBUG__ !== false) {
+                // Mark elements with their chaincss classes
+                const observer = new MutationObserver(() => {
+                  document.querySelectorAll('[class*="chain-"]').forEach(el => {
+                    const classes = Array.from(el.classList).filter(c => c.includes('chain-')).join(' ');
+                    if (classes && !el.hasAttribute('data-chaincss-class')) {
+                      el.setAttribute('data-chaincss-class', classes);
+                    }
+                  });
+                });
+                observer.observe(document.body, { childList: true, subtree: true });
+                
+                console.log('🔍 ChainCSS Debug Mode Active');
+                console.log('📊 Class Map:', classMap);
+              }
+              
+              if (import.meta.hot) {
+                import.meta.hot.accept((newModule) => {
+                  if (newModule?.default) {
+                    style.textContent = newModule.default;
+                  }
+                });
+                import.meta.hot.dispose(() => {
+                  style.remove();
+                });
+              }
+              
+              export default css;
+            `,
+            map: null
+          };
+        }
+        
+        // Development without Debug
         if (process.env.NODE_ENV !== 'production') {
           return {
             code: `
-              // ChainCSS HMR
               const id = ${JSON.stringify(id)};
               const css = ${JSON.stringify(css)};
               
-              // Add style to head
               let style = document.querySelector(\`style[data-chaincss="\${id}"]\`);
               if (!style) {
                 style = document.createElement('style');
@@ -168,14 +261,12 @@ export default function chaincssVite(opts = {}) {
               }
               style.textContent = css;
               
-              // HMR handling
               if (import.meta.hot) {
                 import.meta.hot.accept((newModule) => {
                   if (newModule?.default) {
                     style.textContent = newModule.default;
                   }
                 });
-                
                 import.meta.hot.dispose(() => {
                   style.remove();
                 });
@@ -187,7 +278,7 @@ export default function chaincssVite(opts = {}) {
           };
         }
         
-        // Production: just export CSS
+        // Production with Tree Shaking tracking
         return {
           code: `export default ${JSON.stringify(css)};`,
           map: null
@@ -199,12 +290,89 @@ export default function chaincssVite(opts = {}) {
       }
     },
     
-    // Handle HMR updates
+    // Add debug styles to HTML
+    transformIndexHtml(html) {
+      if (debug && process.env.NODE_ENV !== 'production') {
+        return {
+          html,
+          tags: [
+            {
+              tag: 'script',
+              injectTo: 'head',
+              children: `
+                window.__CHAINCSS_DEBUG__ = true;
+                console.log('🔍 ChainCSS Debug Mode: Hover over elements to see their atomic classes');
+              `
+            },
+            {
+              tag: 'style',
+              injectTo: 'head',
+              children: `
+                [data-chaincss-class]:hover::after {
+                  content: attr(data-chaincss-class);
+                  position: absolute;
+                  background: #667eea;
+                  color: white;
+                  padding: 2px 8px;
+                  font-size: 11px;
+                  border-radius: 4px;
+                  font-family: monospace;
+                  z-index: 9999;
+                  pointer-events: none;
+                  white-space: nowrap;
+                  box-shadow: 0 2px 4px rgba(0,0,0,0.2);
+                }
+              `
+            }
+          ]
+        };
+      }
+      return html;
+    },
+    
+    // Tree Shaking: Remove unused CSS
+    generateBundle(options, bundle) {
+      if (!treeShake) return;
+      
+      const jsBundle = Object.values(bundle).find(
+        file => file.type === 'chunk' && file.isEntry
+      );
+      
+      if (!jsBundle) return;
+      
+      const usedSelectors = trackUsedSelectors(jsBundle.code);
+      
+      const totalSelectors = Object.keys(generatedClassMap).length;
+      const usedCount = usedSelectors.size;
+      const deadCount = totalSelectors - usedCount;
+      const savings = totalSelectors > 0 ? (deadCount / totalSelectors * 100).toFixed(1) : 0;
+      
+      if (deadCount > 0) {
+        console.log(`\n ChainCSS Tree Shaking Results:`);
+        console.log(`Total styles: ${totalSelectors}`);
+        console.log(`Used styles: ${usedCount}`);
+        console.log(`Dead code eliminated: ${deadCount} (${savings}% savings)`);
+      }
+      
+      const cssFile = Object.values(bundle).find(
+        file => file.type === 'asset' && file.fileName.endsWith('.css')
+      );
+      
+      if (cssFile && typeof cssFile.source === 'string') {
+        const originalCSS = cssFile.source;
+        const filteredCSS = filterUsedCSS(originalCSS, usedSelectors);
+        
+        if (filteredCSS.length < originalCSS.length) {
+          cssFile.source = filteredCSS;
+          const cssSavings = ((originalCSS.length - filteredCSS.length) / originalCSS.length * 100).toFixed(1);
+          console.log(`   🎨 CSS size reduced by ${cssSavings}%`);
+        }
+      }
+    },
+    
     handleHotUpdate({ file, server }) {
       if (file.endsWith(extension)) {
-        // Invalidate cache for changed file
         fileCache.delete(file);
-        // Trigger reload
         server.ws.send({
           type: 'full-reload',
           path: '*'

package/node/theme-validator.js

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import path from 'path';
+
+export function validateThemeFiles(configPath) {
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  
+  if (!config.themes) return;
+  
+  const { contract, themes } = config;
+  
+  console.log('\n🎨 Validating Theme Contract...\n');
+  
+  const errors = [];
+  
+  themes.forEach((theme, index) => {
+    const themeName = theme.name || `theme-${index}`;
+    try {
+      validateTheme(contract, theme.values);
+      console.log(`✅ ${themeName}: Valid`);
+    } catch (err) {
+      errors.push(`❌ ${themeName}: ${err.message}`);
+    }
+  });
+  
+  if (errors.length > 0) {
+    console.error('\nTheme Contract Validation Failed:\n');
+    errors.forEach(err => console.error(err));
+    process.exit(1);
+  }
+  
+  console.log('\n✅ All themes valid!\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chaincss",
-  "version": "1.12.14",
+  "version": "1.13.0",
   "description": "Chainable CSS-in-JS with build-time compilation, atomic CSS, and zero-runtime options",
   "keywords": [
     "css",

package/shared/theme-contract.js

@@ -0,0 +1,98 @@
+export function createThemeContract(contractShape) {
+  // Store the contract for validation
+  const contract = contractShape;
+  
+  // Create a proxy that validates token access
+  const contractProxy = new Proxy(contract, {
+    get(target, prop) {
+      if (prop === '__isContract') return true;
+      if (prop === '__validate') return (theme) => validateTheme(contract, theme);
+      return target[prop];
+    }
+  });
+  
+  return contractProxy;
+}
+
+export function validateTheme(contract, theme, path = '') {
+  const errors = [];
+  
+  function validate(contractPart, themePart, currentPath) {
+    if (typeof contractPart === 'object' && contractPart !== null) {
+      // Check if theme has all required keys
+      const requiredKeys = Object.keys(contractPart);
+      const themeKeys = Object.keys(themePart || {});
+      
+      requiredKeys.forEach(key => {
+        const newPath = currentPath ? `${currentPath}.${key}` : key;
+        
+        if (!themePart || !themePart.hasOwnProperty(key)) {
+          errors.push(` Missing required token: "${newPath}"`);
+        } else {
+          validate(contractPart[key], themePart[key], newPath);
+        }
+      });
+      
+      // Warn about extra keys (optional, could be allowed)
+      themeKeys.forEach(key => {
+        if (!contractPart.hasOwnProperty(key)) {
+          const newPath = currentPath ? `${currentPath}.${key}` : key;
+          console.warn(` Extra token not in contract: "${newPath}"`);
+        }
+      });
+    } else {
+      // Leaf node - just check type (optional)
+      if (typeof themePart !== 'string') {
+        errors.push(` Token "${currentPath}" must be a string, got ${typeof themePart}`);
+      }
+    }
+  }
+  
+  validate(contract, theme, path);
+  
+  if (errors.length > 0) {
+    throw new Error(`Theme Contract Validation Failed:\n${errors.join('\n')}`);
+  }
+  
+  return true;
+}
+
+export function createTheme(contract, themeValues) {
+  // Validate at creation time
+  if (contract.__isContract) {
+    contract.__validate(themeValues);
+  } else {
+    validateTheme(contract, themeValues);
+  }
+  
+  // Create the actual theme tokens
+  const tokens = {};
+  
+  function buildTokens(contractPart, themePart, target, path = '') {
+    Object.keys(contractPart).forEach(key => {
+      const newPath = path ? `${path}.${key}` : key;
+      
+      if (typeof contractPart[key] === 'object' && contractPart[key] !== null) {
+        target[key] = {};
+        buildTokens(contractPart[key], themePart[key] || {}, target[key], newPath);
+      } else {
+        target[key] = themePart[key];
+      }
+    });
+  }
+  
+  buildTokens(contract, themeValues, tokens);
+  
+  // Add getter method
+  tokens.get = (path) => {
+    const parts = path.split('.');
+    let current = tokens;
+    for (const part of parts) {
+      if (current === undefined) return undefined;
+      current = current[part];
+    }
+    return current;
+  };
+  
+  return tokens;
+}

package/shared/tokens.mjs

@@ -1,5 +1,15 @@
+// shared/tokens.mjs
+
 class DesignTokens {
-  constructor(tokens = {}) {
+  constructor(tokens = {}, contract = null) {
+    // Store contract for validation
+    this.contract = contract;
+    
+    // Validate against contract if provided
+    if (contract) {
+      this.validateContract(tokens, contract);
+    }
+    
     this.tokens = this.deepFreeze({
       colors: {},
       spacing: {},
@@ -14,6 +24,48 @@ class DesignTokens {
     this.flattened = this.flattenTokens(this.tokens);
   }
 
+  // Validate token structure against contract
+  validateContract(tokens, contract, path = '') {
+    const errors = [];
+    
+    const validate = (contractPart, tokenPart, currentPath) => {
+      if (typeof contractPart === 'object' && contractPart !== null) {
+        const requiredKeys = Object.keys(contractPart);
+        const tokenKeys = Object.keys(tokenPart || {});
+        
+        requiredKeys.forEach(key => {
+          const newPath = currentPath ? `${currentPath}.${key}` : key;
+          
+          if (!tokenPart || !tokenPart.hasOwnProperty(key)) {
+            errors.push(`❌ Missing required token: "${newPath}"`);
+          } else {
+            validate(contractPart[key], tokenPart[key], newPath);
+          }
+        });
+        
+        // Warn about extra keys
+        tokenKeys.forEach(key => {
+          if (!contractPart.hasOwnProperty(key)) {
+            const newPath = currentPath ? `${currentPath}.${key}` : key;
+            console.warn(`⚠️ Extra token not in contract: "${newPath}"`);
+          }
+        });
+      } else {
+        if (typeof tokenPart !== 'string') {
+          errors.push(`❌ Token "${currentPath}" must be a string, got ${typeof tokenPart}`);
+        }
+      }
+    };
+    
+    validate(contract, tokens, path);
+    
+    if (errors.length > 0) {
+      throw new Error(`Theme Contract Validation Failed:\n${errors.join('\n')}`);
+    }
+    
+    return true;
+  }
+
   // Deep freeze to prevent accidental modifications
   deepFreeze(obj) {
     Object.keys(obj).forEach(key => {
@@ -57,7 +109,7 @@ class DesignTokens {
     return css;
   }
 
-  // Create a theme variant
+  // Create a theme variant with contract validation
   createTheme(name, overrides) {
     const themeTokens = { ...this.flattened };
     
@@ -67,7 +119,13 @@ class DesignTokens {
       }
     });
     
-    return new DesignTokens(this.expandTokens(themeTokens));
+    // Validate theme against original contract if exists
+    if (this.contract) {
+      const expandedTokens = this.expandTokens(themeTokens);
+      this.validateContract(expandedTokens, this.contract);
+    }
+    
+    return new DesignTokens(this.expandTokens(themeTokens), this.contract);
   }
 
   // Expand flattened tokens back to nested structure
@@ -234,8 +292,13 @@ const defaultTokens = {
 const tokens = new DesignTokens(defaultTokens);
 
 // Token utility functions
-const createTokens = (customTokens) => {
-  return new DesignTokens(customTokens);
+const createTokens = (customTokens, contract = null) => {
+  return new DesignTokens(customTokens, contract);
+};
+
+// Define a theme contract
+const defineThemeContract = (contract) => {
+  return contract;
 };
 
 // Generate responsive values
@@ -251,6 +314,7 @@ const responsive = (values) => {
 export {
   tokens,
   createTokens,
+  defineThemeContract,
   responsive,
   DesignTokens
 };

package/types.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="react" />
 
-declare module '@melcanz85/chaincss' {
+declare module 'chaincss' {
   // ============================================================================
   // Core Types
   // ============================================================================
@@ -33,6 +33,12 @@ declare module '@melcanz85/chaincss' {
     
     // Selector shortcut
     $(selector: string): ChainBuilder;
+
+    // Theme method
+    theme<T extends Record<string, any>>(
+      tokens: T,
+      callback: (chain: ChainBuilder) => void
+    ): ChainBuilder;
   }
   
   export interface KeyframeBuilder {
@@ -123,6 +129,10 @@ declare module '@melcanz85/chaincss' {
   ): (Component: React.ComponentType<P>) => React.FC<P & { chainStyles?: Record<string, string> }>;
   
   export function cx(...classes: (string | undefined | null | false)[]): string;
+
+  export function enableChainCSSDebug(): void;
+  export function disableChainCSSDebug(): void;
+  export function isDebugEnabled(): boolean;
   
   // ============================================================================
   // Configuration
@@ -179,6 +189,8 @@ declare module '@melcanz85/chaincss' {
     minify?: boolean;
     prefix?: boolean;
     hmr?: boolean;
+    debug?: boolean;  
+    treeShake?: boolean; 
   }
   
   export function vitePlugin(options?: VitePluginOptions): any;
@@ -188,9 +200,9 @@ declare module '@melcanz85/chaincss' {
 // Vite Plugin Subpath Export
 // ============================================================================
 
-declare module '@melcanz85/chaincss/vite-plugin' {
+declare module 'chaincss/vite-plugin' {
   import { Plugin } from 'vite';
-  import { VitePluginOptions } from '@melcanz85/chaincss';
+  import { VitePluginOptions } from 'chaincss';
   
   export default function chaincssVite(options?: VitePluginOptions): Plugin;
 }
@@ -199,16 +211,16 @@ declare module '@melcanz85/chaincss/vite-plugin' {
 // React Subpath Export
 // ============================================================================
 
-declare module '@melcanz85/chaincss/react' {
-  export * from '@melcanz85/chaincss';
+declare module 'chaincss/react' {
+  export * from 'chaincss';
   
   // Re-export React-specific hooks
-  export const useChainStyles: typeof import('@melcanz85/chaincss').useChainStyles;
-  export const useDynamicChainStyles: typeof import('@melcanz85/chaincss').useDynamicChainStyles;
-  export const useThemeChainStyles: typeof import('@melcanz85/chaincss').useThemeChainStyles;
-  export const ChainCSSGlobal: typeof import('@melcanz85/chaincss').ChainCSSGlobal;
-  export const withChainStyles: typeof import('@melcanz85/chaincss').withChainStyles;
-  export const cx: typeof import('@melcanz85/chaincss').cx;
+  export const useChainStyles: typeof import('chaincss').useChainStyles;
+  export const useDynamicChainStyles: typeof import('chaincss').useDynamicChainStyles;
+  export const useThemeChainStyles: typeof import('chaincss').useThemeChainStyles;
+  export const ChainCSSGlobal: typeof import('chaincss').ChainCSSGlobal;
+  export const withChainStyles: typeof import('chaincss').withChainStyles;
+  export const cx: typeof import('chaincss').cx;
 }
 
 // ============================================================================
@@ -236,4 +248,30 @@ export type Recipe<TVariants extends Record<string, Record<string, any>>> = {
 
 export function recipe<TVariants extends Record<string, Record<string, any>>>(
   options: RecipeOptions<TVariants>
-): Recipe<TVariants>;
+): Recipe<TVariants>;
+
+//================
+// THEME CONTRACT
+//================
+export interface ThemeContract {
+  [key: string]: string | Record<string, any>;
+}
+
+export function defineThemeContract<T extends ThemeContract>(
+  contract: T
+): T & { __isContract: true; __validate: (theme: any) => void };
+
+export function createTheme<T extends Record<string, any>>(
+  contract: T,
+  values: T
+): DesignTokens;
+
+export function createTokens(
+  customTokens: Partial<Tokens>,
+  contract?: ThemeContract
+): DesignTokens;
+
+export function validateTheme(
+  contract: ThemeContract,
+  theme: any
+): boolean;