@vlian/framework 1.2.54 → 1.2.56

package/dist/index.umd.js

@@ -1,14 +1,14 @@
 /*!
- * @vlian/framework v1.2.53
+ * @vlian/framework v1.2.55
  * Secra Framework - 一个现代化的低代码框架
  * (c) 2026 Secra Framework Contributors
  * Licensed under Apache-2.0
  */
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('@vlian/utils'), require('@vlian/logger'), require('@vlian/monitoring'), require('react/jsx-runtime'), require('react-dom/client'), require('react'), require('react-router-dom'), require('zod'), require('i18next'), require('react-i18next'), require('@vlian/csrf'), require('@/utils')) :
-    typeof define === 'function' && define.amd ? define(['exports', '@vlian/utils', '@vlian/logger', '@vlian/monitoring', 'react/jsx-runtime', 'react-dom/client', 'react', 'react-router-dom', 'zod', 'i18next', 'react-i18next', '@vlian/csrf', '@/utils'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.vlianFramework = {}, global.vlianUtils, global.logger, global.monitoring, global.jsxRuntime, global.ReactDOMClient, global.React, global.ReactRouterDOM, global.z, global.i18next, global.ReactI18next, global.csrf, global.utils$1));
-})(this, (function (exports, vlianUtils, logger, monitoring, jsxRuntime, client, React, reactRouterDom, zod, i18n, reactI18next, csrf, utils$1) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('@vlian/utils'), require('@vlian/logger'), require('@vlian/monitoring'), require('react/jsx-runtime'), require('react-dom/client'), require('react'), require('react-router-dom'), require('zod'), require('i18next'), require('react-i18next'), require('@vlian/csrf')) :
+    typeof define === 'function' && define.amd ? define(['exports', '@vlian/utils', '@vlian/logger', '@vlian/monitoring', 'react/jsx-runtime', 'react-dom/client', 'react', 'react-router-dom', 'zod', 'i18next', 'react-i18next', '@vlian/csrf'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.vlianFramework = {}, global.vlianUtils, global.logger, global.monitoring, global.jsxRuntime, global.ReactDOMClient, global.React, global.ReactRouterDOM, global.z, global.i18next, global.ReactI18next, global.csrf));
+})(this, (function (exports, vlianUtils, logger, monitoring, jsxRuntime, client, React, reactRouterDom, zod, i18n, reactI18next, csrf) { 'use strict';
 
     function _interopNamespaceDefault(e) {
         var n = Object.create(null);
@@ -29,84 +29,13 @@
 
     var vlianUtils__namespace = /*#__PURE__*/_interopNamespaceDefault(vlianUtils);
 
-    const local$1 = {
-        notfound: {
-            home: "Back to Home"
-        },
-        defaultApp: {
-            title: "Welcome to Secra Framework",
-            description: "Framework has been successfully started! Please provide your app component to get started.",
-            quickStart: {
-                title: "Quick Start",
-                description: "Provide the app option in your startup configuration to render your application:",
-                code: "import { start } from '@vlian/framework';\nimport App from './App';\n\nstart({\n  app: <App />,\n});"
-            },
-            nextSteps: {
-                title: "Next Steps",
-                step1: "Create your application root component (e.g., App.tsx)",
-                step2: "Pass the app option in your startup configuration",
-                step3: "Start developing your application features"
-            },
-            footer: "Secra Framework - Modern Low-Code Frontend Application Framework"
-        }
-    };
-
-    const local = {
-        notfound: {
-            home: "回到首页"
-        },
-        defaultApp: {
-            title: "欢迎使用 Secra Framework",
-            description: "框架已成功启动！请提供您的应用组件以开始使用。",
-            quickStart: {
-                title: "快速开始",
-                description: "在启动配置中提供 app 选项来渲染您的应用：",
-                code: "import { start } from '@vlian/framework';\nimport App from './App';\n\nstart({\n  app: <App />,\n});"
-            },
-            nextSteps: {
-                title: "下一步",
-                step1: "创建您的应用根组件（如 App.tsx）",
-                step2: "在启动配置中传入 app 选项",
-                step3: "开始开发您的应用功能"
-            },
-            footer: "Secra Framework - 现代化的低代码前端应用框架"
-        }
-    };
-
-    let setupPromise = null;
-    /** Setup plugin i18n */ function setupI18n(otherLocales = {
-        'en-US': {},
-        'zh-CN': {}
-    }) {
-        const locales = {
-            'en-US': {
-                translation: Object.assign({}, local$1, otherLocales['en-US'])
-            },
-            'zh-CN': {
-                translation: Object.assign({}, local, otherLocales['zh-CN'])
-            }
-        };
-        if (i18n.isInitialized) {
-            i18n.addResourceBundle('en-US', 'translation', locales['en-US'].translation, true, true);
-            i18n.addResourceBundle('zh-CN', 'translation', locales['zh-CN'].translation, true, true);
-            return Promise.resolve(i18n);
-        }
-        if (setupPromise) {
-            return setupPromise;
-        }
-        const initPromise = i18n.use(reactI18next.initReactI18next).init({
-            interpolation: {
-                escapeValue: false
-            },
-            lng: 'zh-CN',
-            resources: locales
-        }).then(()=>i18n);
-        setupPromise = initPromise;
-        return initPromise;
+    const reactI18nextInstance = i18n.use(reactI18next.initReactI18next);
+    /** Setup plugin i18n */ async function setupI18n(options, callback) {
+        await reactI18nextInstance.init(options, callback);
     }
     const $t = i18n.t;
-    function setLang(locale) {
-        i18n.changeLanguage(locale);
+    async function setLang(locale, callback) {
+        await i18n.changeLanguage(locale, callback);
     }
 
     function _define_property$K(obj, key, value) {
@@ -1269,13 +1198,13 @@
 
     /**
      * 初始化方法
-     * 
+     *
      * 这是核心的初始化逻辑，可被启动页或直接调用
-     * 
+     *
      * @param options - 初始化选项
      * @param onProgress - 进度回调函数（可选）
      * @returns Promise<InitializationContext>
-     * 
+     *
      * @example
      * ```typescript
      * const context = await initialization({
@@ -11980,7 +11909,7 @@
         }
         return window.localStorage;
     }
-    function readPersistedValue$1(options, defaultKey) {
+    function readPersistedValue(options, defaultKey) {
         if (options.enabled === false) {
             return null;
         }
@@ -11994,7 +11923,7 @@
             return null;
         }
     }
-    function writePersistedValue$1(value, options, defaultKey) {
+    function writePersistedValue(value, options, defaultKey) {
         if (options.enabled === false || !value) {
             return;
         }
@@ -12042,7 +11971,7 @@
                 return;
             }
             hydratedRef.current = true;
-            const persistedMode = readPersistedValue$1(persistenceOptions, DEFAULT_THEME_STORAGE_KEY);
+            const persistedMode = readPersistedValue(persistenceOptions, DEFAULT_THEME_STORAGE_KEY);
             if (!persistedMode || !isThemeMode(persistedMode) || !modes.includes(persistedMode)) {
                 return;
             }
@@ -12063,7 +11992,7 @@
             if (!mode || lastWrittenModeRef.current === mode) {
                 return;
             }
-            writePersistedValue$1(mode, persistenceOptions, DEFAULT_THEME_STORAGE_KEY);
+            writePersistedValue(mode, persistenceOptions, DEFAULT_THEME_STORAGE_KEY);
             lastWrittenModeRef.current = mode;
         }, [
             persistenceOptions,
@@ -12137,7 +12066,7 @@
                 return;
             }
             hydratedRef.current = true;
-            const persistedLocale = readPersistedValue$1(persistenceOptions, DEFAULT_LOCALE_STORAGE_KEY);
+            const persistedLocale = readPersistedValue(persistenceOptions, DEFAULT_LOCALE_STORAGE_KEY);
             if (!persistedLocale || !isLocale(persistedLocale) || !locales.includes(persistedLocale)) {
                 return;
             }
@@ -12154,7 +12083,7 @@
             if (lastWrittenLocaleRef.current === locale) {
                 return;
             }
-            writePersistedValue$1(locale, persistenceOptions, DEFAULT_LOCALE_STORAGE_KEY);
+            writePersistedValue(locale, persistenceOptions, DEFAULT_LOCALE_STORAGE_KEY);
             lastWrittenLocaleRef.current = locale;
         }, [
             locale,
@@ -12245,76 +12174,6 @@
         }
     };
 
-    function resolveStorageInstance(driver) {
-        if (driver === 'none' || typeof window === 'undefined') {
-            return null;
-        }
-        const instance = driver === 'localStorage' ? storage.local : driver === 'sessionStorage' ? storage.session : storage.indexedDB;
-        if (!instance || typeof instance.get !== 'function' || typeof instance.set !== 'function') {
-            return null;
-        }
-        return instance;
-    }
-    async function readPersistedValue(persistence) {
-        if (!persistence || persistence.enabled === false) {
-            return null;
-        }
-        const driver = persistence.storage ?? 'localStorage';
-        const key = persistence.key;
-        if (!key) {
-            return null;
-        }
-        const targetStorage = resolveStorageInstance(driver);
-        if (!targetStorage) {
-            return null;
-        }
-        try {
-            const value = await targetStorage.get(key);
-            if (value === null || value === undefined) {
-                return null;
-            }
-            if (typeof value === 'string') {
-                return value;
-            }
-            return JSON.stringify(value);
-        } catch  {
-            return null;
-        }
-    }
-    async function writePersistedValue(persistence, value) {
-        if (!persistence || persistence.enabled === false) {
-            return;
-        }
-        const driver = persistence.storage ?? 'localStorage';
-        const key = persistence.key;
-        if (!key) {
-            return;
-        }
-        const targetStorage = resolveStorageInstance(driver);
-        if (!targetStorage) {
-            return;
-        }
-        try {
-            await targetStorage.set(key, value);
-        } catch (e) {
-            utils$1.logger.error(e);
-        // ignore persistence errors
-        }
-    }
-
-    function _define_property$4(obj, key, value) {
-        if (key in obj) {
-            Object.defineProperty(obj, key, {
-                value: value,
-                enumerable: true,
-                configurable: true,
-                writable: true
-            });
-        } else {
-            obj[key] = value;
-        }
-        return obj;
-    }
     function normalizeLogLevel(value, fallback) {
         if (typeof value === 'number' && Number.isInteger(value)) {
             switch(value){
@@ -12353,26 +12212,93 @@
                 return fallback;
         }
     }
+    function normalizeLoggerSnapshot(value, fallback) {
+        if (typeof value === 'number' || typeof value === 'string') {
+            return {
+                level: normalizeLogLevel(value, fallback.level)
+            };
+        }
+        const source = value && typeof value === 'object' ? value : {};
+        return {
+            level: normalizeLogLevel(source.level, fallback.level)
+        };
+    }
+    function isLoggerEqual(left, right) {
+        return left.level === right.level;
+    }
+
+    const DEFAULT_LOGGER_CACHE_KEY = 'vlian:kernel:logger-level';
+    function resolvePersistenceContext$2(persistence) {
+        if (persistence?.enabled !== true) {
+            return null;
+        }
+        return {
+            key: persistence.key || DEFAULT_LOGGER_CACHE_KEY
+        };
+    }
+    async function loadLoggerFromCache(cacheManager, persistence, fallback) {
+        const persistenceContext = resolvePersistenceContext$2(persistence);
+        if (!persistenceContext) {
+            return {
+                ...fallback
+            };
+        }
+        try {
+            const cached = await cacheManager.get(persistenceContext.key, {
+                defaultValue: fallback
+            });
+            return normalizeLoggerSnapshot(cached, fallback);
+        } catch  {
+            return {
+                ...fallback
+            };
+        }
+    }
+    async function saveLoggerToCache(cacheManager, persistence, snapshot) {
+        const persistenceContext = resolvePersistenceContext$2(persistence);
+        if (!persistenceContext) {
+            return;
+        }
+        try {
+            await cacheManager.set(persistenceContext.key, {
+                ...snapshot
+            });
+        } catch  {
+        // Ignore persistence failures and keep logger updates in memory.
+        }
+    }
+
+    function _define_property$4(obj, key, value) {
+        if (key in obj) {
+            Object.defineProperty(obj, key, {
+                value: value,
+                enumerable: true,
+                configurable: true,
+                writable: true
+            });
+        } else {
+            obj[key] = value;
+        }
+        return obj;
+    }
     class LoggerManager {
         async initialize(context) {
             this.config = context.config.logger;
-            const hasConfiguredLevel = this.config.level !== undefined && this.config.level !== null;
-            const configuredLevel = normalizeLogLevel(this.config.level, logger.LogLevel.INFO);
-            if (hasConfiguredLevel) {
-                this.level = configuredLevel;
-                logger.logger.setLevel(this.level);
-                await writePersistedValue(this.config.persistence, String(this.level));
-                return;
-            }
-            const persisted = await readPersistedValue(this.config.persistence);
-            if (persisted !== null) {
-                this.level = normalizeLogLevel(persisted, configuredLevel);
-                logger.logger.setLevel(this.level);
-                return;
-            }
-            this.level = configuredLevel;
-            logger.logger.setLevel(this.level);
-            await writePersistedValue(this.config.persistence, String(this.level));
+            this.cacheManager = context.cacheManager;
+            const initialSnapshot = normalizeLoggerSnapshot({
+                level: this.config.level
+            }, {
+                level: logger.LogLevel.INFO
+            });
+            this.snapshot = await loadLoggerFromCache(this.cacheManager, this.config.persistence, initialSnapshot);
+            logger.logger.setLevel(this.snapshot.level);
+            this.initialized = true;
+        }
+        subscribe(listener) {
+            this.listeners.add(listener);
+            return ()=>{
+                this.listeners.delete(listener);
+            };
         }
         debug(...args) {
             logger.logger.debug(...args);
@@ -12387,18 +12313,52 @@
             logger.logger.error(...args);
         }
         async setLevel(level) {
-            this.level = level;
-            logger.logger.setLevel(level);
-            await writePersistedValue(this.config.persistence, String(level));
+            this.ensureInitialized();
+            const prevSnapshot = this.snapshot;
+            const nextSnapshot = normalizeLoggerSnapshot({
+                level
+            }, prevSnapshot);
+            if (isLoggerEqual(prevSnapshot, nextSnapshot)) {
+                return;
+            }
+            this.snapshot = nextSnapshot;
+            logger.logger.setLevel(this.snapshot.level);
+            if (this.cacheManager) {
+                await saveLoggerToCache(this.cacheManager, this.config.persistence, this.snapshot);
+            }
+            this.emit(this.snapshot, prevSnapshot);
         }
         getSnapshot() {
             return {
-                level: this.level
+                ...this.snapshot
             };
         }
+        ensureInitialized() {
+            if (!this.initialized) {
+                throw new Error('LoggerManager must be initialized before use.');
+            }
+        }
+        emit(next, prev) {
+            for (const listener of this.listeners){
+                try {
+                    listener({
+                        ...next
+                    }, {
+                        ...prev
+                    });
+                } catch  {
+                // Keep notifying remaining listeners even if one fails.
+                }
+            }
+        }
         constructor(){
-            _define_property$4(this, "level", logger.LogLevel.INFO);
+            _define_property$4(this, "snapshot", {
+                level: logger.LogLevel.INFO
+            });
             _define_property$4(this, "config", DEFAULT_CONFIG.logger);
+            _define_property$4(this, "listeners", new Set());
+            _define_property$4(this, "cacheManager", null);
+            _define_property$4(this, "initialized", false);
         }
     }
 
@@ -12437,6 +12397,182 @@
         }
     }
 
+    function canUseDom() {
+        return typeof document !== 'undefined';
+    }
+    function resolveThemeMode(theme) {
+        if (theme.mode !== 'system') {
+            return theme.mode;
+        }
+        if (typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+            return 'dark';
+        }
+        return 'light';
+    }
+    function applyThemeToDocument(nextTheme, prevTheme) {
+        if (!canUseDom()) {
+            return;
+        }
+        const root = document.documentElement;
+        const nextMode = resolveThemeMode(nextTheme);
+        const prevMode = prevTheme ? resolveThemeMode(prevTheme) : undefined;
+        if (!prevMode || prevMode !== nextMode) {
+            root.classList.remove('light', 'dark');
+            root.classList.add(nextMode);
+        }
+        if (!prevTheme || prevTheme.primaryColor !== nextTheme.primaryColor) {
+            if (nextTheme.primaryColor) {
+                root.style.setProperty('--app-primary-color', nextTheme.primaryColor);
+            } else {
+                root.style.removeProperty('--app-primary-color');
+            }
+        }
+        const prevTokens = prevTheme?.tokens || {};
+        const nextTokens = nextTheme.tokens || {};
+        for (const token of Object.keys(prevTokens)){
+            if (!(token in nextTokens)) {
+                root.style.removeProperty(`--${token}`);
+            }
+        }
+        for (const [token, value] of Object.entries(nextTokens)){
+            if (!prevTheme || prevTokens[token] !== value) {
+                root.style.setProperty(`--${token}`, String(value));
+            }
+        }
+    }
+
+    const VALID_THEME_MODES = new Set([
+        'light',
+        'dark',
+        'system'
+    ]);
+    const TOKEN_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+    function isPlainObject$1(value) {
+        return Object.prototype.toString.call(value) === '[object Object]';
+    }
+    function hasOwnProperty(value, key) {
+        return Object.prototype.hasOwnProperty.call(value, key);
+    }
+    function cloneTheme(theme) {
+        return {
+            ...theme,
+            ...theme.tokens ? {
+                tokens: {
+                    ...theme.tokens
+                }
+            } : {}
+        };
+    }
+    function sanitizeTokens(tokens) {
+        if (!isPlainObject$1(tokens)) {
+            return undefined;
+        }
+        const sanitizedTokens = {};
+        for (const [token, tokenValue] of Object.entries(tokens)){
+            if (!TOKEN_NAME_PATTERN.test(token)) {
+                continue;
+            }
+            if (typeof tokenValue === 'string' || typeof tokenValue === 'number') {
+                sanitizedTokens[token] = tokenValue;
+            }
+        }
+        return Object.keys(sanitizedTokens).length > 0 ? sanitizedTokens : undefined;
+    }
+    function normalizeTheme(value, fallback) {
+        const source = isPlainObject$1(value) ? value : {};
+        const mode = VALID_THEME_MODES.has(source.mode) ? source.mode : fallback.mode;
+        const primaryColor = typeof source.primaryColor === 'string' && source.primaryColor.trim() ? source.primaryColor : fallback.primaryColor;
+        const fallbackTokens = sanitizeTokens(fallback.tokens);
+        const incomingTokens = sanitizeTokens(source.tokens);
+        return {
+            mode,
+            ...primaryColor ? {
+                primaryColor
+            } : {},
+            ...incomingTokens || fallbackTokens ? {
+                tokens: {
+                    ...fallbackTokens || {},
+                    ...incomingTokens || {}
+                }
+            } : {}
+        };
+    }
+    function mergeTheme(current, next) {
+        const mergedTheme = {
+            mode: hasOwnProperty(next, 'mode') && VALID_THEME_MODES.has(next.mode) ? next.mode : current.mode,
+            ...hasOwnProperty(next, 'primaryColor') ? typeof next.primaryColor === 'string' && next.primaryColor.trim() ? {
+                primaryColor: next.primaryColor
+            } : {} : current.primaryColor ? {
+                primaryColor: current.primaryColor
+            } : {},
+            ...hasOwnProperty(next, 'tokens') ? sanitizeTokens(next.tokens) ? {
+                tokens: sanitizeTokens(next.tokens)
+            } : {} : current.tokens ? {
+                tokens: {
+                    ...current.tokens
+                }
+            } : {}
+        };
+        return normalizeTheme(mergedTheme, DEFAULT_EMPTY_THEME);
+    }
+    const DEFAULT_EMPTY_THEME = {
+        mode: 'light'
+    };
+    function isThemeEqual(left, right) {
+        if (left.mode !== right.mode || left.primaryColor !== right.primaryColor) {
+            return false;
+        }
+        const leftTokens = left.tokens || {};
+        const rightTokens = right.tokens || {};
+        const leftKeys = Object.keys(leftTokens);
+        const rightKeys = Object.keys(rightTokens);
+        if (leftKeys.length !== rightKeys.length) {
+            return false;
+        }
+        for (const key of leftKeys){
+            if (leftTokens[key] !== rightTokens[key]) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    const DEFAULT_THEME_CACHE_KEY = 'vlian:kernel:theme';
+    function resolvePersistenceContext$1(persistence) {
+        if (persistence?.enabled !== true) {
+            return null;
+        }
+        return {
+            key: persistence.key || DEFAULT_THEME_CACHE_KEY
+        };
+    }
+    async function loadThemeFromCache(cacheManager, persistence, fallback) {
+        const persistenceContext = resolvePersistenceContext$1(persistence);
+        const safeFallback = cloneTheme(fallback);
+        if (!persistenceContext) {
+            return safeFallback;
+        }
+        try {
+            const cached = await cacheManager.get(persistenceContext.key, {
+                defaultValue: safeFallback
+            });
+            return normalizeTheme(cached, safeFallback);
+        } catch  {
+            return safeFallback;
+        }
+    }
+    async function saveThemeToCache(cacheManager, persistence, theme) {
+        const persistenceContext = resolvePersistenceContext$1(persistence);
+        if (!persistenceContext) {
+            return;
+        }
+        try {
+            await cacheManager.set(persistenceContext.key, cloneTheme(theme));
+        } catch  {
+        // Ignore persistence failures and keep theme updates in memory.
+        }
+    }
+
     function _define_property$2(obj, key, value) {
         if (key in obj) {
             Object.defineProperty(obj, key, {
@@ -12450,49 +12586,20 @@
         }
         return obj;
     }
-    function applyThemeToDocument(theme) {
-        if (typeof document === 'undefined') {
-            return;
-        }
-        const root = document.documentElement;
-        root.classList.remove('light', 'dark');
-        const resolvedMode = theme.mode === 'system' ? typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light' : theme.mode;
-        root.classList.add(resolvedMode);
-        if (theme.primaryColor) {
-            root.style.setProperty('--app-primary-color', theme.primaryColor);
-        }
-        if (theme.tokens) {
-            Object.entries(theme.tokens).forEach(([token, tokenValue])=>{
-                root.style.setProperty(`--${token}`, String(tokenValue));
-            });
-        }
-    }
     class ThemeManager {
         async initialize(context) {
             this.config = context.config.theme;
-            this.theme = {
-                ...DEFAULT_THEME,
-                ...this.config.initial || {}
-            };
-            this.cache = context.cacheManager;
-            const { key = "vlian:kernel:theme" } = this.config.persistence || {};
-            const persisted = await this.cache.get(key, {
-                defaultValue: this.theme
-            });
-            if (persisted !== null) {
-                this.theme = {
-                    ...this.theme,
-                    ...persisted
-                };
-            } else {
-                await this.cache.set(key, persisted);
-            }
+            this.cacheManager = context.cacheManager;
+            const initialTheme = normalizeTheme(this.config.initial || {}, DEFAULT_THEME);
+            this.theme = await loadThemeFromCache(this.cacheManager, this.config.persistence, initialTheme);
             applyThemeToDocument(this.theme);
+            this.initialized = true;
         }
         getTheme() {
-            return {
-                ...this.theme
-            };
+            return cloneTheme(this.theme);
+        }
+        getSnapshot() {
+            return this.getTheme();
         }
         subscribe(listener) {
             this.listeners.add(listener);
@@ -12500,34 +12607,139 @@
                 this.listeners.delete(listener);
             };
         }
-        emit(next, prev) {
-            this.listeners.forEach((listener)=>{
-                listener({
-                    ...next
-                }, {
-                    ...prev
-                });
-            });
-        }
         async setTheme(nextTheme) {
-            const prev = this.theme;
-            this.theme = {
-                ...this.theme,
-                ...nextTheme
-            };
-            applyThemeToDocument(this.theme);
-            const { key = "vlian:kernel:theme" } = this.config.persistence || {};
-            await this.cache?.set(key, this.theme);
-            this.emit(this.theme, prev);
+            this.ensureInitialized();
+            const prevTheme = this.theme;
+            const mergedTheme = mergeTheme(prevTheme, nextTheme);
+            if (isThemeEqual(prevTheme, mergedTheme)) {
+                return;
+            }
+            this.theme = mergedTheme;
+            applyThemeToDocument(this.theme, prevTheme);
+            if (this.cacheManager) {
+                await saveThemeToCache(this.cacheManager, this.config.persistence, this.theme);
+            }
+            this.emit(this.theme, prevTheme);
         }
-        getSnapshot() {
-            return this.getTheme();
+        ensureInitialized() {
+            if (!this.initialized) {
+                throw new Error('ThemeManager must be initialized before use.');
+            }
+        }
+        emit(next, prev) {
+            for (const listener of this.listeners){
+                try {
+                    listener(cloneTheme(next), cloneTheme(prev));
+                } catch  {
+                // Keep notifying remaining listeners even if one fails.
+                }
+            }
         }
         constructor(){
-            _define_property$2(this, "theme", DEFAULT_THEME);
+            _define_property$2(this, "theme", cloneTheme(DEFAULT_THEME));
             _define_property$2(this, "config", DEFAULT_CONFIG.theme);
             _define_property$2(this, "listeners", new Set());
-            _define_property$2(this, "cache", undefined);
+            _define_property$2(this, "cacheManager", null);
+            _define_property$2(this, "initialized", false);
+        }
+    }
+
+    function isPlainObject(value) {
+        return Object.prototype.toString.call(value) === '[object Object]';
+    }
+    function cloneI18nSnapshot(snapshot) {
+        const resources = snapshot.resources ? Object.fromEntries(Object.entries(snapshot.resources).map(([locale, value])=>[
+                locale,
+                {
+                    ...value
+                }
+            ])) : undefined;
+        return {
+            locale: snapshot.locale,
+            ...resources ? {
+                resources
+            } : {}
+        };
+    }
+    function normalizeI18nSnapshot(value, fallback) {
+        const source = isPlainObject(value) ? value : {};
+        const locale = typeof source.locale === 'string' && source.locale.trim() ? source.locale : fallback.locale;
+        const fallbackResources = fallback.resources;
+        const incomingResources = isPlainObject(source.resources) ? Object.fromEntries(Object.entries(source.resources).filter(([, resourceValue])=>isPlainObject(resourceValue)).map(([locale, resourceValue])=>[
+                locale,
+                {
+                    ...resourceValue
+                }
+            ])) : undefined;
+        const resources = incomingResources || fallbackResources ? {
+            ...fallbackResources || {},
+            ...incomingResources || {}
+        } : undefined;
+        return {
+            locale,
+            ...resources ? {
+                resources
+            } : {}
+        };
+    }
+    function mergeI18nSnapshot(current, next) {
+        return normalizeI18nSnapshot({
+            locale: next.locale ?? current.locale,
+            resources: next.resources ?? current.resources
+        }, current);
+    }
+    function isI18nEqual(left, right) {
+        if (left.locale !== right.locale) {
+            return false;
+        }
+        const leftResources = left.resources || {};
+        const rightResources = right.resources || {};
+        const leftLocales = Object.keys(leftResources);
+        const rightLocales = Object.keys(rightResources);
+        if (leftLocales.length !== rightLocales.length) {
+            return false;
+        }
+        for (const locale of leftLocales){
+            if (leftResources[locale] !== rightResources[locale]) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    const DEFAULT_I18N_CACHE_KEY = 'vlian:kernel:i18n';
+    function resolvePersistenceContext(persistence) {
+        if (persistence?.enabled !== true) {
+            return null;
+        }
+        return {
+            key: persistence.key || DEFAULT_I18N_CACHE_KEY
+        };
+    }
+    async function loadI18nFromCache(cacheManager, persistence, fallback) {
+        const persistenceContext = resolvePersistenceContext(persistence);
+        const safeFallback = cloneI18nSnapshot(fallback);
+        if (!persistenceContext) {
+            return safeFallback;
+        }
+        try {
+            const cached = await cacheManager.get(persistenceContext.key, {
+                defaultValue: safeFallback
+            });
+            return normalizeI18nSnapshot(cached, safeFallback);
+        } catch  {
+            return safeFallback;
+        }
+    }
+    async function saveI18nToCache(cacheManager, persistence, snapshot) {
+        const persistenceContext = resolvePersistenceContext(persistence);
+        if (!persistenceContext) {
+            return;
+        }
+        try {
+            await cacheManager.set(persistenceContext.key, cloneI18nSnapshot(snapshot));
+        } catch  {
+        // Ignore persistence failures and keep i18n updates in memory.
         }
     }
 
@@ -12547,31 +12759,21 @@
     class I18nManager {
         async initialize(context) {
             this.config = context.config.i18n;
-            this.snapshot = {
-                ...DEFAULT_I18N,
-                ...this.config.initial || {}
-            };
-            const persisted = await readPersistedValue(this.config.persistence);
-            if (persisted !== null) {
-                try {
-                    const parsed = JSON.parse(persisted);
-                    this.snapshot = {
-                        ...this.snapshot,
-                        ...parsed
-                    };
-                } catch  {
-                // ignore parse errors
-                }
-            } else {
-                await writePersistedValue(this.config.persistence, JSON.stringify(this.snapshot));
-            }
-            await setupI18n(this.snapshot.resources || {});
-            setLang(this.snapshot.locale);
+            this.cacheManager = context.cacheManager;
+            const initialSnapshot = normalizeI18nSnapshot(this.config.initial || {}, DEFAULT_I18N);
+            this.snapshot = await loadI18nFromCache(this.cacheManager, this.config.persistence, initialSnapshot);
+            await setupI18n({
+                interpolation: {
+                    escapeValue: false
+                },
+                lng: this.snapshot.locale || "zh-CN",
+                resources: this.snapshot.resources
+            });
+            await setLang(this.snapshot.locale);
+            this.initialized = true;
         }
         getSnapshot() {
-            return {
-                ...this.snapshot
-            };
+            return cloneI18nSnapshot(this.snapshot);
         }
         subscribe(listener) {
             this.listeners.add(listener);
@@ -12579,29 +12781,43 @@
                 this.listeners.delete(listener);
             };
         }
-        emit(next, prev) {
-            this.listeners.forEach((listener)=>{
-                listener({
-                    ...next
-                }, {
-                    ...prev
-                });
-            });
-        }
         async setLocale(locale) {
-            const prev = this.snapshot;
-            this.snapshot = {
-                ...this.snapshot,
+            this.ensureInitialized();
+            const prevSnapshot = this.snapshot;
+            const nextSnapshot = mergeI18nSnapshot(prevSnapshot, {
                 locale
-            };
-            setLang(locale);
-            await writePersistedValue(this.config.persistence, JSON.stringify(this.snapshot));
-            this.emit(this.snapshot, prev);
+            });
+            if (isI18nEqual(prevSnapshot, nextSnapshot)) {
+                return;
+            }
+            this.snapshot = nextSnapshot;
+            // set lang
+            await setLang(this.snapshot.locale);
+            if (this.cacheManager) {
+                await saveI18nToCache(this.cacheManager, this.config.persistence, this.snapshot);
+            }
+            this.emit(this.snapshot, prevSnapshot);
+        }
+        ensureInitialized() {
+            if (!this.initialized) {
+                throw new Error('I18nManager must be initialized before use.');
+            }
+        }
+        emit(next, prev) {
+            for (const listener of this.listeners){
+                try {
+                    listener(cloneI18nSnapshot(next), cloneI18nSnapshot(prev));
+                } catch  {
+                // Keep notifying remaining listeners even if one fails.
+                }
+            }
         }
         constructor(){
-            _define_property$1(this, "snapshot", DEFAULT_I18N);
+            _define_property$1(this, "snapshot", cloneI18nSnapshot(DEFAULT_I18N));
             _define_property$1(this, "config", DEFAULT_CONFIG.i18n);
             _define_property$1(this, "listeners", new Set());
+            _define_property$1(this, "cacheManager", null);
+            _define_property$1(this, "initialized", false);
         }
     }