tailwind-to-style 3.1.3 → 3.2.0

package/dist/index.esm.js

@@ -1,7 +1,6 @@
 /**
- * tailwind-to-style v3.1.3
+ * tailwind-to-style v3.2.0
  * Runtime Tailwind CSS to inline styles converter
- * Core only: tws, twsx, configure
  * 
  * @author Bigetion
  * @license MIT
@@ -1810,9 +1809,9 @@ try {
 }
 const logger = new Logger(logLevel);
 
-/**
- * User Configuration Management
- * Handles theme extensions and custom plugin registration
+/**
+ * User Configuration Management
+ * Handles theme extensions and custom plugin registration
  */
 
 
@@ -1824,8 +1823,8 @@ function setClearConfigCache(fn) {
   clearConfigCache$1 = fn;
 }
 
-/**
- * User configuration state
+/**
+ * User configuration state
  */
 let userConfig = {
   theme: {
@@ -1848,11 +1847,11 @@ let userConfig = {
 // Cache for extended theme to avoid redundant lookups
 const extendedThemeCache = new Map();
 
-/**
- * Deep merge two objects
- * @param {Object} target - Target object
- * @param {Object} source - Source object
- * @returns {Object} Merged object
+/**
+ * Deep merge two objects
+ * @param {Object} target - Target object
+ * @param {Object} source - Source object
+ * @returns {Object} Merged object
  */
 function deepMerge(target, source) {
   const result = {
@@ -1868,31 +1867,31 @@ function deepMerge(target, source) {
   return result;
 }
 
-/**
- * Configure tailwind-to-style with custom theme and plugins
- * @param {Object} config - Configuration object
- * @param {Object} [config.theme] - Theme configuration
- * @param {Object} [config.theme.extend] - Theme extensions
- * @param {Array} [config.plugins] - Array of plugins
- * @param {Object} [config.corePlugins] - Core plugins to enable/disable
- * @param {string} [config.prefix] - Prefix for all classes
- *
- * @example
- * configure({
- *   theme: {
- *     extend: {
- *       colors: {
- *         brand: {
- *           500: '#3B82F6',
- *         },
- *       },
- *       spacing: {
- *         128: '32rem',
- *       },
- *     },
- *   },
- *   plugins: [myCustomPlugin],
- * });
+/**
+ * Configure tailwind-to-style with custom theme and plugins
+ * @param {Object} config - Configuration object
+ * @param {Object} [config.theme] - Theme configuration
+ * @param {Object} [config.theme.extend] - Theme extensions
+ * @param {Array} [config.plugins] - Array of plugins
+ * @param {Object} [config.corePlugins] - Core plugins to enable/disable
+ * @param {string} [config.prefix] - Prefix for all classes
+ *
+ * @example
+ * configure({
+ *   theme: {
+ *     extend: {
+ *       colors: {
+ *         brand: {
+ *           500: '#3B82F6',
+ *         },
+ *       },
+ *       spacing: {
+ *         128: '32rem',
+ *       },
+ *     },
+ *   },
+ *   plugins: [myCustomPlugin],
+ * });
  */
 function configure() {
   let config = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -1903,6 +1902,32 @@ function configure() {
       return;
     }
 
+    // Validate config structure
+    const validTopKeys = ['theme', 'plugins', 'corePlugins', 'prefix', 'styled'];
+    const invalidKeys = Object.keys(config).filter(k => !validTopKeys.includes(k));
+    if (invalidKeys.length > 0) {
+      logger.warn(`configure: Unrecognized config keys: ${invalidKeys.join(', ')}. ` + `Valid keys are: ${validTopKeys.join(', ')}`);
+    }
+    if (config.theme) {
+      if (typeof config.theme !== 'object' || Array.isArray(config.theme)) {
+        logger.warn('configure: theme must be an object');
+        return;
+      }
+      const validThemeKeys = ['extend', 'colors', 'spacing', 'borderRadius', 'fontSize', 'fontFamily', 'screens', 'breakpoints'];
+      const invalidThemeKeys = Object.keys(config.theme).filter(k => !validThemeKeys.includes(k) && typeof config.theme[k] !== 'object');
+      if (invalidThemeKeys.length > 0) {
+        logger.warn(`configure: Unrecognized theme keys: ${invalidThemeKeys.join(', ')}. ` + `Common keys are: ${validThemeKeys.join(', ')}`);
+      }
+    }
+    if (config.plugins !== undefined && !Array.isArray(config.plugins)) {
+      logger.warn('configure: plugins must be an array');
+      return;
+    }
+    if (config.prefix !== undefined && typeof config.prefix !== 'string') {
+      logger.warn('configure: prefix must be a string');
+      return;
+    }
+
     // Clear extended theme cache when config changes
     extendedThemeCache.clear();
 
@@ -1954,9 +1979,9 @@ function configure() {
   }
 }
 
-/**
- * Get current user configuration
- * @returns {Object} Current configuration
+/**
+ * Get current user configuration
+ * @returns {Object} Current configuration
  */
 function getConfig() {
   return {
@@ -1964,8 +1989,8 @@ function getConfig() {
   };
 }
 
-/**
- * Reset configuration to defaults
+/**
+ * Reset configuration to defaults
  */
 function resetConfig() {
   userConfig = {
@@ -1981,10 +2006,10 @@ function resetConfig() {
   logger.info("Configuration reset to defaults");
 }
 
-/**
- * Get extended theme value
- * @param {string} key - Theme key (e.g., 'colors', 'spacing')
- * @returns {Object} Extended theme values
+/**
+ * Get extended theme value
+ * @param {string} key - Theme key (e.g., 'colors', 'spacing')
+ * @returns {Object} Extended theme values
  */
 function getExtendedTheme(key) {
   // Check cache first
@@ -1998,17 +2023,17 @@ function getExtendedTheme(key) {
   return result;
 }
 
-/**
- * Get all registered plugins
- * @returns {Array} Array of plugins
+/**
+ * Get all registered plugins
+ * @returns {Array} Array of plugins
  */
 function getPlugins() {
   return userConfig.plugins;
 }
 
-/**
- * Get configured prefix
- * @returns {string} Prefix string
+/**
+ * Get configured prefix
+ * @returns {string} Prefix string
  */
 function getPrefix() {
   return userConfig.prefix;
@@ -2523,9 +2548,9 @@ function staggerAnimations(elements, animationName) {
   });
 }
 
-/**
- * Animation Generator
- * Generates animation utility classes with dynamic inline animations
+/**
+ * Animation Generator
+ * Generates animation utility classes with dynamic inline animations
  */
 
 function generator$2I() {
@@ -7243,9 +7268,9 @@ function generator$d() {
   return responsiveCssString;
 }
 
-/**
- * Transition Delay Generator
- * Generates transition-delay utility classes
+/**
+ * Transition Delay Generator
+ * Generates transition-delay utility classes
  */
 
 function generator$c() {
@@ -7274,9 +7299,9 @@ function generator$c() {
   return responsiveCssString;
 }
 
-/**
- * Transition Duration Generator
- * Generates transition-duration utility classes
+/**
+ * Transition Duration Generator
+ * Generates transition-duration utility classes
  */
 
 function generator$b() {
@@ -7305,9 +7330,9 @@ function generator$b() {
   return responsiveCssString;
 }
 
-/**
- * Transition Property Generator
- * Generates transition-property utility classes
+/**
+ * Transition Property Generator
+ * Generates transition-property utility classes
  */
 
 function generator$a() {
@@ -7347,9 +7372,9 @@ function generator$a() {
   return responsiveCssString;
 }
 
-/**
- * Transition Timing Function Generator
- * Generates transition-timing-function utility classes (ease)
+/**
+ * Transition Timing Function Generator
+ * Generates transition-timing-function utility classes (ease)
  */
 
 function generator$9() {
@@ -7988,6 +8013,108 @@ const patterns = {
   ...fontFamily
 };
 
+/**
+ * CX - Conditional Class Name Builder
+ * 
+ * A lightweight utility for conditionally joining Tailwind class names.
+ * Similar to `clsx`/`classnames` but designed specifically for tailwind-to-style.
+ * 
+ * @module cx
+ */
+
+/**
+ * Conditionally join class names into a single string.
+ * 
+ * Accepts strings, objects (key=className, value=condition), arrays, and nested combinations.
+ * Falsy values (null, undefined, false, 0, '') are ignored.
+ * 
+ * @param {...(string|Object|Array|boolean|null|undefined)} args - Class name inputs
+ * @returns {string} Joined class names string
+ * 
+ * @example
+ * // Strings
+ * cx('bg-blue-500', 'text-white')
+ * // → 'bg-blue-500 text-white'
+ * 
+ * @example
+ * // Conditionals
+ * cx('p-4', isActive && 'bg-blue-500', isDisabled && 'opacity-50')
+ * // → 'p-4 bg-blue-500' (if isActive=true, isDisabled=false)
+ * 
+ * @example
+ * // Object syntax
+ * cx('p-4', { 'bg-blue-500': isActive, 'opacity-50': isDisabled, 'cursor-pointer': true })
+ * // → 'p-4 bg-blue-500 cursor-pointer'
+ * 
+ * @example
+ * // Arrays (nested)
+ * cx(['p-4', 'bg-white'], isActive && ['ring-2', 'ring-blue-500'])
+ * // → 'p-4 bg-white ring-2 ring-blue-500'
+ * 
+ * @example
+ * // Mixed
+ * cx(
+ *   'base-class',
+ *   condition && 'conditional-class',
+ *   { 'object-class': true, 'ignored-class': false },
+ *   ['array-class-1', 'array-class-2']
+ * )
+ */
+function cx() {
+  const classes = [];
+  for (let i = 0; i < arguments.length; i++) {
+    const arg = i < 0 || arguments.length <= i ? undefined : arguments[i];
+
+    // Skip falsy values
+    if (!arg) continue;
+    const type = typeof arg;
+    if (type === 'string') {
+      classes.push(arg);
+    } else if (Array.isArray(arg)) {
+      // Recursively process arrays
+      const inner = cx(...arg);
+      if (inner) classes.push(inner);
+    } else if (type === 'object') {
+      // Object: keys are class names, values are conditions
+      const keys = Object.keys(arg);
+      for (let j = 0; j < keys.length; j++) {
+        if (arg[keys[j]]) {
+          classes.push(keys[j]);
+        }
+      }
+    }
+  }
+  return classes.join(' ');
+}
+
+/**
+ * Create a cx function bound with base classes.
+ * Useful for component-level class composition.
+ * 
+ * @param {...(string|Object|Array)} baseArgs - Base class arguments always included
+ * @returns {Function} A cx function pre-filled with base classes
+ * 
+ * @example
+ * const btnClasses = cx.with('px-4 py-2 rounded font-medium transition-colors')
+ * 
+ * btnClasses('bg-blue-500 text-white')
+ * // → 'px-4 py-2 rounded font-medium transition-colors bg-blue-500 text-white'
+ * 
+ * btnClasses({ 'opacity-50 cursor-not-allowed': isDisabled })
+ * // → 'px-4 py-2 rounded font-medium transition-colors opacity-50 cursor-not-allowed'
+ */
+cx.with = function () {
+  for (var _len = arguments.length, baseArgs = new Array(_len), _key = 0; _key < _len; _key++) {
+    baseArgs[_key] = arguments[_key];
+  }
+  return function () {
+    for (var _len2 = arguments.length, args = new Array(_len2), _key2 = 0; _key2 < _len2; _key2++) {
+      args[_key2] = arguments[_key2];
+    }
+    return cx(...baseArgs, ...args);
+  };
+};
+
 /**
  * Web Animations API Integration
  * Dynamic animations without keyframes injection
@@ -8309,16 +8436,89 @@ function applyDynamicAnimation(element, templateName) {
   return animationName;
 }
 
+// ============================================================================
+// SSR (Server-Side Rendering) Support
+// Detect environment once at module load for zero-cost runtime checks
+// ============================================================================
+const IS_BROWSER = typeof window !== "undefined" && typeof document !== "undefined";
+const IS_SERVER = !IS_BROWSER;
+
+// SSR CSS collector - accumulates CSS strings during server rendering
+let _ssrCollectedCss = [];
+let _ssrCollecting = false;
+
+/**
+ * Start collecting CSS for SSR. Call before rendering.
+ * @returns {void}
+ * @example
+ * import { startSSR, stopSSR } from 'tailwind-to-style'
+ * startSSR()
+ * const html = renderToString(<App />)
+ * const css = stopSSR()
+ * // Inject css into <head> of your HTML response
+ */
+function startSSR() {
+  _ssrCollectedCss = [];
+  _ssrCollecting = true;
+}
+
+/**
+ * Stop collecting CSS and return all collected CSS as a single string.
+ * @returns {string} All CSS collected during SSR
+ */
+function stopSSR() {
+  _ssrCollecting = false;
+  const css = _ssrCollectedCss.join('\n');
+  _ssrCollectedCss = [];
+  return css;
+}
+
+/**
+ * Get collected CSS without stopping collection.
+ * @returns {string} Currently collected CSS
+ */
+function getSSRStyles() {
+  return _ssrCollectedCss.join('\n');
+}
+
+// ============================================================================
+// Bounded Caches (prevent memory leaks in long-running SPAs)
+// ============================================================================
+const MAX_CACHE_SIZE = 5000;
+const MAX_SET_SIZE = 10000;
+
 // Global registry to track injected keyframes (prevents duplication)
 const _injectedKeyframes = new Set();
 
-// Global cache Maps for cached versions (twsxCache, twsxVariantsCache functions)
+// Global cache Maps with bounded eviction
 const _twsxInputCache = new Map();
 const _twsxVariantsResultCache = new Map();
 
 // WeakMap for object identity-based caching (fast lookup for repeated objects)
 const _objectIdentityCache = new WeakMap();
 
+/** Evict oldest entries from a Map when it exceeds maxSize */
+function evictMap(map) {
+  let maxSize = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : MAX_CACHE_SIZE;
+  if (map.size <= maxSize) return;
+  const excess = map.size - maxSize;
+  const iter = map.keys();
+  for (let i = 0; i < excess; i++) {
+    map.delete(iter.next().value);
+  }
+}
+
+/** Evict oldest entries from a Set when it exceeds maxSize */
+function evictSet(set) {
+  let maxSize = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : MAX_SET_SIZE;
+  if (set.size <= maxSize) return;
+  const excess = set.size - maxSize;
+  const iter = set.values();
+  for (let i = 0; i < excess; i++) {
+    set.delete(iter.next().value);
+  }
+}
+
 // Mapping of animation names to their keyframe definitions
 const BUILTIN_KEYFRAMES = {
   spin: {
@@ -8403,8 +8603,8 @@ function generateMinifiedKeyframes(animationNames) {
 // by avoiding repeated regex object creation in hot code paths
 // ============================================================================
 
-// Class parsing
-const CLASS_PARSER_REGEX = /[\w-\/]+(?:\/\d+)?(?:\[[^\]]+\])?/g;
+// Class parsing (includes . for decimal values like p-0.5)
+const CLASS_PARSER_REGEX = /[\w.\-\/]+(?:\/\d+)?(?:\[[^\]]+\])?/g;
 
 // Opacity modifiers
 const OPACITY_MODIFIER_REGEX = /\/(\d+)$/;
@@ -8440,8 +8640,8 @@ const VARIANT_GROUP_REGEX = /(\w+):\(([^()]+(?:\((?:[^()]+)\))?[^()]*)\)/g;
 const WHITESPACE_SPLIT_REGEX = /\s+/;
 const VARIANT_COLON_SPLIT_REGEX = /:/;
 
-// CSS variable resolution
-const CSS_VAR_REGEX = /var\((--[\w-]+)(?:,\s*([^)]+))?\)/g;
+// CSS variable resolution — supports nested parens in fallback (e.g. rgba(...))
+const CSS_VAR_REGEX = /var\((--[\w-]+)(?:,\s*((?:[^()]+|\([^()]*\))*))?\)/g;
 const CAMEL_CASE_REGEX = /-([a-z])/g;
 
 // Animation detection
@@ -8679,11 +8879,11 @@ function parseCustomClassWithPatterns(className) {
   return null;
 }
 
-/**
- * Resolve all CSS custom properties (var) in a CSS string and output only clear CSS (no custom property)
- * Optimized with for loops and indexOf for 2-3x better performance
- * @param {string} cssString
- * @returns {string} e.g. 'color: rgba(255,255,255,1); background: #fff;'
+/**
+ * Resolve all CSS custom properties (var) in a CSS string and output only clear CSS (no custom property)
+ * Optimized with for loops and indexOf for 2-3x better performance
+ * @param {string} cssString
+ * @returns {string} e.g. 'color: rgba(255,255,255,1); background: #fff;'
  */
 function resolveCssToClearCss(cssString) {
   const customVars = {};
@@ -8735,9 +8935,9 @@ function resolveCssToClearCss(cssString) {
 // Cache for getConfigOptions - use LRU cache
 const configOptionsCache = new LRUCache(500);
 
-/**
- * Clear config options cache (internal use)
- * Called when user configuration changes
+/**
+ * Clear config options cache (internal use)
+ * Called when user configuration changes
  */
 function clearConfigCache() {
   configOptionsCache.clear();
@@ -9003,6 +9203,9 @@ function separateAndResolveCSS(arr) {
             // Prioritize more specific values (e.g., !important)
             if (value.includes("!important") || !cssProperties[key]) {
               cssProperties[key] = value;
+            } else if (key === "--gradient-color-stops" && value.includes("--gradient-via-color") && !cssProperties[key].includes("--gradient-via-color")) {
+              // Allow 3-stop gradient (with via) to overwrite 2-stop version
+              cssProperties[key] = value;
             }
           }
         }
@@ -9014,10 +9217,10 @@ function separateAndResolveCSS(arr) {
       ...cssProperties
     };
 
-    /**
-     * Optimized CSS variable resolution using regex-based approach
-     * 2-3x faster than manual char-by-char parsing
-     * Handles nested var() with fallback values
+    /**
+     * Optimized CSS variable resolution using regex-based approach
+     * 2-3x faster than manual char-by-char parsing
+     * Handles nested var() with fallback values
      */
     const resolveValue = function (value, variables) {
       let maxDepth = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 10;
@@ -9106,11 +9309,11 @@ function separateAndResolveCSS(arr) {
   }
 }
 
-/**
- * Process opacity modifier from class name (e.g., text-red-500/50 -> 50% opacity)
- * @param {string} className - Class name with potential opacity modifier
- * @param {string} cssDeclaration - CSS declaration to modify
- * @returns {string} Modified CSS declaration with opacity applied
+/**
+ * Process opacity modifier from class name (e.g., text-red-500/50 -> 50% opacity)
+ * @param {string} className - Class name with potential opacity modifier
+ * @param {string} cssDeclaration - CSS declaration to modify
+ * @returns {string} Modified CSS declaration with opacity applied
  */
 function processOpacityModifier(className, cssDeclaration) {
   const opacityMatch = OPACITY_MODIFIER_REGEX.exec(className);
@@ -9173,18 +9376,18 @@ function processOpacityModifier(className, cssDeclaration) {
   return modifiedDeclaration;
 }
 
-/**
- * Convert Tailwind class string to inline CSS styles or JSON object
- * @param {string} classNames - String containing Tailwind classes to convert
- * @param {boolean} convertToJson - If true, result will be JSON object, if false becomes CSS string
- * @returns {string|Object} Inline CSS string or style JSON object
+/**
+ * Convert Tailwind class string to inline CSS styles or JSON object
+ * @param {string} classNames - String containing Tailwind classes to convert
+ * @param {boolean} convertToJson - If true, result will be JSON object, if false becomes CSS string
+ * @returns {string|Object} Inline CSS string or style JSON object
  */
 function tws(classNames, convertToJson) {
   const totalMarker = performanceMonitor.start("tws:total");
   try {
     // Initialize CSS object using singleton cache
     const cssObject = tailwindCache.getOrGenerate(generateTailwindCssString, convertCssToObject);
-    if ([!classNames, typeof classNames !== "string", classNames.trim() === ""].includes(true)) {
+    if (!classNames || typeof classNames !== "string" || classNames.trim() === "") {
       performanceMonitor.end(totalMarker);
       return convertToJson ? {} : "";
     }
@@ -9505,6 +9708,17 @@ function walkStyleTree(selector, val, styles, walk) {
     processNestedSelectors(nested, selector, styles, walk);
   } else if (typeof val === "string") {
     if (val.trim() === "") return;
+    // Handle @css string directive: '@css { ... }'
+    const trimmedVal = val.trim();
+    if (trimmedVal.startsWith('@css')) {
+      const cssMatch = trimmedVal.match(/^@css\s*\{([\s\S]*)\}\s*$/);
+      if (cssMatch) {
+        const rawCss = cssMatch[1].trim();
+        styles[selector] = styles[selector] || '';
+        styles[selector] += rawCss.split(';').filter(d => d.trim()).map(d => d.trim() + ';').join(' ') + '\n';
+        return;
+      }
+    }
     walk(selector, [expandGroupedClass(val)]);
   } else if (typeof val === "object" && val !== null) {
     const {
@@ -9681,13 +9895,13 @@ function generateCssString(styles) {
   return cssString.trim();
 }
 
-/**
- * Generate CSS string from style object with SCSS-like syntax (NO CACHE)
- * This is the original non-cached version. Use twsx() for cached version.
- * Supports nested selectors, state variants, responsive variants, and @css directives
- * @param {Object} obj - Object with SCSS-like style format
- * @param {Object} [options] - Additional options, e.g. { inject: true/false }
- * @returns {string} Generated CSS string
+/**
+ * Generate CSS string from style object with SCSS-like syntax (NO CACHE)
+ * This is the original non-cached version. Use twsx() for cached version.
+ * Supports nested selectors, state variants, responsive variants, and @css directives
+ * @param {Object} obj - Object with SCSS-like style format
+ * @param {Object} [options] - Additional options, e.g. { inject: true/false }
+ * @returns {string} Generated CSS string
  */
 function twsxNoCache(obj) {
   let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -9773,6 +9987,17 @@ function twsxNoCache(obj) {
       let baseClass = "";
       const nested = {};
       if (typeof val === "string") {
+        // Handle @css string directive: '@css { ... }'
+        const trimmedVal = val.trim();
+        if (trimmedVal.startsWith('@css')) {
+          const cssMatch = trimmedVal.match(/^@css\s*\{([\s\S]*)\}\s*$/);
+          if (cssMatch) {
+            const rawCss = cssMatch[1].trim();
+            styles[selector] = styles[selector] || '';
+            styles[selector] += rawCss.split(';').filter(d => d.trim()).map(d => d.trim() + ';').join(' ') + '\n';
+            continue;
+          }
+        }
         // Check if this is a @css property value - if so, don't process through expandGroupedClass
         if (selector.includes(" @css ")) {
           // This is a CSS property value from @css flattening - keep as-is
@@ -9883,42 +10108,42 @@ function twsxNoCache(obj) {
   }
 }
 
-/**
- * Create a variant-based style generator (NO CACHE)
- * This is the original non-cached version. Use twsxVariants() for cached version.
- * Supports base styles, variants, compound variants, and default variants
- *
- * @param {Object} config - Configuration object
- * @param {string} config.base - Base Tailwind classes applied to all variants
- * @param {Object} config.variants - Variant definitions with their options
- * @param {Array} config.compoundVariants - Compound variant rules for multi-variant combinations
- * @param {Object} config.defaultVariants - Default variant values
- * @returns {Function} A function that accepts variant props and returns merged classes
- *
- * @example
- * const button = twsxVariantsNoCache({
- *   base: 'px-4 py-2 rounded font-medium',
- *   variants: {
- *     color: {
- *       primary: 'bg-blue-500 text-white',
- *       secondary: 'bg-gray-500 text-white'
- *     },
- *     size: {
- *       sm: 'text-sm',
- *       lg: 'text-lg'
- *     }
- *   },
- *   compoundVariants: [
- *     { color: 'primary', size: 'lg', class: 'font-bold shadow-lg' }
- *   ],
- *   defaultVariants: {
- *     color: 'primary',
- *     size: 'sm'
- *   }
- * });
- *
- * // Usage:
- * button({ color: 'primary', size: 'lg' }) // Returns merged classes
+/**
+ * Create a variant-based style generator (NO CACHE)
+ * This is the original non-cached version. Use twsxVariants() for cached version.
+ * Supports base styles, variants, compound variants, and default variants
+ *
+ * @param {Object} config - Configuration object
+ * @param {string} config.base - Base Tailwind classes applied to all variants
+ * @param {Object} config.variants - Variant definitions with their options
+ * @param {Array} config.compoundVariants - Compound variant rules for multi-variant combinations
+ * @param {Object} config.defaultVariants - Default variant values
+ * @returns {Function} A function that accepts variant props and returns merged classes
+ *
+ * @example
+ * const button = twsxVariantsNoCache({
+ *   base: 'px-4 py-2 rounded font-medium',
+ *   variants: {
+ *     color: {
+ *       primary: 'bg-blue-500 text-white',
+ *       secondary: 'bg-gray-500 text-white'
+ *     },
+ *     size: {
+ *       sm: 'text-sm',
+ *       lg: 'text-lg'
+ *     }
+ *   },
+ *   compoundVariants: [
+ *     { color: 'primary', size: 'lg', class: 'font-bold shadow-lg' }
+ *   ],
+ *   defaultVariants: {
+ *     color: 'primary',
+ *     size: 'sm'
+ *   }
+ * });
+ *
+ * // Usage:
+ * button({ color: 'primary', size: 'lg' }) // Returns merged classes
  */
 function twsxVariantsNoCache(className) {
   let config = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -9930,11 +10155,11 @@ function twsxVariantsNoCache(className) {
     nested = {}
   } = config;
 
-  /**
-   * Check if a compound variant matches the current props
-   * @param {Object} compound - Compound variant definition
-   * @param {Object} props - Current variant props
-   * @returns {boolean}
+  /**
+   * Check if a compound variant matches the current props
+   * @param {Object} compound - Compound variant definition
+   * @param {Object} props - Current variant props
+   * @returns {boolean}
    */
   function matchesCompoundVariant(compound, props) {
     for (const key in compound) {
@@ -9955,19 +10180,19 @@ function twsxVariantsNoCache(className) {
     return true;
   }
 
-  /**
-   * Merge multiple class strings with conflict resolution
-   * Later classes override earlier ones for the same CSS property
-   * @param  {...string} classStrings - Class strings to merge
-   * @returns {string}
+  /**
+   * Merge multiple class strings with conflict resolution
+   * Later classes override earlier ones for the same CSS property
+   * @param  {...string} classStrings - Class strings to merge
+   * @returns {string}
    */
   function mergeClasses() {
     const result = [];
     const propertyMap = new Map(); // Track index by conflict key
 
-    /**
-     * Extract conflict key from Tailwind class
-     * Classes that affect the same CSS property should have the same key
+    /**
+     * Extract conflict key from Tailwind class
+     * Classes that affect the same CSS property should have the same key
      */
     function getConflictKey(cls) {
       // Extract variant prefix (hover:, focus:, etc.)
@@ -10199,10 +10424,10 @@ function twsxVariantsNoCache(className) {
     return result.filter(Boolean).join(" ");
   }
 
-  /**
-   * Generate classes for a specific variant combination
-   * @param {Object} props - Variant props
-   * @returns {string} Merged Tailwind classes
+  /**
+   * Generate classes for a specific variant combination
+   * @param {Object} props - Variant props
+   * @returns {string} Merged Tailwind classes
    */
   function generateClasses() {
     let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -10318,10 +10543,10 @@ function twsxVariantsNoCache(className) {
     }
   }
 
-  /**
-   * Build class name string from props (for component usage)
-   * @param {Object} props - Variant props
-   * @returns {string} Class name string like "alert alert-warning" or "btn btn-outline-danger"
+  /**
+   * Build class name string from props (for component usage)
+   * @param {Object} props - Variant props
+   * @returns {string} Class name string like "alert alert-warning" or "btn btn-outline-danger"
    */
   function buildClassName() {
     let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -10363,10 +10588,10 @@ function twsxVariantsNoCache(className) {
 // FAST HASHING UTILITIES FOR OBJECT CACHING
 // ============================================================================
 
-/**
- * FNV-1a hash algorithm - Fast and good distribution for strings
- * @param {string} str - String to hash
- * @returns {number} 32-bit hash
+/**
+ * FNV-1a hash algorithm - Fast and good distribution for strings
+ * @param {string} str - String to hash
+ * @returns {number} 32-bit hash
  */
 function hashString(str) {
   let hash = 2166136261; // FNV offset basis
@@ -10377,16 +10602,16 @@ function hashString(str) {
   return hash >>> 0; // Convert to unsigned 32-bit
 }
 
-/**
- * Fast deep hash for objects - Optimized for style objects
- * Strategy:
- * 1. Use object identity (WeakMap) for exact same object references
- * 2. For different objects, create stable hash from sorted keys + values
- * 3. Cache hash per object to avoid recomputation
- *
- * @param {any} obj - Object to hash
- * @param {Object} options - Additional options to include in hash
- * @returns {string} Hash key for caching
+/**
+ * Fast deep hash for objects - Optimized for style objects
+ * Strategy:
+ * 1. Use object identity (WeakMap) for exact same object references
+ * 2. For different objects, create stable hash from sorted keys + values
+ * 3. Cache hash per object to avoid recomputation
+ *
+ * @param {any} obj - Object to hash
+ * @param {Object} options - Additional options to include in hash
+ * @returns {string} Hash key for caching
  */
 function fastObjectHash(obj) {
   let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -10431,22 +10656,22 @@ function fastObjectHash(obj) {
   return options && Object.keys(options).length > 0 ? `${hashKey}:${JSON.stringify(options)}` : hashKey;
 }
 
-/**
- * 🚀 CACHED VERSION OF TWSX (DEFAULT)
- * Generate CSS string with input-level caching for repeated calls
- * Uses fast FNV-1a hash + WeakMap for 10-100x performance improvement
- *
- * @param {Object} obj - Object with SCSS-like style format
- * @param {Object} [options] - Additional options, e.g. { inject: true/false }
- * @returns {string} Generated CSS string
- *
- * @example
- * const styles = { '.btn': 'bg-blue-500 text-white p-4' };
- * twsx(styles); // First call: ~40ms
- * twsx(styles); // Cached: ~0.1ms (100x faster!)
- *
- * // For non-cached version (rare case):
- * twsxNoCache(styles);
+/**
+ * 🚀 CACHED VERSION OF TWSX (DEFAULT)
+ * Generate CSS string with input-level caching for repeated calls
+ * Uses fast FNV-1a hash + WeakMap for 10-100x performance improvement
+ *
+ * @param {Object} obj - Object with SCSS-like style format
+ * @param {Object} [options] - Additional options, e.g. { inject: true/false }
+ * @returns {string} Generated CSS string
+ *
+ * @example
+ * const styles = { '.btn': 'bg-blue-500 text-white p-4' };
+ * twsx(styles); // First call: ~40ms
+ * twsx(styles); // Cached: ~0.1ms (100x faster!)
+ *
+ * // For non-cached version (rare case):
+ * twsxNoCache(styles);
  */
 function twsx(obj) {
   let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -10461,7 +10686,7 @@ function twsx(obj) {
     const {
       inject = true
     } = options;
-    if (inject && typeof window !== "undefined" && typeof document !== "undefined") {
+    if (inject && (IS_BROWSER || _ssrCollecting)) {
       autoInjectCss(cached);
     }
     return cached;
@@ -10470,27 +10695,28 @@ function twsx(obj) {
   // Cache miss: call original twsxNoCache and cache result
   const result = twsxNoCache(obj, options);
   _twsxInputCache.set(cacheKey, result);
+  evictMap(_twsxInputCache);
   return result;
 }
 
-/**
- * 🚀 CACHED VERSION OF TWSXVARIANTS (DEFAULT)
- * Create variant-based style generator with config-level caching
- * Uses fast FNV-1a hash for 10-100x performance improvement
- *
- * @param {string} className - Base class name
- * @param {Object} config - Configuration object (base, variants, compoundVariants, etc.)
- * @returns {Function} A function that accepts variant props and returns merged classes
- *
- * @example
- * const button = twsxVariants('btn', {
- *   variants: { color: { primary: {...}, secondary: {...} } }
- * });
- * // First call: ~50ms to generate function
- * // Subsequent calls with same config: ~0.1ms (returns cached function)
- *
- * // For non-cached version (rare case):
- * twsxVariantsNoCache('btn', config);
+/**
+ * 🚀 CACHED VERSION OF TWSXVARIANTS (DEFAULT)
+ * Create variant-based style generator with config-level caching
+ * Uses fast FNV-1a hash for 10-100x performance improvement
+ *
+ * @param {string} className - Base class name
+ * @param {Object} config - Configuration object (base, variants, compoundVariants, etc.)
+ * @returns {Function} A function that accepts variant props and returns merged classes
+ *
+ * @example
+ * const button = twsxVariants('btn', {
+ *   variants: { color: { primary: {...}, secondary: {...} } }
+ * });
+ * // First call: ~50ms to generate function
+ * // Subsequent calls with same config: ~0.1ms (returns cached function)
+ *
+ * // For non-cached version (rare case):
+ * twsxVariantsNoCache('btn', config);
  */
 function twsxVariants(className) {
   let config = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -10505,6 +10731,7 @@ function twsxVariants(className) {
   // Cache miss: call original twsxVariantsNoCache and cache result
   const result = twsxVariantsNoCache(className, config);
   _twsxVariantsResultCache.set(cacheKey, result);
+  evictMap(_twsxVariantsResultCache);
   return result;
 }
 
@@ -10522,25 +10749,64 @@ function getCssHash(str) {
   return hash;
 }
 
-// Enhanced auto-inject CSS with performance monitoring
+// Enhanced auto-inject CSS with performance monitoring & SSR support
 const injectedCssHashSet = new Set();
 function autoInjectCss(cssString) {
   const marker = performanceMonitor.start("css:inject");
   try {
-    if (typeof window !== "undefined" && typeof document !== "undefined") {
+    // SSR mode: collect CSS strings instead of DOM injection
+    if (_ssrCollecting) {
+      const cssHash = getCssHash(cssString);
+      if (injectedCssHashSet.has(cssHash)) {
+        performanceMonitor.end(marker);
+        return;
+      }
+      injectedCssHashSet.add(cssHash);
+      evictSet(injectedCssHashSet);
+      _ssrCollectedCss.push(cssString);
+      performanceMonitor.end(marker);
+      return;
+    }
+    if (IS_BROWSER) {
       const cssHash = getCssHash(cssString);
       if (injectedCssHashSet.has(cssHash)) {
         performanceMonitor.end(marker);
         return;
       }
       injectedCssHashSet.add(cssHash);
+      evictSet(injectedCssHashSet);
       let styleTag = document.getElementById("twsx-auto-style");
       if (!styleTag) {
         styleTag = document.createElement("style");
         styleTag.id = "twsx-auto-style";
+        styleTag.setAttribute("data-twsx", "");
         document.head.appendChild(styleTag);
       }
-      styleTag.textContent += `\n${cssString}`;
+
+      // Use insertRule for better performance (avoids full stylesheet reparse)
+      try {
+        const sheet = styleTag.sheet;
+        if (sheet) {
+          // Split CSS by closing brace to insert individual rules
+          const rules = cssString.split('}').filter(r => r.trim());
+          for (const rule of rules) {
+            const trimmed = rule.trim();
+            if (trimmed) {
+              try {
+                sheet.insertRule(trimmed + '}', sheet.cssRules.length);
+              } catch (e) {
+                // Fallback for complex rules (e.g., @keyframes, @media)
+                styleTag.textContent += `\n${trimmed}}`;
+              }
+            }
+          }
+        } else {
+          styleTag.textContent += `\n${cssString}`;
+        }
+      } catch (e) {
+        // Ultimate fallback
+        styleTag.textContent += `\n${cssString}`;
+      }
 
       // Log injection stats periodically
       if (injectedCssHashSet.size % 10 === 0) {
@@ -10555,19 +10821,19 @@ function autoInjectCss(cssString) {
 }
 
 // Enhanced debounced functions with performance monitoring configuration
-/**
- * Debounced version of tws function with performance monitoring
- * @param {string} classNames - String containing Tailwind classes to convert
- * @param {boolean} convertToJson - If true, result will be JSON object, if false becomes CSS string
- * @returns {string|Object} Inline CSS string or style JSON object
+/**
+ * Debounced version of tws function with performance monitoring
+ * @param {string} classNames - String containing Tailwind classes to convert
+ * @param {boolean} convertToJson - If true, result will be JSON object, if false becomes CSS string
+ * @returns {string|Object} Inline CSS string or style JSON object
  */
 const debouncedTws = debounce(tws, 50); // Faster debounce for tws
 
-/**
- * Debounced version of twsx function with performance monitoring
- * @param {Object} obj - Object with SCSS-like style format
- * @param {Object} [options] - Additional options
- * @returns {string} Generated CSS string
+/**
+ * Debounced version of twsx function with performance monitoring
+ * @param {Object} obj - Object with SCSS-like style format
+ * @param {Object} [options] - Additional options
+ * @returns {string} Generated CSS string
  */
 const debouncedTwsx = debounce(twsx, 100); // Standard debounce for twsx
 
@@ -10610,6 +10876,5 @@ const performanceUtils = {
   }
 };
 
-// End of exports - v3.0.0 core only (tws, twsx, twsxVariants, configure)
-
-export { DYNAMIC_TEMPLATES, INLINE_ANIMATIONS, LRUCache, Logger, TwsError, animateElement, applyDynamicAnimation, applyInlineAnimation, applyWebAnimation, chainAnimations, clearConfigCache, configure, createDynamicAnimation, createPlugin, createTemplateAnimation, createUtilityPlugin, createVariantPlugin, debouncedTws, debouncedTwsx, getConfig, getTailwindCache, handleError, initWebAnimations, logger, onError, performanceUtils, resetConfig, resetTailwindCache, staggerAnimations, tws, twsx, twsxVariants };
+export { DYNAMIC_TEMPLATES, INLINE_ANIMATIONS, IS_BROWSER, IS_SERVER, LRUCache, Logger, TwsError, animateElement, applyDynamicAnimation, applyInlineAnimation, applyWebAnimation, chainAnimations, clearConfigCache, configure, createDynamicAnimation, createPlugin, createTemplateAnimation, createUtilityPlugin, createVariantPlugin, cx, debouncedTws, debouncedTwsx, getConfig, getSSRStyles, getTailwindCache, handleError, initWebAnimations, logger, onError, performanceUtils, resetConfig, resetTailwindCache, staggerAnimations, startSSR, stopSSR, tws, twsx, twsxVariants };
+//# sourceMappingURL=index.esm.js.map