@shohojdhara/atomix 0.5.2 → 0.5.5

package/dist/theme.js

@@ -1,6 +1,6 @@
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 
-import { createContext, useRef, useEffect, useCallback, useMemo, useState, useContext, Component } from "react";
+import React, { createContext, useRef, useEffect, useCallback, useMemo, useState, useContext, Component } from "react";
 
 /**
  * Design Tokens
@@ -296,7 +296,51 @@ import { createContext, useRef, useEffect, useCallback, useMemo, useState, useCo
     "breakpoint-md": "768px",
     "breakpoint-lg": "992px",
     "breakpoint-xl": "1200px",
-    "breakpoint-xxl": "1440px"
+    "breakpoint-xxl": "1440px",
+    // Advanced Features - Interactive Effects (Phase 2)
+    "interactive-vortex-enabled": "false",
+    "interactive-vortex-strength": "0.5",
+    "interactive-vortex-radius": "100",
+    "interactive-vortex-decay": "0.8",
+    "interactive-chromatic-enabled": "false",
+    "interactive-chromatic-mode": "lateral",
+    "interactive-chromatic-red-shift": "0.02",
+    "interactive-chromatic-green-shift": "0",
+    "interactive-chromatic-blue-shift": "-0.02",
+    "interactive-chromatic-edge-only": "false",
+    "interactive-chromatic-edge-threshold": "0.5",
+    "interactive-mouse-sensitivity": "1.0",
+    "interactive-mouse-trail-effect": "false",
+    "interactive-animation-speed-base": "1.0",
+    "interactive-animation-speed-multiplier": "1.0",
+    // Advanced Features - Optimization (Phase 3)
+    "optimization-breakpoint-mobile": "0px",
+    "optimization-breakpoint-tablet": "768px",
+    "optimization-breakpoint-desktop": "1024px",
+    "optimization-breakpoint-wide": "1440px",
+    "optimization-device-scaling-mobile": "0.5",
+    "optimization-device-scaling-tablet": "0.75",
+    "optimization-device-scaling-desktop": "1.0",
+    "optimization-performance-fps-target": "60",
+    "optimization-auto-scaling-enabled": "false",
+    "optimization-auto-scaling-low-end": "0.5",
+    "optimization-auto-scaling-mid-range": "0.75",
+    "optimization-auto-scaling-high-end": "1.0",
+    // Advanced Features - Visual Polish (Phase 4)
+    "visual-polish-border-iridescent-glow": "false",
+    "visual-polish-border-shimmer-effect": "false",
+    "visual-polish-border-beveled-edges": "false",
+    "visual-polish-border-pulsing-glow": "false",
+    "visual-polish-content-aware-blur-enabled": "false",
+    "visual-polish-content-aware-depth-detection": "false",
+    "visual-polish-content-aware-edge-preservation": "false",
+    "visual-polish-content-aware-variable-radius": "false",
+    "visual-polish-holographic-enabled": "false",
+    "visual-polish-holographic-rainbow-diffraction": "false",
+    "visual-polish-holographic-scanline-animation": "false",
+    "visual-polish-holographic-grid-overlay": "false",
+    "visual-polish-holographic-data-stream": "false",
+    "visual-polish-holographic-pulse-rings": "false"
 };
 
 /**
@@ -376,412 +420,278 @@ import { createContext, useRef, useEffect, useCallback, useMemo, useState, useCo
 }
 
 /**
- * Theme System Error Handling
+ * Theme Adapter
  *
- * Centralized error handling for the Atomix theme system.
- * Provides custom error classes and logging utilities.
- */
-/**
- * Theme error codes
- */ var ThemeErrorCode, LogLevel;
-
-!function(ThemeErrorCode) {
-    /** Theme not found in registry */
-    ThemeErrorCode.THEME_NOT_FOUND = "THEME_NOT_FOUND", 
-    /** Theme failed to load */
-    ThemeErrorCode.THEME_LOAD_FAILED = "THEME_LOAD_FAILED", 
-    /** Theme validation failed */
-    ThemeErrorCode.THEME_VALIDATION_FAILED = "THEME_VALIDATION_FAILED", 
-    /** Configuration loading failed */
-    ThemeErrorCode.CONFIG_LOAD_FAILED = "CONFIG_LOAD_FAILED", 
-    /** Configuration validation failed */
-    ThemeErrorCode.CONFIG_VALIDATION_FAILED = "CONFIG_VALIDATION_FAILED", 
-    /** Circular dependency detected */
-    ThemeErrorCode.CIRCULAR_DEPENDENCY = "CIRCULAR_DEPENDENCY", 
-    /** Missing dependency */
-    ThemeErrorCode.MISSING_DEPENDENCY = "MISSING_DEPENDENCY", 
-    /** Storage operation failed */
-    ThemeErrorCode.STORAGE_ERROR = "STORAGE_ERROR", 
-    /** Invalid theme name */
-    ThemeErrorCode.INVALID_THEME_NAME = "INVALID_THEME_NAME", 
-    /** CSS injection failed */
-    ThemeErrorCode.CSS_INJECTION_FAILED = "CSS_INJECTION_FAILED", 
-    /** Invalid color format */
-    ThemeErrorCode.INVALID_COLOR_FORMAT = "INVALID_COLOR_FORMAT", 
-    /** Missing required token */
-    ThemeErrorCode.MISSING_REQUIRED_TOKEN = "MISSING_REQUIRED_TOKEN", 
-    /** Accessibility contrast violation */
-    ThemeErrorCode.CONTRAST_VIOLATION = "CONTRAST_VIOLATION", 
-    /** Invalid token type */
-    ThemeErrorCode.INVALID_TOKEN_TYPE = "INVALID_TOKEN_TYPE", 
-    /** Unknown error */
-    ThemeErrorCode.UNKNOWN_ERROR = "UNKNOWN_ERROR";
-}(ThemeErrorCode || (ThemeErrorCode = {}));
-
-/**
- * Custom error class for theme-related errors
+ * Converts between Theme objects and DesignTokens
  */
-class ThemeError extends Error {
-    constructor(message, code = ThemeErrorCode.UNKNOWN_ERROR, context) {
-        super(message), this.name = "ThemeError", this.code = code, this.context = context, 
-        this.timestamp = Date.now(), 
-        // Maintains proper stack trace for where our error was thrown (only available on V8)
-        Error.captureStackTrace && Error.captureStackTrace(this, ThemeError);
-    }
-    /**
-   * Convert error to JSON for logging
-   */    toJSON() {
-        return {
-            name: this.name,
-            message: this.message,
-            code: this.code,
-            context: this.context,
-            timestamp: this.timestamp,
-            stack: this.stack
-        };
-    }
-}
-
-/**
- * Log level
- */ !function(LogLevel) {
-    LogLevel[LogLevel.ERROR = 0] = "ERROR", LogLevel[LogLevel.WARN = 1] = "WARN", LogLevel[LogLevel.INFO = 2] = "INFO", 
-    LogLevel[LogLevel.DEBUG = 3] = "DEBUG";
-}(LogLevel || (LogLevel = {}));
-
 /**
- * Theme Logger
- *
- * Centralized logging for the theme system.
- * Replaces console statements with structured logging.
- */
-class ThemeLogger {
-    constructor(config = {}) {
-        this.config = {
-            level: config.level ?? ("undefined" != typeof process && "production" === process.env?.NODE_ENV ? LogLevel.WARN : LogLevel.INFO),
-            enableConsole: config.enableConsole ?? !0,
-            onError: config.onError,
-            onWarn: config.onWarn,
-            onInfo: config.onInfo,
-            onDebug: config.onDebug
-        };
-    }
-    /**
-   * Log an error
-   */    error(message, error, context) {
-        if (this.config.level < LogLevel.ERROR) return;
-        const errorObj = error instanceof Error ? error : new Error(message), themeError = error instanceof ThemeError ? error : new ThemeError(message, ThemeErrorCode.UNKNOWN_ERROR, context);
-        this.config.enableConsole && console.error(`[ThemeError] ${message}`, {
-            error: errorObj,
-            context: {
-                ...context,
-                ...themeError.context
-            },
-            code: themeError.code
-        }), this.config.onError?.(themeError, context);
-    }
-    /**
-   * Log a warning
-   */    warn(message, context) {
-        this.config.level < LogLevel.WARN || (this.config.enableConsole && console.warn(`[ThemeWarning] ${message}`, context || {}), 
-        this.config.onWarn?.(message, context));
+ * Convert a Theme object to DesignTokens
+ */ function themeToDesignTokens(theme) {
+    const tokens = {};
+    // Convert colors
+        if (theme.palette) {
+        // Primary color
+        if (theme.palette.primary) {
+            const primaryMain = theme.palette.primary.main;
+            tokens.primary = primaryMain;
+            const rgb = hexToRgb$2(primaryMain);
+            rgb && (tokens["primary-rgb"] = rgb);
+        }
+        // Secondary color
+                if (theme.palette.secondary) {
+            const secondaryMain = theme.palette.secondary.main;
+            tokens.secondary = secondaryMain;
+            const rgb = hexToRgb$2(secondaryMain);
+            rgb && (tokens["secondary-rgb"] = rgb);
+        }
+        // Other colors
+                const colorKeys = [ "error", "warning", "info", "success" ];
+        for (const key of colorKeys) if (theme.palette[key]) {
+            const colorMain = theme.palette[key].main;
+            tokens[key] = colorMain;
+            const rgb = hexToRgb$2(colorMain);
+            rgb && (tokens[`${key}-rgb`] = rgb);
+        }
+        // Background colors
+                theme.palette.background && (tokens["body-bg"] = theme.palette.background.default), 
+        // Text colors
+        theme.palette.text && (tokens["body-color"] = theme.palette.text.primary);
     }
-    /**
-   * Log an info message
-   */    info(message, context) {
-        this.config.level < LogLevel.INFO || (this.config.enableConsole && console.info(`[ThemeInfo] ${message}`, context || {}), 
-        this.config.onInfo?.(message, context));
+    // Convert typography
+        // Convert border radius
+    if (theme.typography && (tokens["body-font-family"] = theme.typography.fontFamily, 
+    tokens["body-font-size"] = `${theme.typography.fontSize}px`, tokens["font-weight-normal"] = `${theme.typography.fontWeightRegular}`, 
+    tokens["font-weight-bold"] = `${theme.typography.fontWeightBold}`), 
+    // Convert spacing
+    "function" == typeof theme.spacing && (
+    // If spacing is a function, call it with some values to get results
+    tokens["spacing-1"] = theme.spacing(1), tokens["spacing-2"] = theme.spacing(2), 
+    tokens["spacing-4"] = theme.spacing(4)), 
+    // Convert breakpoints
+    theme.breakpoints?.values && (tokens["breakpoint-xs"] = `${theme.breakpoints.values.xs}px`, 
+    tokens["breakpoint-sm"] = `${theme.breakpoints.values.sm}px`, tokens["breakpoint-md"] = `${theme.breakpoints.values.md}px`, 
+    tokens["breakpoint-lg"] = `${theme.breakpoints.values.lg}px`, tokens["breakpoint-xl"] = `${theme.breakpoints.values.xl}px`), 
+    // Convert shadows
+    theme.shadows && (tokens["box-shadow"] = theme.shadows[2], // Use a moderate shadow
+    tokens["box-shadow-sm"] = theme.shadows[1], tokens["box-shadow-lg"] = theme.shadows[3]), 
+    // Convert transitions
+    theme.transitions && (tokens["transition-duration-base"] = `${theme.transitions.duration.standard}ms`), 
+    // Convert z-index
+    theme.zIndex && (tokens["z-modal"] = `${theme.zIndex.modal}`, tokens["z-popover"] = `${theme.zIndex.popover}`, 
+    tokens["z-tooltip"] = `${theme.zIndex.tooltip}`), theme.borderRadius) {
+        const baseRadius = theme.borderRadius.base;
+        tokens["border-radius"] = "number" == typeof baseRadius ? `${baseRadius}px` : baseRadius;
     }
-    /**
-   * Log a debug message
-   */    debug(message, context) {
-        this.config.level < LogLevel.DEBUG || (this.config.enableConsole, this.config.onDebug?.(message, context));
+    // Add advanced feature tokens if available in theme
+        if (theme.custom) {
+        // Interactive Effects (Phase 2)
+        if (theme.custom.interactiveEffects) {
+            const ie = theme.custom.interactiveEffects;
+            // Vortex effects
+                        ie.vortex && (tokens["interactive-vortex-enabled"] = String(ie.vortex.enabled ?? !1), 
+            tokens["interactive-vortex-strength"] = String(ie.vortex.strength ?? .5), tokens["interactive-vortex-radius"] = String(ie.vortex.radius ?? 100), 
+            tokens["interactive-vortex-decay"] = String(ie.vortex.decay ?? .8)), 
+            // Chromatic aberration
+            ie.chromaticAberration && (tokens["interactive-chromatic-enabled"] = String(ie.chromaticAberration.enabled ?? !1), 
+            tokens["interactive-chromatic-mode"] = ie.chromaticAberration.mode ?? "lateral", 
+            tokens["interactive-chromatic-red-shift"] = String(ie.chromaticAberration.redShift ?? .02), 
+            tokens["interactive-chromatic-green-shift"] = String(ie.chromaticAberration.greenShift ?? 0), 
+            tokens["interactive-chromatic-blue-shift"] = String(ie.chromaticAberration.blueShift ?? -.02), 
+            tokens["interactive-chromatic-edge-only"] = String(ie.chromaticAberration.edgeOnly ?? !1), 
+            tokens["interactive-chromatic-edge-threshold"] = String(ie.chromaticAberration.edgeThreshold ?? .5)), 
+            // Mouse interaction
+            ie.mouseInteraction && (tokens["interactive-mouse-sensitivity"] = String(ie.mouseInteraction.sensitivity ?? 1), 
+            tokens["interactive-mouse-trail-effect"] = String(ie.mouseInteraction.trailEffect ?? !1)), 
+            // Animation speed
+            ie.animationSpeed && (tokens["interactive-animation-speed-base"] = String(ie.animationSpeed.base ?? 1), 
+            tokens["interactive-animation-speed-multiplier"] = String(ie.animationSpeed.timeMultiplier ?? 1));
+        }
+        // Optimization (Phase 3)
+                if (theme.custom.optimization) {
+            const opt = theme.custom.optimization;
+            // Responsive breakpoints
+                        opt.responsive && (opt.responsive.breakpoints && (tokens["optimization-breakpoint-mobile"] = opt.responsive.breakpoints.mobile ?? "0px", 
+            tokens["optimization-breakpoint-tablet"] = opt.responsive.breakpoints.tablet ?? "768px", 
+            tokens["optimization-breakpoint-desktop"] = opt.responsive.breakpoints.desktop ?? "1024px", 
+            tokens["optimization-breakpoint-wide"] = opt.responsive.breakpoints.wide ?? "1440px"), 
+            opt.responsive.deviceScaling && (tokens["optimization-device-scaling-mobile"] = String(opt.responsive.deviceScaling.mobile ?? .5), 
+            tokens["optimization-device-scaling-tablet"] = String(opt.responsive.deviceScaling.tablet ?? .75), 
+            tokens["optimization-device-scaling-desktop"] = String(opt.responsive.deviceScaling.desktop ?? 1))), 
+            // Performance settings
+            opt.performance && (tokens["optimization-performance-fps-target"] = String(opt.performance.fpsTarget ?? 60), 
+            tokens["optimization-auto-scaling-enabled"] = String(opt.performance.autoScaling ?? !1)), 
+            // Auto-scaling settings
+            opt.autoScaling && (tokens["optimization-auto-scaling-enabled"] = String(opt.autoScaling.enabled ?? !1), 
+            tokens["optimization-auto-scaling-low-end"] = String(opt.autoScaling.qualityThresholds?.lowEnd ?? .5), 
+            tokens["optimization-auto-scaling-mid-range"] = String(opt.autoScaling.qualityThresholds?.midRange ?? .75), 
+            tokens["optimization-auto-scaling-high-end"] = String(opt.autoScaling.qualityThresholds?.highEnd ?? 1));
+        }
+        // Visual Polish (Phase 4)
+                if (theme.custom.visualPolish) {
+            const vp = theme.custom.visualPolish;
+            vp.borders && (tokens["visual-polish-border-iridescent-glow"] = String(vp.borders.iridescentGlow ?? !1), 
+            tokens["visual-polish-border-shimmer-effect"] = String(vp.borders.shimmerEffect ?? !1), 
+            tokens["visual-polish-border-beveled-edges"] = String(vp.borders.beveledEdges ?? !1), 
+            tokens["visual-polish-border-pulsing-glow"] = String(vp.borders.pulsingGlow ?? !1)), 
+            vp.contentAwareBlur && (tokens["visual-polish-content-aware-blur-enabled"] = String(vp.contentAwareBlur.enabled ?? !1), 
+            tokens["visual-polish-content-aware-depth-detection"] = String(vp.contentAwareBlur.depthDetection ?? !1), 
+            tokens["visual-polish-content-aware-edge-preservation"] = String(vp.contentAwareBlur.edgePreservation ?? !1), 
+            tokens["visual-polish-content-aware-variable-radius"] = String(vp.contentAwareBlur.variableRadius ?? !1)), 
+            vp.holographicEffects && (tokens["visual-polish-holographic-enabled"] = String(vp.holographicEffects.enabled ?? !1), 
+            tokens["visual-polish-holographic-rainbow-diffraction"] = String(vp.holographicEffects.rainbowDiffraction ?? !1), 
+            tokens["visual-polish-holographic-scanline-animation"] = String(vp.holographicEffects.scanlineAnimation ?? !1), 
+            tokens["visual-polish-holographic-grid-overlay"] = String(vp.holographicEffects.gridOverlay ?? !1), 
+            tokens["visual-polish-holographic-data-stream"] = String(vp.holographicEffects.dataStream ?? !1), 
+            tokens["visual-polish-holographic-pulse-rings"] = String(vp.holographicEffects.pulseRings ?? !1));
+        }
     }
+    // Create full tokens object with defaults
+        return createTokens(tokens);
 }
 
 /**
- * Default logger instance
- */ let defaultLogger = null;
-
-/**
- * Get or create default logger
- */ function getLogger() {
-    return defaultLogger || (defaultLogger = new ThemeLogger), defaultLogger;
-}
-
-/**
- * Core Theme Functions
- *
- * Simplified theme system using DesignTokens only.
- * Config-first approach: loads from atomix.config.ts when no input is provided.
- */
-/**
- * Create theme CSS from DesignTokens
+ * Converts an AtomixConfig to DesignTokens
  *
- * **Config-First Approach**: If no input is provided, loads from `atomix.config.ts`.
+ * This function maps the configuration from the user-facing format
+ * to the internal DesignTokens format used by the theme system.
  *
- * @param input - DesignTokens (partial) or undefined (loads from config)
- * @param options - CSS generation options (prefix is automatically read from config if not provided)
- * @returns CSS string with custom properties
- * @throws Error if config loading fails when no input is provided
+ * @param config - The configuration object to convert
+ * @returns DesignTokens object ready for theme generation
  *
  * @example
  * ```typescript
- * // Loads from atomix.config.ts
- * const css = createTheme();
- *
- * // Using DesignTokens
- * const css = createTheme({
- *   'primary': '#7c3aed',
- *   'spacing-4': '1rem',
- * });
+ * import { configToTokens } from '@shohojdhara/atomix/theme';
  *
- * // With custom options
- * const css = createTheme(undefined, { prefix: 'myapp', selector: ':root' });
+ * const config = {
+ *   prefix: 'myapp',
+ *   theme: { extend: { colors: { primary: { main: '#7AFFD7' } } } }
+ * };
+ * const tokens = configToTokens(config);
  * ```
- */ function createTheme(input, options) {
-    // Validate options if provided
-    if (options?.prefix) {
-        const prefixPattern = /^[a-z][a-z0-9-]*$/;
-        if (!prefixPattern.test(options.prefix)) throw new ThemeError(`Invalid CSS variable prefix: "${options.prefix}". Prefix must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens (e.g., "atomix", "my-app").`, ThemeErrorCode.THEME_VALIDATION_FAILED, {
-            prefix: options.prefix,
-            pattern: prefixPattern.toString()
-        });
-    }
-    // Validate selector if provided
-        if (options?.selector && ("string" != typeof options.selector || 0 === options.selector.trim().length)) throw new ThemeError(`Invalid CSS selector: "${options.selector}". Selector must be a non-empty string (e.g., ":root", ".my-theme").`, ThemeErrorCode.THEME_VALIDATION_FAILED, {
-        selector: options.selector
-    });
-    // Determine tokens based on input
-        let tokens;
-    if (input) {
-        // Validate input tokens structure
-        if ("object" != typeof input || null === input || Array.isArray(input)) throw new ThemeError(`Invalid tokens input. Expected an object with DesignTokens, but received: ${typeof input}.`, ThemeErrorCode.THEME_VALIDATION_FAILED, {
-            inputType: typeof input
-        });
-        // Use DesignTokens directly
-                tokens = input;
-    }
-    // Merge with defaults and generate CSS
-     else 
-    // Auto-loading config from file system is removed for browser compatibility.
-    // If no input is provided, we return an empty theme (using defaults only) or user must provide tokens.
-    // This allows createTheme to be isomorphic.
-    // Warn in development if no input provided
-    "production" !== process.env.NODE_ENV && "undefined" != typeof window && console.warn("Atomix: createTheme() called without tokens. Using default tokens only."), 
-    tokens = {};
-    const allTokens = createTokens(tokens), prefix = options?.prefix ?? "atomix";
-    // Get prefix from options or use default
-        return generateCSSVariables$1(allTokens, {
-        ...options,
-        prefix: prefix
-    });
-}
-
-/**
- * Theme Composition Utilities
- *
- * Simplified utilities for composing and merging DesignTokens.
- */
-// ============================================================================
-// Deep Merge Utility
-// ============================================================================
-/**
- * Check if value is an object
- */ function isObject$6(item) {
-    return item && "object" == typeof item && !Array.isArray(item) && "function" != typeof item;
-}
-
-/**
- * Deep merge multiple objects
- * Later objects override earlier ones
- */ function deepMerge(...objects) {
-    if (0 === objects.length) return {};
-    if (1 === objects.length) return objects[0];
-    const [target, ...sources] = objects, result = {
-        ...target
+ */ function configToTokens(config) {
+    const prefix = config.prefix || "atomix", theme = config.theme || {};
+    // Start with default tokens
+    let tokens = {
+        ...defaultTokens
     };
-    for (const source of sources) if (source) for (const key in source) {
-        if (!Object.prototype.hasOwnProperty.call(source, key)) continue;
-        const targetValue = result[key], sourceValue = source[key];
-        isObject$6(targetValue) && isObject$6(sourceValue) ? 
-        // Recursively merge objects
-        result[key] = deepMerge(targetValue, sourceValue) : 
-        // Override with source value
-        result[key] = sourceValue;
+    // Apply theme extensions
+        // Apply advanced features if available in config
+    if (theme.extend && 
+    // Apply extensions to tokens
+    Object.entries(theme.extend).forEach((([category, values]) => {
+        "object" == typeof values && null !== values && Object.entries(values).forEach((([key, value]) => {
+            // Map theme categories to token names
+            const tokenName = `${category}-${key}`;
+            "string" == typeof value || "number" == typeof value ? tokens[tokenName] = String(value) : "object" == typeof value && null !== value && 
+            // Handle nested objects like color scales
+            Object.entries(value).forEach((([nestedKey, nestedValue]) => {
+                "string" != typeof nestedValue && "number" != typeof nestedValue || (tokens[`${tokenName}-${nestedKey}`] = String(nestedValue));
+            }));
+        }));
+    })), 
+    // Apply theme tokens if provided (completely replacing defaults)
+    theme.tokens && (tokens = {
+        ...tokens,
+        ...theme.tokens
+    }), config) {
+        // Interactive Effects (Phase 2)
+        if (config.interactiveEffects) {
+            const ie = config.interactiveEffects;
+            // Vortex effects
+                        ie.vortex && (tokens["interactive-vortex-enabled"] = String(ie.vortex.enabled ?? !1), 
+            tokens["interactive-vortex-strength"] = String(ie.vortex.strength ?? .5), tokens["interactive-vortex-radius"] = String(ie.vortex.radius ?? 100), 
+            tokens["interactive-vortex-decay"] = String(ie.vortex.decay ?? .8), tokens["interactive-vortex-curl-noise"] = String(ie.vortex.curlNoise ?? !1), 
+            tokens["interactive-vortex-velocity-tracking"] = String(ie.vortex.velocityTracking ?? !1)), 
+            // Chromatic aberration
+            ie.chromaticAberration && (tokens["interactive-chromatic-enabled"] = String(ie.chromaticAberration.enabled ?? !1), 
+            tokens["interactive-chromatic-mode"] = ie.chromaticAberration.mode ?? "lateral", 
+            tokens["interactive-chromatic-red-shift"] = String(ie.chromaticAberration.redShift ?? .02), 
+            tokens["interactive-chromatic-green-shift"] = String(ie.chromaticAberration.greenShift ?? 0), 
+            tokens["interactive-chromatic-blue-shift"] = String(ie.chromaticAberration.blueShift ?? -.02), 
+            tokens["interactive-chromatic-edge-only"] = String(ie.chromaticAberration.edgeOnly ?? !1), 
+            tokens["interactive-chromatic-edge-threshold"] = String(ie.chromaticAberration.edgeThreshold ?? .5)), 
+            // Mouse interaction
+            ie.mouseInteraction && (tokens["interactive-mouse-sensitivity"] = String(ie.mouseInteraction.sensitivity ?? 1), 
+            tokens["interactive-mouse-trail-effect"] = String(ie.mouseInteraction.trailEffect ?? !1), 
+            tokens["interactive-mouse-pressure-sensitivity"] = String(ie.mouseInteraction.pressureSensitivity ?? !1)), 
+            // Animation speed
+            ie.animationSpeed && (tokens["interactive-animation-speed-base"] = String(ie.animationSpeed.base ?? 1), 
+            tokens["interactive-animation-speed-multiplier"] = String(ie.animationSpeed.timeMultiplier ?? 1));
+        }
+        // Optimization (Phase 3)
+                if (config.optimization) {
+            const opt = config.optimization;
+            // Responsive breakpoints
+                        opt.responsive && (opt.responsive.breakpoints && (tokens["optimization-breakpoint-mobile"] = opt.responsive.breakpoints.mobile ?? "0px", 
+            tokens["optimization-breakpoint-tablet"] = opt.responsive.breakpoints.tablet ?? "768px", 
+            tokens["optimization-breakpoint-desktop"] = opt.responsive.breakpoints.desktop ?? "1024px", 
+            tokens["optimization-breakpoint-wide"] = opt.responsive.breakpoints.wide ?? "1440px"), 
+            opt.responsive.deviceScaling && (tokens["optimization-device-scaling-mobile"] = String(opt.responsive.deviceScaling.mobile ?? .5), 
+            tokens["optimization-device-scaling-tablet"] = String(opt.responsive.deviceScaling.tablet ?? .75), 
+            tokens["optimization-device-scaling-desktop"] = String(opt.responsive.deviceScaling.desktop ?? 1))), 
+            // Performance settings
+            opt.performance && (tokens["optimization-performance-fps-target"] = String(opt.performance.fpsTarget ?? 60), 
+            tokens["optimization-auto-scaling-enabled"] = String(opt.performance.autoScaling ?? !1), 
+            tokens["optimization-monitor-dashboard-enabled"] = String(opt.performance.monitorDashboard ?? !1)), 
+            // Auto-scaling settings
+            opt.autoScaling && (tokens["optimization-auto-scaling-enabled"] = String(opt.autoScaling.enabled ?? !1), 
+            tokens["optimization-auto-scaling-low-end"] = String(opt.autoScaling.qualityThresholds?.lowEnd ?? .5), 
+            tokens["optimization-auto-scaling-mid-range"] = String(opt.autoScaling.qualityThresholds?.midRange ?? .75), 
+            tokens["optimization-auto-scaling-high-end"] = String(opt.autoScaling.qualityThresholds?.highEnd ?? 1));
+        }
+        // Visual Polish (Phase 4)
+                if (config.visualPolish) {
+            const vp = config.visualPolish;
+            vp.borders && (tokens["visual-polish-border-iridescent-glow"] = String(vp.borders.iridescentGlow ?? !1), 
+            tokens["visual-polish-border-shimmer-effect"] = String(vp.borders.shimmerEffect ?? !1), 
+            tokens["visual-polish-border-beveled-edges"] = String(vp.borders.beveledEdges ?? !1), 
+            tokens["visual-polish-border-pulsing-glow"] = String(vp.borders.pulsingGlow ?? !1)), 
+            vp.contentAwareBlur && (tokens["visual-polish-content-aware-blur-enabled"] = String(vp.contentAwareBlur.enabled ?? !1), 
+            tokens["visual-polish-content-aware-depth-detection"] = String(vp.contentAwareBlur.depthDetection ?? !1), 
+            tokens["visual-polish-content-aware-edge-preservation"] = String(vp.contentAwareBlur.edgePreservation ?? !1), 
+            tokens["visual-polish-content-aware-variable-radius"] = String(vp.contentAwareBlur.variableRadius ?? !1)), 
+            vp.holographicEffects && (tokens["visual-polish-holographic-enabled"] = String(vp.holographicEffects.enabled ?? !1), 
+            tokens["visual-polish-holographic-rainbow-diffraction"] = String(vp.holographicEffects.rainbowDiffraction ?? !1), 
+            tokens["visual-polish-holographic-scanline-animation"] = String(vp.holographicEffects.scanlineAnimation ?? !1), 
+            tokens["visual-polish-holographic-grid-overlay"] = String(vp.holographicEffects.gridOverlay ?? !1), 
+            tokens["visual-polish-holographic-data-stream"] = String(vp.holographicEffects.dataStream ?? !1), 
+            tokens["visual-polish-holographic-pulse-rings"] = String(vp.holographicEffects.pulseRings ?? !1));
+        }
     }
-    return result;
+    // Apply prefix to all tokens
+        const prefixedTokens = {};
+    return Object.entries(tokens).forEach((([key, value]) => {
+        // If the token key already starts with the prefix, use as-is
+        // Otherwise, add the prefix
+        const prefixedKey = key.startsWith(prefix) ? key : `${prefix}-${key}`;
+        prefixedTokens[prefixedKey] = value;
+    })), prefixedTokens;
 }
 
 /**
- * Merge multiple DesignTokens objects into a single DesignTokens object
- *
- * @param tokens - DesignTokens objects to merge
- * @returns Merged DesignTokens object
- *
- * @example
- * ```typescript
- * const baseTokens = { 'primary': '#000', 'spacing-4': '1rem' };
- * const customTokens = { 'secondary': '#fff', 'spacing-4': '1.5rem' };
- * const merged = mergeTheme(baseTokens, customTokens);
- * // Returns: { 'primary': '#000', 'secondary': '#fff', 'spacing-4': '1.5rem' }
- * ```
- */ function mergeTheme(...tokens) {
-    return deepMerge({}, ...tokens);
+ * Convert hex color to RGB
+ */ function hexToRgb$2(hex) {
+    hex = hex.replace(/^#?([a-f\d])([a-f\d])([a-f\d])$/i, ((m, r, g, b) => r + r + g + g + b + b));
+    const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+    return result && result[1] && result[2] && result[3] ? `${parseInt(result[1], 16)}, ${parseInt(result[2], 16)}, ${parseInt(result[3], 16)}` : "0, 0, 0";
 }
 
 /**
- * Extend DesignTokens with additional tokens
- *
- * @param baseTokens - Base DesignTokens to extend
- * @param extension - Additional DesignTokens to merge
- * @returns Extended DesignTokens object
+ * Converts DesignTokens to CSS variables
  *
- * @example
- * ```typescript
- * const base = { 'primary': '#000' };
- * const extended = extendTheme(base, { 'secondary': '#fff' });
- * // Returns: { 'primary': '#000', 'secondary': '#fff' }
- * ```
- */ function extendTheme(baseTokens, extension) {
-    return mergeTheme(baseTokens, extension);
-}
-
-/**
- * Create a new theme registry
- */ function createThemeRegistry() {
-    return {};
+ * @param tokens - The tokens to convert
+ * @returns A record of CSS variable names and values
+ */ function designTokensToCSSVars(tokens) {
+    const cssVars = {};
+    return Object.entries(tokens).forEach((([key, value]) => {
+        void 0 !== value && (cssVars[`--atomix-${key}`] = String(value));
+    })), cssVars;
 }
 
-/**
- * Register a theme
- * @param registry - Theme registry object
- * @param id - Theme identifier
- * @param metadata - Theme metadata
- */ function registerTheme(registry, id, metadata) {
-    registry[id] = metadata;
-}
+var commonjsGlobal = "undefined" != typeof globalThis ? globalThis : "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof self ? self : {};
 
-/**
- * Unregister a theme
- * @param registry - Theme registry object
- * @param id - Theme identifier
- */ function unregisterTheme(registry, id) {
-    const exists = id in registry;
-    return delete registry[id], exists;
-}
-
-/**
- * Check if a theme is registered
- * @param registry - Theme registry object
- * @param id - Theme identifier
- */ function hasTheme(registry, id) {
-    return id in registry;
-}
-
-/**
- * Get theme metadata
- * @param registry - Theme registry object
- * @param id - Theme identifier
- */ function getTheme(registry, id) {
-    return registry[id];
-}
-
-/**
- * Get all registered theme metadata
- * @param registry - Theme registry object
- */ function getAllThemes(registry) {
-    return Object.values(registry);
-}
-
-/**
- * Get all registered theme IDs
- * @param registry - Theme registry object
- */ function getThemeIds(registry) {
-    return Object.keys(registry);
-}
-
-/**
- * Clear all registered themes
- * @param registry - Theme registry object
- */ function clearThemes(registry) {
-    Object.keys(registry).forEach((key => delete registry[key]));
-}
-
-/**
- * Get the number of registered themes
- * @param registry - Theme registry object
- */ function getThemeCount(registry) {
-    return Object.keys(registry).length;
-}
-
-/**
- * CSS Injection Utilities
- *
- * Inject CSS into HTML head via <style> element.
- */
-/**
- * Check if running in browser environment
- */ function isBrowser$1() {
-    return "undefined" != typeof document;
-}
-
-/**
- * Inject CSS into HTML head via <style> element
- *
- * Creates or updates a style element in the document head.
- * If an element with the same ID exists, it will be updated.
- *
- * @param css - CSS string to inject
- * @param id - Style element ID (default: 'atomix-theme')
- *
- * @example
- * ```typescript
- * const css = ':root { --atomix-color-primary: #7AFFD7; }';
- * injectCSS(css);
- *
- * // With custom ID
- * injectCSS(css, 'my-custom-theme');
- * ```
- */ function injectCSS$1(css, id = "atomix-theme") {
-    if (!isBrowser$1()) return;
-    let styleElement = document.getElementById(id);
-    styleElement || (styleElement = document.createElement("style"), styleElement.id = id, 
-    styleElement.setAttribute("data-atomix-theme", "true"), document.head.appendChild(styleElement)), 
-    styleElement.textContent = css;
-}
-
-/**
- * Remove injected CSS from DOM
- *
- * Removes the style element with the given ID from the document head.
- *
- * @param id - Style element ID to remove (default: 'atomix-theme')
- *
- * @example
- * ```typescript
- * removeCSS(); // Removes default 'atomix-theme'
- * removeCSS('my-custom-theme'); // Removes custom ID
- * ```
- */ function removeCSS(id = "atomix-theme") {
-    if (!isBrowser$1()) return;
-    const styleElement = document.getElementById(id);
-    styleElement && styleElement.remove();
-}
-
-/**
- * Check if CSS is already injected
- *
- * @param id - Style element ID to check (default: 'atomix-theme')
- * @returns True if style element exists
- */ function isCSSInjected(id = "atomix-theme") {
-    return !!isBrowser$1() && null !== document.getElementById(id);
-}
-
-var commonjsGlobal = "undefined" != typeof globalThis ? globalThis : "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof self ? self : {};
-
-function getDefaultExportFromCjs(x) {
-    return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, "default") ? x.default : x;
+function getDefaultExportFromCjs(x) {
+    return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, "default") ? x.default : x;
 }
 
 var fails$9 = function(exec) {
@@ -862,7 +772,7 @@ var match, version, createPropertyDescriptor$2 = function(bitmap, value) {
     return it;
 }, IndexedObject$1 = indexedObject, requireObjectCoercible$2 = requireObjectCoercible$3, toIndexedObject$2 = function(it) {
     return IndexedObject$1(requireObjectCoercible$2(it));
-}, isCallable$7 = isCallable$8, isObject$5 = function(it) {
+}, isCallable$7 = isCallable$8, isObject$6 = function(it) {
     return "object" == typeof it ? null !== it : isCallable$7(it);
 }, path$3 = {}, path$2 = path$3, globalThis$b = globalThis_1, isCallable$6 = isCallable$8, aFunction = function(variable) {
     return isCallable$6(variable) ? variable : void 0;
@@ -901,7 +811,7 @@ var environmentV8Version = version, V8_VERSION = environmentV8Version, fails$5 =
             return "Object";
         }
     }(argument) + " is not a function");
-}, aCallable$2 = aCallable$3, isNullOrUndefined = isNullOrUndefined$2, call$2 = functionCall, isCallable$3 = isCallable$8, isObject$4 = isObject$5, $TypeError$5 = TypeError, sharedStore = {
+}, aCallable$2 = aCallable$3, isNullOrUndefined = isNullOrUndefined$2, call$2 = functionCall, isCallable$3 = isCallable$8, isObject$5 = isObject$6, $TypeError$5 = TypeError, sharedStore = {
     exports: {}
 }, globalThis$7 = globalThis_1, defineProperty = Object.defineProperty, globalThis$6 = globalThis_1, store$1 = sharedStore.exports = globalThis$6["__core-js_shared__"] || function(key, value) {
     try {
@@ -933,25 +843,25 @@ var key, value, store = sharedStore.exports, requireObjectCoercible$1 = requireO
 }, wellKnownSymbol$5 = function(name) {
     return hasOwn$2(WellKnownSymbolsStore, name) || (WellKnownSymbolsStore[name] = NATIVE_SYMBOL && hasOwn$2(Symbol$1, name) ? Symbol$1[name] : createWellKnownSymbol("Symbol." + name)), 
     WellKnownSymbolsStore[name];
-}, call$1 = functionCall, isObject$3 = isObject$5, isSymbol$1 = isSymbol$2, $TypeError$4 = TypeError, TO_PRIMITIVE = wellKnownSymbol$5("toPrimitive"), toPrimitive = function(input, pref) {
-    if (!isObject$3(input) || isSymbol$1(input)) return input;
+}, call$1 = functionCall, isObject$4 = isObject$6, isSymbol$1 = isSymbol$2, $TypeError$4 = TypeError, TO_PRIMITIVE = wellKnownSymbol$5("toPrimitive"), toPrimitive = function(input, pref) {
+    if (!isObject$4(input) || isSymbol$1(input)) return input;
     var result, func, exoticToPrim = (func = input[TO_PRIMITIVE], isNullOrUndefined(func) ? void 0 : aCallable$2(func));
     if (exoticToPrim) {
         if (void 0 === pref && (pref = "default"), result = call$1(exoticToPrim, input, pref), 
-        !isObject$3(result) || isSymbol$1(result)) return result;
+        !isObject$4(result) || isSymbol$1(result)) return result;
         throw new $TypeError$4("Can't convert object to primitive value");
     }
     return void 0 === pref && (pref = "number"), function(input, pref) {
         var fn, val;
-        if ("string" === pref && isCallable$3(fn = input.toString) && !isObject$4(val = call$2(fn, input))) return val;
-        if (isCallable$3(fn = input.valueOf) && !isObject$4(val = call$2(fn, input))) return val;
-        if ("string" !== pref && isCallable$3(fn = input.toString) && !isObject$4(val = call$2(fn, input))) return val;
+        if ("string" === pref && isCallable$3(fn = input.toString) && !isObject$5(val = call$2(fn, input))) return val;
+        if (isCallable$3(fn = input.valueOf) && !isObject$5(val = call$2(fn, input))) return val;
+        if ("string" !== pref && isCallable$3(fn = input.toString) && !isObject$5(val = call$2(fn, input))) return val;
         throw new $TypeError$5("Can't convert object to primitive value");
     }(input, pref);
 }, isSymbol = isSymbol$2, toPropertyKey$2 = function(argument) {
     var key = toPrimitive(argument, "string");
     return isSymbol(key) ? key : key + "";
-}, isObject$2 = isObject$5, document$1 = globalThis_1.document, EXISTS = isObject$2(document$1) && isObject$2(document$1.createElement), ie8DomDefine = !descriptors && !fails$9((function() {
+}, isObject$3 = isObject$6, document$1 = globalThis_1.document, EXISTS = isObject$3(document$1) && isObject$3(document$1.createElement), ie8DomDefine = !descriptors && !fails$9((function() {
     // eslint-disable-next-line es/no-object-defineproperty -- required for testing
     return 7 !== Object.defineProperty((it = "div", EXISTS ? document$1.createElement(it) : {}), "a", {
         get: function() {
@@ -981,8 +891,8 @@ var fails$3 = fails$9, isCallable$2 = isCallable$8, replacement = /#|\.prototype
         value: 42,
         writable: !1
     }).prototype;
-})), isObject$1 = isObject$5, $String$1 = String, $TypeError$3 = TypeError, DESCRIPTORS$1 = descriptors, IE8_DOM_DEFINE = ie8DomDefine, V8_PROTOTYPE_DEFINE_BUG = v8PrototypeDefineBug, anObject = function(argument) {
-    if (isObject$1(argument)) return argument;
+})), isObject$2 = isObject$6, $String$1 = String, $TypeError$3 = TypeError, DESCRIPTORS$1 = descriptors, IE8_DOM_DEFINE = ie8DomDefine, V8_PROTOTYPE_DEFINE_BUG = v8PrototypeDefineBug, anObject = function(argument) {
+    if (isObject$2(argument)) return argument;
     throw new $TypeError$3($String$1(argument) + " is not an object");
 }, toPropertyKey = toPropertyKey$2, $TypeError$2 = TypeError, $defineProperty = Object.defineProperty, $getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
 
@@ -1099,7 +1009,7 @@ var globalThis$2 = globalThis_1, path = path$3, getBuiltInPrototypeMethod$3 = fu
     if (pureMethod) return pureMethod;
     var NativeConstructor = globalThis$2[CONSTRUCTOR], NativePrototype = NativeConstructor && NativeConstructor.prototype;
     return NativePrototype && NativePrototype[METHOD];
-}, includes$4 = getBuiltInPrototypeMethod$3("Array", "includes"), isObject = isObject$5, classof$3 = classofRaw$2, MATCH$1 = wellKnownSymbol$5("match"), $TypeError$1 = TypeError, test = {};
+}, includes$4 = getBuiltInPrototypeMethod$3("Array", "includes"), isObject$1 = isObject$6, classof$3 = classofRaw$2, MATCH$1 = wellKnownSymbol$5("match"), $TypeError$1 = TypeError, test = {};
 
 test[wellKnownSymbol$5("toStringTag")] = "z";
 
@@ -1115,7 +1025,7 @@ var TO_STRING_TAG_SUPPORT = "[object z]" === String(test), isCallable = isCallab
 }, $String = String, MATCH = wellKnownSymbol$5("match"), $$1 = _export, notARegExp = function(it) {
     if (function(it) {
         var isRegExp;
-        return isObject(it) && (void 0 !== (isRegExp = it[MATCH$1]) ? !!isRegExp : "RegExp" === classof$3(it));
+        return isObject$1(it) && (void 0 !== (isRegExp = it[MATCH$1]) ? !!isRegExp : "RegExp" === classof$3(it));
     }(it)) throw new $TypeError$1("The method doesn't accept regular expressions");
     return it;
 }, requireObjectCoercible = requireObjectCoercible$3, toString = function(argument) {
@@ -1153,18 +1063,595 @@ const _includesInstanceProperty =  getDefaultExportFromCjs((function(it) {
 }));
 
 /**
- * Theme System Constants
- *
- * Centralized constants for the theme system to avoid magic numbers and strings.
- */
-/**
- * Default storage key for theme persistence
- */ "undefined" != typeof process && process.env;
+ * Load theme from config file (synchronous, Node.js only)
+ * @param configPath - Path to config file (default: atomix.config.ts)
+ * @returns DesignTokens from theme configuration
+ * @throws Error if config loading is not available in browser environment
+ */
+/**
+ * Helper function to load config from a specific path
+ */
+function loadConfigAtPath(path, required, defaultConfig) {
+    try {
+        // Use dynamic import for ESM compatibility
+        const configModule = require(path), config = configModule.default || configModule;
+        // Validate it's an AtomixConfig
+        if (config && "object" == typeof config) return config;
+        throw new Error("Invalid config format");
+    } catch (error) {
+        if (required) throw new Error(`Failed to load config from ${path}: ${error.message}`);
+        // Return default config if not required
+                return defaultConfig;
+    }
+}
+
+/**
+ * Core Theme Functions
+ *
+ * Unified theme system that handles both DesignTokens and Theme objects.
+ * Config-first approach: loads from atomix.config.ts when no input is provided.
+ * Config-first approach: loads advanced features from config when available.
+ */
+/**
+ * Create theme CSS from tokens or Theme object
+ *
+ * **Config-First Approach**: If no input is provided, loads from `atomix.config.ts`.
+ * Config file is required for automatic loading.
+ *
+ * @param input - DesignTokens (partial), Theme object, or undefined (loads from config)
+ * @param options - CSS generation options (prefix is automatically read from config if not provided)
+ * @returns CSS string with custom properties
+ * @throws Error if config loading fails when no input is provided
+ *
+ * @example
+ * ```typescript
+ * // Loads from atomix.config.ts (config file required)
+ * const css = createTheme();
+ *
+ * // Using DesignTokens
+ * const css = createTheme({
+ *   'primary': '#7c3aed',
+ *   'spacing-4': '1rem',
+ * });
+ *
+ * // Using Theme object
+ * const theme = createThemeObject({ palette: { primary: { main: '#7c3aed' } } });
+ * const css = createTheme(theme);
+ *
+ * // With custom options
+ * const css = createTheme(undefined, { prefix: 'myapp', selector: ':root' });
+ * ```
+ */ function createTheme(input, options) {
+    let tokens, configPrefix;
+    // If no input provided, load from config (required)
+    if (input) 
+    // Convert Theme object to DesignTokens
+    tokens = !0 === input.__isJSTheme || input.palette && input.typography ? themeToDesignTokens(input) : input; else {
+        const configTokens = function() {
+            // Check if we're in a browser environment
+            if ("undefined" != typeof window) throw new Error("loadThemeFromConfigSync: Not available in browser environment. Config loading requires Node.js/SSR environment.");
+            // Use dynamic import to load the config loader
+            // This allows bundlers to handle external dependencies properly
+                        let loadAtomixConfig;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const {loadAtomixConfig: loader} = require("../../config/loader");
+                loadAtomixConfig = loader;
+            } catch (error) {
+                throw new Error("Config loader module not available");
+            }
+            const config = loadAtomixConfig({
+                configPath: undefined,
+                required: !0
+            });
+            if (!config?.theme) return createTokens({});
+            if ((obj = config.theme) && "object" == typeof obj && (obj.palette || obj.typography || obj.spacing || obj.breakpoints || obj.colors)) return themeToDesignTokens(config.theme);
+            // Handle the config.theme object which has extend/tokens/themes properties
+            // Extract the actual tokens from the theme configuration
+                        // Helper type guard function
+            var obj;
+            /**
+ * Load Atomix configuration from project root
+ *
+ * Attempts to load atomix.config.ts, atomix.config.js, or atomix.config.json from the current working directory.
+ * Falls back to default config if file doesn't exist.
+ *
+ * @param options - Loader options
+ * @returns Loaded configuration or default
+ *
+ * @example
+ * ```typescript
+ * import { loadAtomixConfig } from '@shohojdhara/atomix/config';
+ * import { createTheme } from '@shohojdhara/atomix/theme';
+ *
+ * const config = loadAtomixConfig();
+ * const theme = createTheme(config.theme?.tokens || {});
+ * ```
+ */            const themeConfig = config.theme;
+            let tokensToApply = {};
+            return themeConfig.tokens ? 
+            // If tokens is provided, use it as the base
+            tokensToApply = themeConfig.tokens : themeConfig.extend && (
+            // If only extend is provided, use it as overrides
+            tokensToApply = themeConfig.extend), 
+            // Apply advanced feature configurations as tokens
+            config.interactiveEffects && (
+            // Vortex effects
+            config.interactiveEffects.vortex && (tokensToApply = {
+                ...tokensToApply,
+                "interactive-vortex-enabled": String(config.interactiveEffects.vortex.enabled ?? !1),
+                "interactive-vortex-strength": String(config.interactiveEffects.vortex.strength ?? .5),
+                "interactive-vortex-radius": String(config.interactiveEffects.vortex.radius ?? 100),
+                "interactive-vortex-decay": String(config.interactiveEffects.vortex.decay ?? .8)
+            }), 
+            // Chromatic aberration
+            config.interactiveEffects.chromaticAberration && (tokensToApply = {
+                ...tokensToApply,
+                "interactive-chromatic-enabled": String(config.interactiveEffects.chromaticAberration.enabled ?? !1),
+                "interactive-chromatic-mode": config.interactiveEffects.chromaticAberration.mode ?? "lateral",
+                "interactive-chromatic-red-shift": String(config.interactiveEffects.chromaticAberration.redShift ?? .02),
+                "interactive-chromatic-green-shift": String(config.interactiveEffects.chromaticAberration.greenShift ?? 0),
+                "interactive-chromatic-blue-shift": String(config.interactiveEffects.chromaticAberration.blueShift ?? -.02),
+                "interactive-chromatic-edge-only": String(config.interactiveEffects.chromaticAberration.edgeOnly ?? !1),
+                "interactive-chromatic-edge-threshold": String(config.interactiveEffects.chromaticAberration.edgeThreshold ?? .5)
+            }), 
+            // Mouse interaction
+            config.interactiveEffects.mouseInteraction && (tokensToApply = {
+                ...tokensToApply,
+                "interactive-mouse-sensitivity": String(config.interactiveEffects.mouseInteraction.sensitivity ?? 1),
+                "interactive-mouse-trail-effect": String(config.interactiveEffects.mouseInteraction.trailEffect ?? !1)
+            }), 
+            // Animation speed
+            config.interactiveEffects.animationSpeed && (tokensToApply = {
+                ...tokensToApply,
+                "interactive-animation-speed-base": String(config.interactiveEffects.animationSpeed.base ?? 1),
+                "interactive-animation-speed-multiplier": String(config.interactiveEffects.animationSpeed.timeMultiplier ?? 1)
+            })), 
+            // Apply optimization configurations as tokens
+            config.optimization && (
+            // Responsive breakpoints
+            config.optimization.responsive && (config.optimization.responsive.breakpoints && (tokensToApply = {
+                ...tokensToApply,
+                "optimization-breakpoint-mobile": config.optimization.responsive.breakpoints.mobile ?? "0px",
+                "optimization-breakpoint-tablet": config.optimization.responsive.breakpoints.tablet ?? "768px",
+                "optimization-breakpoint-desktop": config.optimization.responsive.breakpoints.desktop ?? "1024px",
+                "optimization-breakpoint-wide": config.optimization.responsive.breakpoints.wide ?? "1440px"
+            }), config.optimization.responsive.deviceScaling && (tokensToApply = {
+                ...tokensToApply,
+                "optimization-device-scaling-mobile": String(config.optimization.responsive.deviceScaling.mobile ?? .5),
+                "optimization-device-scaling-tablet": String(config.optimization.responsive.deviceScaling.tablet ?? .75),
+                "optimization-device-scaling-desktop": String(config.optimization.responsive.deviceScaling.desktop ?? 1)
+            })), 
+            // Performance settings
+            config.optimization.performance && (tokensToApply = {
+                ...tokensToApply,
+                "optimization-performance-fps-target": String(config.optimization.performance.fpsTarget ?? 60),
+                "optimization-auto-scaling-enabled": String(config.optimization.performance.autoScaling ?? !1)
+            }), 
+            // Auto-scaling settings
+            config.optimization.autoScaling && (tokensToApply = {
+                ...tokensToApply,
+                "optimization-auto-scaling-enabled": String(config.optimization.autoScaling.enabled ?? !1),
+                "optimization-auto-scaling-low-end": String(config.optimization.autoScaling.qualityThresholds?.lowEnd ?? .5),
+                "optimization-auto-scaling-mid-range": String(config.optimization.autoScaling.qualityThresholds?.midRange ?? .75),
+                "optimization-auto-scaling-high-end": String(config.optimization.autoScaling.qualityThresholds?.highEnd ?? 1)
+            })), 
+            // Apply visual polish configurations as tokens
+            config.visualPolish && (config.visualPolish.borders && (tokensToApply = {
+                ...tokensToApply,
+                "visual-polish-border-iridescent-glow": String(config.visualPolish.borders.iridescentGlow ?? !1),
+                "visual-polish-border-shimmer-effect": String(config.visualPolish.borders.shimmerEffect ?? !1),
+                "visual-polish-border-beveled-edges": String(config.visualPolish.borders.beveledEdges ?? !1),
+                "visual-polish-border-pulsing-glow": String(config.visualPolish.borders.pulsingGlow ?? !1)
+            }), config.visualPolish.contentAwareBlur && (tokensToApply = {
+                ...tokensToApply,
+                "visual-polish-content-aware-blur-enabled": String(config.visualPolish.contentAwareBlur.enabled ?? !1),
+                "visual-polish-content-aware-depth-detection": String(config.visualPolish.contentAwareBlur.depthDetection ?? !1),
+                "visual-polish-content-aware-edge-preservation": String(config.visualPolish.contentAwareBlur.edgePreservation ?? !1),
+                "visual-polish-content-aware-variable-radius": String(config.visualPolish.contentAwareBlur.variableRadius ?? !1)
+            }), config.visualPolish.holographicEffects && (tokensToApply = {
+                ...tokensToApply,
+                "visual-polish-holographic-enabled": String(config.visualPolish.holographicEffects.enabled ?? !1),
+                "visual-polish-holographic-rainbow-diffraction": String(config.visualPolish.holographicEffects.rainbowDiffraction ?? !1),
+                "visual-polish-holographic-scanline-animation": String(config.visualPolish.holographicEffects.scanlineAnimation ?? !1),
+                "visual-polish-holographic-grid-overlay": String(config.visualPolish.holographicEffects.gridOverlay ?? !1),
+                "visual-polish-holographic-data-stream": String(config.visualPolish.holographicEffects.dataStream ?? !1),
+                "visual-polish-holographic-pulse-rings": String(config.visualPolish.holographicEffects.pulseRings ?? !1)
+            })), createTokens(tokensToApply);
+        }();
+        // Get prefix from config
+                try {
+            // Use the imported function directly instead of require to avoid bundling issues
+            const config = function(options = {}) {
+                const {configPath: configPath, required: required = !1} = options, defaultConfig = {
+                    prefix: "atomix",
+                    theme: {
+                        extend: {}
+                    }
+                };
+                // Default config
+                                // In browser environments, config loading is not supported
+                if ("undefined" != typeof window) {
+                    if (required) throw new Error('Config loading requires Node.js file system access.\n\nSolutions:\n1. Provide tokens explicitly to createTheme():\n   const css = createTheme({ "--brand-primary": "#6366f1" });\n\n2. Use SSR framework (Next.js, Remix, Astro)\n\n3. Load config on server and pass to client\n\nSee examples/config-examples/browser-only.config.ts');
+                    return defaultConfig;
+                }
+                // If a specific config path is provided, try to load it directly
+                                if (configPath) return loadConfigAtPath(configPath, required, defaultConfig);
+                // Otherwise, try standard locations in order of preference
+                                const possiblePaths = [ "atomix.config.ts", "atomix.config.js", "atomix.config.json" ];
+                for (const path of possiblePaths) {
+                    const config = loadConfigAtPath(path, !1, defaultConfig);
+                    // If we found a valid config, return it
+                                        if (JSON.stringify(config) !== JSON.stringify(defaultConfig)) return config;
+                }
+                // If no config file was found or all contained only defaults, return default config
+                                if (required) throw new Error('No Atomix configuration file found in project root.\n\nExpected one of:\n  - atomix.config.ts (recommended)\n  - atomix.config.js\n  - atomix.config.json\n\nQuick Fix:\n1. Create a config file in your project root:\n   touch atomix.config.ts\n\n2. Add basic configuration:\n   import { defineConfig } from "@shohojdhara/atomix/config";\n   export default defineConfig({ prefix: "myapp" });\n\n3. Or copy an example:\n   cp node_modules/@shohojdhara/atomix/examples/config-examples/standard.config.ts ./atomix.config.ts');
+                return defaultConfig;
+            }({
+                configPath: "atomix.config.ts",
+                required: !0
+            });
+            configPrefix = config?.prefix;
+        } catch (error) {
+            // Prefix loading failed, but tokens were loaded, so continue
+        }
+        tokens = configTokens;
+    }
+    // Merge with defaults and generate CSS
+        const allTokens = createTokens(tokens), prefix = options?.prefix ?? configPrefix ?? "atomix";
+    // Get prefix from options, config, or use default
+        return generateCSSVariables$1(allTokens, {
+        ...options,
+        prefix: prefix
+    });
+}
+
+/**
+ * Theme Composition Utilities
+ *
+ * Simplified utilities for composing and merging DesignTokens.
+ */
+// ============================================================================
+// Deep Merge Utility
+// ============================================================================
+/**
+ * Check if value is an object
+ */ function isObject(item) {
+    return item && "object" == typeof item && !Array.isArray(item) && "function" != typeof item;
+}
+
+/**
+ * Deep merge multiple objects
+ * Later objects override earlier ones
+ */ function deepMerge(...objects) {
+    if (0 === objects.length) return {};
+    if (1 === objects.length) return objects[0];
+    const [target, ...sources] = objects, result = {
+        ...target
+    };
+    for (const source of sources) if (source) for (const key in source) {
+        if (!Object.prototype.hasOwnProperty.call(source, key)) continue;
+        const targetValue = result[key], sourceValue = source[key];
+        isObject(targetValue) && isObject(sourceValue) ? 
+        // Recursively merge objects
+        result[key] = deepMerge(targetValue, sourceValue) : 
+        // Override with source value
+        result[key] = sourceValue;
+    }
+    return result;
+}
+
+/**
+ * Merge multiple DesignTokens objects into a single DesignTokens object
+ *
+ * @param tokens - DesignTokens objects to merge
+ * @returns Merged DesignTokens object
+ *
+ * @example
+ * ```typescript
+ * const baseTokens = { 'primary': '#000', 'spacing-4': '1rem' };
+ * const customTokens = { 'secondary': '#fff', 'spacing-4': '1.5rem' };
+ * const merged = mergeTheme(baseTokens, customTokens);
+ * // Returns: { 'primary': '#000', 'secondary': '#fff', 'spacing-4': '1.5rem' }
+ * ```
+ */ function mergeTheme(...tokens) {
+    return deepMerge({}, ...tokens);
+}
+
+/**
+ * Extend DesignTokens with additional tokens
+ *
+ * @param baseTokens - Base DesignTokens to extend
+ * @param extension - Additional DesignTokens to merge
+ * @returns Extended DesignTokens object
+ *
+ * @example
+ * ```typescript
+ * const base = { 'primary': '#000' };
+ * const extended = extendTheme(base, { 'secondary': '#fff' });
+ * // Returns: { 'primary': '#000', 'secondary': '#fff' }
+ * ```
+ */ function extendTheme(baseTokens, extension) {
+    return mergeTheme(baseTokens, extension);
+}
+
+/**
+ * Create a new theme registry
+ */ function createThemeRegistry() {
+    return {};
+}
+
+/**
+ * Register a theme
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ * @param metadata - Theme metadata
+ */ function registerTheme(registry, id, metadata) {
+    registry[id] = metadata;
+}
+
+/**
+ * Unregister a theme
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ */ function unregisterTheme(registry, id) {
+    const exists = id in registry;
+    return delete registry[id], exists;
+}
+
+/**
+ * Check if a theme is registered
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ */ function hasTheme(registry, id) {
+    return id in registry;
+}
+
+/**
+ * Get theme metadata
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ */ function getTheme(registry, id) {
+    return registry[id];
+}
+
+/**
+ * Get all registered theme metadata
+ * @param registry - Theme registry object
+ */ function getAllThemes(registry) {
+    return Object.values(registry);
+}
+
+/**
+ * Get all registered theme IDs
+ * @param registry - Theme registry object
+ */ function getThemeIds(registry) {
+    return Object.keys(registry);
+}
+
+/**
+ * Clear all registered themes
+ * @param registry - Theme registry object
+ */ function clearThemes(registry) {
+    Object.keys(registry).forEach((key => delete registry[key]));
+}
+
+/**
+ * Get the number of registered themes
+ * @param registry - Theme registry object
+ */ function getThemeCount(registry) {
+    return Object.keys(registry).length;
+}
+
+/**
+ * CSS Injection Utilities
+ *
+ * Inject CSS into HTML head via <style> element.
+ */
+/**
+ * Check if running in browser environment
+ */ function isBrowser$1() {
+    return "undefined" != typeof document;
+}
+
+/**
+ * Inject CSS into HTML head via <style> element
+ *
+ * Creates or updates a style element in the document head.
+ * If an element with the same ID exists, it will be updated.
+ *
+ * @param css - CSS string to inject
+ * @param id - Style element ID (default: 'atomix-theme')
+ *
+ * @example
+ * ```typescript
+ * const css = ':root { --atomix-color-primary: #7AFFD7; }';
+ * injectCSS(css);
+ *
+ * // With custom ID
+ * injectCSS(css, 'my-custom-theme');
+ * ```
+ */ function injectCSS$1(css, id = "atomix-theme") {
+    if (!isBrowser$1()) return;
+    let styleElement = document.getElementById(id);
+    styleElement || (styleElement = document.createElement("style"), styleElement.id = id, 
+    styleElement.setAttribute("data-atomix-theme", "true"), document.head.appendChild(styleElement)), 
+    styleElement.textContent = css;
+}
+
+/**
+ * Remove injected CSS from DOM
+ *
+ * Removes the style element with the given ID from the document head.
+ *
+ * @param id - Style element ID to remove (default: 'atomix-theme')
+ *
+ * @example
+ * ```typescript
+ * removeCSS(); // Removes default 'atomix-theme'
+ * removeCSS('my-custom-theme'); // Removes custom ID
+ * ```
+ */ function removeCSS(id = "atomix-theme") {
+    if (!isBrowser$1()) return;
+    const styleElement = document.getElementById(id);
+    styleElement && styleElement.remove();
+}
+
+/**
+ * Check if CSS is already injected
+ *
+ * @param id - Style element ID to check (default: 'atomix-theme')
+ * @returns True if style element exists
+ */ function isCSSInjected(id = "atomix-theme") {
+    return !!isBrowser$1() && null !== document.getElementById(id);
+}
+
+/**
+ * Theme System Constants
+ *
+ * Centralized constants for the theme system to avoid magic numbers and strings.
+ */
+/**
+ * Default storage key for theme persistence
+ */
+/**
+ * Theme System Error Handling
+ *
+ * Centralized error handling for the Atomix theme system.
+ * Provides custom error classes and logging utilities.
+ */
+/**
+ * Theme error codes
+ */
+var ThemeErrorCode, LogLevel;
+
+"undefined" != typeof process && process.env, function(ThemeErrorCode) {
+    /** Theme not found in registry */
+    ThemeErrorCode.THEME_NOT_FOUND = "THEME_NOT_FOUND", 
+    /** Theme failed to load */
+    ThemeErrorCode.THEME_LOAD_FAILED = "THEME_LOAD_FAILED", 
+    /** Theme validation failed */
+    ThemeErrorCode.THEME_VALIDATION_FAILED = "THEME_VALIDATION_FAILED", 
+    /** Configuration loading failed */
+    ThemeErrorCode.CONFIG_LOAD_FAILED = "CONFIG_LOAD_FAILED", 
+    /** Configuration validation failed */
+    ThemeErrorCode.CONFIG_VALIDATION_FAILED = "CONFIG_VALIDATION_FAILED", 
+    /** Circular dependency detected */
+    ThemeErrorCode.CIRCULAR_DEPENDENCY = "CIRCULAR_DEPENDENCY", 
+    /** Missing dependency */
+    ThemeErrorCode.MISSING_DEPENDENCY = "MISSING_DEPENDENCY", 
+    /** Storage operation failed */
+    ThemeErrorCode.STORAGE_ERROR = "STORAGE_ERROR", 
+    /** Invalid theme name */
+    ThemeErrorCode.INVALID_THEME_NAME = "INVALID_THEME_NAME", 
+    /** CSS injection failed */
+    ThemeErrorCode.CSS_INJECTION_FAILED = "CSS_INJECTION_FAILED", 
+    /** Invalid color format */
+    ThemeErrorCode.INVALID_COLOR_FORMAT = "INVALID_COLOR_FORMAT", 
+    /** Missing required token */
+    ThemeErrorCode.MISSING_REQUIRED_TOKEN = "MISSING_REQUIRED_TOKEN", 
+    /** Accessibility contrast violation */
+    ThemeErrorCode.CONTRAST_VIOLATION = "CONTRAST_VIOLATION", 
+    /** Invalid token type */
+    ThemeErrorCode.INVALID_TOKEN_TYPE = "INVALID_TOKEN_TYPE", 
+    /** Unknown error */
+    ThemeErrorCode.UNKNOWN_ERROR = "UNKNOWN_ERROR";
+}(ThemeErrorCode || (ThemeErrorCode = {}));
+
+/**
+ * Custom error class for theme-related errors
+ */
+class ThemeError extends Error {
+    constructor(message, code = ThemeErrorCode.UNKNOWN_ERROR, context) {
+        super(message), this.name = "ThemeError", this.code = code, this.context = context, 
+        this.timestamp = Date.now(), 
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        Error.captureStackTrace && Error.captureStackTrace(this, ThemeError);
+    }
+    /**
+   * Convert error to JSON for logging
+   */    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            timestamp: this.timestamp,
+            stack: this.stack
+        };
+    }
+}
+
+/**
+ * Log level
+ */ !function(LogLevel) {
+    LogLevel[LogLevel.ERROR = 0] = "ERROR", LogLevel[LogLevel.WARN = 1] = "WARN", LogLevel[LogLevel.INFO = 2] = "INFO", 
+    LogLevel[LogLevel.DEBUG = 3] = "DEBUG";
+}(LogLevel || (LogLevel = {}));
+
+/**
+ * Theme Logger
+ *
+ * Centralized logging for the theme system.
+ * Replaces console statements with structured logging.
+ */
+class ThemeLogger {
+    constructor(config = {}) {
+        this.config = {
+            level: config.level ?? ("undefined" != typeof process && "production" === process.env?.NODE_ENV ? LogLevel.WARN : LogLevel.INFO),
+            enableConsole: config.enableConsole ?? !0,
+            onError: config.onError,
+            onWarn: config.onWarn,
+            onInfo: config.onInfo,
+            onDebug: config.onDebug
+        };
+    }
+    /**
+   * Log an error
+   */    error(message, error, context) {
+        if (this.config.level < LogLevel.ERROR) return;
+        const errorObj = error instanceof Error ? error : new Error(message), themeError = error instanceof ThemeError ? error : new ThemeError(message, ThemeErrorCode.UNKNOWN_ERROR, context);
+        this.config.enableConsole && console.error(`[ThemeError] ${message}`, {
+            error: errorObj,
+            context: {
+                ...context,
+                ...themeError.context
+            },
+            code: themeError.code
+        }), this.config.onError?.(themeError, context);
+    }
+    /**
+   * Log a warning
+   */    warn(message, context) {
+        this.config.level < LogLevel.WARN || (this.config.enableConsole && console.warn(`[ThemeWarning] ${message}`, context || {}), 
+        this.config.onWarn?.(message, context));
+    }
+    /**
+   * Log an info message
+   */    info(message, context) {
+        this.config.level < LogLevel.INFO || (this.config.enableConsole && console.info(`[ThemeInfo] ${message}`, context || {}), 
+        this.config.onInfo?.(message, context));
+    }
+    /**
+   * Log a debug message
+   */    debug(message, context) {
+        this.config.level < LogLevel.DEBUG || (this.config.enableConsole, this.config.onDebug?.(message, context));
+    }
+}
+
+/**
+ * Default logger instance
+ */ let defaultLogger = null;
+
+/**
+ * Get or create default logger
+ */ function getLogger() {
+    return defaultLogger || (defaultLogger = new ThemeLogger), defaultLogger;
+}
 
 /**
  * Check if code is running in a browser environment
- */
-const isBrowser = () => "undefined" != typeof window && "undefined" != typeof document, isServer = () => !isBrowser(), sanitizePath = path => path.replace(/[<>"']/g, "").replace(/\.\./g, "").replace(/\/+/g, "/").replace(/^\/+|\/+$/g, "") // Trim leading/trailing slashes
+ */ const isBrowser = () => "undefined" != typeof window && "undefined" != typeof document, isServer = () => !isBrowser(), sanitizePath = path => path.replace(/[<>"']/g, "").replace(/\.\./g, "").replace(/\/+/g, "/").replace(/^\/+|\/+$/g, "") // Trim leading/trailing slashes
 , buildThemePath = (themeName, basePath = "/themes", useMinified = !1, cdnPath = null) => {
     // Validate theme name to prevent path injection
     if (!isValidThemeName(themeName)) throw new ThemeError(`Invalid theme name: "${themeName}". Theme names must be lowercase alphanumeric with hyphens (e.g., "my-theme").`, ThemeErrorCode.INVALID_THEME_NAME, {
@@ -1248,107 +1735,481 @@ const isBrowser = () => "undefined" != typeof window && "undefined" != typeof do
 
 /**
  * Check if code is running on the server (SSR)
- */
+ */ var aCallable = aCallable$3, toObject = toObject$2, IndexedObject = indexedObject, lengthOfArrayLike = lengthOfArrayLike$2, $TypeError = TypeError, REDUCE_EMPTY = "Reduce of empty array with no initial value", createMethod = function(IS_RIGHT) {
+    return function(that, callbackfn, argumentsLength, memo) {
+        var O = toObject(that), self = IndexedObject(O), length = lengthOfArrayLike(O);
+        if (aCallable(callbackfn), 0 === length && argumentsLength < 2) throw new $TypeError(REDUCE_EMPTY);
+        var index = IS_RIGHT ? length - 1 : 0, i = IS_RIGHT ? -1 : 1;
+        if (argumentsLength < 2) for (;;) {
+            if (index in self) {
+                memo = self[index], index += i;
+                break;
+            }
+            if (index += i, IS_RIGHT ? index < 0 : length <= index) throw new $TypeError(REDUCE_EMPTY);
+        }
+        for (;IS_RIGHT ? index >= 0 : length > index; index += i) index in self && (memo = callbackfn(memo, self[index], index, O));
+        return memo;
+    };
+}, arrayReduce = {
+    // `Array.prototype.reduce` method
+    // https://tc39.es/ecma262/#sec-array.prototype.reduce
+    left: createMethod(!1),
+    // `Array.prototype.reduceRight` method
+    // https://tc39.es/ecma262/#sec-array.prototype.reduceright
+    right: createMethod(!0)
+}, fails = fails$9, globalThis$1 = globalThis_1, userAgent = environmentUserAgent, classof = classofRaw$2, userAgentStartsWith = function(string) {
+    return userAgent.slice(0, string.length) === string;
+}, environment = userAgentStartsWith("Bun/") ? "BUN" : userAgentStartsWith("Cloudflare-Workers") ? "CLOUDFLARE" : userAgentStartsWith("Deno/") ? "DENO" : userAgentStartsWith("Node.js/") ? "NODE" : globalThis$1.Bun && "string" == typeof Bun.version ? "BUN" : globalThis$1.Deno && "object" == typeof Deno.version ? "DENO" : "process" === classof(globalThis$1.process) ? "NODE" : globalThis$1.window && globalThis$1.document ? "BROWSER" : "REST", $reduce = arrayReduce.left;
+
+// `Array.prototype.reduce` method
+// https://tc39.es/ecma262/#sec-array.prototype.reduce
+_export({
+    target: "Array",
+    proto: !0,
+    forced: !("NODE" === environment) && environmentV8Version > 79 && environmentV8Version < 83 || !function(METHOD_NAME, argument) {
+        var method = [][METHOD_NAME];
+        return !!method && fails((function() {
+            // eslint-disable-next-line no-useless-call -- required for testing
+            method.call(null, argument || function() {
+                return 1;
+            }, 1);
+        }));
+    }("reduce")
+}, {
+    reduce: function(callbackfn /* , initialValue */) {
+        var length = arguments.length;
+        return $reduce(this, callbackfn, length, length > 1 ? arguments[1] : void 0);
+    }
+});
+
+var reduce$3 = getBuiltInPrototypeMethod$3("Array", "reduce"), isPrototypeOf = objectIsPrototypeOf, method = reduce$3, ArrayPrototype = Array.prototype;
+
+const _reduceInstanceProperty =  getDefaultExportFromCjs((function(it) {
+    var own = it.reduce;
+    return it === ArrayPrototype || isPrototypeOf(ArrayPrototype, it) && own === ArrayPrototype.reduce ? method : own;
+}));
+
+// ============================================================================
+// Theme Mode Switching
+// ============================================================================
 /**
- * Theme Utilities
+ * Switch between light and dark themes
  *
- * Helper utilities for working with themes, including color manipulation,
- * spacing helpers, and theme value accessors.
- */
+ * Automatically toggles a class on the root element and persists the choice.
+ *
+ * @param mode - Theme mode ('light', 'dark', or 'system')
+ * @param options - Configuration options
+ *
+ * @example
+ * ```typescript
+ * import { switchTheme } from '@shohojdhara/atomix/theme/utils';
+ *
+ * // Switch to dark mode
+ * switchTheme('dark');
+ *
+ * // Toggle between light/dark
+ * const current = getCurrentTheme();
+ * switchTheme(current === 'dark' ? 'light' : 'dark');
+ * ```
+ */ function switchTheme(mode, options = {}) {
+    const {selector: selector = ":root", storageKey: storageKey = "atomix-theme", enableTransition: enableTransition = !0, transitionDuration: transitionDuration = 300} = options, resolvedMode = "system" === mode ? getSystemTheme() : mode, root = ":root" === selector ? document.documentElement : document.querySelector(selector);
+    // Determine actual mode (resolve 'system')
+        if (root) {
+        // Add transition class if enabled
+        if (enableTransition) {
+            const htmlRoot = root;
+            htmlRoot.style.transition = `all ${transitionDuration}ms ease-in-out`, 
+            // Remove transition after it completes
+            setTimeout((() => {
+                htmlRoot.style.transition = "";
+            }), transitionDuration);
+        }
+        // Apply theme class
+                root.classList.remove("atomix-theme-light", "atomix-theme-dark"), root.classList.add(`atomix-theme-${resolvedMode}`), 
+        // Set data attribute for CSS selectors
+        root.setAttribute("data-theme", resolvedMode), 
+        // Persist choice
+        persistTheme(resolvedMode, {
+            storageKey: storageKey
+        }), 
+        // Dispatch custom event for listeners
+        window.dispatchEvent(new CustomEvent("atomix-theme-change", {
+            detail: {
+                mode: resolvedMode
+            }
+        }));
+    }
+}
+
+/**
+ * Toggle between light and dark themes
+ *
+ * @param options - Configuration options
+ * @returns The new theme mode
+ *
+ * @example
+ * ```typescript
+ * const newMode = toggleTheme();
+ * console.log('Switched to:', newMode);
+ * ```
+ */ function toggleTheme(options = {}) {
+    const next = "dark" === getCurrentTheme(options.storageKey) ? "light" : "dark";
+    return switchTheme(next, options), next;
+}
+
+/**
+ * Get current theme mode
+ *
+ * @param storageKey - Storage key (default: 'atomix-theme')
+ * @returns Current theme mode or 'light' if not set
+ */ function getCurrentTheme(storageKey = "atomix-theme") {
+    return "undefined" == typeof window ? "light" : localStorage.getItem(storageKey) || "light";
+}
+
+/**
+ * Get system theme preference
+ *
+ * @returns 'dark' if system prefers dark mode, 'light' otherwise
+ */ function getSystemTheme() {
+    return "undefined" == typeof window ? "light" : window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+/**
+ * Initialize theme based on saved preference or system preference
+ *
+ * Call this once at app startup.
+ *
+ * @param options - Configuration options
+ * @returns The initialized theme mode
+ *
+ * @example
+ * ```typescript
+ * // In your app entry point
+ * import { initializeTheme } from '@shohojdhara/atomix/theme/utils';
+ *
+ * const theme = initializeTheme();
+ * console.log('Theme initialized:', theme);
+ * ```
+ */ function initializeTheme(options = {}) {
+    const saved = getCurrentTheme(options.storageKey);
+    // If no saved preference, use system preference
+        if (!saved || "system" === saved) {
+        const system = getSystemTheme();
+        return switchTheme(system, options), system;
+    }
+    // Use saved preference
+        return switchTheme(saved, options), saved;
+}
+
+/**
+ * Listen for system theme changes
+ *
+ * @param callback - Function to call when system theme changes
+ * @returns Cleanup function to stop listening
+ *
+ * @example
+ * ```typescript
+ * const cleanup = listenToSystemTheme((mode) => {
+ *   console.log('System theme changed to:', mode);
+ *   switchTheme(mode);
+ * });
+ *
+ * // Later, when component unmounts
+ * cleanup();
+ * ```
+ */ function listenToSystemTheme(callback) {
+    if ("undefined" == typeof window) return () => {};
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)"), handler = e => {
+        callback(e.matches ? "dark" : "light");
+    };
+    // Modern browsers
+    return mediaQuery.addEventListener ? (mediaQuery.addEventListener("change", handler), 
+    () => mediaQuery.removeEventListener("change", handler)) : (
+    // Fallback for older browsers
+    mediaQuery.addListener(handler), () => mediaQuery.removeListener(handler));
+}
+
 // ============================================================================
-// Color Manipulation Utilities
+// Theme Persistence
 // ============================================================================
 /**
- * Convert hex color to RGB object
- */
-function hexToRgb$1(hex) {
-    const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
-    return result ? {
-        r: parseInt(result[1], 16),
-        g: parseInt(result[2], 16),
-        b: parseInt(result[3], 16)
-    } : null;
+ * Save theme preference to storage
+ *
+ * @param mode - Theme mode to save
+ * @param options - Persistence options
+ */ function persistTheme(mode, options = {}) {
+    if ("undefined" == typeof window) return;
+    const {storageKey: storageKey = "atomix-theme", storageType: storageType = "localStorage"} = options;
+    ("localStorage" === storageType ? localStorage : sessionStorage).setItem(storageKey, mode);
+}
+
+/**
+ * Clear saved theme preference
+ *
+ * @param options - Persistence options
+ */ function clearThemePreference(options = {}) {
+    if ("undefined" == typeof window) return;
+    const {storageKey: storageKey = "atomix-theme", storageType: storageType = "localStorage"} = options;
+    ("localStorage" === storageType ? localStorage : sessionStorage).removeItem(storageKey);
+}
+
+// ============================================================================
+// Theme Tokens Manipulation
+// ============================================================================
+/**
+ * Merge multiple token sets
+ *
+ * Deep merges token objects, with later tokens overriding earlier ones.
+ *
+ * @param tokens - Token objects to merge
+ * @returns Merged tokens
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeTokens(
+ *   baseTokens,
+ *   { colors: { primary: { main: '#custom' } } }
+ * );
+ * ```
+ */ function mergeTokens(...tokens) {
+    return _reduceInstanceProperty(tokens).call(tokens, ((acc, current) => deepMerge(acc, current)), {});
+}
+
+/**
+ * Override specific tokens
+ *
+ * Creates a new token object with specific overrides.
+ *
+ * @param base - Base tokens
+ * @param overrides - Tokens to override
+ * @returns New tokens with overrides applied
+ *
+ * @example
+ * ```typescript
+ * const customized = overrideTokens(defaultTokens, {
+ *   colors: {
+ *     primary: { main: '#ff0000' }
+ *   }
+ * });
+ * ```
+ */ function overrideTokens(base, overrides) {
+    return deepMerge({
+        ...base
+    }, overrides);
+}
+
+/**
+ * Pick specific token categories
+ *
+ * Extracts only the specified categories from tokens.
+ *
+ * @param tokens - Source tokens
+ * @param categories - Categories to pick
+ * @returns Tokens with only selected categories
+ *
+ * @example
+ * ```typescript
+ * const colorTokens = pickTokens(allTokens, ['colors']);
+ * ```
+ */ function pickTokens(tokens, categories) {
+    const result = {};
+    return categories.forEach((category => {
+        tokens[category] && (result[category] = tokens[category]);
+    })), result;
+}
+
+/**
+ * Omit specific token categories
+ *
+ * Removes specified categories from tokens.
+ *
+ * @param tokens - Source tokens
+ * @param categories - Categories to omit
+ * @returns Tokens without omitted categories
+ *
+ * @example
+ * ```typescript
+ * const withoutColors = omitTokens(allTokens, ['colors']);
+ * ```
+ */ function omitTokens(tokens, categories) {
+    const result = {
+        ...tokens
+    };
+    return categories.forEach((category => {
+        delete result[category];
+    })), result;
+}
+
+// ============================================================================
+// Color Utilities
+// ============================================================================
+/**
+ * Convert hex color to RGB
+ *
+ * @param hex - Hex color (with or without #)
+ * @returns RGB object { r, g, b }
+ */ function hexToRgb$1(hex) {
+    // Validate
+    if (
+    // Remove # if present
+    // Handle shorthand hex
+    3 === (hex = hex.replace(/^#/, "")).length && (hex = hex.split("").map((c => c + c)).join("")), 
+    6 !== hex.length) return null;
+    const num = parseInt(hex, 16);
+    return {
+        r: num >> 16 & 255,
+        g: num >> 8 & 255,
+        b: 255 & num
+    };
 }
 
 /**
- * Convert RGB to hex color
+ * Convert RGB to hex
+ *
+ * @param r - Red (0-255)
+ * @param g - Green (0-255)
+ * @param b - Blue (0-255)
+ * @returns Hex color with #
  */ function rgbToHex(r, g, b) {
-    const toHex = val => Math.round(Math.max(0, Math.min(255, val))).toString(16).padStart(2, "0");
-    return `#${toHex(r ?? 0)}${toHex(g ?? 0)}${toHex(b ?? 0)}`;
+    return "#" + [ r, g, b ].map((x => {
+        const hex = x.toString(16);
+        return 1 === hex.length ? "0" + hex : hex;
+    })).join("");
 }
 
 /**
- * Calculate relative luminance of a color
- * Used for determining contrast ratios
- */ function getLuminance(color) {
-    const rgb = hexToRgb$1(color);
+ * Calculate luminance of a color
+ *
+ * Used for determining contrast ratios.
+ *
+ * @param hex - Hex color
+ * @returns Luminance value (0-1)
+ */ function getLuminance(hex) {
+    const rgb = hexToRgb$1(hex);
     if (!rgb) return 0;
-    const {r: r, g: g, b: b} = rgb, [rs, gs, bs] = [ r ?? 0, g ?? 0, b ?? 0 ].map((c => {
-        const val = c / 255;
-        return val <= .03928 ? val / 12.92 : Math.pow((val + .055) / 1.055, 2.4);
-    }));
-    return .2126 * (rs ?? 0) + .7152 * (gs ?? 0) + .0722 * (bs ?? 0);
+    const [r, g, b] = [ rgb.r, rgb.g, rgb.b ].map((v => (v /= 255) <= .03928 ? v / 12.92 : Math.pow((v + .055) / 1.055, 2.4)));
+    return .2126 * (r ?? 0) + .7152 * (g ?? 0) + .0722 * (b ?? 0);
 }
 
 /**
  * Calculate contrast ratio between two colors
- */ function getContrastRatio(foreground, background) {
-    const lumA = getLuminance(foreground), lumB = getLuminance(background);
-    return (Math.max(lumA, lumB) + .05) / (Math.min(lumA, lumB) + .05);
+ *
+ * @param hex1 - First hex color
+ * @param hex2 - Second hex color
+ * @returns Contrast ratio (1-21)
+ */ function getContrastRatio(hex1, hex2) {
+    const lum1 = getLuminance(hex1), lum2 = getLuminance(hex2);
+    return (Math.max(lum1, lum2) + .05) / (Math.min(lum1, lum2) + .05);
+}
+
+/**
+ * Check if text color passes WCAG AA standard
+ *
+ * @param textColor - Text color hex
+ * @param backgroundColor - Background color hex
+ * @param size - Font size ('small' or 'large')
+ * @returns true if passes WCAG AA
+ */ function isAccessible(textColor, backgroundColor, size = "small") {
+    return getContrastRatio(textColor, backgroundColor) >= ("large" === size ? 3 : 4.5);
 }
 
 /**
- * Get appropriate contrast text color (black or white) for a background color
- */ function getContrastText(background, threshold = 3) {
-    const contrastWithWhite = getContrastRatio("#FFFFFF", background), contrastWithBlack = getContrastRatio("#000000", background);
-    return contrastWithWhite >= threshold ? "#FFFFFF" : contrastWithBlack >= threshold ? "#000000" : contrastWithWhite > contrastWithBlack ? "#FFFFFF" : "#000000";
+ * Get appropriate text color (black or white) for a background
+ *
+ * @param backgroundColor - Background hex color
+ * @param threshold - Contrast threshold (default: 3)
+ * @returns '#000000' or '#FFFFFF'
+ */ function getContrastText(backgroundColor, threshold = 3) {
+    return getContrastRatio(backgroundColor, "#FFFFFF") >= threshold ? "#FFFFFF" : "#000000";
 }
 
 /**
- * Lighten a color by a given amount
+ * Lighten a color
  *
- * @param color - Hex color string
- * @param amount - Amount to lighten (0-1), default 0.2
+ * @param hex - Base hex color
+ * @param amount - Amount to lighten (0-1)
  * @returns Lightened hex color
- */ function lighten(color, amount = .2) {
-    const rgb = hexToRgb$1(color);
-    if (!rgb) return color;
-    const {r: r, g: g, b: b} = rgb, lightenValue = val => Math.min(255, Math.round(val + (255 - val) * amount));
-    return rgbToHex(lightenValue(r), lightenValue(g), lightenValue(b));
+ */ function lighten(hex, amount = 0) {
+    const rgb = hexToRgb$1(hex);
+    if (!rgb) return hex;
+    // Use amount directly as factor (0-1)
+        const factor = Math.max(0, Math.min(1, amount)), r = Math.round(rgb.r + (255 - rgb.r) * factor), g = Math.round(rgb.g + (255 - rgb.g) * factor), b = Math.round(rgb.b + (255 - rgb.b) * factor);
+    return rgbToHex(Math.min(255, r), Math.min(255, g), Math.min(255, b));
 }
 
 /**
- * Darken a color by a given amount
+ * Darken a color
  *
- * @param color - Hex color string
- * @param amount - Amount to darken (0-1), default 0.2
+ * @param hex - Base hex color
+ * @param amount - Amount to darken (0-1)
  * @returns Darkened hex color
- */ function darken(color, amount = .2) {
-    const rgb = hexToRgb$1(color);
-    if (!rgb) return color;
-    const {r: r, g: g, b: b} = rgb, darkenValue = val => Math.max(0, Math.round(val * (1 - amount)));
-    return rgbToHex(darkenValue(r), darkenValue(g), darkenValue(b));
+ */ function darken(hex, amount = 0) {
+    const rgb = hexToRgb$1(hex);
+    if (!rgb) return hex;
+    // Use amount directly as factor (0-1)
+        const factor = Math.max(0, Math.min(1, amount)), r = Math.round(rgb.r * (1 - factor)), g = Math.round(rgb.g * (1 - factor)), b = Math.round(rgb.b * (1 - factor));
+    return rgbToHex(Math.max(0, r), Math.max(0, g), Math.max(0, b));
 }
 
 /**
- * Add alpha (opacity) to a color
+ * Add alpha to a color
  *
- * @param color - Hex color string
+ * @param hex - Hex color
  * @param opacity - Opacity value (0-1)
  * @returns RGBA color string
- */ function alpha(color, opacity) {
-    const rgb = hexToRgb$1(color);
-    if (!rgb) return color;
-    const {r: r, g: g, b: b} = rgb;
-    return `rgba(${r}, ${g}, ${b}, ${Math.max(0, Math.min(1, opacity))})`;
+ */ function alpha(hex, opacity) {
+    const rgb = hexToRgb$1(hex);
+    if (!rgb) return hex;
+    const validOpacity = Math.max(0, Math.min(1, opacity));
+    return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${validOpacity})`;
 }
 
 /**
  * Emphasize a color (lighten if dark, darken if light)
  *
- * @param color - Hex color string
- * @param coefficient - Amount to emphasize (0-1), default 0.15
+ * @param hex - Hex color
+ * @param amount - Amount to emphasize (0-1)
  * @returns Emphasized hex color
+ */ function emphasize(hex, amount = .15) {
+    return getLuminance(hex) > .5 ? darken(hex, amount) : lighten(hex, amount);
+}
+
+/**
+ * Create a spacing utility
+ *
+ * @param spacingInput - Spacing configuration
+ * @returns Spacing function
+ */ function createSpacing(spacingInput = 4) {
+    return (...values) => 0 === values.length ? "0px" : "function" == typeof spacingInput ? spacingInput(...values) : values.map((value => {
+        if ("number" == typeof spacingInput) return value * spacingInput + "px";
+        if (Array.isArray(spacingInput)) {
+            const scaled = spacingInput[value];
+            return "number" == typeof scaled ? `${scaled}px` : `${value}px`;
+        }
+        return `${value}px`;
+    })).join(" ");
+}
+
+/**
+ * CSS Variable Generator
+ *
+ * Generates CSS custom properties from theme objects and injects them into the DOM.
+ *
+ * **Token Naming Alignment:**
+ * This generator produces CSS variables that match the SCSS token naming pattern exactly:
+ * - Colors: --atomix-primary, --atomix-primary-1 through --atomix-primary-10
+ * - Spacing: --atomix-spacing-1, --atomix-spacing-4, etc.
+ * - Typography: --atomix-font-size-base, --atomix-font-weight-normal, etc.
+ * - Shadows: --atomix-box-shadow, --atomix-box-shadow-sm, etc.
+ *
+ * All tokens follow the flat structure pattern used in SCSS (not nested like --atomix-palette-primary-main).
+ * This ensures compatibility between SCSS themes and JavaScript themes.
+ *
+ * @see src/styles/03-generic/_generic.root.scss for SCSS token definitions
+ */
+/**
+ * Convert a nested object to flat CSS variable declarations
+ * Uses iterative approach for better performance with large objects
  */
 /**
  * Generate a color scale from a base color (1-10 steps)
@@ -1416,18 +2277,7 @@ function generateCSSVariables(theme, options = {}) {
                                 color.dark && (vars[`${prefix}-${key}-hover`] = color.dark), 
                 // Generate semantic color variants (matches SCSS patterns)
                 // Text emphasis: emphasized version of the color for text (--atomix-primary-text-emphasis)
-                vars[`${prefix}-${key}-text-emphasis`] = function(color, coefficient = .15) {
-                    return getLuminance(color) > .5 ? darken(color, coefficient) : lighten(color, coefficient);
-                }
-                // ============================================================================
-                // Spacing Utilities
-                // ============================================================================
-                /**
- * Create a spacing function from various input types
- *
- * @param spacingInput - Spacing configuration (number, array, or function), default 4
- * @returns Spacing function
- */ (color.main, .15), 
+                vars[`${prefix}-${key}-text-emphasis`] = emphasize(color.main, .15), 
                 // Background subtle: very light version for backgrounds (--atomix-primary-bg-subtle)
                 vars[`${prefix}-${key}-bg-subtle`] = alpha(color.main, .1), 
                 // Border subtle: light version for borders (--atomix-primary-border-subtle)
@@ -1757,44 +2607,22 @@ function generateCSSVariables(theme, options = {}) {
         // 2X large border radius (maps to spacing-4 = 16px)
         vars[`${prefix}-border-radius-xxl`] = formatValue(borderRadius.xxl, "1rem"), 
         // 3X large border radius (maps to spacing-6 = 24px)
-        vars[`${prefix}-border-radius-3xl`] = formatValue(borderRadius["3xl"], "1.5rem"), 
-        // 4X large border radius (maps to spacing-8 = 32px)
-        vars[`${prefix}-border-radius-4xl`] = formatValue(borderRadius["4xl"], "2rem"), 
-        // Pill shape (fully rounded, maps to spacing-200 = 800px)
-        vars[`${prefix}-border-radius-pill`] = formatValue(borderRadius.pill, "50rem"), 
-        vars;
-    }
-    /**
- * Generate focus ring CSS variables
- */ (theme.borderRadius, prefix)), Object.assign(variables, function(palette, prefix) {
-        const vars = {};
-        // Focus ring properties
-                return vars[`${prefix}-focus-ring-width`] = "3px", vars[`${prefix}-focus-ring-offset`] = "2px", 
-        vars[`${prefix}-focus-ring-opacity`] = "0.25", vars;
-    }(theme.palette, prefix)), theme.custom && Object.keys(theme.custom).length > 0) {
-        const customVars = 
-        /**
- * CSS Variable Generator
- *
- * Generates CSS custom properties from theme objects and injects them into the DOM.
- *
- * **Token Naming Alignment:**
- * This generator produces CSS variables that match the SCSS token naming pattern exactly:
- * - Colors: --atomix-primary, --atomix-primary-1 through --atomix-primary-10
- * - Spacing: --atomix-spacing-1, --atomix-spacing-4, etc.
- * - Typography: --atomix-font-size-base, --atomix-font-weight-normal, etc.
- * - Shadows: --atomix-box-shadow, --atomix-box-shadow-sm, etc.
- *
- * All tokens follow the flat structure pattern used in SCSS (not nested like --atomix-palette-primary-main).
- * This ensures compatibility between SCSS themes and JavaScript themes.
- *
- * @see src/styles/03-generic/_generic.root.scss for SCSS token definitions
- */
-        /**
- * Convert a nested object to flat CSS variable declarations
- * Uses iterative approach for better performance with large objects
- */
-        function(obj, prefix = "", result = {}) {
+        vars[`${prefix}-border-radius-3xl`] = formatValue(borderRadius["3xl"], "1.5rem"), 
+        // 4X large border radius (maps to spacing-8 = 32px)
+        vars[`${prefix}-border-radius-4xl`] = formatValue(borderRadius["4xl"], "2rem"), 
+        // Pill shape (fully rounded, maps to spacing-200 = 800px)
+        vars[`${prefix}-border-radius-pill`] = formatValue(borderRadius.pill, "50rem"), 
+        vars;
+    }
+    /**
+ * Generate focus ring CSS variables
+ */ (theme.borderRadius, prefix)), Object.assign(variables, function(palette, prefix) {
+        const vars = {};
+        // Focus ring properties
+                return vars[`${prefix}-focus-ring-width`] = "3px", vars[`${prefix}-focus-ring-offset`] = "2px", 
+        vars[`${prefix}-focus-ring-opacity`] = "0.25", vars;
+    }(theme.palette, prefix)), theme.custom && Object.keys(theme.custom).length > 0) {
+        const customVars = function(obj, prefix = "", result = {}) {
             // Use iterative approach with stack to avoid deep recursion
             const stack = [ {
                 obj: obj,
@@ -2248,19 +3076,29 @@ const logger = getLogger(), ThemeProvider = ({children: children, defaultTheme:
         // Check storage first
         if (enablePersistence && storageAdapter.isAvailable()) {
             const stored = storageAdapter.getItem(storageKey);
-            if (stored) return stored;
+            if (stored) {
+                // If it looks like a JSON object, parse it
+                if (stored.trim().startsWith("{")) try {
+                    return JSON.parse(stored);
+                } catch (e) {
+                    return logger.error("Failed to parse stored theme tokens", e), stored;
+                }
+                return stored;
+            }
         }
         // If defaultTheme is provided, use it
                 return null != defaultTheme ? defaultTheme : "default";
         // Default fallback
         }), [ defaultTheme, enablePersistence, storageKey, storageAdapter ]), [currentTheme, setCurrentTheme] = useState((() => "string" == typeof initialDefaultTheme ? initialDefaultTheme : "tokens-theme")), [activeTokens, setActiveTokens] = useState((() => {
-        // If defaultTheme is DesignTokens, validate and store them
-        if (defaultTheme && "string" != typeof defaultTheme) {
+        // 1. Check if initialDefaultTheme (from storage) is an object
+        if (initialDefaultTheme && "string" != typeof initialDefaultTheme) {
+            const {tokens: tokens, validation: validation} = validateAndMergeTokens(initialDefaultTheme);
+            if (validation.valid) return tokens;
+        }
+        // 2. Check if defaultTheme prop is an object
+                if (defaultTheme && "string" != typeof defaultTheme) {
             const {tokens: tokens, validation: validation} = validateAndMergeTokens(defaultTheme);
-            return validation.valid ? tokens : (logger.warn("Invalid default theme tokens, using defaults", {
-                errors: validation.errors,
-                warnings: validation.warnings
-            }), createTokens({}));
+            if (validation.valid) return tokens;
         }
         return null;
     })), [isLoading, setIsLoading] = useState(!1), [error, setError] = useState(null), loadedThemesRef = useRef(new Set), themePromisesRef = useRef({}), abortControllerRef = useRef(null);
@@ -2272,10 +3110,14 @@ const logger = getLogger(), ThemeProvider = ({children: children, defaultTheme:
     useEffect((() => {
         isServer() || applyThemeAttributes(String(currentTheme), dataAttribute);
     }), [ currentTheme, dataAttribute ]), 
-    // Handle theme persistence
+    // Handle persistence
     useEffect((() => {
-        enablePersistence && storageAdapter.isAvailable() && storageAdapter.setItem(storageKey, String(currentTheme));
-    }), [ currentTheme, storageKey, enablePersistence, storageAdapter ]), 
+        enablePersistence && storageAdapter.isAvailable() && ("tokens-theme" === currentTheme ? 
+        // Only persist if we have actual tokens to store
+        activeTokens && storageAdapter.setItem(storageKey, JSON.stringify(activeTokens)) : 
+        // Persist named theme string
+        storageAdapter.setItem(storageKey, String(currentTheme)));
+    }), [ currentTheme, activeTokens, enablePersistence, storageKey, storageAdapter ]), 
     // Cleanup: Remove completed promises and abort controllers on unmount
     useEffect((() => () => {
         // Cancel any in-flight theme loads
@@ -2414,20 +3256,21 @@ const logger = getLogger(), ThemeProvider = ({children: children, defaultTheme:
                 setIsLoading(!1);
             }
         }
-    }), [ themes, isThemeLoaded, handleError, basePath, useMinified, cdnPath ]), themeManager = useMemo((() => ({})), []), availableThemes = useMemo((() => Object.entries(themes).map((([name, metadata]) => ({
+    }), [ themes, isThemeLoaded, handleError, basePath, useMinified, cdnPath ]), updateTheme = useCallback((async (sectionOrTokens, values) => setTheme("string" == typeof sectionOrTokens && values ? values : sectionOrTokens)), [ setTheme ]), themeManager = useMemo((() => ({})), []), availableThemes = useMemo((() => Object.entries(themes).map((([name, metadata]) => ({
         ...metadata,
         name: name
     })))), [ themes ]), contextValue = useMemo((() => ({
         theme: currentTheme,
         activeTokens: activeTokens,
         setTheme: setTheme,
+        updateTheme: updateTheme,
         availableThemes: availableThemes,
         isLoading: isLoading,
         error: error,
         isThemeLoaded: isThemeLoaded,
         preloadTheme: preloadTheme,
         themeManager: themeManager
-    })), [ currentTheme, activeTokens, setTheme, availableThemes, 
+    })), [ currentTheme, activeTokens, setTheme, updateTheme, availableThemes, 
     // Use memoized value
     isLoading, error, isThemeLoaded, preloadTheme, themeManager ]);
     // Check if theme is loaded
@@ -2481,6 +3324,7 @@ function useTheme() {
         theme: context.theme,
         activeTokens: context.activeTokens,
         setTheme: context.setTheme,
+        updateTheme: context.updateTheme,
         availableThemes: context.availableThemes,
         isLoading: context.isLoading,
         error: context.error,
@@ -2716,6 +3560,389 @@ function useThemeTokens() {
     }
 }
 
+/**
+ * useThemeSwitcher Hook
+ *
+ * React hook for managing theme switching with persistence and system preference detection.
+ * Provides an easy-to-use API for dark/light mode toggling.
+ *
+ * @example
+ * ```tsx
+ * import { useThemeSwitcher } from '@shohojdhara/atomix/theme';
+ *
+ * function ThemeToggle() {
+ *   const { mode, toggle, setMode, isDark } = useThemeSwitcher();
+ *
+ *   return (
+ *     <button onClick={toggle}>
+ *       {isDark ? '☀️ Light' : '🌙 Dark'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+/**
+ * Hook for managing theme switching
+ *
+ * @param options - Configuration options
+ * @returns Theme switcher controls
+ */ function useThemeSwitcher(options = {}) {
+    const {initialMode: initialMode = "system", syncWithSystem: syncWithSystem = !1, storageKey: storageKey = "atomix-theme", enableTransition: enableTransition = !0, transitionDuration: transitionDuration = 300} = options, [mode, setModeState] = useState((() => {
+        if ("undefined" == typeof window) return initialMode;
+        // Check for saved preference first
+                const saved = getCurrentTheme(storageKey);
+        return saved && "system" !== saved ? saved : "system" === initialMode ? getSystemTheme() : initialMode;
+        // Fall back to initial mode or system
+        }));
+    // State for current mode
+        // Initialize theme on mount
+    return useEffect((() => {
+        "undefined" != typeof window && (
+        // Initialize with proper theme application
+        initializeTheme({
+            storageKey: storageKey,
+            enableTransition: enableTransition,
+            transitionDuration: transitionDuration
+        }), 
+        // Update state to match initialized theme
+        setModeState(getCurrentTheme(storageKey)));
+    }), [ storageKey, enableTransition, transitionDuration ]), 
+    // Listen for system theme changes if enabled
+    useEffect((() => {
+        if (syncWithSystem) return listenToSystemTheme((newMode => {
+            setModeState(newMode), switchTheme(newMode, {
+                storageKey: storageKey,
+                enableTransition: enableTransition,
+                transitionDuration: transitionDuration
+            });
+        }));
+    }), [ syncWithSystem, storageKey, enableTransition, transitionDuration ]), {
+        mode: mode,
+        isDark: "dark" === mode,
+        isLight: "light" === mode,
+        toggle: useCallback((() => {
+            const newMode = toggleTheme({
+                storageKey: storageKey,
+                enableTransition: enableTransition,
+                transitionDuration: transitionDuration
+            });
+            return setModeState(newMode), newMode;
+        }), [ storageKey, enableTransition, transitionDuration ]),
+        setMode: useCallback((newMode => {
+            switchTheme(newMode, {
+                storageKey: storageKey,
+                enableTransition: enableTransition,
+                transitionDuration: transitionDuration
+            }), setModeState(newMode);
+        }), [ storageKey, enableTransition, transitionDuration ]),
+        resetToSystem: useCallback((() => {
+            const systemMode = getSystemTheme();
+            switchTheme(systemMode, {
+                storageKey: storageKey,
+                enableTransition: enableTransition,
+                transitionDuration: transitionDuration
+            }), setModeState(systemMode);
+        }), [ storageKey, enableTransition, transitionDuration ]),
+        clearPreference: useCallback((() => {
+            "undefined" != typeof window && localStorage.removeItem(storageKey);
+        }), [ storageKey ])
+    };
+}
+
+/**
+ * ThemeToggle component with multiple variants
+ */ const ThemeToggle = ({className: className = "", showLabel: showLabel = !1, lightLabel: lightLabel = "Light", darkLabel: darkLabel = "Dark", iconSize: iconSize = 20, variant: variant = "icon", render: render, ariaLabel: ariaLabel = "Toggle theme", ...hookOptions}) => {
+    const {mode: mode, isDark: isDark, toggle: toggle} = useThemeSwitcher(hookOptions);
+    // Custom render
+        return render ? jsx(Fragment, {
+        children: render({
+            isDark: isDark,
+            toggle: toggle,
+            mode: mode
+        })
+    }) : 
+    // Icon-only variant (default)
+    "icon" === variant ? jsx("button", {
+        onClick: toggle,
+        className: `theme-toggle theme-toggle-icon ${className}`,
+        "aria-label": ariaLabel,
+        title: isDark ? darkLabel : lightLabel,
+        style: {
+            background: "none",
+            border: "none",
+            cursor: "pointer",
+            padding: "8px",
+            borderRadius: "50%",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            transition: "all 0.3s ease-in-out"
+        },
+        children: isDark ? jsxs("svg", {
+            width: iconSize,
+            height: iconSize,
+            viewBox: "0 0 24 24",
+            fill: "none",
+            stroke: "currentColor",
+            strokeWidth: "2",
+            strokeLinecap: "round",
+            strokeLinejoin: "round",
+            children: [ jsx("circle", {
+                cx: "12",
+                cy: "12",
+                r: "5"
+            }), jsx("line", {
+                x1: "12",
+                y1: "1",
+                x2: "12",
+                y2: "3"
+            }), jsx("line", {
+                x1: "12",
+                y1: "21",
+                x2: "12",
+                y2: "23"
+            }), jsx("line", {
+                x1: "4.22",
+                y1: "4.22",
+                x2: "5.64",
+                y2: "5.64"
+            }), jsx("line", {
+                x1: "18.36",
+                y1: "18.36",
+                x2: "19.78",
+                y2: "19.78"
+            }), jsx("line", {
+                x1: "1",
+                y1: "12",
+                x2: "3",
+                y2: "12"
+            }), jsx("line", {
+                x1: "21",
+                y1: "12",
+                x2: "23",
+                y2: "12"
+            }), jsx("line", {
+                x1: "4.22",
+                y1: "19.78",
+                x2: "5.64",
+                y2: "18.36"
+            }), jsx("line", {
+                x1: "18.36",
+                y1: "5.64",
+                x2: "19.78",
+                y2: "4.22"
+            }) ]
+        }) : jsx("svg", {
+            width: iconSize,
+            height: iconSize,
+            viewBox: "0 0 24 24",
+            fill: "none",
+            stroke: "currentColor",
+            strokeWidth: "2",
+            strokeLinecap: "round",
+            strokeLinejoin: "round",
+            children: jsx("path", {
+                d: "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"
+            })
+        })
+    }) : 
+    // Button variant with text
+    "button" === variant ? jsxs("button", {
+        onClick: toggle,
+        className: `theme-toggle theme-toggle-button ${className}`,
+        "aria-label": ariaLabel,
+        style: {
+            display: "flex",
+            alignItems: "center",
+            gap: "8px",
+            padding: "8px 16px",
+            borderRadius: "8px",
+            border: "1px solid currentColor",
+            background: "transparent",
+            color: "inherit",
+            cursor: "pointer",
+            fontSize: "14px",
+            fontWeight: "500",
+            transition: "all 0.3s ease-in-out"
+        },
+        children: [ isDark ? jsxs("svg", {
+            width: iconSize,
+            height: iconSize,
+            viewBox: "0 0 24 24",
+            fill: "none",
+            stroke: "currentColor",
+            strokeWidth: "2",
+            strokeLinecap: "round",
+            strokeLinejoin: "round",
+            children: [ jsx("circle", {
+                cx: "12",
+                cy: "12",
+                r: "5"
+            }), jsx("line", {
+                x1: "12",
+                y1: "1",
+                x2: "12",
+                y2: "3"
+            }), jsx("line", {
+                x1: "12",
+                y1: "21",
+                x2: "12",
+                y2: "23"
+            }), jsx("line", {
+                x1: "4.22",
+                y1: "4.22",
+                x2: "5.64",
+                y2: "5.64"
+            }), jsx("line", {
+                x1: "18.36",
+                y1: "18.36",
+                x2: "19.78",
+                y2: "19.78"
+            }), jsx("line", {
+                x1: "1",
+                y1: "12",
+                x2: "3",
+                y2: "12"
+            }), jsx("line", {
+                x1: "21",
+                y1: "12",
+                x2: "23",
+                y2: "12"
+            }), jsx("line", {
+                x1: "4.22",
+                y1: "19.78",
+                x2: "5.64",
+                y2: "18.36"
+            }), jsx("line", {
+                x1: "18.36",
+                y1: "5.64",
+                x2: "19.78",
+                y2: "4.22"
+            }) ]
+        }) : jsx("svg", {
+            width: iconSize,
+            height: iconSize,
+            viewBox: "0 0 24 24",
+            fill: "none",
+            stroke: "currentColor",
+            strokeWidth: "2",
+            strokeLinecap: "round",
+            strokeLinejoin: "round",
+            children: jsx("path", {
+                d: "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"
+            })
+        }), showLabel && jsx("span", {
+            children: isDark ? darkLabel : lightLabel
+        }) ]
+    }) : 
+    // Switch/toggle variant
+    "switch" === variant ? jsx("div", {
+        className: `theme-toggle theme-toggle-switch ${className}`,
+        role: "button",
+        tabIndex: 0,
+        onClick: toggle,
+        onKeyDown: e => "Enter" === e.key && toggle(),
+        "aria-label": ariaLabel,
+        style: {
+            position: "relative",
+            width: "56px",
+            height: "28px",
+            borderRadius: "14px",
+            background: isDark ? "#4b5563" : "#d1d5db",
+            cursor: "pointer",
+            transition: "background 0.3s ease-in-out",
+            display: "flex",
+            alignItems: "center",
+            padding: "2px"
+        },
+        children: jsx("div", {
+            style: {
+                position: "absolute",
+                left: isDark ? "auto" : "2px",
+                right: isDark ? "2px" : "auto",
+                width: "24px",
+                height: "24px",
+                borderRadius: "50%",
+                background: "white",
+                boxShadow: "0 2px 4px rgba(0, 0, 0, 0.2)",
+                transition: "all 0.3s ease-in-out",
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center"
+            },
+            children: isDark ? jsx("svg", {
+                width: "14",
+                height: "14",
+                viewBox: "0 0 24 24",
+                fill: "none",
+                stroke: "#4b5563",
+                strokeWidth: "2",
+                strokeLinecap: "round",
+                strokeLinejoin: "round",
+                children: jsx("path", {
+                    d: "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"
+                })
+            }) : jsxs("svg", {
+                width: "14",
+                height: "14",
+                viewBox: "0 0 24 24",
+                fill: "none",
+                stroke: "#f59e0b",
+                strokeWidth: "2",
+                strokeLinecap: "round",
+                strokeLinejoin: "round",
+                children: [ jsx("circle", {
+                    cx: "12",
+                    cy: "12",
+                    r: "5"
+                }), jsx("line", {
+                    x1: "12",
+                    y1: "1",
+                    x2: "12",
+                    y2: "3"
+                }), jsx("line", {
+                    x1: "12",
+                    y1: "21",
+                    x2: "12",
+                    y2: "23"
+                }), jsx("line", {
+                    x1: "4.22",
+                    y1: "4.22",
+                    x2: "5.64",
+                    y2: "5.64"
+                }), jsx("line", {
+                    x1: "18.36",
+                    y1: "18.36",
+                    x2: "19.78",
+                    y2: "19.78"
+                }), jsx("line", {
+                    x1: "1",
+                    y1: "12",
+                    x2: "3",
+                    y2: "12"
+                }), jsx("line", {
+                    x1: "21",
+                    y1: "12",
+                    x2: "23",
+                    y2: "12"
+                }), jsx("line", {
+                    x1: "4.22",
+                    y1: "19.78",
+                    x2: "5.64",
+                    y2: "18.36"
+                }), jsx("line", {
+                    x1: "18.36",
+                    y1: "5.64",
+                    x2: "19.78",
+                    y2: "4.22"
+                }) ]
+            })
+        })
+    }) : null;
+};
+
+ThemeToggle.displayName = "ThemeToggle";
+
 /**
  * Theme Applicator
  *
@@ -2728,7 +3955,8 @@ function useThemeTokens() {
  * Theme applicator class for runtime theme application
  *
  * Uses the unified theme system for efficient CSS variable generation and injection.
- */ class ThemeApplicator {
+ */
+class ThemeApplicator {
     constructor(root = document.documentElement) {
         this.styleId = "atomix-theme-applicator", this.root = root;
     }
@@ -4268,65 +5496,7 @@ class ThemeValidator {
             children: "\n        .atomix-theme-comparator {\n          border: 1px solid #e0e0e0;\n          border-radius: 8px;\n          background: white;\n          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;\n          padding: 24px;\n        }\n\n        .comparator-header {\n          display: grid;\n          grid-template-columns: 1fr auto 1fr;\n          gap: 24px;\n          align-items: center;\n          margin-bottom: 24px;\n          padding-bottom: 24px;\n          border-bottom: 2px solid #e0e0e0;\n        }\n\n        .theme-column {\n          text-align: center;\n        }\n\n        .theme-column h3 {\n          margin: 0;\n          font-size: 20px;\n          color: #333;\n        }\n\n        .version {\n          display: inline-block;\n          margin-top: 4px;\n          padding: 2px 8px;\n          background: #e3f2fd;\n          color: #1976d2;\n          border-radius: 4px;\n          font-size: 12px;\n        }\n\n        .vs-divider {\n          font-weight: bold;\n          font-size: 24px;\n          color: #666;\n        }\n\n        .filter-controls {\n          display: flex;\n          gap: 16px;\n          align-items: center;\n          margin-bottom: 24px;\n          padding: 16px;\n          background: #f5f5f5;\n          border-radius: 8px;\n          flex-wrap: wrap;\n        }\n\n        .filter-group {\n          display: flex;\n          align-items: center;\n          gap: 8px;\n        }\n\n        .filter-group label {\n          font-size: 14px;\n          font-weight: 500;\n          color: #666;\n        }\n\n        .search-input {\n          padding: 8px 12px;\n          border: 1px solid #e0e0e0;\n          border-radius: 4px;\n          font-size: 14px;\n          width: 250px;\n        }\n\n        .search-input:focus {\n          outline: none;\n          border-color: #2196f3;\n        }\n\n        .clear-search {\n          background: #f44336;\n          color: white;\n          border: none;\n          border-radius: 50%;\n          width: 24px;\n          height: 24px;\n          cursor: pointer;\n          font-size: 18px;\n          line-height: 1;\n          display: flex;\n          align-items: center;\n          justify-content: center;\n        }\n\n        .clear-search:hover {\n          background: #d32f2f;\n        }\n\n        .filter-select {\n          padding: 8px 12px;\n          border: 1px solid #e0e0e0;\n          border-radius: 4px;\n          font-size: 14px;\n          background: white;\n          cursor: pointer;\n        }\n\n        .clear-filters {\n          padding: 8px 16px;\n          background: #666;\n          color: white;\n          border: none;\n          border-radius: 4px;\n          cursor: pointer;\n          font-size: 14px;\n        }\n\n        .clear-filters:hover {\n          background: #555;\n        }\n\n        .search-highlight {\n          background: #fff59d;\n          padding: 2px 4px;\n          border-radius: 2px;\n        }\n\n        .comparator-stats {\n          display: grid;\n          grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));\n          gap: 16px;\n          margin-bottom: 24px;\n        }\n\n        .stat {\n          text-align: center;\n          padding: 16px;\n          background: #f5f5f5;\n          border-radius: 8px;\n        }\n\n        .stat-added {\n          border-left: 4px solid #4caf50;\n        }\n\n        .stat-removed {\n          border-left: 4px solid #f44336;\n        }\n\n        .stat-changed {\n          border-left: 4px solid #ff9800;\n        }\n\n        .stat-filtered {\n          border-left: 4px solid #2196f3;\n        }\n\n        .stat-value {\n          display: block;\n          font-size: 32px;\n          font-weight: bold;\n          color: #2196f3;\n        }\n\n        .stat-label {\n          display: block;\n          font-size: 12px;\n          color: #666;\n          margin-top: 4px;\n        }\n\n        .no-differences {\n          text-align: center;\n          padding: 48px;\n          font-size: 18px;\n          color: #4caf50;\n          background: #e8f5e9;\n          border-radius: 8px;\n        }\n\n        .differences-list h4 {\n          margin: 0 0 16px 0;\n          font-size: 18px;\n          color: #333;\n        }\n\n        .difference-item {\n          margin-bottom: 16px;\n          border: 2px solid;\n          border-radius: 8px;\n          overflow: hidden;\n          transition: all 0.2s ease;\n        }\n\n        .difference-added {\n          border-color: #4caf50;\n        }\n\n        .difference-removed {\n          border-color: #f44336;\n        }\n\n        .difference-changed {\n          border-color: #ff9800;\n        }\n\n        .difference-header {\n          display: flex;\n          align-items: center;\n          gap: 12px;\n          padding: 12px;\n          background: rgba(0, 0, 0, 0.05);\n        }\n\n        .difference-type {\n          padding: 4px 8px;\n          border-radius: 4px;\n          font-size: 11px;\n          font-weight: bold;\n          color: white;\n          text-transform: uppercase;\n        }\n\n        .difference-path {\n          font-family: 'Monaco', 'Menlo', monospace;\n          font-size: 13px;\n          color: #1976d2;\n          flex: 1;\n        }\n\n        .difference-category {\n          font-size: 11px;\n          padding: 2px 6px;\n          background: rgba(0, 0, 0, 0.1);\n          border-radius: 4px;\n          color: #666;\n          text-transform: uppercase;\n        }\n\n        .difference-values {\n          display: grid;\n          grid-template-columns: 1fr auto 1fr;\n          gap: 16px;\n          padding: 16px;\n          align-items: start;\n        }\n\n        .value-column {\n          min-width: 0;\n        }\n\n        .value-column.value-empty {\n          opacity: 0.5;\n        }\n\n        .value-label {\n          font-size: 12px;\n          font-weight: bold;\n          color: #666;\n          margin-bottom: 8px;\n        }\n\n        .value-content {\n          margin: 0;\n          padding: 12px;\n          background: rgba(255, 255, 255, 0.7);\n          border-radius: 4px;\n          font-family: 'Monaco', 'Menlo', monospace;\n          font-size: 12px;\n          overflow-x: auto;\n          white-space: pre-wrap;\n          word-break: break-all;\n        }\n\n        .value-empty {\n          color: #999;\n          font-style: italic;\n        }\n\n        .value-divider {\n          font-size: 20px;\n          color: #666;\n          align-self: center;\n        }\n      "
         }) ]
     });
-};
-
-/**
- * Theme Comparator Component
- *
- * Compares two themes and highlights differences
- */ var aCallable = aCallable$3, toObject = toObject$2, IndexedObject = indexedObject, lengthOfArrayLike = lengthOfArrayLike$2, $TypeError = TypeError, REDUCE_EMPTY = "Reduce of empty array with no initial value", createMethod = function(IS_RIGHT) {
-    return function(that, callbackfn, argumentsLength, memo) {
-        var O = toObject(that), self = IndexedObject(O), length = lengthOfArrayLike(O);
-        if (aCallable(callbackfn), 0 === length && argumentsLength < 2) throw new $TypeError(REDUCE_EMPTY);
-        var index = IS_RIGHT ? length - 1 : 0, i = IS_RIGHT ? -1 : 1;
-        if (argumentsLength < 2) for (;;) {
-            if (index in self) {
-                memo = self[index], index += i;
-                break;
-            }
-            if (index += i, IS_RIGHT ? index < 0 : length <= index) throw new $TypeError(REDUCE_EMPTY);
-        }
-        for (;IS_RIGHT ? index >= 0 : length > index; index += i) index in self && (memo = callbackfn(memo, self[index], index, O));
-        return memo;
-    };
-}, arrayReduce = {
-    // `Array.prototype.reduce` method
-    // https://tc39.es/ecma262/#sec-array.prototype.reduce
-    left: createMethod(!1),
-    // `Array.prototype.reduceRight` method
-    // https://tc39.es/ecma262/#sec-array.prototype.reduceright
-    right: createMethod(!0)
-}, fails = fails$9, globalThis$1 = globalThis_1, userAgent = environmentUserAgent, classof = classofRaw$2, userAgentStartsWith = function(string) {
-    return userAgent.slice(0, string.length) === string;
-}, environment = userAgentStartsWith("Bun/") ? "BUN" : userAgentStartsWith("Cloudflare-Workers") ? "CLOUDFLARE" : userAgentStartsWith("Deno/") ? "DENO" : userAgentStartsWith("Node.js/") ? "NODE" : globalThis$1.Bun && "string" == typeof Bun.version ? "BUN" : globalThis$1.Deno && "object" == typeof Deno.version ? "DENO" : "process" === classof(globalThis$1.process) ? "NODE" : globalThis$1.window && globalThis$1.document ? "BROWSER" : "REST", $reduce = arrayReduce.left;
-
-// `Array.prototype.reduce` method
-// https://tc39.es/ecma262/#sec-array.prototype.reduce
-_export({
-    target: "Array",
-    proto: !0,
-    forced: !("NODE" === environment) && environmentV8Version > 79 && environmentV8Version < 83 || !function(METHOD_NAME, argument) {
-        var method = [][METHOD_NAME];
-        return !!method && fails((function() {
-            // eslint-disable-next-line no-useless-call -- required for testing
-            method.call(null, argument || function() {
-                return 1;
-            }, 1);
-        }));
-    }("reduce")
-}, {
-    reduce: function(callbackfn /* , initialValue */) {
-        var length = arguments.length;
-        return $reduce(this, callbackfn, length, length > 1 ? arguments[1] : void 0);
-    }
-});
-
-var reduce$3 = getBuiltInPrototypeMethod$3("Array", "reduce"), isPrototypeOf = objectIsPrototypeOf, method = reduce$3, ArrayPrototype = Array.prototype;
-
-const _reduceInstanceProperty =  getDefaultExportFromCjs((function(it) {
-    var own = it.reduce;
-    return it === ArrayPrototype || isPrototypeOf(ArrayPrototype, it) && own === ArrayPrototype.reduce ? method : own;
-})), DEFAULT_PALETTE = {
+}, DEFAULT_PALETTE = {
     primary: {
         main: "#7c3aed",
         // Primary-6
@@ -4511,9 +5681,11 @@ const _reduceInstanceProperty =  getDefaultExportFromCjs((function(it) {
     pill: "50rem"
 };
 
-// ============================================================================
-// Default Theme Values
-// ============================================================================
+/**
+ * Theme Comparator Component
+ *
+ * Compares two themes and highlights differences
+ */
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -4523,13 +5695,13 @@ const _reduceInstanceProperty =  getDefaultExportFromCjs((function(it) {
 function createPaletteColor(color) {
     return "string" == typeof color ? {
         main: color,
-        light: lighten(color),
-        dark: darken(color),
+        light: lighten(color, .15),
+        dark: darken(color, .15),
         contrastText: getContrastText(color)
     } : {
         main: color.main || "#000000",
-        light: color.light || lighten(color.main || "#000000"),
-        dark: color.dark || darken(color.main || "#000000"),
+        light: color.light || lighten(color.main || "#000000", .15),
+        dark: color.dark || darken(color.main || "#000000", .15),
         contrastText: color.contrastText || getContrastText(color.main || "#000000")
     };
 }
@@ -4564,23 +5736,19 @@ function createThemeObject(...options) {
         },
         background: {
             default: mergedOptions.palette?.background?.default || DEFAULT_PALETTE.background.default,
+            paper: mergedOptions.palette?.background?.paper || DEFAULT_PALETTE.background.paper,
             subtle: mergedOptions.palette?.background?.subtle || DEFAULT_PALETTE.background.subtle
         },
         text: {
             primary: mergedOptions.palette?.text?.primary || DEFAULT_PALETTE.text.primary,
             secondary: mergedOptions.palette?.text?.secondary || DEFAULT_PALETTE.text.secondary,
             disabled: mergedOptions.palette?.text?.disabled || DEFAULT_PALETTE.text.disabled
-        }
+        },
+        // Spread other palette properties
+        ...mergedOptions.palette
     }, typography = deepMerge({
         ...DEFAULT_TYPOGRAPHY
-    }, mergedOptions.typography || {}), spacing = function(spacingInput = 4) {
-        // If it's already a function, return it
-        return "function" == typeof spacingInput ? spacingInput : 
-        // If it's a number, create a function that multiplies by that number
-        "number" == typeof spacingInput ? (...values) => 0 === values.length ? "0px" : values.map((value => value * spacingInput + "px")).join(" ") : 
-        // If it's an array, use it as a scale
-        Array.isArray(spacingInput) ? (...values) => 0 === values.length ? "0px" : values.map((value => `${spacingInput[value] || value}px`)).join(" ") : (...values) => 0 === values.length ? "0px" : values.map((value => 4 * value + "px")).join(" ");
-    }(mergedOptions.spacing), breakpoints = function(breakpointsInput) {
+    }, mergedOptions.typography || {}), spacing = createSpacing(mergedOptions.spacing), breakpoints = function(breakpointsInput) {
         const values = {
             xs: 0,
             sm: 576,
@@ -5403,24 +6571,6 @@ const ThemeLiveEditor = ({initialTheme: initialTheme, onChange: onChange, classN
 /**
  * Design Tokens Customizer Component
  */
-/**
- * Theme Adapter
- *
- * Converts between Theme objects and DesignTokens.
- */
-/**
- * Convert DesignTokens to Theme-compatible CSS variables
- *
- * @param tokens - DesignTokens object
- * @returns CSS variables object compatible with Theme.cssVars
- */
-function designTokensToCSSVars(tokens) {
-    const cssVars = {};
-    return Object.entries(tokens).forEach((([key, value]) => {
-        void 0 !== value && (cssVars[`--atomix-${key}`] = String(value));
-    })), cssVars;
-}
-
 /**
  * Map SCSS tokens to CSS custom properties
  *
@@ -5428,7 +6578,8 @@ function designTokensToCSSVars(tokens) {
  * const tokens = { '$primary-color': '#7AFFD7', '$spacing-md': '16px' }
  * const vars = mapSCSSTokensToCSSVars(tokens)
  * // Returns: { '--primary-color': '#7AFFD7', '--spacing-md': '16px' }
- */ function mapSCSSTokensToCSSVars(tokens, options = {}) {
+ */
+function mapSCSSTokensToCSSVars(tokens, options = {}) {
     const vars = {}, {prefix: prefix = "atomix", separator: separator = "-"} = options;
     return Object.entries(tokens).forEach((([key, value]) => {
         // Remove $ prefix from SCSS variables
@@ -5541,6 +6692,335 @@ function designTokensToCSSVars(tokens) {
     // Check if keys look like DesignTokens (kebab-case, no nesting)
 }
 
+/**
+ * Performance monitor class
+ */ class PerformanceMonitor {
+    /**
+   * Create a new performance monitor
+   *
+   * @param config Configuration options
+   */
+    constructor(config) {
+        this.frameCount = 0, this.lastSampleTime = 0, this.lastFpsUpdate = 0, this.frameTimes = [], 
+        this.animationFrameId = null, this.isActive = !1, this.startTime = 0, this.config = {
+            fpsTarget: config?.fpsTarget ?? 60,
+            sampleInterval: config?.sampleInterval ?? 500,
+            onUpdate: config?.onUpdate ?? (() => {}),
+            onDegraded: config?.onDegraded ?? (() => {}),
+            enableMemoryMonitoring: config?.enableMemoryMonitoring ?? ("undefined" != typeof window && window.performance && window.performance.memory)
+        };
+    }
+    /**
+   * Start monitoring performance
+   */    start() {
+        this.isActive || (this.isActive = !0, this.frameCount = 0, this.lastSampleTime = performance.now(), 
+        this.lastFpsUpdate = this.lastSampleTime, this.frameTimes = [], this.startTime = this.lastSampleTime, 
+        this.animationFrameId = requestAnimationFrame(this.onFrame.bind(this)));
+    }
+    /**
+   * Stop monitoring performance
+   */    stop() {
+        this.animationFrameId && (cancelAnimationFrame(this.animationFrameId), this.animationFrameId = null), 
+        this.isActive = !1;
+    }
+    /**
+   * Get current performance metrics
+   */    getMetrics() {
+        var _context;
+        const now = performance.now(), elapsed = now - this.lastFpsUpdate, fps = elapsed > 0 ? Math.round(this.frameCount / elapsed * 1e3) : 0, avgFrameTime = this.frameTimes.length > 0 ? _reduceInstanceProperty(_context = this.frameTimes).call(_context, ((a, b) => a + b), 0) / this.frameTimes.length : 0, peakFrameTime = this.frameTimes.length > 0 ? Math.max(...this.frameTimes) : 0;
+        // Get memory stats if available
+        let memory;
+        if (this.config.enableMemoryMonitoring) {
+            const perf = window.performance;
+            perf && perf.memory && (memory = {
+                usedJSHeapSize: perf.memory.usedJSHeapSize,
+                totalJSHeapSize: perf.memory.totalJSHeapSize,
+                jsHeapSizeLimit: perf.memory.jsHeapSizeLimit
+            });
+        }
+        return {
+            fps: fps,
+            frameTime: avgFrameTime,
+            peakFrameTime: peakFrameTime,
+            memory: memory,
+            timestamp: now,
+            isDegraded: fps < .7 * this.config.fpsTarget
+        };
+    }
+    /**
+   * Get the current FPS
+   */    getFps() {
+        return this.getMetrics().fps;
+    }
+    /**
+   * Check if performance is degraded
+   */    isPerformanceDegraded() {
+        return this.getMetrics().isDegraded;
+    }
+    /**
+   * Private method called on each animation frame
+   */    onFrame(timestamp) {
+        if (!this.isActive) return;
+        // Calculate frame time
+                const frameTime = timestamp - this.lastSampleTime;
+        // Check if we need to update metrics
+        if (this.frameTimes.push(frameTime), 
+        // Keep only the last 60 frame times for averaging
+        this.frameTimes.length > 60 && this.frameTimes.shift(), this.frameCount++, this.lastSampleTime = timestamp, 
+        timestamp - this.lastFpsUpdate >= this.config.sampleInterval) {
+            const metrics = this.getMetrics();
+            // Call update callback
+                        this.config.onUpdate(metrics), 
+            // Check for degradation
+            metrics.isDegraded && this.config.onDegraded(metrics), 
+            // Reset counters
+            this.frameCount = 0, this.lastFpsUpdate = timestamp;
+        }
+        this.animationFrameId = requestAnimationFrame(this.onFrame.bind(this));
+    }
+    /**
+   * Run a performance test for a specific function
+   *
+   * @param fn Function to test
+   * @param iterations Number of iterations (default: 100)
+   * @returns Average execution time in ms
+   */    async testFunctionPerformance(fn, iterations = 100) {
+        const times = [];
+        for (let i = 0; i < iterations; i++) {
+            const start = performance.now();
+            fn();
+            const end = performance.now();
+            times.push(end - start);
+        }
+        return _reduceInstanceProperty(times).call(times, ((a, b) => a + b), 0) / times.length;
+    }
+}
+
+/**
+ * Create a performance monitor instance
+ *
+ * @param config Configuration options
+ * @returns PerformanceMonitor instance
+ *
+ * @example
+ * ```typescript
+ * import { createPerformanceMonitor } from '@shohojdhara/atomix/theme';
+ *
+ * const monitor = createPerformanceMonitor({
+ *   fpsTarget: 60,
+ *   onUpdate: (metrics) => console.log('FPS:', metrics.fps),
+ *   onDegraded: (metrics) => console.warn('Performance degraded!', metrics),
+ * });
+ *
+ * monitor.start();
+ *
+ * // Later...
+ * monitor.stop();
+ * ```
+ */ function createPerformanceMonitor(config) {
+    return new PerformanceMonitor(config);
+}
+
+/**
+ * Hook for React components to monitor performance
+ *
+ * @param config Configuration options
+ * @returns Performance metrics and monitor controls
+ *
+ * @example
+ * ```typescript
+ * import { usePerformanceMonitor } from '@shohojdhara/atomix/theme';
+ *
+ * function MyComponent() {
+ *   const { metrics, start, stop } = usePerformanceMonitor({ fpsTarget: 60 });
+ *
+ *   useEffect(() => {
+ *     start();
+ *     return () => stop();
+ *   }, []);
+ *
+ *   return <div>FPS: {metrics.fps}</div>;
+ * }
+ * ```
+ */ function usePerformanceMonitor(config) {
+    const [monitor] = React.useState((() => createPerformanceMonitor(config))), [metrics, setMetrics] = React.useState((() => "undefined" != typeof window ? monitor.getMetrics() : {
+        fps: 0,
+        frameTime: 0,
+        peakFrameTime: 0,
+        timestamp: 0,
+        isDegraded: !1
+    })), start = React.useCallback((() => {
+        "undefined" != typeof window && monitor.start();
+    }), [ monitor ]), stop = React.useCallback((() => {
+        "undefined" != typeof window && monitor.stop();
+    }), [ monitor ]);
+    return React.useEffect((() => {
+        if ("undefined" == typeof window) return;
+        // Update metrics when monitor callbacks fire
+                const originalOnUpdate = config?.onUpdate;
+        return monitor.config.onUpdate = newMetrics => {
+            setMetrics(newMetrics), originalOnUpdate?.(newMetrics);
+        }, () => {
+            monitor.stop();
+        };
+    }), [ monitor, config?.onUpdate ]), {
+        metrics: metrics,
+        start: start,
+        stop: stop
+    };
+}
+
+/**
+ * Responsive Utility for Atomix Theme System
+ *
+ * Provides responsive breakpoint detection and device-aware parameter scaling
+ * based on configuration from the advanced optimization features.
+ */
+/**
+ * Responsive utility class
+ */ class ResponsiveUtil {
+    constructor(config) {
+        this.currentDevice = "desktop", // Default
+        this.resizeHandler = null, this.observer = null, this.config = config, this.currentDevice = this.getCurrentDeviceType(), 
+        // Set up resize listener
+        this.setupResizeListener();
+    }
+    /**
+   * Get the current device type based on viewport width
+   */    getCurrentDeviceType() {
+        if ("undefined" == typeof window) return "desktop";
+ // SSR fallback
+                const width = window.innerWidth;
+        // Parse breakpoint values to numbers
+                this.parsePxValue(this.config.breakpoints.mobile);
+        const tabletWidth = this.parsePxValue(this.config.breakpoints.tablet), desktopWidth = this.parsePxValue(this.config.breakpoints.desktop), wideWidth = this.parsePxValue(this.config.breakpoints.wide);
+        return width < tabletWidth ? "mobile" : width < desktopWidth ? "tablet" : width < wideWidth ? "desktop" : "wide";
+    }
+    /**
+   * Get the scaling factor for the current device
+   */    getCurrentScalingFactor() {
+        // 'wide' devices use the same scaling as 'desktop'
+        const scalingKey = "wide" === this.currentDevice ? "desktop" : this.currentDevice;
+        return this.config.deviceScaling[scalingKey] || 1;
+    }
+    /**
+   * Scale a value based on the current device's scaling factor
+   */    scaleValue(value) {
+        return value * this.getCurrentScalingFactor();
+    }
+    /**
+   * Check if the current device matches a specific type
+   */    isDevice(device) {
+        return this.currentDevice === device;
+    }
+    /**
+   * Check if the current device is mobile or smaller
+   */    isMobileOrSmaller() {
+        return "mobile" === this.currentDevice;
+    }
+    /**
+   * Check if the current device is tablet or smaller
+   */    isTabletOrSmaller() {
+        return "mobile" === this.currentDevice || "tablet" === this.currentDevice;
+    }
+    /**
+   * Check if the current device is desktop or larger
+   */    isDesktopOrLarger() {
+        return "desktop" === this.currentDevice || "wide" === this.currentDevice;
+    }
+    /**
+   * Update the responsive configuration
+   */    updateConfig(config) {
+        this.config = config, this.currentDevice = this.getCurrentDeviceType();
+    }
+    /**
+   * Destroy the responsive utility and clean up listeners
+   */    destroy() {
+        this.resizeHandler && (window.removeEventListener("resize", this.resizeHandler), 
+        this.resizeHandler = null), this.observer && (this.observer.disconnect(), this.observer = null);
+    }
+    /**
+   * Parse a CSS value to pixels
+   */    parsePxValue(value) {
+        return value.endsWith("px") ? parseFloat(value.slice(0, -2)) : 
+        // For other units, we'll use a rough conversion assuming 16px base
+        value.endsWith("rem") ? 16 * parseFloat(value.slice(0, -3)) : value.endsWith("em") ? 16 * parseFloat(value.slice(0, -2)) : parseFloat(value) || 0;
+    }
+    /**
+   * Set up the resize listener
+   */    setupResizeListener() {
+        if ("undefined" == typeof window) return;
+        // Throttled resize handler
+                let resizeTimeout = null;
+        const handleResize = () => {
+            resizeTimeout && window.clearTimeout(resizeTimeout), resizeTimeout = window.setTimeout((() => {
+                const newDeviceType = this.getCurrentDeviceType();
+                newDeviceType !== this.currentDevice && (this.currentDevice = newDeviceType);
+            }), 150);
+        } // Throttle to 150ms
+        ;
+        this.resizeHandler = handleResize, window.addEventListener("resize", handleResize), 
+        // Also observe the document body for size changes
+        "undefined" != typeof ResizeObserver && (this.observer = new ResizeObserver(handleResize), 
+        this.observer.observe(document.body));
+    }
+}
+
+/**
+ * Create a responsive utility instance
+ *
+ * @param config Responsive configuration
+ * @returns ResponsiveUtil instance
+ */ function createResponsiveUtil(config) {
+    return new ResponsiveUtil(config);
+}
+
+/**
+ * Hook for React components to use responsive features
+ *
+ * @param config Responsive configuration
+ * @returns Current device type and utility functions
+ */ function useResponsive(config) {
+    const [util] = React.useState((() => createResponsiveUtil(config))), [deviceType, setDeviceType] = React.useState((() => "undefined" != typeof window ? util.getCurrentDeviceType() : "desktop"));
+    return React.useEffect((() => {
+        if ("undefined" == typeof window) return;
+        const handleResize = () => {
+            const newDeviceType = util.getCurrentDeviceType();
+            newDeviceType !== deviceType && setDeviceType(newDeviceType);
+        };
+        // Update device type on mount
+                return setDeviceType(util.getCurrentDeviceType()), 
+        // Listen for resize events
+        window.addEventListener("resize", handleResize), () => {
+            window.removeEventListener("resize", handleResize), util.destroy();
+        };
+    }), [ util, deviceType ]), "undefined" == typeof window ? {
+        deviceType: "desktop",
+        isMobile: !1,
+        isTablet: !1,
+        isDesktop: !0,
+        isWide: !1,
+        scaleValue: value => value,
+        getCurrentDeviceType: () => "desktop",
+        getCurrentScalingFactor: () => 1,
+        isMobileOrSmaller: () => !1,
+        isTabletOrSmaller: () => !0,
+        isDesktopOrLarger: () => !0
+    } : {
+        deviceType: deviceType,
+        isMobile: "mobile" === deviceType,
+        isTablet: "tablet" === deviceType,
+        isDesktop: "desktop" === deviceType,
+        isWide: "wide" === deviceType,
+        scaleValue: value => util.scaleValue(value),
+        getCurrentDeviceType: () => util.getCurrentDeviceType(),
+        getCurrentScalingFactor: () => util.getCurrentScalingFactor(),
+        isMobileOrSmaller: () => util.isMobileOrSmaller(),
+        isTabletOrSmaller: () => util.isTabletOrSmaller(),
+        isDesktopOrLarger: () => util.isDesktopOrLarger()
+    };
+}
+
 /**
  * RTL (Right-to-Left) Support Utilities
  *
@@ -5726,6 +7206,32 @@ class RTLManager {
     }
 }
 
+/**
+ * Create RTL manager instance
+ */ function createRTLManager(config) {
+    return new RTLManager(config);
+}
+
+/**
+ * Check if locale is RTL
+ */ function isRTLLocale(locale) {
+    return RTL_LOCALES.has(locale.toLowerCase());
+}
+
+/**
+ * Get direction from locale
+ */ function getDirectionFromLocale(locale) {
+    return isRTLLocale(locale) ? "rtl" : "ltr";
+}
+
+/**
+ * RTL-aware CSS helper
+ *
+ * Returns appropriate CSS based on direction
+ */ function rtlCSS(ltrCSS, rtlCSS, direction = "ltr") {
+    return "rtl" === direction ? rtlCSS : ltrCSS;
+}
+
 /**
  * Theme System Exports
  *
@@ -5748,8 +7254,6 @@ class RTLManager {
 // ============================================================================
 // Core Theme Functions
 // ============================================================================
-// Create theme CSS from DesignTokens
-// File saving utilities removed to prevent bundling Node.js modules in browser
 /**
  * Inject theme CSS into DOM
  */ function injectTheme(css, id = "atomix-theme") {
@@ -5762,5 +7266,5 @@ class RTLManager {
     removeCSS(id);
 }
 
-export { DesignTokensCustomizer, RTLManager, ThemeApplicator, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemePreview, ThemeProvider, ThemeValidator, applyCSSVariables, applyComponentTheme, applyTheme, camelToKebab, clearThemes, createTheme, createThemeRegistry, createTokens, cssVarsToStyle, deepMerge, defaultTokens, designTokensToCSSVars, extendTheme, extractComponentName, generateCSSVariableName, generateCSSVariables$1 as generateCSSVariables, generateCSSVariablesForSelector, generateClassName, generateComponentCSSVars, getAllThemes, getCSSVariable, getComponentThemeValue, getTheme, getThemeApplicator, getThemeCount, getThemeIds, hasTheme, injectCSS$1 as injectCSS, injectTheme, isCSSInjected, isDesignTokens, isValidCSSVariableName, mapSCSSTokensToCSSVars, mergeCSSVars, mergeTheme, normalizeThemeTokens, registerTheme, removeCSS, removeCSSVariables, removeTheme, themePropertyToCSSVar, unregisterTheme, useComponentTheme, useHistory, useTheme, useThemeTokens };
+export { DesignTokensCustomizer, RTLManager, ThemeApplicator, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemePreview, ThemeProvider, ThemeToggle, ThemeValidator, alpha, applyCSSVariables, applyComponentTheme, applyTheme, camelToKebab, clearThemePreference, clearThemes, configToTokens, createPerformanceMonitor, createRTLManager, createResponsiveUtil, createSpacing, createTheme, createThemeRegistry, createTokens, cssVarsToStyle, darken, deepMerge, defaultTokens, designTokensToCSSVars, emphasize, extendTheme, extractComponentName, generateCSSVariableName, generateCSSVariables$1 as generateCSSVariables, generateCSSVariablesForSelector, generateClassName, generateComponentCSSVars, getAllThemes, getCSSVariable, getComponentThemeValue, getContrastRatio, getContrastText, getCurrentTheme, getDirectionFromLocale, getLuminance, getSystemTheme, getTheme, getThemeApplicator, getThemeCount, getThemeIds, hasTheme, hexToRgb$1 as hexToRgb, initializeTheme, injectCSS$1 as injectCSS, injectTheme, isAccessible, isCSSInjected, isDesignTokens, isRTLLocale, isValidCSSVariableName, lighten, listenToSystemTheme, mapSCSSTokensToCSSVars, mergeCSSVars, mergeTheme, mergeTokens, normalizeThemeTokens, omitTokens, overrideTokens, persistTheme, pickTokens, registerTheme, removeCSS, removeCSSVariables, removeTheme, rgbToHex, rtlCSS, switchTheme, themePropertyToCSSVar, toggleTheme, unregisterTheme, useComponentTheme, useHistory, usePerformanceMonitor, useResponsive, useTheme, useThemeSwitcher, useThemeTokens };
 //# sourceMappingURL=theme.js.map