react-achievements 3.9.3 → 4.1.0

package/dist/index.cjs

@@ -2,8 +2,6 @@
 
 var achievementsEngine = require('achievements-engine');
 var React = require('react');
-var Modal = require('react-modal');
-var Confetti = require('react-confetti');
 
 // Type guard to detect async storage
 function isAsyncStorage(storage) {
@@ -19,6 +17,174 @@ var StorageType;
     StorageType["RestAPI"] = "restapi"; // Asynchronous REST API storage
 })(StorageType || (StorageType = {}));
 
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+function __rest(s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+const warnedMessages = new Set();
+function warnDeprecation(message) {
+    var _a, _b;
+    const isProduction = typeof globalThis !== 'undefined' &&
+        ((_b = (_a = globalThis.process) === null || _a === void 0 ? void 0 : _a.env) === null || _b === void 0 ? void 0 : _b.NODE_ENV) === 'production';
+    if (isProduction || warnedMessages.has(message)) {
+        return;
+    }
+    warnedMessages.add(message);
+    console.warn(`[react-achievements] ${message}`);
+}
+
+const AchievementContext = React.createContext(undefined);
+const getAllAchievementRecord = (engine) => {
+    return Object.fromEntries(engine.getAllAchievements().map((achievement) => [
+        achievement.achievementId,
+        achievement,
+    ]));
+};
+const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'local', children, onError, useBuiltInUI, restApiConfig, engine: externalEngine, eventMapping, icons = {}, }) => {
+    if (useBuiltInUI !== undefined) {
+        warnDeprecation('`useBuiltInUI` is deprecated and is now a no-op because built-in UI is the default. It will be removed in 4.2.');
+    }
+    if (achievementsConfig && externalEngine) {
+        throw new Error('Cannot provide both "achievements" and "engine" props to AchievementProvider.\n\n' +
+            'Choose one pattern:\n' +
+            '1. Direct metric tracking: <AchievementProvider achievements={config}>\n' +
+            '2. Event-based tracking: <AchievementProvider engine={myEngine}>');
+    }
+    const isProviderCreatedEngine = Boolean(achievementsConfig);
+    const [engine] = React.useState(() => {
+        if (externalEngine) {
+            return externalEngine;
+        }
+        if (!achievementsConfig) {
+            throw new Error('AchievementProvider requires either "achievements" or "engine" prop.\n\n' +
+                '1. Direct metric tracking: <AchievementProvider achievements={config}>\n' +
+                '2. Event-based tracking: <AchievementProvider engine={myEngine}>');
+        }
+        return new achievementsEngine.AchievementEngine({
+            achievements: achievementsConfig,
+            storage: storage,
+            restApiConfig,
+            onError: onError,
+            eventMapping,
+        });
+    });
+    const [achievementState, setAchievementState] = React.useState(() => ({
+        unlocked: [...engine.getUnlocked()],
+        all: getAllAchievementRecord(engine),
+    }));
+    const syncAchievementState = React.useCallback(() => {
+        setAchievementState({
+            unlocked: [...engine.getUnlocked()],
+            all: getAllAchievementRecord(engine),
+        });
+    }, [engine]);
+    React.useEffect(() => {
+        return () => {
+            if (!externalEngine) {
+                engine.destroy();
+            }
+        };
+    }, [engine, externalEngine]);
+    React.useEffect(() => {
+        const unsubscribeUnlocked = engine.on('achievement:unlocked', syncAchievementState);
+        const unsubscribeStateChanged = engine.on('state:changed', syncAchievementState);
+        return () => {
+            unsubscribeUnlocked();
+            unsubscribeStateChanged();
+        };
+    }, [engine, syncAchievementState]);
+    const update = (newMetrics) => {
+        engine.update(newMetrics);
+    };
+    const reset = () => {
+        engine.reset();
+        syncAchievementState();
+    };
+    const getState = () => {
+        const metrics = engine.getMetrics();
+        const unlocked = engine.getUnlocked();
+        const metricsInArrayFormat = {};
+        Object.entries(metrics).forEach(([key, value]) => {
+            metricsInArrayFormat[key] = Array.isArray(value) ? value : [value];
+        });
+        return {
+            metrics: metricsInArrayFormat,
+            unlocked: [...unlocked],
+        };
+    };
+    const exportData = () => {
+        return engine.export();
+    };
+    const importData = (jsonString, options) => {
+        const result = engine.import(jsonString, options);
+        syncAchievementState();
+        return result;
+    };
+    const getAllAchievements = () => {
+        return engine.getAllAchievements();
+    };
+    return (React.createElement(AchievementContext.Provider, { value: {
+            update,
+            achievements: achievementState,
+            reset,
+            getState,
+            exportData,
+            importData,
+            getAllAchievements,
+            engine,
+            icons,
+            _isLegacyPattern: isProviderCreatedEngine,
+        } }, children));
+};
+
+/**
+ * Access the active AchievementEngine instance.
+ *
+ * In v4 this works with both provider-created engines (`achievements` prop) and
+ * injected engines (`engine` prop).
+ */
+const useAchievementEngine = () => {
+    const context = React.useContext(AchievementContext);
+    if (!context) {
+        throw new Error('useAchievementEngine must be used within an AchievementProvider.\n\n' +
+            'Wrap your component tree:\n' +
+            '<AchievementProvider achievements={achievements}>\n' +
+            '  <YourComponent />\n' +
+            '</AchievementProvider>');
+    }
+    return context.engine;
+};
+
 /**
  * Built-in theme presets
  */
@@ -135,56 +301,6 @@ function getTheme(name) {
     return builtInThemes[name];
 }
 
-const getPositionStyles = (position) => {
-    const base = {
-        position: 'fixed',
-        margin: '20px',
-        zIndex: 1000,
-    };
-    switch (position) {
-        case 'top-left':
-            return Object.assign(Object.assign({}, base), { top: 0, left: 0 });
-        case 'top-right':
-            return Object.assign(Object.assign({}, base), { top: 0, right: 0 });
-        case 'bottom-left':
-            return Object.assign(Object.assign({}, base), { bottom: 0, left: 0 });
-        case 'bottom-right':
-            return Object.assign(Object.assign({}, base), { bottom: 0, right: 0 });
-    }
-};
-const BadgesButton = ({ onClick, position = 'bottom-right', placement = 'fixed', styles = {}, unlockedAchievements, theme = 'modern', }) => {
-    // Get theme configuration for consistent styling
-    const themeConfig = getTheme(theme) || builtInThemes.modern;
-    const accentColor = themeConfig.notification.accentColor;
-    // Different styling for fixed vs inline placement
-    const baseStyles = placement === 'inline'
-        ? Object.assign({ 
-            // Inline mode: looks like a navigation item
-            backgroundColor: 'transparent', color: themeConfig.notification.textColor, padding: '12px 16px', border: 'none', borderRadius: '6px', cursor: 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '8px', fontSize: '15px', width: '100%', textAlign: 'left', transition: 'background-color 0.2s ease-in-out' }, styles) : Object.assign(Object.assign({ 
-        // Fixed mode: floating button
-        backgroundColor: accentColor, color: 'white', padding: '10px 20px', border: 'none', borderRadius: '20px', cursor: 'pointer', display: 'flex', alignItems: 'center', gap: '8px', fontSize: '16px', boxShadow: '0 2px 5px rgba(0,0,0,0.2)', transition: 'transform 0.2s ease-in-out' }, getPositionStyles(position)), styles);
-    return (React.createElement("button", { onClick: onClick, style: baseStyles, onMouseEnter: (e) => {
-            if (placement === 'inline') {
-                // Inline mode: subtle background color change
-                e.target.style.backgroundColor = 'rgba(255, 255, 255, 0.1)';
-            }
-            else {
-                // Fixed mode: scale transformation
-                e.target.style.transform = 'scale(1.05)';
-            }
-        }, onMouseLeave: (e) => {
-            if (placement === 'inline') {
-                e.target.style.backgroundColor = 'transparent';
-            }
-            else {
-                e.target.style.transform = 'scale(1)';
-            }
-        }, "data-placement": placement, "data-testid": "badges-button" },
-        "\uD83C\uDFC6 Achievements (",
-        unlockedAchievements.length,
-        ")"));
-};
-
 const defaultAchievementIcons = {
     // Essential fallback icons for system use
     default: '⭐', // Fallback when no icon is provided
@@ -196,184 +312,123 @@ const defaultAchievementIcons = {
     star: '⭐',
 };
 
-const defaultStyles = {
-    badgesButton: {
-        backgroundColor: '#4CAF50',
-        color: 'white',
-        padding: '10px 20px',
+/**
+ * Built-in notification component
+ * Modern, theme-aware achievement notification with smooth animations
+ */
+const BuiltInNotification = ({ achievement, onClose, duration = 5000, position = 'top-center', theme = 'modern', icons = {}, stackIndex = 0, }) => {
+    var _a, _b, _c;
+    const [isVisible, setIsVisible] = React.useState(false);
+    const [isExiting, setIsExiting] = React.useState(false);
+    // Merge custom icons with defaults
+    const mergedIcons = Object.assign(Object.assign({}, defaultAchievementIcons), icons);
+    // Get theme configuration
+    const themeConfig = getTheme(theme) || builtInThemes.modern;
+    const { notification: themeStyles } = themeConfig;
+    React.useEffect(() => {
+        // Slide in animation
+        const showTimer = setTimeout(() => setIsVisible(true), 10);
+        // Auto-dismiss
+        const dismissTimer = setTimeout(() => {
+            setIsExiting(true);
+            setTimeout(() => onClose === null || onClose === void 0 ? void 0 : onClose(), 300);
+        }, duration);
+        return () => {
+            clearTimeout(showTimer);
+            clearTimeout(dismissTimer);
+        };
+    }, [duration, onClose]);
+    const getPositionStyles = () => {
+        const stackedOffset = 20 + stackIndex * 104;
+        const base = {
+            position: 'fixed',
+            zIndex: 9999,
+        };
+        switch (position) {
+            case 'top-center':
+                return Object.assign(Object.assign({}, base), { top: stackedOffset, left: '50%', transform: 'translateX(-50%)' });
+            case 'top-left':
+                return Object.assign(Object.assign({}, base), { top: stackedOffset, left: 20 });
+            case 'top-right':
+                return Object.assign(Object.assign({}, base), { top: stackedOffset, right: 20 });
+            case 'bottom-center':
+                return Object.assign(Object.assign({}, base), { bottom: stackedOffset, left: '50%', transform: 'translateX(-50%)' });
+            case 'bottom-left':
+                return Object.assign(Object.assign({}, base), { bottom: stackedOffset, left: 20 });
+            case 'bottom-right':
+                return Object.assign(Object.assign({}, base), { bottom: stackedOffset, right: 20 });
+            default:
+                return Object.assign(Object.assign({}, base), { top: stackedOffset, left: '50%', transform: 'translateX(-50%)' });
+        }
+    };
+    const containerStyles = Object.assign(Object.assign({}, getPositionStyles()), { background: themeStyles.background, borderRadius: themeStyles.borderRadius, boxShadow: themeStyles.boxShadow, padding: '16px 24px', minWidth: '320px', maxWidth: '500px', display: 'flex', alignItems: 'center', gap: '16px', opacity: isVisible && !isExiting ? 1 : 0, transform: position.startsWith('top')
+            ? `translateY(${isVisible && !isExiting ? '0' : '-20px'}) ${position.includes('center') ? 'translateX(-50%)' : ''}`
+            : `translateY(${isVisible && !isExiting ? '0' : '20px'}) ${position.includes('center') ? 'translateX(-50%)' : ''}`, transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)', pointerEvents: isVisible ? 'auto' : 'none' });
+    const iconStyles = {
+        fontSize: '48px',
+        lineHeight: 1,
+        flexShrink: 0,
+    };
+    const contentStyles = {
+        flex: 1,
+        color: themeStyles.textColor,
+        minWidth: 0,
+    };
+    const headerStyles = {
+        fontSize: ((_a = themeStyles.fontSize) === null || _a === void 0 ? void 0 : _a.header) || '12px',
+        textTransform: 'uppercase',
+        letterSpacing: '1px',
+        opacity: 0.8,
+        marginBottom: '4px',
+        color: themeStyles.accentColor,
+        fontWeight: 600,
+    };
+    const titleStyles = {
+        fontSize: ((_b = themeStyles.fontSize) === null || _b === void 0 ? void 0 : _b.title) || '18px',
+        fontWeight: 'bold',
+        marginBottom: '4px',
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        whiteSpace: 'nowrap',
+    };
+    const descriptionStyles = {
+        fontSize: ((_c = themeStyles.fontSize) === null || _c === void 0 ? void 0 : _c.description) || '14px',
+        opacity: 0.9,
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        display: '-webkit-box',
+        WebkitLineClamp: 2,
+        WebkitBoxOrient: 'vertical',
+    };
+    const closeButtonStyles = {
+        background: 'none',
         border: 'none',
-        borderRadius: '20px',
+        color: themeStyles.textColor,
+        fontSize: '24px',
         cursor: 'pointer',
-        display: 'flex',
-        alignItems: 'center',
-        gap: '8px',
-        fontSize: '16px',
-        boxShadow: '0 2px 5px rgba(0,0,0,0.2)',
-        transition: 'transform 0.2s ease-in-out',
-    },
-    badgesModal: {
-        overlay: {
-            backgroundColor: 'rgba(0, 0, 0, 0.75)',
-            display: 'flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-            zIndex: 1000,
-        },
-        content: {
-            position: 'relative',
-            background: '#fff',
-            borderRadius: '8px',
-            padding: '20px',
-            maxWidth: '500px',
-            width: '90%',
-            maxHeight: '80vh',
-            overflow: 'auto',
-        },
-        header: {
-            display: 'flex',
-            justifyContent: 'space-between',
-            alignItems: 'center',
-            marginBottom: '20px',
-        },
-        closeButton: {
-            background: 'none',
-            border: 'none',
-            fontSize: '24px',
-            cursor: 'pointer',
-            padding: '0',
-        },
-        achievementList: {
-            display: 'flex',
-            flexDirection: 'column',
-            gap: '16px',
-        },
-        achievementItem: {
-            display: 'flex',
-            gap: '16px',
-            padding: '16px',
-            borderRadius: '8px',
-            backgroundColor: '#f5f5f5',
-            alignItems: 'center',
-        },
-        achievementTitle: {
-            margin: '0',
-            fontSize: '18px',
-            fontWeight: 'bold',
-        },
-        achievementDescription: {
-            margin: '4px 0 0 0',
-            color: '#666',
-        },
-        achievementIcon: {
-            fontSize: '32px',
-            display: 'flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-        },
-        lockIcon: {
-            fontSize: '24px',
-            position: 'absolute',
-            top: '50%',
-            right: '16px',
-            transform: 'translateY(-50%)',
-        },
-        lockedAchievementItem: {
-            display: 'flex',
-            gap: '16px',
-            padding: '16px',
-            borderRadius: '8px',
-            backgroundColor: '#e0e0e0',
-            alignItems: 'center',
-            opacity: 0.5,
-        },
-    },
-};
-
-const BadgesModal = ({ isOpen, onClose, achievements, styles = {}, icons = {}, showAllAchievements = false, showUnlockConditions = false, allAchievements, }) => {
-    // Merge custom icons with default icons, with custom icons taking precedence
-    const mergedIcons = Object.assign(Object.assign({}, defaultAchievementIcons), icons);
-    return (React.createElement(Modal, { isOpen: isOpen, onRequestClose: onClose, style: {
-            overlay: Object.assign(Object.assign({}, defaultStyles.badgesModal.overlay), styles === null || styles === void 0 ? void 0 : styles.overlay),
-            content: Object.assign(Object.assign({}, defaultStyles.badgesModal.content), styles === null || styles === void 0 ? void 0 : styles.content)
-        }, contentLabel: "Achievements" },
-        React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.header), styles === null || styles === void 0 ? void 0 : styles.header) },
-            React.createElement("h2", { style: { margin: 0 } }, "\uD83C\uDFC6 Achievements"),
-            React.createElement("button", { onClick: onClose, style: Object.assign(Object.assign({}, defaultStyles.badgesModal.closeButton), styles === null || styles === void 0 ? void 0 : styles.closeButton), "aria-label": "Close" }, "\u00D7")),
-        React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementList), styles === null || styles === void 0 ? void 0 : styles.achievementList) }, (() => {
-            // Determine which achievements to display
-            const achievementsToDisplay = showAllAchievements && allAchievements
-                ? allAchievements
-                : achievements.map(a => (Object.assign(Object.assign({}, a), { isUnlocked: true })));
-            return (React.createElement(React.Fragment, null,
-                achievementsToDisplay.map((achievement) => {
-                    const isLocked = !achievement.isUnlocked;
-                    return (React.createElement("div", { key: achievement.achievementId, style: Object.assign(Object.assign(Object.assign({}, (isLocked
-                            ? Object.assign(Object.assign({}, defaultStyles.badgesModal.lockedAchievementItem), styles === null || styles === void 0 ? void 0 : styles.lockedAchievementItem) : defaultStyles.badgesModal.achievementItem)), styles === null || styles === void 0 ? void 0 : styles.achievementItem), { position: 'relative' }) },
-                        achievement.achievementIconKey && (React.createElement("div", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementIcon), styles === null || styles === void 0 ? void 0 : styles.achievementIcon), { opacity: isLocked ? 0.4 : 1 }) }, achievement.achievementIconKey in mergedIcons
-                            ? mergedIcons[achievement.achievementIconKey]
-                            : mergedIcons.default || '⭐')),
-                        React.createElement("div", { style: { flex: 1 } },
-                            React.createElement("h3", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementTitle), styles === null || styles === void 0 ? void 0 : styles.achievementTitle), { color: isLocked ? '#999' : undefined }) }, achievement.achievementTitle),
-                            React.createElement("p", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementDescription), styles === null || styles === void 0 ? void 0 : styles.achievementDescription), { color: isLocked ? '#aaa' : '#666' }) },
-                                achievement.achievementDescription,
-                                showUnlockConditions && isLocked && achievement.achievementDescription && (React.createElement("span", { style: {
-                                        display: 'block',
-                                        fontSize: '12px',
-                                        marginTop: '4px',
-                                        fontStyle: 'italic',
-                                        color: '#888'
-                                    } },
-                                    "\uD83D\uDD13 ",
-                                    achievement.achievementDescription)))),
-                        isLocked && (React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.lockIcon), styles === null || styles === void 0 ? void 0 : styles.lockIcon) }, "\uD83D\uDD12"))));
-                }),
-                achievementsToDisplay.length === 0 && (React.createElement("p", { style: { textAlign: 'center', color: '#666' } }, "No achievements configured."))));
-        })())));
-};
-
-/**
- * BadgesButtonWithModal - A convenience component that combines BadgesButton and BadgesModal
- *
- * This component manages the modal state internally, providing a simplified API
- * for the common use case of displaying achievements.
- *
- * For advanced use cases requiring custom state management or multiple triggers,
- * use BadgesButton and BadgesModal separately.
- *
- * @example
- * ```tsx
- * // Simple usage
- * <BadgesButtonWithModal
- *   unlockedAchievements={achievements.unlocked}
- * />
- *
- * // Show all achievements (locked + unlocked)
- * <BadgesButtonWithModal
- *   unlockedAchievements={achievements.unlocked}
- *   showAllAchievements={true}
- *   allAchievements={getAllAchievements()}
- *   showUnlockConditions={true}
- * />
- *
- * // Customize position and theme
- * <BadgesButtonWithModal
- *   unlockedAchievements={achievements.unlocked}
- *   position="top-right"
- *   theme="gamified"
- * />
- *
- * // Inline mode for navigation
- * <BadgesButtonWithModal
- *   unlockedAchievements={achievements.unlocked}
- *   placement="inline"
- * />
- * ```
- */
-const BadgesButtonWithModal = ({ unlockedAchievements, position = 'bottom-right', placement = 'fixed', showAllAchievements = false, allAchievements, showUnlockConditions = false, icons, theme = 'modern', buttonStyles, modalStyles, }) => {
-    const [isModalOpen, setIsModalOpen] = React.useState(false);
-    return (React.createElement(React.Fragment, null,
-        React.createElement(BadgesButton, { onClick: () => setIsModalOpen(true), unlockedAchievements: unlockedAchievements, position: position, placement: placement, theme: theme, styles: buttonStyles }),
-        React.createElement(BadgesModal, { isOpen: isModalOpen, onClose: () => setIsModalOpen(false), achievements: unlockedAchievements, showAllAchievements: showAllAchievements, allAchievements: allAchievements, showUnlockConditions: showUnlockConditions, icons: icons, styles: modalStyles })));
+        opacity: 0.6,
+        transition: 'opacity 0.2s',
+        padding: '4px',
+        flexShrink: 0,
+        lineHeight: 1,
+    };
+    // If achievementIconKey exists but not in mergedIcons, use it directly (might be an emoji)
+    // Otherwise, look up in mergedIcons or fall back to default
+    const icon = (achievement.achievementIconKey &&
+        mergedIcons[achievement.achievementIconKey]) ||
+        achievement.achievementIconKey ||
+        mergedIcons.default ||
+        '⭐';
+    return (React.createElement("div", { style: containerStyles, "data-testid": "built-in-notification" },
+        React.createElement("div", { style: iconStyles }, icon),
+        React.createElement("div", { style: contentStyles },
+            React.createElement("div", { style: headerStyles }, "Achievement Unlocked!"),
+            React.createElement("div", { style: titleStyles }, achievement.achievementTitle),
+            achievement.achievementDescription && (React.createElement("div", { style: descriptionStyles }, achievement.achievementDescription))),
+        React.createElement("button", { onClick: () => {
+                setIsExiting(true);
+                setTimeout(() => onClose === null || onClose === void 0 ? void 0 : onClose(), 300);
+            }, style: closeButtonStyles, onMouseEnter: (e) => (e.currentTarget.style.opacity = '1'), onMouseLeave: (e) => (e.currentTarget.style.opacity = '0.6'), "aria-label": "Close notification" }, "\u00D7")));
 };
 
 /**
@@ -416,137 +471,6 @@ function useWindowSize() {
     return size;
 }
 
-const ConfettiWrapper = ({ show }) => {
-    const { width, height } = useWindowSize();
-    if (!show)
-        return null;
-    return (React.createElement(Confetti, { width: width, height: height, numberOfPieces: 200, recycle: false, style: {
-            position: 'fixed',
-            top: 0,
-            left: 0,
-            zIndex: 1001,
-            pointerEvents: 'none',
-        } }));
-};
-
-/**
- * Built-in notification component
- * Modern, theme-aware achievement notification with smooth animations
- */
-const BuiltInNotification = ({ achievement, onClose, duration = 5000, position = 'top-center', theme = 'modern', icons = {}, }) => {
-    var _a, _b, _c;
-    const [isVisible, setIsVisible] = React.useState(false);
-    const [isExiting, setIsExiting] = React.useState(false);
-    // Merge custom icons with defaults
-    const mergedIcons = Object.assign(Object.assign({}, defaultAchievementIcons), icons);
-    // Get theme configuration
-    const themeConfig = getTheme(theme) || builtInThemes.modern;
-    const { notification: themeStyles } = themeConfig;
-    React.useEffect(() => {
-        // Slide in animation
-        const showTimer = setTimeout(() => setIsVisible(true), 10);
-        // Auto-dismiss
-        const dismissTimer = setTimeout(() => {
-            setIsExiting(true);
-            setTimeout(() => onClose === null || onClose === void 0 ? void 0 : onClose(), 300);
-        }, duration);
-        return () => {
-            clearTimeout(showTimer);
-            clearTimeout(dismissTimer);
-        };
-    }, [duration, onClose]);
-    const getPositionStyles = () => {
-        const base = {
-            position: 'fixed',
-            zIndex: 9999,
-        };
-        switch (position) {
-            case 'top-center':
-                return Object.assign(Object.assign({}, base), { top: 20, left: '50%', transform: 'translateX(-50%)' });
-            case 'top-left':
-                return Object.assign(Object.assign({}, base), { top: 20, left: 20 });
-            case 'top-right':
-                return Object.assign(Object.assign({}, base), { top: 20, right: 20 });
-            case 'bottom-center':
-                return Object.assign(Object.assign({}, base), { bottom: 20, left: '50%', transform: 'translateX(-50%)' });
-            case 'bottom-left':
-                return Object.assign(Object.assign({}, base), { bottom: 20, left: 20 });
-            case 'bottom-right':
-                return Object.assign(Object.assign({}, base), { bottom: 20, right: 20 });
-            default:
-                return Object.assign(Object.assign({}, base), { top: 20, left: '50%', transform: 'translateX(-50%)' });
-        }
-    };
-    const containerStyles = Object.assign(Object.assign({}, getPositionStyles()), { background: themeStyles.background, borderRadius: themeStyles.borderRadius, boxShadow: themeStyles.boxShadow, padding: '16px 24px', minWidth: '320px', maxWidth: '500px', display: 'flex', alignItems: 'center', gap: '16px', opacity: isVisible && !isExiting ? 1 : 0, transform: position.startsWith('top')
-            ? `translateY(${isVisible && !isExiting ? '0' : '-20px'}) ${position.includes('center') ? 'translateX(-50%)' : ''}`
-            : `translateY(${isVisible && !isExiting ? '0' : '20px'}) ${position.includes('center') ? 'translateX(-50%)' : ''}`, transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)', pointerEvents: isVisible ? 'auto' : 'none' });
-    const iconStyles = {
-        fontSize: '48px',
-        lineHeight: 1,
-        flexShrink: 0,
-    };
-    const contentStyles = {
-        flex: 1,
-        color: themeStyles.textColor,
-        minWidth: 0,
-    };
-    const headerStyles = {
-        fontSize: ((_a = themeStyles.fontSize) === null || _a === void 0 ? void 0 : _a.header) || '12px',
-        textTransform: 'uppercase',
-        letterSpacing: '1px',
-        opacity: 0.8,
-        marginBottom: '4px',
-        color: themeStyles.accentColor,
-        fontWeight: 600,
-    };
-    const titleStyles = {
-        fontSize: ((_b = themeStyles.fontSize) === null || _b === void 0 ? void 0 : _b.title) || '18px',
-        fontWeight: 'bold',
-        marginBottom: '4px',
-        overflow: 'hidden',
-        textOverflow: 'ellipsis',
-        whiteSpace: 'nowrap',
-    };
-    const descriptionStyles = {
-        fontSize: ((_c = themeStyles.fontSize) === null || _c === void 0 ? void 0 : _c.description) || '14px',
-        opacity: 0.9,
-        overflow: 'hidden',
-        textOverflow: 'ellipsis',
-        display: '-webkit-box',
-        WebkitLineClamp: 2,
-        WebkitBoxOrient: 'vertical',
-    };
-    const closeButtonStyles = {
-        background: 'none',
-        border: 'none',
-        color: themeStyles.textColor,
-        fontSize: '24px',
-        cursor: 'pointer',
-        opacity: 0.6,
-        transition: 'opacity 0.2s',
-        padding: '4px',
-        flexShrink: 0,
-        lineHeight: 1,
-    };
-    // If achievementIconKey exists but not in mergedIcons, use it directly (might be an emoji)
-    // Otherwise, look up in mergedIcons or fall back to default
-    const icon = (achievement.achievementIconKey &&
-        mergedIcons[achievement.achievementIconKey]) ||
-        achievement.achievementIconKey ||
-        mergedIcons.default ||
-        '⭐';
-    return (React.createElement("div", { style: containerStyles, "data-testid": "built-in-notification" },
-        React.createElement("div", { style: iconStyles }, icon),
-        React.createElement("div", { style: contentStyles },
-            React.createElement("div", { style: headerStyles }, "Achievement Unlocked!"),
-            React.createElement("div", { style: titleStyles }, achievement.achievementTitle),
-            achievement.achievementDescription && (React.createElement("div", { style: descriptionStyles }, achievement.achievementDescription))),
-        React.createElement("button", { onClick: () => {
-                setIsExiting(true);
-                setTimeout(() => onClose === null || onClose === void 0 ? void 0 : onClose(), 300);
-            }, style: closeButtonStyles, onMouseEnter: (e) => (e.currentTarget.style.opacity = '1'), onMouseLeave: (e) => (e.currentTarget.style.opacity = '0.6'), "aria-label": "Close notification" }, "\u00D7")));
-};
-
 /**
  * Built-in confetti component
  * Lightweight CSS-based confetti animation
@@ -605,128 +529,565 @@ const BuiltInConfetti = ({ show, duration = 5000, particleCount = 50, colors = [
               transform: translateY(0) rotate(0deg);
               opacity: 1;
             }
-            100% {
-              transform: translateY(${height + 50}px) rotate(720deg);
-              opacity: 0;
+            100% {
+              transform: translateY(${height + 50}px) rotate(720deg);
+              opacity: 0;
+            }
+          }
+        `),
+        React.createElement("div", { style: containerStyles, "data-testid": "built-in-confetti" }, particles)));
+};
+
+const NOTIFICATION_DURATION_MS = 5000;
+const AchievementUIContext = React.createContext({
+    icons: {},
+    ui: {},
+});
+const AchievementEffects = ({ icons, ui }) => {
+    const engine = useAchievementEngine();
+    const seenAchievementsRef = React.useRef(new Set(engine.getUnlocked()));
+    const confettiTimerRef = React.useRef(null);
+    const [showConfetti, setShowConfetti] = React.useState(false);
+    const [notifications, setNotifications] = React.useState([]);
+    React.useEffect(() => {
+        const unsubscribeUnlocked = engine.on('achievement:unlocked', (event) => {
+            if (seenAchievementsRef.current.has(event.achievementId)) {
+                return;
+            }
+            seenAchievementsRef.current.add(event.achievementId);
+            const unlockedAchievement = {
+                achievementId: event.achievementId,
+                achievementTitle: event.achievementTitle,
+                achievementDescription: event.achievementDescription,
+                achievementIconKey: event.achievementIconKey,
+                isUnlocked: true,
+            };
+            if (ui.enableNotifications !== false) {
+                setNotifications((currentNotifications) => {
+                    if (currentNotifications.some((notification) => notification.achievementId === unlockedAchievement.achievementId)) {
+                        return currentNotifications;
+                    }
+                    return [...currentNotifications, unlockedAchievement];
+                });
+            }
+            if (ui.enableConfetti !== false) {
+                if (confettiTimerRef.current) {
+                    clearTimeout(confettiTimerRef.current);
+                }
+                setShowConfetti(true);
+                confettiTimerRef.current = setTimeout(() => {
+                    setShowConfetti(false);
+                    confettiTimerRef.current = null;
+                }, NOTIFICATION_DURATION_MS);
+            }
+        });
+        const unsubscribeStateChanged = engine.on('state:changed', () => {
+            const unlocked = new Set(engine.getUnlocked());
+            seenAchievementsRef.current.forEach((achievementId) => {
+                if (!unlocked.has(achievementId)) {
+                    seenAchievementsRef.current.delete(achievementId);
+                }
+            });
+        });
+        return () => {
+            unsubscribeUnlocked();
+            unsubscribeStateChanged();
+            if (confettiTimerRef.current) {
+                clearTimeout(confettiTimerRef.current);
+            }
+        };
+    }, [engine, ui.enableConfetti, ui.enableNotifications]);
+    const NotificationComponent = ui.NotificationComponent || BuiltInNotification;
+    const ConfettiComponentResolved = ui.ConfettiComponent || BuiltInConfetti;
+    return (React.createElement(React.Fragment, null,
+        ui.enableNotifications !== false &&
+            notifications.map((notification, index) => (React.createElement(NotificationComponent, { key: notification.achievementId, achievement: notification, onClose: () => setNotifications((currentNotifications) => currentNotifications.filter((currentNotification) => currentNotification.achievementId !== notification.achievementId)), duration: NOTIFICATION_DURATION_MS, position: ui.notificationPosition || 'top-center', theme: ui.theme || 'modern', icons: icons, stackIndex: index }))),
+        ui.enableConfetti !== false && (React.createElement(ConfettiComponentResolved, { show: showConfetti, duration: NOTIFICATION_DURATION_MS }))));
+};
+const AchievementProvider = (_a) => {
+    var { children, icons = {}, ui = {}, useBuiltInUI } = _a, providerProps = __rest(_a, ["children", "icons", "ui", "useBuiltInUI"]);
+    if (useBuiltInUI !== undefined) {
+        warnDeprecation('`useBuiltInUI` is deprecated and is now a no-op because built-in UI is the default. It will be removed in 4.2.');
+    }
+    const uiContextValue = React.useMemo(() => ({ icons, ui }), [icons, ui]);
+    return (React.createElement(AchievementUIContext.Provider, { value: uiContextValue },
+        React.createElement(AchievementProvider$1, Object.assign({}, providerProps, { icons: icons }),
+            children,
+            React.createElement(AchievementEffects, { icons: icons, ui: ui }))));
+};
+
+const useAchievements = () => {
+    const context = React.useContext(AchievementContext);
+    if (!context) {
+        throw new Error('useAchievements must be used within an AchievementProvider');
+    }
+    return context;
+};
+
+const useAchievementState = () => {
+    const { achievements, getAllAchievements, getState } = useAchievements();
+    const allAchievements = getAllAchievements();
+    const unlockedIds = achievements.unlocked;
+    const unlockedAchievementSet = new Set(unlockedIds);
+    const unlockedAchievements = allAchievements.filter((achievement) => unlockedAchievementSet.has(achievement.achievementId));
+    return {
+        unlockedIds,
+        unlockedAchievements,
+        allAchievements,
+        unlockedCount: unlockedIds.length,
+        totalCount: allAchievements.length,
+        metrics: getState().metrics,
+    };
+};
+
+const defaultStyles = {
+    badgesButton: {
+        backgroundColor: '#4CAF50',
+        color: 'white',
+        padding: '10px 20px',
+        border: 'none',
+        borderRadius: '20px',
+        cursor: 'pointer',
+        display: 'flex',
+        alignItems: 'center',
+        gap: '8px',
+        fontSize: '16px',
+        boxShadow: '0 2px 5px rgba(0,0,0,0.2)',
+        transition: 'transform 0.2s ease-in-out',
+    },
+    badgesModal: {
+        overlay: {
+            position: 'fixed',
+            top: 0,
+            right: 0,
+            bottom: 0,
+            left: 0,
+            backgroundColor: 'rgba(0, 0, 0, 0.75)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            zIndex: 10000,
+        },
+        content: {
+            position: 'relative',
+            background: '#fff',
+            borderRadius: '8px',
+            padding: '20px',
+            maxWidth: '500px',
+            width: '90%',
+            maxHeight: '80vh',
+            overflow: 'auto',
+        },
+        header: {
+            display: 'flex',
+            justifyContent: 'space-between',
+            alignItems: 'center',
+            marginBottom: '20px',
+        },
+        closeButton: {
+            background: 'none',
+            border: 'none',
+            fontSize: '24px',
+            cursor: 'pointer',
+            padding: '0',
+        },
+        achievementList: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '16px',
+        },
+        achievementItem: {
+            display: 'flex',
+            gap: '16px',
+            padding: '16px',
+            borderRadius: '8px',
+            backgroundColor: '#f5f5f5',
+            alignItems: 'center',
+        },
+        achievementTitle: {
+            margin: '0',
+            fontSize: '18px',
+            fontWeight: 'bold',
+        },
+        achievementDescription: {
+            margin: '4px 0 0 0',
+            color: '#666',
+        },
+        achievementIcon: {
+            fontSize: '32px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+        },
+        lockIcon: {
+            fontSize: '24px',
+            position: 'absolute',
+            top: '50%',
+            right: '16px',
+            transform: 'translateY(-50%)',
+        },
+        lockedAchievementItem: {
+            display: 'flex',
+            gap: '16px',
+            padding: '16px',
+            borderRadius: '8px',
+            backgroundColor: '#e0e0e0',
+            alignItems: 'center',
+            opacity: 0.5,
+        },
+    },
+    levelProgress: {
+        container: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '8px',
+            padding: '12px 16px',
+        },
+        header: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            gap: '12px',
+            fontWeight: 600,
+        },
+        levelLabel: {
+            fontSize: '14px',
+        },
+        valueText: {
+            fontSize: '12px',
+            opacity: 0.8,
+        },
+        progressTrack: {
+            position: 'relative',
+            height: '10px',
+            backgroundColor: 'rgba(255, 255, 255, 0.2)',
+            borderRadius: '999px',
+            overflow: 'hidden',
+        },
+        progressBar: {
+            height: '100%',
+            borderRadius: '999px',
+            transition: 'width 0.2s ease-in-out',
+        },
+        progressText: {
+            fontSize: '12px',
+            opacity: 0.8,
+            textAlign: 'right',
+        },
+    },
+};
+
+const resolveIcon = (achievement, icons) => {
+    return ((achievement.achievementIconKey && icons[achievement.achievementIconKey]) ||
+        achievement.achievementIconKey ||
+        icons.default ||
+        '⭐');
+};
+const AchievementsList = ({ achievements, showLocked = true, showUnlockConditions = false, icons = {}, styles = {}, emptyState, className, renderAchievement, }) => {
+    const context = React.useContext(AchievementContext);
+    const uiContext = React.useContext(AchievementUIContext);
+    const mergedIcons = Object.assign(Object.assign(Object.assign(Object.assign({}, defaultAchievementIcons), context === null || context === void 0 ? void 0 : context.icons), uiContext.icons), icons);
+    const sourceAchievements = achievements || (context === null || context === void 0 ? void 0 : context.getAllAchievements());
+    if (!sourceAchievements) {
+        throw new Error('AchievementsList requires either an achievements prop or an AchievementProvider parent.');
+    }
+    const achievementsToDisplay = showLocked
+        ? sourceAchievements
+        : sourceAchievements.filter((achievement) => achievement.isUnlocked);
+    if (achievementsToDisplay.length === 0) {
+        return (React.createElement("p", { style: { textAlign: 'center', color: '#666' } }, emptyState || 'No achievements configured.'));
+    }
+    return (React.createElement("div", { className: className, style: Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementList), styles === null || styles === void 0 ? void 0 : styles.achievementList), "data-testid": "achievements-list" }, achievementsToDisplay.map((achievement, index) => {
+        const isLocked = !achievement.isUnlocked;
+        const icon = resolveIcon(achievement, mergedIcons);
+        if (renderAchievement) {
+            return (React.createElement(React.Fragment, { key: achievement.achievementId }, renderAchievement({ achievement, isLocked, icon, index })));
+        }
+        return (React.createElement("div", { key: achievement.achievementId, style: Object.assign(Object.assign(Object.assign({}, (isLocked
+                ? Object.assign(Object.assign({}, defaultStyles.badgesModal.lockedAchievementItem), styles === null || styles === void 0 ? void 0 : styles.lockedAchievementItem) : defaultStyles.badgesModal.achievementItem)), styles === null || styles === void 0 ? void 0 : styles.achievementItem), { position: 'relative' }), "data-testid": "achievement-list-item", "data-unlocked": achievement.isUnlocked ? 'true' : 'false' },
+            React.createElement("div", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementIcon), styles === null || styles === void 0 ? void 0 : styles.achievementIcon), { opacity: isLocked ? 0.4 : 1 }) }, icon),
+            React.createElement("div", { style: { flex: 1 } },
+                React.createElement("h3", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementTitle), styles === null || styles === void 0 ? void 0 : styles.achievementTitle), { color: isLocked ? '#999' : undefined }) }, achievement.achievementTitle),
+                achievement.achievementDescription && (React.createElement("p", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementDescription), styles === null || styles === void 0 ? void 0 : styles.achievementDescription), { color: isLocked ? '#aaa' : '#666' }) },
+                    achievement.achievementDescription,
+                    showUnlockConditions && isLocked && (React.createElement("span", { style: {
+                            display: 'block',
+                            fontSize: '12px',
+                            marginTop: '4px',
+                            fontStyle: 'italic',
+                            color: '#888',
+                        } },
+                        "\uD83D\uDD13 ",
+                        achievement.achievementDescription))))),
+            isLocked && (React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.lockIcon), styles === null || styles === void 0 ? void 0 : styles.lockIcon) }, "\uD83D\uDD12"))));
+    })));
+};
+
+const AchievementsModal = ({ isOpen, onClose, achievements, title = '🏆 Achievements', styles = {}, icons = {}, showLocked = true, showUnlockConditions = false, emptyState, renderAchievement, theme, }) => {
+    const context = React.useContext(AchievementContext);
+    const uiContext = React.useContext(AchievementUIContext);
+    React.useEffect(() => {
+        if (!isOpen || typeof document === 'undefined') {
+            return;
+        }
+        const previousOverflow = document.body.style.overflow;
+        document.body.style.overflow = 'hidden';
+        const handleKeyDown = (event) => {
+            if (event.key === 'Escape') {
+                onClose();
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return () => {
+            document.body.style.overflow = previousOverflow;
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [isOpen, onClose]);
+    if (!isOpen)
+        return null;
+    const CustomModal = uiContext.ui.ModalComponent;
+    const sourceAchievements = achievements || (context === null || context === void 0 ? void 0 : context.getAllAchievements());
+    const modalAchievements = showLocked
+        ? sourceAchievements
+        : sourceAchievements === null || sourceAchievements === void 0 ? void 0 : sourceAchievements.filter((achievement) => achievement.isUnlocked);
+    const resolvedTheme = theme || uiContext.ui.theme || 'modern';
+    const mergedIcons = Object.assign(Object.assign(Object.assign(Object.assign({}, defaultAchievementIcons), context === null || context === void 0 ? void 0 : context.icons), uiContext.icons), icons);
+    if (CustomModal) {
+        if (!modalAchievements) {
+            throw new Error('AchievementsModal requires either an achievements prop or an AchievementProvider parent.');
+        }
+        return (React.createElement(CustomModal, { isOpen: isOpen, onClose: onClose, achievements: modalAchievements, icons: mergedIcons, theme: resolvedTheme }));
+    }
+    return (React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.overlay), styles === null || styles === void 0 ? void 0 : styles.overlay), role: "presentation", onClick: onClose, "data-testid": "achievements-modal-overlay" },
+        React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.content), styles === null || styles === void 0 ? void 0 : styles.content), role: "dialog", "aria-modal": "true", "aria-labelledby": "achievements-modal-title", onClick: (event) => event.stopPropagation(), "data-testid": "achievements-modal" },
+            React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.header), styles === null || styles === void 0 ? void 0 : styles.header) },
+                React.createElement("h2", { id: "achievements-modal-title", style: { margin: 0 } }, title),
+                React.createElement("button", { onClick: onClose, style: Object.assign(Object.assign({}, defaultStyles.badgesModal.closeButton), styles === null || styles === void 0 ? void 0 : styles.closeButton), "aria-label": "Close" }, "\u00D7")),
+            React.createElement(AchievementsList, { achievements: modalAchievements, showLocked: showLocked, showUnlockConditions: showUnlockConditions, icons: icons, styles: styles, emptyState: emptyState, renderAchievement: renderAchievement }))));
+};
+
+const getPositionStyles$1 = (position) => {
+    const base = {
+        position: 'fixed',
+        margin: '20px',
+        zIndex: 1000,
+    };
+    switch (position) {
+        case 'top-left':
+            return Object.assign(Object.assign({}, base), { top: 0, left: 0 });
+        case 'top-right':
+            return Object.assign(Object.assign({}, base), { top: 0, right: 0 });
+        case 'bottom-left':
+            return Object.assign(Object.assign({}, base), { bottom: 0, left: 0 });
+        case 'bottom-right':
+            return Object.assign(Object.assign({}, base), { bottom: 0, right: 0 });
+    }
+};
+const AchievementsWidget = ({ position = 'bottom-right', placement = 'fixed', showAllAchievements = true, showUnlockConditions = false, showCount = true, icons, theme, label = 'Achievements', icon = '🏆', triggerClassName, renderTrigger, buttonStyles, modalStyles, modalTitle, emptyState, renderAchievement, }) => {
+    const uiContext = React.useContext(AchievementUIContext);
+    const [isModalOpen, setIsModalOpen] = React.useState(false);
+    const { unlockedAchievements, allAchievements, unlockedCount, totalCount } = useAchievementState();
+    const resolvedTheme = theme || uiContext.ui.theme || 'modern';
+    const themeConfig = getTheme(resolvedTheme) || builtInThemes.modern;
+    const modalAchievements = showAllAchievements ? allAchievements : unlockedAchievements;
+    const openModal = () => setIsModalOpen(true);
+    const buttonBaseStyles = placement === 'inline'
+        ? Object.assign({ backgroundColor: 'transparent', color: 'inherit', padding: '10px 12px', border: 'none', borderRadius: '6px', cursor: 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '8px', font: 'inherit', width: '100%', textAlign: 'left' }, buttonStyles) : Object.assign(Object.assign({ backgroundColor: themeConfig.notification.accentColor, color: 'white', padding: '10px 20px', border: 'none', borderRadius: '20px', cursor: 'pointer', display: 'flex', alignItems: 'center', gap: '8px', fontSize: '16px', boxShadow: '0 2px 5px rgba(0,0,0,0.2)', transition: 'transform 0.2s ease-in-out' }, getPositionStyles$1(position)), buttonStyles);
+    const buttonProps = {
+        type: 'button',
+        onClick: openModal,
+        style: buttonBaseStyles,
+        className: triggerClassName,
+        'data-placement': placement,
+        'data-testid': 'achievements-widget-button',
+        'aria-label': `${label}: ${unlockedCount} of ${totalCount} achievements unlocked`,
+    };
+    return (React.createElement(React.Fragment, null,
+        renderTrigger ? (renderTrigger({
+            open: openModal,
+            label,
+            unlockedCount,
+            totalCount,
+            unlockedAchievements,
+            allAchievements,
+            buttonProps,
+        })) : (React.createElement("button", Object.assign({}, buttonProps, { onMouseEnter: (event) => {
+                if (placement !== 'inline') {
+                    event.currentTarget.style.transform = 'scale(1.05)';
+                }
+            }, onMouseLeave: (event) => {
+                if (placement !== 'inline') {
+                    event.currentTarget.style.transform = 'scale(1)';
+                }
+            } }),
+            React.createElement("span", null, icon),
+            React.createElement("span", { style: { flex: 1 } }, label),
+            showCount && React.createElement("span", null, unlockedCount))),
+        React.createElement(AchievementsModal, { isOpen: isModalOpen, onClose: () => setIsModalOpen(false), achievements: modalAchievements, showUnlockConditions: showUnlockConditions, icons: icons, styles: modalStyles, title: modalTitle, emptyState: emptyState, renderAchievement: renderAchievement, theme: resolvedTheme })));
+};
+
+const getPositionStyles = (position) => {
+    const base = {
+        position: 'fixed',
+        margin: '20px',
+        zIndex: 1000,
+    };
+    switch (position) {
+        case 'top-left':
+            return Object.assign(Object.assign({}, base), { top: 0, left: 0 });
+        case 'top-right':
+            return Object.assign(Object.assign({}, base), { top: 0, right: 0 });
+        case 'bottom-left':
+            return Object.assign(Object.assign({}, base), { bottom: 0, left: 0 });
+        case 'bottom-right':
+            return Object.assign(Object.assign({}, base), { bottom: 0, right: 0 });
+    }
+};
+/**
+ * @deprecated Use `AchievementsWidget` for new integrations. This v3
+ * compatibility wrapper will be removed in 4.2.
+ */
+const BadgesButton = ({ onClick, position = 'bottom-right', placement = 'fixed', styles = {}, unlockedAchievements, theme = 'modern', }) => {
+    React.useEffect(() => {
+        warnDeprecation('`BadgesButton` is deprecated. Use `AchievementsWidget` instead. `BadgesButton` will be removed in 4.2.');
+    }, []);
+    // Get theme configuration for consistent styling
+    const themeConfig = getTheme(theme) || builtInThemes.modern;
+    const accentColor = themeConfig.notification.accentColor;
+    // Different styling for fixed vs inline placement
+    const baseStyles = placement === 'inline'
+        ? Object.assign({ 
+            // Inline mode: looks like a navigation item
+            backgroundColor: 'transparent', color: themeConfig.notification.textColor, padding: '12px 16px', border: 'none', borderRadius: '6px', cursor: 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '8px', fontSize: '15px', width: '100%', textAlign: 'left', transition: 'background-color 0.2s ease-in-out' }, styles) : Object.assign(Object.assign({ 
+        // Fixed mode: floating button
+        backgroundColor: accentColor, color: 'white', padding: '10px 20px', border: 'none', borderRadius: '20px', cursor: 'pointer', display: 'flex', alignItems: 'center', gap: '8px', fontSize: '16px', boxShadow: '0 2px 5px rgba(0,0,0,0.2)', transition: 'transform 0.2s ease-in-out' }, getPositionStyles(position)), styles);
+    return (React.createElement("button", { onClick: onClick, style: baseStyles, onMouseEnter: (e) => {
+            if (placement === 'inline') {
+                // Inline mode: subtle background color change
+                e.target.style.backgroundColor = 'rgba(255, 255, 255, 0.1)';
+            }
+            else {
+                // Fixed mode: scale transformation
+                e.target.style.transform = 'scale(1.05)';
+            }
+        }, onMouseLeave: (e) => {
+            if (placement === 'inline') {
+                e.target.style.backgroundColor = 'transparent';
+            }
+            else {
+                e.target.style.transform = 'scale(1)';
             }
-          }
-        `),
-        React.createElement("div", { style: containerStyles, "data-testid": "built-in-confetti" }, particles)));
+        }, "data-placement": placement, "data-testid": "badges-button" },
+        "\uD83C\uDFC6 Achievements (",
+        unlockedAchievements.length,
+        ")"));
 };
 
-/******************************************************************************
-Copyright (c) Microsoft Corporation.
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
-***************************************************************************** */
-/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
-
-
-function __awaiter(thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-}
-
-typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+/**
+ * @deprecated Use `AchievementsModal`, `AchievementsWidget`, or
+ * `AchievementsList` for new integrations. This v3 compatibility wrapper will
+ * be removed in 4.2.
+ */
+const BadgesModal = ({ isOpen, onClose, achievements, styles = {}, icons = {}, showAllAchievements = false, showUnlockConditions = false, allAchievements, }) => {
+    React.useEffect(() => {
+        warnDeprecation('`BadgesModal` is deprecated. Use `AchievementsWidget` or `AchievementsList` instead. `BadgesModal` will be removed in 4.2.');
+    }, []);
+    const achievementsToDisplay = showAllAchievements && allAchievements
+        ? allAchievements
+        : achievements.map((achievement) => (Object.assign(Object.assign({}, achievement), { isUnlocked: true })));
+    return (React.createElement(AchievementsModal, { isOpen: isOpen, onClose: onClose, achievements: achievementsToDisplay, styles: styles, icons: icons, showUnlockConditions: showUnlockConditions }));
 };
 
 /**
- * Legacy UI library detection system
- * Attempts to dynamically import external UI libraries
- * Shows deprecation warnings when detected
+ * @deprecated Use `AchievementsWidget` for new integrations. This v3
+ * compatibility wrapper will be removed in 4.2.
  */
-let cachedLibraries = null;
-let detectionAttempted = false;
-let deprecationWarningShown = false;
+const BadgesButtonWithModal = ({ unlockedAchievements, position = 'bottom-right', placement = 'fixed', showAllAchievements = false, allAchievements, showUnlockConditions = false, icons, theme = 'modern', buttonStyles, modalStyles, }) => {
+    const [isModalOpen, setIsModalOpen] = React.useState(false);
+    return (React.createElement(React.Fragment, null,
+        React.createElement(BadgesButton, { onClick: () => setIsModalOpen(true), unlockedAchievements: unlockedAchievements, position: position, placement: placement, theme: theme, styles: buttonStyles }),
+        React.createElement(BadgesModal, { isOpen: isModalOpen, onClose: () => setIsModalOpen(false), achievements: unlockedAchievements, showAllAchievements: showAllAchievements, allAchievements: allAchievements, showUnlockConditions: showUnlockConditions, icons: icons, styles: modalStyles })));
+};
+
 /**
- * Attempts to dynamically import legacy UI libraries
- * Uses try/catch to gracefully handle missing dependencies
- * Caches result to avoid multiple import attempts
- *
- * @returns Promise resolving to LegacyLibraries object
+ * @deprecated Use the provider `ui.ConfettiComponent` option or the built-in
+ * confetti default. This v3 compatibility wrapper will be removed in 4.2.
  */
-function detectLegacyLibraries() {
-    return __awaiter(this, void 0, void 0, function* () {
-        if (detectionAttempted && cachedLibraries !== null) {
-            return cachedLibraries;
-        }
-        detectionAttempted = true;
-        const libraries = {};
-        // Try to import react-toastify
-        try {
-            const toastifyModule = yield import('react-toastify');
-            libraries.toast = toastifyModule.toast;
-            libraries.ToastContainer = toastifyModule.ToastContainer;
-        }
-        catch (_a) {
-            // Not installed, will use built-in notification
-        }
-        // Try to import react-modal
-        try {
-            const modalModule = yield import('react-modal');
-            libraries.Modal = modalModule.default;
-        }
-        catch (_b) {
-            // Not installed, will use built-in modal
-        }
-        // Try to import react-confetti
-        try {
-            const confettiModule = yield import('react-confetti');
-            libraries.Confetti = confettiModule.default;
-        }
-        catch (_c) {
-            // Not installed, will use built-in confetti
-        }
-        // Try to import react-use (only for useWindowSize)
-        try {
-            const reactUseModule = yield import('react-use');
-            libraries.useWindowSize = reactUseModule.useWindowSize;
-        }
-        catch (_d) {
-            // Not installed, will use built-in useWindowSize
-        }
-        cachedLibraries = libraries;
-        // Show deprecation warning if ANY legacy library is found
-        if (!deprecationWarningShown && Object.keys(libraries).length > 0) {
-            const foundLibraries = [];
-            if (libraries.toast)
-                foundLibraries.push('react-toastify');
-            if (libraries.Modal)
-                foundLibraries.push('react-modal');
-            if (libraries.Confetti)
-                foundLibraries.push('react-confetti');
-            if (libraries.useWindowSize)
-                foundLibraries.push('react-use');
-            console.warn(`[react-achievements] DEPRECATION WARNING: External UI dependencies (${foundLibraries.join(', ')}) are deprecated and will become fully optional in v4.0.0.\n\n` +
-                `The library now includes built-in UI components with modern design and theme support.\n\n` +
-                `To migrate:\n` +
-                `1. Add "useBuiltInUI={true}" to your AchievementProvider\n` +
-                `2. Test your application (UI will change to modern theme)\n` +
-                `3. Optionally customize with theme="minimal" or theme="gamified"\n` +
-                `4. Remove external dependencies from package.json\n\n` +
-                `To silence this warning, set useBuiltInUI={true} in AchievementProvider.\n\n` +
-                `Learn more: https://github.com/dave-b-b/react-achievements#migration-guide`);
-            deprecationWarningShown = true;
-        }
-        return libraries;
-    });
-}
+const ConfettiWrapper = ({ show }) => {
+    React.useEffect(() => {
+        warnDeprecation('`ConfettiWrapper` is deprecated. Use the provider `ui.ConfettiComponent` option or built-in confetti defaults instead. `ConfettiWrapper` will be removed in 4.2.');
+    }, []);
+    return React.createElement(BuiltInConfetti, { show: show, particleCount: 200 });
+};
+
+const clamp = (value, min, max) => {
+    return Math.min(Math.max(value, min), max);
+};
+const LevelProgress = ({ level, currentXP, nextLevelXP, label = 'Level', valueLabel, showValues = true, showPercent = true, theme = 'modern', styles = {}, className, }) => {
+    const themeConfig = getTheme(theme) || builtInThemes.modern;
+    const safeMax = nextLevelXP > 0 ? nextLevelXP : 1;
+    const clampedCurrent = clamp(currentXP, 0, safeMax);
+    const progress = Math.round((clampedCurrent / safeMax) * 100);
+    const computedValueLabel = valueLabel !== null && valueLabel !== void 0 ? valueLabel : `${clampedCurrent} / ${safeMax} XP`;
+    const containerStyles = Object.assign(Object.assign(Object.assign({}, defaultStyles.levelProgress.container), { background: themeConfig.notification.background, color: themeConfig.notification.textColor, borderRadius: themeConfig.notification.borderRadius, boxShadow: themeConfig.notification.boxShadow }), styles === null || styles === void 0 ? void 0 : styles.container);
+    const progressBarStyles = Object.assign(Object.assign(Object.assign({}, defaultStyles.levelProgress.progressBar), { backgroundColor: themeConfig.notification.accentColor, width: `${progress}%` }), styles === null || styles === void 0 ? void 0 : styles.progressBar);
+    return (React.createElement("div", { className: className, style: containerStyles, "data-testid": "level-progress" },
+        React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.levelProgress.header), styles === null || styles === void 0 ? void 0 : styles.header) },
+            React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.levelProgress.levelLabel), styles === null || styles === void 0 ? void 0 : styles.levelLabel) },
+                label,
+                " ",
+                level),
+            showValues && (React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.levelProgress.valueText), styles === null || styles === void 0 ? void 0 : styles.valueText) }, computedValueLabel))),
+        React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.levelProgress.progressTrack), styles === null || styles === void 0 ? void 0 : styles.progressTrack), role: "progressbar", "aria-valuemin": 0, "aria-valuemax": safeMax, "aria-valuenow": clampedCurrent, "aria-label": "Level progress" },
+            React.createElement("div", { style: progressBarStyles })),
+        showPercent && (React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.levelProgress.progressText), styles === null || styles === void 0 ? void 0 : styles.progressText) },
+            progress,
+            "%"))));
+};
+
+/**
+ * A simplified hook for achievement tracking.
+ * Provides the v4 happy path for direct metric updates plus explicit state names.
+ */
+const useSimpleAchievements = () => {
+    const { update, reset, getState, exportData, importData } = useAchievements();
+    const achievementState = useAchievementState();
+    const track = (metric, value) => update({ [metric]: value });
+    const increment = (metric, amount = 1) => {
+        const currentState = getState();
+        const currentMetricArray = currentState.metrics[metric] || [0];
+        const currentValue = Array.isArray(currentMetricArray)
+            ? currentMetricArray[0]
+            : currentMetricArray;
+        const newValue = (typeof currentValue === 'number' ? currentValue : 0) + amount;
+        update({ [metric]: newValue });
+    };
+    const trackMultiple = (metrics) => update(metrics);
+    return {
+        track,
+        increment,
+        trackMultiple,
+        unlockedIds: achievementState.unlockedIds,
+        unlockedAchievements: achievementState.unlockedAchievements,
+        allAchievements: achievementState.allAchievements,
+        unlockedCount: achievementState.unlockedCount,
+        totalCount: achievementState.totalCount,
+        metrics: achievementState.metrics,
+        reset,
+        getState,
+        exportData,
+        importData,
+        getAllAchievements: () => achievementState.allAchievements,
+        /**
+         * @deprecated Use `unlockedIds` instead. This alias will be removed in 4.2.
+         */
+        unlocked: achievementState.unlockedIds,
+        /**
+         * @deprecated Use `allAchievements` instead. This alias will be removed in 4.2.
+         */
+        all: achievementState.allAchievements,
+    };
+};
 
 /**
  * Built-in modal component
@@ -942,415 +1303,6 @@ const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'mode
                 })))))));
 };
 
-/**
- * Legacy library wrappers for backwards compatibility
- * Wraps external UI libraries to match our component interfaces
- */
-/**
- * Wrapper for react-toastify toast notifications
- * Falls back to built-in notification if not available
- */
-const createLegacyToastNotification = (libraries) => {
-    return ({ achievement, onClose, icons = {} }) => {
-        const { toast } = libraries;
-        //  Merge custom icons with defaults from react-achievements
-        const mergedIcons = Object.assign(Object.assign({}, defaultAchievementIcons), icons);
-        const icon = (achievement.achievementIconKey &&
-            mergedIcons[achievement.achievementIconKey]) ||
-            achievement.achievementIconKey ||
-            mergedIcons.default ||
-            '⭐';
-        React.useEffect(() => {
-            if (!toast)
-                return;
-            // Call toast.success with achievement content
-            toast.success(React.createElement("div", { style: { display: 'flex', alignItems: 'center' } },
-                React.createElement("span", { style: { fontSize: '2em', marginRight: '10px' } }, icon),
-                React.createElement("div", null,
-                    React.createElement("div", { style: { fontSize: '12px', opacity: 0.8, marginBottom: '4px' } }, "Achievement Unlocked!"),
-                    React.createElement("div", { style: { fontWeight: 'bold', marginBottom: '4px' } }, achievement.achievementTitle),
-                    achievement.achievementDescription && (React.createElement("div", { style: { fontSize: '13px', opacity: 0.9 } }, achievement.achievementDescription)))), {
-                position: 'top-right',
-                autoClose: 5000,
-                hideProgressBar: false,
-                closeOnClick: true,
-                pauseOnHover: true,
-                draggable: true,
-                toastId: achievement.achievementId,
-                onClose,
-            });
-        }, [achievement, toast, onClose, icon]);
-        return null; // Toast handles its own rendering
-    };
-};
-/**
- * Wrapper for react-confetti Confetti component
- * Falls back to built-in confetti if not available
- */
-const createLegacyConfettiWrapper = (libraries) => {
-    return ({ show, duration = 5000, particleCount = 200, colors }) => {
-        const { Confetti, useWindowSize: legacyUseWindowSize } = libraries;
-        // If Confetti not available, use built-in
-        if (!Confetti) {
-            return (React.createElement(BuiltInConfetti, { show: show, duration: duration, particleCount: particleCount, colors: colors }));
-        }
-        // Use react-confetti with react-use's useWindowSize if available
-        // Otherwise fall back to default dimensions
-        let width = 0;
-        let height = 0;
-        if (legacyUseWindowSize) {
-            const size = legacyUseWindowSize();
-            width = size.width;
-            height = size.height;
-        }
-        else if (typeof window !== 'undefined') {
-            width = window.innerWidth;
-            height = window.innerHeight;
-        }
-        if (!show)
-            return null;
-        return (React.createElement(Confetti, { width: width, height: height, numberOfPieces: particleCount, recycle: false, colors: colors, style: {
-                position: 'fixed',
-                top: 0,
-                left: 0,
-                zIndex: 10001,
-                pointerEvents: 'none',
-            } }));
-    };
-};
-
-const AchievementContext = React.createContext(undefined);
-const AchievementProvider = ({ achievements: achievementsConfig, storage = 'local', children, icons = {}, onError, restApiConfig, ui = {}, useBuiltInUI = false, engine: externalEngine, eventMapping, }) => {
-    // VALIDATION: Prevent mixing patterns
-    if (achievementsConfig && externalEngine) {
-        throw new Error('Cannot provide both "achievements" and "engine" props to AchievementProvider.\n\n' +
-            'Choose one pattern:\n' +
-            '1. OLD metric-based: <AchievementProvider achievements={config}>\n' +
-            '2. NEW event-based: <AchievementProvider engine={myEngine}>');
-    }
-    // Track which pattern is being used
-    const isLegacyPattern = Boolean(achievementsConfig);
-    // Engine instance (either external or auto-created)
-    // Initialize synchronously BEFORE first render to avoid timing issues
-    const [engine] = React.useState(() => {
-        if (externalEngine) {
-            // NEW PATTERN: Use external injected engine
-            return externalEngine;
-        }
-        // OLD PATTERN: Auto-create engine from achievements
-        if (!achievementsConfig) {
-            throw new Error('AchievementProvider requires either "achievements" or "engine" prop.\n\n' +
-                '1. OLD pattern: <AchievementProvider achievements={config}>\n' +
-                '2. NEW pattern: <AchievementProvider engine={myEngine}>');
-        }
-        return new achievementsEngine.AchievementEngine({
-            achievements: achievementsConfig,
-            storage: storage, // Type cast needed for compatibility
-            restApiConfig,
-            onError: onError,
-            eventMapping,
-        });
-    });
-    // React state synced from engine
-    // Initialize with current engine state (engine is available immediately)
-    const [achievementState, setAchievementState] = React.useState(() => {
-        const unlocked = engine.getUnlocked();
-        return {
-            unlocked: [...unlocked],
-            all: {}, // Will be populated by getAllAchievements
-        };
-    });
-    // Track which achievements have been seen to avoid duplicate notifications
-    const seenAchievementsRef = React.useRef(new Set(engine.getUnlocked()));
-    const [showConfetti, setShowConfetti] = React.useState(false);
-    // NEW: UI component resolution state (v3.6.0)
-    const [legacyLibraries, setLegacyLibraries] = React.useState(null);
-    const [uiReady, setUiReady] = React.useState(useBuiltInUI);
-    const [currentNotification, setCurrentNotification] = React.useState(null);
-    // Cleanup: Destroy engine on unmount (only if we auto-created it)
-    React.useEffect(() => {
-        return () => {
-            // Only destroy if we auto-created the engine
-            if (!externalEngine) {
-                engine.destroy();
-            }
-        };
-    }, [engine, externalEngine]);
-    // Subscribe to engine events
-    React.useEffect(() => {
-        // Engine is always available (initialized synchronously)
-        // Handle achievement unlocked
-        const unsubscribeUnlocked = engine.on('achievement:unlocked', (event) => {
-            // Update unlocked list
-            setAchievementState(prev => (Object.assign(Object.assign({}, prev), { unlocked: [...engine.getUnlocked()] })));
-            // Show notification if not seen before
-            if (!seenAchievementsRef.current.has(event.achievementId)) {
-                seenAchievementsRef.current.add(event.achievementId);
-                if (ui.enableNotifications !== false) {
-                    // Create a full AchievementWithStatus object for the notification
-                    const unlockedAchievement = {
-                        achievementId: event.achievementId,
-                        achievementTitle: event.achievementTitle,
-                        achievementDescription: event.achievementDescription,
-                        achievementIconKey: event.achievementIconKey,
-                        isUnlocked: true,
-                    };
-                    setCurrentNotification(unlockedAchievement);
-                    // Show confetti
-                    setShowConfetti(true);
-                    // Hide confetti after 5 seconds
-                    setTimeout(() => {
-                        setShowConfetti(false);
-                    }, 5000);
-                }
-            }
-        });
-        // Handle state changes (for syncing unlocked list)
-        const unsubscribeStateChanged = engine.on('state:changed', () => {
-            setAchievementState(prev => (Object.assign(Object.assign({}, prev), { unlocked: [...engine.getUnlocked()] })));
-        });
-        return () => {
-            unsubscribeUnlocked();
-            unsubscribeStateChanged();
-        };
-    }, [engine, icons, ui.enableNotifications]);
-    // Detect legacy UI libraries on mount
-    React.useEffect(() => {
-        if (useBuiltInUI) {
-            setUiReady(true);
-            return;
-        }
-        detectLegacyLibraries().then((libs) => {
-            setLegacyLibraries(libs);
-            setUiReady(true);
-        });
-    }, [useBuiltInUI]);
-    // Resolve UI components based on detection and config
-    const NotificationComponent = ui.NotificationComponent ||
-        (useBuiltInUI ? BuiltInNotification :
-            legacyLibraries && Object.keys(legacyLibraries).length > 0 && legacyLibraries.toast
-                ? createLegacyToastNotification(legacyLibraries)
-                : BuiltInNotification);
-    const ConfettiComponentResolved = ui.ConfettiComponent ||
-        (useBuiltInUI ? BuiltInConfetti :
-            legacyLibraries && Object.keys(legacyLibraries).length > 0 && legacyLibraries.Confetti
-                ? createLegacyConfettiWrapper(legacyLibraries)
-                : BuiltInConfetti);
-    // Context methods - delegate to engine
-    const update = (newMetrics) => {
-        engine.update(newMetrics);
-    };
-    const reset = () => {
-        engine.reset();
-        seenAchievementsRef.current.clear();
-        setShowConfetti(false);
-        setCurrentNotification(null);
-    };
-    const getState = () => {
-        const metrics = engine.getMetrics();
-        const unlocked = engine.getUnlocked();
-        // Convert metrics to array format for backward compatibility
-        const metricsInArrayFormat = {};
-        Object.entries(metrics).forEach(([key, value]) => {
-            metricsInArrayFormat[key] = Array.isArray(value) ? value : [value];
-        });
-        return {
-            metrics: metricsInArrayFormat,
-            unlocked: [...unlocked],
-        };
-    };
-    const exportData = () => {
-        return engine.export();
-    };
-    const importData = (jsonString, options) => {
-        var _a;
-        const result = engine.import(jsonString, options);
-        // Update seen achievements to prevent duplicate notifications
-        if ((result === null || result === void 0 ? void 0 : result.success) && 'mergedUnlocked' in result) {
-            (_a = result.mergedUnlocked) === null || _a === void 0 ? void 0 : _a.forEach((id) => {
-                seenAchievementsRef.current.add(id);
-            });
-        }
-        return result;
-    };
-    const getAllAchievements = () => {
-        return engine.getAllAchievements();
-    };
-    return (React.createElement(AchievementContext.Provider, { value: {
-            update,
-            achievements: achievementState,
-            reset,
-            getState,
-            exportData,
-            importData,
-            getAllAchievements,
-            engine, // Always defined - no undefined fallback needed
-            _isLegacyPattern: isLegacyPattern, // NEW: Expose pattern flag to hooks
-        } },
-        children,
-        uiReady && currentNotification && ui.enableNotifications !== false && (React.createElement(NotificationComponent, { achievement: currentNotification, onClose: () => setCurrentNotification(null), duration: 5000, position: ui.notificationPosition || 'top-center', theme: ui.theme || 'modern', icons: icons })),
-        uiReady && ui.enableConfetti !== false && (React.createElement(ConfettiComponentResolved, { show: showConfetti, duration: 5000 }))));
-};
-
-const useAchievements = () => {
-    const context = React.useContext(AchievementContext);
-    if (!context) {
-        throw new Error('useAchievements must be used within an AchievementProvider');
-    }
-    // STRICT CHECK: Detect if Provider has injected engine (new pattern)
-    if (!context._isLegacyPattern) {
-        throw new Error('Cannot use useAchievements when AchievementProvider has injected engine.\n\n' +
-            'You are using the NEW event-based pattern.\n' +
-            'useAchievements is for the OLD metric-based pattern only.\n\n' +
-            'Use engine.emit() instead:\n' +
-            '  const engine = useAchievementEngine();\n' +
-            '  engine.emit("eventName", data);\n\n' +
-            'Or switch to the old pattern:\n' +
-            '  <AchievementProvider achievements={config}>\n' +
-            '  const { track } = useAchievements();\n' +
-            '  track("score", 100);');
-    }
-    return context;
-};
-
-/**
- * A simplified hook for achievement tracking.
- * Provides an easier API for common use cases while maintaining access to advanced features.
- */
-const useSimpleAchievements = () => {
-    const { update, achievements, reset, getState, exportData, importData, getAllAchievements } = useAchievements();
-    return {
-        /**
-         * Track a metric value for achievements
-         * @param metric - The metric name (e.g., 'score', 'level')
-         * @param value - The metric value
-         */
-        track: (metric, value) => update({ [metric]: value }),
-        /**
-         * Increment a numeric metric by a specified amount
-         * @param metric - The metric name (e.g., 'buttonClicks', 'score')
-         * @param amount - The amount to increment by (defaults to 1)
-         */
-        increment: (metric, amount = 1) => {
-            const currentState = getState();
-            const currentMetricArray = currentState.metrics[metric] || [0];
-            const currentValue = Array.isArray(currentMetricArray) ? currentMetricArray[0] : currentMetricArray;
-            const newValue = (typeof currentValue === 'number' ? currentValue : 0) + amount;
-            update({ [metric]: newValue });
-        },
-        /**
-         * Track multiple metrics at once
-         * @param metrics - Object with metric names as keys and values
-         */
-        trackMultiple: (metrics) => update(metrics),
-        /**
-         * Array of unlocked achievement IDs
-         */
-        unlocked: achievements.unlocked,
-        /**
-         * All available achievements
-         */
-        all: achievements.all,
-        /**
-         * Number of unlocked achievements
-         */
-        unlockedCount: achievements.unlocked.length,
-        /**
-         * Reset all achievement progress
-         */
-        reset,
-        /**
-         * Get current state (advanced usage)
-         */
-        getState,
-        /**
-         * Export achievement data to JSON string
-         * @returns JSON string containing all achievement data
-         */
-        exportData,
-        /**
-         * Import achievement data from JSON string
-         * @param jsonString - JSON string containing exported achievement data
-         * @param options - Import options (merge strategy, validation)
-         * @returns Import result with success status and any errors
-         */
-        importData,
-        /**
-         * Get all achievements with their unlock status
-         * @returns Array of achievements with isUnlocked boolean property
-         */
-        getAllAchievements,
-    };
-};
-
-/**
- * Hook to access the injected AchievementEngine instance (NEW event-based pattern)
- *
- * IMPORTANT: This hook only works when Provider has an externally created engine injected via the `engine` prop.
- * Do NOT use this hook with the old `achievements` prop pattern - use `useAchievements()` instead.
- *
- * @example
- * ```tsx
- * // Create engine outside React
- * import { AchievementEngine } from 'achievements-engine';
- *
- * const myEngine = new AchievementEngine({
- *   achievements: config,
- *   eventMapping: { 'userScored': 'score', 'levelUp': 'level' },
- *   storage: 'local'
- * });
- *
- * // Inject into Provider
- * <AchievementProvider engine={myEngine}>
- *   <App />
- * </AchievementProvider>
- *
- * function App() {
- *   const engine = useAchievementEngine();
- *   engine.emit('userScored', 100);
- *   engine.emit('levelUp', 5);
- * }
- * ```
- *
- * @returns AchievementEngine instance
- * @throws Error if used with old achievements prop pattern
- * @throws Error if used outside AchievementProvider
- * @since 3.8.0
- */
-const useAchievementEngine = () => {
-    const context = React.useContext(AchievementContext);
-    if (!context) {
-        throw new Error('useAchievementEngine must be used within an AchievementProvider.\n\n' +
-            'Wrap your component tree:\n' +
-            'const myEngine = new AchievementEngine({ achievements, eventMapping });\n' +
-            '<AchievementProvider engine={myEngine}>\n' +
-            '  <YourComponent />\n' +
-            '</AchievementProvider>');
-    }
-    // STRICT CHECK: Detect if Provider was initialized with achievements (old pattern)
-    if (context._isLegacyPattern) {
-        throw new Error('Cannot use useAchievementEngine when AchievementProvider has achievements prop.\n\n' +
-            'You are using the OLD metric-based pattern.\n' +
-            'useAchievementEngine is for the NEW event-based pattern only.\n\n' +
-            'Choose one:\n\n' +
-            '1. OLD PATTERN (keep current code):\n' +
-            '   <AchievementProvider achievements={config}>\n' +
-            '   const { track } = useAchievements();\n' +
-            '   track("score", 100);\n\n' +
-            '2. NEW PATTERN (migrate to events):\n' +
-            '   const engine = new AchievementEngine({ achievements, eventMapping });\n' +
-            '   <AchievementProvider engine={engine}>\n' +
-            '   const engine = useAchievementEngine();\n' +
-            '   engine.emit("userScored", 100);');
-    }
-    if (!context.engine) {
-        throw new Error('No engine available. AchievementProvider requires either:\n' +
-            '1. achievements prop (old pattern)\n' +
-            '2. engine prop (new pattern)');
-    }
-    return context.engine;
-};
-
 Object.defineProperty(exports, 'AchievementBuilder', {
     enumerable: true,
     get: function () { return achievementsEngine.AchievementBuilder; }
@@ -1441,6 +1393,9 @@ Object.defineProperty(exports, 'normalizeAchievements', {
 });
 exports.AchievementContext = AchievementContext;
 exports.AchievementProvider = AchievementProvider;
+exports.AchievementsList = AchievementsList;
+exports.AchievementsModal = AchievementsModal;
+exports.AchievementsWidget = AchievementsWidget;
 exports.BadgesButton = BadgesButton;
 exports.BadgesButtonWithModal = BadgesButtonWithModal;
 exports.BadgesModal = BadgesModal;
@@ -1448,10 +1403,13 @@ exports.BuiltInConfetti = BuiltInConfetti;
 exports.BuiltInModal = BuiltInModal;
 exports.BuiltInNotification = BuiltInNotification;
 exports.ConfettiWrapper = ConfettiWrapper;
+exports.HeadlessAchievementProvider = AchievementProvider$1;
+exports.LevelProgress = LevelProgress;
 exports.defaultAchievementIcons = defaultAchievementIcons;
 exports.defaultStyles = defaultStyles;
 exports.isAsyncStorage = isAsyncStorage;
 exports.useAchievementEngine = useAchievementEngine;
+exports.useAchievementState = useAchievementState;
 exports.useAchievements = useAchievements;
 exports.useSimpleAchievements = useSimpleAchievements;
 exports.useWindowSize = useWindowSize;