@done-coding/admin-core 0.18.0 → 0.19.0

package/types/bridge/index.d.ts

@@ -11,224 +11,635 @@ export { createGenerateRouteMetaRawTree, type RouteMetaDefaultConfig, } from './
 export { createStorageWithNamespace } from './storage';
 export type { CoreThemeEntry, CoreThemeLifecycleContext, CoreThemeLifecycleHooks, CoreConfigDescription, CoreThemeModule, CoreThemeMode, CoreThemeDensity, CoreThemeMotion, ElSize, CoreThemeComponentDefaults, CoreThemePresetLayout, BridgeThemeLayoutState, BridgeThemeLayoutBaseline, BridgeThemeHook, } from './theme';
 export type { CoreLayoutModule, BridgeLayoutHook, BridgeLayoutInit, LayoutCollapsePersistShape, } from './layout';
+/**
+ * 认证桥接无状态纯工厂。
+ *
+ * core 模块级零状态——每次调用 `createCoreBridge({...})` 在函数作用域内新建一组
+ * 闭包变量，传入 init 参数立即初始化，返回可直接使用的实例。core [MUST NOT] 持
+ * 已实例化单例（避免 dist/src 双 module instance 分裂，规避机制见 design §2.3,
+ * 结构上不持单例，[MUST NOT] 用 Symbol.for / globalThis 兜底）。
+ */
+/**
+ * register 入参类型，全字段 optional + 「有值才更新」增量合并。
+ *
+ * #4e 增 4 个增量可选业务 api（loginApi/logoutApi/getUserInfoApi/refreshTokenApi），
+ * 由 `createUserStore` 薄壳侧 register 注入；getToken/refreshToken/refreshAuth 由
+ * `createUserStore` core 工厂 setup 内自 register（裁决 2/3）。
+ */
 export interface CoreBridgeRegisterOptions<UserInfo = unknown, LoginParams = unknown> {
+    /** 取 token（v3 终锁 BR-1 ③ 终裁：零参 facade——core 对 UserInfo 不透明 + 拦截器无 info 源，泛型 `<UserInfo>` 纯透传不沾 getToken 签名） */
     getToken?: () => string | undefined;
+    /** 跳转登录 */
     goToLogin?: () => void;
+    /** 刷新 token */
     refreshToken?: () => Promise<unknown>;
+    /** 刷新鉴权（重新拉取用户信息） */
     refreshAuth?: () => Promise<unknown>;
+    /** 登录 api（对应 app accountLogin；#2.7 期 axios `{data}` wrapper 业务层 wrap 剥离，core 直读 UserInfo），增量可选 */
     loginApi?: (params: LoginParams) => Promise<Partial<UserInfo>>;
+    /** 退出登录 api（对应 app accountLogout），增量可选 */
     logoutApi?: () => Promise<unknown>;
+    /** 取用户信息 api（对应 app getLoginAccountInfo；#2.7 期 axios `{data}` wrapper 业务层 wrap 剥离；{user_info} 连壳历史语义在业务层 wrap 决定是否保留 D2），增量可选 */
     getUserInfoApi?: () => Promise<Partial<UserInfo>>;
+    /** 刷新 token api（#C 期签名最简化：core 不感知业务 shape，直传 refreshToken string；业务方 wrap 内自打包业务约定的入参 shape，如 `{Authorization: rt}`），增量可选 */
     refreshTokenApi?: (refreshToken: string) => Promise<string>;
 }
 export type { CoreBridgePlugin, CoreBridgePluginBridgeSlice, CoreBridgePluginContext, CoreBridgePluginInstall, CoreBridgePluginLike, } from './plugin';
+/**
+ * pinia persist storage 适配器最小接口。
+ *
+ * 仅约束 `store/app.ts` persist 适配器实际依赖的三方法，是浏览器 `Storage`
+ * 的结构子集——`createStorageWithNamespace()` 返回的命名空间 Storage 可直接赋值兼容。
+ */
 export interface StorageLike {
+    /** 读取键值，未命中返回 null */
     getItem: (key: string) => string | null;
+    /** 写入键值 */
     setItem: (key: string, value: string) => void;
+    /** 删除键值 */
     removeItem: (key: string) => void;
 }
+/**
+ * 应用主题颜色类型。
+ *
+ * 镜像 app 端 `@/config` `AppThemeColor` 全字段——store/app 的 `theme`
+ * computed 透出后由 app-layout 消费点访问 `primaryColor` 等全字段，故 [MUST]
+ * 完整镜像，[MUST NOT] 收窄到 store/app 体内直接读的子集（否则消费点 TS2339）。
+ */
 export interface AppThemeColor {
+    /** 背景色 */
     bodyColor: string;
+    /** 基础色 */
     baseColor: string;
+    /** 主色调 */
     primaryColor: string;
+    /** 成功色 */
     successColor: string;
+    /** 警告色 */
     warningColor: string;
+    /** 危险色 */
     dangerColor: string;
+    /** 错误色 */
     errorColor: string;
+    /** 信息色 */
     infoColor: string;
+    /** 圆角（风格可选；core 挂 --dc-core-radius ＋ --el-border-radius-base） */
     radius?: string;
+    /** 边框色（风格可选；core 挂 --dc-core-border-color ＋ --el-border-color） */
     borderColor?: string;
+    /** 阴影（风格可选；core 挂 --dc-core-shadow ＋ --el-box-shadow） */
     shadow?: string;
+    /** 边框宽（风格可选；core 挂 --dc-core-border-width ＋ --el-border-width） */
     borderWidth?: string;
+    /** 强调色（风格可选；core 仅挂 --dc-core-accent，EP 无对应） */
     accent?: string;
+    /** 辉光（风格可选；core 仅挂 --dc-core-glow，EP 无对应） */
     glow?: string;
+    /** 模糊（风格可选；core 仅挂 --dc-core-blur，EP 无对应） */
     blur?: string;
+    /** 聚焦环（风格可选；core 仅挂 --dc-core-focus-ring，EP 无对应） */
     focusRing?: string;
+    /** 表面色（风格可选；core 仅挂 --dc-core-surface，EP 无对应） */
     surface?: string;
 }
+/**
+ * 布局模块 `style` 逃生舱排除的「引擎托管键」联合（甲方终锁键集）。
+ *
+ * 这些 CSS 属性由布局引擎（store/app 几何 calc + 主题色兜底 + fixed 定位 + sidebar/aside
+ * 让位）独占计算，消费方 `style` [MUST NOT] 染指——否则破布局。分类：
+ * - 尺寸：width / height（几何算）
+ * - 定位：position / top / right / bottom / left / inset（fixed 锚点）
+ * - 显示 / 盒外：display（破布局流）/ margin 家族（破 fixed 定位）
+ * - 盒内：padding 家族（sidebar/aside 用 paddingTop 让位 header，整族锁防破让位）
+ * - 颜色：color / background / backgroundColor（走 config.color|background + --dc-core-* 兜底，规则 14）
+ */
 type AppLayoutManagedStyleKey = "width" | "height" | "position" | "top" | "right" | "bottom" | "left" | "inset" | "display" | "margin" | "marginTop" | "marginRight" | "marginBottom" | "marginLeft" | "padding" | "paddingTop" | "paddingRight" | "paddingBottom" | "paddingLeft" | "color" | "background" | "backgroundColor";
+/**
+ * 布局模块（Header/Footer/Sidebar/Aside）`style` 逃生舱类型。
+ *
+ * = `Omit<CSSProperties, 托管键>`——消费方显式自定义装饰（borderRadius / boxShadow /
+ * border / backdropFilter / opacity / transition 等），走规则 14「组件 prop 显式自定义值
+ * → 内联 :style 直值」例外条款。托管键经类型 `Omit` 编译期拦截 + store 合并运行时压过（双保险）。
+ */
 export type AppLayoutModuleStyle = Omit<CSSProperties, AppLayoutManagedStyleKey>;
+/**
+ * `store/app.ts` 实际消费的 app config 子集结构。
+ *
+ * 字段名与层级镜像 app 端 `@/config` 原结构（[MUST NOT] 重命名）；覆盖
+ * store/app 现消费字段（含 `theme` 透出后消费点所需全字段），[MUST NOT] 扩面
+ * 到全量 app config。core 不能 import app，故在此显式定义等价 interface。
+ */
 export interface AppConfig {
+    /** 应用基础信息（store/app 仅取 name） */
     APP_BASE_INFO: {
+        /** 应用名称 */
         name: string;
     };
+    /** 应用布局-header 配置 */
     APP_LAYOUT_HEADER_CONFIG: {
+        /** header 高度(px) */
         height: number;
+        /** 字体色；缺省 → 不写 color、CSS 继承 :root 全局 color(= baseColor)；[MUST NOT] 写死字面量 */
         color?: string;
+        /** 背景（color / image / gradient 等 CSS background）；缺省 → bodyColor(经 --dc-core-* var)；[MUST NOT] 写死字面量 */
         background?: string;
+        /** 装饰逃生舱（borderRadius/boxShadow/... ；排除引擎托管键，见 {@link AppLayoutModuleStyle}） */
         style?: AppLayoutModuleStyle;
     };
+    /** 应用布局-footer 配置 */
     APP_LAYOUT_FOOTER_CONFIG: {
+        /** footer 高度(px) */
         height: number;
+        /** 字体色；缺省 → 继承 :root color(baseColor) */
         color?: string;
+        /** 背景（color / image / gradient 等 CSS background）；缺省 → bodyColor */
         background?: string;
+        /** 装饰逃生舱（见 {@link AppLayoutModuleStyle}） */
         style?: AppLayoutModuleStyle;
     };
+    /** 应用布局-sidebar 配置（store/app 取 collapseWidth / width） */
     APP_LAYOUT_SIDEBAR_CONFIG: {
+        /** [展开的]宽度(px) */
         width: number;
+        /** 折叠起来的宽度(px) */
         collapseWidth: number;
+        /** 字体色；缺省 → 继承 :root color(baseColor) */
         color?: string;
+        /** 背景（color / image / gradient 等 CSS background）；缺省 → bodyColor */
         background?: string;
+        /** 装饰逃生舱（见 {@link AppLayoutModuleStyle}） */
         style?: AppLayoutModuleStyle;
     };
+    /**
+     * 应用布局-aside 右侧补充区配置（P1' 新增 additive，对称 sidebar）。
+     * 仅自定义 shell 渲染右侧区时生效；不配则 aside 不存在（经典布局零影响）。
+     */
     APP_LAYOUT_ASIDE_CONFIG: {
+        /** aside 宽度(px) */
         width: number;
+        /** 字体色；缺省 → 继承 :root color(baseColor) */
         color?: string;
+        /** 背景（color / image / gradient 等 CSS background）；缺省 → bodyColor */
         background?: string;
+        /** 装饰逃生舱（见 {@link AppLayoutModuleStyle}） */
         style?: AppLayoutModuleStyle;
     };
+    /** 应用布局-页面主体配置（store/app 仅取 shimPadding） */
     APP_LAYOUT_BODY_CONFIG: {
+        /** 页面主体 padding - 默认值(px) */
         shimPadding: number;
     };
+    /**
+     * 应用布局-模块间距配置（内缝；模块间露 size px 底色条带，漏出 .app-body 的 bodyColor）。
+     *
+     * 与 viewport 边框（整体外框）正交：gap 是模块**之间**的缝。默认 `{ size: 0 }` = 模块贴合、
+     * 现状不变；`size>0` 时 store 几何 calc 在相邻模块间叠加该间距（缺位侧不留悬空缝）。
+     * 分离观感需模块 `background` 为 surface 色（≠ bodyColor），由 preset/消费方设。
+     * 布局插件经 `bridge.update("APP_LAYOUT_GAP_CONFIG", { size })` 设值。
+     */
     APP_LAYOUT_GAP_CONFIG: {
+        /** 模块间距(px)；缺省 0 = 贴合 */
         size: 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: {
+        /** 亮色主题 */
         light: AppThemeColor;
+        /** 暗色主题 */
         dark: AppThemeColor;
     };
+    /** 应用路由元信息默认配置（store/app 取 show* 四项；createUserStore 经此取 menuShow/needLogin 默认） */
     APP_ROUTER_META_DEFAULT_CONFIG: {
+        /** 各路由[未配置情况下]默认是否展示 header */
         showHeader: boolean;
+        /** 各路由[未配置情况下]默认是否展示 footer */
         showFooter: boolean;
+        /** 各路由[未配置情况下]默认是否展示 sidebar */
         showSidebar: boolean;
+        /** 各路由[未配置情况下]默认是否展示右侧 aside（additive 可选；缺省 false，store `?? false` 兜底） */
         showAside?: boolean;
+        /** 默认是否展示 breadcrumb */
         showBreadcrumb: boolean;
+        /** 各路由[未配置情况下]默认是否展示在菜单 */
         menuShow: boolean;
+        /** 各路由[未配置情况下]默认是否需要登录 */
         needLogin: boolean;
     };
+    /** 应用缓存配置（#4e additive 第 8 项；createUserStore 经 namespace 实例化 useState） */
     APP_CACHE_CONFIG: {
+        /** 缓存命名空间 */
         namespace: string;
     };
 }
+/**
+ * 应用环境信息（#2.5 期新增，per ADR-6）。
+ *
+ * 镜像 app 端 `@/config` `APP_ENV_INFO` 字面量推导结构。`mode` 取自
+ * `import.meta.env.MODE`，`isProd` / `isDev` 派生自 mode 比较；本类型对外
+ * 显式声明便于下游业务项目直接 import 使用。
+ */
 export interface AppEnvInfo {
+    /** 环境模式（如 "production" / "development"） */
     mode: string;
+    /** 是生产环境 */
     isProd: boolean;
+    /** 是开发环境 */
     isDev: boolean;
 }
+/**
+ * 应用布局-面包屑配置（#2.5 期新增，per ADR-6）。
+ */
 export interface AppLayoutBreadcrumbConfig {
+    /** 面包屑高度(px) */
     height: number;
 }
+/**
+ * 应用布局聚合配置（#2.5 期新增，per ADR-3 候选 b bridge 内部派生）。
+ *
+ * 由 `createCoreBridge` 内部从 5 子布局配置（HEADER/FOOTER/SIDEBAR/BREADCRUMB/BODY）
+ * Object.freeze 聚合派生，挂载到 `bridge.APP_LAYOUT_CONFIG` readonly 属性。
+ */
 export interface AppLayoutConfig {
+    /** header 配置 */
     header: AppConfig["APP_LAYOUT_HEADER_CONFIG"];
+    /** footer 配置 */
     footer: AppConfig["APP_LAYOUT_FOOTER_CONFIG"];
+    /** sidebar 配置 */
     sidebar: AppConfig["APP_LAYOUT_SIDEBAR_CONFIG"];
+    /** aside 右侧补充区配置（P1' additive） */
     aside: AppConfig["APP_LAYOUT_ASIDE_CONFIG"];
+    /** 面包屑配置 */
     breadcrumb: AppLayoutBreadcrumbConfig;
+    /** 页面主体配置 */
     body: AppConfig["APP_LAYOUT_BODY_CONFIG"];
+    /** 视口边框配置 */
     viewport: AppConfig["APP_LAYOUT_VIEWPORT_CONFIG"];
+    /** 模块间距配置（内缝 gap） */
     gap: AppConfig["APP_LAYOUT_GAP_CONFIG"];
 }
+/**
+ * 应用路由配置（#2.5 期新增，per ADR-6）。
+ *
+ * 镜像 app 端 `@/config/router.ts` `APP_ROUTER_CONFIG` 字面量结构。
+ */
 export interface AppRouterConfig {
+    /** 是否使用 hash 路由 */
     isHash: boolean;
+    /** 路由根路径（同一域名不同 pathname 对应不同应用） */
     basePath: string;
+    /** 相同层级路由缓存最大数量 */
     keepAliveMaxCount: number;
+    /** 路由 meta 默认值（复用 AppConfig 字段类型） */
     metaDefault: AppConfig["APP_ROUTER_META_DEFAULT_CONFIG"];
 }
+/**
+ * 应用路由路径配置——8 path 聚合（#7.3 期新增）。
+ *
+ * 镜像 app 端 `@/config/router.ts` `APP_ROUTER_PATHS_CONFIG` 聚合结构；供
+ * layout 族下沉 core 时通过 `appBridge.APP_ROUTER_PATHS_CONFIG.homePath`
+ * 等读取路径常量，避免直 import 业务侧 `@/config` 路径符号。
+ *
+ * `loginNoCheckPath` / `authNoCheckPath` 标 `readonly string[]` 表只读语义；
+ * 业务侧 `string[]` 协变兼容 `readonly string[]`（赋值方向单向）。
+ */
 export interface AppRouterPathsConfig {
+    /** 根路径[!!!必设重定向] */
     rootPath: string;
+    /** 首页路径 */
     homePath: string;
+    /** 登录路径 */
     loginPath: string;
+    /** 注册路径 */
     registerPath: string;
+    /** 404 路径 */
     noFoundPath: string;
+    /** 无权限路径 */
     noPermissionPath: string;
+    /** 登录免检路径 */
     loginNoCheckPath: readonly string[];
+    /** 权限免检路径 */
     authNoCheckPath: readonly string[];
 }
+/** 应用基础信息 type 别名（#2.5 期 type 别名复用，per ADR-6） */
 export type AppBaseInfo = AppConfig["APP_BASE_INFO"];
+/** 应用布局-header 配置 type 别名 */
 export type AppLayoutHeaderConfig = AppConfig["APP_LAYOUT_HEADER_CONFIG"];
+/** 应用布局-footer 配置 type 别名 */
 export type AppLayoutFooterConfig = AppConfig["APP_LAYOUT_FOOTER_CONFIG"];
+/** 应用布局-sidebar 配置 type 别名 */
 export type AppLayoutSidebarConfig = AppConfig["APP_LAYOUT_SIDEBAR_CONFIG"];
+/** 应用布局-aside 右侧补充区配置 type 别名（P1' additive） */
 export type AppLayoutAsideConfig = AppConfig["APP_LAYOUT_ASIDE_CONFIG"];
+/** 应用布局-页面主体配置 type 别名 */
 export type AppLayoutBodyConfig = AppConfig["APP_LAYOUT_BODY_CONFIG"];
+/** 应用布局-视口边框配置 type 别名 */
 export type AppLayoutViewportConfig = AppConfig["APP_LAYOUT_VIEWPORT_CONFIG"];
+/** 应用布局-模块间距配置 type 别名（内缝 gap） */
 export type AppLayoutGapConfig = AppConfig["APP_LAYOUT_GAP_CONFIG"];
+/** 应用主题配置 type 别名 */
 export type AppThemeConfig = AppConfig["APP_THEME_CONFIG"];
+/** 应用路由元信息默认配置 type 别名 */
 export type AppRouterMetaDefaultConfig = AppConfig["APP_ROUTER_META_DEFAULT_CONFIG"];
+/** 应用缓存配置 type 别名 */
 export type AppCacheConfig = AppConfig["APP_CACHE_CONFIG"];
+/**
+ * token / refreshToken 字段访问器（含 get + set）。
+ *
+ * 第一宪法：core 对业务 `UserInfo` shape 完全不透明——业务自存自取，经本 adapter
+ * 注入读写两字段的纯函数，core [MUST NOT] 硬编字面字段名/路径耦合业务字段位置。
+ * `set` [MUST] 产新对象（[MUST NOT] 原地 mutate，破响应式 + 破不可变）。
+ */
 export interface UserInfoFieldAccessor<UserInfo = unknown> {
+    /** 读字段值；[MUST] 返回 string——业务经 getUserInfoInitFn 把该字段初值置 `""`，保证空态为 `""` 而非 undefined（类型恒定，免下游满屏 `token!`） */
     get: (info: Partial<UserInfo>) => string;
+    /**
+     * 写入字段值，返回**保留 info 其余全部字段**的新对象。
+     *
+     * [MUST] 含 info 全字段（如 `{ ...info, <业务字段>: value }`）——createUserStore
+     * getInfo 顺势更新全部用户信息时以 data 为基，依赖本契约把 token/refreshToken
+     * 贴回而不丢失 data 其余字段；[MUST NOT] 只返回单字段对象，[MUST NOT] 原地 mutate info。
+     */
     set: (info: Partial<UserInfo>, value: string) => Partial<UserInfo>;
 }
+/**
+ * permission 字段访问器（仅 get）。
+ *
+ * 权限由服务端下发只读，core 不写——仅 get 无 set；返回权限 key 列表（业务侧保底 `[]`）。
+ */
 export interface UserInfoPermissionAccessor<UserInfo = unknown> {
+    /** 从用户信息读取权限列表 */
     get: (info: Partial<UserInfo>) => (string | number)[];
 }
+/**
+ * 用户信息字段访问器集（token / refreshToken / permission 三字段注入）。
+ *
+ * createUserStore 经 `bridge.userInfoAccess.<字段>.get/set` 读写业务 UserInfo，
+ * core 零字段名耦合（第一宪法）。业务 shape 完全自由（嵌套 / 组合 / 任意命名），
+ * core 只认 adapter 契约不认数据结构。
+ */
 export interface UserInfoAccess<UserInfo = unknown> {
+    /** token 字段访问器 */
     token: UserInfoFieldAccessor<UserInfo>;
+    /** refreshToken 字段访问器 */
     refreshToken: UserInfoFieldAccessor<UserInfo>;
+    /** permission 字段访问器（仅 get） */
     permission: UserInfoPermissionAccessor<UserInfo>;
 }
+/**
+ * `createCoreBridge` 入参类型（#2.5 期 schema 扩张到 14 顶层字段，per ADR-3 / ADR-6）。
+ *
+ * #2.5 期完全显式入参化：原 `appConfig: AppConfig` 嵌套字段拆解为 11 个顶层字段平铺
+ * + 新增 `APP_ENV_INFO` / `APP_LAYOUT_BREADCRUMB_CONFIG` / `APP_ROUTER_CONFIG` 3 字段
+ * + 注：`APP_LAYOUT_CONFIG` 由 bridge 内部从 5 子布局配置聚合派生（候选 b，不在 initOptions 中）。
+ *
+ * `routes`（#4e additive）为 app 嵌套路由树（带 children），createUserStore 经此算权限树；
+ * `getUserInfoInitFn` 为 createUserStore 用户信息空保底注入面（core 对 UserInfo 不透明，
+ * 业务 shape 不下沉，规则 8）。`userInfoAccess` 为 token / refreshToken / permission
+ * 三字段的业务注入访问器（第一宪法：core 经纯函数 get/set 读写，零字面字段名耦合，
+ * 业务 UserInfo shape 完全自由）。
+ */
 export interface CoreBridgeInitOptions<UserInfo = unknown> {
+    /** 应用基础信息（store/app 仅取 name） */
     APP_BASE_INFO: AppBaseInfo;
+    /** 应用环境信息（mode / isProd / isDev，env 派生） */
     APP_ENV_INFO: AppEnvInfo;
+    /** 应用缓存配置（bridge 内部 storage / useState 派生 namespace） */
     APP_CACHE_CONFIG: AppCacheConfig;
+    /** 应用布局-header 配置 */
     APP_LAYOUT_HEADER_CONFIG: AppLayoutHeaderConfig;
+    /** 应用布局-footer 配置 */
     APP_LAYOUT_FOOTER_CONFIG: AppLayoutFooterConfig;
+    /** 应用布局-sidebar 配置 */
     APP_LAYOUT_SIDEBAR_CONFIG: AppLayoutSidebarConfig;
+    /**
+     * 应用布局-aside 右侧补充区配置（P1' 新增 additive，可选；app 不传时核内默认 width 0）。
+     * 默认 shell 也渲染 AppAside（宽 0 不可见）；app/preset 加宽即启用，经典布局零影响。
+     */
     APP_LAYOUT_ASIDE_CONFIG?: Partial<AppLayoutAsideConfig>;
+    /** 应用布局-面包屑配置（#2.5 期新增字段） */
     APP_LAYOUT_BREADCRUMB_CONFIG: AppLayoutBreadcrumbConfig;
+    /** 应用布局-页面主体配置 */
     APP_LAYOUT_BODY_CONFIG: AppLayoutBodyConfig;
+    /**
+     * 应用布局-视口边框配置（可选；app 整体不传时核内默认四边 0 = 不套框，现状不变）。
+     * 传部分字段时与默认四边 0 浅合并（见 createCoreBridge 内 DEFAULT 合并）。
+     */
     APP_LAYOUT_VIEWPORT_CONFIG?: Partial<AppLayoutViewportConfig>;
+    /**
+     * 应用布局-模块间距配置（可选；app 不传时核内默认 `{ size: 0 }` = 模块贴合、现状不变）。
+     * 布局插件经 preset.layout.gap 或 `bridge.update` 设值。
+     */
     APP_LAYOUT_GAP_CONFIG?: Partial<AppLayoutGapConfig>;
+    /** 应用路由元信息默认配置（bridge 内部 generateRouteMetaRawTree 派生） */
     APP_ROUTER_META_DEFAULT_CONFIG: AppRouterMetaDefaultConfig;
+    /** 应用路由配置（#2.5 期新增字段） */
     APP_ROUTER_CONFIG: AppRouterConfig;
+    /** 应用路由路径配置（#7.3 期新增字段；8 path 聚合供 layout 族通过 bridge 取业务路径） */
     APP_ROUTER_PATHS_CONFIG: AppRouterPathsConfig;
+    /** 应用主题配置（light / dark 双主题） */
     APP_THEME_CONFIG: AppThemeConfig;
+    /**
+     * 明暗模式默认值（**仅无缓存时生效**，可选）；缺省 `"light"`。
+     *
+     * 读持久化命中 themeMode → 缓存优先；无缓存才回落本值。设 `"dark"` =「首次进入默认暗色」、
+     * `"system"` =「默认跟随系统」。透传给 theme cache hook 的 `defaultMode`。
+     */
     defaultThemeMode?: CoreThemeMode;
+    /**
+     * 是否显示内置「风格切换下拉」（AppTheme 的 ElSelect）；缺省 `true`。
+     *
+     * false 时仅隐藏风格下拉，**亮/暗/跟随系统三态切换恒显、不受此控**。风格下拉本就
+     * 仅在注册多风格（list.length>1）时出现，此开关用于「多风格已注册但不想让用户切风格」。
+     * 经 `bridge.showThemeStyleSwitcher` readonly 暴露，AppTheme 直读 `v-if` 自控。
+     */
     showThemeStyleSwitcher?: boolean;
+    /** app 嵌套路由树（必传，#4e additive；createUserStore 权限树依赖 children 嵌套，[MUST NOT] 传扁平化数据） */
     routes: RouteRecordRaw[];
+    /** 用户信息空保底工厂（v3 终锁 Δ0b；恒返非空业务字段默认值对象，createUserStore useState 经此取初值，core 不锁业务 shape） */
     getUserInfoInitFn: () => UserInfo;
+    /** 用户信息字段访问器集（第一宪法：core 经业务注入 get/set 读写 token/refreshToken/permission，零字段名耦合，业务 shape 自由） */
     userInfoAccess: UserInfoAccess<UserInfo>;
 }
+/**
+ * 认证桥接实例类型。
+ *
+ * 调用侧 4 auth 方法签名与原 app `@/config` facade 完全一致。
+ * 工厂 `createCoreBridge(options)` 接收 init 参数，内部立即初始化，
+ * 返回即用的实例——消除 create-then-init 两步时序耦合。
+ */
 export interface CoreBridge<UserInfo = unknown, LoginParams = unknown> {
+    /** 注册 auth fn + 业务 api（增量合并，多次调用就近增量，后注册覆盖前注册） */
     register: (options: CoreBridgeRegisterOptions<UserInfo, LoginParams>) => void;
+    /** 取 token（v3 终锁 BR-1 ③ 终裁零参；现有无参调用 `bridge.getToken()` 继续合法，泛型 `<UserInfo>` 纯透传不沾本签名） */
     getToken: () => string | undefined;
+    /** 跳转登录 */
     goToLogin: () => void;
+    /** 刷新 token */
     refreshToken: () => Promise<void>;
+    /** 刷新鉴权 */
     refreshAuth: () => Promise<void>;
+    /** 返回 bridge 内部派生的 storage 实例（per REQ-1 入参内化；保持 StorageLike 可变方法可调用） */
     getStorage: () => StorageLike;
+    /** 返回 `init` 注册的 routes 引用（routes 例外保持可变，破循环依赖时序，per REQ-4 + audit §3.4） */
     getRoutes: () => RouteRecordRaw[];
+    /** 返回 `init` 注册的 getUserInfoInitFn 引用（v3 终锁 Δ0d，镜像 getRoutes 范式） */
     getUserInfoInitFn: () => () => UserInfo;
+    /** bridge 内部派生 useState 实例方法（per REQ-2；ns 已绑定，调用方零 ns 参；cacheKey 形如 `${ns}/useState/${moduleKey}`） */
     useState: ReturnType<typeof createUseState>;
+    /** bridge 内部派生 generateRouteMetaRawTree 实例方法（per REQ-3；metaDefault 已绑定 APP_ROUTER_META_DEFAULT_CONFIG，调用方零 metaDefault 参） */
     generateRouteMetaRawTree: ReturnType<typeof createGenerateRouteMetaRawTree>;
+    /** 登录 api（createUserStore login 内调；#2.7 期 axios `{data}` wrapper 业务层 wrap 剥离；未注册被调 reject 原生 Error） */
     loginApi: (params: LoginParams) => Promise<Partial<UserInfo>>;
+    /** 退出登录 api（createUserStore logout 内调；未注册被调 reject 原生 Error） */
     logoutApi: () => Promise<unknown>;
+    /** 取用户信息 api（createUserStore getInfo 内调；#2.7 期 axios `{data}` wrapper 业务层 wrap 剥离；连壳 {user_info} 见 design D2 由业务层决定；未注册被调 reject 原生 Error） */
     getUserInfoApi: () => Promise<Partial<UserInfo>>;
+    /** 刷新 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: 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: DeepReadonly<AppLayoutHeaderConfig>;
+    /** 应用布局-footer 配置（per #2.5 期 REQ-1） */
     readonly APP_LAYOUT_FOOTER_CONFIG: DeepReadonly<AppLayoutFooterConfig>;
+    /** 应用布局-sidebar 配置（per #2.5 期 REQ-1） */
     readonly APP_LAYOUT_SIDEBAR_CONFIG: DeepReadonly<AppLayoutSidebarConfig>;
+    /** 应用布局-aside 右侧补充区配置（P1' additive，响应式只读视图） */
     readonly APP_LAYOUT_ASIDE_CONFIG: DeepReadonly<AppLayoutAsideConfig>;
+    /** 应用布局-面包屑配置（per #2.5 期 REQ-1） */
     readonly APP_LAYOUT_BREADCRUMB_CONFIG: DeepReadonly<AppLayoutBreadcrumbConfig>;
+    /** 应用布局-页面主体配置（per #2.5 期 REQ-1） */
     readonly APP_LAYOUT_BODY_CONFIG: DeepReadonly<AppLayoutBodyConfig>;
+    /** 应用布局-视口边框配置（响应式只读视图，经 bridge.update 跟随） */
     readonly APP_LAYOUT_VIEWPORT_CONFIG: DeepReadonly<AppLayoutViewportConfig>;
+    /** 应用布局-模块间距配置（内缝 gap；响应式只读视图，经 bridge.update 跟随） */
     readonly APP_LAYOUT_GAP_CONFIG: DeepReadonly<AppLayoutGapConfig>;
+    /** 应用布局聚合配置（per #2.5 期 ADR-3 bridge 内部聚合派生） */
     readonly APP_LAYOUT_CONFIG: DeepReadonly<AppLayoutConfig>;
+    /** 应用路由元信息默认配置（per #2.5 期 REQ-1） */
     readonly APP_ROUTER_META_DEFAULT_CONFIG: AppRouterMetaDefaultConfig;
+    /** 应用路由配置（per #2.5 期 REQ-1） */
     readonly APP_ROUTER_CONFIG: AppRouterConfig;
+    /** 应用路由路径配置（per #7.3 期；8 path 聚合 readonly 挂载） */
     readonly APP_ROUTER_PATHS_CONFIG: AppRouterPathsConfig;
+    /** 应用主题配置（per #2.5 期 REQ-1） */
     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: CoreThemeModule;
+    /** 当前风格名（响应式只读真相源；[MUST NOT] 解构/快照取值，⚠️ 切换后定格） */
     readonly themeStyle: DeepReadonly<Ref<string>>;
+    /** 明暗模式三态真相源（响应式只读；亮/暗/跟随系统）。`theme.setMode` 切换；themeIsDark 由本 mode 派生。 */
     readonly themeMode: DeepReadonly<Ref<CoreThemeMode>>;
+    /** 是否暗色（响应式只读 **派生**；= mode==='system'?系统偏暗:mode==='dark'。appStore.isDarkTheme / 挂值 composable 读此） */
     readonly themeIsDark: DeepReadonly<Ref<boolean>>;
+    /**
+     * 当前 preset 的 layout 运行时维度（响应式只读真相源）。
+     *
+     * = `{ shell?, extractLevel1ToHeader }`——AppLayout 直读：`shell` 缺省回退内置默认
+     * AppShell（经典布局）；`extractLevel1ToHeader` 驱动菜单分流。尺寸 / 套框纯数据维度
+     * 经 `theme.setStyle` 灌进 bridge 响应式布局 config（基线复位 + 叠加），不在此重复。
+     * [MUST NOT] 解构/快照（⚠️ 切换 preset 后定格）。
+     */
     readonly themeLayout: DeepReadonly<Ref<BridgeThemeLayoutState>>;
+    /**
+     * 当前密度档 / 动效档（响应式只读真相源；明暗无关）。
+     * `useCoreThemeApply` watch 此重写节奏 `<style>`；`theme.setStyle` 按 preset 复位、
+     * `theme.setDensity`/`setMotion` 直接改。[MUST NOT] 解构/快照。
+     */
     readonly themeDensity: DeepReadonly<Ref<CoreThemeDensity>>;
     readonly themeMotion: DeepReadonly<Ref<CoreThemeMotion>>;
+    /**
+     * 当前生效的 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 写的 `--dc-core-*` cascade（输出 A）。
+     * [MUST NOT] 解构/快照（⚠️ 切换风格/明暗后定格）。
+     */
     readonly themeColors: DeepReadonly<Ref<AppThemeColor>>;
+    /** 是否显示内置「风格切换下拉」（AppTheme ElSelect）；init 静态值，缺省 true。亮暗切换恒显、不受此控。 */
     readonly showThemeStyleSwitcher: boolean;
+    /**
+     * 布局折叠模块（折叠真相源在 bridge）。
+     *
+     * `layout.{sidebarCollapsed,asideCollapsed}` 响应式只读折叠态 + `setSidebarCollapse /
+     * toggleSidebar / setAsideCollapse / toggleAside` 切换方法。appStore 转发
+     * （`sidebarIsCollapse` 读 `sidebarCollapsed`、`changeSidebarCollapseStatus` →
+     * `setSidebarCollapse`），AppSidebar / AppAside 经 store 驱动；折叠态持久化随写。
+     * [MUST NOT] 解构/快照折叠态（⚠️ 切换后定格）。
+     */
     readonly layout: CoreLayoutModule;
+    /** 用户信息字段访问器集（业务注入；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;
+    /**
+     * 安装 bridge 插件。
+     *
+     * 插件状态按 bridge 实例隔离；同一插件引用或同名插件重复安装时会跳过。
+     * `app.use(bridge)` 只负责 Vue provide，完整插件扩展走本方法。
+     */
     use: <Options = unknown>(plugin: CoreBridgePluginLike<UserInfo, LoginParams, Options>, options?: Options) => CoreBridge<UserInfo, LoginParams>;
+    /**
+     * Vue 插件 install（插件系统一期，REQ-9）。
+     *
+     * `app.use(bridge)` 经 `app.provide(CORE_BRIDGE_KEY, bridge)` 全局注入整个 bridge
+     * 实例；业务子组件 `inject(CORE_BRIDGE_KEY)` 拿到整 bridge → 读只读响应式配置 +
+     * 调 `bridge.update`。**opt-in**：不 `app.use(bridge)` 则 inject 返回 undefined。
+     * 区别于组件级 `APP_LAYOUT_BRIDGE_KEY`（layout 域窄切片）——本通道是 app 级全局整实例。
+     */
     install: (app: App) => App;
 }
+/**
+ * 认证桥接无状态纯工厂：接收 init 参数，内部立即初始化，返回可直接使用的
+ * `CoreBridge` 实例。实例状态（appConfig / storage / routes / fn 引用）仅存在于
+ * 本次调用的闭包内，工厂自身零状态。
+ *
+ * @example
+ *   const appBridge = createCoreBridge<LoginAccountInfo, AccountLoginParams>({
+ *     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_ROUTER_META_DEFAULT_CONFIG, APP_ROUTER_CONFIG, APP_THEME_CONFIG,
+ *     routes,
+ *     getUserInfoInitFn: getUserInfoInit,
+ *   });
+ */
 export declare function createCoreBridge<UserInfo = unknown, LoginParams = unknown>(options: CoreBridgeInitOptions<UserInfo>): CoreBridge<UserInfo, LoginParams>;