@shohojdhara/atomix 0.5.1 → 0.5.4

package/dist/index.esm.js

@@ -1,6 +1,6 @@
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 
-import React, { useState, useRef, useEffect, memo, forwardRef, useId, useMemo, useCallback, Children, isValidElement, cloneElement, createContext, useContext, useImperativeHandle, Component } from "react";
+import React, { useState, useRef, useCallback, useEffect, memo, forwardRef, useId, useMemo, Children, isValidElement, cloneElement, createContext, useContext, useImperativeHandle, Component } from "react";
 
 import * as PhosphorIcons from "@phosphor-icons/react";
 
@@ -8,6 +8,10 @@ import { Pause, Play, SkipBack, SkipForward, SpeakerX, SpeakerHigh, Gear, Downlo
 
 import { createPortal } from "react-dom";
 
+import { existsSync } from "fs";
+
+import { join } from "path";
+
 var commonjsGlobal = "undefined" != typeof globalThis ? globalThis : "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof self ? self : {};
 
 function getDefaultExportFromCjs(x) {
@@ -1965,19 +1969,19 @@ function useAccordion(initialProps) {
         disabled: !1,
         iconPosition: "right",
         ...initialProps
-    }, isControlled = "boolean" == typeof defaultProps.isOpen, [internalOpen, setInternalOpen] = useState(defaultProps.defaultOpen || !1), isOpen = isControlled ? defaultProps.isOpen : internalOpen, [panelHeight, setPanelHeight] = useState(isOpen ? "auto" : "0px"), panelRef = useRef(null), contentRef = useRef(null), updatePanelHeight = () => {
+    }, isControlled = "boolean" == typeof defaultProps.isOpen, [internalOpen, setInternalOpen] = useState(defaultProps.defaultOpen || !1), isOpen = isControlled ? defaultProps.isOpen : internalOpen, [panelHeight, setPanelHeight] = useState(isOpen ? "auto" : "0px"), panelRef = useRef(null), contentRef = useRef(null), updatePanelHeight = useCallback((() => {
         if (contentRef.current && panelRef.current) {
             const height = isOpen ? `${contentRef.current.clientHeight}px` : "0px";
             panelRef.current.style.setProperty(ACCORDION.CSS_VARS.PANEL_HEIGHT, height), setPanelHeight(height);
         }
-    };
+    }), [ isOpen ]);
     // Controlled/uncontrolled open state
         /**
    * Effect to update panel height when open state changes
    */
     return useEffect((() => {
         updatePanelHeight();
-    }), [ isOpen ]), 
+    }), [ isOpen, updatePanelHeight ]), 
     /**
    * Effect to handle window resize and update panel height
    */
@@ -1986,7 +1990,7 @@ function useAccordion(initialProps) {
             isOpen && updatePanelHeight();
         };
         return window.addEventListener("resize", handleResize), () => window.removeEventListener("resize", handleResize);
-    }), [ isOpen ]), {
+    }), [ isOpen, updatePanelHeight ]), {
         state: {
             isOpen: isOpen,
             panelHeight: panelHeight
@@ -3562,7 +3566,7 @@ function useResponsiveGlass({baseParams: baseParams, breakpoints: breakpoints =
  * @param config Monitor configuration
  * @returns Performance metrics and controls
  */
-function usePerformanceMonitor(config = {}) {
+function usePerformanceMonitor$1(config = {}) {
     const {enabled: enabled = !0, targetFps: targetFps = 60, minFps: minFps = 45, scaleUpThreshold: scaleUpThreshold = 58, lowFpsFrames: lowFpsFrames = 3, highFpsFrames: highFpsFrames = 10, debug: debug = !1, showOverlay: showOverlay = !1} = config, [metrics, setMetrics] = useState({
         fps: 0,
         frameTime: 0,
@@ -4118,7 +4122,7 @@ function getDevicePreset(presetName) {
         debug: !1
     });
     // Performance monitoring - tracks FPS, frame time, memory usage
-    const {metrics: performanceMetrics, toggleMonitoring: toggleMonitoring} = usePerformanceMonitor({
+    const {metrics: performanceMetrics, toggleMonitoring: toggleMonitoring} = usePerformanceMonitor$1({
         enabled: debugPerformance,
         // Enable when debugPerformance is true
         debug: !1,
@@ -5111,7 +5115,7 @@ const BreadcrumbItem =  forwardRef((({children: children, href: href, active: ac
 
 BreadcrumbItem.displayName = "BreadcrumbItem";
 
-const Breadcrumb =  memo((function({items: items, divider: divider, className: className = "", "aria-label": ariaLabel = "Breadcrumb", linkComponent: linkComponent, style: style, children: children}) {
+const BreadcrumbComponent =  memo((function({items: items, divider: divider, className: className = "", "aria-label": ariaLabel = "Breadcrumb", linkComponent: linkComponent, style: style, children: children}) {
     const breadcrumbClasses = [ BREADCRUMB.CLASSES.BASE, className ].filter(Boolean).join(" ");
     let content;
     if (items && items.length > 0) 
@@ -5151,7 +5155,7 @@ const Breadcrumb =  memo((function({items: items, divider: divider, className: c
             children: content
         })
     });
-}));
+})), Breadcrumb = BreadcrumbComponent;
 
 /**
  * Spinner state and functionality
@@ -5311,7 +5315,152 @@ class ThemeNaming {
 
 ThemeNaming.prefix = "atomix";
 
-const Button =  React.memo( forwardRef((({label: label, children: children, onClick: onClick, variant: variant = "primary", size: size = "md", disabled: disabled = !1, loading: loading = !1, loadingText: loadingText, icon: icon, iconName: iconName, iconSize: iconSize = "sm", iconPosition: iconPosition = "start", iconOnly: iconOnly = !1, rounded: rounded = !1, fullWidth: fullWidth = !1, block: block = !1, active: active = !1, selected: selected = !1, type: type = "button", className: className = "", as: Component = "button", href: href, target: target, glass: glass, onHover: onHover, onFocus: onFocus, onBlur: onBlur, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, "aria-expanded": ariaExpanded, "aria-controls": ariaControls, tabIndex: tabIndex, style: style, linkComponent: linkComponent, ...props}, ref) => {
+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;
+}));
+
+/**
+ * Render a slot with the given props
+ *
+ * Priority order:
+ * 1. render function
+ * 2. component
+ * 3. children
+ * 4. fallback
+ *
+ * @example
+ * renderSlot(
+ *   { render: (props) => <CustomButton {...props} /> },
+ *   { onClick: handleClick, children: 'Click me' }
+ * )
+ */ function renderSlot(slot, props, fallback) {
+    // No slot provided, use fallback
+    if (!slot) return fallback;
+    // Slot is a plain React node
+        if ( React.isValidElement(slot) || "string" == typeof slot || "number" == typeof slot) return slot;
+    // Slot is an object with rendering options
+        if ("object" == typeof slot && null !== slot) {
+        const slotObj = slot;
+        // Priority 1: render function
+                if (slotObj.render && "function" == typeof slotObj.render) return slotObj.render(props);
+        // Priority 2: component
+                if (slotObj.component) {
+            const Component = slotObj.component;
+            return jsx(Component, {
+                ...props
+            });
+        }
+        // Priority 3: children
+                if (void 0 !== slotObj.children) return slotObj.children;
+    }
+    // Fallback
+        return fallback;
+}
+
+/**
+ * Check if a value is a slot configuration
+ */ function isSlot(value) {
+    return "object" == typeof value && null !== value && ("render" in value || "component" in value || "children" in value);
+}
+
+/**
+ * Merge multiple slot configurations
+ * Later slots override earlier ones
+ */ function mergeSlots(...slots) {
+    const filtered = slots.filter((s => void 0 !== s));
+    if (0 !== filtered.length) return 1 === filtered.length ? filtered[0] : _reduceInstanceProperty(filtered).call(filtered, ((acc, slot) => ({
+        ...acc,
+        ...slot
+    })));
+}
+
+/**
+ * Create a slot wrapper component
+ *
+ * @example
+ * const ButtonSlot = createSlotComponent<ButtonSlotProps>('button')
+ *
+ * <ButtonSlot slot={customSlot} {...props}>
+ *   Default content
+ * </ButtonSlot>
+ */ function createSlotComponent(defaultElement = "div") {
+    return function({slot: slot, children: children, ...props}) {
+        const slotProps = props;
+        return slot ? jsx(Fragment, {
+            children: renderSlot(slot, slotProps, children)
+        }) : jsx(defaultElement, "string" == typeof defaultElement ? {
+            ...props,
+            children: children
+        } : {
+            ...slotProps,
+            children: children
+        });
+    };
+}
+
+/**
+ * Utility to create typed slot props
+ */ function createSlotProps(props) {
+    return props;
+}
+
+/**
+ * Hook to manage slot rendering
+ */ function useSlot(slot, props, fallback) {
+    return React.useMemo((() => renderSlot(slot, props, fallback)), [ slot, props, fallback ]);
+}
+
+const Button =  React.memo( forwardRef((({label: label, children: children, onClick: onClick, variant: variant = "primary", size: size = "md", disabled: disabled = !1, loading: loading = !1, loadingText: loadingText, icon: icon, iconName: iconName, iconSize: iconSize = "sm", iconPosition: iconPosition = "start", iconOnly: iconOnly = !1, rounded: rounded = !1, fullWidth: fullWidth = !1, block: block = !1, active: active = !1, selected: selected = !1, type: type = "button", className: className = "", as: Component = "button", href: href, target: target, glass: glass, onHover: onHover, onFocus: onFocus, onBlur: onBlur, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, "aria-expanded": ariaExpanded, "aria-controls": ariaControls, tabIndex: tabIndex, style: style, linkComponent: linkComponent, slots: slots, ...props}, ref) => {
     const isDisabled = disabled || loading, shouldRenderAsLink = Boolean(href), iconElement = iconName ? jsx(Icon, {
         name: iconName,
         size: iconSize
@@ -5327,17 +5476,28 @@ const Button =  React.memo( forwardRef((({label: label, children: children, onCl
         children: [ loading && jsx("span", {
             className: ThemeNaming.bemClass(THEME_NAMING.BUTTON_PREFIX, THEME_NAMING.SPINNER_ELEMENT),
             "aria-hidden": "true",
-            children: jsx(Spinner, {
+            children: renderSlot(slots?.spinner, {
+                className: ThemeNaming.bemClass(THEME_NAMING.BUTTON_PREFIX, THEME_NAMING.SPINNER_ELEMENT),
                 size: spinnerSize,
                 variant: "link" === variant || "string" == typeof variant && variant.startsWith("outline-") ? "primary" : "danger" === variant ? "error" : variant
-            })
+            }, jsx(Spinner, {
+                size: spinnerSize,
+                variant: "link" === variant || "string" == typeof variant && variant.startsWith("outline-") ? "primary" : "danger" === variant ? "error" : variant
+            }))
         }), iconElement && !loading && jsx("span", {
             className: ThemeNaming.bemClass(THEME_NAMING.BUTTON_PREFIX, THEME_NAMING.ICON_ELEMENT),
             "aria-hidden": "true",
-            children: iconElement
+            children: renderSlot(slots?.icon, {
+                className: ThemeNaming.bemClass(THEME_NAMING.BUTTON_PREFIX, THEME_NAMING.ICON_ELEMENT),
+                children: iconElement,
+                size: iconSize
+            }, iconElement)
         }), !iconOnly && buttonText && jsx("span", {
             className: ThemeNaming.bemClass(THEME_NAMING.BUTTON_PREFIX, THEME_NAMING.LABEL_ELEMENT),
-            children: buttonText
+            children: renderSlot(slots?.label, {
+                className: ThemeNaming.bemClass(THEME_NAMING.BUTTON_PREFIX, THEME_NAMING.LABEL_ELEMENT),
+                children: buttonText
+            }, buttonText)
         }) ]
     }), buttonProps = {
         className: buttonClass,
@@ -5354,48 +5514,59 @@ const Button =  React.memo( forwardRef((({label: label, children: children, onCl
         tabIndex: void 0 !== tabIndex ? tabIndex : isDisabled ? -1 : 0,
         style: style,
         ...props
-    };
-    // Determine if we should render as a link
-    // If disabled, we still check href, but we might want to render as button or anchor with aria-disabled
-    // The previous logic was Boolean(href && !isDisabled). This meant if disabled, it renders as <button>.
-    // This is a safe fallback for disabled links.
-        let content;
-    // Render as anchor if href is provided
-        if (shouldRenderAsLink) 
-    // Use custom linkComponent if provided (e.g., Next.js Link)
-    if (linkComponent) {
-        const LinkComp = linkComponent, linkProps = {
+    }, buttonChildren = renderSlot(slots?.root, {
+        className: buttonClass,
+        children: buttonContent,
+        disabled: isDisabled,
+        loading: loading,
+        onClick: handleClickEvent,
+        type: type,
+        "aria-label": safeAriaLabel,
+        "aria-disabled": isDisabled,
+        "aria-busy": loading
+    }, (() => {
+        // Render as anchor if href is provided
+        if (shouldRenderAsLink) {
+            // Use custom linkComponent if provided (e.g., Next.js Link)
+            if (linkComponent) {
+                const LinkComp = linkComponent, linkProps = {
+                    ...buttonProps,
+                    ref: ref,
+                    // linkComponent usually forwards ref to anchor
+                    href: isDisabled ? void 0 : href,
+                    to: isDisabled ? void 0 : href,
+                    target: target,
+                    rel: "_blank" === target ? "noopener noreferrer" : void 0
+                };
+                return jsx(LinkComp, {
+                    ...linkProps,
+                    children: buttonContent
+                });
+            }
+            // Fallback to regular anchor tag
+            return jsx("a", {
+                ...buttonProps,
+                ref: ref,
+                href: isDisabled ? void 0 : href,
+                target: target,
+                rel: "_blank" === target ? "noopener noreferrer" : void 0,
+                children: buttonContent
+            });
+        }
+        // Default button rendering
+        return jsx(Component, {
             ...buttonProps,
             ref: ref,
-            // linkComponent usually forwards ref to anchor
-            href: isDisabled ? void 0 : href,
-            to: isDisabled ? void 0 : href,
-            target: target,
-            rel: "_blank" === target ? "noopener noreferrer" : void 0
-        };
-        content = jsx(LinkComp, {
-            ...linkProps,
+            type: "button" === Component ? type : void 0,
+            disabled: isDisabled,
             children: buttonContent
         });
-    } else 
-    // Fallback to regular anchor tag
-    content = jsx("a", {
-        ...buttonProps,
-        ref: ref,
-        href: isDisabled ? void 0 : href,
-        target: target,
-        rel: "_blank" === target ? "noopener noreferrer" : void 0,
-        children: buttonContent
-    }); else 
-    // Default button rendering
-    content = jsx(Component, {
-        ...buttonProps,
-        ref: ref,
-        type: "button" === Component ? type : void 0,
-        disabled: isDisabled,
-        children: buttonContent
-    });
-    if (glass) {
+    })());
+    // Determine if we should render as a link
+    // If disabled, we still check href, but we might want to render as button or anchor with aria-disabled
+    // The previous logic was Boolean(href && !isDisabled). This meant if disabled, it renders as <button>.
+    // This is a safe fallback for disabled links.
+        if (glass) {
         // Default glass props
         const defaultGlassProps = {
             displacementScale: 20,
@@ -5408,10 +5579,10 @@ const Button =  React.memo( forwardRef((({label: label, children: children, onCl
         };
         return jsx(AtomixGlass, {
             ...glassProps,
-            children: content
+            children: buttonChildren
         });
     }
-    return content;
+    return buttonChildren;
 })));
 
 Button.displayName = "Button";
@@ -5923,67 +6094,12 @@ const ElevationCard = ({elevationClass: elevationClass = "is-elevated", classNam
     });
 };
 
-ElevationCard.displayName = "ElevationCard";
-
-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;
-}));
-
 /**
  * Comprehensive chart hook with shared functionality
  * @param initialProps - Initial chart properties
  * @returns Chart state and methods
- */ function useChart(initialProps) {
+ */
+function useChart(initialProps) {
     const [interactionState, setInteractionState] = useState({
         hoveredPoint: null,
         selectedPoints: [],
@@ -6015,8 +6131,11 @@ const _reduceInstanceProperty =  getDefaultExportFromCjs((function(it) {
     }), animationFrameRef = useRef(null);
     // Default chart properties
         // Cleanup animation frame on unmount
-    useEffect((() => () => {
-        animationFrameRef.current && cancelAnimationFrame(animationFrameRef.current);
+    useEffect((() => {
+        const currentRef = animationFrameRef.current;
+        return () => {
+            currentRef && cancelAnimationFrame(currentRef);
+        };
     }), []);
     /**
    * Point interaction handlers
@@ -6407,7 +6526,9 @@ function getDatasetBounds(data) {
 
 /**
  * Hook for managing chart toolbar state and generating chart-specific configurations
- */ const ChartToolbar =  memo( forwardRef((({chartType: chartType = "line", groups: groups = [], enableDefaults: enableDefaults = !0, defaults: defaults = {
+ */ ElevationCard.displayName = "ElevationCard";
+
+const ChartToolbar =  memo( forwardRef((({chartType: chartType = "line", groups: groups = [], enableDefaults: enableDefaults = !0, defaults: defaults = {
     refresh: !0,
     export: !0,
     fullscreen: !0,
@@ -6897,8 +7018,8 @@ toolbarConfig: toolbarConfig, customToolbarActions: customToolbarActions, custom
         }), [ chartType ]), finalDefaults = useMemo((() => ({
             ...getChartDefaults(),
             ...defaults
-        })), [ getChartDefaults, defaults ]), enhancedHandlers = {
-            onRefresh: useCallback((() => {
+        })), [ getChartDefaults, defaults ]), enhancedHandlers = useMemo((() => ({
+            onRefresh: () => {
                 setState((prev => ({
                     ...prev,
                     isRefreshing: !0
@@ -6908,8 +7029,8 @@ toolbarConfig: toolbarConfig, customToolbarActions: customToolbarActions, custom
                         isRefreshing: !1
                     })));
                 }), 1e3);
-            }), [ handlers.onRefresh ]),
-            onExport: useCallback((async format => {
+            },
+            onExport: async format => {
                 setState((prev => ({
                     ...prev,
                     isExporting: !0
@@ -6922,70 +7043,70 @@ toolbarConfig: toolbarConfig, customToolbarActions: customToolbarActions, custom
                         isExporting: !1
                     })));
                 }
-            }), [ handlers.onExport ]),
-            onFullscreen: useCallback((isFullscreen => {
+            },
+            onFullscreen: isFullscreen => {
                 setState((prev => ({
                     ...prev,
                     isFullscreen: isFullscreen
                 }))), handlers.onFullscreen?.(isFullscreen);
-            }), [ handlers.onFullscreen ]),
-            onZoomIn: useCallback((() => {
+            },
+            onZoomIn: () => {
                 setState((prev => ({
                     ...prev,
                     zoomLevel: Math.min(1.2 * prev.zoomLevel, 5)
                 }))), handlers.onZoomIn?.();
-            }), [ handlers.onZoomIn ]),
-            onZoomOut: useCallback((() => {
+            },
+            onZoomOut: () => {
                 setState((prev => ({
                     ...prev,
                     zoomLevel: Math.max(prev.zoomLevel / 1.2, .2)
                 }))), handlers.onZoomOut?.();
-            }), [ handlers.onZoomOut ]),
-            onZoomReset: useCallback((() => {
+            },
+            onZoomReset: () => {
                 setState((prev => ({
                     ...prev,
                     zoomLevel: 1
                 }))), handlers.onZoomReset?.();
-            }), [ handlers.onZoomReset ]),
-            onPanToggle: useCallback((enabled => {
+            },
+            onPanToggle: enabled => {
                 setState((prev => ({
                     ...prev,
                     panEnabled: enabled
                 }))), handlers.onPanToggle?.(enabled);
-            }), [ handlers.onPanToggle ]),
-            onReset: useCallback((() => {
+            },
+            onReset: () => {
                 setState((prev => ({
                     ...prev,
                     zoomLevel: 1,
                     panEnabled: !1
                 }))), handlers.onReset?.();
-            }), [ handlers.onReset ]),
-            onGridToggle: useCallback((show => {
+            },
+            onGridToggle: show => {
                 setState((prev => ({
                     ...prev,
                     showGrid: show
                 }))), handlers.onGridToggle?.(show);
-            }), [ handlers.onGridToggle ]),
-            onLegendToggle: useCallback((show => {
+            },
+            onLegendToggle: show => {
                 setState((prev => ({
                     ...prev,
                     showLegend: show
                 }))), handlers.onLegendToggle?.(show);
-            }), [ handlers.onLegendToggle ]),
-            onTooltipsToggle: useCallback((show => {
+            },
+            onTooltipsToggle: show => {
                 setState((prev => ({
                     ...prev,
                     showTooltips: show
                 }))), handlers.onTooltipsToggle?.(show);
-            }), [ handlers.onTooltipsToggle ]),
-            onAnimationsToggle: useCallback((enabled => {
+            },
+            onAnimationsToggle: enabled => {
                 setState((prev => ({
                     ...prev,
                     animationsEnabled: enabled
                 }))), handlers.onAnimationsToggle?.(enabled);
-            }), [ handlers.onAnimationsToggle ]),
-            onSettings: useCallback((() => {}), [])
-        }, generateToolbarGroups = useCallback((() => {
+            },
+            onSettings: () => {}
+        })), [ handlers ]), generateToolbarGroups = useCallback((() => {
             const groups = [], dataActions = [];
             // Data actions group
                         finalDefaults.refresh && dataActions.push({
@@ -7110,7 +7231,7 @@ toolbarConfig: toolbarConfig, customToolbarActions: customToolbarActions, custom
                 actions: customActions
             });
             return groups;
-        }), [ chartType, finalDefaults, state, enhancedHandlers, customActions, customGroups ]);
+        }), [ finalDefaults, state, enhancedHandlers, customActions, customGroups ]);
         // Keyboard shortcuts
         return useEffect((() => {
             const handleKeyDown = event => {
@@ -7702,7 +7823,7 @@ const ChartRenderer =  memo( forwardRef((({datasets: datasets = [], config: conf
         announcement: announcement,
         focusedPoint: focusedPoint,
         getAccessibleDescription: () => "Chart description"
-    })), [ announcement, focusedPoint ]), transform = useMemo((() => chartContext ? `translate(${chartContext.panOffset.x}px, ${chartContext.panOffset.y}px) scale(${chartContext.zoomLevel})` : ""), [ chartContext?.panOffset.x, chartContext?.panOffset.y, chartContext?.zoomLevel ]), chartData = useMemo((() => {
+    })), [ announcement, focusedPoint ]), transform = useMemo((() => chartContext ? `translate(${chartContext.panOffset.x}px, ${chartContext.panOffset.y}px) scale(${chartContext.zoomLevel})` : ""), [ chartContext ]), chartData = useMemo((() => {
         // Return null if dimensions not ready to prevent calculation with invalid dimensions
         if (!isInitialized || 0 === dimensions.width || 0 === dimensions.height) return null;
         const scales = calculateScales(processedData, dimensions.width, dimensions.height, void 0, config);
@@ -8115,7 +8236,7 @@ function useBarChart(datasets, options = {}) {
                 opacity: .4
             } ]
         };
-    })) : []), [ options.useGradients ]), formatValue = useCallback((value => options.valueFormatter ? options.valueFormatter(value) : value.toString()), [ options.valueFormatter ]);
+    })) : []), [ options.useGradients ]), formatValue = useCallback((value => options.valueFormatter ? options.valueFormatter(value) : value.toString()), [ options ]);
     return {
         // State
         hoveredBar: hoveredBar,
@@ -8141,7 +8262,7 @@ function useBarChart(datasets, options = {}) {
                     y: horizontal ? y + height / 2 : y - 5
                 };
             }
-        }), [ options.dataLabelPosition ]),
+        }), [ options ]),
         // Handlers
         handleBarHover: handleBarHover,
         handleBarLeave: handleBarLeave,
@@ -8450,13 +8571,13 @@ const DonutChart =  memo( forwardRef((({datasets: datasets = [], config: config
     roundedCorners: !0
 }, onDataPointClick: onDataPointClick, ...props}, ref) => {
     // Use the first dataset for donut chart
-    const dataset = datasets.length > 0 ? datasets[0] : {
+    const dataset = useMemo((() => datasets.length > 0 ? datasets[0] : {
         label: "",
         data: []
-    }, chartData = useMemo((() => {
+    }), [ datasets ]), chartData = useMemo((() => {
         if (!dataset?.data?.length) return null;
         // Filter out invalid data points
-                const validDataPoints = dataset?.data?.filter((point => "number" == typeof point.value && !isNaN(point.value) && isFinite(point.value) && point.value > 0));
+                const validDataPoints = (dataset?.data || []).filter((point => "number" == typeof point.value && !isNaN(point.value) && isFinite(point.value) && point.value > 0));
         return validDataPoints.length ? {
             validDataPoints: validDataPoints
         } : null;
@@ -9412,7 +9533,7 @@ function usePieChart(data, options = {}) {
         const parts = [];
         return !1 !== options.showLabels && parts.push(slice.label), options.showPercentages && parts.push(`${Math.round(slice.percentage)}%`), 
         options.showValues && parts.push(slice.value.toString()), parts.join(" - ");
-    }), [ options.labelFormatter, options.showLabels, options.showPercentages, options.showValues ]), getSliceTransform = useCallback(((slice, isHovered) => isHovered && options.enableHoverEffects && options.hoverOffset ? `translate(${Math.cos(slice.midAngle) * options.hoverOffset}, ${Math.sin(slice.midAngle) * options.hoverOffset})` : ""), [ options.enableHoverEffects, options.hoverOffset ]), isSliceSelected = useCallback((index => selectedSlices.has(index)), [ selectedSlices ]);
+    }), [ options ]), getSliceTransform = useCallback(((slice, isHovered) => isHovered && options.enableHoverEffects && options.hoverOffset ? `translate(${Math.cos(slice.midAngle) * options.hoverOffset}, ${Math.sin(slice.midAngle) * options.hoverOffset})` : ""), [ options.enableHoverEffects, options.hoverOffset ]), isSliceSelected = useCallback((index => selectedSlices.has(index)), [ selectedSlices ]);
     return {
         // Data
         processedData: processedData,
@@ -10839,7 +10960,7 @@ const DataTable =  memo((({data: data, columns: columns, className: className, s
             const newOrder = columns.map((col => col.key)), currentOrderSet = new Set(columnOrder), newOrderSet = new Set(newOrder);
             // Only update if there are actual differences
             newOrder.length === columnOrder.length && newOrder.every((key => currentOrderSet.has(key))) && columnOrder.every((key => newOrderSet.has(key))) || setColumnOrder(newOrder);
-        }), [ columns ]), 
+        }), [ columns, columnOrder ]), 
         // Update column visibility when columns prop changes
         useEffect((() => {
             setColumnVisibility((prev => {
@@ -11384,7 +11505,7 @@ function formatDate(date, format) {
 /**
  * Check if a date is within a min and max range
  */ function useDatePicker({value: value, onChange: onChange, selectionMode: selectionMode = "single", startDate: startDate, endDate: endDate, onRangeChange: onRangeChange, format: format = "MM/dd/yyyy", minDate: minDate, maxDate: maxDate, inline: inline = !1} = {}) {
-    const [isOpen, setIsOpen] = useState(inline), [inputValue, setInputValue] = useState(value ? formatDate(value, format) : ""), [rangeInputValue, setRangeInputValue] = useState(startDate && endDate ? `${formatDate(startDate, format)} - ${formatDate(endDate, format)}` : startDate ? `${formatDate(startDate, format)} - Select end date` : ""), [viewDate, setViewDate] = useState(value || startDate || new Date), [viewMode, setViewMode] = useState("days"), [rangeSelectionState, setRangeSelectionState] = useState(!startDate || startDate && endDate ? "start" : "end"), datePickerRef = useRef(null), inputRef = useRef(null), today = new Date, currentMonth = viewDate.getMonth(), currentYear = viewDate.getFullYear(), daysInMonth = getDaysInMonth(currentYear, currentMonth), firstDayOfMonth = new Date(currentYear, currentMonth, 1).getDay();
+    const [isOpen, setIsOpen] = useState(inline), [inputValue, setInputValue] = useState(value ? formatDate(value, format) : ""), [rangeInputValue, setRangeInputValue] = useState(startDate && endDate ? `${formatDate(startDate, format)} - ${formatDate(endDate, format)}` : startDate ? `${formatDate(startDate, format)} - Select end date` : ""), [viewDate, setViewDate] = useState(value || startDate || new Date), [viewMode, setViewMode] = useState("days"), [rangeSelectionState, setRangeSelectionState] = useState(!startDate || startDate && endDate ? "start" : "end"), datePickerRef = useRef(null), inputRef = useRef(null), today = useMemo((() => new Date), []), currentMonth = viewDate.getMonth(), currentYear = viewDate.getFullYear(), daysInMonth = getDaysInMonth(currentYear, currentMonth), firstDayOfMonth = new Date(currentYear, currentMonth, 1).getDay();
     // Update input value when value or range dates change externally
     useEffect((() => {
         "single" === selectionMode ? setInputValue(value ? formatDate(value, format) : "") : (setRangeInputValue(startDate && endDate ? `${formatDate(startDate, format)} - ${formatDate(endDate, format)}` : startDate ? `${formatDate(startDate, format)} - Select end date` : ""), 
@@ -11907,21 +12028,11 @@ const DatePicker =  forwardRef((({value: value, onChange: onChange, selectionMod
  * @returns EdgePanel state and methods
  */
 function useEdgePanel(initialProps) {
-    // Default EdgePanel properties
-    const defaultProps = {
-        position: "start",
-        mode: "slide",
-        isOpen: !1,
-        backdrop: !0,
-        closeOnBackdropClick: !0,
-        closeOnEscape: !0,
-        glass: void 0,
-        ...initialProps
-    }, [isOpen, setIsOpen] = useState(defaultProps.isOpen || !1), containerRef = useRef(null), backdropRef = useRef(null), adjustBodyPadding = useCallback((() => {
-        if (!containerRef.current || "push" !== defaultProps.mode) return;
-        const {position: position} = defaultProps, size = "top" === position || "bottom" === position ? containerRef.current.clientHeight : containerRef.current.clientWidth;
+    const {position: position = "start", mode: mode = "slide", isOpen: propIsOpen = !1, backdrop: backdrop = !0, closeOnBackdropClick: closeOnBackdropClick = !0, closeOnEscape: closeOnEscape = !0, glass: glass, onOpenChange: onOpenChange, className: className = ""} = initialProps || {}, [isOpen, setIsOpen] = useState(propIsOpen || !1), containerRef = useRef(null), backdropRef = useRef(null), adjustBodyPadding = useCallback((() => {
+        if (!containerRef.current || "push" !== mode) return;
+        const size = "top" === position || "bottom" === position ? containerRef.current.clientHeight : containerRef.current.clientWidth;
         // Map position to CSS padding property
-        let paddingProperty;
+                let paddingProperty;
         switch (position) {
           case "start":
             paddingProperty = "paddingLeft";
@@ -11936,9 +12047,8 @@ function useEdgePanel(initialProps) {
             paddingProperty = `padding${position.charAt(0).toUpperCase() + position.slice(1)}`;
         }
         document.body.style[paddingProperty] = `${size}px`, document.body.classList.add("is-pushed");
-    }), [ defaultProps.mode, defaultProps.position ]), resetBodyPadding = useCallback((() => {
-        if ("push" !== defaultProps.mode) return;
-        const {position: position} = defaultProps;
+    }), [ mode, position ]), resetBodyPadding = useCallback((() => {
+        if ("push" !== mode) return;
         // Map position to CSS padding property
                 let paddingProperty;
         switch (position) {
@@ -11955,11 +12065,10 @@ function useEdgePanel(initialProps) {
             paddingProperty = `padding${position.charAt(0).toUpperCase() + position.slice(1)}`;
         }
         document.body.style[paddingProperty] = "", document.body.classList.remove("is-pushed");
-    }), [ defaultProps.mode, defaultProps.position ]), openPanel = useCallback(((useFadeAnimation = !1) => {
+    }), [ mode, position ]), openPanel = useCallback(((useFadeAnimation = !1) => {
         if (setIsOpen(!0), document.body.classList.add("is-edgepanel-open"), containerRef.current) {
-            const {mode: mode} = defaultProps;
             // Only add animation if not in 'none' mode
-                        if ("none" !== mode) if (useFadeAnimation) {
+            if ("none" !== mode) if (useFadeAnimation) {
                 // Add fade animation class
                 containerRef.current.classList.add("is-fade-animating"), containerRef.current.offsetHeight;
                 // Remove animation class after animation completes
@@ -11979,14 +12088,13 @@ function useEdgePanel(initialProps) {
             // Set transform or opacity based on animation type
                         useFadeAnimation ? (containerRef.current.style.opacity = "1", containerRef.current.style.transform = "") : containerRef.current.style.transform = "translate(0)", 
             // If push mode, adjust body padding
-            "push" === defaultProps.mode && adjustBodyPadding();
+            "push" === mode && adjustBodyPadding();
         }
-        defaultProps.onOpenChange && defaultProps.onOpenChange(!0);
-    }), [ defaultProps, adjustBodyPadding ]), closePanel = useCallback(((useFadeAnimation = !1) => {
+        onOpenChange && onOpenChange(!0);
+    }), [ mode, adjustBodyPadding, onOpenChange ]), closePanel = useCallback(((useFadeAnimation = !1) => {
         if (containerRef.current) {
-            const {position: position, mode: mode} = defaultProps;
             // Only add animation if not in 'none' mode
-                        if ("none" !== mode) if (useFadeAnimation) {
+            if ("none" !== mode) if (useFadeAnimation) {
                 // Add fade out animation class
                 containerRef.current.classList.add("is-fade-animating-out");
                 // Capture container for setTimeout
@@ -12008,46 +12116,42 @@ function useEdgePanel(initialProps) {
             // Then set transform
             containerRef.current.style.transform = position ? EDGE_PANEL.TRANSFORM_VALUES[position] : "", 
             // Reset body padding if push mode
-            "push" === defaultProps.mode && resetBodyPadding(), setTimeout((() => {
-                setIsOpen(!1), document.body.classList.remove("is-edgepanel-open"), defaultProps.onOpenChange && defaultProps.onOpenChange(!1);
+            "push" === mode && resetBodyPadding(), setTimeout((() => {
+                setIsOpen(!1), document.body.classList.remove("is-edgepanel-open"), onOpenChange && onOpenChange(!1);
             }), "none" === mode ? 0 : EDGE_PANEL.ANIMATION_DURATION);
-        } else setIsOpen(!1), document.body.classList.remove("is-edgepanel-open"), defaultProps.onOpenChange && defaultProps.onOpenChange(!1);
-    }), [ defaultProps, resetBodyPadding ]), handleEscapeKey = useCallback((event => {
-        defaultProps.closeOnEscape && "Escape" === event.key && isOpen && closePanel();
-    }), [ closePanel, defaultProps.closeOnEscape, isOpen ]), handleBackdropClick = useCallback((event => {
-        defaultProps.closeOnBackdropClick && event.target === event.currentTarget && closePanel();
-    }), [ closePanel, defaultProps.closeOnBackdropClick ]);
+        } else setIsOpen(!1), document.body.classList.remove("is-edgepanel-open"), onOpenChange && onOpenChange(!1);
+    }), [ mode, position, onOpenChange, resetBodyPadding ]), handleEscapeKey = useCallback((event => {
+        closeOnEscape && "Escape" === event.key && isOpen && closePanel();
+    }), [ closePanel, closeOnEscape, isOpen ]), handleBackdropClick = useCallback((event => {
+        closeOnBackdropClick && event.target === event.currentTarget && closePanel();
+    }), [ closePanel, closeOnBackdropClick ]);
     /**
    * Set up event listeners for keyboard events
    */
-    return useEffect((() => (isOpen && defaultProps.closeOnEscape && document.addEventListener("keydown", handleEscapeKey), 
+    return useEffect((() => (isOpen && closeOnEscape && document.addEventListener("keydown", handleEscapeKey), 
     () => {
         document.removeEventListener("keydown", handleEscapeKey);
-    })), [ isOpen, handleEscapeKey, defaultProps.closeOnEscape ]), 
+    })), [ isOpen, handleEscapeKey, closeOnEscape ]), 
     /**
    * Set initial transform values
    */
     useEffect((() => {
-        if (containerRef.current) {
-            const {position: position, mode: mode} = defaultProps;
-            isOpen || "slide" !== mode && "push" !== mode || !position || (containerRef.current.style.transform = EDGE_PANEL.TRANSFORM_VALUES[position], 
-            // Set initial opacity for fade animations
-            defaultProps.glass && (containerRef.current.style.opacity = "0"));
-        }
-    }), [ defaultProps.mode, defaultProps.position, defaultProps.glass, isOpen ]), 
+        containerRef.current && (isOpen || "slide" !== mode && "push" !== mode || !position || (containerRef.current.style.transform = EDGE_PANEL.TRANSFORM_VALUES[position], 
+        // Set initial opacity for fade animations
+        glass && (containerRef.current.style.opacity = "0")));
+    }), [ mode, position, glass, isOpen ]), 
     /**
    * Sync with prop changes
    */
     useEffect((() => {
-        void 0 !== defaultProps.isOpen && defaultProps.isOpen !== isOpen && (defaultProps.isOpen ? openPanel(!!defaultProps.glass) : closePanel(!!defaultProps.glass));
-    }), [ defaultProps.isOpen, closePanel, isOpen, openPanel, defaultProps.glass ]), 
-    {
+        void 0 !== propIsOpen && propIsOpen !== isOpen && (propIsOpen ? openPanel(!!glass) : closePanel(!!glass));
+    }), [ propIsOpen, closePanel, isOpen, openPanel, glass ]), {
         isOpen: isOpen,
         containerRef: containerRef,
         backdropRef: backdropRef,
         generateEdgePanelClass: props => {
-            const {position: position = defaultProps.position, className: className = "", isOpen: propIsOpen} = props, baseClass = EDGE_PANEL.CLASSES.BASE;
-            return `${baseClass} ${position ? `${baseClass}--${position}` : ""} ${propIsOpen ?? isOpen ? EDGE_PANEL.CLASSES.IS_OPEN : ""} ${className}`.trim();
+            const {position: propPosition = position, className: propClassName = className, isOpen: argIsOpen} = props, baseClass = EDGE_PANEL.CLASSES.BASE;
+            return `${baseClass} ${propPosition ? `${baseClass}--${propPosition}` : ""} ${argIsOpen ?? isOpen ? EDGE_PANEL.CLASSES.IS_OPEN : ""} ${propClassName}`.trim();
         },
         openPanel: openPanel,
         closePanel: closePanel,
@@ -12429,7 +12533,7 @@ function useHero(initialProps) {
  * @returns Slider state and methods
  */
     function(config) {
-        const {slides: slides, autoplay: autoplay, loop: loop = !0, transition: transition = "fade", transitionDuration: transitionDuration = 1e3} = config, [currentIndex, setCurrentIndex] = useState(0), [isTransitioning, setIsTransitioning] = useState(!1), autoplayRef = useRef(null), isPausedRef = useRef(!1), callbackRef = useRef(), slideRefs = useMemo((() => slides.map((() =>  React.createRef()))), [ slides.length ]), videoRefs = useMemo((() => slides.map((() =>  React.createRef()))), [ slides.length ]), handleSlideTransition = useCallback((nextIndex => {
+        const {slides: slides, autoplay: autoplay, loop: loop = !0, transition: transition = "fade", transitionDuration: transitionDuration = 1e3} = config, [currentIndex, setCurrentIndex] = useState(0), [isTransitioning, setIsTransitioning] = useState(!1), autoplayRef = useRef(null), isPausedRef = useRef(!1), callbackRef = useRef(void 0), slideRefs = useMemo((() => slides.map((() =>  React.createRef()))), [ slides ]), videoRefs = useMemo((() => slides.map((() =>  React.createRef()))), [ slides ]), handleSlideTransition = useCallback((nextIndex => {
             if (nextIndex === currentIndex || isTransitioning) return;
             if (nextIndex < 0 || nextIndex >= slides.length) return;
             setIsTransitioning(!0), 
@@ -12748,22 +12852,15 @@ function useHero(initialProps) {
  * @param initialProps - Initial side menu properties
  * @returns SideMenu state and methods
  */ function useSideMenu(initialProps) {
-    // Default side menu properties
-    const defaultProps = {
-        collapsible: !0,
-        collapsibleDesktop: !1,
-        defaultCollapsedDesktop: !1,
-        isOpen: !1,
-        ...initialProps
-    }, [isOpenState, setIsOpenState] = useState(void 0 !== defaultProps.defaultCollapsedDesktop ? !defaultProps.defaultCollapsedDesktop : defaultProps.isOpen || !1), wrapperRef = useRef(null), innerRef = useRef(null), sideMenuRef = useRef(null);
+    const {collapsible: collapsible = !0, collapsibleDesktop: collapsibleDesktop = !1, defaultCollapsedDesktop: defaultCollapsedDesktop = !1, isOpen: isOpen, onToggle: onToggle, disabled: disabled = !1} = initialProps || {}, [isOpenState, setIsOpenState] = useState(void 0 !== defaultCollapsedDesktop ? !defaultCollapsedDesktop : isOpen || !1), wrapperRef = useRef(null), innerRef = useRef(null), sideMenuRef = useRef(null);
     // Local open state for when not controlled externally
         // Update local state when external state changes
     useEffect((() => {
-        void 0 !== defaultProps.isOpen ? setIsOpenState(defaultProps.isOpen) : void 0 !== defaultProps.defaultCollapsedDesktop && setIsOpenState(!defaultProps.defaultCollapsedDesktop);
-    }), [ defaultProps.isOpen, defaultProps.defaultCollapsedDesktop ]), 
+        void 0 !== isOpen ? setIsOpenState(isOpen) : void 0 !== defaultCollapsedDesktop && setIsOpenState(!defaultCollapsedDesktop);
+    }), [ isOpen, defaultCollapsedDesktop ]), 
     // Set initial height on mount
     useEffect((() => {
-        const shouldCollapse = window.innerWidth < 768 ? defaultProps.collapsible : defaultProps.collapsibleDesktop, currentOpen = void 0 !== defaultProps.isOpen ? defaultProps.isOpen : isOpenState;
+        const shouldCollapse = window.innerWidth < 768 ? collapsible : collapsibleDesktop, currentOpen = void 0 !== isOpen ? isOpen : isOpenState;
         if (shouldCollapse && wrapperRef.current && innerRef.current) {
             // Use setTimeout to ensure DOM is fully rendered
             const timeoutId = setTimeout((() => {
@@ -12772,14 +12869,14 @@ function useHero(initialProps) {
             return () => clearTimeout(timeoutId);
         }
         !shouldCollapse && wrapperRef.current && (wrapperRef.current.style.height = "auto");
-    }), []), // Only run on mount
+    }), [ collapsible, collapsibleDesktop, isOpen, isOpenState ]), 
     // Handle responsive behavior - vertical collapse for both mobile and desktop
     useEffect((() => {
         const handleResize = () => {
-            if (window.innerWidth < 768 ? defaultProps.collapsible : defaultProps.collapsibleDesktop) {
+            if (window.innerWidth < 768 ? collapsible : collapsibleDesktop) {
                 if (wrapperRef.current && innerRef.current) {
                     // Set proper height for vertical animation (both mobile and desktop)
-                    const currentOpen = void 0 !== defaultProps.isOpen ? defaultProps.isOpen : isOpenState;
+                    const currentOpen = void 0 !== isOpen ? isOpen : isOpenState;
                     // Use requestAnimationFrame to ensure DOM is ready
                                         requestAnimationFrame((() => {
                         wrapperRef.current && innerRef.current && (wrapperRef.current.style.height = currentOpen ? `${innerRef.current.scrollHeight}px` : "0px");
@@ -12793,12 +12890,12 @@ function useHero(initialProps) {
                 return window.addEventListener("resize", handleResize), () => {
             clearTimeout(timeoutId), window.removeEventListener("resize", handleResize);
         };
-    }), [ defaultProps.collapsible, defaultProps.collapsibleDesktop, defaultProps.isOpen, defaultProps.onToggle, isOpenState ]), 
+    }), [ collapsible, collapsibleDesktop, isOpen, onToggle, isOpenState ]), 
     // Update wrapper height when open state changes (both mobile and desktop)
     useEffect((() => {
-        const shouldCollapse = window.innerWidth < 768 ? defaultProps.collapsible : defaultProps.collapsibleDesktop;
+        const shouldCollapse = window.innerWidth < 768 ? collapsible : collapsibleDesktop;
         if (shouldCollapse && wrapperRef.current && innerRef.current) {
-            const currentOpen = void 0 !== defaultProps.isOpen ? defaultProps.isOpen : isOpenState;
+            const currentOpen = void 0 !== isOpen ? isOpen : isOpenState;
             // Use requestAnimationFrame to ensure DOM is ready
                         requestAnimationFrame((() => {
                 wrapperRef.current && innerRef.current && (wrapperRef.current.style.height = currentOpen ? `${innerRef.current.scrollHeight}px` : "0px");
@@ -12806,26 +12903,25 @@ function useHero(initialProps) {
         } else !shouldCollapse && wrapperRef.current && (
         // Not collapsible - always show content
         wrapperRef.current.style.height = "auto");
-    }), [ defaultProps.isOpen, isOpenState, defaultProps.collapsible, defaultProps.collapsibleDesktop ]);
+    }), [ isOpen, isOpenState, collapsible, collapsibleDesktop ]);
     /**
    * Generate side menu class based on properties
    * @param props - Side menu properties
    * @returns Class string
    */
     const handleToggle = () => {
-        if (defaultProps.disabled) return;
-        const newState = void 0 !== defaultProps.isOpen ? !defaultProps.isOpen : !isOpenState;
-        "function" == typeof defaultProps.onToggle ? 
+        if (disabled) return;
+        const newState = void 0 !== isOpen ? !isOpen : !isOpenState;
+        "function" == typeof onToggle ? 
         // Controlled component
-        defaultProps.onToggle(newState) : 
+        onToggle(newState) : 
         // Uncontrolled component
         setIsOpenState(newState);
-    }, getCurrentOpenState = () => void 0 !== defaultProps.isOpen ? defaultProps.isOpen : isOpenState;
+    }, getCurrentOpenState = () => void 0 !== isOpen ? isOpen : isOpenState;
     /**
    * Generate wrapper class
    * @returns Class string
    */    return {
-        defaultProps: defaultProps,
         isOpenState: getCurrentOpenState(),
         wrapperRef: wrapperRef,
         innerRef: innerRef,
@@ -13410,21 +13506,21 @@ function useTodo(initialProps) {
     const [interaction, setInteraction] = useState({
         hoveredIndex: null,
         selectedIndex: null
-    });
+    }), handlePointHover = useCallback((index => {
+        setInteraction((prev => ({
+            ...prev,
+            hoveredIndex: index
+        })));
+    }), []), handlePointClick = useCallback((index => {
+        setInteraction((prev => ({
+            ...prev,
+            selectedIndex: prev.selectedIndex === index ? null : index
+        })));
+    }), []);
     return {
         interaction: interaction,
-        handlePointHover: useCallback((index => {
-            setInteraction((prev => ({
-                ...prev,
-                hoveredIndex: index
-            })));
-        }), []),
-        handlePointClick: useCallback((index => {
-            setInteraction((prev => ({
-                ...prev,
-                selectedIndex: prev.selectedIndex === index ? null : index
-            })));
-        }), []),
+        handlePointHover: handlePointHover,
+        handlePointClick: handlePointClick,
         clearInteraction: useCallback((() => {
             setInteraction({
                 hoveredIndex: null,
@@ -13467,7 +13563,7 @@ const composablesImport =  Object.freeze( Object.defineProperty({
     useNavDropdown: useNavDropdown,
     useNavItem: useNavItem,
     useNavbar: useNavbar,
-    usePerformanceMonitor: usePerformanceMonitor,
+    usePerformanceMonitor: usePerformanceMonitor$1,
     usePieChart: usePieChart,
     useRadio: useRadio,
     useResponsiveGlass: useResponsiveGlass,
@@ -13530,7 +13626,7 @@ SelectOption.displayName = "SelectOption";
 /**
  * Select - A component for dropdown selection
  */
-const Select =  memo((({options: options, value: value, onChange: onChange, onBlur: onBlur, onFocus: onFocus, placeholder: placeholder = "Select an option", className: className = "", style: style, disabled: disabled = !1, required: required = !1, id: id, name: name, size: size = "md", invalid: invalid = !1, valid: valid = !1, multiple: multiple = !1, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, glass: glass, children: children}) => {
+const SelectComponentBase = ({options: options, value: value, onChange: onChange, onBlur: onBlur, onFocus: onFocus, placeholder: placeholder = "Select an option", className: className = "", style: style, disabled: disabled = !1, required: required = !1, id: id, name: name, size: size = "md", invalid: invalid = !1, valid: valid = !1, multiple: multiple = !1, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, glass: glass, children: children}) => {
     const {generateSelectClass: generateSelectClass} = useSelect({
         size: size,
         disabled: disabled,
@@ -13721,7 +13817,7 @@ const Select =  memo((({options: options, value: value, onChange: onChange, onBl
         });
     }
     return selectContent;
-}));
+}, Select =  memo(SelectComponentBase);
 
 Select.displayName = "Select", Select.Option = SelectOption;
 
@@ -14288,7 +14384,7 @@ Footer.displayName = "Footer";
  */
 const MasonryGrid =  forwardRef((({children: children, className: className = "", xs: xs = 1, sm: sm, md: md, lg: lg, xl: xl, xxl: xxl, gap: gap = 16, animate: animate = !0, imagesLoaded: imagesLoaded = !0, onLayoutComplete: onLayoutComplete, onImageLoad: onImageLoad, ...props}, ref) => {
     // === REFS & STATE ===
-    const [columns, setColumns] = useState(xs), [positions, setPositions] = useState([]), [layoutComplete, setLayoutComplete] = useState(!1), [loadingImages, setLoadingImages] = useState(!1), containerRef = useRef(null), columnHeights = useRef([]), imagesLoadedCount = useRef(0), totalImagesCount = useRef(0), imageElements = useRef(new Map);
+    const [columns, setColumns] = useState(xs), [positions, setPositions] = useState([]), [, setLayoutComplete] = useState(!1), [loadingImages, setLoadingImages] = useState(!1), containerRef = useRef(null), columnHeights = useRef([]), imagesLoadedCount = useRef(0), totalImagesCount = useRef(0), imageElements = useRef(new Map);
     useEffect((() => {
         setLoadingImages(!!imagesLoaded);
     }), [ columns, imagesLoaded ]), 
@@ -14317,34 +14413,45 @@ const MasonryGrid =  forwardRef((({children: children, className: className = ""
             });
         })), setItems(newItems);
     }), [ children ]);
-    // === TRACK & MANAGE IMAGES ===
-    const handleImageLoad = useCallback((img => {
-        if (!imageElements.current.get(img)) {
-            // Add loaded class for animation
-            if (imageElements.current.set(img, !0), imagesLoadedCount.current += 1, containerRef.current && imagesLoaded) {
-                const itemElement = img.closest(".o-masonry-grid > div");
-                itemElement && (itemElement.offsetHeight, itemElement.classList.add("o-masonry-grid__item-loaded"), 
-                itemElement.classList.remove("o-masonry-grid__item-loading"));
+    // === MANAGE ITEM LAYOUT ===
+    const calculateLayout = useCallback((() => {
+        if (!containerRef.current || 0 === items.length) return;
+        const colWidth = (containerRef.current.offsetWidth - gap * (columns - 1)) / columns;
+        columnHeights.current = Array(columns).fill(0);
+        const newPositions = [];
+        items.forEach(((item, index) => {
+            if (item.ref.current) {
+                // Find the shortest column
+                const shortestCol = columnHeights.current.indexOf(Math.min(...columnHeights.current)), left = shortestCol * (colWidth + gap), top = columnHeights.current[shortestCol] ?? 0, height = item.ref.current.offsetHeight;
+                columnHeights.current[shortestCol] = top + height + gap, newPositions[index] = {
+                    left: left,
+                    top: top,
+                    width: colWidth,
+                    height: height
+                };
             }
-            // Ensure layout is recalculated after DOM paints the item image (prevents overlap on slow/late image loads)
-                        requestAnimationFrame((() => {
-                requestAnimationFrame((() => {
-                    calculateLayout();
-                }));
-            })), onImageLoad?.(imagesLoadedCount.current, totalImagesCount.current), 
-            // If all images have loaded, update loading state and complete layout
-            imagesLoadedCount.current >= totalImagesCount.current && totalImagesCount.current > 0 && (setLayoutComplete(!0), 
-            setLoadingImages(!1), // This ensures the loading class is removed *immediately* after images load
-            // Force a double requestAnimationFrame for final layout calculation after all images are loaded (guarantees DOM paint)
-            requestAnimationFrame((() => {
-                requestAnimationFrame((() => {
-                    calculateLayout(), 
-                    // As a failsafe, if still present for some render lag, force another setLoadingImages(false)
-                    setLoadingImages(!1);
-                }));
-            })), onLayoutComplete?.());
+        })), setPositions(newPositions);
+    }), [ items, columns, gap ]), handleImageLoad = useCallback((img => {
+        if (imageElements.current.get(img)) return;
+        // Add loaded class for animation
+        if (imageElements.current.set(img, !0), imagesLoadedCount.current += 1, containerRef.current && imagesLoaded) {
+            const itemElement = img.closest(".o-masonry-grid > div");
+            itemElement && (itemElement.offsetHeight, itemElement.classList.add("o-masonry-grid__item-loaded"), 
+            itemElement.classList.remove("o-masonry-grid__item-loading"));
         }
-    }), [ onImageLoad, onLayoutComplete, imagesLoaded ]), trackImages = useCallback((() => {
+        // Schedule layout recalculation after next paint to prevent overlap
+                const scheduleLayoutUpdate = () => {
+            const frameId = requestAnimationFrame((() => {
+                onImageLoad?.(imagesLoadedCount.current, totalImagesCount.current), calculateLayout();
+            }));
+            return () => cancelAnimationFrame(frameId);
+        }, cleanup = scheduleLayoutUpdate();
+        // Clean up previous scheduled updates
+                // If all images have loaded, update loading state and complete layout
+        imagesLoadedCount.current >= totalImagesCount.current && totalImagesCount.current > 0 && (setLayoutComplete(!0), 
+        setLoadingImages(!1), setTimeout((() => cleanup()), 0), // Clean up after current execution
+        scheduleLayoutUpdate(), onLayoutComplete?.());
+    }), [ onImageLoad, onLayoutComplete, imagesLoaded, calculateLayout ]), trackImages = useCallback((() => {
         if (!imagesLoaded || !containerRef.current) return;
         imageElements.current.clear(), imagesLoadedCount.current = 0;
         const images = containerRef.current.querySelectorAll("img");
@@ -14363,30 +14470,21 @@ const MasonryGrid =  forwardRef((({children: children, className: className = ""
                 img.removeEventListener("error", masonryImg._masonryLoadHandler), delete masonryImg._masonryLoadHandler);
             }));
         });
-    }), [ imagesLoaded, handleImageLoad, onLayoutComplete ]), calculateLayout = useCallback((() => {
-        if (!containerRef.current || 0 === items.length) return;
-        const colWidth = (containerRef.current.offsetWidth - gap * (columns - 1)) / columns;
-        columnHeights.current = Array(columns).fill(0);
-        const newPositions = [];
-        items.forEach(((item, index) => {
-            if (item.ref.current) {
-                // Find the shortest column
-                const shortestCol = columnHeights.current.indexOf(Math.min(...columnHeights.current)), left = shortestCol * (colWidth + gap), top = columnHeights.current[shortestCol] ?? 0, height = item.ref.current.offsetHeight;
-                columnHeights.current[shortestCol] = top + height + gap, newPositions[index] = {
-                    left: left,
-                    top: top,
-                    width: colWidth,
-                    height: height
-                };
-            }
-        })), setPositions(newPositions);
-    }), [ items, columns, gap ]);
-    // === OBSERVE CONTAINER RESIZE ===
+    }), [ imagesLoaded, handleImageLoad, onLayoutComplete ]);
+    // === TRACK & MANAGE IMAGES ===
+        // === OBSERVE CONTAINER RESIZE ===
     useEffect((() => {
         if (!containerRef.current) return;
-        let animationFrame = null;
-        const observer = new ResizeObserver((() => {
-            animationFrame && cancelAnimationFrame(animationFrame), animationFrame = requestAnimationFrame((() => calculateLayout()));
+        let animationFrame = null, lastWidth = 0;
+        const observer = new ResizeObserver((entries => {
+            const entry = entries[0];
+            if (!entry) return;
+            const currentWidth = entry.contentRect.width;
+            // Only recalculate if width actually changed (prevents excessive calculations)
+                        Math.abs(currentWidth - lastWidth) > 1 && (animationFrame && cancelAnimationFrame(animationFrame), 
+            animationFrame = requestAnimationFrame((() => {
+                calculateLayout(), lastWidth = currentWidth;
+            })));
         }));
         return observer.observe(containerRef.current), () => {
             observer.disconnect(), animationFrame && cancelAnimationFrame(animationFrame);
@@ -14397,24 +14495,21 @@ const MasonryGrid =  forwardRef((({children: children, className: className = ""
     setLayoutComplete(!0), void setLoadingImages(!1))
     // Only reset layoutComplete when items or columns change
     ), [ items, columns, calculateLayout, imagesLoaded, trackImages ]), 
-    // === NEW: Add ResizeObservers to all grid items for bulletproof image+content measurement ===
+    // === ADD RESIZEOBSERVERS TO GRID ITEMS FOR DYNAMIC CONTENT MEASUREMENT ===
     React.useEffect((() => {
-        // Clean up old observers if items ever change
         const observers = [];
+        let animationFrame = null;
+        // Debounced layout calculation for item resize events
+                const debouncedCalculateLayout = () => {
+            animationFrame && cancelAnimationFrame(animationFrame), animationFrame = requestAnimationFrame(calculateLayout);
+        };
         return items.forEach((item => {
             if (item.ref.current) {
-                const obs = new ResizeObserver((() => {
-                    // Double rAF: ensures layout only runs after DOM/paint/async renders
-                    requestAnimationFrame((() => {
-                        requestAnimationFrame((() => {
-                            calculateLayout();
-                        }));
-                    }));
-                }));
+                const obs = new ResizeObserver(debouncedCalculateLayout);
                 obs.observe(item.ref.current), observers.push(obs);
             }
         })), () => {
-            observers.forEach((obs => obs.disconnect()));
+            observers.forEach((obs => obs.disconnect())), animationFrame && cancelAnimationFrame(animationFrame);
         };
     }), [ items, calculateLayout ]);
     // Ensure loadingImages state resets when items/columns/imagesLoaded change
@@ -15851,12 +15946,12 @@ const SideMenu =  forwardRef((({title: title, children: children, menuItems: men
             const index = Number(key);
             index >= currentLength && (delete nestedWrapperRefs.current[index], delete nestedInnerRefs.current[index]);
         })));
-    }), [ menuItems?.length ]);
+    }), [ menuItems ]);
     // Helper function to update nested wrapper height
-    const updateNestedHeight = (index, isOpen) => {
+    const updateNestedHeight = useCallback(((index, isOpen) => {
         const wrapper = nestedWrapperRefs.current[index], inner = nestedInnerRefs.current[index];
         wrapper && inner && (wrapper.style.height = isOpen ? `${inner.scrollHeight}px` : "0px");
-    };
+    }), []);
     // Set initial heights for nested wrappers on mount and when menuItems change
         useEffect((() => {
         if (!menuItems?.length) return;
@@ -15870,7 +15965,7 @@ const SideMenu =  forwardRef((({title: title, children: children, menuItems: men
         // Only run when menuItems change, nestedItemStates is read but not in deps to avoid loops
         // eslint-disable-next-line react-hooks/exhaustive-deps
         ;
-    }), [ menuItems?.length ]), 
+    }), [ menuItems, updateNestedHeight ]), 
     // Update nested wrapper heights when state changes
     useEffect((() => {
         if (!menuItems?.length) return;
@@ -15883,7 +15978,7 @@ const SideMenu =  forwardRef((({title: title, children: children, menuItems: men
         })), () => {
             frameIds.forEach((id => cancelAnimationFrame(id)));
         };
-    }), [ nestedItemStates, menuItems?.length ]);
+    }), [ nestedItemStates, menuItems, updateNestedHeight ]);
     // Combine refs using utility
     const combinedRef = useForkRef(sideMenuRef, ref), sideMenuClass = generateSideMenuClass({
         className: className,
@@ -16770,7 +16865,7 @@ useEffect((() => {
                     }
                 };
             }));
-        }), [ isMounted, currentIndex, calculateBounds, constrainPosition ]), setImagePosition = useCallback((position => {
+        }), [ currentIndex, calculateBounds, constrainPosition ]), setImagePosition = useCallback((position => {
             setImageStates((prev => {
                 const currentState = prev[currentIndex] || {
                     zoomLevel: 1,
@@ -16820,7 +16915,7 @@ useEffect((() => {
                     }
                 };
             }));
-        }), [ isMounted, currentIndex, calculateBounds, constrainPosition ]), handleWheel = useCallback((event => {
+        }), [ currentIndex, calculateBounds, constrainPosition ]), handleWheel = useCallback((event => {
             var _context;
             if (!isMounted || !event || !event.currentTarget) return;
             // Additional safety check for the target element
@@ -17177,7 +17272,7 @@ useEffect((() => {
                 }
                 return prev;
             }));
-        }), [ isMounted, enableGestures, isDragging, startDragPosition, currentIndex, constrainPosition, calculateBounds ]), handleTouchEnd = useCallback((() => {
+        }), [ enableGestures, isDragging, startDragPosition, currentIndex, constrainPosition, calculateBounds ]), handleTouchEnd = useCallback((() => {
             setIsDragging(!1), lastDistanceRef.current = null, lastMidpointRef.current = null;
         }), []), currentState = imageStates[currentIndex] || {
             zoomLevel: 1,
@@ -17381,9 +17476,9 @@ const PopoverContext =  createContext({
     triggerType: "click"
 }), Popover = ({content: content, position: position = "top", trigger: trigger = "click", className: className = "", style: style, delay: delay = 0, offset: offset = 12, defaultOpen: defaultOpen = !1, isOpen: controlledIsOpen, onOpenChange: onOpenChange, closeOnClickOutside: closeOnClickOutside = !0, closeOnEscape: closeOnEscape = !0, id: id, children: children, glass: glass}) => {
     const {isOpen: isOpen, setIsOpen: setIsOpen, triggerRef: triggerRef, popoverRef: popoverRef, arrowRef: arrowRef, popoverId: popoverId, currentPosition: currentPosition, updatePosition: updatePosition} = (({position: position = "top", trigger: trigger = "click", offset: offset = 12, delay: delay = 0, defaultOpen: defaultOpen = !1, isOpen: controlledIsOpen, onOpenChange: onOpenChange, closeOnClickOutside: closeOnClickOutside = !0, closeOnEscape: closeOnEscape = !0, id: id}) => {
-        const [isOpen, setIsOpenState] = useState(defaultOpen), [currentPosition, setCurrentPosition] = useState("auto" === position ? "top" : position), triggerRef = useRef(null), popoverRef = useRef(null), arrowRef = useRef(null), timeoutRef = useRef(null), popoverId = id || `popover-${Math.random().toString(36).slice(2, 11)}`, isControlled = void 0 !== controlledIsOpen, isOpenState = isControlled ? controlledIsOpen : isOpen, setIsOpen = newIsOpen => {
+        const [isOpen, setIsOpenState] = useState(defaultOpen), [currentPosition, setCurrentPosition] = useState("auto" === position ? "top" : position), triggerRef = useRef(null), popoverRef = useRef(null), arrowRef = useRef(null), timeoutRef = useRef(null), popoverId = id || `popover-${Math.random().toString(36).slice(2, 11)}`, isControlled = void 0 !== controlledIsOpen, isOpenState = isControlled ? controlledIsOpen : isOpen, setIsOpen = useCallback((newIsOpen => {
             isControlled || setIsOpenState(newIsOpen), onOpenChange && onOpenChange(newIsOpen);
-        };
+        }), [ isControlled, onOpenChange ]);
         // Handle hover events if trigger is hover
         useEffect((() => {
             if ("hover" !== trigger || !triggerRef.current || !popoverRef.current) return;
@@ -17403,17 +17498,16 @@ const PopoverContext =  createContext({
                 setIsOpen(!1);
             };
             // Add hover event listeners
-            return triggerRef.current.addEventListener("mouseenter", handleTriggerMouseEnter), 
-            triggerRef.current.addEventListener("mouseleave", handleTriggerMouseLeave), popoverRef.current.addEventListener("mouseenter", handlePopoverMouseEnter), 
-            popoverRef.current.addEventListener("mouseleave", handlePopoverMouseLeave), () => {
-                triggerRef.current && (triggerRef.current.removeEventListener("mouseenter", handleTriggerMouseEnter), 
-                triggerRef.current.removeEventListener("mouseleave", handleTriggerMouseLeave)), 
-                popoverRef.current && (popoverRef.current.removeEventListener("mouseenter", handlePopoverMouseEnter), 
-                popoverRef.current.removeEventListener("mouseleave", handlePopoverMouseLeave)), 
-                null !== timeoutRef.current && window.clearTimeout(timeoutRef.current);
+            triggerRef.current.addEventListener("mouseenter", handleTriggerMouseEnter), triggerRef.current.addEventListener("mouseleave", handleTriggerMouseLeave), 
+            popoverRef.current.addEventListener("mouseenter", handlePopoverMouseEnter), popoverRef.current.addEventListener("mouseleave", handlePopoverMouseLeave);
+            const currentTrigger = triggerRef.current, currentPopover = popoverRef.current;
+            return () => {
+                currentTrigger && (currentTrigger.removeEventListener("mouseenter", handleTriggerMouseEnter), 
+                currentTrigger.removeEventListener("mouseleave", handleTriggerMouseLeave)), currentPopover && (currentPopover.removeEventListener("mouseenter", handlePopoverMouseEnter), 
+                currentPopover.removeEventListener("mouseleave", handlePopoverMouseLeave)), null !== timeoutRef.current && window.clearTimeout(timeoutRef.current);
             };
-        }), [ trigger, delay, isOpenState ]);
-        const updatePosition = event => {
+        }), [ trigger, delay, isOpenState, setIsOpen ]);
+        const updatePosition = useCallback((event => {
             if (!triggerRef.current || !popoverRef.current) return;
             const triggerRect = triggerRef.current.getBoundingClientRect(), popoverRect = popoverRef.current.getBoundingClientRect(), viewportWidth = window.innerWidth, viewportHeight = window.innerHeight, isNearViewportEdge = triggerRect.top < 50 || triggerRect.bottom > viewportHeight - 50 || triggerRect.left < 50 || triggerRect.right > viewportWidth - 50;
             // If this is a scroll update and trigger isn't near edges, skip repositioning
@@ -17474,9 +17568,9 @@ const PopoverContext =  createContext({
             // Add scroll position to convert viewport coordinates to absolute position
             const absoluteTop = top + window.scrollY, absoluteLeft = left + window.scrollX;
             // Apply position using absolute positioning to follow when scrolling
-            popoverRef.current.style.position = "absolute", popoverRef.current.style.top = `${absoluteTop}px`, 
-            popoverRef.current.style.left = `${absoluteLeft}px`;
-        };
+            popoverRef.current && (popoverRef.current.style.position = "absolute", popoverRef.current.style.top = `${absoluteTop}px`, 
+            popoverRef.current.style.left = `${absoluteLeft}px`);
+        }), [ position, offset ]);
         // Position the popover
                 return useEffect((() => {
             if (!isOpenState || !triggerRef.current || !popoverRef.current) return;
@@ -17502,7 +17596,7 @@ const PopoverContext =  createContext({
                 window.removeEventListener("resize", updatePosition), window.removeEventListener("scroll", handleScroll), 
                 scrollTimeout && clearTimeout(scrollTimeout), clearInterval(intervalId);
             };
-        }), [ isOpenState, position, offset ]), 
+        }), [ isOpenState, updatePosition ]), 
         // Handle click outside to close popover
         useEffect((() => {
             if (!isOpenState || !closeOnClickOutside) return;
@@ -17512,7 +17606,7 @@ const PopoverContext =  createContext({
             return document.addEventListener("mousedown", handleClickOutside), () => {
                 document.removeEventListener("mousedown", handleClickOutside);
             };
-        }), [ isOpenState, closeOnClickOutside ]), 
+        }), [ isOpenState, closeOnClickOutside, setIsOpen ]), 
         // Handle escape key to close popover
         useEffect((() => {
             if (!isOpenState || !closeOnEscape) return;
@@ -17522,7 +17616,7 @@ const PopoverContext =  createContext({
             return document.addEventListener("keydown", handleEscapeKey), () => {
                 document.removeEventListener("keydown", handleEscapeKey);
             };
-        }), [ isOpenState, closeOnEscape ]), 
+        }), [ isOpenState, closeOnEscape, setIsOpen ]), 
         // Clean up on unmount
         useEffect((() => () => {
             null !== timeoutRef.current && window.clearTimeout(timeoutRef.current);
@@ -17703,10 +17797,11 @@ const calculateStarValue = (e, starValue, allowHalf) => {
     }), [ readOnly, onChange, allowHalf ]);
     // Use vanilla JS implementation if specified
     useEffect((() => {
-        if (useVanillaJS && "undefined" != typeof window && internalRef.current) 
+        if (!useVanillaJS || "undefined" == typeof window || !internalRef.current) return;
+        const currentInstance = ratingInstance.current;
         // Cleanup on unmount
-        return () => {
-            ratingInstance.current && ratingInstance.current.destroy();
+                return () => {
+            currentInstance && currentInstance.destroy();
         };
     }), [ useVanillaJS, valueProp, defaultValue, maxValue, allowHalf, readOnly, size, variant, onChange ]), 
     // Update vanilla JS implementation when props change
@@ -17827,10 +17922,11 @@ const ProductReview = ({productName: productName, productImage: productImage, in
     const [rating, setRating] = useState(initialRating), [comment, setComment] = useState(""), [submitted, setSubmitted] = useState(!1), reviewRef = useRef(null), reviewInstance = useRef(null);
     useEffect((() => {
         // Only run on client-side
-        if ("undefined" != typeof window && reviewRef.current) 
+        if ("undefined" == typeof window || !reviewRef.current) return;
+        const currentInstance = reviewInstance.current;
         // Cleanup on unmount
-        return () => {
-            reviewInstance.current && reviewInstance.current.destroy();
+                return () => {
+            currentInstance && currentInstance.destroy();
         };
     }), [ productName, productImage, initialRating, maxRating, allowHalf, ratingColor, onSubmit ]);
     const handleSubmit = e => {
@@ -18075,10 +18171,11 @@ const SectionIntro = ({title: title, label: label, text: text, actions: actions,
     const sectionIntroRef = useRef(null), sectionIntroInstance = useRef(null);
     useEffect((() => {
         // Only run on client-side
-        if ("undefined" != typeof window && sectionIntroRef.current) 
+        if ("undefined" == typeof window || !sectionIntroRef.current) return;
+        const currentInstance = sectionIntroInstance.current;
         // Cleanup on unmount
-        return () => {
-            sectionIntroInstance.current && sectionIntroInstance.current.destroy();
+                return () => {
+            currentInstance && currentInstance.destroy();
         };
     }), [ alignment, backgroundImageSrc, showOverlay, size, skeleton ]);
     // Determine CSS classes
@@ -18162,7 +18259,7 @@ SectionIntro.displayName = "SectionIntro";
 
 const Slider =  forwardRef(((props, ref) => {
     const {slides: slides = [], height: height = 300, width: width = "100%", slidesToShow: slidesToShow = 1, spaceBetween: spaceBetween = 0, loop: loop = !1, initialSlide: initialSlide = 0, direction: direction = "horizontal", speed: speed = 300, allowTouchMove: allowTouchMove = !0, threshold: threshold = 50, grabCursor: grabCursor = !0, autoplay: autoplay, navigation: navigation, pagination: pagination, className: className, style: style, onSlideChange: onSlideChange, ...rest} = props, validSlides = Array.isArray(slides) ? slides : [], slider = function(options) {
-        const {slides: rawSlides, slidesToShow: slidesToShow = 1, spaceBetween: spaceBetween = 0, loop: loop = !1, initialSlide: initialSlide = 0, direction: direction = "horizontal", speed: speed = 300, allowTouchMove: allowTouchMove = !0, threshold: threshold = 50, autoplay: autoplay, onSlideChange: onSlideChange} = options, slides = Array.isArray(rawSlides) ? rawSlides : [], containerRef = useRef(null), wrapperRef = useRef(null), repositioningRef = useRef(!1), autoplayRef = useRef(null), [autoplayRunning, setAutoplayRunning] = useState(!1), sliderStateRef = useRef({
+        const {slides: rawSlides, slidesToShow: slidesToShow = 1, spaceBetween: spaceBetween = 0, loop: loop = !1, initialSlide: initialSlide = 0, direction: direction = "horizontal", speed: speed = 300, allowTouchMove: allowTouchMove = !0, threshold: threshold = 50, autoplay: autoplay, onSlideChange: onSlideChange} = options, slides = useMemo((() => Array.isArray(rawSlides) ? rawSlides : []), [ rawSlides ]), containerRef = useRef(null), wrapperRef = useRef(null), repositioningRef = useRef(!1), autoplayRef = useRef(null), [autoplayRunning, setAutoplayRunning] = useState(!1), sliderStateRef = useRef({
             isTransitioning: !1,
             loop: loop,
             slides: slides,
@@ -18297,7 +18394,7 @@ const Slider =  forwardRef(((props, ref) => {
                     setIsTransitioning(!1), onSlideChange?.(nextIndex);
                 }), speed);
             }
-        }), [ realIndex, internalIndex, slides.length, slidesToShow, loop, isTransitioning, speed, onSlideChange, allSlides.length, loopedSlides, autoplay ]), slidePrev = useCallback((() => {
+        }), [ realIndex, internalIndex, slides.length, slidesToShow, loop, isTransitioning, speed, onSlideChange, autoplay ]), slidePrev = useCallback((() => {
             if (!isTransitioning) if (
             // Stop autoplay on interaction if disableOnInteraction is true
             autoplay && "object" == typeof autoplay && autoplay.disableOnInteraction && autoplayRef.current && (clearInterval(autoplayRef.current), 
@@ -18319,7 +18416,7 @@ const Slider =  forwardRef(((props, ref) => {
                     setIsTransitioning(!1), onSlideChange?.(prevIndex);
                 }), speed);
             }
-        }), [ realIndex, internalIndex, slides.length, loop, isTransitioning, speed, onSlideChange, allSlides.length, loopedSlides, autoplay ]), goToSlide = useCallback((index => {
+        }), [ realIndex, internalIndex, slides.length, loop, isTransitioning, speed, onSlideChange, autoplay ]), goToSlide = useCallback((index => {
             isTransitioning || index === realIndex || (
             // Stop autoplay on interaction if disableOnInteraction is true
             autoplay && "object" == typeof autoplay && autoplay.disableOnInteraction && autoplayRef.current && (clearInterval(autoplayRef.current), 
@@ -18327,7 +18424,7 @@ const Slider =  forwardRef(((props, ref) => {
             setRealIndex(index), setInternalIndex(loop ? slides.length + index : index), setTimeout((() => {
                 setIsTransitioning(!1), onSlideChange?.(index);
             }), speed));
-        }), [ realIndex, isTransitioning, speed, onSlideChange, loop, loopedSlides, autoplay ]), handleTouchStart = useCallback((e => {
+        }), [ realIndex, isTransitioning, speed, onSlideChange, loop, slides.length, autoplay ]), handleTouchStart = useCallback((e => {
             if (!allowTouchMove) return;
             // Stop autoplay on interaction if disableOnInteraction is true
                         autoplay && "object" == typeof autoplay && autoplay.disableOnInteraction && autoplayRef.current && (clearInterval(autoplayRef.current), 
@@ -18582,7 +18679,7 @@ const Steps = ({items: items, activeIndex: activeIndex = 0, vertical: vertical =
         let content;
     useEffect((() => {
         currentStep !== activeIndex && setCurrentStep(activeIndex);
-    }), [ activeIndex ]), 
+    }), [ activeIndex, currentStep ]), 
     // Legacy rendering
     content = items && items.length > 0 ? items.map(((item, index) => jsx(StepsItem, {
         index: index,
@@ -18726,7 +18823,7 @@ const TabsPanel =  forwardRef((({children: children, className: className = "",
 
 TabsPanel.displayName = "TabsPanel";
 
-const Tabs =  memo((({items: items, activeIndex: activeIndex = TAB.DEFAULTS.ACTIVE_INDEX, onTabChange: onTabChange, className: className = "", style: style, glass: glass, children: children}) => {
+const TabsComponentBase = ({items: items, activeIndex: activeIndex = TAB.DEFAULTS.ACTIVE_INDEX, onTabChange: onTabChange, className: className = "", style: style, glass: glass, children: children}) => {
     const [currentTab, setCurrentTab] = useState(activeIndex), handleTabClick = index => {
         setCurrentTab(index), onTabChange && onTabChange(index);
     }, handleKeyDown = (event, totalTabs) => {
@@ -18842,7 +18939,7 @@ const Tabs =  memo((({items: items, activeIndex: activeIndex = TAB.DEFAULTS.ACTI
         });
     }
     return wrapper;
-}));
+}, Tabs =  memo(TabsComponentBase);
 
 Tabs.displayName = "Tabs", Tabs.List = TabsList, Tabs.Trigger = TabsTrigger, Tabs.Panels = TabsPanels, 
 Tabs.Panel = TabsPanel;
@@ -18854,10 +18951,11 @@ const Testimonial = ({quote: quote, author: author, size: size = "", skeleton: s
     const testimonialRef = useRef(null), testimonialInstance = useRef(null);
     useEffect((() => {
         // Only run on client-side
-        if ("undefined" != typeof window && testimonialRef.current) 
+        if ("undefined" == typeof window || !testimonialRef.current) return;
+        const currentInstance = testimonialInstance.current;
         // Cleanup on unmount
-        return () => {
-            testimonialInstance.current && testimonialInstance.current.destroy();
+                return () => {
+            currentInstance && currentInstance.destroy();
         };
     }), [ size, skeleton ]);
     // Determine CSS classes
@@ -19998,11 +20096,13 @@ const VideoPlayer =  forwardRef((({src: src, type: type = "video", youtubeId: yo
                 detectBorderRadius();
         // Create ResizeObserver to watch for style changes
         let resizeObserver = null;
-        return "undefined" != typeof ResizeObserver && containerRef.current && (resizeObserver = new ResizeObserver(detectBorderRadius), 
+        "undefined" != typeof ResizeObserver && containerRef.current && (resizeObserver = new ResizeObserver(detectBorderRadius), 
         resizeObserver.observe(containerRef.current)), 
         // Also listen for window resize (in case styles change)
-        window.addEventListener("resize", detectBorderRadius), () => {
-            window.removeEventListener("resize", detectBorderRadius), resizeObserver && containerRef.current && (resizeObserver.unobserve(containerRef.current), 
+        window.addEventListener("resize", detectBorderRadius);
+        const currentContainer = containerRef.current;
+        return () => {
+            window.removeEventListener("resize", detectBorderRadius), resizeObserver && currentContainer && (resizeObserver.unobserve(currentContainer), 
             resizeObserver.disconnect());
         };
     }), []);
@@ -20757,7 +20857,51 @@ const components =  Object.freeze( Object.defineProperty({
     "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"
 };
 
 // Export all component types
@@ -20839,202 +20983,644 @@ function createTokens(overrides) {
 }
 
 /**
- * Theme System Error Handling
+ * Theme Adapter
  *
- * Centralized error handling for the Atomix theme system.
- * Provides custom error classes and logging utilities.
+ * Converts between Theme objects and DesignTokens
  */
 /**
- * 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
- */
-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 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);
     }
-    /**
-   * 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
-        };
+    // 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;
+    }
+    // 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);
 }
 
 /**
- * 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
+ * Converts an AtomixConfig to DesignTokens
  *
- * 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));
+ * This function maps the configuration from the user-facing format
+ * to the internal DesignTokens format used by the theme system.
+ *
+ * @param config - The configuration object to convert
+ * @returns DesignTokens object ready for theme generation
+ *
+ * @example
+ * ```typescript
+ * import { configToTokens } from '@shohojdhara/atomix/theme';
+ *
+ * const config = {
+ *   prefix: 'myapp',
+ *   theme: { extend: { colors: { primary: { main: '#7AFFD7' } } } }
+ * };
+ * const tokens = configToTokens(config);
+ * ```
+ */ function configToTokens(config) {
+    const prefix = config.prefix || "atomix", theme = config.theme || {};
+    // Start with default tokens
+    let tokens = {
+        ...defaultTokens
+    };
+    // 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));
+        }
     }
+    // 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;
 }
 
 /**
- * Default logger instance
- */ let defaultLogger = null;
+ * 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";
+}
 
 /**
- * Get or create default logger
- */ function getLogger() {
-    return defaultLogger || (defaultLogger = new ThemeLogger), defaultLogger;
+ * Converts DesignTokens to CSS variables
+ *
+ * @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;
 }
 
 /**
- * Core Theme Functions
- *
- * Simplified theme system using DesignTokens only.
- * Config-first approach: loads from atomix.config.ts when no input is provided.
+ * 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
  */
 /**
- * Create theme CSS from DesignTokens
+ * Validate Atomix configuration structure
  *
- * **Config-First Approach**: If no input is provided, loads from `atomix.config.ts`.
+ * Performs basic validation to catch common configuration errors early.
+ * Returns warnings for potential issues.
  *
- * @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 - Configuration object to validate
+ * @returns Array of validation warnings (empty if valid)
  *
  * @example
  * ```typescript
- * // Loads from atomix.config.ts
- * const css = createTheme();
- *
- * // Using DesignTokens
- * const css = createTheme({
- *   'primary': '#7c3aed',
- *   'spacing-4': '1rem',
- * });
+ * import { loadAtomixConfig, validateConfig } from '@shohojdhara/atomix/config';
  *
- * // With custom options
- * const css = createTheme(undefined, { prefix: 'myapp', selector: ':root' });
+ * const config = loadAtomixConfig();
+ * const warnings = validateConfig(config);
+ * warnings.forEach(w => console.warn(w));
  * ```
- */ 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()
-        });
+ */
+function validateConfig$1(config) {
+    const warnings = [];
+    // Check prefix format
+        // Check theme structure
+    if (config.prefix && (/^[a-zA-Z][a-zA-Z0-9-]*$/.test(config.prefix) || warnings.push(`Invalid prefix "${config.prefix}". Prefix should start with a letter and contain only letters, numbers, and hyphens.\nExample: "myapp", "brand-ui", "enterprise"`), 
+    config.prefix.length < 2 && warnings.push(`Prefix "${config.prefix}" is too short. Use at least 2 characters for clarity.\nExample: "app" instead of "a"`)), 
+    config.theme && (
+    // Warn if both extend and tokens are provided
+    config.theme.extend && config.theme.tokens && warnings.push("Both theme.extend and theme.tokens are defined. theme.tokens will take precedence and completely replace the default token system.\nIf you want to extend defaults, remove theme.tokens and use only theme.extend."), 
+    config.theme.extend)) {
+        const extend = config.theme.extend, validThemeKeys = [ "colors", "typography", "spacing", "borderRadius", "shadows", "zIndex", "transitions", "breakpoints" ];
+        // Check for common typos in theme properties
+                Object.keys(extend).forEach((key => {
+            _includesInstanceProperty(validThemeKeys).call(validThemeKeys, key) || warnings.push(`Unknown theme property: "${key}"\nValid properties: ${validThemeKeys.join(", ")}\nDid you mean one of these? Check for typos.`);
+        }));
     }
-    // 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;
+    // Validate advanced features
+        if (config.interactiveEffects) {
+        const ie = config.interactiveEffects;
+        // Validate vortex settings
+                ie.vortex && (ie.vortex.strength && (ie.vortex.strength < 0 || ie.vortex.strength > 10) && warnings.push("Vortex strength should be between 0 and 10 for optimal performance"), 
+        ie.vortex.radius && ie.vortex.radius < 0 && warnings.push("Vortex radius should be a positive number"), 
+        ie.vortex.decay && (ie.vortex.decay <= 0 || ie.vortex.decay > 1) && warnings.push("Vortex decay should be between 0 and 1")), 
+        // Validate chromatic aberration settings
+        ie.chromaticAberration && (ie.chromaticAberration.redShift && Math.abs(ie.chromaticAberration.redShift) > .1 && warnings.push("Chromatic red shift value seems unusually high (>0.1), verify this is intended"), 
+        ie.chromaticAberration.blueShift && Math.abs(ie.chromaticAberration.blueShift) > .1 && warnings.push("Chromatic blue shift value seems unusually high (>0.1), verify this is intended"), 
+        ie.chromaticAberration.edgeThreshold && (ie.chromaticAberration.edgeThreshold < 0 || ie.chromaticAberration.edgeThreshold > 1) && warnings.push("Chromatic edge threshold should be between 0 and 1")), 
+        // Validate mouse interaction settings
+        ie.mouseInteraction && ie.mouseInteraction.sensitivity && ie.mouseInteraction.sensitivity < 0 && warnings.push("Mouse sensitivity should be a positive number"), 
+        // Validate animation speed settings
+        ie.animationSpeed && (ie.animationSpeed.base && ie.animationSpeed.base <= 0 && warnings.push("Animation base speed should be greater than 0"), 
+        ie.animationSpeed.timeMultiplier && ie.animationSpeed.timeMultiplier <= 0 && warnings.push("Animation time multiplier should be greater than 0"));
+    }
+    // Validate optimization settings
+        if (config.optimization) {
+        const opt = config.optimization;
+        // Validate responsive breakpoints
+                if (opt.responsive && opt.responsive.breakpoints) {
+            const breakpoints = opt.responsive.breakpoints;
+            breakpoints.mobile && !isValidCSSLength(breakpoints.mobile) && warnings.push("Mobile breakpoint value is not a valid CSS length"), 
+            breakpoints.tablet && !isValidCSSLength(breakpoints.tablet) && warnings.push("Tablet breakpoint value is not a valid CSS length"), 
+            breakpoints.desktop && !isValidCSSLength(breakpoints.desktop) && warnings.push("Desktop breakpoint value is not a valid CSS length"), 
+            breakpoints.wide && !isValidCSSLength(breakpoints.wide) && warnings.push("Wide breakpoint value is not a valid CSS length");
+        }
+        // Validate device scaling
+                if (opt.responsive && opt.responsive.deviceScaling) {
+            const scaling = opt.responsive.deviceScaling;
+            scaling.mobile && (scaling.mobile <= 0 || scaling.mobile > 1) && warnings.push("Mobile device scaling should be between 0 and 1"), 
+            scaling.tablet && (scaling.tablet <= 0 || scaling.tablet > 1) && warnings.push("Tablet device scaling should be between 0 and 1"), 
+            scaling.desktop && (scaling.desktop <= 0 || scaling.desktop > 1) && warnings.push("Desktop device scaling should be between 0 and 1");
+        }
+        // Validate performance settings
+                // Validate auto-scaling thresholds
+        if (opt.performance && opt.performance.fpsTarget && (opt.performance.fpsTarget <= 0 || opt.performance.fpsTarget > 240) && warnings.push("FPS target should be a reasonable value (typically 30-120)"), 
+        opt.autoScaling && opt.autoScaling.qualityThresholds) {
+            const thresholds = opt.autoScaling.qualityThresholds;
+            thresholds.lowEnd && (thresholds.lowEnd < 0 || thresholds.lowEnd > 1) && warnings.push("Auto-scaling low-end threshold should be between 0 and 1"), 
+            thresholds.midRange && (thresholds.midRange < 0 || thresholds.midRange > 1) && warnings.push("Auto-scaling mid-range threshold should be between 0 and 1"), 
+            thresholds.highEnd && (thresholds.highEnd < 0 || thresholds.highEnd > 1) && warnings.push("Auto-scaling high-end threshold should be between 0 and 1");
+        }
+    }
+    // Validate visual polish settings
+        if (config.visualPolish) {
+        const vp = config.visualPolish;
+        // Validate content aware blur settings
+                vp.contentAwareBlur && (void 0 !== vp.contentAwareBlur.edgePreservation && "boolean" != typeof vp.contentAwareBlur.edgePreservation && warnings.push("Content-aware blur edge preservation should be a boolean value"), 
+        void 0 !== vp.contentAwareBlur.depthDetection && "boolean" != typeof vp.contentAwareBlur.depthDetection && warnings.push("Content-aware blur depth detection should be a boolean value")), 
+        // Validate holographic effects settings
+        vp.holographicEffects && (void 0 !== vp.holographicEffects.enabled && "boolean" != typeof vp.holographicEffects.enabled && warnings.push("Holographic effects enabled should be a boolean value"), 
+        void 0 !== vp.holographicEffects.rainbowDiffraction && "boolean" != typeof vp.holographicEffects.rainbowDiffraction && warnings.push("Holographic rainbow diffraction should be a boolean value"));
+    }
+    // Validate AI settings
+        var _context;
+    return config.ai && (config.ai.provider && !_includesInstanceProperty(_context = [ "openai", "anthropic" ]).call(_context, config.ai.provider) && warnings.push(`Unknown AI provider: "${config.ai.provider}". Supported: openai, anthropic`), 
+    config.ai.temperature && (config.ai.temperature < 0 || config.ai.temperature > 1) && warnings.push("AI temperature should be between 0 and 1"), 
+    config.ai.maxTokens && config.ai.maxTokens < 100 && warnings.push("AI maxTokens should typically be 100 or more"), 
+    config.ai.rateLimit && (config.ai.rateLimit.requests <= 0 && warnings.push("AI rate limit requests should be greater than 0"), 
+    config.ai.rateLimit.windowMs <= 0 && warnings.push("AI rate limit window should be greater than 0"))), 
+    // Validate telemetry settings
+    config.telemetry && config.telemetry.path && !config.telemetry.path.endsWith(".json") && warnings.push("Telemetry path should typically end with .json"), 
+    warnings;
+}
+
+/**
+ * Helper function to validate CSS length values
+ */ function isValidCSSLength(value) {
+    return /^(\d+(\.\d+)?)(px|em|rem|%|vw|vh|vmin|vmax|cm|mm|in|pt|pc|ex|ch)?$/.test(value);
+}
+
+/**
+ * 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 || {});
+ * ```
+ */ function loadAtomixConfig(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;
+}
+
+/**
+ * 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;
+    }
+}
+
+/**
+ * Resolve config path
+ *
+ * Finds atomix.config.ts in the project, checking common locations.
+ * Returns null in browser environments where file system access is not available.
+ *
+ * This function is designed to help tools identify if a config exists without loading it.
+ *
+ * @param configPath - Optional custom path to check
+ * @returns Absolute path to config file or null if not found
+ */ function resolveConfigPath(configPath) {
+    // In browser environments, config resolution is not possible
+    if ("undefined" != typeof window) return null;
+    // If a specific config path is provided, check if it exists
+        if (configPath) {
+        const absPath = join(process.cwd(), configPath);
+        return existsSync(absPath) ? absPath : null;
+    }
+    // Otherwise, check standard locations
+        const possiblePaths = [ join(process.cwd(), "atomix.config.ts"), join(process.cwd(), "atomix.config.js"), join(process.cwd(), "atomix.config.json") ];
+    for (const path of possiblePaths) if (existsSync(path)) return path;
+    return null;
+}
+
+/**
+ * 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;
+            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 = loadAtomixConfig({
+                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
-     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
+        const allTokens = createTokens(tokens), prefix = options?.prefix ?? configPrefix ?? "atomix";
+    // Get prefix from options, config, or use default
         return generateCSSVariables$1(allTokens, {
         ...options,
         prefix: prefix
@@ -21248,12 +21834,145 @@ class ThemeLogger {
  */
 /**
  * Default storage key for theme persistence
- */ "undefined" != typeof process && process.env;
+ */
+/**
+ * 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 = {}));
 
 /**
- * Check if code is running in a browser environment
+ * Custom error class for theme-related errors
  */
-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
+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
 , 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, {
@@ -21338,106 +22057,428 @@ const isBrowser = () => "undefined" != typeof window && "undefined" != typeof do
 /**
  * Check if code is running on the server (SSR)
  */
+// ============================================================================
+// Theme Mode Switching
+// ============================================================================
 /**
- * Theme Utilities
+ * Switch between light and dark themes
+ *
+ * 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');
  *
- * Helper utilities for working with themes, including color manipulation,
- * spacing helpers, and theme value accessors.
+ * // 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;
 }
 
 /**
- * Convert RGB to hex color
+ * 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
+ *
+ * @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
+ *
+ * @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);
 }
 
 /**
- * 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);
+ * 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)
@@ -21505,18 +22546,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)
@@ -21861,29 +22891,7 @@ function generateCSSVariables(theme, options = {}) {
                 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 = {}) {
+        const customVars = function(obj, prefix = "", result = {}) {
             // Use iterative approach with stack to avoid deep recursion
             const stack = [ {
                 obj: obj,
@@ -22337,19 +23345,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 ]), [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) {
+        }), [ defaultTheme, enablePersistence, storageKey, storageAdapter ]), [currentTheme, setCurrentTheme] = useState((() => "string" == typeof initialDefaultTheme ? initialDefaultTheme : "tokens-theme")), [activeTokens, setActiveTokens] = useState((() => {
+        // 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);
@@ -22361,10 +23379,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
@@ -22503,20 +23525,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
@@ -22570,6 +23593,7 @@ function useTheme() {
         theme: context.theme,
         activeTokens: context.activeTokens,
         setTheme: context.setTheme,
+        updateTheme: context.updateTheme,
         availableThemes: context.availableThemes,
         isLoading: context.isLoading,
         error: context.error,
@@ -22805,6 +23829,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
  *
@@ -22817,7 +24224,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;
     }
@@ -23643,7 +25051,7 @@ class ThemeValidator {
  *
  * Provides detailed inspection and debugging information for themes
  */ const ThemeInspector = ({theme: theme, showValidation: showValidation = !0, showCSSVariables: showCSSVariables = !0, showStructure: showStructure = !0, className: className, style: style}) => {
-    const [activeTab, setActiveTab] = useState("overview"), [expandedSections, setExpandedSections] = useState(new Set([ "palette" ])), [searchQuery, setSearchQuery] = useState(""), [debouncedSearchQuery, setDebouncedSearchQuery] = useState(""), [copiedPath, setCopiedPath] = useState(null), searchTimeoutRef = useRef();
+    const [activeTab, setActiveTab] = useState("overview"), [expandedSections, setExpandedSections] = useState(new Set([ "palette" ])), [searchQuery, setSearchQuery] = useState(""), [debouncedSearchQuery, setDebouncedSearchQuery] = useState(""), [copiedPath, setCopiedPath] = useState(null), searchTimeoutRef = useRef(void 0);
     // Debounce search query
     useEffect((() => (searchTimeoutRef.current && clearTimeout(searchTimeoutRef.current), 
     searchTimeoutRef.current = setTimeout((() => {
@@ -24049,7 +25457,7 @@ class ThemeValidator {
         }) ]
     });
 }, ThemeComparator = ({themeA: themeA, themeB: themeB, showOnlyDifferences: showOnlyDifferences = !1, className: className, style: style}) => {
-    const [searchQuery, setSearchQuery] = useState(""), [debouncedSearchQuery, setDebouncedSearchQuery] = useState(""), [filterType, setFilterType] = useState("all"), [filterCategory, setFilterCategory] = useState("all"), searchTimeoutRef = useRef();
+    const [searchQuery, setSearchQuery] = useState(""), [debouncedSearchQuery, setDebouncedSearchQuery] = useState(""), [filterType, setFilterType] = useState("all"), [filterCategory, setFilterCategory] = useState("all"), searchTimeoutRef = useRef(void 0);
     // Debounce search query
     useEffect((() => (searchTimeoutRef.current && clearTimeout(searchTimeoutRef.current), 
     searchTimeoutRef.current = setTimeout((() => {
@@ -24556,13 +25964,13 @@ class ThemeValidator {
 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")
     };
 }
@@ -24597,23 +26005,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,
@@ -24845,7 +26249,7 @@ const ThemeLiveEditor = ({initialTheme: initialTheme, onChange: onChange, classN
         } catch (err) {
             setError(err instanceof Error ? err.message : "Invalid JSON");
         }
-    }), [ updateTheme ]), jsonUpdateTimeoutRef = useRef();
+    }), [ updateTheme ]), jsonUpdateTimeoutRef = useRef(void 0);
     // Debounced JSON update to history
         useEffect((() => {
         if (!error) {
@@ -25434,48 +26838,360 @@ 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
+ * Design Tokens Customizer Component
+ */
+/**
+ * Theme Helper Functions
+ *
+ * Utility functions for working with DesignTokens
+ */
+/**
+ * Check if a value is DesignTokens
+ *
+ * Type guard to check if an object is DesignTokens format.
+ *
+ * @param value - Value to check
+ * @returns True if value is DesignTokens
+ */
+function isDesignTokens(value) {
+    if (!value || "object" != typeof value) return !1;
+    // DesignTokens is a flat object with string keys, no nested structures
+        const obj = value;
+    // Check for absence of Theme-specific properties
+        if ("palette" in obj || "typography" in obj || "__isJSTheme" in obj) return !1;
+    // Check if it has DesignTokens-like structure (flat string keys)
+        const keys = Object.keys(obj);
+    return 0 !== keys.length && keys.some((key => /^[a-z]+(-[a-z0-9]+)*$/.test(key) && "string" == typeof obj[key]));
+    // 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 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;
+ * @param config Responsive configuration
+ * @returns ResponsiveUtil instance
+ */ function createResponsiveUtil(config) {
+    return new ResponsiveUtil(config);
 }
 
 /**
- * Theme Helper Functions
- *
- * Utility functions for working with DesignTokens
- */
-/**
- * Check if a value is DesignTokens
- *
- * Type guard to check if an object is DesignTokens format.
+ * Hook for React components to use responsive features
  *
- * @param value - Value to check
- * @returns True if value is DesignTokens
- */ function isDesignTokens(value) {
-    if (!value || "object" != typeof value) return !1;
-    // DesignTokens is a flat object with string keys, no nested structures
-        const obj = value;
-    // Check for absence of Theme-specific properties
-        if ("palette" in obj || "typography" in obj || "__isJSTheme" in obj) return !1;
-    // Check if it has DesignTokens-like structure (flat string keys)
-        const keys = Object.keys(obj);
-    return 0 !== keys.length && keys.some((key => /^[a-z]+(-[a-z0-9]+)*$/.test(key) && "string" == typeof obj[key]));
-    // Check if keys look like DesignTokens (kebab-case, no nesting)
+ * @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()
+    };
 }
 
 /**
@@ -25663,6 +27379,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
  *
@@ -25685,8 +27427,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") {
@@ -25699,7 +27439,114 @@ class RTLManager {
     removeCSS(id);
 }
 
-const themeImport =  Object.freeze( Object.defineProperty({
+/**
+ * Main theme module interface
+ */ const index = {
+    // Core
+    createTheme: createTheme,
+    injectTheme: injectTheme,
+    removeTheme: removeTheme,
+    // Context and Provider
+    ThemeProvider: ThemeProvider,
+    useTheme: useTheme,
+    useThemeTokens: useThemeTokens,
+    ThemeContext: ThemeContext,
+    ThemeErrorBoundary: ThemeErrorBoundary,
+    // Adapters
+    configToTokens: configToTokens,
+    designTokensToCSSVars: designTokensToCSSVars,
+    // Theme Utils
+    switchTheme: switchTheme,
+    toggleTheme: toggleTheme,
+    getCurrentTheme: getCurrentTheme,
+    getSystemTheme: getSystemTheme,
+    initializeTheme: initializeTheme,
+    listenToSystemTheme: listenToSystemTheme,
+    persistTheme: persistTheme,
+    clearThemePreference: clearThemePreference,
+    // Token Manipulation
+    mergeTokens: mergeTokens,
+    overrideTokens: overrideTokens,
+    pickTokens: pickTokens,
+    omitTokens: omitTokens,
+    // Color Utilities
+    hexToRgb: hexToRgb$1,
+    rgbToHex: rgbToHex,
+    getLuminance: getLuminance,
+    getContrastRatio: getContrastRatio,
+    isAccessible: isAccessible,
+    getContrastText: getContrastText,
+    lighten: lighten,
+    darken: darken,
+    alpha: alpha,
+    emphasize: emphasize,
+    createSpacing: createSpacing,
+    // Performance utilities
+    createPerformanceMonitor: createPerformanceMonitor,
+    usePerformanceMonitor: usePerformanceMonitor,
+    // Responsive utilities
+    createResponsiveUtil: createResponsiveUtil,
+    useResponsive: useResponsive,
+    // Components
+    ThemeToggle: ThemeToggle,
+    ThemeApplicator: ThemeApplicator,
+    applyTheme: applyTheme,
+    getThemeApplicator: getThemeApplicator,
+    // Registry
+    createThemeRegistry: createThemeRegistry,
+    registerTheme: registerTheme,
+    unregisterTheme: unregisterTheme,
+    hasTheme: hasTheme,
+    getTheme: getTheme,
+    getAllThemes: getAllThemes,
+    getThemeIds: getThemeIds,
+    clearThemes: clearThemes,
+    getThemeCount: getThemeCount,
+    // Composition
+    deepMerge: deepMerge,
+    mergeTheme: mergeTheme,
+    extendTheme: extendTheme,
+    // Tokens
+    createTokens: createTokens,
+    defaultTokens: defaultTokens,
+    // Generators
+    generateCSSVariables: generateCSSVariables$1,
+    generateCSSVariablesForSelector: generateCSSVariablesForSelector,
+    // Naming
+    generateClassName: generateClassName,
+    generateCSSVariableName: generateCSSVariableName,
+    normalizeThemeTokens: normalizeThemeTokens,
+    camelToKebab: camelToKebab,
+    themePropertyToCSSVar: themePropertyToCSSVar,
+    // Component Theming
+    getComponentThemeValue: getComponentThemeValue,
+    generateComponentCSSVars: generateComponentCSSVars,
+    applyComponentTheme: applyComponentTheme,
+    useComponentTheme: useComponentTheme,
+    // Hooks
+    useThemeSwitcher: useThemeSwitcher,
+    // Helpers
+    isDesignTokens: isDesignTokens,
+    // CSS Variable Mapper
+    mapSCSSTokensToCSSVars: mapSCSSTokensToCSSVars,
+    applyCSSVariables: applyCSSVariables,
+    removeCSSVariables: removeCSSVariables,
+    getCSSVariable: getCSSVariable,
+    cssVarsToStyle: cssVarsToStyle,
+    mergeCSSVars: mergeCSSVars,
+    isValidCSSVariableName: isValidCSSVariableName,
+    extractComponentName: extractComponentName,
+    // Injection Utils
+    injectCSS: injectCSS$1,
+    removeCSS: removeCSS,
+    isCSSInjected: isCSSInjected,
+    // I18n
+    RTLManager: RTLManager,
+    createRTLManager: createRTLManager,
+    isRTLLocale: isRTLLocale,
+    getDirectionFromLocale: getDirectionFromLocale,
+    rtlCSS: rtlCSS
+}, themeImport =  Object.freeze( Object.defineProperty({
     __proto__: null,
     DesignTokensCustomizer: DesignTokensCustomizer,
     RTLManager: RTLManager,
@@ -25711,19 +27558,30 @@ const themeImport =  Object.freeze( Object.defineProperty({
     ThemeLiveEditor: ThemeLiveEditor,
     ThemePreview: ThemePreview,
     ThemeProvider: ThemeProvider,
+    ThemeToggle: ThemeToggle,
     ThemeValidator: ThemeValidator,
+    alpha: alpha,
     applyCSSVariables: applyCSSVariables,
     applyComponentTheme: applyComponentTheme,
     applyTheme: applyTheme,
     camelToKebab: camelToKebab,
+    clearThemePreference: clearThemePreference,
     clearThemes: clearThemes,
+    configToTokens: configToTokens,
+    createPerformanceMonitor: createPerformanceMonitor,
+    createRTLManager: createRTLManager,
+    createResponsiveUtil: createResponsiveUtil,
+    createSpacing: createSpacing,
     createTheme: createTheme,
     createThemeRegistry: createThemeRegistry,
     createTokens: createTokens,
     cssVarsToStyle: cssVarsToStyle,
+    darken: darken,
     deepMerge: deepMerge,
+    default: index,
     defaultTokens: defaultTokens,
     designTokensToCSSVars: designTokensToCSSVars,
+    emphasize: emphasize,
     extendTheme: extendTheme,
     extractComponentName: extractComponentName,
     generateCSSVariableName: generateCSSVariableName,
@@ -25734,29 +27592,53 @@ const themeImport =  Object.freeze( Object.defineProperty({
     getAllThemes: getAllThemes,
     getCSSVariable: getCSSVariable,
     getComponentThemeValue: getComponentThemeValue,
+    getContrastRatio: getContrastRatio,
+    getContrastText: getContrastText,
+    getCurrentTheme: getCurrentTheme,
+    getDirectionFromLocale: getDirectionFromLocale,
+    getLuminance: getLuminance,
+    getSystemTheme: getSystemTheme,
     getTheme: getTheme,
     getThemeApplicator: getThemeApplicator,
     getThemeCount: getThemeCount,
     getThemeIds: getThemeIds,
     hasTheme: hasTheme,
+    hexToRgb: hexToRgb$1,
+    initializeTheme: initializeTheme,
     injectCSS: injectCSS$1,
     injectTheme: injectTheme,
+    isAccessible: isAccessible,
     isCSSInjected: isCSSInjected,
     isDesignTokens: isDesignTokens,
+    isRTLLocale: isRTLLocale,
     isValidCSSVariableName: isValidCSSVariableName,
+    lighten: lighten,
+    listenToSystemTheme: listenToSystemTheme,
     mapSCSSTokensToCSSVars: mapSCSSTokensToCSSVars,
     mergeCSSVars: mergeCSSVars,
     mergeTheme: mergeTheme,
+    mergeTokens: mergeTokens,
     normalizeThemeTokens: normalizeThemeTokens,
+    omitTokens: omitTokens,
+    overrideTokens: overrideTokens,
+    persistTheme: persistTheme,
+    pickTokens: pickTokens,
     registerTheme: registerTheme,
     removeCSS: removeCSS,
     removeCSSVariables: removeCSSVariables,
     removeTheme: removeTheme,
+    rgbToHex: rgbToHex,
+    rtlCSS: rtlCSS,
+    switchTheme: switchTheme,
     themePropertyToCSSVar: themePropertyToCSSVar,
+    toggleTheme: toggleTheme,
     unregisterTheme: unregisterTheme,
     useComponentTheme: useComponentTheme,
     useHistory: useHistory,
+    usePerformanceMonitor: usePerformanceMonitor,
+    useResponsive: useResponsive,
     useTheme: useTheme,
+    useThemeSwitcher: useThemeSwitcher,
     useThemeTokens: useThemeTokens
 }, Symbol.toStringTag, {
     value: "Module"
@@ -26018,15 +27900,6 @@ const themeImport =  Object.freeze( Object.defineProperty({
     Radio: RADIO_CSS_VARS
 };
 
-/**
- * CSS Variables Constants
- *
- * Comprehensive CSS custom property definitions for all components.
- * These provide type-safe access to component styling variables.
- */
-/**
- * Button CSS Variables
- */
 /**
  * Get CSS variables for a component
  */
@@ -26052,97 +27925,6 @@ function getComponentCSSVars(component) {
     } : base : override;
 }
 
-/**
- * Render a slot with the given props
- *
- * Priority order:
- * 1. render function
- * 2. component
- * 3. children
- * 4. fallback
- *
- * @example
- * renderSlot(
- *   { render: (props) => <CustomButton {...props} /> },
- *   { onClick: handleClick, children: 'Click me' }
- * )
- */ function renderSlot(slot, props, fallback) {
-    // No slot provided, use fallback
-    if (!slot) return fallback;
-    // Slot is a plain React node
-        if ( React.isValidElement(slot) || "string" == typeof slot || "number" == typeof slot) return slot;
-    // Slot is an object with rendering options
-        if ("object" == typeof slot && null !== slot) {
-        const slotObj = slot;
-        // Priority 1: render function
-                if (slotObj.render && "function" == typeof slotObj.render) return slotObj.render(props);
-        // Priority 2: component
-                if (slotObj.component) {
-            const Component = slotObj.component;
-            return jsx(Component, {
-                ...props
-            });
-        }
-        // Priority 3: children
-                if (void 0 !== slotObj.children) return slotObj.children;
-    }
-    // Fallback
-        return fallback;
-}
-
-/**
- * Check if a value is a slot configuration
- */ function isSlot(value) {
-    return "object" == typeof value && null !== value && ("render" in value || "component" in value || "children" in value);
-}
-
-/**
- * Merge multiple slot configurations
- * Later slots override earlier ones
- */ function mergeSlots(...slots) {
-    const filtered = slots.filter((s => void 0 !== s));
-    if (0 !== filtered.length) return 1 === filtered.length ? filtered[0] : _reduceInstanceProperty(filtered).call(filtered, ((acc, slot) => ({
-        ...acc,
-        ...slot
-    })));
-}
-
-/**
- * Create a slot wrapper component
- *
- * @example
- * const ButtonSlot = createSlotComponent<ButtonSlotProps>('button')
- *
- * <ButtonSlot slot={customSlot} {...props}>
- *   Default content
- * </ButtonSlot>
- */ function createSlotComponent(defaultElement = "div") {
-    return function({slot: slot, children: children, ...props}) {
-        const slotProps = props;
-        return slot ? jsx(Fragment, {
-            children: renderSlot(slot, slotProps, children)
-        }) : jsx(defaultElement, "string" == typeof defaultElement ? {
-            ...props,
-            children: children
-        } : {
-            ...slotProps,
-            children: children
-        });
-    };
-}
-
-/**
- * Utility to create typed slot props
- */ function createSlotProps(props) {
-    return props;
-}
-
-/**
- * Hook to manage slot rendering
- */ function useSlot(slot, props, fallback) {
-    return React.useMemo((() => renderSlot(slot, props, fallback)), [ slot, props, fallback ]);
-}
-
 /**
  * Hook to merge theme overrides with component props
  *
@@ -26210,59 +27992,174 @@ function getComponentCSSVars(component) {
 }
 
 /**
- * Atomix Configuration System
+ * Configuration Types
+ *
+ * Type definitions for the Atomix configuration system.
+ */
+/**
+ * Helper function to define Atomix configuration with type safety
+ */ function defineConfig(config) {
+    return config;
+}
+
+/**
+ * Configuration Validator
  *
- * Tailwind-like configuration for customizing the Atomix Design System.
+ * Provides detailed validation and feedback for Atomix configurations,
+ * especially for advanced features (Phases 2, 3, and 4).
+ */
+/**
+ * Validate an Atomix configuration with detailed feedback
  *
- * External developers can create `atomix.config.ts` in their project root
- * to customize design tokens, similar to Tailwind's tailwind.config.js
+ * @param config - The configuration to validate
+ * @param options - Validation options
+ * @returns Detailed validation result
  *
  * @example
  * ```typescript
- * // atomix.config.ts (in your project)
- * import { defineConfig } from '@shohojdhara/atomix/config';
+ * import { validateConfiguration } from '@shohojdhara/atomix/config';
  *
- * export default defineConfig({
- *   theme: {
- *     extend: {
- *       colors: {
- *         primary: { main: '#7AFFD7' },
- *       },
- *     },
- *   },
- * });
+ * const config = { /* your config *\/ };
+ * const result = validateConfiguration(config);
+ *
+ * if (!result.isValid) {
+ *   console.warn('Warnings:', result.warnings);
+ *   console.info('Suggestions:', result.suggestions);
+ * }
  * ```
+ */ function validateConfiguration(config, options) {
+    const {performanceAnalysis: performanceAnalysis = !0, compatibilityReport: compatibilityReport = !0} = options || {}, warnings = [], suggestions = [];
+    let performanceImpact = "low";
+    // Use the existing validation
+        const baseWarnings = validateConfig$1(config);
+    warnings.push(...baseWarnings), 
+    // Analyze advanced features for performance impact
+    performanceAnalysis && (performanceImpact = 
+    /**
+ * Analyze the performance impact of a configuration
  */
+    function(config) {
+        let impactScore = 0;
+        // Analyze interactive effects
+                if (config.interactiveEffects) {
+            const ie = config.interactiveEffects;
+            ie.vortex?.enabled && (impactScore += 2), ie.chromaticAberration?.enabled && (impactScore += 1), 
+            ie.mouseInteraction?.trailEffect && (impactScore += 1), ie.mouseInteraction?.pressureSensitivity && (impactScore += 1);
+        }
+        // Analyze visual polish effects
+                if (config.visualPolish) {
+            const vp = config.visualPolish;
+            vp.borders?.iridescentGlow && (impactScore += 1), vp.borders?.shimmerEffect && (impactScore += 1), 
+            vp.contentAwareBlur?.enabled && (impactScore += 2), vp.holographicEffects?.enabled && (impactScore += 2), 
+            vp.holographicEffects?.scanlineAnimation && (impactScore += 1), vp.holographicEffects?.dataStream && (impactScore += 1), 
+            vp.holographicEffects?.pulseRings && (impactScore += 1);
+        }
+        // Analyze optimization settings
+                return config.optimization?.autoScaling?.enabled && (impactScore -= 1), 
+        impactScore >= 6 ? "high" : impactScore >= 3 ? "medium" : "low";
+    }
+    /**
+ * Generate suggestions based on the configuration
+ */ (config)), 
+    // Generate suggestions based on configuration
+    function(config, suggestions) {
+        // Suggest enabling performance optimizations if heavy effects are used
+        (config.interactiveEffects || config.visualPolish?.holographicEffects?.enabled) && (config.optimization?.autoScaling?.enabled || suggestions.push("Consider enabling auto-scaling in optimization settings to adjust effects based on device performance: optimization.autoScaling.enabled = true"), 
+        config.optimization?.performance?.fpsTarget || suggestions.push("Set a target FPS in optimization.performance.fpsTarget to ensure smooth performance when using interactive effects")), 
+        // Suggest responsive breakpoints if optimization is partially configured
+        config.optimization && !config.optimization.responsive && suggestions.push("Consider adding responsive breakpoints in optimization.responsive.breakpoints to adapt advanced effects based on device type"), 
+        // Suggest disabling heavy effects on lower-end devices
+        config.visualPolish?.holographicEffects?.enabled && suggestions.push("For better performance on lower-end devices, consider conditionally disabling holographic effects based on device capabilities"), 
+        // Suggest using content-aware blur with performance considerations
+        config.visualPolish?.contentAwareBlur?.enabled && suggestions.push("Content-aware blur can be expensive; consider setting a maximum blur radius or using simpler blur techniques for mobile devices"), 
+        // Suggest using chromatic aberration适度
+        config.interactiveEffects?.chromaticAberration?.enabled && (config.interactiveEffects.chromaticAberration.redShift && Math.abs(config.interactiveEffects.chromaticAberration.redShift) > .05 && suggestions.push("High chromatic aberration red shift values (>0.05) may cause discomfort for some users; consider reducing to improve accessibility"), 
+        config.interactiveEffects.chromaticAberration.blueShift && Math.abs(config.interactiveEffects.chromaticAberration.blueShift) > .05 && suggestions.push("High chromatic aberration blue shift values (>0.05) may cause discomfort for some users; consider reducing to improve accessibility"));
+    }
+    /**
+ * Generate a compatibility report for the configuration
+ */ (config, suggestions);
+    // Determine overall validity
+    const isValid = 0 === warnings.length, compatibility = compatibilityReport ? function(config) {
+        return {
+            browsers: !(config.visualPolish?.holographicEffects?.enabled || config.visualPolish?.contentAwareBlur?.enabled || config.interactiveEffects?.vortex?.enabled || config.interactiveEffects?.chromaticAberration?.enabled),
+            // May have issues on older browsers
+            ssr: !0,
+            // Works fine with SSR
+            frameworks: [ "react", "vue", "angular", "svelte", "vanillajs" ]
+        };
+    }
+    /**
+ * Print a detailed configuration report to the console
+ *
+ * @param config - The configuration to analyze
+ * @param title - Optional title for the report
+ *
+ * @example
+ * ```typescript
+ * import { printConfigReport } from '@shohojdhara/atomix/config';
+ *
+ * const config = { /* your config *\/ };
+ * printConfigReport(config, 'My Application Config');
+ * ```
+ */ (config) : {
+        browsers: !0,
+        ssr: !0,
+        frameworks: [ "react", "vue", "angular", "svelte", "vanillajs" ]
+    };
+    // Generate compatibility report
+        return {
+        isValid: isValid,
+        warnings: warnings,
+        suggestions: suggestions,
+        performanceImpact: performanceImpact,
+        compatibility: compatibility
+    };
+}
+
+function printConfigReport(config, title) {
+    const result = validateConfiguration(config);
+    result.warnings.length > 0 && result.warnings.forEach((warning => {})), result.suggestions.length > 0 && result.suggestions.forEach((suggestion => {}));
+    const featuresDetected = [];
+    config.interactiveEffects && featuresDetected.push("Interactive Effects"), config.optimization && featuresDetected.push("Optimization"), 
+    config.visualPolish && featuresDetected.push("Visual Polish"), config.ai && featuresDetected.push("AI Integration"), 
+    config.tokenEngine && featuresDetected.push("Token Engine"), config.generator && featuresDetected.push("Component Generator"), 
+    featuresDetected.length > 0 && featuresDetected.forEach((feature => {}));
+}
+
 /**
- * Helper function to define Atomix configuration with type safety
+ * Public API for loading and managing Atomix configuration
  *
- * @param config - Atomix configuration object
- * @returns The configuration object
+ * This module provides the public-facing API for configuration loading
+ * in external projects.
  */
 /**
- * Helper function to define Atomix configuration with type safety
+ * Load Atomix configuration from an external project.
  *
- * Similar to Tailwind's defineConfig, provides autocomplete and type checking.
- *
- * @param config - Atomix configuration object
- * @returns The configuration object
+ * @param options - Loading options
+ * @returns The loaded configuration
  *
  * @example
  * ```typescript
- * import { defineConfig } from '@shohojdhara/atomix/config';
+ * import { loadConfig } from '@shohojdhara/atomix/config';
  *
- * export default defineConfig({
- *   theme: {
- *     extend: {
- *       colors: {
- *         primary: { main: '#7AFFD7' },
- *       },
- *     },
- *   },
- * });
+ * const config = loadConfig();
+ * console.log(config.prefix); // 'atomix' or user's custom prefix
  * ```
- */ function defineConfig(config) {
-    return config;
+ */ function loadConfig(options) {
+    return loadAtomixConfig({
+        configPath: options?.configPath,
+        required: options?.required ?? !1
+    });
+}
+
+/**
+ * Validate Atomix configuration structure.
+ *
+ * @param config - Configuration object to validate
+ * @returns Array of validation warnings (empty if valid)
+ */ function validateConfig(config) {
+    return validateConfig$1(config);
 }
 
 // Import and re-export as namespaces with proper typing
@@ -26411,5 +28308,5 @@ const atomix = {
     types: types
 };
 
-export { ACCORDION, ATOMIX_GLASS, AVATAR, AVATAR_GROUP, Accordion, AreaChart, AtomixGlass, AtomixLogo, Avatar, AvatarGroup, BADGE, BADGE_CSS_VARS, BALANCED_PRESET, BLOCK, BREADCRUMB, BUTTON, BUTTON_CSS_VARS, BUTTON_GROUP, Badge, BarChart, Block, Breadcrumb, BubbleChart, Button, ButtonGroup, CALLOUT, CARD, CARD_CSS_VARS, CHART, CHECKBOX_CSS_VARS, CLASS_PREFIX, CODE_SNIPPET, COMPONENT_CSS_VARS, COUNTDOWN, Callout, CandlestickChart, Card, Chart, ChartRenderer, Checkbox, ColorModeToggle, Container, Countdown, DATA_TABLE_CLASSES, DATA_TABLE_SELECTORS, DATEPICKER, DEFAULT_ATOMIX_FONTS, DEFAULT_BREAKPOINTS, DROPDOWN, DROPDOWN_CSS_VARS, DataTable, DatePicker, DesignTokensCustomizer, DeviceDetector, DonutChart, Dropdown, EDGE_PANEL, EdgePanel, ElevationCard, FOOTER, FORM, FORM_GROUP, Footer, FooterLink, FooterSection, FooterSocialLink, Form, FormGroup, FunnelChart, GaugeChart, Grid, GridCol, HERO, HeatmapChart, Hero, INPUT, INPUT_CSS_VARS, Icon, Input, LIST, LIST_GROUP, LineChart, List, ListGroup, MESSAGES, MOBILE_OPTIMIZED_BREAKPOINTS, MODAL, MODAL_CSS_VARS, MasonryGrid, MasonryGridItem, MegaMenu, MegaMenuColumn, MegaMenuLink, Menu, MenuDivider, MenuItem, Messages, Modal, MultiAxisChart, NAV, NAVBAR, Nav, NavDropdown, NavItem, Navbar, PAGINATION_DEFAULTS, PERFORMANCE_PRESET, PHOTOVIEWER, POPOVER, PROGRESS, PROGRESS_CSS_VARS, Pagination, PerformanceOverlay, PhotoViewer, PieChart, Popover, ProductReview, Progress, QUALITY_PRESET, RADIO, RADIO_CSS_VARS, RATING, RIVER, RTLManager, RadarChart, Radio, Rating, River, Row, SECTION_INTRO, SELECT, SIDE_MENU, SIZES, SLIDER, SPINNER, STEPS, ScatterChart, SectionIntro, Select, SideMenu, SideMenuItem, SideMenuList, Slider, Spinner, Steps, TAB, TABS_CSS_VARS, TESTIMONIAL, TEXTAREA, THEME_COLORS, THEME_NAMING, TODO, TOGGLE, TOOLTIP, TOOLTIP_CSS_VARS, TYPEDBUTTON, Tabs, Testimonial, Textarea, ThemeApplicator, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemePreview, ThemeProvider, ThemeValidator, Todo, Toggle, Tooltip, TreemapChart, UPLOAD, Upload, VIDEO_PLAYER, VideoPlayer, WaterfallChart, applyCSSVariables, applyCSSVarsToStyle, applyComponentTheme, applyPartStyles, applyTheme, camelToKebab, clearThemes, composables, constants, createBreakpoints$1 as createBreakpoints, createCSSVarStyle, createDarkVariant, createDebugAttrs, createFontPreloadLink, createPartProps, createSlotComponent, createSlotProps, createTheme, createThemeRegistry, createTokens, cssVarsToStyle, deepMerge, atomix as default, defaultTokens, defineConfig, designTokensToCSSVars, exportTheme, extendTheme, extractComponentName, extractYouTubeId, generateCSSVariableName, generateCSSVariables$1 as generateCSSVariables, generateCSSVariablesForSelector, generateClassName, generateComponentCSSVars, generateFontPreloadTags, generateUUID, getAllThemes, getCSSVariable, getComponentCSSVars, getComponentThemeValue, getDefaultBreakpoints, getDevicePreset, getMobileOptimizedParams, getPartStyles, getQualityMultipliers, getTheme, getThemeApplicator, getThemeCount, getThemeIds, getThemeMetadata, hasCustomization, hasTheme, importTheme, injectCSS$1 as injectCSS, injectTheme, isCSSInjected, isDesignTokens, isSlot, isValidCSSVariableName, isYouTubeUrl, mapSCSSTokensToCSSVars, mergeCSSVars, mergeClassNames, mergeComponentProps, mergePartStyles, mergeSlots, mergeTheme, normalizeThemeTokens, preloadFonts, quickTheme, registerTheme, removeCSS, removeCSSVariables, removeTheme, renderSlot, sliderConstants, supportsDarkMode, theme, themePropertyToCSSVar, themeToCSS, types, unregisterTheme, useAccordion, useAtomixGlass, useBadge, useBarChart, useBlock, useChartData, useChartInteraction, useChartScale, useComponentCustomization, useComponentDefaultProps, useComponentTheme, useEdgePanel, useForm, useFormGroup, useHero, useHistory, useInput, useLineChart, useMergedProps, useNav, useNavDropdown, useNavItem, useNavbar, usePerformanceMonitor, usePieChart, useRadio, useResponsiveGlass, useRiver, useSelect, useSideMenu, useSideMenuItem, useSlot, useSpinner, useTextarea, useTheme, useThemeTokens, useTodo, utils, validateTheme };
+export { ACCORDION, ATOMIX_GLASS, AVATAR, AVATAR_GROUP, Accordion, AreaChart, AtomixGlass, AtomixLogo, Avatar, AvatarGroup, BADGE, BADGE_CSS_VARS, BALANCED_PRESET, BLOCK, BREADCRUMB, BUTTON, BUTTON_CSS_VARS, BUTTON_GROUP, Badge, BarChart, Block, Breadcrumb, BubbleChart, Button, ButtonGroup, CALLOUT, CARD, CARD_CSS_VARS, CHART, CHECKBOX_CSS_VARS, CLASS_PREFIX, CODE_SNIPPET, COMPONENT_CSS_VARS, COUNTDOWN, Callout, CandlestickChart, Card, Chart, ChartRenderer, Checkbox, ColorModeToggle, Container, Countdown, DATA_TABLE_CLASSES, DATA_TABLE_SELECTORS, DATEPICKER, DEFAULT_ATOMIX_FONTS, DEFAULT_BREAKPOINTS, DROPDOWN, DROPDOWN_CSS_VARS, DataTable, DatePicker, DesignTokensCustomizer, DeviceDetector, DonutChart, Dropdown, EDGE_PANEL, EdgePanel, ElevationCard, FOOTER, FORM, FORM_GROUP, Footer, FooterLink, FooterSection, FooterSocialLink, Form, FormGroup, FunnelChart, GaugeChart, Grid, GridCol, HERO, HeatmapChart, Hero, INPUT, INPUT_CSS_VARS, Icon, Input, LIST, LIST_GROUP, LineChart, List, ListGroup, MESSAGES, MOBILE_OPTIMIZED_BREAKPOINTS, MODAL, MODAL_CSS_VARS, MasonryGrid, MasonryGridItem, MegaMenu, MegaMenuColumn, MegaMenuLink, Menu, MenuDivider, MenuItem, Messages, Modal, MultiAxisChart, NAV, NAVBAR, Nav, NavDropdown, NavItem, Navbar, PAGINATION_DEFAULTS, PERFORMANCE_PRESET, PHOTOVIEWER, POPOVER, PROGRESS, PROGRESS_CSS_VARS, Pagination, PerformanceOverlay, PhotoViewer, PieChart, Popover, ProductReview, Progress, QUALITY_PRESET, RADIO, RADIO_CSS_VARS, RATING, RIVER, RTLManager, RadarChart, Radio, Rating, River, Row, SECTION_INTRO, SELECT, SIDE_MENU, SIZES, SLIDER, SPINNER, STEPS, ScatterChart, SectionIntro, Select, SideMenu, SideMenuItem, SideMenuList, Slider, Spinner, Steps, TAB, TABS_CSS_VARS, TESTIMONIAL, TEXTAREA, THEME_COLORS, THEME_NAMING, TODO, TOGGLE, TOOLTIP, TOOLTIP_CSS_VARS, TYPEDBUTTON, Tabs, Testimonial, Textarea, ThemeApplicator, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemePreview, ThemeProvider, ThemeToggle, ThemeValidator, Todo, Toggle, Tooltip, TreemapChart, UPLOAD, Upload, VIDEO_PLAYER, VideoPlayer, WaterfallChart, alpha, applyCSSVariables, applyCSSVarsToStyle, applyComponentTheme, applyPartStyles, applyTheme, camelToKebab, clearThemePreference, clearThemes, composables, configToTokens, constants, createBreakpoints$1 as createBreakpoints, createCSSVarStyle, createDarkVariant, createDebugAttrs, createFontPreloadLink, createPartProps, createPerformanceMonitor, createRTLManager, createResponsiveUtil, createSlotComponent, createSlotProps, createSpacing, createTheme, createThemeRegistry, createTokens, cssVarsToStyle, darken, deepMerge, atomix as default, defaultTokens, defineConfig, designTokensToCSSVars, emphasize, exportTheme, extendTheme, extractComponentName, extractYouTubeId, generateCSSVariableName, generateCSSVariables$1 as generateCSSVariables, generateCSSVariablesForSelector, generateClassName, generateComponentCSSVars, generateFontPreloadTags, generateUUID, getAllThemes, getCSSVariable, getComponentCSSVars, getComponentThemeValue, getContrastRatio, getContrastText, getCurrentTheme, getDefaultBreakpoints, getDevicePreset, getDirectionFromLocale, getLuminance, getMobileOptimizedParams, getPartStyles, getQualityMultipliers, getSystemTheme, getTheme, getThemeApplicator, getThemeCount, getThemeIds, getThemeMetadata, hasCustomization, hasTheme, hexToRgb$1 as hexToRgb, importTheme, initializeTheme, injectCSS$1 as injectCSS, injectTheme, isAccessible, isCSSInjected, isDesignTokens, isRTLLocale, isSlot, isValidCSSVariableName, isYouTubeUrl, lighten, listenToSystemTheme, loadAtomixConfig, loadConfig, mapSCSSTokensToCSSVars, mergeCSSVars, mergeClassNames, mergeComponentProps, mergePartStyles, mergeSlots, mergeTheme, mergeTokens, normalizeThemeTokens, omitTokens, overrideTokens, persistTheme, pickTokens, preloadFonts, printConfigReport, quickTheme, registerTheme, removeCSS, removeCSSVariables, removeTheme, renderSlot, resolveConfigPath, rgbToHex, rtlCSS, sliderConstants, supportsDarkMode, switchTheme, theme, themePropertyToCSSVar, themeToCSS, toggleTheme, types, unregisterTheme, useAccordion, useAtomixGlass, useBadge, useBarChart, useBlock, useChartData, useChartInteraction, useChartScale, useComponentCustomization, useComponentDefaultProps, useComponentTheme, useEdgePanel, useForm, useFormGroup, useHero, useHistory, useInput, useLineChart, useMergedProps, useNav, useNavDropdown, useNavItem, useNavbar, usePieChart, useRadio, useResponsive, useResponsiveGlass, useRiver, useSelect, useSideMenu, useSideMenuItem, useSlot, useSpinner, useTextarea, useTheme, useThemeSwitcher, useThemeTokens, useTodo, utils, validateConfig, validateConfiguration, validateTheme };
 //# sourceMappingURL=index.esm.js.map