@done-coding/admin-core 0.8.3-alpha.0 → 0.9.1-alpha.0

package/es/utils/theme-scale.mjs

@@ -0,0 +1,37 @@
+const l = (s) => {
+  const t = s.trim().replace(/^#/, "");
+  if (t.length === 3) {
+    const n = parseInt(t[0] + t[0], 16), r = parseInt(t[1] + t[1], 16), e = parseInt(t[2] + t[2], 16);
+    return [n, r, e].some(Number.isNaN) ? null : [n, r, e];
+  }
+  if (t.length === 6) {
+    const n = parseInt(t.slice(0, 2), 16), r = parseInt(t.slice(2, 4), 16), e = parseInt(t.slice(4, 6), 16);
+    return [n, r, e].some(Number.isNaN) ? null : [n, r, e];
+  }
+  return null;
+}, o = (s, t, n) => {
+  const r = (e) => Math.min(255, Math.max(0, Math.round(e))).toString(16).padStart(2, "0");
+  return `#${r(s)}${r(t)}${r(n)}`;
+}, i = (s, t, n) => {
+  const r = l(s), e = l(t);
+  return !r || !e ? t : o(
+    r[0] * n + e[0] * (1 - n),
+    r[1] * n + e[1] * (1 - n),
+    r[2] * n + e[2] * (1 - n)
+  );
+}, a = (s, t) => {
+  const n = t === "light" ? "#ffffff" : "#141414", r = t === "light" ? "#000000" : "#ffffff", e = (c) => i(n, s, c / 10);
+  return {
+    base: s,
+    "light-3": e(3),
+    "light-5": e(5),
+    "light-7": e(7),
+    "light-8": e(8),
+    "light-9": e(9),
+    "dark-2": i(r, s, 0.2)
+  };
+};
+export {
+  a as themeScaleDerive,
+  i as themeScaleMix
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/admin-core",
-  "version": "0.8.3-alpha.0",
+  "version": "0.9.1-alpha.0",
   "description": "后台管理核心",
   "private": false,
   "main": "lib/index.cjs",
@@ -60,8 +60,6 @@
     "jsdom": "^29.1.0",
     "less": "^4.2.0",
     "typescript": "^5.2.2",
-    "unplugin-auto-import": "^0.17.8",
-    "unplugin-vue-components": "^0.26.0",
     "vite": "^5.2.0",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^1.6.1",
@@ -81,5 +79,5 @@
     "node": ">=18.0.0",
     "pnpm": ">=9.0.0"
   },
-  "gitHead": "2db8c4bfcf63a1cd077ef7c7426e25f33c243e2b"
+  "gitHead": "6924deab3afbbc45ec75501f9a888ae0eb3d0648"
 }

package/types/bridge/config-hook.d.ts

@@ -0,0 +1,91 @@
+import { DeepReadonly } from 'vue';
+import { AppBaseInfo, AppLayoutHeaderConfig, AppLayoutFooterConfig, AppLayoutSidebarConfig, AppLayoutBreadcrumbConfig, AppLayoutBodyConfig, AppLayoutViewportConfig, AppThemeConfig, AppLayoutConfig } from './index';
+/**
+ * 可 update 的响应式配置字段 key 联合（插件系统一期 7 个 + viewport 边框期补 1 = 8 个）。
+ *
+ * #插件系统一期：bridge 的布局/主题/基础信息字段下沉为 reactive 响应式，
+ * 经 `update(key, partial)` 单字段一级浅合并触发。viewport 边框期新增
+ * `APP_LAYOUT_VIEWPORT_CONFIG`（同属布局子，纳入本联合 + layoutAggregate）。
+ * 其余 init 字段（env / cache / router 族 / userInfoAccess）非响应式范围，[MUST NOT] 纳入本联合。
+ */
+export type UpdatableConfigKey = "APP_BASE_INFO" | "APP_LAYOUT_HEADER_CONFIG" | "APP_LAYOUT_FOOTER_CONFIG" | "APP_LAYOUT_SIDEBAR_CONFIG" | "APP_LAYOUT_BREADCRUMB_CONFIG" | "APP_LAYOUT_BODY_CONFIG" | "APP_LAYOUT_VIEWPORT_CONFIG" | "APP_THEME_CONFIG";
+/**
+ * 7 个可 update 字段 key → 值类型映射。
+ *
+ * `update<K>(key, partial)` 的 `partial` 类型经 `Partial<UpdatableConfigMap[K]>`
+ * 推导；`createBridgeConfigHook` 的 init 入参亦以本映射约束（见 `BridgeConfigInit`）。
+ */
+export interface UpdatableConfigMap {
+    /** 应用基础信息 */
+    APP_BASE_INFO: AppBaseInfo;
+    /** 应用布局-header 配置 */
+    APP_LAYOUT_HEADER_CONFIG: AppLayoutHeaderConfig;
+    /** 应用布局-footer 配置 */
+    APP_LAYOUT_FOOTER_CONFIG: AppLayoutFooterConfig;
+    /** 应用布局-sidebar 配置 */
+    APP_LAYOUT_SIDEBAR_CONFIG: AppLayoutSidebarConfig;
+    /** 应用布局-面包屑配置 */
+    APP_LAYOUT_BREADCRUMB_CONFIG: AppLayoutBreadcrumbConfig;
+    /** 应用布局-页面主体配置 */
+    APP_LAYOUT_BODY_CONFIG: AppLayoutBodyConfig;
+    /** 应用布局-视口边框配置 */
+    APP_LAYOUT_VIEWPORT_CONFIG: AppLayoutViewportConfig;
+    /** 应用主题配置 */
+    APP_THEME_CONFIG: AppThemeConfig;
+}
+/**
+ * `createBridgeConfigHook` 入参类型——7 个本期响应式字段的初值（= `UpdatableConfigMap`）。
+ *
+ * 由 `createAdminBridge` 闭包内从 `options` 的对应 7 字段直传；入参字段对象将被
+ * 直接 `reactive()` 化（方案 A，[MUST NOT] 浅拷贝），故 [MUST] 为去 freeze 后的非
+ * frozen 裸对象（app 端去字段级 freeze 保证）。
+ */
+export type BridgeConfigInit = UpdatableConfigMap;
+/**
+ * configHook 内部返回契约——`update` 方法 + 8 个对外 readonly 视图。
+ *
+ * **不对外 export**：`createBridgeConfigHook` / 本 interface / 上述类型符号 [MUST NOT]
+ * 在 `bridge/index.ts` re-export（守封装边界）。`bridge/index.ts` 仅内部 import 工厂，
+ * 把 `update` 与各 `roXxx` 视图组装进 `AdminBridge` 公开面。
+ *
+ * 7 个 readonly 视图各为对应 reactive 子配置的 `readonly()` 深只读包装；`roLayout`
+ * 为 5 布局子的 `reactive({...})` 聚合的 readonly 包装——5 字段指向各 reactive 子配置，
+ * 任一布局子 `update` 原地改经叶子代理同步跟随（Vue reactive 深度转换保留嵌套响应式），零拷贝。
+ */
+export interface BridgeConfigHook {
+    /** 单字段一级浅合并 update（`Object.assign` 派发到对应 reactive 子配置） */
+    update: <K extends UpdatableConfigKey>(key: K, partial: Partial<UpdatableConfigMap[K]>) => void;
+    /** 应用基础信息对外只读视图 */
+    roBaseInfo: DeepReadonly<AppBaseInfo>;
+    /** 应用布局-header 配置对外只读视图 */
+    roHeader: DeepReadonly<AppLayoutHeaderConfig>;
+    /** 应用布局-footer 配置对外只读视图 */
+    roFooter: DeepReadonly<AppLayoutFooterConfig>;
+    /** 应用布局-sidebar 配置对外只读视图 */
+    roSidebar: DeepReadonly<AppLayoutSidebarConfig>;
+    /** 应用布局-面包屑配置对外只读视图 */
+    roBreadcrumb: DeepReadonly<AppLayoutBreadcrumbConfig>;
+    /** 应用布局-页面主体配置对外只读视图 */
+    roBody: DeepReadonly<AppLayoutBodyConfig>;
+    /** 应用布局-视口边框配置对外只读视图 */
+    roViewport: DeepReadonly<AppLayoutViewportConfig>;
+    /** 应用主题配置对外只读视图 */
+    roTheme: DeepReadonly<AppThemeConfig>;
+    /**
+     * 应用布局聚合配置只读视图（5 布局子 reactive 聚合的 readonly 包装）。
+     *
+     * `reactive({header: reactiveHeader, ...})` 5 字段指向各 reactive 子配置，任一布局子
+     * update 原地改经叶子代理同步跟随（Vue reactive 深度转换保留嵌套响应式），零拷贝。
+     */
+    roLayout: DeepReadonly<AppLayoutConfig>;
+}
+/**
+ * bridge 响应式配置 hook 工厂。
+ *
+ * 接收 7 个本期字段初值，逐字段 `reactive()` 化（方案 A：直接 reactive 入参对象，
+ * [MUST NOT] 浅拷贝），内部把 5 布局子聚合为 `layoutAggregate = reactive({...})`，
+ * 对外返回 `update`（单字段一级浅合并 `Object.assign`，[MUST NOT] 深合并 / merge / clone）+
+ * 7 个 `readonly()` 视图 + 1 个 `roLayout`（readonly 聚合视图）。每次 `createAdminBridge`
+ * 调用各自闭包内构造一份，零模块级单例（守实例隔离）。
+ */
+export declare function createBridgeConfigHook(init: BridgeConfigInit): BridgeConfigHook;

package/types/bridge/index.d.ts

@@ -1,6 +1,10 @@
+import { App, DeepReadonly, Ref } from 'vue';
 import { RouteRecordRaw } from 'vue-router';
 import { createUseState } from './state';
 import { createGenerateRouteMetaRawTree } from './route';
+import { UpdatableConfigKey, UpdatableConfigMap } from './config-hook';
+import { AdminBridgePluginLike } from './plugin';
+import { AdminThemeModule } from './theme';
 export { createUseState, type UseStateOptions } from './state';
 export { createGenerateRouteMetaRawTree, type RouteMetaDefaultConfig, } from './route';
 export { createStorageWithNamespace } from './storage';
@@ -37,6 +41,7 @@ export interface AdminBridgeRegisterOptions<UserInfo = unknown, LoginParams = un
     /** 刷新 token api（#C 期签名最简化：core 不感知业务 shape，直传 refreshToken string；业务方 wrap 内自打包业务约定的入参 shape，如 `{Authorization: rt}`），增量可选 */
     refreshTokenApi?: (refreshToken: string) => Promise<string>;
 }
+export type { AdminBridgePlugin, AdminBridgePluginBridgeSlice, AdminBridgePluginContext, AdminBridgePluginInstall, AdminBridgePluginLike, } from './plugin';
 /**
  * pinia persist storage 适配器最小接口。
  *
@@ -75,6 +80,24 @@ export interface AppThemeColor {
     errorColor: string;
     /** 信息色 */
     infoColor: string;
+    /** 圆角（风格可选；core 挂 --admin-core-radius ＋ --el-border-radius-base） */
+    radius?: string;
+    /** 边框色（风格可选；core 挂 --admin-core-border-color ＋ --el-border-color） */
+    borderColor?: string;
+    /** 阴影（风格可选；core 挂 --admin-core-shadow ＋ --el-box-shadow） */
+    shadow?: string;
+    /** 边框宽（风格可选；core 挂 --admin-core-border-width ＋ --el-border-width） */
+    borderWidth?: string;
+    /** 强调色（风格可选；core 仅挂 --admin-core-accent，EP 无对应） */
+    accent?: string;
+    /** 辉光（风格可选；core 仅挂 --admin-core-glow，EP 无对应） */
+    glow?: string;
+    /** 模糊（风格可选；core 仅挂 --admin-core-blur，EP 无对应） */
+    blur?: string;
+    /** 聚焦环（风格可选；core 仅挂 --admin-core-focus-ring，EP 无对应） */
+    focusRing?: string;
+    /** 表面色（风格可选；core 仅挂 --admin-core-surface，EP 无对应） */
+    surface?: string;
 }
 /**
  * `store/app.ts` 实际消费的 app config 子集结构。
@@ -111,6 +134,23 @@ export interface AppConfig {
         /** 页面主体 padding - 默认值(px) */
         shimPadding: number;
     };
+    /**
+     * 应用布局-视口边框配置（整个 app-shell 相对浏览器视口四边内缩，套"边框"留白观感）。
+     *
+     * Header/Sidebar 的 fixed 锚点由 `0` 改贴四边 padding 值；AppBody 在原扣 header 高 /
+     * sidebar 宽基础上经 calc 再叠加对应 viewport 边距。app 端可整体不传（核内默认四边 0
+     * = 不套框，现状不变）；布局插件经 `bridge.update("APP_LAYOUT_VIEWPORT_CONFIG", ...)` 设值。
+     */
+    APP_LAYOUT_VIEWPORT_CONFIG: {
+        /** 视口上内边距(px) */
+        paddingTop: number;
+        /** 视口右内边距(px) */
+        paddingRight: number;
+        /** 视口下内边距(px) */
+        paddingBottom: number;
+        /** 视口左内边距(px) */
+        paddingLeft: number;
+    };
     /** 应用主题配置（store/app 取 dark / light，各为完整 AppThemeColor） */
     APP_THEME_CONFIG: {
         /** 亮色主题 */
@@ -178,6 +218,8 @@ export interface AppLayoutConfig {
     breadcrumb: AppLayoutBreadcrumbConfig;
     /** 页面主体配置 */
     body: AppConfig["APP_LAYOUT_BODY_CONFIG"];
+    /** 视口边框配置 */
+    viewport: AppConfig["APP_LAYOUT_VIEWPORT_CONFIG"];
 }
 /**
  * 应用路由配置（#2.5 期新增，per ADR-6）。
@@ -232,6 +274,8 @@ export type AppLayoutFooterConfig = AppConfig["APP_LAYOUT_FOOTER_CONFIG"];
 export type AppLayoutSidebarConfig = AppConfig["APP_LAYOUT_SIDEBAR_CONFIG"];
 /** 应用布局-页面主体配置 type 别名 */
 export type AppLayoutBodyConfig = AppConfig["APP_LAYOUT_BODY_CONFIG"];
+/** 应用布局-视口边框配置 type 别名 */
+export type AppLayoutViewportConfig = AppConfig["APP_LAYOUT_VIEWPORT_CONFIG"];
 /** 应用主题配置 type 别名 */
 export type AppThemeConfig = AppConfig["APP_THEME_CONFIG"];
 /** 应用路由元信息默认配置 type 别名 */
@@ -311,6 +355,11 @@ export interface AdminBridgeInitOptions<UserInfo = unknown> {
     APP_LAYOUT_BREADCRUMB_CONFIG: AppLayoutBreadcrumbConfig;
     /** 应用布局-页面主体配置 */
     APP_LAYOUT_BODY_CONFIG: AppLayoutBodyConfig;
+    /**
+     * 应用布局-视口边框配置（可选；app 整体不传时核内默认四边 0 = 不套框，现状不变）。
+     * 传部分字段时与默认四边 0 浅合并（见 createAdminBridge 内 DEFAULT 合并）。
+     */
+    APP_LAYOUT_VIEWPORT_CONFIG?: Partial<AppLayoutViewportConfig>;
     /** 应用路由元信息默认配置（bridge 内部 generateRouteMetaRawTree 派生） */
     APP_ROUTER_META_DEFAULT_CONFIG: AppRouterMetaDefaultConfig;
     /** 应用路由配置（#2.5 期新增字段） */
@@ -363,23 +412,25 @@ export interface AdminBridge<UserInfo = unknown, LoginParams = unknown> {
     /** 刷新 token api（createUserStore refreshTokenFn 内调；#C 期签名最简化：core 直传 refreshToken string，业务 wrap 内自打包业务 shape；未注册被调 reject 原生 Error） */
     refreshTokenApi: (refreshToken: string) => Promise<string>;
     /** 应用基础信息（per #2.5 期 REQ-1 直接挂载形态） */
-    readonly APP_BASE_INFO: AppBaseInfo;
+    readonly APP_BASE_INFO: DeepReadonly<AppBaseInfo>;
     /** 应用环境信息（per #2.5 期 REQ-1） */
     readonly APP_ENV_INFO: AppEnvInfo;
     /** 应用缓存配置（per #2.5 期 REQ-1） */
     readonly APP_CACHE_CONFIG: AppCacheConfig;
     /** 应用布局-header 配置（per #2.5 期 REQ-1） */
-    readonly APP_LAYOUT_HEADER_CONFIG: AppLayoutHeaderConfig;
+    readonly APP_LAYOUT_HEADER_CONFIG: DeepReadonly<AppLayoutHeaderConfig>;
     /** 应用布局-footer 配置（per #2.5 期 REQ-1） */
-    readonly APP_LAYOUT_FOOTER_CONFIG: AppLayoutFooterConfig;
+    readonly APP_LAYOUT_FOOTER_CONFIG: DeepReadonly<AppLayoutFooterConfig>;
     /** 应用布局-sidebar 配置（per #2.5 期 REQ-1） */
-    readonly APP_LAYOUT_SIDEBAR_CONFIG: AppLayoutSidebarConfig;
+    readonly APP_LAYOUT_SIDEBAR_CONFIG: DeepReadonly<AppLayoutSidebarConfig>;
     /** 应用布局-面包屑配置（per #2.5 期 REQ-1） */
-    readonly APP_LAYOUT_BREADCRUMB_CONFIG: AppLayoutBreadcrumbConfig;
+    readonly APP_LAYOUT_BREADCRUMB_CONFIG: DeepReadonly<AppLayoutBreadcrumbConfig>;
     /** 应用布局-页面主体配置（per #2.5 期 REQ-1） */
-    readonly APP_LAYOUT_BODY_CONFIG: AppLayoutBodyConfig;
+    readonly APP_LAYOUT_BODY_CONFIG: DeepReadonly<AppLayoutBodyConfig>;
+    /** 应用布局-视口边框配置（响应式只读视图，经 bridge.update 跟随） */
+    readonly APP_LAYOUT_VIEWPORT_CONFIG: DeepReadonly<AppLayoutViewportConfig>;
     /** 应用布局聚合配置（per #2.5 期 ADR-3 bridge 内部聚合派生） */
-    readonly APP_LAYOUT_CONFIG: AppLayoutConfig;
+    readonly APP_LAYOUT_CONFIG: DeepReadonly<AppLayoutConfig>;
     /** 应用路由元信息默认配置（per #2.5 期 REQ-1） */
     readonly APP_ROUTER_META_DEFAULT_CONFIG: AppRouterMetaDefaultConfig;
     /** 应用路由配置（per #2.5 期 REQ-1） */
@@ -387,9 +438,58 @@ export interface AdminBridge<UserInfo = unknown, LoginParams = unknown> {
     /** 应用路由路径配置（per #7.3 期；8 path 聚合 readonly 挂载） */
     readonly APP_ROUTER_PATHS_CONFIG: AppRouterPathsConfig;
     /** 应用主题配置（per #2.5 期 REQ-1） */
-    readonly APP_THEME_CONFIG: AppThemeConfig;
+    readonly APP_THEME_CONFIG: DeepReadonly<AppThemeConfig>;
+    /**
+     * 主题模块（架构反转：core/bridge 主导主题切换）。
+     *
+     * `theme.{add,remove,setStyle,setDark,list,labelOf}`——风格 map 注册/注销 ＋ 切换 ＋ 展示名。
+     * 插件 install 经 `bridge.theme.add(name, preset)` 注册风格（preset = {config,label?}）；切换真相在
+     * bridge，appStore / AppTheme.vue 转发 `setStyle` / `setDark`（[MUST NOT] bridge 反向监测 store）。
+     */
+    readonly theme: AdminThemeModule;
+    /** 当前风格名（响应式只读真相源；[MUST NOT] 解构/快照取值，⚠️ 切换后定格） */
+    readonly themeStyle: DeepReadonly<Ref<string>>;
+    /** 是否暗色（响应式只读真相源；appStore.isDarkTheme 读此、挂值 composable toggle .dark 读此） */
+    readonly themeIsDark: DeepReadonly<Ref<boolean>>;
+    /**
+     * 当前生效的 JS 主题色（输出 B：JS 色值直给，与挂值 composable 的 cssvar 输出 A 对称）。
+     *
+     * = `themeIsDark ? APP_THEME_CONFIG.dark : APP_THEME_CONFIG.light`——明暗 + 风格的
+     * 选择逻辑落在 bridge 这个真相源（store **不再自选**，仅 `appStore.theme` 转发本字段）。
+     * 给「需对颜色做运算、吃不了 CSS var」的消费方直读真实色值
+     * （MenuTree → ElMenu hover 派生 TinyColor parse / 任意 JS 内联样式）。
+     * 纯 CSS 消费方走挂值 composable 写的 `--admin-core-*` cascade（输出 A）。
+     * [MUST NOT] 解构/快照（⚠️ 切换风格/明暗后定格）。
+     */
+    readonly themeColors: DeepReadonly<Ref<AppThemeColor>>;
     /** 用户信息字段访问器集（业务注入；createUserStore 经 bridge.userInfoAccess.<字段>.get/set 读写，第一宪法 core 零字段耦合） */
     readonly userInfoAccess: UserInfoAccess<UserInfo>;
+    /**
+     * 更新本期 7 个响应式配置字段（插件系统一期，REQ-1）。
+     *
+     * 两参单字段 + **一级浅合并**（`Object.assign` 把 partial 第一层属性覆盖到对应
+     * reactive 子配置，未传字段保留）。`theme` 的 `light`/`dark` 作为第一层属性整体
+     * 替换（`update("APP_THEME_CONFIG", {light: newLight})` 整体替换 `light`、保留
+     * `dark`）。[MUST NOT] 期望深合并——非 lodash merge / structuredClone 语义。
+     * update 后对应 `bridge.APP_XXX` readonly 视图自动跟随。
+     */
+    update: <K extends UpdatableConfigKey>(key: K, partial: Partial<UpdatableConfigMap[K]>) => void;
+    /**
+     * 安装 admin bridge 插件。
+     *
+     * 插件状态按 bridge 实例隔离；同一插件引用或同名插件重复安装时会跳过。
+     * `app.use(bridge)` 只负责 Vue provide，完整插件扩展走本方法。
+     */
+    use: <Options = unknown>(plugin: AdminBridgePluginLike<UserInfo, LoginParams, Options>, options?: Options) => AdminBridge<UserInfo, LoginParams>;
+    /**
+     * Vue 插件 install（插件系统一期，REQ-9）。
+     *
+     * `app.use(bridge)` 经 `app.provide(ADMIN_BRIDGE_KEY, bridge)` 全局注入整个 bridge
+     * 实例；业务子组件 `inject(ADMIN_BRIDGE_KEY)` 拿到整 bridge → 读只读响应式配置 +
+     * 调 `bridge.update`。**opt-in**：不 `app.use(bridge)` 则 inject 返回 undefined。
+     * 区别于组件级 `APP_LAYOUT_BRIDGE_KEY`（layout 域窄切片）——本通道是 app 级全局整实例。
+     */
+    install: (app: App) => App;
 }
 /**
  * 认证桥接无状态纯工厂：接收 init 参数，内部立即初始化，返回可直接使用的

package/types/bridge/plugin.d.ts

@@ -0,0 +1,39 @@
+import { AdminBridge } from './index';
+import { UpdatableConfigKey, UpdatableConfigMap } from './config-hook';
+/**
+ * 插件可访问的 bridge 视图。
+ *
+ * 屏蔽运行时编排入口、auth facade 与业务 API；需要业务动作时由插件 options 承接。
+ */
+export type AdminBridgePluginBridgeSlice<UserInfo = unknown, LoginParams = unknown> = Omit<AdminBridge<UserInfo, LoginParams>, "init" | "register" | "getToken" | "goToLogin" | "refreshToken" | "refreshAuth" | "loginApi" | "logoutApi" | "getUserInfoApi" | "refreshTokenApi" | "use" | "install">;
+/**
+ * admin bridge 插件安装上下文。
+ *
+ * 插件只通过公开 bridge 实例与受控 action 工作，不访问 bridge 内部闭包状态。
+ */
+export interface AdminBridgePluginContext<UserInfo = unknown, LoginParams = unknown> {
+    /** 当前安装插件的 bridge 可用能力 */
+    bridge: AdminBridgePluginBridgeSlice<UserInfo, LoginParams>;
+    /** 配置更新 action 的便捷引用 */
+    update: <K extends UpdatableConfigKey>(key: K, partial: Partial<UpdatableConfigMap[K]>) => void;
+}
+/** admin bridge 插件安装函数。 */
+export type AdminBridgePluginInstall<UserInfo = unknown, LoginParams = unknown, Options = unknown> = (ctx: AdminBridgePluginContext<UserInfo, LoginParams>, options?: Options) => void;
+/** admin bridge 对象插件。 */
+export interface AdminBridgePlugin<UserInfo = unknown, LoginParams = unknown, Options = unknown> {
+    /** 插件名；存在时用于跨对象实例的幂等安装 */
+    name?: string;
+    /** 插件安装函数 */
+    install: AdminBridgePluginInstall<UserInfo, LoginParams, Options>;
+}
+/** admin bridge 支持函数插件与对象插件两种形态。 */
+export type AdminBridgePluginLike<UserInfo = unknown, LoginParams = unknown, Options = unknown> = AdminBridgePlugin<UserInfo, LoginParams, Options> | AdminBridgePluginInstall<UserInfo, LoginParams, Options>;
+/** 创建单个 bridge 实例专属的插件安装宿主。 */
+export declare function createBridgePluginHost<UserInfo = unknown, LoginParams = unknown>(): {
+    use: <Options = unknown>(payload: {
+        bridge: AdminBridge<UserInfo, LoginParams>;
+        update: AdminBridgePluginContext<UserInfo, LoginParams>["update"];
+        plugin: AdminBridgePluginLike<UserInfo, LoginParams, Options>;
+        options?: Options;
+    }) => AdminBridge<UserInfo, LoginParams>;
+};

package/types/bridge/theme.d.ts

@@ -0,0 +1,85 @@
+import { DeepReadonly, Ref } from 'vue';
+import { AppThemeConfig, StorageLike } from './index';
+/**
+ * 风格切换真相源在 bridge——core 之于主题 ＝ core 之于 userInfo：core 是
+ * 「无知容器 + 切换能力暴露者」，不持有 dark 真相、不关心主题内容，谁实现谁注册
+ * （core 默认一对 / 插件扩展 core 均不关心）。
+ *
+ * 本模块从 `bridge/index.ts` 按耦合度拆出（core CLAUDE.md 规则：bridge 可独立能力
+ * [MUST NOT] 都耦合进 index.ts）。维护风格 map（name → 快照 config）＋ 顶层响应式
+ * `themeStyle` / `themeIsDark`，对外 `theme.{add,remove,setStyle,setDark,list}`。
+ * setStyle 复用注入的 `update("APP_THEME_CONFIG", {light,dark})` 把当前风格 config
+ * 灌进 bridge 响应式 APP_THEME_CONFIG（故 init 后响应式 APP_THEME_CONFIG 随切换变，
+ * 不再恒等于初始值）；用注入的 `storage` 持久化 `{themeStyle,themeIsDark}` 并 init 恢复。
+ */
+/**
+ * 主题注册项（`bridge.theme.add` 第 2 参）——core 侧主题「preset」结构。
+ *
+ * core 不依赖 plugin，故自定义此最小注册形；plugin-theme 的 `AdminThemePreset`
+ * （含 id/label/description/config）是其结构超集，可整坨直接透传：
+ * `bridge.theme.add(preset.id, preset)`（多出的 id/description 作 excess 字段被忽略）。
+ */
+export interface AdminThemeEntry {
+    /**
+     * 风格色值（light/dark 两套 `AppThemeColor`）。
+     *
+     * 内部做浅快照（`{light:{...},dark:{...}}`）——与调用方对象解耦，且与 bridge
+     * 响应式 APP_THEME_CONFIG 的 proxy target 解耦（避免切走后反写注册值）。
+     */
+    config: AppThemeConfig;
+    /** 展示名（供 `AppTheme.vue` 下拉显示，如中文「柔光悬浮」）；缺省回退注册 name 自身。 */
+    label?: string;
+}
+/** 主题模块对外能力。 */
+export interface AdminThemeModule {
+    /**
+     * 注册/覆盖一个风格（插件 install 经 `bridge.theme.add` 调；同名覆盖）。
+     *
+     * 第 2 参收 {@link AdminThemeEntry}（`{config,label?}`）；config 内部浅快照解耦。
+     * 若新注册 name 命中持久化恢复的目标风格（init 时尚未注册），自动 `setStyle(name)`。
+     */
+    add: (name: string, preset: AdminThemeEntry) => void;
+    /** 注销一个风格（`'default'` 不可注销；注销当前风格则回退 `'default'`）。 */
+    remove: (name: string) => void;
+    /** 切换风格（未注册回退 `'default'`）：同步 APP_THEME_CONFIG ＋ 持久化。 */
+    setStyle: (name: string) => void;
+    /** 切换暗色：写 `themeIsDark` ＋ 持久化。 */
+    setDark: (isDark: boolean) => void;
+    /** 响应式风格名列表（只读，供 `AppTheme.vue` 下拉；`length>1` 才显示选择）。 */
+    list: DeepReadonly<Ref<string[]>>;
+    /** 取风格展示名（`add` 注册的 label；缺省回退 name 自身）。 */
+    labelOf: (name: string) => string;
+}
+/** 主题 hook 对外契约：模块 ＋ 两个顶层响应式只读真相源。 */
+export interface BridgeThemeHook {
+    /** 主题模块（add/remove/setStyle/setDark/list） */
+    theme: AdminThemeModule;
+    /** 当前风格名（响应式只读；切换真相源，appStore / AppTheme.vue 读此） */
+    themeStyle: DeepReadonly<Ref<string>>;
+    /** 是否暗色（响应式只读；切换真相源，appStore.isDarkTheme 读此、挂值 composable toggle .dark 读此） */
+    themeIsDark: DeepReadonly<Ref<boolean>>;
+}
+/** `createBridgeThemeHook` 入参。 */
+export interface BridgeThemeInit {
+    /** init 默认风格 config（= bridge init 传入的 APP_THEME_CONFIG）；core 自动 add 为 `'default'` */
+    initConfig: AppThemeConfig;
+    /**
+     * 注入的 config 更新器（= configHook.update 收窄到 APP_THEME_CONFIG）。
+     *
+     * setStyle 经此把当前风格 config 灌进 bridge 响应式 APP_THEME_CONFIG（一级浅合并
+     * 整体替换 light/dark）。复用既有 update 通道，[MUST NOT] 另持一份主题响应式。
+     */
+    update: (key: "APP_THEME_CONFIG", partial: Partial<AppThemeConfig>) => void;
+    /** 注入的命名空间 storage（= bridge.getStorage()）；持久化 `{themeStyle,themeIsDark}` */
+    storage: StorageLike;
+    /** 持久化 key（命名空间已由 storage 加前缀）；缺省 `"admin-core-theme"` */
+    storageKey?: string;
+}
+/**
+ * bridge 主题 hook 工厂。
+ *
+ * 每次 `createAdminBridge` 调用各自闭包内构造一份（零模块级单例，守实例隔离）。
+ * init：自动 `add('default', initConfig)`；读持久化恢复 `themeIsDark` 即时生效、
+ * `themeStyle` 走「desiredStyle 命中再 apply」时序（插件后注册风格亦能恢复）。
+ */
+export declare function createBridgeThemeHook(init: BridgeThemeInit): BridgeThemeHook;

package/types/components/app-layout/AppTheme.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/types/components/app-layout/types.d.ts

@@ -39,4 +39,4 @@ export type AppLayoutUserStoreSlice<UserInfo = Record<string, any>> = ReturnType
  * （getRoutes / generateRouteMetaRawTree）。loginApi / refreshToken 等 auth
  * 面不通过本 slice 暴露（业务侧通过 appAdminBridge 直读）。
  */
-export type AppLayoutBridgeSlice = Pick<AdminBridge, "APP_BASE_INFO" | "APP_ENV_INFO" | "APP_CACHE_CONFIG" | "APP_LAYOUT_HEADER_CONFIG" | "APP_LAYOUT_FOOTER_CONFIG" | "APP_LAYOUT_SIDEBAR_CONFIG" | "APP_LAYOUT_BREADCRUMB_CONFIG" | "APP_LAYOUT_BODY_CONFIG" | "APP_LAYOUT_CONFIG" | "APP_ROUTER_META_DEFAULT_CONFIG" | "APP_ROUTER_CONFIG" | "APP_ROUTER_PATHS_CONFIG" | "APP_THEME_CONFIG" | "getRoutes" | "generateRouteMetaRawTree">;
+export type AppLayoutBridgeSlice = Pick<AdminBridge, "APP_BASE_INFO" | "APP_ENV_INFO" | "APP_CACHE_CONFIG" | "APP_LAYOUT_HEADER_CONFIG" | "APP_LAYOUT_FOOTER_CONFIG" | "APP_LAYOUT_SIDEBAR_CONFIG" | "APP_LAYOUT_BREADCRUMB_CONFIG" | "APP_LAYOUT_BODY_CONFIG" | "APP_LAYOUT_VIEWPORT_CONFIG" | "APP_LAYOUT_CONFIG" | "APP_ROUTER_META_DEFAULT_CONFIG" | "APP_ROUTER_CONFIG" | "APP_ROUTER_PATHS_CONFIG" | "APP_THEME_CONFIG" | "theme" | "themeStyle" | "themeIsDark" | "themeColors" | "getRoutes" | "generateRouteMetaRawTree">;

package/types/components/form/FormItem.vue.d.ts

@@ -46,15 +46,15 @@ declare function __VLS_template(): {
             $slots: Readonly<{
                 [name: string]: import('vue').Slot<any> | undefined;
             }>;
-            $root: ComponentPublicInstance | null;
-            $parent: ComponentPublicInstance | null;
+            $root: import('vue').ComponentPublicInstance | null;
+            $parent: import('vue').ComponentPublicInstance | null;
             $host: Element | null;
             $emit: (event: string, ...args: any[]) => void;
             $el: any;
             $options: import('vue').ComponentOptionsBase<Readonly<import('element-plus').FormItemProps> & Readonly<{}>, {
-                size: globalThis.ComputedRef<"" | "default" | "small" | "large">;
-                validateMessage: globalThis.Ref<string, string>;
-                validateState: globalThis.Ref<"" | "error" | "success" | "validating", "" | "error" | "success" | "validating">;
+                size: import('vue').ComputedRef<"" | "default" | "small" | "large">;
+                validateMessage: import('vue').Ref<string, string>;
+                validateState: import('vue').Ref<"" | "error" | "success" | "validating", "" | "error" | "success" | "validating">;
                 validate: (trigger: string, callback?: import('element-plus').FormValidateCallback) => import('element-plus').FormValidationResult;
                 clearValidate: () => void;
                 resetField: () => void;
@@ -79,7 +79,7 @@ declare function __VLS_template(): {
                 unmounted?: (() => void) | (() => void)[];
                 renderTracked?: ((e: import('vue').DebuggerEvent) => void) | ((e: import('vue').DebuggerEvent) => void)[];
                 renderTriggered?: ((e: import('vue').DebuggerEvent) => void) | ((e: import('vue').DebuggerEvent) => void)[];
-                errorCaptured?: ((err: unknown, instance: ComponentPublicInstance | null, info: string) => boolean | void) | ((err: unknown, instance: ComponentPublicInstance | null, info: string) => boolean | void)[];
+                errorCaptured?: ((err: unknown, instance: import('vue').ComponentPublicInstance | null, info: string) => boolean | void) | ((err: unknown, instance: import('vue').ComponentPublicInstance | null, info: string) => boolean | void)[];
             };
             $forceUpdate: () => void;
             $nextTick: typeof import('vue').nextTick;
@@ -151,15 +151,15 @@ declare const __VLS_component: import('vue').DefineComponent<FormMainItemProps,
         $slots: Readonly<{
             [name: string]: import('vue').Slot<any> | undefined;
         }>;
-        $root: ComponentPublicInstance | null;
-        $parent: ComponentPublicInstance | null;
+        $root: import('vue').ComponentPublicInstance | null;
+        $parent: import('vue').ComponentPublicInstance | null;
         $host: Element | null;
         $emit: (event: string, ...args: any[]) => void;
         $el: any;
         $options: import('vue').ComponentOptionsBase<Readonly<import('element-plus').FormItemProps> & Readonly<{}>, {
-            size: globalThis.ComputedRef<"" | "default" | "small" | "large">;
-            validateMessage: globalThis.Ref<string, string>;
-            validateState: globalThis.Ref<"" | "error" | "success" | "validating", "" | "error" | "success" | "validating">;
+            size: import('vue').ComputedRef<"" | "default" | "small" | "large">;
+            validateMessage: import('vue').Ref<string, string>;
+            validateState: import('vue').Ref<"" | "error" | "success" | "validating", "" | "error" | "success" | "validating">;
             validate: (trigger: string, callback?: import('element-plus').FormValidateCallback) => import('element-plus').FormValidationResult;
             clearValidate: () => void;
             resetField: () => void;
@@ -184,7 +184,7 @@ declare const __VLS_component: import('vue').DefineComponent<FormMainItemProps,
             unmounted?: (() => void) | (() => void)[];
             renderTracked?: ((e: import('vue').DebuggerEvent) => void) | ((e: import('vue').DebuggerEvent) => void)[];
             renderTriggered?: ((e: import('vue').DebuggerEvent) => void) | ((e: import('vue').DebuggerEvent) => void)[];
-            errorCaptured?: ((err: unknown, instance: ComponentPublicInstance | null, info: string) => boolean | void) | ((err: unknown, instance: ComponentPublicInstance | null, info: string) => boolean | void)[];
+            errorCaptured?: ((err: unknown, instance: import('vue').ComponentPublicInstance | null, info: string) => boolean | void) | ((err: unknown, instance: import('vue').ComponentPublicInstance | null, info: string) => boolean | void)[];
         };
         $forceUpdate: () => void;
         $nextTick: typeof import('vue').nextTick;

package/types/components/form/FormItemNestForm.vue.d.ts

@@ -0,0 +1,36 @@
+import { FormItemConfigList } from './types';
+import { ColProps } from 'element-plus';
+type __VLS_Props = {
+    /** 所属父 item key（注册到父 FormMain exposeMap 的索引） */
+    nestKey: string;
+    /** 子表单配置列表 */
+    list: FormItemConfigList;
+    layout?: Partial<ColProps>;
+    rowGutter?: number;
+    /** 联结组件外环阴影颜色；缺省走 CSS 变量主题自适配（亮/暗），仅显式传时内联覆盖 */
+    shadowColor?: string;
+    /** 父 item 代表 span（P3 rebase 算因子用；helper 经 resolveLayoutSpan(layout) 传入） */
+    parentSpan?: number;
+    /** 是否叠本层嵌套布局 rebase（缺省 true；false = 逆向逃生口，layout 原样直透） */
+    rebase?: boolean;
+};
+type __VLS_PublicProps = {
+    modelValue?: Record<string, any>;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: Record<string, any>) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: Record<string, any>) => any) | undefined;
+}>, {
+    rebase: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    childRef: {
+        validate: () => Promise<void>;
+        resetFields: () => void;
+        clearValidate: (key?: string) => void;
+        generate: () => Record<string, any>;
+        parse: (stringifyData: import('./types').ExcludeNeverProperties<import('./types').ExtractFormStringifyRawFromObject<Record<string, any>, Record<string, any>>>) => Record<string, any>;
+        stringify: () => import('./types').ExcludeNeverProperties<import('./types').ExtractFormStringifyRawFromObject<Record<string, any>, Record<string, any>>>;
+    } | null;
+}, any>;
+export default _default;

package/types/components/form/FormItemNestFormList.vue.d.ts

@@ -0,0 +1,63 @@
+import { VNodeChild } from 'vue';
+import { ColProps } from 'element-plus';
+import { FormItemConfigList } from './types';
+import { ActionBtnConfirmConfig } from '../display';
+declare const _default: <T extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly "onUpdate:modelValue"?: ((value: T[]) => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:modelValue"> & ({
+        modelValue?: T[];
+    } & {
+        /** 所属父 item key（注册到父 FormMain exposeMap 的索引） */
+        nestKey: string;
+        /** 每行子表单配置列表 */
+        list: FormItemConfigList;
+        /** 行稳定标识字段（指向 T 内稳定 id）；缺省走内部自增 rowId */
+        rowKey?: string;
+        /** 新增行工厂；缺省 generateFormData(list) 产子默认对象 */
+        itemFactory?: () => T;
+        /** 最少行数（删到 min 禁删；硬约束走父 item rules 长度校验） */
+        min?: number;
+        /** 最多行数（达上限禁新增；硬约束走父 item rules 长度校验） */
+        max?: number;
+        layout?: Partial<ColProps>;
+        rowGutter?: number;
+        addText?: string;
+        removeText?: string;
+        /** 顶部自定义渲染（render-fn prop，替代 template slot；label 由父 FormItem 渲染） */
+        headerRender?: (scope: {
+            count: number;
+            max: number;
+        }) => VNodeChild;
+        /** 底部自定义渲染；缺省 = 内置「新增」按钮 */
+        footerRender?: (scope: {
+            count: number;
+            max: number;
+            canAdd: boolean;
+            add: () => void;
+        }) => VNodeChild;
+        /** 联结组件外环 + 每行分割阴影颜色 */
+        shadowColor?: string;
+        /** 父 item 代表 span（P3 rebase 算因子用；helper 经 resolveLayoutSpan(layout) 传入） */
+        parentSpan?: number;
+        /** 是否叠本层嵌套布局 rebase（缺省 true；false = 逆向逃生口，layout 原样直透） */
+        rebase?: boolean;
+        /**
+         * 行删除二次确认（破坏性操作防误删）：
+         * - `true`（默认）→ 默认 popconfirm「确认删除该项？」（danger）
+         * - `false` → 不弹确认，直删（回旧行为）
+         * - 对象 → 自定义 ActionBtnConfirmConfig
+         */
+        removeConfirm?: boolean | ActionBtnConfirmConfig;
+    }) & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
+    attrs: any;
+    slots: {};
+    emit: (evt: "update:modelValue", value: T[]) => void;
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};