@4399ywkf/core 5.0.26 → 5.0.28

package/dist/schema-CMyZyL6E.d.ts

@@ -0,0 +1,1153 @@
+import { Configuration } from '@rspack/core';
+import { a as AppConfig, P as ProviderConfig } from './types-BYqzyGAY.js';
+
+/**
+ * 路由项定义
+ */
+interface RouteItem {
+    /** 路由路径 */
+    path: string;
+    /** 组件文件路径（相对于 src） */
+    component: string;
+    /** 是否为 index 路由 */
+    index?: boolean;
+    /** 是否为布局组件 */
+    isLayout?: boolean;
+    /** 子路由 */
+    children?: RouteItem[];
+    /** 路由元信息 */
+    meta?: RouteMeta;
+}
+/**
+ * 路由元信息
+ */
+interface RouteMeta {
+    /** 页面标题 */
+    title?: string;
+    /** 是否需要登录 */
+    auth?: boolean;
+    /** 自定义数据 */
+    [key: string]: unknown;
+}
+
+/**
+ * 插件上下文
+ */
+interface PluginContext {
+    /** 工作目录 */
+    cwd: string;
+    /** 是否开发模式 */
+    isDev: boolean;
+    /** 是否生产模式 */
+    isProd: boolean;
+    /** 用户配置 */
+    config: Required<YwkfConfig>;
+    /** 日志工具 */
+    logger: PluginLogger;
+}
+/**
+ * 插件日志工具
+ */
+interface PluginLogger {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+    debug: (message: string) => void;
+}
+/**
+ * 构建阶段钩子
+ */
+interface BuildHooks {
+    /**
+     * 修改 Rspack 配置
+     */
+    modifyRspackConfig?: (config: Configuration, context: PluginContext) => Configuration | undefined | Promise<Configuration | undefined>;
+    /**
+     * 构建开始前
+     */
+    beforeBuild?: (context: PluginContext) => void | Promise<void>;
+    /**
+     * 构建完成后
+     */
+    afterBuild?: (context: PluginContext, stats: {
+        success: boolean;
+        errors?: string[];
+    }) => void | Promise<void>;
+    /**
+     * 开发服务器启动前
+     */
+    beforeDevServer?: (context: PluginContext) => void | Promise<void>;
+    /**
+     * 开发服务器启动后
+     */
+    afterDevServer?: (context: PluginContext, server: {
+        port: number;
+        host: string;
+    }) => void | Promise<void>;
+}
+/**
+ * 路由阶段钩子
+ */
+interface RouterHooks {
+    /**
+     * 修改路由配置
+     */
+    modifyRoutes?: (routes: RouteItem[], context: PluginContext) => RouteItem[] | undefined | Promise<RouteItem[] | undefined>;
+    /**
+     * 路由生成后
+     */
+    afterRoutesGenerated?: (routes: RouteItem[], context: PluginContext) => void | Promise<void>;
+}
+/**
+ * 运行时阶段钩子
+ */
+interface RuntimeHooks {
+    /**
+     * 修改运行时配置
+     */
+    modifyAppConfig?: (appConfig: AppConfig, context: PluginContext) => AppConfig | undefined;
+    /**
+     * 添加 Provider
+     */
+    addProvider?: (context: PluginContext) => ProviderConfig | ProviderConfig[];
+    /**
+     * 应用渲染前
+     */
+    beforeRender?: (context: PluginContext) => void;
+    /**
+     * 应用渲染后
+     */
+    afterRender?: (context: PluginContext) => void;
+}
+/**
+ * 生成的文件
+ */
+interface GeneratedFile {
+    /** 文件路径（相对于 .ywkf 目录） */
+    path: string;
+    /** 文件内容 */
+    content: string;
+}
+/**
+ * 代码生成器上下文
+ */
+interface GeneratorContext {
+    /** 工作目录 */
+    cwd: string;
+    /** 输出目录（.ywkf） */
+    outputDir: string;
+    /** 用户配置 */
+    config: Required<YwkfConfig>;
+    /** 是否开发模式 */
+    isDev: boolean;
+}
+/**
+ * 代码注入点
+ */
+interface CodeInjection {
+    /** 导入语句 */
+    imports?: string[];
+    /** 顶层代码（在函数外部） */
+    topLevel?: string[];
+    /** 导出语句 */
+    exports?: string[];
+}
+/**
+ * 代码生成阶段钩子
+ */
+interface GeneratorHooks {
+    /**
+     * 修改入口文件代码
+     */
+    modifyEntryCode?: (code: string, context: GeneratorContext) => string | undefined;
+    /**
+     * 修改启动文件代码
+     */
+    modifyBootstrapCode?: (code: string, context: GeneratorContext) => string | undefined;
+    /**
+     * 注入入口代码
+     * 返回需要注入到入口文件的代码片段
+     */
+    injectEntry?: (context: GeneratorContext) => CodeInjection | undefined;
+    /**
+     * 注入启动代码
+     * 返回需要注入到启动文件的代码片段
+     */
+    injectBootstrap?: (context: GeneratorContext) => CodeInjection | undefined;
+    /**
+     * 生成额外文件
+     */
+    generateFiles?: (context: GeneratorContext) => GeneratedFile[] | undefined;
+    /**
+     * 代码生成完成后
+     */
+    afterGenerate?: (context: GeneratorContext) => void | Promise<void>;
+}
+/**
+ * 插件钩子集合
+ */
+interface PluginHooks extends BuildHooks, RouterHooks, RuntimeHooks, GeneratorHooks {
+}
+/**
+ * 插件定义
+ */
+interface YwkfPlugin {
+    /** 插件名称 */
+    name: string;
+    /** 插件版本 */
+    version?: string;
+    /** 插件描述 */
+    description?: string;
+    /**
+     * 插件初始化
+     * @returns 插件钩子
+     */
+    setup: (context: PluginContext) => PluginHooks | Promise<PluginHooks>;
+}
+/**
+ * 插件配置（用户在 ywkf.config.ts 中使用）
+ */
+type PluginConfig = string | YwkfPlugin | [string, Record<string, unknown>] | [YwkfPlugin, Record<string, unknown>];
+/**
+ * 创建插件的辅助函数类型
+ */
+type DefinePlugin = (options?: Record<string, unknown>) => YwkfPlugin;
+/**
+ * 插件 API（传递给插件的 setup 函数）
+ */
+interface PluginAPI {
+    /** 获取配置 */
+    getConfig: () => Required<YwkfConfig>;
+    /** 获取工作目录 */
+    getCwd: () => string;
+    /** 是否开发环境 */
+    isDev: () => boolean;
+    /** 添加 Rspack 插件 */
+    addRspackPlugin: (plugin: unknown) => void;
+    /** 修改 Rspack 配置 */
+    modifyRspackConfig: (modifier: (config: Configuration) => Configuration | undefined) => void;
+}
+
+interface AnalyticsPluginOptions {
+    /** 是否启用构建分析 */
+    buildAnalysis?: boolean;
+    /** 是否输出构建时间 */
+    timing?: boolean;
+    /** 是否分析 bundle 大小 */
+    bundleSize?: boolean;
+    /** 大文件警告阈值（KB） */
+    sizeWarningThreshold?: number;
+}
+/**
+ * 构建分析插件
+ *
+ * @example
+ * ```ts
+ * import { analyticsPlugin } from "@4399ywkf/core/plugin";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     analyticsPlugin({
+ *       timing: true,
+ *       bundleSize: true,
+ *       sizeWarningThreshold: 500, // 500KB
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare const analyticsPlugin: (options?: AnalyticsPluginOptions | undefined) => YwkfPlugin;
+
+interface BiomePluginOptions {
+    /**
+     * 是否在项目根目录生成 biome.json（仅在文件不存在时）
+     * @default true
+     */
+    scaffold?: boolean;
+    /**
+     * 额外忽略的文件 glob
+     */
+    ignore?: string[];
+    /**
+     * 自定义 linter 规则覆盖（浅合并到继承的规则上）
+     */
+    rules?: Record<string, Record<string, string>>;
+    /**
+     * 自定义 formatter 覆盖
+     */
+    formatter?: Record<string, unknown>;
+    /**
+     * 自定义 javascript formatter 覆盖
+     */
+    javascript?: Record<string, unknown>;
+}
+/**
+ * Biome 代码规范插件
+ *
+ * 在 setup 阶段自动生成 biome.json，通过 extends 继承
+ * @4399ywkf/core 内置的共享配置，为项目提供统一的
+ * Lint / Format / Import Sorting 规范。
+ *
+ * 用户项目的 biome.json 只需 extends 框架配置，
+ * 再按需覆盖少量规则即可。
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, biomePlugin } from "@4399ywkf/core";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     biomePlugin(),
+ *   ],
+ * });
+ * ```
+ */
+declare const biomePlugin: (options?: BiomePluginOptions | undefined) => YwkfPlugin;
+/**
+ * 生成默认 biome.json 配置内容（纯数据，供 CLI 脚手架使用）
+ *
+ * 生成的配置通过 extends 继承 @4399ywkf/core/biome 共享配置，
+ * 用户只需在此基础上按需覆盖。
+ */
+declare function getDefaultBiomeConfig(): Record<string, unknown>;
+
+/**
+ * 浏览器版本要求
+ */
+interface BrowserMinVersions {
+    chrome?: number;
+    edge?: number;
+    firefox?: number;
+    safari?: number;
+}
+interface BrowserCheckPluginOptions {
+    /**
+     * 需要检测的浏览器特性（API 级别的特性检测）
+     * @default ["Object.hasOwn"]
+     * @example ["Object.hasOwn", "Array.prototype.at", "structuredClone"]
+     */
+    features?: string[];
+    /**
+     * 最低浏览器版本要求（基于 UA 解析）
+     *
+     * 优先级：`minVersions` > `fromBrowserslist` 解析结果 > 内置默认值
+     *
+     * @default { chrome: 93, edge: 93, firefox: 92, safari: 15.4 }
+     */
+    minVersions?: BrowserMinVersions;
+    /**
+     * 从 `.browserslistrc` 文件或 `package.json` 的 `browserslist` 字段中
+     * 自动读取最低浏览器版本要求。
+     *
+     * - `true`   — 自动在项目根目录查找 `.browserslistrc` 或 `package.json#browserslist`
+     * - `string` — 指定 `.browserslistrc` 文件的路径（相对于项目根目录）
+     * - `false`  — 不读取，使用 `minVersions` 或内置默认值
+     *
+     * 如果同时配置了 `minVersions`，`minVersions` 中的值会**覆盖** `.browserslistrc` 中的对应值。
+     *
+     * @default false
+     *
+     * @example
+     * ```ts
+     * // 自动检测
+     * browserCheckPlugin({ fromBrowserslist: true })
+     *
+     * // 指定路径
+     * browserCheckPlugin({ fromBrowserslist: "../.browserslistrc" })
+     *
+     * // 自动读取 + 覆盖 safari 版本
+     * browserCheckPlugin({ fromBrowserslist: true, minVersions: { safari: 16 } })
+     * ```
+     */
+    fromBrowserslist?: boolean | string;
+    /**
+     * 警告页面标题
+     * @default "浏览器版本过低"
+     */
+    title?: string;
+    /**
+     * 警告页面描述信息
+     * @default "您当前的浏览器版本不支持本应用所需的功能。请升级到以下推荐浏览器的最新版本："
+     */
+    message?: string;
+    /**
+     * 是否显示推荐浏览器下载链接
+     * @default true
+     */
+    showDownloadLinks?: boolean;
+    /**
+     * 自定义渲染 HTML 的函数。如果提供，将替代默认的警告页面。
+     */
+    renderHtml?: (opts: {
+        title: string;
+        message: string;
+        showDownloadLinks: boolean;
+        minVersions: BrowserMinVersions;
+    }) => string;
+    /**
+     * 伴随自定义 HTML 执行的 JS 脚本代码（字符串形式）。
+     * 注意：这段代码会在不支持的浏览器中执行，请使用 ES5 语法。
+     */
+    renderScript?: string;
+}
+/**
+ * 浏览器最低版本检查插件
+ *
+ * 在应用启动前检测浏览器兼容性，若不满足要求则展示升级提示页面，阻止应用加载。
+ * 支持两种检测策略：
+ * 1. **特性检测**（推荐）：检查浏览器是否支持指定的 API，如 `Object.hasOwn`
+ * 2. **UA 版本检测**：解析 User-Agent 判断浏览器版本是否达到最低要求
+ *
+ * @see https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwn
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, browserCheckPlugin } from "@4399ywkf/core";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     browserCheckPlugin(),
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // 自定义最低版本和检测特性
+ * browserCheckPlugin({
+ *   features: ["Object.hasOwn", "Array.prototype.at"],
+ *   minVersions: { chrome: 100, edge: 100, firefox: 100, safari: 16 },
+ *   title: "请升级浏览器",
+ *   message: "当前浏览器版本过低，无法正常使用本系统。",
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // 从 .browserslistrc 自动读取最低版本要求
+ * browserCheckPlugin({
+ *   fromBrowserslist: true,
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // 从 .browserslistrc 读取，并覆盖 safari 版本
+ * browserCheckPlugin({
+ *   fromBrowserslist: true,
+ *   minVersions: { safari: 16 },
+ * })
+ * ```
+ */
+declare const browserCheckPlugin: (options?: BrowserCheckPluginOptions | undefined) => YwkfPlugin;
+
+interface GarfishPluginOptions {
+    /** 应用名称（微前端标识） */
+    appName?: string;
+    /** 是否作为主应用 */
+    master?: boolean;
+    /** 子应用列表（主应用模式） */
+    apps?: {
+        name: string;
+        entry: string;
+        activeRule: string;
+        basename?: string;
+    }[];
+    /** 沙箱配置 */
+    sandbox?: {
+        /** 是否开启 JS 沙箱 */
+        open?: boolean;
+        /** 是否开启快照沙箱 */
+        snapshot?: boolean;
+        /** 样式隔离 */
+        strictStyleIsolation?: boolean;
+    };
+}
+/**
+ * Garfish 微前端插件
+ *
+ * 通过插件方式启用微前端功能，支持子应用和主应用两种模式。
+ *
+ * @example
+ * ```ts
+ * // ywkf.config.ts - 子应用模式
+ * import { defineConfig, garfishPlugin } from "@4399ywkf/core";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     garfishPlugin({
+ *       appName: "sub-app",
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // ywkf.config.ts - 主应用模式
+ * import { defineConfig, garfishPlugin } from "@4399ywkf/core";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     garfishPlugin({
+ *       master: true,
+ *       apps: [
+ *         { name: "sub-app", entry: "http://localhost:3001", activeRule: "/sub" },
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare const garfishPlugin: (options?: GarfishPluginOptions | undefined) => YwkfPlugin;
+
+interface I18nPluginOptions {
+    /**
+     * 默认语言
+     * @default "zh-CN"
+     */
+    defaultLocale?: string;
+    /**
+     * 支持的语言列表
+     * @default ["zh-CN", "en-US"]
+     */
+    locales?: string[];
+    /**
+     * 翻译 JSON 文件目录（相对于项目根目录）
+     * 非默认语言的 JSON 翻译文件存放位置
+     * @default "locales"
+     */
+    localesDir?: string;
+    /**
+     * 默认语言 TS 源文件目录（相对于项目根目录）
+     * 开发者在此编写 TypeScript 翻译源文件，作为 i18n 的 single source of truth
+     * @default "src/locales/default"
+     */
+    sourceDir?: string;
+    /**
+     * 默认命名空间
+     * @default ["common"]
+     */
+    defaultNS?: string[];
+    /**
+     * 是否自动生成初始脚手架文件
+     * @default true
+     */
+    autoScaffold?: boolean;
+}
+/**
+ * 国际化插件（TS-first 工作流）
+ *
+ * 开发流程：
+ * 1. 开发者在 src/locales/default/ 中编写 TypeScript 翻译源文件（有类型推导 + IDE 补全）
+ * 2. 运行 `pnpm i18n:gen` 将 TS 源文件转换为 locales/{defaultLocale}/*.json
+ * 3. 运行 `pnpm i18n` 使用 @lobehub/i18n-cli 将默认语言 JSON 翻译为其他语言
+ * 4. 运行时：开发模式下默认语言直接 import TS，其他场景懒加载 JSON
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, i18nPlugin } from "@4399ywkf/core";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     i18nPlugin({
+ *       defaultLocale: "zh-CN",
+ *       locales: ["zh-CN", "en-US", "ja-JP"],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare const i18nPlugin: (options?: I18nPluginOptions | undefined) => YwkfPlugin;
+
+interface MockPluginOptions {
+    /** Mock 文件目录 */
+    mockDir?: string;
+    /** 是否在生产环境启用 */
+    enableInProd?: boolean;
+    /** 延迟时间（模拟网络延迟） */
+    delay?: number;
+    /** 前缀路径 */
+    prefix?: string;
+}
+/**
+ * Mock 数据插件
+ *
+ * @example
+ * ```ts
+ * // ywkf.config.ts
+ * import { mockPlugin } from "@4399ywkf/core/plugin";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     mockPlugin({
+ *       mockDir: "mock",
+ *       prefix: "/api",
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * Mock 文件示例 (mock/user.ts):
+ * ```ts
+ * export default {
+ *   "GET /api/users": [
+ *     { id: 1, name: "张三" },
+ *   ],
+ *   "POST /api/users": (req, res) => {
+ *     res.json({ success: true });
+ *   },
+ * };
+ * ```
+ */
+declare const mockPlugin: (options?: MockPluginOptions | undefined) => YwkfPlugin;
+
+interface ReactQueryPluginOptions {
+    /**
+     * 默认 staleTime（毫秒）
+     * @default 5 * 60 * 1000 (5 分钟)
+     */
+    staleTime?: number;
+    /**
+     * 默认 gcTime（毫秒）
+     * @default 10 * 60 * 1000 (10 分钟)
+     */
+    gcTime?: number;
+    /**
+     * 默认重试次数
+     * @default 1
+     */
+    retry?: number | boolean;
+    /**
+     * 是否开启 React Query DevTools（仅开发模式生效）
+     * @default true
+     */
+    devtools?: boolean;
+    /**
+     * axios baseURL
+     * @default ""
+     */
+    baseURL?: string;
+    /**
+     * 请求超时时间（毫秒）
+     * @default 15000
+     */
+    timeout?: number;
+}
+/**
+ * React Query + Axios 请求层插件
+ *
+ * - 自动注入 QueryClientProvider
+ * - 生成 .ywkf/query-client.ts（QueryClient 实例 + 默认配置）
+ * - 生成 .ywkf/request.ts（axios 封装 + 拦截器骨架）
+ * - 开发模式可选开启 React Query DevTools
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, reactQueryPlugin } from "@4399ywkf/core";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     reactQueryPlugin({ staleTime: 5 * 60 * 1000 }),
+ *   ],
+ * });
+ * ```
+ */
+declare const reactQueryPlugin: (options?: ReactQueryPluginOptions | undefined) => YwkfPlugin;
+
+interface TailwindPluginOptions {
+    /**
+     * 自定义暗色模式选择器
+     * @default '&:where([data-theme="dark"], [data-theme="dark"] *)'
+     */
+    darkModeSelector?: string;
+    /**
+     * 是否生成 postcss.config.js（如果不存在）
+     * @default true
+     */
+    autoConfig?: boolean;
+    /**
+     * 额外的 CSS 内容（追加到 index.css 之后）
+     */
+    extraCSS?: string;
+}
+/**
+ * Tailwind CSS 插件
+ *
+ * 自动配置 Tailwind CSS：
+ * - 注入 `@import "tailwindcss"` 到 index.css
+ * - 确保 postcss.config.js 存在
+ * - 修改 Rspack 配置添加 postcss-loader
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, tailwindPlugin } from "@4399ywkf/core";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     tailwindPlugin(),
+ *   ],
+ * });
+ * ```
+ */
+declare const tailwindPlugin: (options?: TailwindPluginOptions | undefined) => YwkfPlugin;
+
+interface ThemePluginOptions {
+    /**
+     * 是否启用暗色模式切换能力
+     * @default true
+     */
+    darkMode?: boolean;
+    /**
+     * 默认主题模式（运行时可通过 useThemeStore 动态切换）
+     * @default "light"
+     */
+    defaultAppearance?: "light" | "dark" | "auto";
+    /**
+     * 主色调（Lobe-UI 命名预设，运行时可通过 useThemeStore 动态切换）
+     *
+     * 不设置时使用 Lobe-UI 默认 primary 色阶（黑色系），
+     * 可选值："blue" | "cyan" | "geekblue" | "gold" | "green" | "lime"
+     *       | "magenta" | "orange" | "purple" | "red" | "volcano" | "yellow"
+     *
+     * @default undefined
+     */
+    primaryColor?: string;
+    /**
+     * 中性色（Lobe-UI 命名预设）
+     *
+     * 可选值："mauve" | "olive" | "sage" | "sand" | "slate"
+     *
+     * @default undefined
+     */
+    neutralColor?: string;
+    /**
+     * antd 组件前缀
+     *
+     * 支持三种配置方式（优先级从高到低）：
+     * 1. 运行时环境变量 process.env.YWKF_PREFIX_CLS
+     * 2. 插件选项中直接指定
+     * 3. 默认值 "ant"
+     *
+     * @default "ant"
+     */
+    prefixCls?: string;
+    /**
+     * 是否启用 CSS 变量
+     * @default true
+     */
+    cssVar?: boolean;
+    /**
+     * 是否注入全局样式重置
+     * @default true
+     */
+    globalReset?: boolean;
+    /**
+     * 是否启用外部主题注入（微前端场景）
+     *
+     * 启用后：
+     * - 应用启动时读取 window.__YWKF_THEME__ 作为初始覆盖
+     * - 监听 ywkf:theme-change 自定义事件，实现运行时主题同步
+     *
+     * @default false
+     */
+    externalTheme?: boolean;
+    /**
+     * antd 国际化 locale 配置
+     *
+     * - `"auto"`（默认）：运行时自动检测并动态加载对应的 antd 语言包，兜底 zhCN。
+     *   检测优先级：`window.__YWKF_LOCALE__`（微前端注入）> `navigator.language` > `"zh-CN"`
+     *
+     *   auto 模式下 locale 被纳入 ThemeStore，支持：
+     *   - 用户代码通过 `useThemeStore.getState().setLocale("en-US")` 运行时切换
+     *   - 微前端主应用通过 `ywkf:locale-change` 自定义事件同步 locale
+     *   - 便捷 hook `useLocale()` 获取当前 locale（BCP 47 tag）
+     *
+     * - 指定具体名称（如 `"zhCN"` / `"enUS"`）：静态导入该语言包，无运行时开销，
+     *   locale 仍会写入 ThemeStore 但不会自动检测或监听外部事件
+     *
+     * @default "auto"
+     */
+    locale?: "zhCN" | "enUS" | "zhTW" | "jaJP" | "koKR" | "auto";
+    /**
+     * 将 Tooltip / Dropdown / Modal 等弹层的挂载节点限定在 ThemeWrapper 容器内
+     *
+     * 解决问题：antd 弹层默认挂载到 document.body，在以下场景会导致样式失效：
+     * - 微前端子应用使用 StyleProvider 将样式注入到子应用容器，弹层挂载 body 后脱离样式范围
+     * - CSS 变量作用域被限定在特定容器，body 上的弹层无法继承
+     *
+     * 启用后会在 ThemeWrapper 内创建一个 `data-ywkf-root` 容器作为弹层挂载点，
+     * 该容器始终是 StyleProvider 的子孙节点，样式链路不会断裂。
+     *
+     * @default true
+     */
+    scopePopupContainer?: boolean;
+}
+/**
+ * 响应式主题系统插件
+ *
+ * 基于 antd-style + @4399ywkf/theme-system + Zustand 提供运行时可变的主题管理：
+ * - 使用 Lobe-UI 色彩体系（13 阶色阶 + 自定义算法）
+ * - 支持 PrimaryColors / NeutralColors 命名预设
+ * - 亮/暗色/跟随系统自动切换
+ * - 支持微前端场景主应用注入主题
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, themePlugin } from "@4399ywkf/core";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     themePlugin({
+ *       defaultAppearance: "light",
+ *       primaryColor: "geekblue",
+ *       neutralColor: "slate",
+ *       prefixCls: "my-app",
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare const themePlugin: (options?: ThemePluginOptions | undefined) => YwkfPlugin;
+
+interface ZustandPluginOptions {
+    /**
+     * 是否自动生成 store 脚手架（仅在 store/ 目录不存在时）
+     * @default true
+     */
+    scaffold?: boolean;
+    /**
+     * store 目录路径（相对于项目根目录）
+     * @default "store"
+     */
+    storeDir?: string;
+}
+/**
+ * Zustand 状态管理插件
+ *
+ * 采用扁平域/Slice 架构：
+ * - store/{domain}/slices/ 按业务域拆分
+ * - 每个 slice 拆为 initialState.ts + actions.ts
+ * - 域级 store.ts 聚合所有 slice
+ * - 使用 StateCreator<Store, [['zustand/devtools', never]], [], Action> 标准范式
+ * - 内置 devtools + subscribeWithSelector 中间件
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, zustandPlugin } from "@4399ywkf/core";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     zustandPlugin(),
+ *   ],
+ * });
+ * ```
+ */
+declare const zustandPlugin: (options?: ZustandPluginOptions | undefined) => YwkfPlugin;
+
+/**
+ * 开发服务器配置
+ */
+interface DevServerConfig {
+    /** 开发服务器端口 */
+    port?: number;
+    /** 开发服务器主机 */
+    host?: string;
+    /** 代理配置 */
+    proxy?: Record<string, string | object>;
+    /** 是否开启 HTTPS */
+    https?: boolean;
+}
+/**
+ * 输出配置
+ */
+interface OutputConfig {
+    /** 输出目录 */
+    path?: string;
+    /** 公共路径 */
+    publicPath?: string;
+    /** 是否清理输出目录 */
+    clean?: boolean;
+}
+/**
+ * HTML 配置
+ */
+interface HtmlConfig {
+    /** 页面标题 */
+    title?: string;
+    /** HTML 模板路径 */
+    template?: string;
+    /** favicon 路径 */
+    favicon?: string;
+    /** 挂载根元素 ID */
+    mountRoot?: string;
+}
+/**
+ * 样式配置
+ */
+interface StyleConfig {
+    /** 是否启用 CSS Modules */
+    cssModules?: boolean;
+    /** Less 配置 */
+    less?: {
+        /** 是否启用 */
+        enabled?: boolean;
+        /** Less 选项 */
+        lessOptions?: Record<string, unknown>;
+    };
+    /** Sass 配置 */
+    sass?: {
+        /** 是否启用 */
+        enabled?: boolean;
+        /** Sass 选项 */
+        sassOptions?: Record<string, unknown>;
+    };
+    /** 是否启用 TailwindCSS */
+    tailwindcss?: boolean;
+}
+/**
+ * 路由配置
+ */
+interface RouterConfig {
+    /** 路由基础路径 */
+    basename?: string;
+    /** 是否启用约定式路由 */
+    conventional?: boolean;
+    /** 约定式路由扫描目录 */
+    pagesDir?: string;
+    /** 排除的文件/目录模式 */
+    exclude?: (string | RegExp)[];
+    /**
+     * 懒加载的加载状态配置
+     * - `false`：禁用全局默认加载状态（各路由仍可通过 loading.tsx 单独配置）
+     * - `{ component: string }`：自定义全局默认加载组件的导入路径
+     * - 不配置：使用内置默认加载组件
+     *
+     * @example
+     * // 禁用加载状态
+     * loading: false
+     *
+     * @example
+     * // 自定义加载组件
+     * loading: { component: "@/components/Loading" }
+     */
+    loading?: false | {
+        component: string;
+    };
+}
+/**
+ * 微前端配置
+ */
+interface MicroFrontendConfig {
+    /** 是否启用微前端模式 */
+    enabled?: boolean;
+    /** 应用名称（用于 UMD 导出） */
+    name?: string;
+    /** 微前端框架类型 */
+    framework?: "qiankun" | "garfish";
+}
+/**
+ * 性能配置
+ */
+interface PerformanceConfig {
+    /** 是否启用 Rsdoctor 分析 */
+    rsdoctor?: boolean;
+    /** 是否开启代码分割 */
+    splitChunks?: boolean;
+    /** 是否移除 console */
+    dropConsole?: boolean;
+}
+/**
+ * 工具链配置
+ */
+interface ToolsConfig {
+    /**
+     * 自定义 Rspack 配置
+     * @param config 当前配置
+     * @param context 上下文信息
+     * @returns 修改后的配置
+     */
+    rspack?: (config: Configuration, context: {
+        isDev: boolean;
+        isProd: boolean;
+    }) => Configuration | undefined;
+}
+/**
+ * 环境变量配置
+ */
+interface EnvConfig {
+    /** 公共环境变量文件路径 */
+    publicEnvFile?: string;
+    /** 环境特定的变量文件目录 */
+    envDir?: string;
+}
+/**
+ * 内置插件快捷配置
+ *
+ * 这些插件默认启用，无需手动 import 和声明。
+ * 设为 `false` 可禁用，传入配置对象可自定义参数。
+ *
+ * @example
+ * ```ts
+ * defineConfig({
+ *   // 禁用 zustand
+ *   zustand: false,
+ *   // 自定义 reactQuery 参数
+ *   reactQuery: { timeout: 30000 },
+ * })
+ * ```
+ */
+interface BuiltinPluginConfig {
+    /**
+     * React Query + Axios 请求层（默认启用）
+     *
+     * 设为 `false` 禁用；传入配置对象自定义参数。
+     * @default {} (启用，使用默认配置)
+     */
+    reactQuery?: ReactQueryPluginOptions | false;
+    /**
+     * Zustand 状态管理（默认启用）
+     *
+     * 设为 `false` 禁用；传入配置对象自定义参数。
+     * @default {} (启用，使用默认配置)
+     */
+    zustand?: ZustandPluginOptions | false;
+    /**
+     * Tailwind CSS（默认启用）
+     *
+     * 设为 `false` 禁用；传入配置对象自定义参数。
+     * @default {} (启用，使用默认配置)
+     */
+    tailwind?: TailwindPluginOptions | false;
+}
+/**
+ * 可选插件快捷配置
+ *
+ * 这些插件默认不启用，配置后自动启用。
+ * 设为 `true` 使用默认配置启用，传入配置对象可自定义参数。
+ *
+ * @example
+ * ```ts
+ * defineConfig({
+ *   theme: { darkMode: true, locale: "auto" },
+ *   browserCheck: { fromBrowserslist: true },
+ * })
+ * ```
+ */
+interface OptionalPluginConfig {
+    /**
+     * antd-style 主题系统
+     *
+     * 设为 `true` 使用默认配置启用，或传入 ThemePluginOptions 自定义。
+     */
+    theme?: ThemePluginOptions | true;
+    /**
+     * 国际化 (i18next)
+     *
+     * 设为 `true` 使用默认配置启用，或传入 I18nPluginOptions 自定义。
+     */
+    i18n?: I18nPluginOptions | true;
+    /**
+     * 微前端 (Garfish)
+     *
+     * 传入 GarfishPluginOptions 配置。
+     */
+    garfish?: GarfishPluginOptions;
+    /**
+     * 浏览器兼容性检查
+     *
+     * 设为 `true` 使用默认配置启用，或传入 BrowserCheckPluginOptions 自定义。
+     */
+    browserCheck?: BrowserCheckPluginOptions | true;
+    /**
+     * Biome 代码规范
+     *
+     * 设为 `true` 使用默认配置启用，或传入 BiomePluginOptions 自定义。
+     */
+    biome?: BiomePluginOptions | true;
+    /**
+     * Mock 数据服务
+     *
+     * 设为 `true` 使用默认配置启用，或传入 MockPluginOptions 自定义。
+     */
+    mock?: MockPluginOptions | true;
+    /**
+     * 构建分析
+     *
+     * 设为 `true` 使用默认配置启用，或传入 AnalyticsPluginOptions 自定义。
+     */
+    analytics?: AnalyticsPluginOptions | true;
+}
+/**
+ * 框架内部配置（不含插件快捷键）
+ *
+ * 内部模块使用此类型，通过 `Required<YwkfConfig>` 确保所有字段有值。
+ */
+interface YwkfConfig {
+    /** 应用名称 */
+    appName?: string;
+    /** 应用中文名 */
+    appCName?: string;
+    /** 开发服务器配置 */
+    dev?: DevServerConfig;
+    /** 输出配置 */
+    output?: OutputConfig;
+    /** HTML 配置 */
+    html?: HtmlConfig;
+    /** 样式配置 */
+    style?: StyleConfig;
+    /** 路由配置 */
+    router?: RouterConfig;
+    /** 微前端配置 */
+    microFrontend?: MicroFrontendConfig;
+    /** 性能配置 */
+    performance?: PerformanceConfig;
+    /** 工具链配置 */
+    tools?: ToolsConfig;
+    /** 环境变量配置 */
+    env?: EnvConfig;
+    /** 路径别名 */
+    alias?: Record<string, string>;
+    /** 插件列表 */
+    plugins?: PluginConfig[];
+}
+/**
+ * 用户输入配置（支持插件快捷键）
+ *
+ * 支持两种插件声明方式（可混用）：
+ *
+ * **方式一：快捷配置（推荐）**
+ * ```ts
+ * defineConfig({
+ *   appName: "my-app",
+ *   theme: { darkMode: true },
+ *   browserCheck: { fromBrowserslist: true },
+ * })
+ * ```
+ *
+ * **方式二：手动插件（完全控制）**
+ * ```ts
+ * import { themePlugin, browserCheckPlugin } from "@4399ywkf/core";
+ * defineConfig({
+ *   plugins: [themePlugin({ darkMode: true }), browserCheckPlugin()],
+ * })
+ * ```
+ *
+ * 两种方式可以混合使用。快捷配置中的插件与 `plugins` 数组合并时，
+ * 同名插件以 `plugins` 数组中的为准（显式声明优先）。
+ */
+interface YwkfUserConfig extends YwkfConfig, BuiltinPluginConfig, OptionalPluginConfig {
+}
+/**
+ * 定义配置的辅助函数（提供类型提示）
+ *
+ * 接受 `YwkfUserConfig`（含插件快捷键），返回 `YwkfConfig`（内部类型）。
+ * 类型转换在运行时由 `normalizeConfig` 完成。
+ */
+declare function defineConfig(config: YwkfUserConfig): YwkfConfig;
+/**
+ * 默认配置
+ */
+declare const defaultConfig: Required<YwkfConfig>;
+
+export { type AnalyticsPluginOptions as A, type BuiltinPluginConfig as B, type CodeInjection as C, type DevServerConfig as D, type EnvConfig as E, type GeneratedFile as F, type GeneratorContext as G, type HtmlConfig as H, type I18nPluginOptions as I, type GeneratorHooks as J, type PluginContext as K, type RouterHooks as L, type MicroFrontendConfig as M, type RuntimeHooks as N, type OptionalPluginConfig as O, type PerformanceConfig as P, type YwkfPlugin as Q, type RouterConfig as R, type StyleConfig as S, type ToolsConfig as T, type RouteItem as U, type DefinePlugin as V, type PluginAPI as W, type PluginLogger as X, type YwkfConfig as Y, type ZustandPluginOptions as Z, defineConfig as a, type OutputConfig as b, type YwkfUserConfig as c, defaultConfig as d, type PluginHooks as e, type PluginConfig as f, analyticsPlugin as g, type BiomePluginOptions as h, biomePlugin as i, type BrowserCheckPluginOptions as j, type BrowserMinVersions as k, browserCheckPlugin as l, type GarfishPluginOptions as m, garfishPlugin as n, getDefaultBiomeConfig as o, i18nPlugin as p, type MockPluginOptions as q, mockPlugin as r, type ReactQueryPluginOptions as s, reactQueryPlugin as t, type TailwindPluginOptions as u, type ThemePluginOptions as v, tailwindPlugin as w, themePlugin as x, type BuildHooks as y, zustandPlugin as z };