@vlian/framework 1.0.0

package/dist/core/startup/startApp.js

@@ -0,0 +1,147 @@
+/**
+ * 应用启动主函数
+ * 重构后的启动逻辑，集成所有新功能
+ */ import { logger } from "../../utils";
+import { ErrorCode, InitializationError } from "../../utils/errors";
+import { initTraceIdGenerator, generateTraceId, setCurrentTraceId } from "../../utils/traceId";
+import { shouldShowSplashScreen } from "../splash";
+import { initialization, initializationErrorState } from "../initialization/index";
+import { middlewareManager } from "../middleware";
+import { initializeServices } from "./initializeServices";
+import { getAppInstanceManager } from "./AppInstance";
+import { getEnvironmentDetector } from "./environment";
+import { getRouterManager } from "../router/RouterManager";
+/**
+ * 启动应用
+ * 
+ * @param options - 启动配置选项
+ * @param instanceId - 应用实例ID（可选，用于多实例场景）
+ * @returns 应用实例
+ */ export async function startApp(options = {}, instanceId) {
+    const startTime = performance.now();
+    const envDetector = getEnvironmentDetector();
+    const instanceManager = getAppInstanceManager();
+    // 初始化追踪 ID 生成器
+    initTraceIdGenerator('app');
+    const traceId = generateTraceId();
+    setCurrentTraceId(traceId);
+    try {
+        // 1. 环境检测和容器获取
+        const container = options.container || envDetector.safeGetElement('#root');
+        if (!container) {
+            throw new InitializationError('未找到挂载容器', undefined, {
+                container: options.container
+            }, ErrorCode.CONTAINER_NOT_FOUND);
+        }
+        logger.info('框架启动中...');
+        // 2. 创建应用实例
+        const appInstance = instanceManager.createInstance(instanceId, options);
+        // 3. 初始化服务（并行）
+        const servicesInitStart = performance.now();
+        const services = await initializeServices(options);
+        const servicesInitDuration = performance.now() - servicesInitStart;
+        // 4. 初始化应用实例
+        appInstance.initialize(container, services);
+        // 5. 初始化路由管理器
+        const routerManager = getRouterManager();
+        if (options.router) {
+            await routerManager.initialize(options.router);
+        }
+        // 6. 性能追踪
+        const performanceTracker = appInstance.getPerformanceTracker();
+        if (performanceTracker) {
+            performanceTracker.recordServiceInit(servicesInitDuration);
+        }
+        // 6. 是否显示启动页
+        const shouldShowSplash = shouldShowSplashScreen(options.showSplashScreen);
+        const renderer = appInstance.getRenderer();
+        // 8. 渲染应用函数
+        const renderApp = async (context)=>{
+            const renderStart = performance.now();
+            await renderer.renderApp(options, services, context);
+            const renderDuration = performance.now() - renderStart;
+            if (performanceTracker) {
+                performanceTracker.recordFirstRender(renderDuration);
+                const totalDuration = performance.now() - startTime;
+                performanceTracker.recordTotalStartup(totalDuration);
+                performanceTracker.report();
+            }
+            // 开发模式下显示开发工具
+            if (process.env.NODE_ENV === 'development' && typeof window !== 'undefined') {
+                // 延迟显示开发工具，避免影响首次渲染
+                setTimeout(()=>{
+                    const devToolsContainer = document.createElement('div');
+                    devToolsContainer.id = '__framework_dev_tools__';
+                    document.body.appendChild(devToolsContainer);
+                // 这里需要动态导入React来渲染开发工具
+                // 为了简化，暂时注释掉，后续可以完善
+                // import('react-dom/client').then(({ createRoot }) => {
+                //   const root = createRoot(devToolsContainer);
+                //   root.render(<DevToolsTrigger appInstance={appInstance} />);
+                // });
+                }, 1000);
+            }
+        };
+        if (shouldShowSplash) {
+            // 场景1: 显示启动页，初始化在启动页中完成
+            const onSplashComplete = (context)=>{
+                logger.info('启动页初始化完成');
+                if (options.onSplashComplete) {
+                    Promise.resolve(options.onSplashComplete(()=>{
+                        logger.info('框架加载完成');
+                        renderApp(context);
+                    }, context)).catch((error)=>{
+                        logger.error('onSplashComplete 回调执行失败:', error);
+                        initializationErrorState.setError(error);
+                        renderApp(context);
+                    });
+                } else {
+                    logger.info('框架加载完成');
+                    renderApp(context);
+                }
+            };
+            // 渲染启动页
+            renderer.renderSplashScreen(options, services, onSplashComplete);
+        } else {
+            // 场景2: 不显示启动页，直接执行初始化
+            logger.info('开始执行初始化（无启动页）');
+            try {
+                const initStart = performance.now();
+                // 使用中间件包装初始化函数
+                const initContext = await middlewareManager.execute(options, async ()=>{
+                    return await initialization(options, (progress, step)=>{
+                        logger.debug(`初始化进度: ${progress}%${step ? ` - ${step}` : ''}`);
+                    });
+                });
+                const initDuration = performance.now() - initStart;
+                if (performanceTracker) {
+                    performanceTracker.recordInitialization(initDuration);
+                }
+                logger.info('初始化完成（无启动页）', initContext);
+                logger.info('框架加载完成');
+                renderApp(initContext);
+            } catch (error) {
+                logger.error('初始化失败:', error);
+                initializationErrorState.setError(error);
+                renderApp();
+            }
+        }
+        return instanceManager;
+    } catch (error) {
+        logger.error('框架启动失败:', error);
+        // 如果容器存在，尝试渲染错误页面
+        const container = options.container || envDetector.safeGetElement('#root');
+        if (container) {
+            const errorInstance = instanceManager.getInstance();
+            if (errorInstance && errorInstance.isInitialized()) {
+                const renderer = errorInstance.getRenderer();
+                const services = errorInstance.getServices();
+                initializationErrorState.setError(error);
+                renderer.renderError(options, services);
+            }
+        }
+        throw error;
+    }
+}
+
+//# sourceMappingURL=startApp.js.map

package/dist/core/startup/startApp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/core/startup/startApp.ts"],"sourcesContent":["/**\n * 应用启动主函数\n * 重构后的启动逻辑，集成所有新功能\n */\n\nimport { logger } from '../../utils';\nimport { ErrorCode, InitializationError } from '../../utils/errors';\nimport { initTraceIdGenerator, generateTraceId, setCurrentTraceId } from '../../utils/traceId';\nimport type { StartOptions } from '../types';\nimport { shouldShowSplashScreen } from '../splash';\nimport { initialization, initializationErrorState } from '../initialization/index';\nimport { middlewareManager } from '../middleware';\nimport { initializeServices } from './initializeServices';\nimport { AppInstanceManager, getAppInstanceManager } from './AppInstance';\nimport { getEnvironmentDetector } from './environment';\nimport { getRouterManager } from '../router/RouterManager';\n\n/**\n * 启动应用\n * \n * @param options - 启动配置选项\n * @param instanceId - 应用实例ID（可选，用于多实例场景）\n * @returns 应用实例\n */\nexport async function startApp(\n  options: StartOptions = {},\n  instanceId?: string\n): Promise<AppInstanceManager> {\n  const startTime = performance.now();\n  const envDetector = getEnvironmentDetector();\n  const instanceManager = getAppInstanceManager();\n\n  // 初始化追踪 ID 生成器\n  initTraceIdGenerator('app');\n  const traceId = generateTraceId();\n  setCurrentTraceId(traceId);\n\n  try {\n    // 1. 环境检测和容器获取\n    const container = options.container || envDetector.safeGetElement('#root');\n    if (!container) {\n      throw new InitializationError(\n        '未找到挂载容器',\n        undefined,\n        { container: options.container },\n        ErrorCode.CONTAINER_NOT_FOUND\n      );\n    }\n\n    logger.info('框架启动中...');\n\n    // 2. 创建应用实例\n    const appInstance = instanceManager.createInstance(instanceId, options);\n\n    // 3. 初始化服务（并行）\n    const servicesInitStart = performance.now();\n    const services = await initializeServices(options);\n    const servicesInitDuration = performance.now() - servicesInitStart;\n\n    // 4. 初始化应用实例\n    appInstance.initialize(container, services);\n\n    // 5. 初始化路由管理器\n    const routerManager = getRouterManager();\n    if (options.router) {\n      await routerManager.initialize(options.router);\n    }\n\n    // 6. 性能追踪\n    const performanceTracker = appInstance.getPerformanceTracker();\n    if (performanceTracker) {\n      performanceTracker.recordServiceInit(servicesInitDuration);\n    }\n\n    // 6. 是否显示启动页\n    const shouldShowSplash = shouldShowSplashScreen(options.showSplashScreen);\n\n    const renderer = appInstance.getRenderer();\n\n    // 8. 渲染应用函数\n    const renderApp = async (context?: Awaited<ReturnType<typeof initialization>>) => {\n      const renderStart = performance.now();\n      await renderer.renderApp(options, services, context);\n      const renderDuration = performance.now() - renderStart;\n\n      if (performanceTracker) {\n        performanceTracker.recordFirstRender(renderDuration);\n        const totalDuration = performance.now() - startTime;\n        performanceTracker.recordTotalStartup(totalDuration);\n        performanceTracker.report();\n      }\n\n      // 开发模式下显示开发工具\n      if (process.env.NODE_ENV === 'development' && typeof window !== 'undefined') {\n        // 延迟显示开发工具，避免影响首次渲染\n        setTimeout(() => {\n          const devToolsContainer = document.createElement('div');\n          devToolsContainer.id = '__framework_dev_tools__';\n          document.body.appendChild(devToolsContainer);\n          \n          // 这里需要动态导入React来渲染开发工具\n          // 为了简化，暂时注释掉，后续可以完善\n          // import('react-dom/client').then(({ createRoot }) => {\n          //   const root = createRoot(devToolsContainer);\n          //   root.render(<DevToolsTrigger appInstance={appInstance} />);\n          // });\n        }, 1000);\n      }\n    };\n\n    if (shouldShowSplash) {\n      // 场景1: 显示启动页，初始化在启动页中完成\n      const onSplashComplete = (context: Awaited<ReturnType<typeof initialization>>) => {\n        logger.info('启动页初始化完成');\n\n        if (options.onSplashComplete) {\n          Promise.resolve(\n            options.onSplashComplete(() => {\n              logger.info('框架加载完成');\n              renderApp(context);\n            }, context)\n          ).catch((error) => {\n            logger.error('onSplashComplete 回调执行失败:', error);\n            initializationErrorState.setError(error);\n            renderApp(context);\n          });\n        } else {\n          logger.info('框架加载完成');\n          renderApp(context);\n        }\n      };\n\n      // 渲染启动页\n      renderer.renderSplashScreen(options, services, onSplashComplete);\n    } else {\n      // 场景2: 不显示启动页，直接执行初始化\n      logger.info('开始执行初始化（无启动页）');\n\n      try {\n        const initStart = performance.now();\n\n        // 使用中间件包装初始化函数\n        const initContext = await middlewareManager.execute(\n          options,\n          async () => {\n            return await initialization(options, (progress, step) => {\n              logger.debug(`初始化进度: ${progress}%${step ? ` - ${step}` : ''}`);\n            });\n          }\n        );\n\n        const initDuration = performance.now() - initStart;\n        if (performanceTracker) {\n          performanceTracker.recordInitialization(initDuration);\n        }\n\n        logger.info('初始化完成（无启动页）', initContext);\n        logger.info('框架加载完成');\n        renderApp(initContext);\n      } catch (error) {\n        logger.error('初始化失败:', error);\n        initializationErrorState.setError(error);\n        renderApp();\n      }\n    }\n\n    return instanceManager;\n  } catch (error) {\n    logger.error('框架启动失败:', error);\n\n    // 如果容器存在，尝试渲染错误页面\n    const container = options.container || envDetector.safeGetElement('#root');\n    if (container) {\n      const errorInstance = instanceManager.getInstance();\n      if (errorInstance && errorInstance.isInitialized()) {\n        const renderer = errorInstance.getRenderer();\n        const services = errorInstance.getServices();\n        initializationErrorState.setError(error);\n        renderer.renderError(options, services);\n      }\n    }\n\n    throw error;\n  }\n}\n"],"names":["logger","ErrorCode","InitializationError","initTraceIdGenerator","generateTraceId","setCurrentTraceId","shouldShowSplashScreen","initialization","initializationErrorState","middlewareManager","initializeServices","getAppInstanceManager","getEnvironmentDetector","getRouterManager","startApp","options","instanceId","startTime","performance","now","envDetector","instanceManager","traceId","container","safeGetElement","undefined","CONTAINER_NOT_FOUND","info","appInstance","createInstance","servicesInitStart","services","servicesInitDuration","initialize","routerManager","router","performanceTracker","getPerformanceTracker","recordServiceInit","shouldShowSplash","showSplashScreen","renderer","getRenderer","renderApp","context","renderStart","renderDuration","recordFirstRender","totalDuration","recordTotalStartup","report","process","env","NODE_ENV","window","setTimeout","devToolsContainer","document","createElement","id","body","appendChild","onSplashComplete","Promise","resolve","catch","error","setError","renderSplashScreen","initStart","initContext","execute","progress","step","debug","initDuration","recordInitialization","errorInstance","getInstance","isInitialized","getServices","renderError"],"mappings":"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"}

package/dist/core/types.cjs

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+
+//# sourceMappingURL=types.js.map

package/dist/core/types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/types.ts"],"names":[],"mappings":""}

package/dist/core/types.d.ts

@@ -0,0 +1,461 @@
+import { LogLevel } from '../utils';
+import type { LangType } from '../library/locale/types';
+import { Container, RootOptions } from 'react-dom/client';
+import { type ReactElement, type ReactNode } from 'react';
+import { type InitializationContext, type ConfigStrategy } from './initialization';
+import type { StorageOptions } from '../types';
+import type { ConfigProviderProps, AppProps } from "antd";
+import type { ThemeConfig } from './app';
+import type { FrameworkError } from '../utils/errors';
+import type { RouterConfig } from './router/types';
+/**
+ * 生命周期钩子函数类型
+ */
+export type ManagerLifecycle = {
+    /**
+     * 在初始化之前执行
+     */
+    beforeInitialization?: () => Promise<void> | void;
+    /**
+     * 初始化
+     */
+    initialization?: () => Promise<void> | void;
+    /**
+     * 在初始化之后执行
+     *
+     * @param context - 初始化上下文，包含配置、进度、耗时等信息
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   lifecycle: {
+     *     afterInitialization: (context) => {
+     *       console.log('初始化完成', context);
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    afterInitialization?: (context: InitializationContext) => Promise<void> | void;
+};
+/**
+ * 启动配置选项
+ */
+export interface StartOptions {
+    /**
+     * React 应用的挂载容器
+     *
+     * 用于指定 React 应用渲染的目标 DOM 元素。如果不提供，框架将自动查找页面中
+     * 的根元素（通常为 id="root" 的元素）作为默认容器。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     *
+     * // 使用默认容器（自动查找 id="root" 的元素）
+     * start({});
+     *
+     * // 指定自定义容器
+     * const container = document.getElementById('app');
+     * start({ container });
+     * ```
+     */
+    container?: Container;
+    /**
+     * React 根节点的配置选项
+     *
+     * 用于配置 React 18+ 的 createRoot 方法的选项，包括：
+     * - `onRecoverableError`: 错误恢复回调函数
+     * - `identifierPrefix`: 用于标识符前缀，用于服务端渲染的 hydration
+     *
+     * 这些选项将传递给 `react-dom/client` 的 `createRoot` 方法。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     *
+     * start({
+     *   rootOptions: {
+     *     onRecoverableError: (error) => {
+     *       console.error('React 错误恢复:', error);
+     *     },
+     *     identifierPrefix: 'my-app-',
+     *   },
+     * });
+     * ```
+     */
+    rootOptions?: RootOptions;
+    /**
+     * 应用根组件
+     *
+     * 用于指定要渲染的 React 应用根组件。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     * import App from './App';
+     *
+     * start({
+     *   app: <App />,
+     * });
+     * ```
+     */
+    app?: ReactElement;
+    /**
+     * 是否显示启动页
+     * - 'auto': 自动判断（推荐）
+     * - 'always': 总是显示
+     * - 'never': 从不显示
+     * - 'first-time-only': 仅首次加载显示
+     *
+     * @default 'auto'
+     */
+    showSplashScreen?: 'auto' | 'always' | 'never' | 'first-time-only';
+    /**
+     * 启动页最小显示时间（毫秒）
+     *
+     * 用于避免启动页闪烁，确保用户能看到启动过程。
+     * 如果初始化完成时间小于此值，将等待至最小时间后再隐藏启动页。
+     *
+     * @default 500
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   minSplashScreenTime: 1000, // 至少显示 1 秒
+     * });
+     * ```
+     */
+    minSplashScreenTime?: number;
+    /**
+     * 路由配置
+     *
+     * 配置应用的路由系统，支持内置路由、自定义路由和禁用路由三种模式。
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   router: {
+     *     enabled: true,
+     *     routes: [
+     *       {
+     *         path: '/login',
+     *         page: LoginPage,
+     *       },
+     *       {
+     *         path: '/',
+     *         layout: MainLayout,
+     *         children: [
+     *           {
+     *             path: 'dashboard',
+     *             page: DashboardPage,
+     *             meta: { title: '仪表盘' },
+     *           },
+     *         ],
+     *       },
+     *     ],
+     *   },
+     * });
+     * ```
+     */
+    router?: RouterConfig;
+    /**
+     * 日志级别
+     */
+    loggerLevel?: LogLevel;
+    /**
+     * 生命周期钩子
+     */
+    lifecycle?: ManagerLifecycle;
+    /**
+     * 国际化
+     */
+    locale?: Record<LangType, Record<string, unknown>>;
+    /**
+     * 配置加载策略
+     */
+    configStrategy?: ConfigStrategy;
+    /**
+     * 启动页完成回调
+     * 仅在显示启动页时，启动页完成初始化后调用
+     * 可以在这里执行额外的操作，然后调用 complete() 继续
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   onSplashComplete: (complete, context) => {
+     *     // 执行额外操作
+     *     await doSomething();
+     *     // 完成后继续
+     *     complete();
+     *   },
+     * });
+     * ```
+     */
+    onSplashComplete?: (complete: () => void, context: InitializationContext) => Promise<void> | void;
+    /**
+     * 存储配置
+     */
+    storageOptions?: StorageOptions;
+    /**
+     * IndexedDB 表名
+     */
+    indexedDBTableName?: string;
+    /**
+     * antd 配置
+     */
+    antd?: ConfigProviderProps;
+    /**
+     * antd App 组件配置
+     *
+     * 用于配置 antd 的 App 组件，使 message、modal、notification 等静态方法能够正确使用。
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   antdApp: {
+     *     message: { maxCount: 3 },
+     *     notification: { placement: 'topRight' },
+     *   },
+     * });
+     * ```
+     */
+    antdApp?: AppProps;
+    /**
+     * 主题配置
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   theme: {
+     *     mode: 'dark',
+     *     primaryColor: '#1890ff',
+     *   },
+     * });
+     * ```
+     */
+    theme?: ThemeConfig;
+    /**
+     * 运行时安全配置
+     */
+    runtimeSecurity?: import('../utils/runtimeSecurity').RuntimeSecurityOptions;
+    /**
+     * 配置安全选项
+     */
+    configSecurity?: import('../utils/configSecurity').ConfigSecurityOptions;
+    /**
+     * 性能监控配置
+     */
+    performanceMonitor?: import('../utils/performance').PerformanceMonitorConfig;
+    /**
+     * 错误监控配置
+     */
+    errorMonitor?: import('../utils/monitoring').ErrorMonitorConfig;
+    /**
+     * 分析服务配置
+     */
+    analytics?: import('../utils/analytics').AnalyticsConfig;
+    /**
+     * 状态管理器配置
+     *
+     * 配置框架的状态管理器，支持自定义适配器和作用域设置。
+     * 如果不提供，将使用默认配置创建状态管理器。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     *
+     * start({
+     *   stateManager: {
+     *     enableRegistry: true,
+     *     defaultScope: 'app',
+     *     devMode: true,
+     *   },
+     * });
+     * ```
+     */
+    stateManager?: import('../state').StateManagerOptions;
+    /**
+     * 自定义启动屏组件
+     *
+     * 如果提供，将使用自定义组件替代默认的启动屏 UI。
+     * 自定义组件将接收初始化进度、当前步骤和初始化状态作为 props。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     *
+     * const CustomSplashScreen = ({ progress, currentStep, isInitializing }) => {
+     *   return (
+     *     <div>
+     *       <h1>加载中...</h1>
+     *       <div>进度: {progress}%</div>
+     *       <div>步骤: {currentStep}</div>
+     *     </div>
+     *   );
+     * };
+     *
+     * start({
+     *   splashScreen: CustomSplashScreen,
+     * });
+     * ```
+     */
+    splashScreen?: React.ComponentType<SplashScreenCustomProps>;
+    /**
+     * 自定义错误反馈组件
+     *
+     * 如果提供，将使用自定义的错误 UI 替代默认的错误 UI（基于 antd 的 Result 组件）。
+     * 自定义组件将接收错误对象和重置函数作为参数。
+     *
+     * @param error - 标准化后的框架错误对象
+     * @param resetError - 重置错误边界的函数，调用后可以尝试重新渲染子组件
+     * @returns 错误 UI 的 React 节点
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     * import { Result, Button } from 'antd';
+     *
+     * start({
+     *   errorFallback: (error, reset) => (
+     *     <Result
+     *       status="error"
+     *       title="自定义错误标题"
+     *       subTitle={error.message}
+     *       extra={<Button onClick={reset}>重试</Button>}
+     *     />
+     *   ),
+     * });
+     * ```
+     */
+    errorFallback?: (error: FrameworkError, resetError: () => void) => ReactNode;
+    /**
+     * 安全配置选项
+     *
+     * 用于配置框架的安全策略，包括 XSS 防护、配置验证等。
+     * 框架默认启用所有安全策略，确保应用安全。
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   security: {
+     *     enableXSSProtection: true, // 默认启用
+     *     validateConfig: true, // 默认启用
+     *     sanitizeUserInput: true, // 默认启用
+     *   },
+     * });
+     * ```
+     */
+    security?: {
+        /**
+         * 是否启用 XSS 防护
+         * @default true
+         */
+        enableXSSProtection?: boolean;
+        /**
+         * 是否验证配置项安全性
+         * @default true
+         */
+        validateConfig?: boolean;
+        /**
+         * 是否清理用户输入
+         * @default true
+         */
+        sanitizeUserInput?: boolean;
+        /**
+         * CSP（内容安全策略）配置
+         */
+        csp?: {
+            defaultSrc?: string[];
+            scriptSrc?: string[];
+            styleSrc?: string[];
+            imgSrc?: string[];
+            connectSrc?: string[];
+            fontSrc?: string[];
+            frameSrc?: string[];
+            allowUnsafeInline?: boolean;
+            allowUnsafeEval?: boolean;
+        };
+        /**
+         * CSRF 防护配置
+         */
+        csrf?: {
+            /**
+             * 是否启用 CSRF 防护
+             * @default true
+             */
+            enabled?: boolean;
+            /**
+             * CSRF Token 获取函数
+             * 如果不提供，框架会自动从 cookie 或 header 中获取
+             */
+            getToken?: () => string | Promise<string>;
+            /**
+             * CSRF Token 验证函数
+             * 如果不提供，框架会使用默认验证逻辑
+             */
+            validateToken?: (token: string) => boolean | Promise<boolean>;
+            /**
+             * CSRF Token 请求头名称
+             * @default 'X-CSRF-Token'
+             */
+            headerName?: string;
+            /**
+             * CSRF Token Cookie 名称
+             * @default 'csrf-token'
+             */
+            cookieName?: string;
+        };
+    };
+    /**
+     * 服务初始化重试配置
+     *
+     * 用于配置服务初始化失败时的重试策略。
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   serviceRetry: {
+     *     maxRetries: 3,
+     *     retryDelay: 1000,
+     *     exponentialBackoff: true,
+     *   },
+     * });
+     * ```
+     */
+    serviceRetry?: {
+        /**
+         * 最大重试次数
+         * @default 3
+         */
+        maxRetries?: number;
+        /**
+         * 重试延迟（毫秒）
+         * @default 1000
+         */
+        retryDelay?: number;
+        /**
+         * 是否启用指数退避
+         * @default true
+         */
+        exponentialBackoff?: boolean;
+    };
+}
+/**
+ * 自定义启动屏组件的 Props
+ */
+export interface SplashScreenCustomProps {
+    /**
+     * 初始化进度（0-100）
+     */
+    progress: number;
+    /**
+     * 当前步骤描述
+     */
+    currentStep: string;
+    /**
+     * 是否正在初始化
+     */
+    isInitializing: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -0,0 +1,5 @@
+/**
+ * 自定义启动屏组件的 Props
+ */ export { };
+
+//# sourceMappingURL=types.js.map